VIBN Frontend for Coolify deployment
This commit is contained in:
369
MCP_README.md
Normal file
369
MCP_README.md
Normal file
@@ -0,0 +1,369 @@
|
||||
# 🔌 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:**
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```typescript
|
||||
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:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-abc123"
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"project": { "name": "My App", ... },
|
||||
"stats": {
|
||||
"totalSessions": 42,
|
||||
"totalCost": 12.50,
|
||||
"totalTokens": 125000,
|
||||
"totalDuration": 3600
|
||||
},
|
||||
"recentSessions": [...]
|
||||
}
|
||||
```
|
||||
|
||||
### `search_sessions`
|
||||
Find sessions with filters.
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-abc123",
|
||||
"workspacePath": "/path/to/workspace",
|
||||
"startDate": "2024-01-01T00:00:00Z",
|
||||
"endDate": "2024-12-31T23:59:59Z"
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "session-xyz",
|
||||
"workspacePath": "/path/to/workspace",
|
||||
"cost": 0.25,
|
||||
"tokensUsed": 2500,
|
||||
"duration": 300,
|
||||
...
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### `get_conversation_context`
|
||||
Reference past AI conversations.
|
||||
|
||||
**Input:**
|
||||
```json
|
||||
{
|
||||
"projectId": "project-abc123",
|
||||
"limit": 50
|
||||
}
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
# 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](https://modelcontextprotocol.io/)
|
||||
- [OpenAI MCP Documentation](https://platform.openai.com/docs/mcp)
|
||||
- [Vibn Documentation](https://vibnai.com/docs)
|
||||
- [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup)
|
||||
|
||||
---
|
||||
|
||||
## 💬 Support
|
||||
|
||||
Need help with MCP integration?
|
||||
|
||||
- 📧 Email: support@vibnai.com
|
||||
- 💬 Discord: [Join our community](https://discord.gg/vibn)
|
||||
- 🐛 Issues: [GitHub Issues](https://github.com/vibn/vibn/issues)
|
||||
|
||||
---
|
||||
|
||||
**Built with ❤️ by the Vibn team**
|
||||
|
||||
*Making AI assistants truly understand your codebase.*
|
||||
|
||||
Reference in New Issue
Block a user