sdl-mcp 0.9.2 → 0.10.0

package/README.md

@@ -19,6 +19,10 @@
 
 ---
 
+
+
+
+
 <br/>
 
 ## What's the problem?
@@ -54,8 +58,8 @@ SDL-MCP fixes this. It indexes your codebase into a searchable **symbol graph**
           ┌──────────┼──────────┐
           │          │          │
           ▼          ▼          ▼
-      29 MCP      10 CLI    HTTP API
-       Tools     Commands   + Graph UI
+      35 MCP      13 CLI    HTTP API
+       Tools     Commands   (dev/network)
           │
           ▼
     AI Coding Agent
@@ -280,7 +284,7 @@ Raw code access (Rung 4) is **policy-gated**. Agents must provide:
 
 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 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
@@ -311,7 +315,7 @@ The feedback loop (`sdl.agent.feedback`) records which symbols were useful and w
 
 ### Sandboxed Runtime Execution
 
-Run tests, linters, and scripts through SDL-MCP's governance layer instead of uncontrolled shell access. Three runtimes (Node.js, Python, Shell), code-mode or args-mode, smart output summarization with keyword-matched excerpts, and gzip artifact persistence.
+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
@@ -358,7 +362,7 @@ Memories are **automatically surfaced** inside graph slices — when an agent bu
 
 ### CLI Tool Access — No MCP Server Required
 
-Access all 29 tool actions directly from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK — just your terminal.
+Access all 35 tool actions directly from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK — just your terminal.
 
 ```bash
 # Search for symbols
@@ -385,10 +389,10 @@ Features include typed argument coercion (string, number, boolean, string[], jso
 
 ### Tool Gateway — 81% Token Reduction
 
-The tool gateway consolidates all 29 MCP tools into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from **~3,742 tokens to ~713 tokens** — an **81% reduction**.
+The tool gateway consolidates all 35 MCP tools into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from **~3,742 tokens to ~713 tokens** — an **81% reduction**.
 
 ```
-  Before:  29 tools × full JSON Schema = ~3,742 tokens at conversation start
+  Before:  35 tools × full JSON Schema = ~3,742 tokens at conversation start
   After:    4 tools × thin schema       = ~713 tokens at conversation start
                                           ─────────────
                                           ~3,029 tokens saved per conversation
@@ -398,7 +402,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 **Why it matters:**
 - **81% token reduction** in `tools/list` overhead (~3,742 → ~713 tokens per conversation)
-- 29 tools consolidated into 4 namespace-scoped tools for simpler agent selection
+- 35 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
 
@@ -410,7 +414,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 <br/>
 
-## All 29 MCP Tools at a Glance
+## All 35 MCP Tools at a Glance
 
 <table>
 <tr><th>Category</th><th>Tool</th><th>One-Line Description</th></tr>
@@ -458,14 +462,24 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 <tr><td><code>sdl.agent.feedback</code></td><td>Record which symbols were useful or missing</td></tr>
 <tr><td><code>sdl.agent.feedback.query</code></td><td>Query aggregated feedback statistics</td></tr>
 
-<tr><td><strong>Runtime</strong></td>
-    <td><code>sdl.runtime.execute</code></td><td>Sandboxed subprocess execution (Node/Python/Shell)</td></tr>
+<tr><td rowspan="2"><strong>Runtime</strong></td>
+    <td><code>sdl.runtime.execute</code></td><td>Sandboxed subprocess execution with outputMode (minimal/summary/intent)</td></tr>
+<tr><td><code>sdl.runtime.queryOutput</code></td><td>On-demand retrieval and keyword search of stored output artifacts</td></tr>
 
 <tr><td rowspan="4"><strong>Memory</strong></td>
     <td><code>sdl.memory.store</code></td><td>Store or update a development memory with symbol/file links</td></tr>
 <tr><td><code>sdl.memory.query</code></td><td>Search memories by text, type, tags, or linked symbols</td></tr>
 <tr><td><code>sdl.memory.remove</code></td><td>Soft-delete a memory from graph and optionally from disk</td></tr>
 <tr><td><code>sdl.memory.surface</code></td><td>Auto-surface relevant memories for a task context</td></tr>
