io.github.Siddhukaushik/slimdex-mcp

Execute multiple slimdex calls in one request to avoid per-call protocol overhead. Pass calls: [{ "tool": "find_definition", "args": { "name": "login" } }, ...]. Cannot nest batch inside itself.

CALL THIS FIRST in a fresh chat — including on a repo slimdex has never seen, where it builds the index itself rather than sending you to index_repo. One synthesized opener instead of stitching memory_list + recap yourself: what the repo is, where recent sessions were digging (automatic journal), and each saved conclusion CHECKED against the current index so stale ones are flagged (✓ live, ⚠ may be stale).

Summarize the working-tree diff (or a diff against `base`) as changed files with +added/-deleted counts AND the enclosing functions/classes each hunk lands in — the blast radius, without pulling the patch into context. The cheap way to start a session on a dirty repo. Requires a git checkout.

Understand a whole topic in ONE call instead of ~10: give a natural-language query ('how does auth work') and slimdex runs the exploration itself — BM25-ranks the symbols, shows how their files connect (import graph, one hop), includes the top few bodies, all under a char budget. Saves the round-trips AND keeps ten separate results out of the transcript. Orient with this; drop to get_symbol_context / read_lines for exact source.

Query the internal import graph. mode=imports: what a file imports. mode=dependents: what imports it. mode=mermaid: a diagram — pass root (+depth, default 2) to walk outward from one file instead of dumping the whole graph, or scope to a path prefix. Run before refactoring a shared module.

Return the stored architecture cheat-sheet plus a freshness verdict: covered files that changed since it was written are flagged as reasons it may be out of date. Read it early to understand the system without re-exploring; if flagged stale, re-read the changed areas and digest_save an update.

Store a compact 'how this repo works' cheat-sheet — modules, flows, entry points, conventions — so future sessions read a page instead of re-exploring. `covers` (the paths it summarizes) lets later sessions be told when a covered file changed. Overwrites the previous one. Save the why and the shape, not a symbol list.

Look up a symbol name in the index; return definition site(s) as path:line:col + kind. Heuristic. Paged: the total is always exact, `limit`/`offset` control how many are printed, `pathPrefix` scopes them.

Whole-word textual search for a symbol, returned as path:line:col with the enclosing function/class. Counts every occurrence, including repeats on one line. Not scope-aware, so may include unrelated same-named identifiers. Supports pathPrefix, limit and offset.

Which references to a symbol live in TEST files: 'if I change calculateTax, which tests catch a break' — run exactly those, not the whole suite. Nothing covering it is surfaced as risk BEFORE you edit. Detected by path convention (*.test.*, *.spec.*, __tests__/, test_*.py …) or an indexed describe/it title. Textual, so same caveat as find_references.

ONE call for what would take several: definition, signature, callers/references (attributed to their enclosing symbol — heuristic), imports, dependents. Sections are OPT-IN via `include` (default definition,signature,callers,imports); add 'body' for full source, 'dependents' for reverse deps. Bounded by callerLimit and maxChars with explicit truncation.

Structural skeleton of a file: every declaration's signature with its indentation preserved and bodies replaced by ' … {line}'. Turns a 2,000-line file into a readable map for a fraction of the tokens. Use this before any full read of a file over ~300 lines.

Return ONLY the body of a symbol (function/class/method) plus a few context lines — not the whole file. Give a name (resolved via the index), several `names` at once, or an explicit path+line. This is the biggest per-lookup token saver. When a skeleton showed you WHERE the functions are, pull their bodies with names:[...] here — do NOT fall back to reading the whole file for a handful of bodies.

Build or refresh the persistent code index (symbols + imports). Only files whose mtime changed are re-parsed, so re-run it liberally, like `git fetch`, before trusting a search. Honors <root>/.slimdex.json (ignoreDirs/extensions/exclude/maxFileBytes) and reports config problems instead of ignoring them.

Wire slimdex's write discipline into the CLIENT, which registering the MCP server cannot do — the protocol has no mechanism for a server to add a hook, so this is the one call that closes the gap. Writes a PreToolUse hook that speaks up ONLY when an edit re-sends 25+ lines that an indexed symbol actually covers, or a whole file over 12KB is read. Merges rather than clobbers, is idempotent, and prints exactly what changed. scope: claude-global (default, all your repos) | claude-local | claude-project | copilot-global (VS Code, all your repos) | copilot-project (.github/hooks, COMMITTED). Use uninstall:true to remove it.

