slimdex-mcp

# slimdex-mcp

A local [MCP](https://modelcontextprotocol.io) server that helps coding agents
**retrieve code narrowly** instead of reading whole files into context. An agent
asks Slimdex for a specific outline, line range, symbol body, or reference
list, rather than loading a file to find one thing.

> **Status: pre-1.0.** It works on the repos it has been run
> against, but it has not been published, packaged, or validated broadly. Read
> [What's actually verified](#whats-actually-verified) before relying on it.

| Tool | What it returns |
|------|-----------------|
| `index_repo` | Builds/refreshes a persistent symbol + import index; only changed files re-parse |
| `outline_file` | Declarations of one file with line numbers |
| `get_file_skeleton` | Signatures with bodies elided, nesting preserved |
| `read_lines` | One line range |
| `get_symbol_context` | One function/class body ±2 lines, capped by `maxLines`; `names:[...]` pulls several bodies in one call |
| `search_code` | `path:line:col` + the matching line with caret highlight; `limit`/`offset`/cursor pagination |
| `find_definition` | Definition site(s) of a symbol as `path:line:col` |
| `search_symbols` | Fuzzy symbol-name lookup, ranked exact→prefix→substring→subsequence |
| `search_intent` | Natural-language query ranked over symbols by BM25 (no embeddings) — find code by what it does |
| `context_pack` | One call: ranks a topic's symbols, shows how they connect, and bundles the top bodies under a budget — the whole exploration in one round-trip |
| `find_references` | Textual references as `path:line:col` + enclosing function |
| `find_tests` | Of the references to a symbol, which live in test files — or a warning that none do |
| `replace_symbol` | Overwrite a symbol's body addressed by name (no re-sent old code); snapshots first, re-indexes after |
| `get_context` | One call: opt-in definition / signature / callers / imports / dependents, budgeted |
| `repo_map` | Dir-level file/line/symbol counts; `path:` drills into a dir's largest files |
| `changed_files` | Changed files + which symbols each hunk lands in |
| `dep_graph` | `imports` / `dependents` / a Mermaid diagram (`root`+`depth` BFS) |
| `stats` | Per-tool call counts and response sizes, in characters, plus read follow-through and write discipline |
| `batch` | Runs several calls in one request |
| `recap` | Prior sessions' activity, reconstructed automatically from the server's tool-call journal — works even when nothing was saved |
| `brief` | One-shot session opener: repo summary + journal-derived focus + saved conclusions checked against the live index (✓ live / ⚠ maybe stale) |
| `digest_save` / `digest_get` | Store a compact repo architecture cheat-sheet once; read it back with a per-covered-file freshness verdict, so the next session skips re-exploring |
| `snapshot` | Copies uncommitted files into `.slimdex/snapshots/` (also auto-runs hourly via `index_repo` on a dirty tree) — insurance against accidental resets, not a substitute for committing |
| `memory_save/search/list/delete` | Durable notes in `.slimdex/memory.json` |

The retrieval guidance below also ships in the server's MCP `instructions`, so
clients inject it into the model's context automatically.

### Recommended agent flow

`brief` first, at the very start of a session — one call that reports what the
repo is, where recent sessions were digging, and which saved conclusions still
match the code (stale ones flagged), so a fresh chat starts informed instead of
blank. Then `get_context("Foo")` to answer "what is this, who calls it, what does
it depend on" in one response. To understand a whole *area* rather than one
symbol, `context_pack("how does auth work")` runs the entire exploration
server-side and hands back a single bounded bundle — the relevant symbols, how
they connect, and the top bodies — so you spend one call and one transcript
entry instead of ten. Don't know the name, only what it does? —
`search_intent("parse the config file")` ranks symbols by intent with BM25, no
embeddings. Drop to `get_symbol_context` for one body (it flags itself if the file
drifted from the index, so you don't re-read to check), `get_file_skeleton` for a
file's shape, and `read_lines` when you need exact source. Before editing a
symbol, `find_tests` on it to see what covers it; to
rewrite a whole function, `replace_symbol` (you send only the new body — the old
code isn't re-sent just to locate the edit). Use `batch` to bundle several
lookups. Every search tool takes `limit` (default 20) and `offset`.

**Response budgeting:** `get_context` sections are opt-in via `include`
(default: definition, signature, callers, imports — add `body` or `dependents`
explicitly), callers are capped by `callerLimit`, and the response is bounded
by `maxChars` (default 12,000). Every cap that trips prints an explicit notice
(`showing 3 of 68`, `truncated at maxChars=...`) rather than dropping data
silently. `get_symbol_context` caps its span with `maxLines` the same way, and
`memory_list` returns the newest 50 facts unless told otherwise, as ~150-char
previews rather than whole bodies (`memory_get ids:[...]` expands them,
`full:true` dumps everything). On an 18-fact store that is the difference
between ~4,100 and ~18,600 chars in the call every session opens with.

### Config: `<root>/.slimdex.json` (optional)

```json
{
  "ignoreDirs": ["fixtures", "backend/src/main/resources/static/assets"],
  "extensions": [".astro", ".vue"],
  "suffixes": [".stories.mdx"],
  "exclude": ["generated/", "legacy/vendor"],
  "maxFileBytes": 2000000
}
```

`suffixes` matches a filename ending, for file types an extension can't identify.
Salesforce metadata sidecars ship as a built-in: `AccountSvc.cls-meta.xml`,
`panel.js-meta.xml` and `Account.object-meta.xml` are indexed, while `pom.xml`,
`web.xml` and `manifest/package.xml` are not — adding `.xml` to `extensions`
would have pulled in every config tree in the repo. Suffix-matched files are
indexed for search and read reach, not symbols.

Merged on top of the built-in ignore list (`node_modules`, `dist`, `.venv`,
`.svelte-kit`, `Pods`, `.pytest_cache`, …). An `ignoreDirs` entry is either a bare
name, matching any directory so called at any depth, or a path containing `/`,
anchored at the repo root and respecting directory boundaries (`src/gen` will not
also ignore `src/generated`). `index_repo` echoes what it loaded and warns about
unknown keys, wrong types, or invalid JSON, so a typo'd config isn't silently
indistinguishable from none.

**Build output usually needs no config at all.** Beyond the directory list, any
file whose lines run past ~5,000 characters is treated as minified build output and
left out of the index — bundlers strip newlines, and hand-written source doesn't
look like that. This catches what a name list structurally cannot: a hash-named
bundle (`index-B7xK2p9q.js`) inside a directory called `assets`. `assets`, `public`
and `static` are deliberately *not* ignored by name, because real source lives in
them; `index_repo` reports the count as `skipped(minified build output): N`.

### How the token saving works

There's no compression trick. The saving is behavioral: these tools let an agent
retrieve outlines, ranges, and locations instead of whole files, and the
persistent index means repeat lookups hit a cached query rather than a re-read.

Two later sessions, run by different models on different repo shapes, added
real-world numbers to the original report:

**Multi-file web app, bug-fix session (GPT-5.3-Codex).**
19 credits reported with slimdex; the model's own estimate for the same scope
without it: 45–70 credits. Math: 19/45 → 19/70 ≈ **58–73% cheaper**. The
counterfactual is the model's estimate, not a measured A/B — directional.

**Single giant file (folio-app: one 6,200-line, 313 KB `app.js`).**
Slimdex's own stats: ~34,000 chars across 8 calls ≈ 9–10k tokens — one
skeleton (213 signatures), then bodies of only ~12 relevant functions, 9 of
them fetched in a single `get_symbol_context names:[...]` call. The naive
path: 313 KB ≈ 78–85k tokens across 3–4 forced full reads. Math: ~10k vs
~80k ≈ **~70k tokens saved, an 85–90% reduction** on exploration. The bug's
diagnosis (an export path with no matching import path) was visible from the
skeleton's signatures before a single body was opened.

Together they sketch the scaling law: **the saving scales with how much
irrelevant code the naive path would drag in.** One giant file is the best
case; a normal repo lands around half to two-thirds cheaper; a repo of tiny
files breaks even. Same standing caveats as everything here: stats count
chars, not tokens (÷3.5–4), and single sessions are evidence, not benchmarks.

**Both figures above measure reading only, which is the cheaper half.** Output
costs roughly 4–5× input, so an undisciplined edit wastes more than an
undisciplined read: rewriting a whole function through a generic edit tool means
re-sending the entire old body purely so the tool can locate it. `replace_symbol`
addresses by name and that cost disappears. `stats` reports this alongside
follow-through, because the leak is otherwise invisible — the expensive path
still produces a correct edit, so nothing signals that you overpaid:

```
write discipline:
  replace_symbol: 0 call(s), 0 symbol(s) rewritten by name
  changed outside slimdex: 12 file(s)
  pre-edit checks (find_tests/dep_graph/get_context/changed_files): 0
```

External edits are inferred from content hashes moving between two `index_repo`
runs, so the number is honest about its limits: it sees that bytes changed, never
which tool changed them, and a human editing in another window counts too.


### The realistic whole-workflow band

The figures above are single-scenario *exploration* numbers — the best case,
where the naive path would have dragged in the most irrelevant code. Averaged
across a whole real workday, not just the exploration slice, the band settles
lower:

- **~55–60%** o