+
+<tr><td rowspan="2"><strong>Code Mode</strong></td>
+    <td><code>sdl.chain</code></td><td>Multi-step tool chaining with budget tracking and ETag caching</td></tr>
+<tr><td><code>sdl.manual</code></td><td>Self-documentation — query usage guide, action schemas, output format reference</td></tr>
+
+<tr><td rowspan="3"><strong>Meta</strong></td>
+    <td><code>sdl.info</code></td><td>Runtime diagnostics — version, Node.js, platform, database, config paths</td></tr>
+<tr><td><code>sdl.usage.stats</code></td><td>Session and lifetime token savings statistics</td></tr>
+<tr><td><code>sdl.action.search</code></td><td>Search SDL action catalog to discover the right tool for a task</td></tr>
 </table>
 
 [Complete MCP Tools Reference (detailed parameters & responses) →](./docs/mcp-tools-detailed.md)
@@ -484,9 +498,11 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 | `sdl-mcp doctor` | Validate runtime, config, DB, grammars, repo access |
 | `sdl-mcp index` | Index repositories (with optional `--watch` mode) |
 | `sdl-mcp serve` | Start MCP server (`--stdio` or `--http`) |
-| `sdl-mcp tool` | Access all 25 MCP tool actions directly ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
+| `sdl-mcp tool` | Access all 35 MCP tool actions directly ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
+| `sdl-mcp info` | Runtime diagnostics — version, Node.js, platform, database, config |
 | `sdl-mcp summary` | Generate copy/paste context summaries from the CLI |
 | `sdl-mcp health` | Compute composite health score with badge/JSON output |
+| `sdl-mcp benchmark` | Run CI regression benchmarks |
 | `sdl-mcp export` | Export sync artifact |
 | `sdl-mcp import` | Import sync artifact |
 | `sdl-mcp pull` | Pull by version/commit with fallback |
@@ -527,7 +543,7 @@ A **VSCode extension** (`sdl-mcp-vscode/`) provides live buffer integration for
 
 | Component | Technology |
 |:----------|:-----------|
-| Runtime | Node.js 20+ / TypeScript 5.9+ (strict ESM) |
+| Runtime | Node.js 24+ / TypeScript 5.9+ (strict ESM) |
 | Graph Database | LadybugDB (embedded, single-file) |
 | Indexer (default) | Rust via napi-rs (multi-threaded) |
 | Indexer (fallback) | tree-sitter + tree-sitter-typescript |
@@ -541,17 +557,69 @@ A **VSCode extension** (`sdl-mcp-vscode/`) provides live buffer integration for
 
 <br/>
 
+## System Architecture
+
+```
+  ┌─────────────────────────────────────────────────────────────────────┐
+  │                        MCP Clients                                  │
+  │  Claude Code · Claude Desktop · Cursor · Windsurf · Codex · Gemini │
+  └──────────────────────────┬──────────────────────────────────────────┘
+                             │ stdio / HTTP
+  ┌──────────────────────────▼──────────────────────────────────────────┐
+  │                      Tool Gateway                                    │
+  │  4 namespace-scoped tools (sdl.query, sdl.code, sdl.repo, sdl.agent) │
+  │  ← Thin JSON schemas → Double Zod validation → Handler dispatch      │
+  └───────┬────────┬────────┬────────┬────────┬────────┬────────────────┘
+          │        │        │        │        │        │
+  ┌───────▼──┐ ┌───▼───┐ ┌─▼──┐ ┌──▼──┐ ┌──▼───┐ ┌──▼──────┐
+  │ Symbols  │ │Slices │ │Code│ │Delta│ │Agent │ │ Memory  │
+  │ search   │ │build  │ │gate│ │diff │ │orch. │ │ store   │
+  │ getCard  │ │refresh│ │skel│ │blast│ │feedbk│ │ query   │
+  │ getCards │ │spill. │ │hot │ │risk │ │chain │ │ surface │
+  └────┬─────┘ └───┬───┘ └─┬──┘ └──┬──┘ └──┬───┘ └──┬─────┘
+       │           │       │       │       │        │
+  ┌────▼───────────▼───────▼───────▼───────▼────────▼───────┐
+  │                    Policy Engine                          │
+  │  Proof-of-need gating · Token budgets · Audit logging     │
+  └──────────────────────────┬──────────────────────────────┘
+                             │
+  ┌──────────────────────────▼──────────────────────────────┐
+  │                   LadybugDB (Graph)                      │
+  │  Symbols · Edges · Files · Versions · Clusters ·         │
+  │  Processes · Memories · Metrics                           │
+  └──────────────────────────▲──────────────────────────────┘
+                             │
+  ┌──────────────────────────┴──────────────────────────────┐
+  │                  Indexer Pipeline                         │
+  │  ┌─────────────────┐    ┌────────────────────────────┐   │
+  │  │  Rust (napi-rs)  │ or │  Tree-sitter (TS fallback) │   │
+  │  │  default engine  │    │  11 language grammars       │   │
+  │  └────────┬────────┘    └──────────┬─────────────────┘   │
+  │           │  Pass 1: Symbols + Imports + Calls            │
+  │           │  Pass 2: Cross-file call resolution            │
+  │           │  Semantic: Embeddings + LLM summaries          │
+  └───────────┴──────────────────────────────────────────────┘
+```
+
+[Full Architecture Documentation →](./docs/architecture.md)
+
+<br/>
+
+---
+
+<br/>
+
 ## Documentation
 
 | Document | Description |
 |:---------|:------------|
 | [Getting Started](./docs/getting-started.md) | Installation, 5-minute setup, MCP client config |
