vibn-frontend/MCP_README.md

🔌 Vibn MCP Integration

Model Context Protocol (MCP) support for Vibn

Connect AI assistants like Claude, ChatGPT, and custom agents to your Vibn projects, enabling them to access your coding sessions, project data, and conversation history.

---

📦 What's Included

1. MCP Server (stdio)

• Standalone server that runs locally
• Exposes Vibn data through the standard MCP protocol
• Works with Claude Desktop, custom AI applications, and more
• File: lib/mcp/server.ts
• Launcher: mcp-server.js

2. HTTP API (REST)

• Web-accessible MCP endpoint
• Authentication via Firebase ID tokens
• Perfect for web-based AI assistants
• Endpoint: /api/mcp

3. Interactive Playground

• Test MCP capabilities directly in the Vibn UI
• View how AI assistants see your data
• Debug MCP requests and responses
• Page: /[workspace]/mcp

---

🚀 Getting Started

Option 1: For Claude Desktop

1. Open Claude Desktop configuration:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add Vibn MCP server:

{
  "mcpServers": {
    "vibn": {
      "command": "node",
      "args": ["/Users/your-username/ai-proxy/vibn-frontend/mcp-server.js"],
      "env": {
        "FIREBASE_PROJECT_ID": "your-project-id",
        "FIREBASE_CLIENT_EMAIL": "your-service-account-email",
        "FIREBASE_PRIVATE_KEY": "your-private-key"
      }
    }
  }
}

3. Restart Claude Desktop

4. Test it:

   • Open a new chat in Claude
   • Type: "Can you show me my Vibn projects?"
   • Claude will use the MCP server to fetch your project data!

Option 2: For Web-Based AI (HTTP API)

Use the REST endpoint to integrate with any AI application:

const response = await fetch('https://vibnai.com/api/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_FIREBASE_ID_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    action: 'read_resource',
    params: {
      uri: 'vibn://projects/YOUR_USER_ID'
    }
  })
});

const data = await response.json();
console.log(data);

Option 3: Test in Vibn UI

1. Navigate to: https://vibnai.com/your-workspace/mcp
2. Click on any tool card to test MCP requests
3. View responses in the interactive playground

---

📚 Available Resources

Resource URI	Description	Returns
vibn://projects/{userId}	All user projects	Array of project objects
vibn://projects/{userId}/{projectId}	Specific project	Single project with details
vibn://sessions/{userId}	All coding sessions	Array of session objects
vibn://sessions/{projectId}	Project sessions	Sessions for specific project
vibn://conversations/{projectId}	AI chat history	Conversation messages

---

🛠️ Available Tools

get_project_summary

Get comprehensive project insights.

Input:

{
  "projectId": "project-abc123"
}

Output:

{
  "project": { "name": "My App", ... },
  "stats": {
    "totalSessions": 42,
    "totalCost": 12.50,
    "totalTokens": 125000,
    "totalDuration": 3600
  },
  "recentSessions": [...]
}

search_sessions

Find sessions with filters.

Input:

{
  "projectId": "project-abc123",
  "workspacePath": "/path/to/workspace",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z"
}

Output:

[
  {
    "id": "session-xyz",
    "workspacePath": "/path/to/workspace",
    "cost": 0.25,
    "tokensUsed": 2500,
    "duration": 300,
    ...
  }
]

get_conversation_context

Reference past AI conversations.

Input:

{
  "projectId": "project-abc123",
  "limit": 50
}

Output:

[
  {
    "role": "user",
    "content": "How do I implement auth?",
    "createdAt": "2024-11-14T10:30:00Z"
  },
  {
    "role": "assistant",
    "content": "Here's how to set up authentication...",
    "createdAt": "2024-11-14T10:30:05Z"
  }
]

---

💡 Example Use Cases

1. Project Status Update

Prompt: "Give me a status update on my Vibn projects"

What happens:

• AI calls vibn://projects/{userId} to list projects
• AI calls get_project_summary for each project
• AI presents a comprehensive overview of all work

