mcp-deepcontext

MCP server enabling symbol-aware semantic search in Claude Code

motivation

Most code search tools treat code as text, ignoring the semantic structure that makes code meaningful. When you're working in a large codebase, you don't just want to find where a string appears. You want to find where a function is called, where a type is implemented, or what modules depend on a particular symbol.

This MCP server bridges that gap by exposing semantic code analysis capabilities to Claude. Instead of grepping for text, Claude can ask questions like "where is this interface implemented?" or "what are all the callers of this function?" and get accurate, symbol-aware results. This makes it possible to have actually useful conversations about unfamiliar codebases.

architecture

graph TD
    A[Claude Desktop] -->|MCP Protocol| B[mcp-deepcontext Server]
    B -->|Parse & Index| C[Symbol Database]
    B -->|AST Analysis| D[TypeScript Compiler API]
    B -->|Semantic Search| E[Vector Embeddings]
    
    C -->|Symbol Locations| B
    D -->|Type Information| B
    E -->|Similarity Scores| B
    
    F[Your Codebase] -->|Watch & Reindex| B

getting started

install

npm install -g mcp-deepcontext

quickstart

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "deepcontext": {
      "command": "mcp-deepcontext",
      "args": ["--workspace", "/path/to/your/project"]
    }
  }
}

Then restart Claude Desktop. The server will index your codebase on startup.

how it works

The server uses the TypeScript compiler API to build a complete symbol graph of your codebase. This includes type definitions, function signatures, class hierarchies, and import relationships. When Claude queries for information, the server can respond with precise locations and context.

For semantic search, the server generates embeddings for code symbols and their surrounding context. This allows for fuzzy matching on intent rather than exact text. The symbol database is kept in sync with file changes through a file watcher that triggers incremental re-indexing.

The MCP protocol exposes this through tools like search_symbols, find_references, get_definition, and find_implementations. Claude can chain these together to answer complex questions about code structure and relationships.

configuration

The server accepts these command-line arguments:

• --workspace <path>: Root directory of the project to index (required)
• --languages <list>: Comma-separated list of languages to index (default: typescript,javascript)
• --exclude <patterns>: Glob patterns to exclude (default: node_modules,dist,build,.git)
• --max-file-size <bytes>: Skip files larger than this (default: 1MB)
• --embedding-model <name>: Model to use for embeddings (default: text-embedding-3-small)

Environment variables:

• OPENAI_API_KEY: Required for embedding generation
• DEEPCONTEXT_LOG_LEVEL: Set to debug for verbose logging

faq

Q: What languages are supported?

Currently TypeScript and JavaScript with full type awareness. Python and Go support is planned.

Q: Does this work with large codebases?

Yes, the indexing is incremental and the symbol database uses an efficient graph structure. Tested on codebases up to 500k lines without issues.

Q: How much does embedding generation cost?

For a typical 100k line codebase, initial indexing generates about 10k embeddings, costing roughly $0.02 with text-embedding-3-small. Incremental updates are much cheaper.

Q: Can I use this without embeddings?

Yes, pass --no-embeddings to disable semantic search. You'll still get all the symbol-aware tools like find references and go-to-definition.

Q: Does this send my code to external services?

Only the extracted symbol names and their immediate context are sent to OpenAI for embedding generation. You can disable this with --no-embeddings for completely local operation.

license

MIT