-| [MCP Tools Reference](./docs/mcp-tools-detailed.md) | Detailed docs for all 29 tools (parameters, responses, examples) |
+| [MCP Tools Reference](./docs/mcp-tools-detailed.md) | Detailed docs for all 35 tools (parameters, responses, examples) |
 | [CLI Reference](./docs/cli-reference.md) | All CLI commands and options |
 | [Configuration Reference](./docs/configuration-reference.md) | Every config option with defaults and guidance |
 | [Agent Workflows](./docs/agent-workflows.md) | Workflow instructions for CLAUDE.md / AGENTS.md |
-| [Architecture](./docs/ARCHITECTURE.md) | Tech stack, data flow, component diagram |
-| [Iris Gate Ladder](./docs/IRIS_GATE_LADDER.md) | Context escalation methodology |
+| [Architecture](./docs/architecture.md) | Tech stack, data flow, component diagram |
+| [Iris Gate Ladder](./docs/feature-deep-dives/iris-gate-ladder.md) | Context escalation methodology |
 | [Troubleshooting](./docs/troubleshooting.md) | Common issues and fixes |
 
 ### Feature Deep Dives
@@ -566,11 +634,13 @@ A **VSCode extension** (`sdl-mcp-vscode/`) provides live buffer integration for
 | [Agent Orchestration](./docs/feature-deep-dives/agent-orchestration.md) | Autopilot mode, feedback loops, portable context summaries |
 | [Indexing & Languages](./docs/feature-deep-dives/indexing-languages.md) | Rust/TS engines, two-pass architecture, 12-language support |
 | [Runtime Execution](./docs/feature-deep-dives/runtime-execution.md) | Sandboxed subprocess execution with governance |
-| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md) | Direct CLI access to all 29 actions, output formats, stdin piping, scripting |
-| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md) | 29→4 tool consolidation, 81% token reduction, thin schemas, migration guide |
+| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md) | Direct CLI access to all tool actions, output formats, stdin piping, scripting |
+| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md) | 35→4 tool consolidation, token reduction, thin schemas, migration guide |
 | [Semantic Engine](./docs/feature-deep-dives/semantic-engine.md) | Pass-2 call resolution, embedding search, LLM summaries, confidence scoring |
 | [Semantic Embeddings Setup](./docs/feature-deep-dives/semantic-embeddings-setup.md) | Dependencies, model installation, provider configuration, tier-by-tier setup |
+| [Code Mode](./docs/feature-deep-dives/code-mode.md) | Tool chaining (sdl.chain), action discovery, manual reference, one-call workflows |
 | [Development Memories](./docs/feature-deep-dives/development-memories.md) | Graph-backed cross-session memory, file sync, staleness detection, auto-surfacing |
+| [Token Savings Meter](./docs/feature-deep-dives/token-savings-meter.md) | Per-call meter, session summaries, lifetime tracking, `sdl.usage.stats` |
 
 <br/>
 

