213 lines
5.2 KiB
Markdown
213 lines
5.2 KiB
Markdown
# Vibn MCP (Model Context Protocol) Server
|
|
|
|
The Vibn MCP Server exposes your project data, coding sessions, and AI conversations to AI assistants through a standardized protocol.
|
|
|
|
## 🎯 What It Does
|
|
|
|
The MCP server allows AI assistants (like Claude, ChatGPT, etc.) to:
|
|
- **Access your project data** - View projects, sessions, costs, and activity
|
|
- **Read conversation history** - Reference past AI conversations
|
|
- **Search sessions** - Find coding sessions by workspace, date, or project
|
|
- **Get project summaries** - Retrieve comprehensive project insights
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Start the MCP Server
|
|
|
|
```bash
|
|
cd vibn-frontend
|
|
npm run mcp:server
|
|
```
|
|
|
|
The server runs on stdio and waits for connections from AI assistants.
|
|
|
|
---
|
|
|
|
## 🔌 Integration Guides
|
|
|
|
### For Claude Desktop
|
|
|
|
Add to your Claude configuration file:
|
|
|
|
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"vibn": {
|
|
"command": "node",
|
|
"args": ["/absolute/path/to/vibn-frontend/mcp-server.js"],
|
|
"env": {
|
|
"FIREBASE_PROJECT_ID": "your-project-id",
|
|
"FIREBASE_CLIENT_EMAIL": "your-client-email",
|
|
"FIREBASE_PRIVATE_KEY": "your-private-key"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### For Custom AI Applications
|
|
|
|
```typescript
|
|
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
|
|
|
const transport = new StdioClientTransport({
|
|
command: 'node',
|
|
args: ['/path/to/vibn-frontend/mcp-server.js'],
|
|
});
|
|
|
|
const client = new Client({
|
|
name: 'my-ai-app',
|
|
version: '1.0.0',
|
|
}, {
|
|
capabilities: {},
|
|
});
|
|
|
|
await client.connect(transport);
|
|
|
|
// Now you can use the client to interact with Vibn data
|
|
const resources = await client.listResources();
|
|
const projectData = await client.readResource({ uri: 'vibn://projects' });
|
|
```
|
|
|
|
---
|
|
|
|
## 📚 Available Resources
|
|
|
|
### Projects
|
|
- **URI:** `vibn://projects`
|
|
- **Description:** List all user projects
|
|
- **Returns:** Array of project objects with metadata
|
|
|
|
### Project Sessions
|
|
- **URI:** `vibn://sessions/{projectId}`
|
|
- **Description:** Get all coding sessions for a specific project
|
|
- **Returns:** Array of session objects with timestamps, costs, tokens
|
|
|
|
### AI Conversations
|
|
- **URI:** `vibn://conversations/{projectId}`
|
|
- **Description:** Get AI conversation history for a project
|
|
- **Returns:** Array of conversation messages with roles and timestamps
|
|
|
|
---
|
|
|
|
## 🛠️ Available Tools
|
|
|
|
### `get_project_summary`
|
|
Get a comprehensive summary of a project.
|
|
|
|
**Parameters:**
|
|
- `projectId` (string, required) - The project ID
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"project": { /* project data */ },
|
|
"stats": {
|
|
"totalSessions": 42,
|
|
"totalCost": 12.50,
|
|
"totalTokens": 125000,
|
|
"totalDuration": 3600
|
|
},
|
|
"recentSessions": [ /* last 5 sessions */ ]
|
|
}
|
|
```
|
|
|
|
### `search_sessions`
|
|
Search coding sessions with filters.
|
|
|
|
**Parameters:**
|
|
- `projectId` (string, optional) - Filter by project
|
|
- `workspacePath` (string, optional) - Filter by workspace path
|
|
- `startDate` (string, optional) - Filter by start date (ISO format)
|
|
- `endDate` (string, optional) - Filter by end date (ISO format)
|
|
|
|
**Returns:** Array of matching sessions
|
|
|
|
### `get_conversation_context`
|
|
Get AI conversation history for context.
|
|
|
|
**Parameters:**
|
|
- `projectId` (string, required) - The project ID
|
|
- `limit` (number, optional) - Max messages to return (default: 50)
|
|
|
|
**Returns:** Array of conversation messages
|
|
|
|
---
|
|
|
|
## 💡 Example Use Cases
|
|
|
|
### 1. Get Project Overview
|
|
```
|
|
AI: Use the get_project_summary tool with projectId: "abc123"
|
|
```
|
|
|
|
### 2. Find Recent Sessions
|
|
```
|
|
AI: Use the search_sessions tool with projectId: "abc123" and no date filters
|
|
```
|
|
|
|
### 3. Reference Past Conversations
|
|
```
|
|
AI: Use the get_conversation_context tool with projectId: "abc123" to see what we discussed before
|
|
```
|
|
|
|
### 4. Analyze Coding Patterns
|
|
```
|
|
AI: Use search_sessions to find all sessions from workspacePath: "/Users/mark/my-project"
|
|
```
|
|
|
|
---
|
|
|
|
## 🔒 Security Notes
|
|
|
|
- The MCP server requires Firebase Admin credentials to access your data
|
|
- Only expose the MCP server to trusted AI assistants
|
|
- Consider running the server locally rather than exposing it publicly
|
|
- The server validates all requests and sanitizes inputs
|
|
|
|
---
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Server Won't Start
|
|
- Ensure `.env.local` has all required Firebase credentials
|
|
- Check that `@modelcontextprotocol/sdk` is installed: `npm install`
|
|
- Verify Node.js version is 18 or higher
|
|
|
|
### AI Can't Connect
|
|
- Check the absolute path in your AI assistant's configuration
|
|
- Ensure the MCP server is running: `npm run mcp:server`
|
|
- Verify environment variables are set correctly
|
|
|
|
### No Data Returned
|
|
- Confirm you have projects and sessions in Firebase
|
|
- Check that the user ID matches your authenticated user
|
|
- Review server logs for error messages
|
|
|
|
---
|
|
|
|
## 📖 Learn More
|
|
|
|
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
|
|
- [OpenAI MCP Guide](https://platform.openai.com/docs/mcp)
|
|
- [Vibn Documentation](https://vibnai.com/docs)
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
Have ideas for new MCP resources or tools? Open an issue or PR!
|
|
|
|
Potential additions:
|
|
- Export project data
|
|
- Create/update projects via MCP
|
|
- Real-time session monitoring
|
|
- Cost analytics and forecasting
|
|
|