reference-mcp

An MCP server whose tools help an AI agent comprehend a codebase — get oriented, navigate by meaning rather than text, trace relationships, and understand why code is shaped the way it is.

It builds its own tree-sitter index of a Python project (no language servers required) and exposes a small set of consolidated, high-leverage tools designed around current agent tool-design best practices: human-readable returns, built-in token budgeting and pagination, and actionable errors.

Tools

Related MCP server: Axon.MCP.Server

Quickstart

uv sync --extra dev

# Point the server at a codebase and run it over stdio:
REFERENCE_MCP_REPO=/path/to/your/project uv run reference-mcp

# Or inspect interactively:
npx @modelcontextprotocol/inspector uv run reference-mcp

Semantic search (optional)

Lexical search works out of the box. To also enable natural-language search ("where is auth handled?"), install the local-embeddings extra — no API key, no network at query time once the model is cached:

uv sync --extra semantic

Then call search_code with mode="semantic". It embeds each symbol (name + signature + docstring) with fastembed (ONNX, model BAAI/bge-small-en-v1.5 by default, override via REFERENCE_MCP_EMBED_MODEL), caches the vectors in the index cache dir, and ranks by cosine similarity. Without the extra, mode="semantic" returns install guidance instead of failing.

Register with an MCP client

{
  "mcpServers": {
    "reference": {
      "command": "uv",
      "args": ["run", "reference-mcp"],
      "env": { "REFERENCE_MCP_REPO": "/path/to/your/project" }
    }
  }
}

Configuration

Design notes

• Read-only. The server never edits your code; it only reads and indexes it.

• Incremental index. Files are re-parsed only when their content hash changes.

• Precision tradeoff. Reference/call-graph resolution is scope- and import-aware name matching, not full type inference. Accurate for most Python; a future LSP backend can slot in behind the same tool surface for dynamic-dispatch-heavy code. To curb false positives, find_references ignores matches inside strings/comments (tree-sitter span masking), and trace_call_graph drops an obj.method() call when its name matches several methods. The residual case it cannot resolve: an obj.method() call whose name matches exactly one project method of an unrelated type (e.g. a dict.get() call when the project defines a single get method) — undecidable without type inference.

Development

uv run ruff check .          # lint
uv run ruff format .         # format
uv run mypy                  # type-check (src/)
uv run pytest                # unit + integration tests
uv run python evals/run_evals.py   # eval harness (must be 100%)

CI runs all of the above on every push and PR (see .github/workflows/ci.yml).