PureContext MCP

Most tools help an AI agent read your codebase. PureContext helps it change your codebase safely.

Agents are already good at finding code. What they can't see is the part that breaks things: what a symbol connects to, what quietly changes alongside it, and whether it's risky to touch at all. PureContext MCP indexes your codebase into a structured, queryable model and gives agents that missing layer — impact, coupling, and change-risk intelligence, before the edit.

Before changing processRefund(), the agent checks:

  get_symbol_risk   → band: HIGH — 47 dependents · churn 8/90d
                      · no direct test · co-changes with ledger.ts (conf 0.71)
  get_blast_radius  → 23 files affected across 4 modules
  get_co_change     → usually moves together with refund.test.ts and ledger.ts

→ so it updates those together, instead of shipping a half-change that
  passes locally and breaks billing in production.

This is the layer autonomous agents are missing. Refactoring and change-safety tooling is still mostly built for humans clicking through an IDE — not for an agent about to edit code it has never seen. PureContext closes that gap: blast radius, temporal co-change, rename/delete/move safety checks, and a composite per-symbol risk score — all queryable as MCP tools.

It's built on token-efficient retrieval as the foundation: agents pull a single function, class, or route by name or meaning instead of reading whole files — typically 90%+ fewer context tokens (see it in action). Precise context means less hallucination, more accurate edits, and the ability to work on codebases far larger than any context window.

Quick start

# Inside your project: registers the MCP server (pinned to your global Node) AND
# adds the workflow rules — auto-detects Claude / Cursor / Windsurf / Continue /
# Cline / Roo Code / Copilot / Claude Desktop
npx purecontext-mcp@latest install all

# Prefer to wire up Claude Code by hand? Register the server manually:
claude mcp add purecontext-mcp -- npx purecontext-mcp@latest

# Recommended: keep the index fresh after checkout / pull / merge / rebase.
# Installs post-checkout, post-merge and post-rewrite git hooks for this repo
# (all worktrees). They re-index only what git says changed and never block git.
npx purecontext-mcp@latest hooks --install --git
# (or: npx purecontext-mcp@latest install all --with-git-hooks)

Then in a Claude Code conversation:

Index my project at /path/to/my-project

That's it. Claude will index your codebase and you can start navigating it by name, by meaning, or by dependency — without reading files.

Related MCP server: mcp-code-indexer

What this looks like in practice

First, find and understand it

A typical "find and understand" conversation, before vs. after:

Without PureContext

You:    Where do we handle Stripe webhook signature verification?
Claude: I'll search the codebase.
        [reads src/api/webhooks/stripe.ts — 412 lines, ~3,100 tokens]
        [reads src/lib/stripe-client.ts    — 287 lines, ~2,150 tokens]
        [reads src/middleware/webhook.ts   — 198 lines, ~1,490 tokens]
        Verification happens in verifyStripeSignature() at line 87 of stripe.ts.
        Total context used: ~6,740 tokens

With PureContext

You:    Where do we handle Stripe webhook signature verification?
Claude: search_symbols(query: "stripe webhook signature")
        → 3 matches, 78 tokens
        get_symbol_source(symbolId: "verifyStripeSignature")
        → 32 lines, 180 tokens
        verifyStripeSignature() at src/api/webhooks/stripe.ts:87.
        It uses the timing-safe HMAC check from Stripe's SDK with a 5-minute tolerance.
        Total context used: ~258 tokens — 96% less

The agent stays in the conversation instead of running out of context after one file read — which frees it to get to the part that actually matters: changing the code safely.

Then change it without breaking things

A typical "modify this" conversation, before vs. after:

Without PureContext

You:    Add a partial-refund path to processRefund().
Claude: [reads processRefund, edits it]
        Done — added the partial-refund branch.

        (Never saw that ledger.ts reconciles every refund, or that
         refund.test.ts asserts the old totals. CI breaks; billing
         drifts in production.)

With PureContext

You:    Add a partial-refund path to processRefund().
Claude: get_symbol_risk(symbolId: "processRefund")
        → band: HIGH — 47 dependents · churn 8/90d · no direct test
          · co-changes with ledger.ts (conf 0.71)
        get_blast_radius(symbolId: "processRefund")
        → 23 files affected across 4 modules
        get_co_change(symbolId: "processRefund")
        → usually moves together with ledger.ts and refund.test.ts

        This symbol is high-risk and untested. I'll update processRefund(),
        adjust the reconciliation in ledger.ts, and extend refund.test.ts
        in the same change.

The difference here isn't tokens — it's that the agent saw the second-order edits before writing code, instead of discovering them in a failed CI run or a production incident.

Change & refactoring intelligence

This is the part most code tools leave to humans. PureContext exposes it as MCP tools an agent can call before it edits — so autonomous changes come with the same impact awareness a careful senior engineer would bring.

