Code Context MCP

Local-first, agent-agnostic code intelligence over MCP. One daemon and one shared index can be used by Claude Code, Codex, and Pi.

MVP

• Streamable HTTP MCP at http://127.0.0.1:7438/mcp

• Multi-project registry

• Tree-sitter AST chunking for Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, and C#

• Incremental file hashing and re-indexing

• EmbeddingGemma 2 text/code embeddings

• 256-d Matryoshka vectors by default

• SQLite persistence

• Hybrid semantic + SQLite FTS5 retrieval

• Symbol lookup and reference search

• No Claude/Codex/Pi-specific logic inside the server

Related MCP server: codegraph

Quick Start

Requirements: Python 3.12.

git clone https://github.com/foreversaga/Code-Context-MCP.git
cd Code-Context-MCP

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[embedding]"

code-context-mcp

Default endpoint:

http://127.0.0.1:7438/mcp

Default configuration:

Data:       ~/.code-context-mcp
Model:      google/embeddinggemma-2
Mode:       text/code only
Dimensions: 256

The embedding extra includes Pillow and torchvision, which the EmbeddingGemma 2 processor requires even for text/code-only usage.

The model is loaded lazily and the first indexing operation may load or download it.

For complete setup, client configuration, indexing, multi-project usage, and troubleshooting, see docs/USAGE.md.

MCP clients

Claude Code

claude mcp add --transport http --scope user code-context http://127.0.0.1:7438/mcp

Codex

Add to ~/.codex/config.toml:

[mcp_servers.code-context]
url = "http://127.0.0.1:7438/mcp"

Pi

Pi supports Streamable HTTP MCP natively. Add to ~/.pi/agent/mcp.json:

{
  "mcpServers": {
    "code-context": {
      "type": "http",
      "url": "http://127.0.0.1:7438/mcp"
    }
  }
}

First project

After connecting the MCP server, ask the coding agent:

Register the current repository as backend and index it with Code Context MCP.

The server will register the project and build its code index. Later indexing runs only process changed files unless force=true is used.

Tools

• register_project(path, project_id?)

• list_projects()

• index_project(project_id, force=false)

• search_code(project_id, query, limit=10)

• search_text(project_id, query, limit=10)

• find_symbol(project_id, symbol, limit=20)

• find_references(project_id, symbol, limit=30)

• get_chunk(chunk_id)

• get_index_status(project_id)

Recommended behavior:

1. Use find_symbol or search_text for exact identifiers.

2. Use search_code for concepts or behavior.

3. Use find_references before changing shared symbols.

4. Read the returned source before editing.

Configuration

export CODE_CONTEXT_HOME=~/.code-context-mcp
export CODE_CONTEXT_MODEL=google/embeddinggemma-2
export CODE_CONTEXT_DIMENSIONS=256
export CODE_CONTEXT_HOST=127.0.0.1
export CODE_CONTEXT_PORT=7438

For tests and smoke checks without loading EmbeddingGemma 2:

export CODE_CONTEXT_EMBEDDER=hash

Architecture

Claude Code --+
Codex --------+--> MCP Streamable HTTP --> Code Context MCP
Pi -----------+                              |
                                             +-- Tree-sitter AST
                                             +-- EmbeddingGemma 2
                                             +-- SQLite FTS5
                                             +-- symbol/reference index
                                             +-- incremental multi-project index

CI

GitHub Actions runs lint and tests on Python 3.12. CI intentionally uses a deterministic fake embedder so the indexing/search/MCP workflow is tested without downloading model weights.