# 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