@semanticode/mcp-server

Semantic code search MCP server powered by MongoDB Vector Search and Voyage AI

Transform how AI assistants understand your codebase with natural language queries, temporal tracking, and deep code insights.

✨ Features

• 🔍 Semantic Search - Natural language queries with Voyage AI voyage-code-3 embeddings
• ⏱️ Temporal Tracking - See how code evolved over the last 100 commits
• 📊 8 Powerful Tools - Comprehensive code understanding capabilities
• 🗄️ MongoDB Vector Search - Production-grade vector database
• ⚡ Real-Time - Fast semantic search (<500ms)
• 🤖 MCP Compatible - Works with Cursor, Claude, and any MCP client

🚀 Quick Start

Prerequisites

1. MongoDB Atlas account (free tier works) - Sign up
2. Voyage AI API key - Get yours

Installation

Option 1: npx (No Installation Required)

Add to your .cursor/mcp.json or Claude configuration:

{
  "mcpServers": {
    "semanticode": {
      "command": "npx",
      "args": ["-y", "@semanticode/mcp-server"],
      "env": {
        "MONGODB_URI": "mongodb+srv://user:[email protected]/semanticode",
        "VOYAGE_API_KEY": "your-voyage-api-key",
        "SEMANTICODE_REPOSITORY": "your-repo-name"
      }
    }
  }
}

Option 2: Global Installation

npm install -g @semanticode/mcp-server

Then add to .cursor/mcp.json:

{
  "mcpServers": {
    "semanticode": {
      "command": "semanticode-mcp",
      "env": {
        "MONGODB_URI": "mongodb+srv://...",
        "VOYAGE_API_KEY": "your-key",
        "SEMANTICODE_REPOSITORY": "your-repo"
      }
    }
  }
}

Index Your Codebase

Before using the MCP tools, index your codebase:

# Install the full SemantiCode toolkit
git clone https://github.com/yourusername/semanticode
cd semanticode
pnpm install && pnpm build

# Index your project
pnpm semanticode index /path/to/your/project

🛠️ Available Tools

1. search_code

Semantically search the codebase using natural language.

Example:

AI: "Find authentication functions in this codebase"
→ Returns functions related to auth with semantic similarity scores

2. find_related

Find entities related to a given function/class through calls, imports, inheritance.

Example:

AI: "What's related to the authenticateUser function?"
→ Shows all functions it calls and functions that call it

3. explain_entity

Get detailed information about a specific function, class, or interface.

Example:

AI: "Explain the UserService class"
→ Shows code, relationships, metadata, authorship

4. explain_changes

Get the change history of an entity with git commits and authors.

Example:

AI: "Who changed the login function recently?"
→ Shows commit history, authors, dates, messages

5. find_callers

Find all functions that call a given function (impact analysis).

Example:

AI: "What would break if I change validatePassword?"
→ Shows all callers and their locations

6. explain_flow

Trace execution flow from a starting function through its dependencies.

Example:

AI: "Trace the flow from handleUserLogin"
→ Shows call chain: handleUserLogin → authenticate → validateToken → checkDB

7. search_by_author

Find all code entities created or modified by a specific author.

Example:

AI: "Show me everything Alice wrote"
→ Lists all functions/classes by Alice

8. timeline

Get a timeline of changes to the codebase within a date range.

Example:

AI: "What changed last week?"
→ Shows commits, affected entities, authors

📊 How It Works

1. Parse - Analyzes TypeScript code using AST parsing
2. Embed - Generates semantic embeddings with Voyage AI voyage-code-3
3. Store - Saves to MongoDB Atlas with Vector Search indexes
4. Track - Monitors git history for temporal queries
5. Serve - Exposes 8 MCP tools for AI assistants

🏗️ Technology Stack

• Parser: @typescript-eslint/typescript-estree - Full TypeScript AST
• Embeddings: Voyage AI voyage-code-3 (1024-dim vectors)
• Database: MongoDB Atlas with Vector Search
• Protocol: Model Context Protocol (MCP) v1.17.0
• Git: simple-git for history tracking

⚙️ Configuration

Environment Variables

• MONGODB_URI - MongoDB Atlas connection string (required)
• VOYAGE_API_KEY - Voyage AI API key (required)
• SEMANTICODE_REPOSITORY - Repository name (required)
• LOG_LEVEL - Logging level: debug, info, warn, error (default: info)

Optional: .semanticode.json

Create in your project root:

{
  "repository": {
    "name": "my-project",
    "ignore": ["node_modules", "dist"]
  },
  "indexing": {
    "historyDepth": 100,
    "batchSize": 50
  },
  "embedding": {
    "model": "voyage-code-3",
    "batchSize": 128
  }
}

📈 Performance

• Search Latency: <500ms for semantic queries
• Indexing Speed: ~500-1000 files/minute
• Memory Usage: <512MB
• Cache TTL: 5 minutes for tool results

🔒 Security

• MongoDB connections use secure TLS
• API keys via environment variables only
• No data leaves your infrastructure
• Self-hosted option available

📝 License

MIT - See LICENSE

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md

🙏 Acknowledgments

• MongoDB - For MongoDB Atlas and Vector Search
• Voyage AI - For voyage-code-3 embedding model
• Anthropic - For MCP protocol

🔗 Links

• GitHub Repository
• MongoDB Atlas
• Voyage AI
• MCP Protocol