sdl-mcp 0.11.1 → 0.11.3

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
-<img src="https://github.com/GlitterKill/sdl-mcp/blob/main/docs/Symbol_Delta_Ledger_MCP.jpg" alt="Symbol Delta Ledger MCP">
+<img src="https://github.com/GlitterKill/sdl-mcp/blob/main/docs/SDL-MCP_promo.webp" alt="Symbol Delta Ledger MCP">
 
 <br/>
 
-# SDL-MCP
+# SYMBOL DELTA LEDGER
 
 ### **Cards-first code context for AI coding agents**
 
@@ -80,7 +80,7 @@ flowchart TD
 
 - **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.
 
-> **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`
+> **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.
 
 <br/>
 
@@ -368,6 +368,8 @@ The sandboxed runtime execution tool (`sdl.runtime.execute`) has its own governa
 
 `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`.
 
+Unscoped 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.
+
 The feedback loop (`sdl.agent.feedback`) records which symbols were useful and which were missing, improving future slice quality.
 
 For 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.
@@ -375,6 +377,7 @@ For portable exports such as tickets and PR descriptions, use the CLI `sdl-mcp s
 **Why it matters:**
 
 - Task-shaped context retrieval plans the **right Iris Gate path** within a token budget
+- Confidence-gated hybrid retrieval improves discovery without slowing known-target lookups
 - Feedback loop records what was useful/missing, improving future slice quality
 - Portable context summaries export findings for use outside MCP environments
 
@@ -474,7 +477,7 @@ flowchart LR
 
 ### CLI Tool Access — No MCP Server Required
 
-Access 30 SDL-MCP action aliases directly from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK is required.
+Access 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.
 
 ```bash
 # Search for symbols
@@ -485,14 +488,22 @@ 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"
+
+# Apply a single-file targeted write
+sdl-mcp tool file.write --repo-id my-repo --file-path config/app.json \
+  --json-path server.port --json-value 8080
+
+# Discover and inspect metadata without opening the graph DB
+sdl-mcp tool action.search --query manual --summary-only
+sdl-mcp tool manual --actions action.search --format json
 ```
 
-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.
+Features 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.
 
 **Why it matters:**
 
-- 30 direct action aliases accessible from **any terminal** — no server, transport, or SDK required
-- Same code paths and Zod validation as the MCP server — identical behavior
+- 35 direct graph/action aliases plus `action.search` and `manual` metadata proxies accessible from **any terminal** - no server, transport, or SDK required
+- Direct graph actions keep gateway-router/Zod parity; metadata proxies share the same MCP registration handlers
 - 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`
 
@@ -502,12 +513,12 @@ Features include typed argument coercion (string, number, boolean, string[], jso
 
 ### Tool Gateway — Compact Tool Registration
 
-The tool gateway projects the 30 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.
+The tool gateway projects the 34 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.
 
 ```mermaid
 %%{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}}}%%
 flowchart LR
-    Before["Flat mode<br/>33 tools<br/>2 universal + 31 flat"] e1@--> After["Gateway mode<br/>6 tools<br/>2 universal + 4 gateway"]
+    Before["Flat mode<br/>37 tools<br/>2 universal + 35 flat"] e1@--> After["Gateway mode<br/>6 tools<br/>2 universal + 4 gateway"]
     After e2@--> Savings["Smaller tools/list payload<br/>lower agent startup overhead"]
 
     classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
@@ -525,7 +536,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 **Why it matters:**
 
 - Large reduction in `tools/list` overhead for gateway-first agents
-- 30 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection
+- 34 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection
 - Fewer tool choices means faster and more accurate tool dispatch by the agent
 - Choose Code Mode for task-shaped retrieval first; opt out of exclusive Code Mode when you also need regular flat or gateway tools
 
@@ -535,7 +546,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 ### Observability Dashboard
 
-Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP behaviour without parsing stderr logs. Cyberpunk-corporate dark UI at `/ui/observability` on the HTTP transport, plus REST + SSE APIs (`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`) for programmatic access. Surfaces cache hit rates, hybrid-retrieval breakdowns (FTS / vector / PPR / RRF), beam-search decision traces, indexing pipeline metrics, write-pool and drain saturation, packed-wire savings, SCIP ingest health, deterministic bottleneck classification, and OS-level resource samples. See [Observability Dashboard Deep Dive](./docs/feature-deep-dives/observability-dashboard.md).
+Built-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 <port>` sidecar, plus REST + SSE APIs (`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`) for programmatic access. Surfaces cache hit rates, 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).
 
 <br/>
 
@@ -547,10 +558,10 @@ Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP be
 
 | Mode                | Tool count | Composition                                                      |
 | :------------------ | :--------- | :--------------------------------------------------------------- |
-| Flat                | `33`       | `2` universal + `31` flat tools                                  |
+| Flat                | `37`       | `2` universal + `35` flat tools                                  |
 | Gateway             | `6`        | `2` universal + `4` gateway tools                                |
-| Gateway + legacy    | `37`       | `2` universal + `4` gateway + `31` flat tools                    |
-| Code Mode exclusive | `4`        | `sdl.action.search`, `sdl.context`, `sdl.manual`, `sdl.workflow` |
+| Gateway + legacy    | `41`       | `2` universal + `4` gateway + `35` flat tools                    |
+| Code Mode exclusive | `5`        | `sdl.action.search`, `sdl.context`, `sdl.file`, `sdl.manual`, `sdl.workflow` |
 
 The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/generated/tool-inventory.md).
 
@@ -639,7 +650,7 @@ The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/gen
 | `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 30 direct action aliases ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
+| `sdl-mcp tool`      | Access 35 direct action aliases ([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                                  |
@@ -761,8 +772,8 @@ flowchart TD
 | [Context Modes](./docs/feature-deep-dives/context-modes.md)                         | Precise vs broad retrieval, adaptive symbol ranking, benchmark trade-offs             |
 | [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 30 action aliases, output formats, stdin piping, scripting       |
-| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 30 gateway-routable actions, 4 namespace tools, thin schemas, migration guide         |
+| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md)                     | Direct CLI access to 35 action aliases, output formats, stdin piping, scripting       |
+| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 34 gateway-routable actions, 4 namespace tools, 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)                                 | `sdl.context`, `sdl.workflow`, action discovery, manual reference, one-call workflows |

package/config/sdlmcp.config.example.json

@@ -163,6 +163,27 @@
       "candidateLimit": 100
     }
   },
+  "semanticEnrichment": {
+    "enabled": false,
+    "autoRunOnIndexRefresh": false,
+    "installPolicy": "never",
+    "cacheDir": null,
+    "concurrency": 1,
+    "timeoutMs": 300000,
+    "languages": [],
+    "providers": {
+      "scip": {
+        "enabled": true,
+        "indexes": []
+      },
+      "lsp": {
+        "enabled": true,
+        "confidence": 0.8,
+        "candidateLimit": 200,
+        "servers": {}
+      }
+    }
+  },
   "prefetch": {
     "enabled": true,
     "maxBudgetPercent": 20,
@@ -208,6 +229,10 @@
     "maxStdoutBytes": 1048576,
     "maxStderrBytes": 262144,
     "maxArtifactBytes": 10485760,
+    "maxResponseArtifactsPerRepo": 128,
+    "maxResponseArtifactBytesPerRepo": 1342177280,
+    "maxResponseArtifactBytesTotal": 2684354560,
+    "maxResponseArtifactsTotal": 512,
     "artifactTtlHours": 24,
     "maxConcurrentJobs": 2,
     "envAllowlist": [],

package/config/sdlmcp.config.schema.json

@@ -838,6 +838,145 @@
         "embeddingConcurrency": 1
       }
     },