get_symbol_risk is the composite verdict: it fuses change frequency (churn), centrality (how much depends on it), complexity, test-coverage gaps, and temporal co-change into one banded score (low / review / high) with human-readable reasons — never a black-box number, and deliberately code-centered (no author or productivity metrics). get_co_change surfaces the coupling the import graph can't see — the test, the migration, or the feature flag that always moves with a file. Together they let an agent edit unfamiliar code the way a cautious human does: check the blast radius, update what moves with it, and flag what it shouldn't touch alone.

PureContext also closes the loop around an edit — judgment, not actuation (it never writes files; your agent does): prepare_change gives a pre-edit impact verdict for a stated intent (and flags the co-change partners you're about to forget), verify_change reconciles the real diff against that plan (complete / incomplete / scope_expanded), and compare_change_impact reports the new cycles or layer violations a change introduced — never blaming it for pre-existing ones.

→ Full tool list and parameters: AGENT_REFERENCE.md · safe-change workflow: SAFE-CHANGES.md

Measured search precision

PureContext is benchmarked on 87 real-world open-source projects with 25 curated ground-truth queries each. Top-rank precision (P@1) reaches 84% on NestJS, 84% on Terraform, 72% on Protobuf and GraphQL, 60% on Nix, 52% on LÖVE (Lua/C++), and 40% on Tokio (Rust). Full per-language tables, methodology, and reproduction steps are in BENCHMARKS.md.

Documentation

User Guide — start here

The guide explains what PureContext does, why each feature exists, and how to use it effectively in real-world situations. It covers both solo developers and team deployments.

Real-world workflows:

→ Full guide index

Reference Manual

Parameter-level documentation for every tool, configuration option, language, framework adapter, and deployment option lives in docs/README.md. The reference manual is cross-linked with the user guide above — every topic has both a narrative and a reference page where one helps.

What it indexes

Languages

34 languages via bundled tree-sitter WASM grammars — no separate install required.

Symbol indexing and search cover all 34. Dependency edges (blast radius, importers, cycles) currently cover TypeScript/JavaScript, the JVM family (Kotlin, Java, Scala, Groovy — package-aware, multi-module safe), C# (namespace-aware, multi-project safe), Python (layout-convention resolver, src/ layouts and relative imports), Go (go.mod resolver, workspaces supported), PHP (namespace + composer PSR-4), Haskell, Elixir, Erlang, Fortran (v1.19.0), Rust (v1.20.0 — mod-tree resolver, Cargo workspaces supported), Dart (v1.31.0), Ruby and Swift (v1.36.0 — discovered load paths + Zeitwerk constants; SwiftPM targets), and languages whose imports are file paths — see which languages get dependency edges before relying on the graph tools for the remaining long tail.

→ Language Support guide · Full reference

Frameworks

Framework-aware extraction — routes, components, hooks, models, ORM entities, and middleware are pulled out as first-class symbols (not just functions and classes).

→ Framework Adapters guide · Full reference

Installation

Requirements: Node.js 18, 20, or 22. Prebuilt binaries included for Windows, macOS, and Linux — no native compilation needed.

Claude Code

claude mcp add purecontext-mcp -- npx purecontext-mcp@latest

Git hooks — keep the index fresh (recommended)

An index built before your last git checkout / pull / rebase returns old symbol locations. Fix that once per repository:

npx purecontext-mcp@latest hooks --install --git        # in any worktree of the repo
npx purecontext-mcp@latest hooks --list                 # shows the state
npx purecontext-mcp@latest hooks --uninstall --git      # removes them

What you get:

• post-checkout, post-merge, post-rewrite shims in the directory git runs hooks from (core.hooksPath respected — husky / lefthook friendly; an existing hook body is kept and chained). A linked worktree installs into the shared hooks dir, so one install covers every worktree.

• After each of those git operations the index is brought up to HEAD from git's own change list — no directory walk. Small changes run inline (10 s cap); big ones run detached, and list_repos shows re-index in progress.

• git worktree add clones the sibling worktree's index instead of re-parsing (measured: a 7k-file tree went from 309 s to 4 s).

• Nothing here can make a git command fail — every shim exits 0.

Without the hooks, run index_folder({ path, onlyChanged: true }) after a branch change; list_repos reports freshness per repo either way.

Keep it small. Since 1.33.0 an index no longer carries the source text; every file's bytes live once in a shared, content-addressed store (~/.purecontext/blobs.db), so a second worktree costs its symbols and edges only. Indexes whose checkout is gone, and half-written ones from a crashed run, are listed by list_repos (store) and removed by

npx purecontext-mcp@latest index gc            # dry run
npx purecontext-mcp@latest index gc --blobs --yes

Claude Desktop

Edit ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "purecontext": {
      "command": "npx",
      "args": ["purecontext-mcp@latest"]
    }
  }
}

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "purecontext": {
      "command": "npx",
      "args": ["purecontext-mcp@latest"]
    }
  }
}

