MCP Server

DiffContext ships an MCP (Model Context Protocol) server for Claude Code, Cursor, Windsurf, and any MCP-compatible agent. It exposes four tools that wrap the existing pipeline — no new retrieval logic, just the wire.

Install

pip install "diffcontext[mcp]"

This adds the mcp SDK as an optional dependency. The core package stays zero-dependency.

Configure

Add to your MCP client config:

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

The --repo flag sets a default repository path. Tools also accept repo_path as a parameter, so an agent working across multiple repos can pass it per-call.

Tools

compile_context

Compile LLM-ready context for a change. Give it changed symbol IDs or a git ref, and it returns the callers, callees, and related functions packed into a token budget with a disclosure header showing what was dropped.

Optionally pass task_description (the bug report or issue text) to bias retrieval toward symbols relevant to the described problem — the one signal the graph alone can’t provide. When only task_description is given (no changed_symbols or git_ref), changes are auto-detected from HEAD.

Example: A bug report says “shell completion for bash and zsh is broken.” You changed shell_complete() in click’s shell_completion.py (click at commit 2c8cd3a, diffcontext 0.5.4). Without the bug report, 9 symbols fit in the 4000-token budget; BashComplete._check_version ranks 17th among non-seed symbols (score 44.3) and is dropped. Pass the bug report as task_description — 10 symbols now fit; BashComplete._check_version jumps to rank 3 (score 74.3), because “bash” in the report BM25-matched BashComplete in the code.

Parameters:

• repo_path (optional): repo path, defaults to --repo
• changed_symbols (optional): list of symbol IDs (e.g. ["./src/auth.py:validate_jwt"])
• git_ref (optional): git ref to detect changes from (e.g. "HEAD~1")
• task_description (optional): bug report or issue text — biases retrieval toward symbols semantically related to the described problem
• max_tokens (default 8000): token budget
• meta (default "full"): header level — "full", "compact", or "off". The pass@1 effect of meta level is UNMEASURED.

find_impact

Find what breaks if you change a symbol. Returns the blast radius: direct callers, direct callees, and transitive impact, ranked by impact score. Default cap is 10 symbols — a reviewer brief must be short enough to read. The total count is always shown (“339 impacted, showing top 10”) so nothing is hidden — the cap is a display choice, not information loss.

Parameters:

• repo_path (optional): repo path, defaults to --repo
• symbol: symbol ID (e.g. ./src/auth.py:validate_jwt)
• limit (default 0): max symbols to show. 0 = the default cap of 10; pass a larger number to see more, or set to the total count for all.

explain_selection

Explain why symbols were included or dropped from context. Returns JSON with included_symbols (id, role, score, tokens) and dropped_symbols (id, score), so an agent can inspect or filter the selection.

Parameters:

• repo_path (optional): repo path, defaults to --repo
• symbol: the changed symbol ID to build context for
• max_tokens (default 8000): token budget

verify_retrieval

Mine git history and grade retrieval quality on your repo. Generates test cases from co-change history, runs retrieval against them, and reports hit/recall. Prints NULL RESULT when the tool doesn’t fit your repo — finding that out is the feature.

Parameters:

• repo_path (optional): repo path, defaults to --repo
• n (default 20): max test cases to generate from git history