+    "semanticEnrichment": {
+      "type": "object",
+      "description": "Provider-backed graph precision enrichment. Separate from semantic embeddings/retrieval.",
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "autoRunOnIndexRefresh": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, run eligible enrichment providers after index.refresh. SCIP keeps its existing mid-index ingest placement and is not moved to the post-index hook."
+        },
+        "installPolicy": {
+          "type": "string",
+          "enum": ["never", "verified"],
+          "default": "never",
+          "description": "Controls provider download behavior. 'verified' permits only checksum-verified downloads; package-manager install recipes are never executed automatically."
+        },
+        "cacheDir": {
+          "type": ["string", "null"],
+          "default": null,
+          "description": "Reserved cache root for future durable provider caches. V2 writes provider results to the graph and does not persist LSP response caches here."
+        },
+        "concurrency": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8,
+          "default": 1,
+          "description": "Reserved cap for future cross-provider scheduling. V2 runs selected providers serially, with provider-specific internal limits where needed."
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 1800000,
+          "default": 300000
+        },
+        "languages": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": [],
+          "description": "Language IDs to enrich. Empty means all current tree-sitter-backed languages."
+        },
+        "providers": {
+          "type": "object",
+          "description": "Provider-specific overrides. Source selection is fixed priority: SCIP > LSP.",
+          "properties": {
+            "scip": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean", "default": true },
+                "providerId": { "type": "string" },
+                "providerVersion": { "type": "string" },
+                "indexes": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": ["path"],
+                    "properties": {
+                      "path": { "type": "string" },
+                      "label": { "type": "string" }
+                    }
+                  },
+                  "default": []
+                }
+              }
+            },
+            "lsp": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean", "default": true },
+                "providerId": { "type": "string" },
+                "providerVersion": { "type": "string" },
+                "confidence": {
+                  "type": "number",
+                  "minimum": 0.5,
+                  "maximum": 1,
+                  "default": 0.8
+                },
+                "candidateLimit": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 5000,
+                  "default": 200
+                },
+                "servers": {
+                  "type": "object",
+                  "additionalProperties": {
+                    "type": "object",
+                    "required": ["serverId", "command"],
+                    "properties": {
+                      "enabled": { "type": "boolean", "default": true },
+                      "serverId": { "type": "string" },
+                      "command": { "type": "string" },
+                      "args": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "default": []
+                      },
+                      "languages": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "default": []
+                      },
+                      "documentLanguageIds": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "default": []
+                      },
+                      "filePatterns": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "default": []
+                      },
+                      "capabilities": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "default": []
+                      },
+                      "readiness": { "type": "string" },
+                      "initializationOptions": { "type": "object" }
+                    }
+                  },
+                  "default": {}
+                }
+              }
+            }
+          },
+          "default": {}
+        }
+      },
+      "default": {
+        "enabled": false,
+        "autoRunOnIndexRefresh": false,
+        "installPolicy": "never",
+        "cacheDir": null,
+        "concurrency": 1,
+        "timeoutMs": 300000,
+        "languages": [],
+        "providers": {}
+      }
+    },
     "prefetch": {
       "type": "object",
       "description": "Predictive prefetch configuration",
@@ -1054,7 +1193,7 @@
         },
         "toolQueueTimeoutMs": {
           "type": "integer",
-          "description": "Timeout for queued tool dispatch operations in milliseconds",
+          "description": "How long a foreground MCP tool request can wait for a dispatch slot before its handler starts. Timed-out requests fail with a retryable unavailable error; running handlers are not canceled.",
           "minimum": 5000,
           "maximum": 120000,
           "default": 30000
@@ -1114,6 +1253,30 @@
           "minimum": 1024,
           "default": 10485760
         },
+        "maxResponseArtifactsPerRepo": {
+          "type": "integer",
+          "description": "Maximum response artifacts retained per repository",
+          "minimum": 1,
+          "default": 128
+        },
+        "maxResponseArtifactBytesPerRepo": {
+          "type": "integer",
+          "description": "Maximum response-artifact bytes retained per repository",
+          "minimum": 1024,
+          "default": 1342177280
+        },
+        "maxResponseArtifactBytesTotal": {
+          "type": "integer",
+          "description": "Maximum response-artifact bytes retained across the artifact directory",
+          "minimum": 1024,
+          "default": 2684354560
+        },
+        "maxResponseArtifactsTotal": {
+          "type": "integer",
+          "description": "Maximum response artifacts retained across the artifact directory",
+          "minimum": 1,
+          "default": 512
+        },
         "artifactTtlHours": {
           "type": "integer",
           "description": "Time-to-live for stored artifacts in hours",
@@ -1195,7 +1358,7 @@
         },
         "rateLimit": {
           "type": "object",
-          "description": "Per-client token bucket for protected HTTP routes before bearer-token comparison",
+          "description": "Per-client token bucket for failed HTTP auth attempts",
           "properties": {
             "bucketSize": {
               "type": "integer",