Rarefaction

[rarefaction logo: a reactor core glowing Cherenkov blue, drawn as a call graph]

Rarefaction — LSP call graph MCP server for AI coding agents

[CI] [npm] [License: GPL v3+] [ip2k/rarefaction MCP server]

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 Codeclaude plugin install rarefaction --marketplace ip2k/rarefaction
# Codexcodex plugin marketplace add ip2k/rarefactioncodex 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-mcpcodex 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 = 20tool_timeout_sec = 180

The server takes --root <path> and --profile <id>. 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.gitcd rarefactionnpm ci && npm run buildclaude 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-servercd /path/to/App && xcode-build-server config -project App.xcodeproj -scheme Appecho 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 workspace that takes the file's crate in (as a member, a package.workspace pointer or a path dependency of the root package), else from the nearest supported project marker. When that leaves part of an enclosing project out, the answer carries a warning that says so and which project to pass. TypeScript is the exception: the TypeScript language server answers one tsconfig.json project at a time, so in an npm, yarn or pnpm workspace with a tsconfig.json per package, callers in other packages are not listed, with or without project, and the warning says that too. The search stops at a directory holding .git, so a position in a git worktree, submodule or other checkout nested inside the workspace is answered from that checkout alone; give positions its path as a prefix, and name it in project for bare names. Bare names in mixed workspaces need profile or a configured default_profile:

{  "default_profile": "typescript",  "profiles": {    "rust": {      "root": "firmware/rust",      "initializationOptions": {        "cargo": { "target": "thumbv7em-none-eabihf", "features": ["board"] }      }    },    "c": { "args": ["--background-index", "-j=2", "--compile-commands-dir=/absolute/local/build"] },    "python": {      "initializationOptions": { "python": { "pythonPath": "/absolute/project/.venv/bin/python" } }    }  }}

command, args, env, and initializationOptions may override each profile's launch settings; initialization objects merge recursively. args replaces the defaults. Rust cargo checks, build scripts and proc macros are disabled by default to avoid incidental compilation; enable them explicitly when your project needs generated/expanded code. After changing this configuration, restart the MCP connection. Missing executables appear in status with setup advice.

Graph output defaults to 50 nodes per direction, two caller levels, one callee level and 80 body lines. Use max_nodes, up, down, or include_body: false to adjust context size. Truncation is explicit. Name lookup without a workspace index falls back to scanning at most 200 source files; use an exact position or a smaller project when needed.

See embedded C, JieLi and WebAssembly setup for analysis compilation databases and target limitations.

Serena alongside Rarefaction

Serena complements this server with symbol navigation, diagnostics and semantic edits. docs/serena.md covers a pinned installation, a WAT adapter, project language settings, limitations and verification.

Privacy

Rarefaction runs entirely on your machine. It reads your project's files and talks to language servers over local stdio; it makes no network requests and collects no telemetry. The language servers it launches behave as they do in your editor (for example, rust-analyzer runs cargo metadata, which may fetch crate indexes). npx downloads the package from npm on first use.

Development

npm ci && npm run buildnpm test                        # unit + real LSP integration; external servers skipped if absentclaude plugin validate .        # plugin and marketplace manifestsnode scripts/verify-codex.mjs   # exercise the registered MCP through Codex, no model turnnpx tsx scripts/try.ts --root fixtures/SampleTypeScript orient '{"symbol":"scale"}'

The logo and icon (Rosé Pine Moon) come from python3 tools/render_logo.py; the README diagrams (Dawn for light, Moon for dark) from python3 tools/render_diagrams.py. The fixtures under fixtures/ are small synthetic projects, one per language. CI runs the suite with clangd and rust-analyzer installed. The Release workflow (a v* tag push, or "Run workflow" on main) checks that every version field agrees (package.json, server.json, both plugin manifests), publishes to npm and the MCP Registry as io.github.ip2k/rarefaction-lsp-mcp, then creates the GitHub release. docs/measurement.md states the thresholds the project holds itself to; docs/decisions.md records why things are the way they are.

Licence

Copyright (C) 2026 Sean (ip2k).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It is distributed WITHOUT ANY WARRANTY; see LICENSE for the full text.