context-mcp

context-mcp

A local-first MCP server that gives LLM coding agents surgical, token-efficient code retrieval through structural graph analysis and hybrid ranked search.

The Problem

LLM coding agents waste thousands of tokens brute-forcing through grep and glob results with no structural understanding of the codebase. They read entire files hoping to find the right function, missing cross-file relationships entirely.

Features

• Single binary, zero cloud dependencies -- SQLite + FTS5 + sqlite-vec, runs entirely local
• Hybrid ranked search -- Personalized PageRank + BM25 + Betweenness Centrality + Semantic Similarity
• 20 MCP tools available across profiles, 5 prompts, 4 resources -- from symbol lookup to blast radius analysis to token-budgeted context assembly
• Sub-120ms query latency -- tested on real-world 18K+ node codebases
• Multi-language -- Go (native go/ast), JavaScript, TypeScript, PHP (tree-sitter)
• Incremental indexing -- filesystem watching with .gitignore-aware hot-reload

Quick Start

git clone https://github.com/maplenk/context-mcp.git && cd context-mcp
go build -tags "fts5" -o context-mcp ./cmd/context-mcp

# Run as MCP server (connect Claude Code, Desktop, or Codex)
./context-mcp -repo /path/to/your/project

# Or query directly via CLI
./context-mcp -repo /path/to/your/project cli context '{"query": "authentication"}'

Prerequisites: Go 1.25+ with CGO enabled, a C compiler (gcc/clang).

Direct Install

The latest packaged release is v0.3.0. For release-based installs, use the checksum-resolved server.json asset attached to that GitHub Release. The checked-in server.json file is the manifest template tracked in git and is resolved with the release checksum during publishing. The current packaged release target is macOS Apple Silicon (darwin/arm64) and installs the prebuilt context-mcp binary over stdio.

That packaged release runs with the default TF-IDF embedding path unless you manually configure an alternate backend such as ONNX at runtime.

The release page also publishes an install.sh helper. It downloads the matching archive, verifies the published SHA-256, and installs context-mcp into a PATH directory.

curl -fsSL https://github.com/maplenk/context-mcp/releases/latest/download/install.sh | sh

By default the helper installs to ~/.local/bin. For a system-wide install, use:

curl -fsSL https://github.com/maplenk/context-mcp/releases/latest/download/install.sh | sh -s -- --system

If you already downloaded context-mcp-darwin-arm64.tar.gz from the release page, download install.sh from the same release and run:

sh install.sh --archive ~/Downloads/context-mcp-darwin-arm64.tar.gz

This terminal installer is the best friction-reduction path we can ship without an Apple Developer account. It is checksum-verified, but it is not a Developer ID signed, notarized “verified developer” installer.

The client-specific commands below are the local-binary path. They assume context-mcp is already present on disk, whether you built it yourself or installed it from a release asset.

Connect to Your Agent

./context-mcp install --client claude-code --repo /absolute/path --profile extended

{
  "mcpServers": {
    "context-mcp": {
      "command": "/absolute/path/to/context-mcp",
      "args": ["-repo", "/absolute/path/to/your/project", "-profile", "extended"]
    }
  }
}

{
  "mcpServers": {
    "context-mcp": {
      "command": "/absolute/path/to/context-mcp",
      "args": ["-repo", "/absolute/path/to/your/project"]
    }
  }
}

./context-mcp install --client codex --repo /absolute/path --profile extended

[mcp_servers.context-mcp]
command = "/absolute/path/to/context-mcp"
args = ["-repo", "/absolute/path/to/your/project", "-profile", "extended"]

./context-mcp -repo /path/to/project serve-http -port 8080
# Optional: -bearer-token dev-token

How It Works

context-mcp walks your repository, parses every source file into an AST, and stores functions, classes, and their relationships as nodes and edges in a local SQLite database with FTS5 full-text indexing. It generates vector embeddings for semantic search, builds an in-memory directed graph for centrality and PageRank computation, and watches the filesystem to incrementally re-index changed files -- keeping the structural model up to date as you code.

Search Ranking

score = 0.35 x Personalized PageRank
      + 0.30 x BM25 (FTS5)
      + 0.20 x Betweenness Centrality
      + 0.15 x Semantic Similarity

Weights optimized via 4-phase parameter sweep across ~130 configurations. FTS5 queries enhanced with CamelCase splitting, prefix matching, and stop word filtering.

