rarefaction

<p align="center"><img src="docs/images/logo.svg" alt="rarefaction logo: a reactor core glowing Cherenkov blue, drawn as a call graph" width="144"></p>

# Rarefaction — LSP call graph MCP server for AI coding agents

[![CI](https://github.com/ip2k/rarefaction/actions/workflows/ci.yml/badge.svg)](https://github.com/ip2k/rarefaction/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/rarefaction-lsp-mcp)](https://www.npmjs.com/package/rarefaction-lsp-mcp)
[![License: GPL v3+](https://img.shields.io/badge/license-GPL--3.0--or--later-blue)](LICENSE)

**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.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/architecture-moon.svg">
  <img alt="How Rarefaction works: a coding agent calls orient over MCP; Rarefaction routes the request to a language profile, resolves the symbol, walks the call graph through the language server over LSP, and returns one bounded answer." src="docs/images/architecture-dawn.svg" width="100%">
</picture>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/orient-moon.svg">
  <img alt="What one orient call returns, for Engine.updateLocation in the Swift fixture: callers at depth 1 and 2 with tests and a test helper marked, the tests that reach it with a command to run only them, and the 4 of 6 files that are live." src="docs/images/orient-dawn.svg" width="100%">
</picture>

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](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:

| 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 |
| [Serena](https://github.com/oraios/serena) | 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](#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.

```bash
# 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

```bash
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` and `orient` (in Claude Code, `mcp__rarefaction__status` and
`mcp__rarefaction__orient`); both 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`:

```toml
[mcp_servers.rarefaction]
startup_timeout_sec = 20
tool_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](https://code.claude.com/docs/en/mcp) and
[Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

### From a clone

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

```bash
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. In mixed repositories pass
> profile or a workspace-relative path:line:column. 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):

```bash
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

| tool | what |
|---|---|
| `orient` | `{symbol, profile?, project?, up?, down?, max_nodes?, include_body?, max_body_lines?}` — the bundle above. `symbol` may be `updateLocation`, `Engine.updateLocation`, or `path/File.swift:204:10`. Ambiguous names come back as an error listing exact positions. |
| `status` | `{profile?, project?}` — what the server can see: the profile inventory and which one is selected, prerequisites such as a build-server config, index freshness, and which LSP features the server offers. Call this first if `orient` finds nothing. |

Planned: `scope` (the live set as an enforceable working set — tree-shaking
for a task) and `impacted_tests` (the upward walk restricted to tests, as a
runnable selection). The live set is not yet a safe boundary for edits: on
real commits it contained a median half of the other files the change
touched ([measurement](docs/measurement.md#results)), so `scope` waits on
widening it beyond call edges.

## Languages and configuration

| Profile | Language server | Prerequis