package/config/sdlmcp.config.example.json

@@ -35,11 +35,15 @@
       "workspaceGlobs": null
     }
   ],
+  "graphDatabase": {
+    "path": "./data/sdl-mcp-graph.lbug"
+  },
   "policy": {
     "maxWindowLines": 180,
     "maxWindowTokens": 1400,
     "requireIdentifiers": true,
-    "allowBreakGlass": false
+    "allowBreakGlass": false,
+    "defaultDenyRaw": true
   },
   "redaction": {
     "enabled": true,
@@ -94,7 +98,8 @@
     "enabled": true,
     "alpha": 0.6,
     "provider": "local",
-    "model": "nomic-embed-text-v1.5",
+    "model": "all-MiniLM-L6-v2",
+    "modelCacheDir": null,
     "generateSummaries": false,
     "summaryProvider": null,
     "summaryModel": null,
@@ -108,6 +113,34 @@
       "efConstruction": 200,
       "efSearch": 50,
       "maxElements": 200000
+    },
+    "retrieval": {
+      "mode": "legacy",
+      "extensionsOptional": true,
+      "fts": {
+        "enabled": true,
+        "indexName": "symbol_search_text_v1",
+        "topK": 75,
+        "conjunctive": false
+      },
+      "vector": {
+        "enabled": true,
+        "topK": 75,
+        "efs": 200,
+        "indexes": {
+          "all-MiniLM-L6-v2": {
+            "indexName": "symbol_vec_minilm_l6_v2"
+          },
+          "nomic-embed-text-v1.5": {
+            "indexName": "symbol_vec_nomic_embed_v15"
+          }
+        }
+      },
+      "fusion": {
+        "strategy": "rrf",
+        "rrfK": 60
+      },
+      "candidateLimit": 100
     }
   },
   "prefetch": {
@@ -116,20 +149,17 @@
     "warmTopN": 50
   },
   "tracing": {
-    "enabled": false,
+    "enabled": true,
     "serviceName": "sdl-mcp",
     "exporterType": "console",
     "otlpEndpoint": null,
     "sampleRate": 1
   },
   "parallelScorer": {
-    "enabled": false,
+    "enabled": true,
     "poolSize": null,
     "minBatchSize": null
   },
-  "graphDatabase": {
-    "path": "./data/sdl-mcp-graph.lbug"
-  },
   "concurrency": {
     "maxSessions": 8,
     "maxToolConcurrency": 8,
@@ -137,17 +167,40 @@
     "writeQueueTimeoutMs": 30000,
     "toolQueueTimeoutMs": 30000
   },
-  "httpAuth": {
+  "runtime": {
+    "enabled": false,
+    "allowedRuntimes": [
+      "node",
+      "python"
+    ],
+    "allowedExecutables": [],
+    "maxDurationMs": 30000,
+    "maxStdoutBytes": 1048576,
+    "maxStderrBytes": 262144,
+    "maxArtifactBytes": 10485760,
+    "artifactTtlHours": 24,
+    "maxConcurrentJobs": 2,
+    "envAllowlist": [],
+    "artifactBaseDir": null
+  },
+  "gateway": {
     "enabled": true,
+    "emitLegacyTools": true
+  },
+  "httpAuth": {
+    "enabled": false,
     "token": null
   },
   "codeMode": {
-    "enabled": false,
-    "exclusive": false,
+    "enabled": true,
+    "exclusive": true,
     "maxChainSteps": 20,
     "maxChainTokens": 50000,
     "maxChainDurationMs": 60000,
     "ladderValidation": "warn",
     "etagCaching": true
+  },
+  "security": {
+    "allowedRepoRoots": []
   }
 }

package/config/sdlmcp.config.json.sample

@@ -37,7 +37,7 @@
     "maxWindowLines": 180,
     "maxWindowTokens": 1400,
     "requireIdentifiers": true,
-    "allowBreakGlass": true
+    "allowBreakGlass": false
   },
   "redaction": {
     "enabled": true,
@@ -66,7 +66,7 @@
     "generateSummaries": false
   },
   "prefetch": {
-    "enabled": false,
+    "enabled": true,
     "maxBudgetPercent": 20,
     "warmTopN": 50
   }