Performance

Full benchmark methodology in benchmarks/. ONNX-specific benchmark comparisons are intentionally documented in benchmarks/README.md; the packaged v0.3.0 release described above uses the default TF-IDF path unless you opt into ONNX manually.

Token Usage

Same real-world task ("find all differences between v1/order and v3/order API paths") run three ways on an 18K-node Laravel codebase:

context-mcp uses 30% fewer tokens and 40% fewer tool calls than no-MCP, and 2x fewer tokens than the alternative MCP server -- while providing ranked, structural results instead of raw grep output.

Run your own benchmarks with ./benchmarks/run_mcp_usage.sh.

Tools

Also includes 5 prompt templates (review_changes, trace_impact, prepare_fix_context, onboard_repo, collect_minimal_context) and 4 resources (repo_summary, index_stats, changed_symbols, hot_paths). Full parameter documentation in USAGE.md.

Workflow Retrieval

For broad orientation questions such as "how does order flow work?", "entire checkout flow", or "payment pipeline", prefer:

{"query": "order flow", "goal": "trace_workflow"}

via assemble_context. That path returns a phase-grouped, token-budgeted workflow skeleton with follow-up suggestions. Use context for targeted discovery, not first-pass workflow mapping.

Compact Output

High-output analysis tools (context, impact, understand, explore, detect_changes, get_architecture_summary, assemble_context) accept a compact: true parameter that strips verbose fields (Reason, WhyNow, NextTool, NextArgs) from each result. list_file_symbols also accepts compact: true and keeps only the minimal symbol inventory shape for large files. This reduces output tokens by 50-70% for agents that only need IDs and scores.

{"query": "payment processing", "compact": true}

Output Sandbox

Responses exceeding 16 KB are automatically sandboxed: the agent receives a short preview with a handle, then calls retrieve_output to page through the full content in 4 KB chunks. Responses between 8-16 KB include a size warning. This prevents context window overflow from unexpectedly large results.

Tools like read_symbol try to stay safe via bounded defaults and automatic downgrading. The output sandbox is the overflow safety net for any tool that still produces an oversized response.

Minimal Profile

Start with 3 tools (discover_tools, execute_tool, health) and keep retrieve_output always available as infrastructure, for 4 total minimal-profile tools:

retrieve_output is always registered in every profile as infrastructure for paginated retrieval of oversized responses.

That means the minimal profile has a 3-tool startup schema footprint and a 4-tool total footprint once infrastructure is included.

Use minimal when your agent's context window is constrained or when startup tool-definition cost matters. The agent discovers and activates only the tool bundles it needs, reducing initial schema overhead by ~65% compared to extended.

./context-mcp -repo /path/to/project -profile minimal

The agent calls discover_tools with a task description, and the best-matching tool bundle is activated automatically. A second bundle is only activated when ambiguity between the top two matches is high. For clients that do not refresh dynamic tool lists reliably, execute_tool remains available as a compatibility fallback. Four bundles are available: inspection (search/read/understand), change_analysis (impact/trace/detect), architecture (structure/modules/key symbols), and assembly (context/checkpoint/delta/search).

Install Helper Limitations

• ONNX args: The install helper only passes --repo and --profile flags. For ONNX-enabled installs, manually create the client config with -onnx-model and -onnx-lib args.
• HTTP auth: install / print-config do not emit client-specific auth header configuration for HTTP bearer-token setups. Configure auth headers manually.
• Profile default: The binary defaults to core. Install helpers use --profile extended in examples for better real-world agent usability.

Language Support

Python, Rust, and Java parsers are on the roadmap.

Why context-mcp?

Configuration

Full configuration reference in USAGE.md.

Development

go build -tags "fts5" ./...           # Build (FTS5 tag required)
go test -tags "fts5" -count=1 ./...   # Run tests
go vet -tags "fts5" ./...             # Static analysis

CI runs build, vet, and race-detector tests on every push. Weekly security scanning with govulncheck, gosec, and trivy.

Roadmap

• Additional language parsers (Python, Rust, Java)
• Pure-Go SQLite to eliminate CGO requirement
• Semantic flow tracing for business concept queries
• Enhanced route extraction for multi-version APIs
• Betweenness sampling for large codebases (>50K nodes)

License

MIT -- see LICENSE.