# 🧠 CodeBrain MCP Server

**Semantic code search powered by AI embeddings and vector similarity.**

Integrate intelligent code search directly into Claude Desktop and Cursor through the Model Context Protocol (MCP).

## 🎯 What It Does

CodeBrain indexes your codebase using AST-based splitting and AI embeddings, enabling:
- **Semantic search** - Find code by meaning, not just keywords
- **Smart chunking** - AST-aware code splitting (respects functions, classes, etc.)
- **Fast retrieval** - Vector similarity search with pgvector
- **Multi-project** - Index and search across multiple codebases

## 🚀 Quick Start

### 1. Prerequisites

```bash
# Docker running (for PostgreSQL + pgvector)
docker ps | grep codebrain

# Node.js 20+
node --version

# Dependencies installed
cd /Users/conorandrle/Documents/Coding/CodeBrainMCP/CodeBrain
pnpm install
```

### 2. Setup Database

```bash
# Start PostgreSQL with pgvector (if not running)
docker run -d \
  --name codebrain \
  -p 5484:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=codebrain \
  pgvector/pgvector:pg15

# Setup database schema
pnpm db:setup
pnpm db:migrate
```

### 3. Configure Environment

Edit `.env`:
```bash
GEMINI_API_KEY=your_api_key_here
DATABASE_URL=postgresql://postgres:postgres@localhost:5484/codebrain?schema=cbmcp
```

### 4. Test the Server

```bash
# Run tests
pnpm test

# Should show: ✅ 28 tests passed

# Test MCP server starts
npx tsx src/index.ts
# Should output: 🚀 CodeBrain MCP Server started (stdio mode)
# Press Ctrl+C to stop
```

## 🔌 Connect to Cursor/Claude

### For Cursor

1. **Open Cursor Settings** → MCP Servers
2. **Add server** named `codebrain`
3. **Copy this config:**

```json
{
  "command": "npx",
  "args": [
    "-y",
    "tsx",
    "/Users/conorandrle/Documents/Coding/CodeBrainMCP/CodeBrain/src/index.ts"
  ],
  "env": {
    "GEMINI_API_KEY": "your_key_here",
    "DATABASE_URL": "postgresql://postgres:postgres@localhost:5484/codebrain?schema=cbmcp"
  }
}
```

4. **Restart Cursor**
5. **Verify** - Check MCP panel shows "codebrain" connected

📖 **Detailed guide:** See [CURSOR_SETUP.md](./CURSOR_SETUP.md)

### For Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "codebrain": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/conorandrle/Documents/Coding/CodeBrainMCP/CodeBrain/src/index.ts"
      ],
      "env": {
        "GEMINI_API_KEY": "your_key_here",
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5484/codebrain?schema=cbmcp"
      }
    }
  }
}
```

Restart Claude Desktop.

## 🛠️ Available MCP Tools

### 1. `index_codebase`
Index a codebase for semantic search.

**Parameters:**
```typescript
{
  projectName: string;   // Unique project identifier
  rootPath: string;      // Absolute path to code
  force?: boolean;       // Re-index existing files
}
```

**Example:**
> "Index my React project at /Users/me/projects/my-app with name 'my-app'"

### 2. `semantic_search`
Search code semantically across indexed projects.

**Parameters:**
```typescript
{
  query: string;         // What to search for
  projectName?: string;  // Filter by project
  topK?: number;        // Number of results (default: 5)
  threshold?: number;   // Similarity threshold (default: 0.5)
}
```

**Example:**
> "Find authentication logic in my-app"

### 3. `list_projects`
List all indexed projects.

**Parameters:** None

**Example:**
> "Show me all indexed projects"

### 4. `get_project_stats`
Get statistics for a project.

**Parameters:**
```typescript
{
  projectName: string;   // Project to query
}
```

**Example:**
> "Show me stats for the my-app project"

## 📊 Architecture

```
┌─────────────────────────────────────────────┐
│         Cursor / Claude Desktop             │
│              (MCP Client)                   │
└─────────────────┬───────────────────────────┘
                  │ MCP Protocol (stdio)
                  │
┌─────────────────▼───────────────────────────┐
│         CodeBrain MCP Server                │
│  ┌─────────────────────────────────────┐   │
│  │  AST Code Splitter                  │   │
│  │  - JavaScript/TypeScript            │   │
│  │  - Python, Go, Rust, Java, C++      │   │
│  └──────────────┬──────────────────────┘   │
│                 │                           │
│  ┌──────────────▼──────────────────────┐   │
│  │  Gemini Embeddings                  │   │
│  │  - 768-dimensional vectors          │   │
│  │  - Semantic descriptions            │   │
│  └──────────────┬──────────────────────┘   │
│                 │                           │
│  ┌──────────────▼──────────────────────┐   │
│  │  Vector Search                      │   │
│  │  - Cosine similarity                │   │
│  │  - Threshold filtering              │   │
│  └──────────────┬──────────────────────┘   │
└─────────────────┼───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│      PostgreSQL + pgvector                  │
│  ┌──────────────────────────────────────┐  │
│  │  Projects → Files → Chunks → Embeds │  │
│  │  Normalized relational schema        │  │
│  └──────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
```

## 🧪 Testing

```bash
# Run all tests
pnpm test

