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

Tool	What it answers
repo_overview	"What is this project?" — languages, layout, entry points, tests, configs.
get_file_outline	"What's in this file?" — symbol skeleton without reading bodies.
find_symbol	"Where is X defined?" — locate a function/class/method/var, optionally with body.
find_references	"Where is X used?" — call sites and usages with context.
search_code	"Where is the code that …?" — lexical/regex search, or natural-language semantic search (optional).
get_dependencies	"What does this import / what depends on it?" — forward and reverse deps.
code_history	"Why is this code here?" — git blame/log/churn for a symbol or region.
find_tests	"What tests cover this?" — symbol ⇄ test mapping.
trace_call_graph	"What calls this / what does it call?" — callers/callees to N levels.
get_type_hierarchy	"What's the class tree?" — subclasses, superclasses, implementations.

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

Env var	Default	Purpose
REFERENCE_MCP_REPO	cwd	Absolute path to the codebase to analyze.
REFERENCE_MCP_CACHE_DIR	~/.cache/reference-mcp	Where the SQLite index is stored (never inside your repo).
REFERENCE_MCP_TOKEN_BUDGET	25000	Soft per-response token cap.

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.

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).