Rarefaction

Rarefaction — LSP call graph MCP server for AI coding agents

Rarefaction is a Model Context Protocol (MCP) server that gives a coding agent the call graph and code context for one symbol straight from the project's language server (Language Server Protocol, LSP). Ask about a function, method or type and get, in one call: its signature and doc, its body, who calls it (tests marked), what it calls, who implements it, the tests that reach it and the short list of files a change can affect. The agent reads that instead of opening whole files and grepping, which keeps its context window small and spends fewer tokens on exploration.

Works with Claude Code, Codex and any MCP client over stdio. Profiles cover Swift, Rust, C/C++, TypeScript/JavaScript, Python and WebAssembly text (WAT).

Run against the bundled TypeScript fixture (fixtures/SampleTypeScript):

# scale — engine.ts:2:17

function scale(value: number): number

Double one input sample.

Callers (2, 1 in tests)

• render — render.ts:2 (calls at 3)
• · testScale — engine.test.ts:2 (calls at 3) [test]

Tests that reach it (1)

• testScale — engine.test.ts:2

Run only these:

npm test -- "engine.test.ts"

Live files (3 of 3)

• engine.test.ts
• engine.ts
• render.ts

_11 LSP requests, 6430 ms (includes language-server cold start); index on-open_

Once the language server has indexed, a call takes a fraction of a second (median 80 ms on ripgrep, 220 ms on the 800-file IronRDP workspace); the server's cold start, 6–16 s on those projects, is paid once per session.

What it helps with

• Reducing token usage in AI coding agents. One bounded answer replaces several whole-file reads and searches. Measured on 50 real commits in ripgrep and IronRDP, the answer was a median 6–7% of the bytes of reading the files it names once. How much that saves in a whole agent session is not measured yet; see docs/measurement.md, including where the live set falls short.
• Call graph and impact analysis. "What calls this function, and what would break if I change it?" By default two levels of callers and one of callees, plus implementations and type hierarchy, each bounded and marked when truncated.
• Choosing which tests to run. Tests that reach the symbol, with a "run only these" command for the project's test runner.
• Orientation in an unfamiliar codebase. Bare names, qualified names or exact path:line:column positions; ambiguity comes back as a list of exact positions rather than a guess.
• Honest answers about coverage. Stale indexes, servers still indexing and servers without call hierarchy are reported in the answer, not hidden.

Why an MCP server for LSP call graphs

Language servers already know the call graph precisely — that is what "find references" and "call hierarchy" are. Editors and LSP tools expose them one hop at a time, so an agent pays a tool call and a round of context per hop. An agent needs the *closure*: everything within a couple of hops, filtered to the project, with the tests picked out, small enough to read in one go. That composition is what this server does. It is deliberately language-agnostic: the core speaks LSP and nothing else, and everything a language needs is a small profile.

How it relates to nearby tools:

Install

Requires Node 22.22.2 or later; used on macOS and Linux (CI runs on Ubuntu), untested on Windows. The TypeScript and Python language servers are bundled. Install the others you need and put them on the PATH your client launches with — see Languages and configuration. Swift needs macOS with Xcode (or a Swift toolchain with sourcekit-lsp).

As a plugin (Claude Code and Codex)

The plugin bundles the server, launched with npx -y rarefaction-lsp-mcp, and an orient-first skill that tells the agent to call status and orient before reading whole files, and scope before editing.

# Claude Code

claude plugin install rarefaction --marketplace ip2k/rarefaction

Codex

codex plugin marketplace add ip2k/rarefaction codex plugin add rarefaction@rarefaction

In a Claude Code session, /plugin install rarefaction --marketplace ip2k/rarefaction does the same. Restart or reconnect the session afterwards.

As an MCP server

claude mcp add --scope user --transport stdio rarefaction -- npx -y rarefaction-lsp-mcp

codex mcp add rarefaction -- npx -y rarefaction-lsp-mcp

Add --env PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH" before the -- if rust-analyzer or wat_server live outside the client's PATH. The tools are status, orient and scope (in Claude Code, mcp__rarefaction__status, mcp__rarefaction__orient and mcp__rarefaction__scope); all three are read-only, so you can allow them in your permissions to avoid repeated prompts. For Codex, give the first index time in ~/.codex/config.toml:

[mcp_servers.rarefaction]

startup_timeout_sec = 20 tool_timeout_sec = 180

The server takes --root and --profile . Explicit --root takes precedence over Claude Code's CLAUDE_PROJECT_DIR, then the working directory. Leave both unset in a user-wide registration so every project can use all supported profiles. See the MCP documentation for Claude Code and Codex.

From a clone

To run your own changes, build and register the compiled entry instead:

git clone https://github.com/ip2k/rarefaction.git

cd rarefaction npm ci && npm run build claude mcp add --scope user --transport stdio rarefaction -- "$(command -v node)" "$PWD/dist/index.js"

Rebuild after changing the server, then restart or reconnect (/mcp) the client session.

Check it works

Start a new chat in a project and ask the agent to call status, then orient on a symbol you know. status.root should match the project and the selected entry in status.profiles should have ok: true. One registration serves all supported languages; each language server starts lazily.

Agent guidance

The plugin's skill covers this. Without the plugin, add this to ~/.claude/CLAUDE.md, AGENTS.md or a project instruction file:

Use rarefaction's status tool once in a new project, then orient on the

relevant symbol before reading whole files, and scope on a symbol before

editing it (advisory: also look outside the files it lists). In mixed

repositories pass profile or a workspace-relative path:line:column, and

pass project for a nested package that is not a workspace member. Start

with the default graph bounds; expand only when necessary. Follow freshness

and coverage advice, and inspect FFI/generated bindings separately when

relevant.

Xcode projects

Xcode projects need a build-server config so sourcekit-lsp gets compiler flags (SwiftPM packages need nothing):

brew install xcode-build-server

cd /path/to/App && xcode-build-server config -project App.xcodeproj -scheme App echo buildServer.json >> .gitignore

Then build once in Xcode or with xcodebuild; the index is only as fresh as the last build, and orient says so when a source file is newer. Saved source edits are sent to open LSP documents before later queries, but Xcode projects still need a new build to refresh their cross-file index.

Tools

Planned: impacted_tests (the upward walk restricted to tests, as a runnable selection).

Languages and configuration

The server probes each language server's capabilities. When call hierarchy is absent, orient reports references and enclosing symbols, without claiming those references are calls. Native Rust/C sources compiled to WebAssembly use rust/c; .wasm binaries need disassembly to .wat. WAST test scripts, vendor assembly, indirect runtime dispatch and cross-language FFI edges are not indexed as a unified graph.

Optional .rarefaction.json in the workspace root configures each profile. Paths in project, profile root, and relative position queries are relative to that workspace. A position query without project is answered from the outermost Cargo w