SDL-MCP

Cards-first code context for AI coding agents

Stop feeding entire files into the context window.<br/>Start giving agents exactly the code intelligence they need.

What's the problem?

Every 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<User> — but it reads them anyway, because that's all it has.

Multiply that across a debugging session touching 20 files and you've burned 40,000+ tokens on context gathering alone.

SDL-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.

How it works — in 30 seconds

flowchart TD
    Codebase["Your Codebase"]
    Indexer["Indexer<br/>12 languages<br/>Rust native or Tree-sitter fallback"]
    Graph["LadybugDB graph<br/>symbols, edges, metrics, versions"]
    MCP["34 flat MCP tools<br/>plus optional gateway and code-mode surfaces"]
    CLI["13 CLI commands"]
    HTTP["HTTP API and graph UI"]
    Agent["AI coding agent<br/>Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini"]

    Codebase --> Indexer --> Graph
    Graph --> MCP
    Graph --> CLI
    Graph --> HTTP
    MCP --> Agent

1. 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
2. Query efficiently — Agents use MCP tools to search, slice, and retrieve exactly the context they need
3. 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)

Quick Start

# Install
npm install -g sdl-mcp

# Initialize, auto-detect languages, index your repo, and run health checks
sdl-mcp init -y --auto-index

# Start the MCP server for your coding agent
sdl-mcp serve --stdio

Point your MCP client at the server and the agent gains access to all SDL-MCP tools. That's it.

npx users: Replace sdl-mcp with npx --yes sdl-mcp@latest in all commands above.

Full Getting Started Guide →

The Iris Gate Ladder

The 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.

flowchart TB
    R1["~100 tokens<br/>Rung 1: Symbol Card<br/>Name, signature, summary, dependencies, metrics"]
    R2["~300 tokens<br/>Rung 2: Skeleton IR<br/>Signatures and control flow with bodies elided"]
    R3["~600 tokens<br/>Rung 3: Hot-Path Excerpt<br/>Identifier-focused lines with context"]
    R4["~2,000 tokens<br/>Rung 4: Raw Code Window<br/>Policy-gated full source"]

    R1 --> R2 --> R3 --> R4

Most questions are answered at Rungs 1-2 without ever reading raw code. That's where the token savings come from.

Why it matters:

• 4–20x token savings on typical code understanding queries
• Most questions answered at Rungs 1–2 without ever reading raw code
• Controlled escalation prevents agents from over-consuming context
• Policy-gated raw access ensures agents prove they need full source

Iris Gate Ladder Deep Dive →

Feature Tour

Symbol Cards — The Atoms of Understanding

Every 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.

flowchart TB
    Card["Symbol Card: validateToken"]
    Kind["Kind: function (exported)"]
    File["File: src/auth/jwt.ts:42-67"]
    Signature["Signature: (token: string, opts?: ValidateOpts) -> Promise<DecodedToken>"]
    Summary["Summary: validates JWT signature and expiration"]
    Invariants["Invariants: throws on expired token"]
    SideEffects["Side effects: logs to audit trail"]
    Deps["Dependencies: verifySignature, checkExpiry, jsonwebtoken, AuditLogger"]
    Metrics["Metrics: fan-in 12, fan-out 4, churn 3/30d"]
    Context["Context: auth-module, request-pipeline, auth.test.ts"]
    ETag["ETag: a7f3c2..."]

    Card --> Kind --> File --> Signature --> Summary --> Invariants --> SideEffects --> Deps --> Metrics --> Context --> ETag

Cards 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).

Why it matters:

• ~100 tokens per symbol vs. ~2,000 tokens to read the full file
• Confidence-scored dependency edges trace real call relationships across files
• Community detection and call-chain tracing reveal architectural structure
• ETag-based conditional requests avoid re-fetching unchanged symbols

Indexing & Language Support Deep Dive →

Graph Slicing — The Right Context for Every Task

Instead 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.

flowchart TD
    Task["Task: Fix the auth middleware"] --> Slice["sdl.slice.build"]
    Slice --> Auth["authenticate"]
    Slice --> Validate["validateToken"]
    Slice --> Config["JwtConfig"]
    Auth --> Hash["hashPassword"]
    Validate --> User["getUserById"]
    Config --> Env["envLoader"]
    Env -. frontier outside budget .-> Frontier["spillover frontier"]