Remove one saved memory fact by its id.

Full text of specific facts by id, with the provenance note of what was being examined when each was saved. The expansion half of the preview model: triage cheaply with brief/memory_list, expand only what you need.

Saved facts newest-first as PREVIEWS (id, date, tags, opening clause); memory_get ids:[…] expands the ones that matter, full:true dumps everything. Prefer brief as the opener — same previews, staleness-checked.

Save a durable note (decision, gotcha, TODO, location) to <root>/.slimdex/memory.json.

Find saved memory facts by substring and/or tag. Previews by default; memory_get expands one by id.

Compact outline of one file — declarations with line numbers, not the body. Orient before reading.

Read only lines [start..end] (1-indexed, inclusive) of a file. Cheaper than the whole file.

Prior activity from the server's own tool-call journal — most-examined files, most-looked-up symbols, recent searches. Needs NO prior memory_save; works even when the last session saved nothing. recap = where sessions looked, memory = what they concluded. Normally use brief (folds both in); reach here for the raw journal.

Write a symbol by NAME — you never re-send the old body to locate the edit. Two modes: REPLACE (name/path+line plus body) overwrites an existing definition; INSERT (after:"X" or before:"X" plus body) adds a NEW symbol next to an existing one, which is what you want for 'add a method beside the related ones' — the anchor's own span comes from the index, so `after` means after its closing brace, not its signature line. Insert puts `body` in verbatim: indent it for the file, and include a leading/trailing newline if you want a blank line. range comes from the index; the file is SNAPSHOTTED first (.slimdex/snapshots), re-indexed after, and the new line span is reported so you don't re-read to verify. Safe to mix with ordinary edit tools: if the file moved under the index, a NAME is re-resolved against a fresh parse automatically (an explicit path+line still refuses, since that coordinate is yours). Ambiguous/unknown names are refused, never guessed. `body` = the complete replacement definition, indented for the file. `edits:[…]` applies several at once (one snapshot, one re-index); the batch is refused before any write if a target is ambiguous, two edits overlap, or a file isn't writable, and a write that fails mid-batch rolls the earlier files back and says so.

Birds-eye overview: top directories with file counts, total lines, and symbol counts. Pass `path` to drill into one directory and list its largest files (with `top` to cap the list) — the bridge between orienting at the directory level and picking a file to skeleton. Start every session here.

Search indexed files; return path:line:col + the matching line (+ optional caret highlight). Every occurrence on a line counts, and the reported total is exact unless the scan cap trips (then it says so). Page with limit and either offset or the opaque cursor from a previous call. Vendor/build dirs are already excluded. Use pathPrefix to scope; for symbols prefer find_definition/find_references.

Know WHAT the code does but not its name: a words query ranked over every indexed symbol by BM25 on tokenized names (camelCase/snake_case), kinds and filenames — 'validate user email' surfaces validateEmail / emailValidator. Matches WORDING, not meaning. Exact/partial name → search_symbols; literal string → search_code.

Find indexed symbols whose name matches a query, ranked exact > prefix > substring > subsequence. Use this when you half-remember a name ("something like handleAuth") — it reads only the index, never the files, so it is far cheaper and far less noisy than search_code for finding a declaration.

Copy every uncommitted file into .slimdex/snapshots/<timestamp>/ as insurance against accidental resets. Also runs automatically (at most hourly) when index_repo sees a dirty tree; newest 10 kept. Defeats a stray `git checkout .`; does NOT replace committing.

Per-tool call counts and response sizes recorded to <root>/.slimdex/stats.json. Reported in characters, not tokens — char/4 estimates are unreliable across tokenizers, so this measures what it can measure honestly. Use it to see which tool is actually producing your context, and to tune limits. Counters are CUMULATIVE across every session on this repo until reset. To measure ONE task: call checkpoint:true when you start, then session:true when you finish — the server is long-lived, so session:true alone means 'since the server booted', which can span several chats.