{"id":44917019,"url":"https://github.com/glitterkill/sdl-mcp","last_synced_at":"2026-06-15T05:01:31.522Z","repository":{"id":337304880,"uuid":"1153052331","full_name":"GlitterKill/sdl-mcp","owner":"GlitterKill","description":"Symbol Delta Ledger (SDL-MCP) gives coding agents the right code context, not your entire repo. It turns sprawling codebases into compact, high-signal context that saves tokens, speeds up workflows, and improves agent output.","archived":false,"fork":false,"pushed_at":"2026-06-07T16:36:53.000Z","size":19621,"stargazers_count":329,"open_issues_count":3,"forks_count":21,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-07T17:10:56.850Z","etag":null,"topics":["agent-context","agent-tools","agentic-coding","agentic-engineering","agentic-workflow","code-analysis","code-context","code-graph","codegraph","coding-agent","context-engine","mcp","semantic-analysis","token-savings","tree-sitter","vector-database","vector-search","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GlitterKill.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T20:34:49.000Z","updated_at":"2026-06-07T16:36:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GlitterKill/sdl-mcp","commit_stats":null,"previous_names":["glitterkill/sdl-mcp"],"tags_count":44,"template":false,"template_full_name":null,"purl":"pkg:github/GlitterKill/sdl-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlitterKill%2Fsdl-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlitterKill%2Fsdl-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlitterKill%2Fsdl-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlitterKill%2Fsdl-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GlitterKill","download_url":"https://codeload.github.com/GlitterKill/sdl-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GlitterKill%2Fsdl-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34348292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-context","agent-tools","agentic-coding","agentic-engineering","agentic-workflow","code-analysis","code-context","code-graph","codegraph","coding-agent","context-engine","mcp","semantic-analysis","token-savings","tree-sitter","vector-database","vector-search","vibe-coding"],"created_at":"2026-02-18T02:11:03.720Z","updated_at":"2026-06-15T05:01:31.508Z","avatar_url":"https://github.com/GlitterKill.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://github.com/GlitterKill/sdl-mcp/blob/main/docs/SDL-MCP_promo.webp\" alt=\"Symbol Delta Ledger MCP\"\u003e\n\n\u003cbr/\u003e\n\n# SYMBOL DELTA LEDGER\n\n### **Cards-first code context for AI coding agents**\n\n_Stop feeding entire files into the context window.\u003cbr/\u003eStart giving agents exactly the code intelligence they need._\n\n\u003cbr/\u003e\n\n![npm version](https://img.shields.io/npm/v/sdl-mcp.svg?style=for-the-badge)\n![npm downloads](https://img.shields.io/npm/dm/sdl-mcp.svg?style=for-the-badge)\n![GitHub commit activity](https://img.shields.io/github/commit-activity/w/GlitterKill/sdl-mcp?style=for-the-badge)\u003cbr/\u003e\n[![RoastMyCode: A](https://roastmycode.ai/badge/GlitterKill/sdl-mcp)](https://roastmycode.ai/roast/latest/GlitterKill/sdl-mcp)\n\n\u003c/div\u003e\n\n---\n\n\u003cbr/\u003e\n\n## What's the problem?\n\nEvery time an AI coding agent reads a file to answer a question, it consumes thousands of tokens. Most of those tokens are irrelevant to the task. The agent doesn't need 500 lines of a file to know that `validateToken` takes a `string` and returns a `Promise\u003cUser\u003e` — but it reads them anyway, because that's all it has.\n\n**Multiply that across a debugging session touching 20 files and you've burned 40,000+ tokens on context gathering alone.**\n\nSDL-MCP fixes this. It indexes your codebase into a searchable **symbol graph** and serves precisely the right amount of context through a controlled escalation path. An agent that uses SDL-MCP understands your code better while consuming a fraction of the tokens.\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## How it works — in 30 seconds\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart TD\n    Codebase[\"Your Codebase\"]\n    Indexer[\"Indexer\u003cbr/\u003e12 languages\u003cbr/\u003eRust native or Tree-sitter fallback\"]\n    Graph[\"LadybugDB graph\u003cbr/\u003esymbols, edges, metrics, versions\"]\n    MCP[\"Current MCP surfaces\u003cbr/\u003e33 flat, 6 gateway, 4 Code Mode\"]\n    CLI[\"13 CLI commands\"]\n    HTTP[\"HTTP API and graph UI\"]\n    Agent[\"AI coding agent\u003cbr/\u003eClaude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini\"]\n\n    Codebase e1@--\u003e Indexer\n    Indexer e2@--\u003e Graph\n    Graph e3@--\u003e MCP\n    Graph e4@--\u003e CLI\n    Graph e5@--\u003e HTTP\n    MCP e6@--\u003e Agent\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5,e6 animate;\n```\n\n1. **Index once** — SDL-MCP parses every symbol in your repo and stores it as a compact metadata record (a \"Symbol Card\") in a graph database\n2. **Query efficiently** — Agents use MCP tools to search, slice, and retrieve exactly the context they need\n3. **Escalate only when necessary** — A four-rung ladder controls how much code the agent sees, from a 100-token card to full source (with justification required)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## Prerequisites\n\n- **Node.js 24+** is required ([download](https://nodejs.org/)). SDL-MCP uses Node.js features not available in earlier versions. Run `node -v` to check.\n\n\u003e **Peer dependency warnings during install?** The tree-sitter grammar packages may produce `ERESOLVE` warnings about peer dependencies. These are harmless — the install succeeds and everything works correctly. Add `--legacy-peer-deps` to suppress them: `npm install -g sdl-mcp --legacy-peer-deps`. SDL-MCP's postinstall also verifies tree-sitter grammar bindings and rebuilds missing ones before pruning sources; installs that use `--ignore-scripts` should run `npm rebuild tree-sitter tree-sitter-kotlin` if a grammar is unavailable.\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## Quick Start\n\n```bash\n# Install (requires Node.js 24+)\nnpm install -g sdl-mcp\n\n# Initialize, auto-detect languages, index your repo, and run health checks\nsdl-mcp init -y --auto-index\n\n# Start the MCP server for your coding agent\nsdl-mcp serve --stdio\n```\n\nPoint your MCP client at the server and the agent gains access to SDL-MCP's current configured surface. By default that is exclusive Code Mode; set `codeMode.exclusive: false` when you want Code Mode plus the regular flat or gateway tools in one session.\n\n\u003e **npx users:** Replace `sdl-mcp` with `npx --yes sdl-mcp@latest` in all commands above.\n\n[Full Getting Started Guide →](./docs/getting-started.md)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## The Iris Gate Ladder\n\nThe core innovation. Named after the adjustable aperture that controls light flow in optics, the Iris Gate Ladder lets agents dial their context \"aperture\" from a pinhole to wide-open.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart TB\n    R1[\"~100 tokens\u003cbr/\u003eRung 1: Symbol Card\u003cbr/\u003eName, signature, summary, dependencies, metrics\"]\n    R2[\"~300 tokens\u003cbr/\u003eRung 2: Skeleton IR\u003cbr/\u003eSignatures and control flow with bodies elided\"]\n    R3[\"~600 tokens\u003cbr/\u003eRung 3: Hot-Path Excerpt\u003cbr/\u003eIdentifier-focused lines with context\"]\n    R4[\"~2,000 tokens\u003cbr/\u003eRung 4: Raw Code Window\u003cbr/\u003ePolicy-gated full source\"]\n\n    R1 e1@--\u003e R2\n    R2 e2@--\u003e R3\n    R3 e3@--\u003e R4\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3 animate;\n```\n\n\u003e **Most questions are answered at Rungs 1-2** without ever reading raw code. That's where the token savings come from.\n\n| Scenario                             | Reading the file | Using the Ladder | Savings |\n| :----------------------------------- | :--------------: | :--------------: | :-----: |\n| \"What does `parseConfig` accept?\"    |    ~2,000 tok    |     ~100 tok     | **20x** |\n| \"Show me the shape of `AuthService`\" |    ~4,000 tok    |     ~300 tok     | **13x** |\n| \"Where is `this.cache` set?\"         |    ~2,000 tok    |     ~500 tok     | **4x**  |\n\n**Why it matters:**\n\n- **4–20x token savings** on typical code understanding queries\n- Most questions answered at Rungs 1–2 without ever reading raw code\n- Controlled escalation prevents agents from over-consuming context\n- Policy-gated raw access ensures agents prove they need full source\n\n[Iris Gate Ladder Deep Dive →](./docs/feature-deep-dives/iris-gate-ladder.md)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## Feature Tour\n\n### Symbol Cards — The Atoms of Understanding\n\nEvery function, class, interface, type, and variable becomes a **Symbol Card**: a compact metadata record (~100 tokens) containing everything an agent needs to _understand_ a symbol without reading its code.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart TB\n    Card[\"Symbol Card: validateToken\"]\n    Kind[\"Kind: function (exported)\"]\n    File[\"File: src/auth/jwt.ts:42-67\"]\n    Signature[\"Signature: (token: string, opts?: ValidateOpts) -\u003e Promise\u003cDecodedToken\u003e\"]\n    Summary[\"Summary: validates JWT signature and expiration\"]\n    Invariants[\"Invariants: throws on expired token\"]\n    SideEffects[\"Side effects: logs to audit trail\"]\n    Deps[\"Dependencies: verifySignature, checkExpiry, jsonwebtoken, AuditLogger\"]\n    Metrics[\"Metrics: fan-in 12, fan-out 4, churn 3/30d\"]\n    Context[\"Context: auth-module, request-pipeline, auth.test.ts\"]\n    ETag[\"ETag: a7f3c2...\"]\n\n    Card e1@--\u003e Kind\n    Kind e2@--\u003e File\n    File e3@--\u003e Signature\n    Signature e4@--\u003e Summary\n    Summary e5@--\u003e Invariants\n    Invariants e6@--\u003e SideEffects\n    SideEffects e7@--\u003e Deps\n    Deps e8@--\u003e Metrics\n    Metrics e9@--\u003e Context\n    Context e10@--\u003e ETag\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5,e6,e7,e8,e9,e10 animate;\n```\n\nCards include **confidence-scored call resolution** (the pass-2 resolver traces imports, aliases, barrel re-exports, and tagged templates to produce accurate dependency edges), **community detection** (cluster membership), and **call-chain tracing** (process participation with entry/intermediate/exit roles).\n\n**Why it matters:**\n\n- **~100 tokens per symbol** vs. ~2,000 tokens to read the full file\n- Confidence-scored dependency edges trace real call relationships across files\n- Community detection and call-chain tracing reveal architectural structure\n- ETag-based conditional requests avoid re-fetching unchanged symbols\n- Workflow ETag caching now seeds `slice.build` with `knownCardEtags` so repeated slice builds can skip unchanged cards\n\n[Indexing \u0026 Language Support Deep Dive →](./docs/feature-deep-dives/indexing-languages.md)\n\n---\n\n### Graph Slicing — The Right Context for Every Task\n\nInstead of reading files in the same directory, SDL-MCP follows the _dependency graph_. Starting from symbols relevant to your task, it traverses weighted edges (call: 1.0, config: 0.8, import: 0.6), scores each symbol by relevance, and returns the N most important within a token budget.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart TD\n    Task[\"Task: Fix the auth middleware\"] e1@--\u003e Slice[\"sdl.slice.build\"]\n    Slice e2@--\u003e Auth[\"authenticate\"]\n    Slice e3@--\u003e Validate[\"validateToken\"]\n    Slice e4@--\u003e Config[\"JwtConfig\"]\n    Auth e5@--\u003e Hash[\"hashPassword\"]\n    Validate e6@--\u003e User[\"getUserById\"]\n    Config e7@--\u003e Env[\"envLoader\"]\n    Env e8@-. frontier outside budget .-\u003e Frontier[\"spillover frontier\"]\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5,e6,e7,e8 animate;\n```\n\nSlices have handles, leases, refresh (delta-only updates), and spillover (paged overflow). You can also skip the symbol search entirely — pass a `taskText` string and SDL-MCP auto-discovers the relevant entry symbols.\n\n**Why it matters:**\n\n- Follows the **dependency graph**, not directory boundaries, for cross-cutting context\n- Weighted edge scoring (call \u003e config \u003e import) prioritizes the most relevant symbols\n- Token-budgeted: returns only what fits within your budget (~800 tokens vs. ~16,000 for raw files)\n- Natural-language task-text auto-discovers entry symbols — no symbol IDs needed\n\n[Graph Slicing Deep Dive →](./docs/feature-deep-dives/graph-slicing.md)\n\n---\n\n### Delta Packs \u0026 Blast Radius — Semantic Change Intelligence\n\n`git diff` tells you what lines changed. SDL-MCP tells you what that change _means_ and who's affected.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart TD\n    Change[\"Modified validateToken() signature\"]\n    Sig[\"signatureDiff\u003cbr/\u003eadded options?: object\"]\n    Inv[\"invariantDiff\u003cbr/\u003eadded throws on expired\"]\n    Fx[\"sideEffectDiff\u003cbr/\u003eadded logs to audit trail\"]\n    Blast[\"Blast radius\"]\n    A1[\"authenticate()\u003cbr/\u003edistance 1\"]\n    A2[\"refreshSession()\u003cbr/\u003edistance 1\"]\n    A3[\"AuthMiddleware\u003cbr/\u003edistance 2\"]\n    A4[\"auth.test.ts\u003cbr/\u003ere-run recommended\"]\n\n    Change e1@--\u003e Sig\n    Change e2@--\u003e Inv\n    Change e3@--\u003e Fx\n    Sig e4@--\u003e Blast\n    Inv e5@--\u003e Blast\n    Fx e6@--\u003e Blast\n    Blast e7@--\u003e A1\n    Blast e8@--\u003e A2\n    Blast e9@--\u003e A3\n    Blast e10@--\u003e A4\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5,e6,e7,e8,e9,e10 animate;\n```\n\n**PR risk analysis** (`sdl.pr.risk.analyze`) wraps this into a scored assessment with findings, evidence, and test recommendations. **Fan-in trend analysis** detects \"amplifier\" symbols whose growing dependency count means changes ripple further over time.\n\n**Why it matters:**\n\n- Semantic diffs show what a change **means**, not just what lines moved\n- Ranked blast radius identifies which dependent symbols are most at risk\n- Fan-in trend analysis detects \"amplifier\" symbols whose changes ripple further over time\n- PR risk scoring produces actionable findings with test re-run recommendations\n\n[Delta \u0026 Blast Radius Deep Dive →](./docs/feature-deep-dives/delta-blast-radius.md)\n\n---\n\n### Live Indexing — Real-Time Code Intelligence\n\nSDL-MCP doesn't wait for you to save. As you type in your editor, buffer updates are pushed to an in-memory overlay store, parsed in the background, and merged with the durable database. Search, cards, and slices reflect your _current_ code, not your last save.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart LR\n    Editor[\"Editor keystrokes\"] e1@--\u003e Push[\"sdl.buffer.push\"]\n    Push e2@--\u003e Overlay[\"Overlay store\"]\n    Overlay e3@--\u003e Reads[\"Merged reads\u003cbr/\u003esearch, cards, slices\"]\n    Overlay e4@--\u003e Persist[\"save / idle checkpoint\"]\n    Persist e5@--\u003e DB[\"LadybugDB durable graph\"]\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5 animate;\n```\n\n**Why it matters:**\n\n- Search, cards, and slices reflect **unsaved editor changes** in real time\n- No manual re-index needed during active development\n- Background AST parsing with in-memory overlay keeps queries fast\n\n[Live Indexing Deep Dive →](./docs/feature-deep-dives/live-indexing.md)\n\n---\n\n### Governance \u0026 Policy — Controlled Access\n\nRaw code access (Rung 4) is **policy-gated**. Agents must provide:\n\n- A **reason** explaining why they need raw code\n- **Identifiers** they expect to find in the code\n- An **expected line count** within configured limits\n\nRequests that don't meet policy are denied with actionable guidance (\"try `getHotPath` with these identifiers instead\"). Every access is audit-logged.\n\nThe sandboxed runtime execution tool (`sdl.runtime.execute`) has its own governance layer: enabled by default, but still guarded by executable allowlisting, CWD jailing, environment scrubbing, concurrency limits, and timeout enforcement. The `outputMode` parameter (`\"minimal\"` | `\"summary\"` | `\"intent\"`) defaults to `\"minimal\"` for ~95% token savings, with `sdl.runtime.queryOutput` enabling on-demand output retrieval when needed.\n\n**Why it matters:**\n\n- Proof-of-need gating prevents agents from wastefully reading raw code\n- Denied requests include **actionable next-best-action** guidance\n- Full audit logging of every code access decision\n- Sandboxed runtime with executable allowlisting, CWD jailing, and environment scrubbing\n\n[Governance \u0026 Policy Deep Dive →](./docs/feature-deep-dives/governance-policy.md)\n\n---\n\n### Agent Context — Task-Shaped Retrieval\n\n`sdl.context` is SDL-MCP's task-shaped context engine. Give it a task type (`debug`, `review`, `implement`, `explain`), a description, and a budget — it selects the right Iris Gate rungs, collects evidence, and returns context tuned to the job. In Code Mode, `sdl.context` provides the same retrieval surface without dropping into `sdl.workflow`.\n\nUnscoped natural-language context calls use confidence-gated hybrid retrieval by default. Exact symbol mentions and explicit `focusPaths` / `focusSymbols` stay on the fast path; low-confidence lexical results can escalate to bounded FTS + vector retrieval. Set `options.semantic: true` to force hybrid retrieval, or `options.semantic: false` to keep lexical-only behavior for deterministic debugging.\n\nThe feedback loop (`sdl.agent.feedback`) records which symbols were useful and which were missing, improving future slice quality.\n\nFor portable exports such as tickets and PR descriptions, use the CLI `sdl-mcp summary` command. It generates token-bounded context briefings in markdown, JSON, or clipboard format for use outside MCP environments.\n\n**Why it matters:**\n\n- Task-shaped context retrieval plans the **right Iris Gate path** within a token budget\n- Confidence-gated hybrid retrieval improves discovery without slowing known-target lookups\n- Feedback loop records what was useful/missing, improving future slice quality\n- Portable context summaries export findings for use outside MCP environments\n\n[Agent Context Deep Dive →](./docs/feature-deep-dives/agent-context.md) · [Context Modes →](./docs/feature-deep-dives/context-modes.md)\n\n---\n\n### Sandboxed Runtime Execution\n\nRun tests, linters, and scripts through SDL-MCP's governance layer instead of uncontrolled shell access. 16 runtimes (Node.js, Python, Go, Java, Rust, Shell, and more), code-mode or args-mode, smart output summarization with keyword-matched excerpts, and gzip artifact persistence.\n\n**Why it matters:**\n\n- Run tests, linters, and scripts **under governance** instead of uncontrolled shell access\n- 16 runtimes supported (Node, Python, Go, Java, Rust, Shell, and more)\n- Executable allowlisting, CWD jailing, timeout enforcement, and environment scrubbing\n- Smart output summarization with keyword-matched excerpts and gzip artifact persistence\n\n[Runtime Execution Deep Dive →](./docs/feature-deep-dives/runtime-execution.md)\n\n---\n\n### Development Memories — Cross-Session Knowledge Persistence (Opt-In)\n\nAgents forget everything between sessions. SDL-MCP fixes this with an **opt-in graph-backed memory system** that lets agents store decisions, bugfix context, and task notes linked directly to the symbols and files they relate to. Memory is **disabled by default** and must be explicitly enabled in the configuration. When enabled, memories are stored both in the graph database (for fast querying) and as checked-in markdown files (for version control and team sharing).\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart LR\n    Session1[\"Agent session 1\u003cbr/\u003erecords bugfix memory\"] e1@--\u003e Store[\"sdl.memory.store\"]\n    Store e2@--\u003e Graph[\"LadybugDB memory node\"]\n    Store e3@--\u003e Files[\".sdl-memory/bugfixes/\u003cid\u003e.md\"]\n    Graph e4@--\u003e Link1[\"MEMORY_OF -\u003e authenticate()\"]\n    Graph e5@--\u003e Link2[\"HAS_MEMORY -\u003e repo\"]\n    Session2[\"Agent session 2\"] e6@--\u003e Surface[\"sdl.memory.surface\"]\n    Surface e7@--\u003e Graph\n    Graph e8@--\u003e Recall[\"Relevant memory surfaced\u003cbr/\u003erace condition fix in authenticate()\"]\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5,e6,e7,e8 animate;\n```\n\nWhen enabled, memories are **automatically surfaced** inside graph slices — when an agent builds a slice touching symbols with linked memories, those memories appear alongside the cards. During re-indexing, memories linked to changed symbols are **flagged as stale**, prompting agents to review and update them. Four MCP tools (`store`, `query`, `remove`, `surface`) provide full CRUD plus intelligent ranking by confidence, recency, and symbol overlap. Memory tools are only available when memory is enabled in the configuration.\n\n**Why it matters:**\n\n- Structured knowledge **persists across sessions**, linked directly to symbols and files\n- Opt-in and disabled by default — enable via `\"memory\": { \"enabled\": true }` in config\n- When enabled, automatically surfaced inside graph slices when touching related symbols\n- Stale memories flagged when linked symbols change during re-indexing\n- Dual storage: graph DB for fast querying + markdown files for version control and team sharing\n\n[Development Memories Deep Dive →](./docs/feature-deep-dives/development-memories.md)\n\n---\n\n### SCIP Integration — Compiler-Grade Cross-References\n\nTree-sitter gives SDL-MCP fast, syntax-level symbol extraction across the supported TypeScript/JavaScript, Python, Go, Java, C#, C/C++, PHP, Rust, Kotlin, and Shell surface. SCIP (Source Code Intelligence Protocol) supplements this with **compiler-grade cross-references** from tools like scip-typescript, scip-go, and rust-analyzer. Generate a `.scip` index file, point SDL-MCP at it, and heuristic edges are upgraded to exact compiler-verified edges, external dependency symbols become first-class graph nodes, and new `implements` edges reveal interface/trait relationships that syntax analysis cannot discover.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart LR\n    Compiler[\"Compiler / Type Checker\"] e1@--\u003e SCIP[\".scip index file\"]\n    SCIP e2@--\u003e Ingest[\"sdl.scip.ingest\"]\n    Ingest e3@--\u003e Upgrade[\"Heuristic edges → exact edges\"]\n    Ingest e4@--\u003e External[\"External dependency nodes\"]\n    Ingest e5@--\u003e Implements[\"implements edges\"]\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5 animate;\n```\n\n**Why it matters:**\n\n- Upgrades heuristic call resolution to **compiler-verified exact edges** (confidence 0.95)\n- External dependencies (npm packages, Go modules, crate deps) become searchable graph nodes\n- Interface/trait implementations tracked via `implements` edges\n- Auto-ingest on `sdl.index.refresh` keeps SCIP data current with zero manual steps\n- Complementary: tree-sitter provides structure, SCIP provides semantic precision\n\n[SCIP Integration Deep Dive →](./docs/feature-deep-dives/scip-integration.md)\n\n---\n\n### CLI Tool Access — No MCP Server Required\n\nAccess SDL-MCP direct action aliases plus the low-risk `action.search` and `manual` metadata proxies from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK is required.\n\n```bash\n# Search for symbols\nsdl-mcp tool symbol.search --query \"handleAuth\" --output-format pretty\n\n# Build a task-scoped slice\nsdl-mcp tool slice.build --task-text \"debug auth flow\" --max-cards 50\n\n# Pipe JSON args, chain commands\necho '{\"repoId\":\"my-repo\"}' | sdl-mcp tool symbol.search --query \"auth\"\n\n# Apply a single-file targeted write\nsdl-mcp tool file.write --repo-id my-repo --file-path config/app.json \\\n  --json-path server.port --json-value 8080\n\n# Discover and inspect metadata without opening the graph DB\nsdl-mcp tool action.search --query manual --summary-only\nsdl-mcp tool manual --actions action.search --format json\n```\n\nFeatures include typed argument coercion (string, number, boolean, string[], json), budget flag merging, stdin JSON piping with CLI flag precedence, auto-resolved `repoId` from cwd for graph actions, four output formats (json, json-compact, pretty, table), typo suggestions, and per-action `--help`. Direct graph actions dispatch through the same gateway router and Zod schemas as the MCP server; `action.search` and `manual` run in process against the same metadata handlers used by MCP registration.\n\n**Why it matters:**\n\n- 36 direct graph/action aliases plus `action.search` and `manual` metadata proxies accessible from **any terminal** - no server, transport, or SDK required\n- Direct graph actions keep gateway-router/Zod parity; metadata proxies share the same MCP registration handlers\n- Four output formats (json, json-compact, pretty, table) for scripting and CI pipelines\n- Auto-resolves repoId from cwd, supports stdin JSON piping and per-action `--help`\n\n[CLI Tool Access Deep Dive →](./docs/feature-deep-dives/cli-tool-access.md)\n\n---\n\n### Tool Gateway — Compact Tool Registration\n\nThe tool gateway projects the 35 gateway-routable SDL actions into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from the full flat schema surface to a compact gateway surface.\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart LR\n    Before[\"Flat mode\u003cbr/\u003e38 tools\u003cbr/\u003e2 universal + 36 flat\"] e1@--\u003e After[\"Gateway mode\u003cbr/\u003e6 tools\u003cbr/\u003e2 universal + 4 gateway\"]\n    After e2@--\u003e Savings[\"Smaller tools/list payload\u003cbr/\u003elower agent startup overhead\"]\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2 animate;\n```\n\nEach gateway tool accepts an `action` discriminator field (e.g., `{ action: \"symbol.search\", repoId: \"x\", query: \"auth\" }`) and routes to the same handlers with double Zod validation. Thin wire schemas in `tools/list` keep the registration compact while full validation happens server-side. The flat-only `sdl.file.write` action remains outside gateway mode today.\n\n**Why it matters:**\n\n- Large reduction in `tools/list` overhead for gateway-first agents\n- 35 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection\n- Fewer tool choices means faster and more accurate tool dispatch by the agent\n- Choose Code Mode for task-shaped retrieval first; opt out of exclusive Code Mode when you also need regular flat or gateway tools\n\n[Tool Gateway Deep Dive →](./docs/feature-deep-dives/tool-gateway.md)\n\n---\n\n### Observability Dashboard\n\nBuilt-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP behaviour without parsing stderr logs. GlitterKill dark UI at `/ui/observability` on the HTTP transport or the loopback-only `sdl-mcp serve --stdio --dashboard-port \u003cport\u003e` sidecar, plus REST + SSE APIs (`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`) for programmatic access. Surfaces cache hit rates, predictive-context outcome learning, hybrid-retrieval breakdowns (FTS / vector / PPR / RRF), beam-search decision traces, indexing pipeline metrics, write-pool and drain saturation, packed-wire token efficiency, and runtime CPU/memory/event-loop probes. See [Observability Dashboard Deep Dive](./docs/feature-deep-dives/observability-dashboard.md).\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## Current Tool Surface at a Glance\n\n| Mode                | Tool count | Composition                                                      |\n| :------------------ | :--------- | :--------------------------------------------------------------- |\n| Flat                | `38`       | `2` universal + `36` flat tools                                  |\n| Gateway             | `6`        | `2` universal + `4` gateway tools                                |\n| Gateway + legacy    | `42`       | `2` universal + `4` gateway + `36` flat tools                    |\n| Code Mode exclusive | `5`        | `sdl.action.search`, `sdl.context`, `sdl.file`, `sdl.manual`, `sdl.workflow` |\n\nThe generated source of truth is [`docs/generated/tool-inventory.md`](./docs/generated/tool-inventory.md).\n\n\u003ctable\u003e\n\u003ctr\u003e\u003cth\u003eCategory\u003c/th\u003e\u003cth\u003eTool\u003c/th\u003e\u003cth\u003eOne-Line Description\u003c/th\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd rowspan=\"4\"\u003e\u003cstrong\u003eRepository\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.repo.register\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eRegister a codebase for indexing\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.repo.status\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eHealth, versions, watcher, prefetch, live-index stats\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.repo.overview\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eCodebase summary: stats, directories, hotspots, clusters, with conditional ETag fetch support\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.index.refresh\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eTrigger full or incremental re-indexing\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"3\"\u003e\u003cstrong\u003eLive Buffer\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.buffer.push\u003c/code\u003e\u003c/td\u003e\u003ctd\u003ePush unsaved editor content for real-time indexing\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.buffer.checkpoint\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eForce-write pending buffers to the durable database\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.buffer.status\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eLive indexing diagnostics and queue depth\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"3\"\u003e\u003cstrong\u003eSymbols\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.symbol.search\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSearch symbols by name (with optional semantic reranking)\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.symbol.getCard\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eGet one card or batch-fetch up to 100 cards with ETag-based conditional support\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.symbol.edit\u003c/code\u003e\u003c/td\u003e\u003ctd\u003ePreview/apply one symbol-scoped edit with AST, range, file, and draft preconditions\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"3\"\u003e\u003cstrong\u003eSlices\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.slice.build\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eBuild a task-scoped dependency subgraph\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.slice.refresh\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eDelta-only update of an existing slice\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.slice.spillover.get\u003c/code\u003e\u003c/td\u003e\u003ctd\u003ePage through overflow symbols beyond the budget\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"3\"\u003e\u003cstrong\u003eCode Access\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.code.getSkeleton\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSignatures + control flow, bodies elided, with conditional ETag fetch support\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.code.getHotPath\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eLines matching specific identifiers + context, with conditional ETag fetch support\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.code.needWindow\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eFull source code (policy-gated, requires justification)\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd\u003e\u003cstrong\u003eDeltas\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.delta.get\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSemantic diff + blast radius between versions\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"2\"\u003e\u003cstrong\u003ePolicy\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.policy.get\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eRead current gating policy\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.policy.set\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eUpdate line/token limits and identifier requirements\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd\u003e\u003cstrong\u003eRisk\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.pr.risk.analyze\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eScored PR risk with findings and test recommendations\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"2\"\u003e\u003cstrong\u003eAgent\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.agent.feedback\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eRecord which symbols were useful or missing\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.agent.feedback.query\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eQuery aggregated feedback statistics\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"2\"\u003e\u003cstrong\u003eRuntime\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.runtime.execute\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSandboxed subprocess execution with outputMode (minimal/summary/intent)\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.runtime.queryOutput\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eOn-demand retrieval and keyword search of stored output artifacts\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"4\"\u003e\u003cstrong\u003eMemory\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.memory.store\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eStore or update a development memory with symbol/file links\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.memory.query\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSearch memories by text, type, tags, or linked symbols\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.memory.remove\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSoft-delete a memory from graph and optionally from disk\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.memory.surface\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eAuto-surface relevant memories for a task context\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"3\"\u003e\u003cstrong\u003eCode Mode\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.context\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eCode Mode task-shaped context retrieval for explain/debug/review/implement work\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.workflow\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eMulti-step operations with budget tracking, ETag caching, and transforms\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.manual\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSelf-documentation — query usage guide, action schemas, output format reference\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd\u003e\u003cstrong\u003eSCIP\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.scip.ingest\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eIngest a pre-built SCIP index for compiler-grade cross-references (with dry-run support)\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"2\"\u003e\u003cstrong\u003eFile\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.file.read\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eRead non-indexed files (configs, docs, templates) with line-range, search, or JSON-path modes\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.file.write\u003c/code\u003e\u003c/td\u003e\u003ctd\u003ePolicy-aware write helper for non-indexed files and templates\u003c/td\u003e\u003c/tr\u003e\n\n\u003ctr\u003e\u003ctd rowspan=\"3\"\u003e\u003cstrong\u003eMeta\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003esdl.info\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eRuntime diagnostics — version, Node.js, platform, database, config paths\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.usage.stats\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSession and lifetime token savings statistics\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003ccode\u003esdl.action.search\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSearch SDL action catalog to discover the right tool for a task\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n[Complete MCP Tools Reference (detailed parameters \u0026 responses) →](./docs/mcp-tools-detailed.md)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## CLI Commands\n\n| Command             | Description                                                                            |\n| :------------------ | :------------------------------------------------------------------------------------- |\n| `sdl-mcp init`      | Bootstrap config, detect repo/languages, optionally auto-index                         |\n| `sdl-mcp doctor`    | Validate runtime, config, DB, grammars, repo access                                    |\n| `sdl-mcp index`     | Index repositories (with optional `--watch` mode)                                      |\n| `sdl-mcp serve`     | Start MCP server (`--stdio` or `--http`)                                               |\n| `sdl-mcp tool`      | Access 36 direct action aliases ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |\n| `sdl-mcp info`      | Runtime diagnostics — version, Node.js, platform, database, config                     |\n| `sdl-mcp summary`   | Generate copy/paste context summaries from the CLI                                     |\n| `sdl-mcp health`    | Compute composite health score with badge/JSON output                                  |\n| `sdl-mcp benchmark` | Run CI regression benchmarks                                                           |\n| `sdl-mcp export`    | Export sync artifact                                                                   |\n| `sdl-mcp import`    | Import sync artifact                                                                   |\n| `sdl-mcp pull`      | Pull by version/commit with fallback                                                   |\n| `sdl-mcp version`   | Show version and environment info                                                      |\n\n[CLI Reference →](./docs/cli-reference.md) · [Configuration Reference →](./docs/configuration-reference.md)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## Compatible With\n\nSDL-MCP works with any MCP-compatible client:\n\n| Client             | Transport    | Setup                               |\n| :----------------- | :----------- | :---------------------------------- |\n| **Claude Code**    | stdio        | `sdl-mcp init --client claude-code` |\n| **Claude Desktop** | stdio        | `sdl-mcp init --client claude-code` |\n| **Cursor**         | stdio        | Standard MCP server config          |\n| **Windsurf**       | stdio        | Standard MCP server config          |\n| **Codex CLI**      | stdio        | `sdl-mcp init --client codex`       |\n| **Gemini CLI**     | stdio        | `sdl-mcp init --client gemini`      |\n| **OpenCode**       | stdio        | `sdl-mcp init --client opencode`    |\n| **Any MCP client** | stdio / http | `sdl-mcp serve --stdio` or `--http` |\n\nA **VSCode extension** (`sdl-mcp-vscode/`) provides live buffer integration for real-time indexing of unsaved edits.\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## Tech Stack\n\n| Component          | Technology                                 |\n| :----------------- | :----------------------------------------- |\n| Runtime            | Node.js 24+ / TypeScript 5.9+ (strict ESM) |\n| Graph Database     | LadybugDB (embedded, single-file)          |\n| Indexer (default)  | Rust via napi-rs (multi-threaded)          |\n| Indexer (fallback) | tree-sitter + tree-sitter-typescript       |\n| MCP SDK            | @modelcontextprotocol/sdk                  |\n| Validation         | Zod schemas for all payloads               |\n| Transports         | stdio (agents) · HTTP (dev/network)        |\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## System Architecture\n\n```mermaid\n%%{init: {\"theme\":\"base\",\"themeVariables\":{\"background\":\"#ffffff\",\"primaryColor\":\"#E7F8F2\",\"primaryBorderColor\":\"#0F766E\",\"primaryTextColor\":\"#102A43\",\"secondaryColor\":\"#E8F1FF\",\"secondaryBorderColor\":\"#2563EB\",\"secondaryTextColor\":\"#102A43\",\"tertiaryColor\":\"#FFF4D6\",\"tertiaryBorderColor\":\"#B45309\",\"tertiaryTextColor\":\"#102A43\",\"lineColor\":\"#0F766E\",\"textColor\":\"#102A43\",\"fontFamily\":\"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif\"},\"flowchart\":{\"curve\":\"basis\",\"htmlLabels\":true}}}%%\nflowchart TD\n    Clients[\"MCP clients\u003cbr/\u003eClaude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini\"]\n    Gateway[\"Tool gateway\u003cbr/\u003esdl.query, sdl.code, sdl.repo, sdl.agent\"]\n    Flat[\"Flat tools and optional code-mode surfaces\"]\n    Policy[\"Policy engine\u003cbr/\u003eproof-of-need, budgets, audit logging\"]\n    Graph[\"LadybugDB graph\u003cbr/\u003esymbols, edges, files, versions, memories\"]\n    Indexer[\"Indexer pipeline\u003cbr/\u003eRust native or Tree-sitter fallback\u003cbr/\u003epass 1, pass 2, semantic enrichment\"]\n\n    Clients e1@--\u003e Gateway\n    Clients e2@--\u003e Flat\n    Gateway e3@--\u003e Policy\n    Flat e4@--\u003e Policy\n    Policy e5@--\u003e Graph\n    Indexer e6@--\u003e Graph\n\n    classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;\n    classDef process fill:#E8F1FF,stroke:#2563EB,stroke-width:2px,color:#102A43;\n    classDef decision fill:#FFF4D6,stroke:#B45309,stroke-width:2px,color:#102A43;\n    classDef storage fill:#F2E8FF,stroke:#7C3AED,stroke-width:2px,color:#102A43;\n    classDef output fill:#FFE8EF,stroke:#BE123C,stroke-width:2px,color:#102A43;\n    classDef muted fill:#F8FAFC,stroke:#64748B,stroke-width:1px,color:#102A43;\n    classDef animate stroke:#0F766E,stroke-width:2px,stroke-dasharray:10\\,5,stroke-dashoffset:900,animation:dash 22s linear infinite;\n    class e1,e2,e3,e4,e5,e6 animate;\n```\n\n[Full Architecture Documentation →](./docs/architecture.md)\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## Documentation\n\n| Document                                                          | Description                                                         |\n| :---------------------------------------------------------------- | :------------------------------------------------------------------ |\n| [Getting Started](./docs/getting-started.md)                      | Installation, 5-minute setup, MCP client config                     |\n| [MCP Tools Reference](./docs/mcp-tools-detailed.md)               | Detailed docs for the current flat, gateway, and Code Mode surfaces |\n| [CLI Reference](./docs/cli-reference.md)                          | All CLI commands and options                                        |\n| [Configuration Reference](./docs/configuration-reference.md)      | Every config option with defaults and guidance                      |\n| [Agent Workflows](./docs/agent-workflows.md)                      | Workflow instructions for CLAUDE.md / AGENTS.md                     |\n| [Architecture](./docs/architecture.md)                            | Tech stack, data flow, component diagram                            |\n| [Iris Gate Ladder](./docs/feature-deep-dives/iris-gate-ladder.md) | Context escalation methodology                                      |\n| [Troubleshooting](./docs/troubleshooting.md)                      | Common issues and fixes                                             |\n\n### Feature Deep Dives\n\n| Topic                                                                               | What You'll Learn                                                                     |\n| :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |\n| [Iris Gate Ladder](./docs/feature-deep-dives/iris-gate-ladder.md)                   | Four-rung context escalation with token savings analysis                              |\n| [Graph Slicing](./docs/feature-deep-dives/graph-slicing.md)                         | BFS/beam search, edge weights, wire formats, auto-discovery                           |\n| [Delta \u0026 Blast Radius](./docs/feature-deep-dives/delta-blast-radius.md)             | Semantic diffs, ranked impact analysis, PR risk scoring                               |\n| [Live Indexing](./docs/feature-deep-dives/live-indexing.md)                         | Real-time editor buffer integration and overlay architecture                          |\n| [Governance \u0026 Policy](./docs/feature-deep-dives/governance-policy.md)               | Proof-of-need gating, audit logging, runtime sandboxing                               |\n| [Agent Context](./docs/feature-deep-dives/agent-context.md)                         | Task-shaped context retrieval, feedback loops, portable context summaries             |\n| [Context Modes](./docs/feature-deep-dives/context-modes.md)                         | Precise vs broad retrieval, adaptive symbol ranking, benchmark trade-offs             |\n| [Indexing \u0026 Languages](./docs/feature-deep-dives/indexing-languages.md)             | Rust/TS engines, two-pass architecture, 12-language support                           |\n| [Provider-First Indexing](./docs/feature-deep-dives/provider-first-indexing.md)     | SCIP/LSP-first planning, provider facts, shadow DB readiness, fallback boundaries     |\n| [Runtime Execution](./docs/feature-deep-dives/runtime-execution.md)                 | Sandboxed subprocess execution with governance                                        |\n| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md)                     | Direct CLI access to 36 action aliases, output formats, stdin piping, scripting       |\n| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 35 gateway-routable actions, 4 namespace tools, thin schemas, migration guide         |\n| [Semantic Engine](./docs/feature-deep-dives/semantic-engine.md)                     | Pass-2 call resolution, embedding search, LLM summaries, confidence scoring           |\n| [Semantic Embeddings Setup](./docs/feature-deep-dives/semantic-embeddings-setup.md) | Dependencies, model installation, provider configuration, tier-by-tier setup          |\n| [Code Mode](./docs/feature-deep-dives/code-mode.md)                                 | `sdl.context`, `sdl.workflow`, action discovery, manual reference, one-call workflows |\n| [Development Memories](./docs/feature-deep-dives/development-memories.md)           | Graph-backed cross-session memory, file sync, staleness detection, auto-surfacing     |\n| [SCIP Integration](./docs/feature-deep-dives/scip-integration.md)                   | Compiler-grade cross-references, external deps, implements edges, auto-ingest         |\n| [Token Savings Meter](./docs/feature-deep-dives/token-savings-meter.md)             | Per-call meter, session summaries, lifetime tracking, `sdl.usage.stats`               |\n\n\u003cbr/\u003e\n\n---\n\n\u003cbr/\u003e\n\n## License\n\nThis project is **source-available**.\n\n- **Free Use (Community License):** You may use, run, and modify this software for any purpose, including **internal business use**, under the terms in [`LICENSE`](./LICENSE).\n- **Commercial Distribution / Embedding:** You must obtain a **commercial license** before you **sell, license, sublicense, bundle, embed, or distribute** this software as part of a for-sale or monetized product. See [`COMMERCIAL_LICENSE.md`](./COMMERCIAL_LICENSE.md).\n\nQuestions? Contact **gmullins.gkc@gmail.com**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglitterkill%2Fsdl-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglitterkill%2Fsdl-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglitterkill%2Fsdl-mcp/lists"}