slimdex-mcp
Slimdex is a local MCP server that gives coding agents narrow, token-efficient repository retrieval and memory instead of whole-file reads.
Index the repository (
index_repo) and snapshot uncommitted files (snapshot).Explore files cheaply: outlines, skeletons, and capped line reads (
outline_file,get_file_skeleton,read_lines).Retrieve individual symbol bodies with context (
get_symbol_context,get_context,context_pack).Search by string, symbol name, or intent (
search_code,search_symbols,search_intent,find_definition).Find references and tests before editing (
find_references,find_tests).Rewrite symbols by name without re-sending old code (
replace_symbol).Map the repo and changes: directory/symbol counts, changed files with hunk-to-symbol attribution, and import graphs (
repo_map,changed_files,dep_graph).Persist memory and session context across chats (
memory_save/search/list/get/delete,digest_save/get,recap,brief).Monitor usage and batch calls (
stats,batch), and optionally install a client-side hook to enforce write discipline (install_hook).
Enables retrieval of code from Salesforce projects by recognizing and indexing Salesforce metadata sidecar files (e.g., .cls-meta.xml, .js-meta.xml, .object-meta.xml) for symbol search and code navigation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@slimdex-mcp search_intent "parse the config file""
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
slimdex-mcp
Your agent reads a 900-line file to change one function — then pays for that file again on every turn that follows. The whole conversation is re-sent each time, so an early read isn't a one-time cost. It's rent.
Slimdex is a local MCP server that gives coding agents narrow retrieval instead: a file's outline, one symbol's body, who calls it, what breaks if it changes — and memory that survives the session, so the next chat starts informed rather than re-deriving the repo from zero.
claude mcp add slimdex -- npx -y slimdex-mcp~50% fewer tokens in day-to-day use — ~55–60% on navigation-heavy work, ~45% on output-heavy work, and 85–90% on the worst case it was built for (one 6,200-line file, explored through a skeleton and 12 symbol bodies instead of four full reads).
Status: 1.1.0, on npm and in the MCP Registry. Those numbers are self-measured on the repos it has been run against, single sessions, not independently validated — and
statscounts characters, not tokens. Read What's actually verified before relying on it.
Tool | What it returns |
| Builds/refreshes a persistent symbol + import index; only changed files re-parse |
| Declarations of one file with line numbers |
| Signatures with bodies elided, nesting preserved |
| One line range, capped at 6,000 characters by default with a continuation line; set |
| One function/class body ±2 lines, capped by |
|
|
| Definition site(s) of a symbol as |
| Fuzzy symbol-name lookup, ranked exact→prefix→substring→subsequence |
| Natural-language query ranked over symbols by BM25 (no embeddings) — find code by what it does |
| 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 |
| Textual references as |
| Of the references to a symbol, which live in test files — or a warning that none do |
| Overwrite a symbol's body addressed by name (no re-sent old code); snapshots first, re-indexes after |
| One call: opt-in definition / signature / callers / imports / dependents, budgeted |
| Dir-level file/line/symbol counts; |
| Changed files + which symbols each hunk lands in |
|
|
| Per-tool call counts and response sizes, in characters, plus read mix and write discipline |
| Runs several calls in one request |
| Prior sessions' activity, reconstructed automatically from the server's tool-call journal — works even when nothing was saved |
| Compact session opener: repo summary + journal-derived focus + recent conclusions checked against the live index (✓ live / ⚠ maybe stale); |
| 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 |
| Copies uncommitted files into |
| Durable notes in |
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)
{
"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
read mix, 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): 0External 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% on navigation-heavy work — reading and understanding a codebase, where narrow retrieval replaces whole-file reads most often.
~45% on output-heavy work — churning out new code, where more of the cost is generation the server doesn't touch (though
replace_symbolnow shaves the write side too).~50% averaged over regular day-to-day use. The saving compounds the more sessions run through it, because
briefand memory mean each new chat starts informed instead of re-deriving the repo from zero.
Use it regularly across sessions in your IDE for the best of this.
Treat these as one data point, not a benchmark. Single repo, single task, one
A/B run each, self-measured, no repetitions or variance. Your mileage depends
heavily on whether your agent actually reaches for the narrow tools instead of
falling back to reading files — which varies by client and model. The method is
repeatable if you want to check it: run the same task in two fresh sessions, one
instructed to use only Slimdex and one instructed to avoid it, and compare
/status cache-write.
What's actually verified
Being explicit, since the rest of this README is easy to over-read.
Covered by the unit suite (npm test runs 224 tests across 23 files):
Symbol extraction across JS/TS (incl. class and object-literal methods), Python, Go, Rust, Java/C#, and comment skipping —
symbols.test.tsImport extraction for JS
import/require/export-from, Python, RustBlock extraction, brace-scoped and indentation-scoped, with string/comment awareness (quotes, templates,
//,/* */, full-line#) —extractBlock.test.tsImport resolution, external-module classification, reverse-edge dependents, Mermaid emission, and root-BFS depth scoping —
graph.test.tsSearch match format, pagination without overlap, per-line occurrence counting, exact totals, regex escaping/rejection —
search.test.tsOpaque cursor round-tripping and malformed-cursor rejection; parser-backend fallback —
pagination.test.tsOutline declaration detection vs. control flow —
outline.test.tsget_symbol_contextmaxLinesbudgeting and truncation noticeString/comment masking and brace-depth tracking —
lexer.test.tsPer-language extraction for all twelve supported languages —
languages.test.tsThe index cache returns the same object until the index is rewritten
.slimdex.jsonloading: every key applied through a real index build, plus the failure modes (invalid JSON, unknown keys, wrong types) each producing a visible warning instead of silence —config.test.tschanged_filesagainst a real temporary git repository: hunk→symbol attribution, untracked files, explicit base refs, and formatting; skips cleanly when git isn't installed —git.test.tsThe file watcher, with real fs events: a save is debounced, reindexed, and lands in the on-disk index —
watch.test.tsGraph edges beyond imports: name-reference edges for import-less code (class→used-class, interface→implementation via dependents, trigger→handler) and declarative-wiring edges from repo XML (metadata-binding→class), with comment/string mentions excluded and per-build caching —
apexgraph.test.tsThe in-memory file cache serves repeats without re-reading and always serves fresh content after an on-disk change —
fscache.test.tsTest-file detection across JS/TS/Python/Go/Ruby/Java/C# conventions, with Windows separators normalized and ordinary source (
latest.ts,Contest.java) not misflagged —testlink.test.tsThe write side: replacing a symbol's block, trailing code preserved, and CRLF vs LF line endings kept so an edit isn't reflowed into a whole-file diff —
edit.test.tsMemory staleness: a fact is marked live when it names a symbol/file that still exists, flagged stale only when every code mention is gone, and left unflagged for prose — plus brief composition —
brief.test.tsIntent search: camelCase/snake_case tokenization, and BM25 ranking that surfaces a differently-named symbol by its intent words while scoring an unrelated query to nothing —
intent.test.tsFreshness: a file newer than its indexed mtime reads as stale (line numbers may be off), a matching mtime reads as fresh, and a missing file never cries stale —
freshness.test.tscontext_packassembly: header + ranked symbols + bodies in one bundle, the no-match message, char-budget gating that still guarantees the first body, and the symbols-limit cap —pack.test.tsThe architecture digest: covered files modified after the digest read as stale, a newer digest reads clean, coverage-scope and directory-prefix filtering, and the rendered fresh/stale verdict —
digest.test.ts
Covered end to end, through the real MCP server (integration.test.ts spawns
the server over stdio against a temporary fixture repo and asserts on output):
index_repo, repo_map, read_lines, get_file_skeleton, outline_file,
get_symbol_context, find_definition, find_references, find_tests (the hit
and the no-coverage warning), search_intent (intent ranking), context_pack (one-call
bundle), digest_save/digest_get (round trip with freshness verdict),
get_context (including its maxChars cap),
dep_graph (imports + mermaid), batch, search_code, search_symbols,
stats, brief, replace_symbol (write-then-query round trip and the
unknown-symbol refusal), the memory_save/search/list/delete round trip, the
path-escape guard, and the not-found paths.
CI runs the build and both suites on Ubuntu + Windows, Node 20 and 22.
Caveat on the watcher test: recursive fs.watch is platform-dependent, so
watch.test.ts degrades to a logged skip on filesystems that never deliver an
event — same behavior as the watcher itself. On Windows, macOS, and current
Linux it asserts the full save→reindex path.
npm run smoke still exists but proves only that the pipeline is alive — the
correctness assertions live in integration.test.ts.
Verified by inspection: src/ contains no network calls — no code leaves
your machine. This one you can check yourself:
grep -rE "fetch\(|https?://|axios|http\.request" src/.
Related MCP server: LocalNest MCP
Longer documentation
In docs/:
tool-guide.md— every tool explained twice (technically and in plain words) with an example each, the combined workflow, and how mtime-based persistence workstool-guide.html— the same guide as a styled, self-contained page for the browsertoken-savings-report.md— the original A/B measurement, its method, and how to repeat itagent-brain.md— the full operating discipline as a readable documentagent-brain-slim.md— the one to drop into a repo as CLAUDE.md / AGENTS.md. Self-contained and one page: savings ladder, question→tool table, memory discipline, session hygiene, honest limits, env knobs. Same coverage as the full document at ~30% of the prose, because the tool rules are dense tables rather than paragraphs the server already injects.
Language coverage
Two measurements, because fixtures alone prove very little.
Fixtures — one per language, counting the declarations a developer would
actually navigate to: 65/65 found, 0 false positives, pinned by
test/languages.test.ts.
Real third-party code — extraction run over ~11,800 files from several hundred real packages (React, Babel, Remix, Socket.io, Playwright, Three.js, Emotion, zod, ajv …) and compared against an independently written heuristic for what counts as a declaration: 95.9% recall. Reproduce it yourself:
npm run audit -- ./node_modules # or any directory of code you didn't writeThat number is a floor, not a grade — the truth heuristic counts some non-declarations, so real recall is a little higher. What it's for is catching regressions and finding the next real gap.
About frameworks
Almost nothing that failed the audit was framework-specific. Frameworks add annotations, decorators and conventions; they rarely invent syntax. Handle the language and the frameworks come with it — fflib's Application/Domain/Selector/ Service/UnitOfWork layers extract completely (129 declarations) without a single fflib-aware rule.
The one genuine exception is test DSLs. A vitest/jest/mocha/RSpec file often
has no top-level declarations at all, so entire test directories used to index to
nothing. describe/it/test titles are now indexed as kind test, which is
what you actually navigate to in a test file.
Framework semantics are recovered wherever the reference exists somewhere in the repo, through two extra edge sources in the graph:
Name-reference edges, for languages that have no import statement (e.g. Apex): if one file's code — comments and strings masked out — mentions a top-level type defined in another file, that's an edge. This is what makes
implementsanswerable as "who implements this interface", and links a trigger to the handler class it news up.Declarative-wiring edges: bindings that frameworks keep in configuration rather than code (custom-metadata records, flow definitions) usually live in the repo as XML with the type name as an element value. Repo XML is scanned for known type names — XML comments excluded — and each hit becomes a
metadata-file → classedge, sodependentsanswers "what wires this up".
Both scans are cached per index build and cost nothing on repos without such
files. Pinned by apexgraph.test.ts. What no static reader can see is a
binding that exists only in a live system — configured in a running org or
database and never retrieved into the repo. If it's not in the repo in any
form, there is no edge to draw; search the type name instead.
Language | Extensions | What's recognised |
JavaScript / TypeScript |
| classes, interfaces, types, enums, functions, top-level arrows, class and object-literal methods |
Apex |
| classes, inner classes, methods (incl. |
Java |
| classes, interfaces, enums, methods, generic methods with a leading |
C# |
| classes, interfaces, structs, async and generic methods, virtual members |
Kotlin |
| classes, data classes, interfaces, |
Swift |
| classes, structs, enums, protocols, |
Python |
| classes, |
Go |
| funcs, receiver methods, struct and interface types |
Rust |
| structs, enums, traits, |
Ruby |
| classes, modules, |
PHP |
| classes, interfaces, traits, methods, functions |
Scala |
| classes, case classes, traits, objects, |
C / C++ / Objective-C |
| classes, structs, enums, free functions (incl. K&R braces, pointer returns), |
Performance
Cold index is a full parse; warm is an mtime check per file. Measured on Windows, Node 24.
Repo | Files | Symbols | Cold index | Warm index | Typical query |
Salesforce DX org | 56 | 344 | 0.1 s | 15 ms | < 10 ms |
Java + React app | 356 | 1,713 | 0.42 s | 26 ms | 3–57 ms |
Synthetic stress | 5,000 | 50,000 | 1.5 s | 0.24 s | 5–22 ms |
The index is held in memory and invalidated by the index file's mtime. Without that cache every tool call re-read and re-parsed the whole index — about 20 ms of dead weight per call on the 5,000-file repo, and it grew with the repo.
find_references is the slowest tool at scale because it is a textual scan,
not an index lookup — but a literal pre-filter now skips the line-split and
per-line regex for any file whose raw source doesn't contain the searched name,
which on a typical repo is most of them. Scope with pathPrefix to cut the
remaining file reads when you know roughly where to look.
File contents are also served from a byte-bounded in-memory LRU (64 MB,
validated by mtime+size per hit), so the second scan of a repo — and the
skeleton→read_lines→context sequence agents actually perform on one file —
costs a stat() instead of a read.
Memory across sessions
memory_save writes to <root>/.slimdex/memory.json, which outlives the
process — a fact saved in one chat is readable in the next, by a different
client, after a restart. Chat and editor share one store only when both point at
the same SLIMDEX_ROOT.
Nothing is captured automatically: the server never sees your conversation, so
the agent has to decide what's worth keeping. The shipped instructions tell it
to read memory first in a new session and to save decisions, constraints and
gotchas as it learns them — but that's guidance to the model, not a guarantee.
Known limitations
Symbol extraction is regex-based and heuristic, not a parser or LSP. It can miss unusual declarations, and
find_referencesis a textual match that may include same-named but unrelated identifiers.Symbol and outline extraction now run against a masked copy of each line, with string and comment contents blanked out, so declaration-shaped prose inside a template literal is no longer indexed as code. Declarations are also depth-aware: a
const x = () => …ortype X = …counts only at top level, because locals inside a function body are not things anyone navigates to. Class methods are still indexed at their nesting depth.An inline Python
#comment containing a brace can still confuse block extraction (#is also the JS private-field sigil, so it can't be stripped blindly).changed_filesattributes a hunk to the nearest preceding declaration — right for a normal function body, approximate for code between declarations. Treat it as blast radius, not a call graph.search_codereports an exact total but stops at an internal scan cap on very large result sets, printingN+ (scan cap reached)rather than a confident wrong number.Language support is uneven: JS/TS is the best-covered. C-family and Ruby, formerly the thinnest, gained dedicated rules (free functions,
Foo::bardefinitions, function-like macros,attr_*); the remaining soft spots are advanced C++ shapes — templates split across lines, operator overloads.For LSP-grade precision you'd swap the parser for tree-sitter or a language server.
src/parser.tsis the seam: aParserinterface selected bySLIMDEX_PARSER, with the regex parser as the only implementation that ships. A tree-sitter backend would drop in there without touching any tool or the index format. It is not built — per-language grammars trade away the "installs instantly, runs offline, zero config" property.
Deliberately not built
Ideas evaluated and rejected, with reasoning — these are design opinions, not measured results:
Symbol-ID dictionaries (
S42→ path) — MCP has no client-side expansion layer, so the model receives an opaque token it must spend another call to resolve.Token-budget managers / cost estimators —
chars/4estimates are unreliable across tokenizers, and auto-compressing on a bad estimate can drop data the model needed.Delta / "already-sent, see response #5" caching — after context compaction the earlier payload is gone, so the reference resolves to nothing.
Embeddings / semantic search — large dependency footprint; possible future optional flag, not a default.
A tree-sitter parser backend — this is the one that would close the remaining ~4%, and it was costed rather than hand-waved:
web-tree-sitteris WASM so it needs no native compilation, but the grammars (tree-sitter-wasms) are 51.7 MB unpacked against ~4.5 MB for the whole current install. Evaluated and declined at 95.9% measured recall, because "installs in a second, runs offline, no configuration" is the property this server exists to have.src/parser.tsremains the seam if that calculus ever changes — a backend drops in there without touching a tool or the index format.
Install
Published on npm as slimdex-mcp,
and listed in the MCP Registry as
io.github.Siddhukaushik/slimdex-mcp. Nothing to build — point your client at:
npx slimdex-mcpOr from source, if you want to hack on it:
git clone https://github.com/Siddhukaushik/slimdex-mcp
cd slimdex-mcp
npm install
npm run build # produces dist/index.js
npm test # vitest unit suiteVerify it runs end to end against a repo:
npm run smoke # this repo
node smoke-test.mjs "C:/path/to/some/repo" # any otherEnvironment variables
Var | Effect |
| Repo to index (or pass as the first CLI arg; defaults to cwd) |
| Set to |
| Parser backend; only |
| Set to |
|
|
| Set to |
The persistent cache
Per repository, Slimdex writes to <repo>/.slimdex/:
index.json— the code index (mtime-invalidated per file, and discarded wholesale when the index format version changes, so a stale index built by an older extractor is never reused)memory.json— saved memory factsstats.json— per-tool usage counters
The directory ignores itself: a * .gitignore is written inside it (the
node_modules/.cache trick), so it never shows up in git status and you don't
have to touch the repo's own .gitignore. Delete that inner file if you want
to commit the cache.
Wiring it into MCP clients
MCP is a shared standard, so the same server should plug into any MCP-capable
client. The project root is passed via SLIMDEX_ROOT (or as the first CLI
arg).
Only Claude Code and Claude Desktop have actually been run. The others below are the standard config shape for each client, written from their documented format — they are untested here and may need adjustment.
Since 1.0.0 the simplest wiring is npx -y slimdex-mcp — no clone, no build, and
it stays current. The examples below keep the node <ABS_PATH> form for anyone
running from source; to use the published package instead, swap
"command": "node", "args": ["<ABS_PATH>"] for
"command": "npx", "args": ["-y", "slimdex-mcp"].
Replace <ABS_PATH> with your build output, e.g.
C:\path\to\slimdex-mcp\dist\index.js, and <REPO> with the repo to index.
No tuning required. The savings that matter are on by default in every
client: memory facts list as previews, responses are terse, an identical re-read
of an unchanged file answers with a pointer instead of the body, and several
symbol edits go in one call. The env vars below are for opting out, or for
lean — which trades a further ~8,700 chars/turn against routing a third of the
tools through batch, so it is deliberately not the default.
Claude Code (CLI) — tested
claude mcp add slimdex --env SLIMDEX_ROOT=<REPO> -- npx -y slimdex-mcpFrom source instead: -- node <ABS_PATH>.
Claude Desktop — tested
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"slimdex": {
"command": "npx",
"args": ["-y", "slimdex-mcp"],
"env": { "SLIMDEX_ROOT": "<REPO>" }
}
}
}Codex CLI — tested
~/.codex/config.toml
[mcp_servers.slimdex]
command = 'C:\Program Files\nodejs\node.exe'
args = ['<ABS_PATH>']
startup_timeout_sec = 30Registered globally like this, slimdex attaches to every Codex task and uses
that task's working directory as the repo root — no SLIMDEX_ROOT needed. Codex
launches the server with a restricted environment, so give command an absolute
path to node rather than relying on PATH.
Cursor — untested
.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
{
"mcpServers": {
"slimdex": {
"command": "node",
"args": ["<ABS_PATH>"],
"env": { "SLIMDEX_ROOT": "${workspaceFolder}" }
}
}
}Windsurf — tested
~/.codeium/windsurf/mcp_config.json — same mcpServers shape as Cursor.
VS Code (Copilot / MCP) — tested
.vscode/mcp.json
{
"servers": {
"slimdex": {
"command": "node",
"args": ["<ABS_PATH>"],
"env": { "SLIMDEX_ROOT": "${workspaceFolder}" }
}
}
}Cline (VS Code extension) — tested
Cline settings → MCP Servers → add:
{
"slimdex": {
"command": "node",
"args": ["<ABS_PATH>"],
"env": { "SLIMDEX_ROOT": "<REPO>" }
}
}Zed — tested
settings.json → context_servers
{
"context_servers": {
"slimdex": {
"command": { "path": "node", "args": ["<ABS_PATH>"], "env": { "SLIMDEX_ROOT": "<REPO>" } }
}
}
}For clients that expose the workspace folder (Cursor, VS Code),
${workspaceFolder}keeps Slimdex pointed at the repo you have open.
Typical agent workflow
index_repoonce at the start (faster on subsequent runs), thenbriefto pick up where past sessions left off with stale notes already flagged.repo_map→ get the lay of the land.outline_fileon a file of interest → pick line ranges.read_linesfor just those ranges.find_definition/find_references/dep_graphto navigate.find_testsbefore editing a symbol;replace_symbolto rewrite one without re-sending its old body.memory_savedecisions and gotchas so the next session starts informed.
License
MIT © 2026 Kael VK Inc. (Business Number 751569161 RC0001) — see LICENSE.
Provided as is, with no warranty and no support. If it doesn't build, doesn't run, or doesn't work on your setup, that's yours to carry — see the disclaimer in the license.
Available Tools
30 toolsbatchRun several tool calls at onceA
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.
Inputs: calls (required).
briefOne-shot session onboarding briefA
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).
Inputs: limit.
changed_filesWhat changed, and which symbols it touchedA
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.
Inputs: base, limit.
context_packOne-call task context bundleA
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.
Inputs: query (required), bodies, budget, symbols.
dep_graphDependency graph queryA
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.
Inputs: mode (required), root, depth, scope, +1 more.
digest_getRead the repo architecture digestA
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.
Inputs: no named parameters.
digest_saveSave the repo architecture digestAIdempotent
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.
Inputs: text (required), covers.
find_definitionFind where a symbol is definedA
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.
Inputs: name (required), kind, limit, offset, +1 more.
find_referencesFind references to a symbol (textual)A
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.
Inputs: name (required), limit, offset, pathPrefix.
find_testsWhich tests exercise a symbolA
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.
Inputs: name (required), limit, pathPrefix.
get_contextOne-shot context brief for a symbolA
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.
Inputs: name (required), include, maxChars, callerLimit.
get_file_skeletonFile skeleton (bodies elided)A
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.
Inputs: path (required).
get_symbol_contextSurgical symbol snippet(s)A
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.
Inputs: line, name, path, after, +4 more.
index_repoIndex / refresh the repositoryAIdempotent
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 /.slimdex.json (ignoreDirs/extensions/exclude/maxFileBytes) and reports config problems instead of ignoring them.
Inputs: force.
install_hookInstall the PreToolUse hookADestructive
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.
Inputs: scope, uninstall.
memory_deleteDelete a memory factADestructiveIdempotent
Remove one saved memory fact by its id. Permanent — no undo, and no snapshot is taken.
Inputs: id (required).
memory_getRead saved facts in fullA
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.
Inputs: ids (required).
memory_listList memoryA
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.
Inputs: full, limit.
memory_savePersist a memory factA
Save a durable note (decision, gotcha, TODO, location) to /.slimdex/memory.json.
Inputs: text (required), tags.
memory_searchSearch saved memoryA
Find saved memory facts by substring and/or tag. Previews by default; memory_get expands one by id.
Inputs: tag, full, query.
outline_fileOutline a file (signatures only)A
Compact outline of one file — declarations with line numbers, not the body. Orient before reading.
Inputs: path (required).
read_linesRead a line rangeA
Read only lines [start..end] (1-indexed, inclusive) of a file. Cheaper than the whole file.
Inputs: end (required), path (required), start (required).
recapWhat previous sessions did (automatic)A
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.
Inputs: limit.
replace_symbolReplace a symbol's body by name (write)ADestructiveIdempotent
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.
Inputs: body, line, name, path, +4 more.
repo_mapHigh-level repo mapA
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.
Inputs: top, path, depth.
search_codeCompact code searchA
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.
Inputs: pattern (required), limit, regex, cursor, +4 more.
search_intentFind code by intent (BM25, no embeddings)A
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.
Inputs: query (required), limit.
search_symbolsFuzzy symbol name searchA
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.
Inputs: query (required), kind, limit, pathPrefix.
snapshotSnapshot uncommitted workA
Copy every uncommitted file into .slimdex/snapshots// 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.
Inputs: no named parameters.
statsTool usage and response-size accountingA
Per-tool call counts and response sizes recorded to /.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.
Inputs: reset, session, checkpoint.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Several tools overlap in purpose: outline_file and get_file_skeleton both summarize a file's declarations, get_context with include:body overlaps get_symbol_context, and find_definition vs search_symbols both locate a symbol by name, while search_code vs find_references are both textual searches. However, the unusually detailed descriptions contain explicit routing guidance ('for symbols prefer find_definition/find_references', 'drop to get_symbol_context') that makes correct selection likely in most cases.
The dominant verb_noun snake_case convention is well-established and organized into clear subfamilies: get_*, find_*, search_*, memory_*, plus index_repo, read_lines, outline_file, replace_symbol, install_hook. Minor deviations exist: digest_get/digest_save invert the verb_noun order, one-word names (snapshot, recap, brief, stats, batch) break the pattern, and repo_map/dep_graph/context_pack are noun_noun compounds.
Thirty tools is on the heavy side, and the memory/persistence cluster alone consumes nine identifiers (memory_* x5, digest_* x2, brief, recap) while outline_file is largely redundant with get_file_skeleton. The broad scope (indexing, search, reading, editing, memory, stats, hooks) justifies most of the surface, but a trimmed design around 20-24 tools would be tighter.
The core workflow is fully covered: orient (brief, repo_map, digest_get), discover (search_code, search_symbols, search_intent, context_pack), read cheaply (read_lines, get_file_skeleton, get_symbol_context), edit safely (replace_symbol with snapshot and re-index), and remember (full memory CRUD). Minor gaps include no symbol delete/rename primitive and no general whole-file write tool, though replace_symbol is explicitly designed to complement ordinary client-side edit tools.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
FixMyPrompt is a remote MCP server for coding agents. It saves the steps your agent worked out as project memories and fetches them in later sessions, scores and rewrites prompts, and checks CLAUDE.md and AGENTS.md files. Works with Claude Code, Codex and Cursor. Free plan available.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for semantic code search & navigation that helps AI agents work efficiently without burning through costly tokens. Instead of reading entire files, agents can search conceptually and jump directly to the specific functions, classes, and code chunks they need.122MIT
- AlicenseBqualityDmaintenanceA local-first MCP server that provides AI agents with safe codebase access through file discovery, hybrid lexical-semantic search, and project introspection. It features durable local memory and semantic indexing while keeping all data and processing entirely on your local machine.7427 npm6MIT
- AlicenseNot gradedqualityBmaintenanceLocal-first code intelligence MCP server that enables coding agents to search code, inspect structure, read exact ranges, and explore Git history with explicit token budgets.171Apache 2.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server that lets coding agents read individual functions, classes and symbols from source files instead of loading whole files, cutting the tokens spent reading code by 85-95% on large files. It provides outlining, exact symbol reads, and project-wide symbol definition and reference lookups across many programming languages, running entirely locally with no index.MIT