Slices 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.

Why it matters:

• Follows the dependency graph, not directory boundaries, for cross-cutting context
• Weighted edge scoring (call > config > import) prioritizes the most relevant symbols
• Token-budgeted: returns only what fits within your budget (~800 tokens vs. ~16,000 for raw files)
• Natural-language task-text auto-discovers entry symbols — no symbol IDs needed

Graph Slicing Deep Dive →

Delta Packs & Blast Radius — Semantic Change Intelligence

git diff tells you what lines changed. SDL-MCP tells you what that change means and who's affected.

flowchart TD
    Change["Modified validateToken() signature"]
    Sig["signatureDiff<br/>added options?: object"]
    Inv["invariantDiff<br/>added throws on expired"]
    Fx["sideEffectDiff<br/>added logs to audit trail"]
    Blast["Blast radius"]
    A1["authenticate()<br/>distance 1"]
    A2["refreshSession()<br/>distance 1"]
    A3["AuthMiddleware<br/>distance 2"]
    A4["auth.test.ts<br/>re-run recommended"]

    Change --> Sig
    Change --> Inv
    Change --> Fx
    Sig --> Blast
    Inv --> Blast
    Fx --> Blast
    Blast --> A1
    Blast --> A2
    Blast --> A3
    Blast --> A4

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.

Why it matters:

• Semantic diffs show what a change means, not just what lines moved
• Ranked blast radius identifies which dependent symbols are most at risk
• Fan-in trend analysis detects "amplifier" symbols whose changes ripple further over time
• PR risk scoring produces actionable findings with test re-run recommendations

Delta & Blast Radius Deep Dive →

Live Indexing — Real-Time Code Intelligence

SDL-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.

flowchart LR
    Editor["Editor keystrokes"] --> Push["sdl.buffer.push"]
    Push --> Overlay["Overlay store"]
    Overlay --> Reads["Merged reads<br/>search, cards, slices"]
    Overlay --> Persist["save / idle checkpoint"]
    Persist --> DB["LadybugDB durable graph"]

Why it matters:

• Search, cards, and slices reflect unsaved editor changes in real time
• No manual re-index needed during active development
• Background AST parsing with in-memory overlay keeps queries fast

Live Indexing Deep Dive →

Governance & Policy — Controlled Access

Raw code access (Rung 4) is policy-gated. Agents must provide:

• A reason explaining why they need raw code
• Identifiers they expect to find in the code
• An expected line count within configured limits

Requests that don't meet policy are denied with actionable guidance ("try getHotPath with these identifiers instead"). Every access is audit-logged.

The sandboxed runtime execution tool (sdl.runtime.execute) has its own governance layer: disabled by default, 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.

Why it matters:

• Proof-of-need gating prevents agents from wastefully reading raw code
• Denied requests include actionable next-best-action guidance
• Full audit logging of every code access decision
• Sandboxed runtime with executable allowlisting, CWD jailing, and environment scrubbing

Governance & Policy Deep Dive →

Agent Context — Task-Shaped Retrieval

sdl.agent.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.

The feedback loop (sdl.agent.feedback) records which symbols were useful and which were missing, improving future slice quality.

sdl.context.summary generates portable, token-bounded context briefings in markdown, JSON, or clipboard format for use outside MCP environments.

Why it matters:

• Task-shaped context retrieval plans the right Iris Gate path within a token budget
• Feedback loop records what was useful/missing, improving future slice quality
• Portable context summaries export findings for use outside MCP environments

Agent Context Deep Dive → · Context Modes →

Sandboxed Runtime Execution

Run 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.

Why it matters:

• Run tests, linters, and scripts under governance instead of uncontrolled shell access
• 16 runtimes supported (Node, Python, Go, Java, Rust, Shell, and more)
• Executable allowlisting, CWD jailing, timeout enforcement, and environment scrubbing
• Smart output summarization with keyword-matched excerpts and gzip artifact persistence

Runtime Execution Deep Dive →

Development Memories — Cross-Session Knowledge Persistence

Agents forget everything between sessions. SDL-MCP fixes this with a graph-backed memory system that lets agents store decisions, bugfix context, and task notes linked directly to the symbols and files they relate to. Memories are stored both in the graph database (for fast querying) and as checked-in markdown files (for version control and team sharing).

