rarefaction
A read-only MCP server that gives a coding agent the bounded call graph, code context, tests and affected files for one symbol, resolved through the project's language server (LSP).
orient— one call returns a symbol's signature, doc and body, its callers (test cases marked) and callees with call sites, implementations and type hierarchy, the tests that reach it with a "run only these" command, and the live files a change can affect.scope— the working set for planning an edit:orient's call-graph files plus files that historically changed in the same commits, each with its reason (advisory, not a boundary).status— detected language profiles and selected one, project roots, executables and compile flags, index freshness, and which LSP features the server supports.Symbol lookup by bare name (
updateLocation), qualified name (Engine.updateLocation), or exactpath:line:column; ambiguous names come back as a list of exact positions rather than a guess.Multi-language through small profiles: Swift (sourcekit-lsp), Rust (rust-analyzer), C/C++ (clangd), TypeScript/JavaScript, Python (Pyright) and WebAssembly text (wat_server), one registration serving all.
Context-window friendly — output is bounded per direction and explicitly marked when truncated; tunable via
up,down,max_nodes,include_body,max_body_lines.Honest coverage — stale indexes, still-indexing servers and missing call-hierarchy support are reported as warnings in the answer.
Runs locally over stdio with Claude Code, Codex or any MCP client: no network requests, no telemetry, all three tools read-only and idempotent.
Provides call graph and symbol context for C/C++ code through the project's language server, including callers, callees, implementations, type hierarchy, tests that reach the symbol, and live files affected by changes.
Provides call graph and symbol context for JavaScript code through the project's language server, including callers, callees, implementations, type hierarchy, tests that reach the symbol, and live files affected by changes.
Provides call graph and symbol context for Python code through the project's language server, including callers, callees, implementations, type hierarchy, tests that reach the symbol, and live files affected by changes.
Provides call graph and symbol context for Rust code through rust-analyzer, including callers, callees, implementations, type hierarchy, tests that reach the symbol, and live files affected by changes.
Provides call graph and symbol context for Swift code through sourcekit-lsp, including callers, callees, implementations, type hierarchy, tests that reach the symbol, and live files affected by changes.
Provides call graph and symbol context for TypeScript code through the project's language server, including callers, callees, implementations, type hierarchy, tests that reach the symbol, and live files affected by changes.
Provides call graph and symbol context for WebAssembly text (WAT) code through the project's language server, including callers, callees, implementations, type hierarchy, tests that reach the symbol, and live files affected by changes.
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:columnpositions; 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.
Related MCP server: CodeCortX-MCP
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:
approach | what the agent gets |
reading files and grep | whole files; text matches, not calls |
per-request LSP tools (definition, references, call hierarchy) | precise answers, one hop per tool call |
symbol navigation and semantic editing over LSP; works well alongside this | |
Rarefaction | the bounded multi-hop call graph, tests and live files for one symbol in one call |
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@rarefactionIn 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-mcpAdd --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 = 180The 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.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 >> .gitignoreThen 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
tool | what |
|
|
|
|
|
|
Planned: impacted_tests (the upward walk restricted to tests, as a
runnable selection).
Languages and configuration
Profile | Language server | Prerequisites / scope |
| sourcekit-lsp | Xcode or a Swift toolchain; SwiftPM, or Xcode with a build-server config |
| rust-analyzer | Cargo.toml or rust-project.json; embedded/no_std/Wasm target settings supported; a project that pins a toolchain needs |
| clangd | C/C++; compile_commands.json or compile_flags.txt for accurate include paths and defines |
|
| TypeScript/JavaScript, TSX/JSX; the native TypeScript 7 language server, bundled with the |
| Pyright | Python and stubs; bundled; configure interpreter/import paths for your environment |
| wat_server | WebAssembly |
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 build
npm test # unit + real LSP integration; external servers skipped if absent
claude plugin validate . # plugin and marketplace manifests
node scripts/verify-codex.mjs # exercise the registered MCP through Codex, no model turn
npx 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.
Available Tools
3 toolsorientOrient on a symbolARead-onlyIdempotent
Compact source context from language-server indexes: signature, body, callers, callees, tests, implementations and relevant files. Use before broad file reads in Swift, Rust, C/C++, TypeScript/JavaScript, Python and WebAssembly WAT projects. In mixed workspaces specify profile or use path:line:column. No cross-language/FFI edges are inferred. Increase up/down only when needed.
Inputs: symbol (required), up, down, profile, +4 more. Returns: body, root, stats, tests, +15 more
scopeWorking set for a changeARead-onlyIdempotent
The files a change to one symbol is likely to touch: orient's call-graph files (callers, callees, implementations, tests) plus files that have historically changed in the same commits as the symbol's file, each with its reason. Use when planning an edit, to know which files to read and check. Advisory, not a boundary: real changes often touch files outside it.
Inputs: symbol (required), up, down, profile, +2 more. Returns: root, files, stats, counts, +5 more
statusProject, language server and index statusARead-onlyIdempotent
Check detected source-language profiles, project roots, executables, compile flags and freshness. Call once before orient in a new project or when orientation is incomplete. Pass profile/project to inspect a nested package.
Inputs: profile, project. Returns: root, profiles
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools have distinct roles: status is a preflight check, orient retrieves symbol context, and scope predicts change impact. There is minor overlap in that status and orient both reference profiles, but the descriptions clearly separate their purposes.
All names are single lowercase words with no underscores or camelCase, which is visually consistent. However, they mix grammatical roles (status is a noun, orient is a verb, scope is ambiguous), so there is no predictable verb_noun pattern.
Three tools is a tight, focused set for a code-orientation server, and each tool serves a clear step in the workflow. The count is slightly minimal but reasonable given the narrow scope.
The surface covers preflight, context retrieval, and impact analysis, but lacks any symbol search or discovery operation—users must already know a path:line:column. This is a notable gap for a code intelligence tool, though core workflows are partially supported.
Maintenance
Related MCP Connectors
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Repository knowledge graph MCP server for codebase understanding and debugging.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).12 npm3Apache 2.0
- FlicenseNot gradedqualityDmaintenanceA lightning-fast, language-agnostic code analysis MCP (Model Context Protocol) server built in Rust9-
- AlicenseNot gradedqualityBmaintenanceStandalone MCP server for code structure analysis using tree-sitter. Directory trees, symbol definitions, and call graphs without reading raw source files. Supports Rust, Python, Go, Java, TypeScript, Fortran, JavaScript, C/C++, and C#. Benchmarked up to 68% fewer tokens vs native tools.7Apache 2.0
- AlicenseAqualityBmaintenanceCall graph MCP server for Rust, Python, TypeScript, TSX, and JavaScript. Every caller and callee carries a resolution field showing how the reference was matched to a definition, plus multi-hop impact analysis for refactoring. Local-only, single binary, no network egress. Benchmarked against grep, ripgrep, and ctags on a 120-item hand-verified golden set, including the cases where it loses.3MIT