sdl-mcp 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SDL-MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# SDL-MCP
+
+<div align="right">
+<details>
+<summary><strong>Documentation</strong></summary>
+
+- [Overview (this page)](./README.md)
+- [Documentation Hub](./docs/README.md)
+  - [Getting Started](./docs/getting-started.md)
+  - [CLI Reference](./docs/cli-reference.md)
+  - [MCP Tools Reference](./docs/mcp-tools-reference.md)
+  - [Configuration Reference](./docs/configuration-reference.md)
+  - [Agent Workflows](./docs/agent-workflows.md)
+  - [Troubleshooting](./docs/troubleshooting.md)
+- [Legacy User Guide](./docs/USER_GUIDE.md)
+
+</details>
+</div>
+
+SDL-MCP (Symbol Delta Ledger MCP Server) is a cards-first context system for coding agents.
+
+Instead of opening large files first, SDL-MCP indexes repositories into symbol cards and graph edges so agents can:
+
+- Search and retrieve small, structured context first
+- Build task-specific graph slices with token budgets
+- Refresh context with deltas between versions
+- Request code windows through policy-gated access
+
+## Why It Helps Coding Agents
+
+- Lower token usage by default through cards/slices/skeletons
+- Better relevance with dependency-aware context retrieval
+- Safer context access via policy controls and auditing
+- Faster iteration through incremental indexing and refresh workflows
+- Works across TypeScript, JavaScript, Python, Go, Java, C#, C, C++, PHP, Rust, Kotlin, and Shell
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g sdl-mcp
+```
+
+Or run without global install:
+
+```bash
+npx sdl-mcp@latest version
+```
+
+### Initialize and Run
+
+```bash
+# 1) Create config in the current project
+sdl-mcp init --client codex
+
+# 2) Validate environment
+sdl-mcp doctor
+
+# 3) Build the symbol ledger
+sdl-mcp index
+
+# 4) Start MCP server (stdio for coding agents)
+sdl-mcp serve --stdio
+```
+
+## Core Feature Set
+
+- Multi-language repository indexing with tree-sitter adapters
+- Symbol cards with signatures, deps, metrics, and versioning
+- Graph slices with handles, leases, refresh, and spillover
+- Delta analysis and blast radius support
+- Code access ladder: `getSkeleton` -> `getHotPath` -> `needWindow`
+- Policy management (`sdl.policy.get` / `sdl.policy.set`)
+- Repository overview and hotspot inspection (`sdl.repo.overview`)
+- PR risk analysis (`sdl.pr.risk.analyze`)
+- Agent orchestration tool (`sdl.agent.orchestrate`)
+- Sync artifact export/import/pull workflows
+
+## CLI Commands
+
+- `init` - bootstrap config and optional client template
+- `doctor` - validate runtime, config, DB path, grammars, repo access
+- `index` - index repositories (optionally watch)
+- `serve` - run MCP server (`--stdio` or `--http`)
+- `export` - export sync artifact
+- `import` - import sync artifact
+- `pull` - pull by version/commit with fallback behavior
+- `benchmark:ci` - run CI benchmark and threshold checks
+- `version` - show version and environment info
+
+## MCP Tools
+
+- Repository: `sdl.repo.register`, `sdl.repo.status`, `sdl.repo.overview`, `sdl.index.refresh`
+- Symbols: `sdl.symbol.search`, `sdl.symbol.getCard`
+- Slice: `sdl.slice.build`, `sdl.slice.refresh`, `sdl.slice.spillover.get`
+- Delta: `sdl.delta.get`
+- Code: `sdl.code.needWindow`, `sdl.code.getSkeleton`, `sdl.code.getHotPath`
+- Policy: `sdl.policy.get`, `sdl.policy.set`
+- Risk/Agent: `sdl.pr.risk.analyze`, `sdl.agent.orchestrate`
+
+See: [MCP Tools Reference](./docs/mcp-tools-reference.md)
+
+## Documentation
+
+- [Documentation Hub](./docs/README.md)
+- [Getting Started](./docs/getting-started.md)
+- [CLI Reference](./docs/cli-reference.md)
+- [MCP Tools Reference](./docs/mcp-tools-reference.md)
+- [Configuration Reference](./docs/configuration-reference.md)
+- [Agent Workflows](./docs/agent-workflows.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Legacy User Guide](./docs/USER_GUIDE.md)
+
+## Development
+
+```bash
+npm run build
+npm run typecheck
+npm run lint
+npm test
+```
+
+Benchmark tooling (npm scripts):
+
+- `npm run benchmark:real`
+- `npm run benchmark:matrix`
+- `npm run benchmark:sweep`
+
+## License
+
+MIT

package/config/benchmark.ci.config.json

@@ -0,0 +1,86 @@
+{
+  "version": "1.0",
+  "description": "Benchmark threshold configuration for CI regression detection (hosted-runner profile)",
+  "thresholds": {
+    "indexing": {
+      "indexTimePerFile": {
+        "maxMs": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      },
+      "indexTimePerSymbol": {
+        "maxMs": 15,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 60
+      }
+    },
+    "quality": {
+      "symbolsPerFile": {
+        "minValue": 5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "edgesPerSymbol": {
+        "minValue": 1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "graphConnectivity": {
+        "minValue": 0.3,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "exportedSymbolRatio": {
+        "minValue": 0.2,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    },
+    "performance": {
+      "sliceBuildTimeMs": {
+        "maxMs": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 125
+      },
+      "avgSkeletonTimeMs": {
+        "maxMs": 5,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 30
+      }
+    },
+    "tokenEfficiency": {
+      "avgCardTokens": {
+        "maxTokens": 350,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 30
+      },
+      "avgSkeletonTokens": {
+        "maxTokens": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      }
+    },
+    "coverage": {
+      "callEdgeCoverage": {
+        "minPercent": 0.1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      },
+      "importEdgeCoverage": {
+        "minPercent": 0.5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    }
+  },
+  "smoothing": {
+    "warmupRuns": 2,
+    "sampleRuns": 3,
+    "outlierMethod": "iqr",
+    "iqrMultiplier": 1.5
+  },
+  "baseline": {
+    "filePath": ".benchmark/baseline.json",
+    "autoUpdateOnPass": false
+  }
+}

package/config/benchmark.ci.windows.config.json

@@ -0,0 +1,86 @@
+{
+  "version": "1.0",
+  "description": "Benchmark threshold configuration for CI regression detection on Windows hosted runners",
+  "thresholds": {
+    "indexing": {
+      "indexTimePerFile": {
+        "maxMs": 800,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 20
+      },
+      "indexTimePerSymbol": {
+        "maxMs": 30,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 80
+      }
+    },
+    "quality": {
+      "symbolsPerFile": {
+        "minValue": 5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "edgesPerSymbol": {
+        "minValue": 1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "graphConnectivity": {
+        "minValue": 0.3,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "exportedSymbolRatio": {
+        "minValue": 0.2,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    },
+    "performance": {
+      "sliceBuildTimeMs": {
+        "maxMs": 2500,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 150
+      },
+      "avgSkeletonTimeMs": {
+        "maxMs": 5,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 40
+      }
+    },
+    "tokenEfficiency": {
+      "avgCardTokens": {
+        "maxTokens": 350,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 30
+      },
+      "avgSkeletonTokens": {
+        "maxTokens": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      }
+    },
+    "coverage": {
+      "callEdgeCoverage": {
+        "minPercent": 0.1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      },
+      "importEdgeCoverage": {
+        "minPercent": 0.5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    }
+  },
+  "smoothing": {
+    "warmupRuns": 2,
+    "sampleRuns": 3,
+    "outlierMethod": "iqr",
+    "iqrMultiplier": 1.5
+  },
+  "baseline": {
+    "filePath": ".benchmark/baseline.windows.json",
+    "autoUpdateOnPass": false
+  }
+}

package/config/benchmark.config.example.json

@@ -0,0 +1,86 @@
+{
+  "version": "1.0",
+  "description": "Benchmark threshold configuration for CI regression detection",
+  "thresholds": {
+    "indexing": {
+      "indexTimePerFile": {
+        "maxMs": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      },
+      "indexTimePerSymbol": {
+        "maxMs": 10,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      }
+    },
+    "quality": {
+      "symbolsPerFile": {
+        "minValue": 5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "edgesPerSymbol": {
+        "minValue": 1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "graphConnectivity": {
+        "minValue": 0.3,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "exportedSymbolRatio": {
+        "minValue": 0.2,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    },
+    "performance": {
+      "sliceBuildTimeMs": {
+        "maxMs": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 25
+      },
+      "avgSkeletonTimeMs": {
+        "maxMs": 5,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 15
+      }
+    },
+    "tokenEfficiency": {
+      "avgCardTokens": {
+        "maxTokens": 250,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      },
+      "avgSkeletonTokens": {
+        "maxTokens": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      }
+    },
+    "coverage": {
+      "callEdgeCoverage": {
+        "minPercent": 0.1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      },
+      "importEdgeCoverage": {
+        "minPercent": 0.5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    }
+  },
+  "smoothing": {
+    "warmupRuns": 2,
+    "sampleRuns": 3,
+    "outlierMethod": "iqr",
+    "iqrMultiplier": 1.5
+  },
+  "baseline": {
+    "filePath": ".benchmark/baseline.json",
+    "autoUpdateOnPass": false
+  }
+}

package/config/benchmark.config.json

@@ -0,0 +1,86 @@
+{
+  "version": "1.0",
+  "description": "Benchmark threshold configuration for CI regression detection",
+  "thresholds": {
+    "indexing": {
+      "indexTimePerFile": {
+        "maxMs": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      },
+      "indexTimePerSymbol": {
+        "maxMs": 10,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      }
+    },
+    "quality": {
+      "symbolsPerFile": {
+        "minValue": 5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "edgesPerSymbol": {
+        "minValue": 1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "graphConnectivity": {
+        "minValue": 0.3,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 5
+      },
+      "exportedSymbolRatio": {
+        "minValue": 0.2,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    },
+    "performance": {
+      "sliceBuildTimeMs": {
+        "maxMs": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 25
+      },
+      "avgSkeletonTimeMs": {
+        "maxMs": 5,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 15
+      }
+    },
+    "tokenEfficiency": {
+      "avgCardTokens": {
+        "maxTokens": 250,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      },
+      "avgSkeletonTokens": {
+        "maxTokens": 200,
+        "trend": "lower-is-better",
+        "allowableIncreasePercent": 10
+      }
+    },
+    "coverage": {
+      "callEdgeCoverage": {
+        "minPercent": 0.1,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      },
+      "importEdgeCoverage": {
+        "minPercent": 0.5,
+        "trend": "higher-is-better",
+        "allowableDecreasePercent": 10
+      }
+    }
+  },
+  "smoothing": {
+    "warmupRuns": 2,
+    "sampleRuns": 3,
+    "outlierMethod": "iqr",
+    "iqrMultiplier": 1.5
+  },
+  "baseline": {
+    "filePath": ".benchmark/baseline.json",
+    "autoUpdateOnPass": false
+  }
+}

package/config/sdlmcp.config.example.json

@@ -0,0 +1,139 @@
+{
+  "repos": [
+    {
+      "repoId": "my-repo",
+      "rootPath": ".",
+      "ignore": [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/.next/**",
+        "**/build/**",
+        "**/.git/**",
+        "**/coverage/**"
+      ],
+      "languages": [
+        "ts",
+        "tsx",
+        "js",
+        "jsx",
+        "py",
+        "go",
+        "java",
+        "cs",
+        "c",
+        "cpp",
+        "php",
+        "rs",
+        "kt",
+        "sh"
+      ],
+      "maxFileBytes": 2000000
+    },
+    {
+      "repoId": "zod-oss",
+      "rootPath": ".tmp/external-benchmarks/zod-oss",
+      "ignore": [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/lib/**",
+        "**/coverage/**",
+        "**/*.test.ts",
+        "**/*.spec.ts"
+      ],
+      "languages": [
+        "ts",
+        "tsx",
+        "js"
+      ]
+    },
+    {
+      "repoId": "preact-oss",
+      "rootPath": ".tmp/external-benchmarks/preact-oss",
+      "ignore": [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/coverage/**",
+        "**/*.test.ts",
+        "**/*.spec.ts",
+        "**/*.test.tsx",
+        "**/*.spec.tsx"
+      ],
+      "languages": [
+        "ts",
+        "tsx",
+        "js",
+        "jsx"
+      ]
+    },
+    {
+      "repoId": "flask-oss",
+      "rootPath": ".tmp/external-benchmarks/flask-oss",
+      "ignore": [
+        "**/.venv/**",
+        "**/venv/**",
+        "**/__pycache__/**",
+        "**/.pytest_cache/**",
+        "**/build/**",
+        "**/dist/**",
+        "**/*.pyc",
+        "**/tests/**"
+      ],
+      "languages": [
+        "py"
+      ]
+    },
+    {
+      "repoId": "ansible-lint-oss",
+      "rootPath": ".tmp/external-benchmarks/ansible-lint-oss",
+      "ignore": [
+        "**/.venv/**",
+        "**/venv/**",
+        "**/__pycache__/**",
+        "**/.pytest_cache/**",
+        "**/build/**",
+        "**/dist/**",
+        "**/*.pyc",
+        "**/test/**",
+        "**/tests/**",
+        "**/.tox/**"
+      ],
+      "languages": [
+        "py",
+        "sh"
+      ]
+    }
+  ],
+  "dbPath": "./data/sdlmcp.sqlite",
+  "policy": {
+    "maxWindowLines": 180,
+    "maxWindowTokens": 1400,
+    "requireIdentifiers": true,
+    "allowBreakGlass": true
+  },
+  "redaction": {
+    "enabled": true,
+    "includeDefaults": true,
+    "patterns": []
+  },
+  "indexing": {
+    "concurrency": 4,
+    "enableFileWatching": false
+  },
+  "slice": {
+    "defaultMaxCards": 60,
+    "defaultMaxTokens": 12000,
+    "edgeWeights": {
+      "call": 1.0,
+      "import": 0.6,
+      "config": 0.8
+    }
+  },
+  "cache": {
+    "enabled": true,
+    "symbolCardMaxEntries": 2000,
+    "symbolCardMaxSizeBytes": 104857600,
+    "graphSliceMaxEntries": 1000,
+    "graphSliceMaxSizeBytes": 52428800
+  }
+}

package/config/sdlmcp.config.json

@@ -0,0 +1,48 @@
+{
+  "repos": [
+    {
+      "repoId": "my-repo",
+      "rootPath": ".",
+      "ignore": [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/.next/**",
+        "**/build/**",
+        "**/.git/**",
+        "**/coverage/**"
+      ],
+      "languages": [
+        "ts",
+        "tsx",
+        "js",
+        "jsx"
+      ],
+      "maxFileBytes": 2000000
+    }
+  ],
+  "dbPath": "./data/sdlmcp.sqlite",
+  "policy": {
+    "maxWindowLines": 180,
+    "maxWindowTokens": 1400,
+    "requireIdentifiers": true,
+    "allowBreakGlass": true
+  },
+  "redaction": {
+    "enabled": true,
+    "includeDefaults": true,
+    "patterns": []
+  },
+  "indexing": {
+    "concurrency": 4,
+    "enableFileWatching": false
+  },
+  "slice": {
+    "defaultMaxCards": 60,
+    "defaultMaxTokens": 12000,
+    "edgeWeights": {
+      "call": 1,
+      "import": 0.6,
+      "config": 0.8
+    }
+  }
+}