Windsurf

Open Windsurf Settings → MCP section, or edit the MCP config file directly:

{
  "mcpServers": {
    "purecontext": {
      "command": "npx",
      "args": ["purecontext-mcp@latest"]
    }
  }
}

VS Code

Create .vscode/mcp.json in your project:

{
  "servers": {
    "purecontext": {
      "type": "stdio",
      "command": "npx",
      "args": ["purecontext-mcp@latest"]
    }
  }
}

Shared team server (HTTP)

If your team runs a shared PureContext server, connect with an HTTP transport instead:

{
  "mcpServers": {
    "purecontext": {
      "transport": "http",
      "url": "https://purecontext.yourcompany.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer pctx_yourpersonalkey"
      }
    }
  }
}

Data directory

Indexes, the shared content store (blobs.db), config, and telemetry live under ~/.purecontext/ by default. Set the PCTX_DATA_DIR environment variable to relocate everything (useful for CI, test isolation, or keeping experiments away from your real indexes):

PCTX_DATA_DIR=/tmp/pctx-scratch npx purecontext-mcp

The test suite sets this automatically (test/setup.ts), so npm test never touches your real ~/.purecontext.

Branches: an index is keyed on the folder path, not the git branch, and since 1.30.0 it records the commit it reflects (head / freshness on list_repos). Install the git hooks once — npx purecontext-mcp hooks --install --git — and every checkout / merge / rebase re-indexes what changed from git's own change list (no directory walk, never blocks git). Without hooks: index_folder({ path, onlyChanged: true }) after an in-place switch. For parallel branch work use one git worktree per branch: a new worktree clones a sibling's index and applies the delta instead of re-parsing.

→ Full installation guide

Teaching your AI agent to use PureContext well

Installing PureContext gives your agent the tools. Adding the agent instructions tells it how to use them — which tool to pick for each task, in what order, and what to avoid.

Without these instructions, an agent may default to reading entire files rather than using search_symbols, or may not know to call list_repos first to get the repository ID required by every tool.

One-command install (recommended)

Run this once inside your project directory:

npx purecontext-mcp@latest install all

This auto-detects which AI coding tools you have set up in the project and writes the PureContext workflow rules to the right place for each. Re-running is safe — every writer is idempotent (managed blocks are marked and replaced rather than appended).

When no --scope flag is given, the CLI prompts you to choose where to install:

Where should PureContext be installed?
  1) Local  — this project only
  2) Global — all projects (user-level config)
  3) Both

Pass --scope to skip the prompt:

npx purecontext-mcp@latest install all --scope=local    # this project only
npx purecontext-mcp@latest install all --scope=global   # user-level, all projects
npx purecontext-mcp@latest install all --scope=both     # both places at once

For a single tool:

npx purecontext-mcp@latest install <tool> --scope=global

To preview without writing files:

npx purecontext-mcp@latest install all --dry-run
npx purecontext-mcp@latest install --list      # show which IDEs were detected

Supported tools and where each one writes its workflow rules (it also registers the purecontext-mcp MCP server with each — pinned to your global Node — in that tool's own MCP config):

Manual install

If you'd rather paste the rules yourself, two instruction files are at the repository root:

• AGENT_INSTRUCTIONS.md — the onboarding doc: mandatory workflow, tool-selection table, navigation patterns, and anti-patterns. Paste into your agent's rules file, or run npx purecontext-mcp install <tool> to write a compact, always-on version automatically.

• AGENT_REFERENCE.md — the single canonical reference: a full intent→tool picker, every parameter, every navigation pattern, and known limitations. Installed automatically by hooks --install; read this when an agent needs the authoritative answer.

Paste the contents into whatever system prompt, memory, or rules configuration your agent uses.

License

MIT — see LICENSE.

Contributing

Issues and pull requests are welcome at github.com/goranocokoljic/pure-context. Before opening a feature PR, please open an issue to discuss the design — the three-layer architecture (Core → Handlers → Adapters) has hard rules about dependency direction that are easy to violate accidentally. See CLAUDE.md at the project root for the architectural conventions.

For language or framework adapters: pick a real-world repository, add a 25-query ground-truth file in benchmarks/<project>/queries.json, and include benchmark numbers (P@1 / P@3 / R@5) in the PR description so reviewers can confirm the change is a net improvement.

Support

• Bug reports and feature requests: GitHub Issues

• Questions about MCP integration: Open a Discussion on the repository

• Changelog: CHANGELOG.md

• Stability and semver policy: docs/27-api-stability.md