# Watch mode
pnpm test:watch

# Individual test suites
pnpm test:splitter     # AST code splitter
pnpm test:indexing     # Indexing workflow
pnpm test:search       # Semantic search
pnpm test:embedding    # Embedding generation

# Integration test (end-to-end)
pnpm test:integration
```

## 🌐 Graph Viewer (React)

Visualise the code graph in the browser with the React/Vite viewer.

```bash
# Start the Graph API server (serves graph JSON on http://localhost:4000)
pnpm graph:server

# In a separate terminal, install and run the viewer UI
cd apps/graph-viewer
pnpm install
pnpm dev

# Open the browser UI → http://localhost:5173
```

Override the API target with `VITE_GRAPH_API_URL` (inside `apps/graph-viewer/.env`) if the server runs elsewhere.

## 📁 Project Structure

```
CodeBrain/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── core/
│   │   ├── indexing.ts       # Indexing orchestration
│   │   ├── search.ts         # Semantic search
│   │   ├── splitter.ts       # AST-based code splitting
│   │   └── embedding/
│   │       ├── base-embedding.ts      # Embedding interface
│   │       └── gemini-embedding.ts    # Gemini implementation
│   └── test/
│       ├── *.test.ts         # Unit tests
│       └── utils.ts          # Test utilities
├── db/
│   ├── index.ts              # Prisma client
│   ├── setup.ts              # Database setup script
│   └── vector-indexes.ts     # Vector index management
├── prisma/
│   └── schema.prisma         # Database schema
├── .env                      # Environment variables
├── mcp-config.json          # MCP configuration template
├── CURSOR_SETUP.md          # Cursor integration guide
└── README.md                # This file
```

## 🗃️ Database Schema

```sql
Project (1) ─┐
             ├─> File (N) ─┐
                           ├─> Chunk (N) ─┐
                                          ├─> Embedding (N)
```

- **Project**: Root container (name, rootPath)
- **File**: Individual source files (path, language, hash)
- **Chunk**: Code segments (text, lines, AST metadata)
- **Embedding**: Vector representations (768-dim, model, similarity search)

## 🔧 Development

### Scripts

```bash
pnpm dev              # Start with auto-reload
pnpm start            # Start server
pnpm build            # Compile TypeScript

pnpm db:setup         # Setup database + pgvector
pnpm db:migrate       # Run migrations
pnpm db:generate      # Generate Prisma client
pnpm db:studio        # Open Prisma Studio
```

### Environment Variables

```bash
# Required
GEMINI_API_KEY=your_gemini_api_key
DATABASE_URL=postgresql://user:pass@host:port/db?schema=cbmcp

# Optional
NODE_ENV=development
```

## 🐛 Troubleshooting

### MCP Connection Issues

**Problem:** Server won't connect in Cursor

**Solutions:**
1. Test manually: `npx tsx src/index.ts` (should output startup message)
2. Check absolute path in config matches your directory
3. Verify environment variables in MCP config
4. Restart Cursor completely (Cmd+Q, then reopen)
5. Check MCP output panel for error logs

### Database Issues

**Problem:** `type "vector" does not exist`

**Solution:**
```bash
pnpm db:setup  # This installs pgvector in cbmcp schema
```

**Problem:** Connection refused

**Solution:**
```bash
docker ps | grep codebrain  # Verify container running
docker start codebrain      # Start if stopped
```

### Embedding Issues

**Problem:** `GEMINI_API_KEY is required`

**Solution:** Add API key to `.env` and MCP config

### Performance Issues

**Problem:** Indexing is slow

**Solutions:**
- Embeddings are cached - subsequent runs are faster
- Adjust batch size in `indexing.ts` if needed
- Consider excluding large directories (node_modules, etc.)

## 📈 Performance

- **Indexing:** ~2-5 seconds per file (first time, includes embedding generation)
- **Re-indexing:** ~100ms per file (if unchanged, uses hash comparison)
- **Search:** ~500ms per query (includes embedding + vector search)
- **Storage:** ~10KB per code chunk (text + embedding + metadata)

## 🔐 Security

- API keys stored in environment variables (not in code)
- Database credentials configurable
- MCP runs locally (no external API calls except Gemini)
- Vector embeddings don't leave your machine

## 📝 License

MIT

## 🤝 Contributing

This is a personal project, but feel free to fork and adapt for your needs!

## 🎓 Learn More

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [pgvector](https://github.com/pgvector/pgvector)
- [Gemini Embeddings](https://ai.google.dev/docs/embeddings_guide)
- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/)

## ✅ Status

- ✅ Database setup and migrations
- ✅ AST-based code splitting
- ✅ Gemini embedding integration
- ✅ Vector similarity search
- ✅ MCP server implementation
- ✅ Comprehensive test suite (28 tests)
- ✅ Multi-project support
- ✅ Cursor/Claude integration ready

**Ready for production use!** 🚀