VIBN Frontend for Coolify deployment
This commit is contained in:
212
MCP_SETUP.md
Normal file
212
MCP_SETUP.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user