SDL-MCP: a symbol-graph context budget layer for coding agents
Symbol Delta Ledger (SDL-MCP) is a policy-centered context budget layer for coding agents: Symbol-graph intelligence combined with precision tools. It turns sprawling codebases into compact, high-signal context that saves tokens, speeds up workflows, and improves agent output.
At a glance
- What is it?
- Symbol Delta Ledger indexes a repository into a symbol graph and exposes it over MCP, so agents can escalate from compact cards to bounded source windows instead of reading whole files. It is an infrastructure choice, and the documentation leaves several operational questions open.
- Who is it for?
- SDL-MCP fits teams already running an MCP-capable coding agent on a Node.js 24 codebase, who want retrieval constrained by symbol relationships and a source-window policy rather than by directory layout. It is the wrong tool for a small repository that fits in a single file read, for a team that cannot run a local indexing process, or for anyone who needs a clear licence answer before shipping.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The token problem SDL-MCP is built around
The default way an agent explores a repository is to open files. A question about one function pulls in its module, its imports, and whatever the agent guesses is adjacent. The README frames the alternative as working from symbols: index the repository into a symbol graph, then let the agent start from compact metadata and request code only when it needs code. The stated goal is a smaller, more deliberate context surface for debugging, reviews, implementation work, and repository exploration.
The intended user is not a person browsing a codebase. It is a coding agent connected over the Model Context Protocol, with SDL-MCP running locally and mediating what the agent is allowed to see. The README describes the server as supporting MCP over stdio or HTTP. If your workflow does not involve an MCP client, most of what the project provides has no consumer.
The Iris Gate Ladder and how retrieval escalates
The mechanism the README names is the Iris Gate Ladder. It defines four rungs: cards, skeletons, hot paths, and policy-gated source windows. Each rung is a richer view than the last, and the agent is expected to ask for the least code that can answer its question. Cards come first. Every indexed symbol gets a compact card holding identity, signature, summary, relationships, and retrieval metadata, which is enough to decide whether a symbol is worth opening.
Graph slicing sits beside the ladder. It follows repository relationships rather than directory boundaries, so a task or a starting symbol returns a budgeted subgraph that can be refreshed or expanded through spillover. That distinction matters in practice: a symbol's neighbours in the graph are often in different directories, and directory-based context selection will miss them.
Indexing itself is layered. Tree-sitter supplies repository structure. Where a compiler or language provider is available, SDL-MCP can ingest SCIP and language-provider facts through provider-first indexing, which adds precise cross-references for covered files and falls back to the regular path for files the provider does not cover. The README does not state which languages have provider coverage, so the precision gain is conditional on your stack.
Tool surfaces: flat, gateway, and code mode
SDL-MCP registers a different number of tools depending on the mode, and the README points to docs/generated/tool-inventory.md as the source of truth. Flat mode registers 38 tools: 2 universal plus 36 flat tools. Gateway mode registers 6: 2 universal plus 4 gateway namespaces, named sdl.agent, sdl.code, sdl.query, and sdl.repo. Gateway with legacy registers 42, combining the gateway namespaces and the flat tools. Code Mode exclusive registers 7 tools: sdl.action.search, sdl.context, sdl.file, sdl.info, sdl.manual, sdl.retrieve, and sdl.workflow.
The README's own guidance is that gateway mode suits clients that benefit from fewer tool choices, while the flat surface suits clients where direct tool names are more useful. That is a real trade-off and the project does not pretend otherwise. Fewer registered tools reduce the chance the agent picks the wrong one; more registered tools make each action directly addressable. Gateway mode preserves server-side validation and routing, so the reduction is in the visible surface, not in what the server can do. Code Mode is the most opinionated option and reads as a task-oriented interface rather than an action catalogue.
Getting it running: init, doctor, serve
Node.js 24 or later is required. The README gives two install paths. For an interactive first install, run the wrapper package from the repository you want to index:
npx create-sdl-mcp
For a global install, the sequence is install, initialize, verify, serve:
npm install -g sdl-mcp cd <repository> sdl-mcp init sdl-mcp doctor sdl-mcp serve --stdio
For non-interactive setup the README gives sdl-mcp init -y --auto-index. The doctor step is worth treating as a gate rather than a formality, because an index that failed partway through will still let the server start and will still answer queries, just from an incomplete graph. The README points to docs/getting-started.md for the setup wizard, supported clients, HTTP transport, and configuration examples, and to docs/mcp-tools-reference.md for request and response shapes on whichever surface you installed. Policy settings govern raw source windows, and the runtime execution surface applies configured executable, working-directory, environment, concurrency, and timeout controls. The README does not enumerate the config keys for those settings in the material available here, so treat the deep-dive documents as required reading before you expose the HTTP transport.
Change analysis, live indexing, and what they cost you
Two features go beyond static retrieval. Delta packs compare indexed versions, identify changed symbols, and trace affected relationships; sdl.pr.risk.analyze packages change evidence and test recommendations for pull-request review. Live indexing is the more unusual one. Draft-buffer updates can appear in a live overlay before the file is saved. When a save is accepted, targeted reconciliation is queued, configured SCIP, LSP, or parser preparation runs in the background, and only the latest saved generation is published. Retrieval continues from the committed graph and, when present, the overlay while that work prepares.
That design has a visible cost. There are two sources of truth during editing, and the README is explicit that the overlay is separate from the committed graph. An agent that reads a symbol mid-edit can see the draft version, and the guarantee is only that the latest saved generation is eventually published. The README does not describe how conflicts between the overlay and an incoming commit are resolved, so if your team edits and commits concurrently, that is a question to answer before relying on live indexing.
Development memories are opt-in. When enabled, they store decisions and task notes with repository links so later work can retrieve them alongside relevant context. The README directs you to docs/memory-protocol.md for behaviour and storage rules. Opt-in is the right default here, because persisted task notes are a second data store with its own lifecycle.
Where SDL-MCP is the wrong tool
The indexing step is the boundary. A repository small enough that a single file read answers the question gains nothing from a symbol graph, and pays the cost of running an indexer and an MCP server. The same applies to one-off scripts and to work in a language where tree-sitter parsing is the only available path and provider facts are absent, since the precision advantage of provider-first indexing does not apply there.
Node.js 24 or later is a hard floor, and it is a recent runtime. Teams pinned to an older LTS line cannot run this at all. The project also runs locally by design, which means every developer or agent host needs its own index; the README does not describe a shared index service. And the licence is unresolved in the metadata: the repository reports NOASSERTION, so there is no stated licence identifier to evaluate. That is not a legal opinion, it is an observation that you cannot determine your obligations from what is published, and for a dependency you install globally and run against proprietary source, that gap should be closed before adoption rather than after.
How this differs from a plain vector search index
The obvious alternative is a vector-search index over code chunks: embed the repository, retrieve by similarity to the query, hand the top matches to the agent. SDL-MCP does include vector-search and vector-database among its topics, so similarity retrieval is presumably part of the stack, but the retrieval model described in the README is not similarity-first. It is symbol-first and relationship-first, with an explicit ladder of views and a budget on the subgraph returned.
The practical difference is what the agent receives. A vector index returns chunks that resemble the question. A symbol graph returns a symbol, its signature, its relationships, and a bounded window of its source, which is a different shape of answer and a different failure mode. Similarity retrieval can surface a plausible-looking chunk from an unrelated module; relationship traversal can surface a correct symbol that the agent did not think to ask about. Neither is strictly better, and the README does not present benchmarks comparing the two. If you already have a chunk-based retrieval pipeline that your team understands, replacing it means replacing your mental model of why the agent sees what it sees.
Maintenance, upgrade cost, and the licence question
The release cadence visible in the supplied material is tight: v0.13.5 on 2026-08-26, v0.13.6 on 2026-08-30, v0.13.7 on 2026-09-07, with the last push to main on 2026-09-09. A 0.x version line moving that quickly means the tool inventory and the MCP tool reference are the documents most likely to drift from the installed build, which is exactly why the README points at docs/generated/tool-inventory.md as the source of truth rather than restating counts in prose.
Upgrade cost concentrates in two places. Tool surface changes alter what the agent can call, and a mode switch between flat, gateway, and Code Mode is a configuration change with behavioural consequences, not a cosmetic one. Policy and runtime execution settings govern raw source windows and process execution, so a change there affects what the agent is permitted to do, not just what it sees. Pin a version, and read the release notes for the version you are moving to.
The licence is the unresolved item. The repository metadata reports NOASSERTION, which means no licence identifier was asserted. The README does not state a licence either. Until that is clarified, treat SDL-MCP as a dependency whose terms you cannot confirm, and do not assume the permissive default that npm packages often carry.
Editorial conclusion
SDL-MCP fits teams already running an MCP-capable coding agent on a Node.js 24 codebase, who want retrieval constrained by symbol relationships and a source-window policy rather than by directory layout. It is the wrong tool for a small repository that fits in a single file read, for a team that cannot run a local indexing process, or for anyone who needs a clear licence answer before shipping. Before adopting, run sdl-mcp init and sdl-mcp doctor on a throwaway clone, read docs/memory-protocol.md if you plan to enable memories, and confirm the actual licence text, because the repository metadata reports NOASSERTION.
Community notes