vibn-frontend/MCP_SETUP.md

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

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

{
  "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

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:

{
  "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
• OpenAI MCP Guide
• Vibn Documentation

---

🤝 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