Skip to main content
Glama
Sign In
CodeBrain MCP Server

CodeBrain MCP Server

by candrle20
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🧠 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

Related MCP server: quarry

🚀 Quick Start

1. Prerequisites

# 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

# 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:

GEMINI_API_KEY=your_api_key_here
DATABASE_URL=postgresql://postgres:postgres@localhost:5484/codebrain?schema=cbmcp

4. Test the Server

# 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:

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

  1. Restart Cursor

  2. Verify - Check MCP panel shows "codebrain" connected

📖 Detailed guide: See CURSOR_SETUP.md

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.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:

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

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

{
  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

# 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.

# 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

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

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

# 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:

pnpm db:setup  # This installs pgvector in cbmcp schema

Problem: Connection refused

Solution:

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

✅ 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! 🚀

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers