# SDL-MCP: a symbol-graph context budget layer for coding agents > GlitterKill/sdl-mcp indexes a repository into a symbol graph and hands agents a controlled path from compact cards to bounded source windows. Here is how it installs, how the retrieval loop works, and where it stops being the right tool. **GlitterKill/sdl-mcp** — 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. - Repository: https://github.com/GlitterKill/sdl-mcp - Stars: 489 · Forks: 31 - Language: TypeScript - License: NOASSERTION - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/glitterkill-sdl-mcp ## The problem sdl-mcp targets: agents that read files instead of symbols A coding agent asked to fix one function usually starts by reading whole files. On a small repository that is fine. On a polyglot monorepo it burns the context window on imports, license headers and unrelated helpers before the model reaches the two lines that matter. SDL-MCP, short for Symbol Delta Ledger, takes the position that the unit of retrieval should be a symbol rather than a file. The README describes it as a "policy-centered context budget layer for coding agents" and frames the goal as turning sprawling codebases into compact, high-signal context. The intended audience is narrow and specific. It is for people running an MCP-capable coding agent against a repository big enough that file-level reads are expensive, and who want the retrieval step to be inspectable rather than implicit. It is not a linter, not a language server, and not a replacement for reading code. It is the layer that decides which code the agent gets to see, and in what order. ## How the symbol graph, cards and the Iris Gate Ladder fit together The mechanism has four stages. First, indexing: SDL-MCP walks the repository and produces symbols, relationships and compact metadata. Second, symbol cards. According to the README, every indexed symbol gets a card carrying its identity, signature, summary, relationships and other retrieval metadata, so an agent has somewhere to start without opening a file. Third, graph slicing, which follows repository relationships instead of directory boundaries and returns a budgeted subgraph for a given task or starting symbol. Fourth, escalation, which the README calls the Iris Gate Ladder: cards, then skeletons, then hot paths, then policy-gated source windows. The agent is expected to ask for the least code that can answer its question and climb only when it needs more. Two details make this more than a thin wrapper over a code index. Parsing is done with tree-sitter for repository structure, and SCIP or language-provider facts can be ingested through what the project calls provider-first indexing, which adds precise cross-references where a provider covers a file and falls back to the regular path where it does not. The second detail is delta work: SDL-MCP can compare indexed versions, identify changed symbols and trace affected relationships, with sdl.pr.risk.analyze packaging change evidence and test recommendations for pull-request review. Live indexing is the subtler piece. Draft-buffer updates can appear in a live overlay before the file is saved, an accepted save queues targeted reconciliation, and retrieval continues from the committed graph plus the overlay while background preparation runs. That is a real design commitment, not a marketing line: it means the agent can see unsaved work without the index committing to it. ## Installing sdl-mcp and running a first index The README states that SDL-MCP requires Node.js 24 or later. For an interactive first install, it points at a wrapper package run from the repository you want to index: ```bash npx create-sdl-mcp ``` That command starts the setup wizard described in the Getting Started guide. For a standard global install the README gives a four-step sequence: install the package, change into the repository, initialize it, verify the setup, then start the stdio server. ```bash npm install -g sdl-mcp cd sdl-mcp init sdl-mcp doctor sdl-mcp serve --stdio ``` sdl-mcp init writes the repository-level configuration and builds the initial index; sdl-mcp doctor is the verification step, and it is the one to run first when something looks wrong. The README also documents a non-interactive path, sdl-mcp init -y --auto-index, for scripted setup. sdl-mcp serve --stdio starts the server on standard input and output, which is the transport most MCP clients expect. The README notes that HTTP transport is covered in the Getting Started guide rather than in the main body, so if your client speaks HTTP you should read that page before assuming the stdio flags carry over. One thing worth knowing before you run any of this: the package declares a postinstall script, and the published file list includes postinstall-watchman.mjs, postinstall-tree-sitter.mjs, postinstall-prune.mjs and postinstall-models.mjs. A global install therefore does more than copy JavaScript into place. If your environment blocks lifecycle scripts, plan for that. ## Choosing between flat, gateway and Code Mode tool surfaces SDL-MCP does not expose one tool list. The README's table gives four registered surfaces, and the generated tool inventory is named as the source of truth for counts. Flat mode registers 38 tools: 2 universal tools and 36 flat tools. Gateway mode registers 6: the same 2 universal tools plus 4 gateway namespaces, sdl.agent, sdl.code, sdl.query and sdl.repo. Gateway with legacy registers 42, combining both. Code Mode exclusive registers 7 tools: sdl.action.search, sdl.context, sdl.file, sdl.info, sdl.manual, sdl.retrieve and sdl.workflow. This is the most consequential configuration decision in the project, and it is easy to get wrong. Some MCP clients degrade when handed several dozen tool definitions; others are easier to drive when the tool names are explicit. Gateway mode keeps server-side validation and routing intact while shrinking what the model sees, which is the right default for a client with a small tool budget. The README's own guidance is to use gateway mode when a client benefits from fewer choices and the flat surface when direct tool names are more useful. Note that the README does not state a token cost for either surface, so the argument for gateway mode is about client behaviour, not a measured saving. ## Where sdl-mcp is the wrong tool The clearest limitation is structural. SDL-MCP runs locally and exposes the Model Context Protocol over stdio or HTTP, which means there is a server process, an index, and a configuration directory in the loop. For a one-off question about a single file, or for a repository small enough to paste into a prompt, that apparatus costs more than it returns. The README does not document a rollback path for a bad index, and it does not describe what happens when the index drifts from the working tree beyond the overlay behaviour for unsaved buffers. The licence is the second thing to check before you build on it. The repository carries a LICENSE file and a separate COMMERCIAL_LICENSE.md, and the package metadata reports the licence as NOASSERTION, meaning no standard SPDX identifier was detected. The README does not state which terms apply to which use. If you are deploying this inside a company, read both files rather than assuming an OSI licence. That is a factual gap in the project's own documentation, not a legal opinion. The third limitation is precision. Provider-first indexing adds accurate cross-references only where a SCIP or language provider actually covers the file. For languages with no provider wired up, the fallback path applies, and the graph is only as good as tree-sitter plus whatever relationships the indexer infers. On a repository dominated by such languages, the delta and blast-radius features will be correspondingly weaker. The README does not list which providers are configured out of the box; the docs directory is where that would live. ## How sdl-mcp differs from a general code-graph MCP server The obvious comparison is with a plain code-graph MCP server, the kind that indexes a repository and answers graph queries. The difference is where the budget sits. A general graph server tends to answer the question you asked: give me the callers of this function, and you get them. SDL-MCP treats retrieval as a graded ladder with a policy layer on top, so the answer to a broad question is deliberately incomplete, and the source window is gated by policy settings rather than returned on demand. Whether that is better depends on your agent. An agent that plans well will use the ladder and spend fewer tokens. An agent that needs the full body of a function to reason correctly will end up climbing the ladder anyway, and the extra round trips are pure overhead. The second difference is delta awareness. Comparing indexed versions and tracing affected relationships is a first-class feature here, with sdl.pr.risk.analyze as the packaged entry point for review work. A graph server that only answers structural queries has no equivalent, and you would be reconstructing the changed-symbol set yourself. ## Release cadence, upgrade cost and the licence question The last push to the repository was on 2026-09-09, and the most recent release listed is v0.13.7 on 2026-09-07, preceded by v0.13.6 on 2026-08-30 and v0.13.5 on 2026-08-26. Patch releases are landing roughly weekly, and the version number is still in the 0.x range. That combination is worth weighing: frequent small releases at 0.x usually mean the surface is still moving, and the four registered tool modes are exactly the kind of thing that shifts between minor versions. Pinning a version and reading the CHANGELOG before each bump is cheaper than discovering a renamed tool mid-task. Upgrade cost also includes the index. Rebuilding after a version change is the safe path, and the README's own flow puts sdl-mcp doctor between init and serve, which suggests it is intended as the post-upgrade check. On licence: LICENSE and COMMERCIAL_LICENSE.md both exist at the repository root, and the package metadata reports NOASSERTION. Confirm which one governs your use before shipping anything built on it. ## Conclusion Adopt sdl-mcp if you run a coding agent against a polyglot repository large enough that whole-file context is wasteful, and you are willing to keep Node.js 24 or later and a local index in the loop. Do not adopt it if you need a stable public API surface, a documented commercial licence today, or a tool that works without a local server process. Before committing, run sdl-mcp doctor on the repository you actually care about and read the generated tool inventory for the mode you plan to register, because the flat, gateway and Code Mode surfaces differ in what the client sees. ## FAQ ### Is SDL-MCP still being developed? The repository is not archived, and its last push was on 2026-09-09. The most recent release listed is v0.13.7 from 2026-09-07, following v0.13.6 and v0.13.5 in the same month. ### What does MCP stand for in software development? In this project MCP refers to the Model Context Protocol, which sdl-mcp implements over stdio or HTTP so coding agents can call its tools. The README states that SDL-MCP runs locally and supports MCP over both transports. ### What Node.js version does sdl-mcp require? The README states that SDL-MCP requires Node.js 24 or later. The package metadata and README badge both point at the same minimum. ### How do I install sdl-mcp for a repository? The README gives two paths: npx create-sdl-mcp from the repository you want to index, or a global npm install -g sdl-mcp followed by sdl-mcp init, sdl-mcp doctor and sdl-mcp serve --stdio. A non-interactive setup is available as sdl-mcp init -y --auto-index. ### What is the difference between flat mode and gateway mode in sdl-mcp? Flat mode registers 38 tools (2 universal plus 36 flat), while gateway mode registers 6 tools (2 universal plus the sdl.agent, sdl.code, sdl.query and sdl.repo namespaces). The README suggests gateway mode when a client benefits from fewer tool choices and the flat surface when direct tool names are more useful. ### What licence does sdl-mcp use? The repository contains both a LICENSE file and a COMMERCIAL_LICENSE.md, and the package metadata reports the licence as NOASSERTION. The README does not explain which terms apply to which use. ## Sources - [GlitterKill/sdl-mcp on GitHub](https://github.com/GlitterKill/sdl-mcp) - [Issues](https://github.com/GlitterKill/sdl-mcp/issues) - [README](https://github.com/GlitterKill/sdl-mcp/blob/main/README.md) - [Releases](https://github.com/GlitterKill/sdl-mcp/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/glitterkill-sdl-mcp