2. Cost Analysis

Prompt: "How much have I spent on AI for project X?"

What happens:

• AI calls get_project_summary for project X
• AI analyzes the totalCost metric
• AI breaks down costs by session if needed

3. Conversation Continuity

Prompt: "What did we discuss about authentication last week?"

What happens:

• AI calls get_conversation_context for the project
• AI searches through conversation history
• AI references past discussions with full context

4. Development Insights

Prompt: "What files am I spending the most time on?"

What happens:

• AI calls search_sessions to get all sessions
• AI analyzes file change patterns
• AI identifies productivity hotspots

---

🏗️ Architecture

┌─────────────────┐
│  AI Assistant   │ (Claude, ChatGPT, etc.)
└────────┬────────┘
         │
         ├─────────── stdio ────────────┐
         │                              │
         └─────────── HTTP ─────────────┤
                                        │
                              ┌─────────▼─────────┐
                              │   Vibn MCP Server │
                              │  (server.ts/api)  │
                              └─────────┬─────────┘
                                        │
                              ┌─────────▼─────────┐
                              │  Firebase Admin   │
                              │    (Firestore)    │
                              └───────────────────┘
                                        │
                              ┌─────────▼─────────┐
                              │   User Projects   │
                              │    + Sessions     │
                              │  + Conversations  │
                              └───────────────────┘

---

🔒 Security

Authentication

• stdio server: Requires Firebase Admin credentials (environment variables)
• HTTP API: Requires Firebase ID token in Authorization header
• User isolation: All queries filter by userId to prevent data leaks

Best Practices

1. Never expose MCP server publicly - Run it locally or behind a firewall
2. Use environment variables - Don't hardcode credentials
3. Rotate keys regularly - Update Firebase service account keys periodically
4. Monitor access logs - Review MCP usage in Firebase logs

---

🧪 Testing

Test the stdio server:

cd vibn-frontend
npm run mcp:server

The server will start and wait for connections. To test manually, you can send MCP JSON-RPC messages via stdin.

Test the HTTP API:

# Get capabilities
curl https://vibnai.com/api/mcp

# List resources (requires auth token)
curl -X POST https://vibnai.com/api/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "list_resources"}'

Test in the UI:

1. Navigate to /your-workspace/mcp
2. Click tool cards to trigger requests
3. View formatted JSON responses

---

🐛 Troubleshooting

"Server won't start"

• ✅ Check .env.local has all Firebase credentials
• ✅ Verify Node.js version (18+)
• ✅ Run npm install to ensure dependencies are installed

"AI can't connect"

• ✅ Use absolute paths in Claude config
• ✅ Verify the MCP server is running
• ✅ Check environment variables are set in config

"No data returned"

• ✅ Confirm you have projects/sessions in Firebase
• ✅ Check userId matches your authenticated user
• ✅ Review server logs for errors

"Permission denied"

• ✅ Ensure Firebase service account has Firestore read access
• ✅ Verify security rules allow server-side access
• ✅ Check ID token is valid and not expired

---

📈 Roadmap

Future MCP enhancements:

• Write operations - Create/update projects via MCP
• Real-time subscriptions - Stream session updates
• Advanced analytics - Cost forecasting, productivity insights
• Git integration - Access commit history via MCP
• File content access - Read actual code files
• Prompt templates - Pre-built prompts for common tasks

---

🤝 Contributing

Want to extend Vibn's MCP capabilities? Here's how:

1. Add new resources - Edit lib/mcp/server.ts and /api/mcp/route.ts
2. Add new tools - Implement in both stdio and HTTP handlers
3. Update docs - Keep MCP_SETUP.md in sync
4. Test thoroughly - Use the playground to verify changes

---

📖 Learn More

• Model Context Protocol Spec
• OpenAI MCP Documentation
• Vibn Documentation
• Firebase Admin SDK

---

💬 Support

Need help with MCP integration?

• 📧 Email: support@vibnai.com
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues

---

Built with ❤️ by the Vibn team

Making AI assistants truly understand your codebase.