flowchart LR
    Session1["Agent session 1<br/>records bugfix memory"] --> Store["sdl.memory.store"]
    Store --> Graph["LadybugDB memory node"]
    Store --> Files[".sdl-memory/bugfixes/<id>.md"]
    Graph --> Link1["MEMORY_OF -> authenticate()"]
    Graph --> Link2["HAS_MEMORY -> repo"]
    Session2["Agent session 2"] --> Surface["sdl.memory.surface"]
    Surface --> Graph
    Graph --> Recall["Relevant memory surfaced<br/>race condition fix in authenticate()"]

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.

Why it matters:

• Structured knowledge persists across sessions, linked directly to symbols and files
• Automatically surfaced inside graph slices when touching related symbols
• Stale memories flagged when linked symbols change during re-indexing
• Dual storage: graph DB for fast querying + markdown files for version control and team sharing

Development Memories Deep Dive →

CLI Tool Access — No MCP Server Required

Access all 32 flat SDL action tools directly from the command line with sdl-mcp tool. No MCP server, transport, or SDK is required.

# Search for symbols
sdl-mcp tool symbol.search --query "handleAuth" --output-format pretty

# Build a task-scoped slice
sdl-mcp tool slice.build --task-text "debug auth flow" --max-cards 50

# Pipe JSON args, chain commands
echo '{"repoId":"my-repo"}' | sdl-mcp tool symbol.search --query "auth"

Features include typed argument coercion (string, number, boolean, string[], json), budget flag merging, stdin JSON piping with CLI-flags-win precedence, auto-resolved repoId from cwd, four output formats (json, json-compact, pretty, table), typo suggestions, and per-action --help. The CLI dispatches through the same gateway router and Zod schemas as the MCP server — identical code paths, identical validation.

Why it matters:

• All MCP tool actions accessible from any terminal — no server, transport, or SDK required
• Same code paths and Zod validation as the MCP server — identical behavior
• Four output formats (json, json-compact, pretty, table) for scripting and CI pipelines
• Auto-resolves repoId from cwd, supports stdin JSON piping and per-action --help

CLI Tool Access Deep Dive →

Tool Gateway — 81% Token Reduction

The tool gateway consolidates the 32 flat SDL action tools 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.

flowchart LR
    Before["Flat mode<br/>32 flat action tools<br/>plus universal discovery/info"] --> After["Gateway mode<br/>4 namespace tools<br/>plus universal discovery/info"]
    After --> Savings["Smaller tools/list payload<br/>lower agent startup overhead"]

Each 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. Legacy flat tool names are optionally emitted alongside for backward compatibility.

Why it matters:

• Large reduction in tools/list overhead for gateway-first agents
• 32 flat action tools consolidated into 4 namespace-scoped tools for simpler agent selection
• Fewer tool choices means faster and more accurate tool dispatch by the agent
• Backward-compatible: legacy flat tool names optionally emitted alongside

Tool Gateway Deep Dive →

All 36 Unique Tool Surfaces at a Glance

Complete MCP Tools Reference (detailed parameters & responses) →

CLI Commands

CLI Reference → · Configuration Reference →

Compatible With

SDL-MCP works with any MCP-compatible client:

A VSCode extension (sdl-mcp-vscode/) provides live buffer integration for real-time indexing of unsaved edits.

Tech Stack

System Architecture

flowchart TD
    Clients["MCP clients<br/>Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini"]
    Gateway["Tool gateway<br/>sdl.query, sdl.code, sdl.repo, sdl.agent"]
    Flat["Flat tools and optional code-mode surfaces"]
    Policy["Policy engine<br/>proof-of-need, budgets, audit logging"]
    Graph["LadybugDB graph<br/>symbols, edges, files, versions, memories"]
    Indexer["Indexer pipeline<br/>Rust native or Tree-sitter fallback<br/>pass 1, pass 2, semantic enrichment"]

    Clients --> Gateway
    Clients --> Flat
    Gateway --> Policy
    Flat --> Policy
    Policy --> Graph
    Indexer --> Graph

Full Architecture Documentation →

Documentation

Feature Deep Dives

License

This project is source-available.

• Free Use (Community License): You may use, run, and modify this software for any purpose, including internal business use, under the terms in LICENSE.
• 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.

Questions? Contact gmullins.gkc@gmail.com.