sdl-mcp

GlitterKill活跃维护

给编码 Agent 用的上下文预算层,靠符号图分析把庞大代码库压缩成高信号上下文,省 token、提速并提升输出质量。

Symbol Delta Ledger (SDL-MCP) is a policy-centered context budget layer for coding agents: Symbol-graph intelligence combined with precision tools. It turns sprawling codebases into compact, high-signal context that saves tokens, speeds up workflows, and improves agent output.

v0.13.7发布于 2026-09-07 04:21 UTC498star32fork同步于 2026-11-10 23:57 UTC

怎么上手

由 README 提炼,执行前请确认
npx create-sdl-mcp
npm install -g sdl-mcp
cd <repository>
sdl-mcp init
sdl-mcp doctor
sdl-mcp serve --stdio
硬件要求按 README 说明

README 未说明硬件要求,仅要求 Node.js 24 或更高版本,本地运行

下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

由 README 自动翻译提炼

把代码库索引成符号图,为编码 Agent 提供省 token 的分层上下文

给编码 Agent 用的上下文预算层,靠符号图分析把庞大代码库压缩成高信号上下文,省 token、提速并提升输出质量。

核心能力

  • 把仓库索引成符号图,生成含签名与关系的紧凑符号卡片
  • 按任务或起始符号返回有预算的子图,可溢出扩展
  • 用 Iris Gate Ladder 逐级升级:卡片、骨架、热路径、受策略约束的源码窗口
  • 对比索引版本生成 delta 包并追踪变更影响面,供 PR 风险分析
  • 支持 tree-sitter 结构解析,并可摄取 SCIP 与语言提供方事实

容易踩的坑

需要 Node.js 24 及以上版本;使用前必须先对目标仓库执行 sdl-mcp init 建立索引;SCIP 或 LSP 精确交叉引用需额外配置提供方,未覆盖的文件回退到普通解析路径

内容由模型根据 README 生成,可能不完整或不准确,以官方文档为准。看原文 README

最近发版

5 个版本v0.13.7
  1. v0.13.7SDL-MCP v0.13.7最新正式版2026-09-07 · 2026-09-07 04:21 UTC

    [0.13.7] - 2026-09-06

    Changed

    • Repository-isolated vectors and required rebuild: Symbol vectors now use repository-specific tables and indexes, with exact-query fallback and bounded concurrent access. This keeps retrieval scoped to the requested repository. Schema version 27 requires stopping SDL-MCP and using the documented safe-rebuild workflow when replacing a populated historical shared Symbol-vector table; startup does not migrate it automatically.

    • Saved-file reconciliation: Saved files and watcher events now use targeted background reconciliation. Publication is guarded and atomic, queued save acknowledgements survive deferred work, and retries retain ownership until changes are published. This addresses broad watcher-triggered indexing that could occupy the dispatch queue and delay reads.

    • Explicit enrichment and compact agent workflows: Louvain enrichment now runs only when explicitly requested. Agent workflow guidance defaults to compact responses without diagnostics, reducing routine output and unnecessary background work.

    Fixed

    • Public tool output contracts: Preserve retrieval and agent-slice fields through response projection, retain typed workflow errors, and route low-budget results through continuations. Omit undefined fields before validation, redact runtime output paths, and keep volatile slice lease expiries behind diagnostic opt-in so otherwise valid calls do not fail output validation.

    • Bounded source fallback: Allow targeted raw reads when indexed source is unparseable and structured retrieval cannot serve the request. Document the bounded fallback and close its review gaps so agents can recover without an unnecessary index rebuild.

    • Semantic readiness and shutdown: Preserve vector health through cache invalidation, finalization, and no-change recovery so ready embeddings remain usable and dirty work is not falsely reported as complete. Propagate cancellation, retain LSP disposal ownership until children close, preserve pending reconciliation during shutdown, and keep native script exit codes.

    • Rust call proof and workflow diagnostics: Recognize Rust use aliases in SCIP call proof. Isolate workflow dry runs from indexing side effects and log active dispatch age to help diagnose requests delayed behind long-running work.

    Security

    • Patched dependencies and Windows FTS runtime: Update fast-uri, browserslist, qs, and @humanfs/node resolutions. Pin the Windows x64 OpenSSL runtime to @sdl-mcp/[email protected], bypass stale extension caches, align compatibility probes with LadybugDB 0.19.0, and retry registry propagation checks.

    Performance

    • Retrieval coverage and fresh-vector writes: Cache symbol retrieval coverage and overlap fresh vector writes with inference to reduce repeated retrieval work and idle time during embedding generation. Bound private vector traces and expose their events for measurement.

    Engineering

    • SDLBench cache measurements: Record provider cache efficiency and compare prompt-cache hygiene across products. Remove injected SDL guidance and linked host skills, preserve sterile workdirs, align statistic units, and reject data that cannot support paired claims so benchmark comparisons use consistent conditions.

    • Cross-platform verification: Enable test linting in CI; isolate semantic and watcher fixtures; correct stale assertions, canonical paths, checkpoint ownership, qualification deadlines, and concurrent fixture writes. Fix reconciliation script typing and mutex-drain coverage, and remove obsolete design documents.

    Commits since v0.13.6

    • 26a3e566b64c88b782d32beda841e13571f19593 Preserve retrieval response fields in public contracts
    • 9960b5ed1b2a14682cbccffcd3801a1a5a009e5f docs: design SDLBench prompt-cache metrics
    • 75febb995b6a003408cd446b5e7bdb0258a3f292 docs: clarify SDLBench cache contract
    • b17ef0a7893920c6a7ae45d31958e34fa1149ec8 Propagate cancellation and
  2. v0.13.6SDL-MCP v0.13.62026-08-30 · 2026-08-30 13:21 UTC
    查看更新说明

    [0.13.6] - 2026-08-30

    Changed

    • CPU embedding auto-tuning: Omitted local CPU settings now use physical-core and startup free-memory bounds for embedding concurrency, symbol batch 8, and the physical-core width for automatic ONNX intra-op threads. Auto-detected and pinned performance tiers share these presets, while explicit settings remain authoritative; remove explicit embeddingConcurrency, embeddingBatchSize, or positive onnx.intraOpNumThreads fields to adopt the automatic values.

    • GPU-aware Jina default: Omitted/commonly configured Jina sessions now choose platform-appropriate FP16 or quantized graphs, initialize and cache by effective artifact, verify downloaded models, and invalidate semantic hashes when the effective artifact changes.

    • DirectML session safety: Pinned ONNX Runtime 1.24.3, enforced DirectML-compatible session options, and serialized inference on DirectML sessions.

    • Incremental symbol embedding refresh: Moved symbol vectors to a dedicated shared table, preserved repository ownership and migration behavior, retained live HNSW indexes for bounded updates, and rebuilt them once around larger replacements.

    • Stable global installs: Install global package payloads as stable copies so temporary package-manager paths cannot break the installed CLI.

    Fixed

    • Multi-repository Jina indexing crash: Coalesce bounded incremental symbol-vector replacements into one live-HNSW write, preventing repeated writes from terminating later repository indexes.

    • Workflow continuation compatibility: Accept scalar workflow continuation data without rejecting otherwise valid stored-response flows.

    • Cross-platform test stability: Corrected platform-sensitive regressions and refreshed the retrieval seed artifact used by verification.

    • Windows Ladybug vector tests: Provision the packaged OpenSSL runtime only for tests that require the Ladybug vector extension, while preserving explicit native-disabled coverage elsewhere.

    Engineering

    • Scoped CodeQL analysis: Added scoped CodeQL analysis and documented the warning/status cutover decisions behind the workflow.

    • Complete release-summary coverage: Added full-range, full-OID coverage validation and immutable tagged release-note rendering.

    Commits since v0.13.5

    • f3b6a9df44f222de2c66cbd50c24ec5e587da9ff docs: define release summary coverage contract
    • cf6b4d7e3e7b175b9fcce649cb2ee2a8c3530d3b docs: plan release summary coverage enforcement
    • 66b7df8d4649f48be59f86c1633c656b6cda4193 feat: enforce complete release summary coverage
    • 550b6abbe46a6ffbe38366c5d524cf4de3ca9d6e Install global packages as stable copies
    • 212266c59d4e7dfabe428e328173a8841432b1e2 feat(db): add symbol vector embedding table migration
    • 411f70f191a4e07c727073fd9395c038cab9ff4f test(db): cover schema version 26 migrations
    • 747fc924fb3b9cca3ddc97d4ebbd8282775362a8 feat: store symbol vectors in dedicated table
    • e57d4f782a75a1c9296617e63a5e990b15ca0fa6 perf(index): retain symbol HNSW during incremental refresh
    • c971fd552120327ffe355634ada35ccf939cd168 fix(index): bootstrap symbol HNSW in degraded mode
    • 4a4c080051732d281f0c0ffe42441dcce25e02c1 fix(retrieval): cut over symbol vectors to embedding table
    • 4b0fc78fc19a5ece92ec443a484623e3c2688b84 fix(db): remove orphaned symbol vectors
    • 7da3622a496e9716e038ab08bfe1a1baf91c235b fix(db): preserve shared symbol vectors on repo delete
    • 1f669656edab2b5a5bbf624c5f4d690dfc067a6b fix(db): prune stale SCIP symbol vectors
    • 972857814cad03b5ecd924bee6d1eb1b1a17b2a7 fix(db): prune isolated placeholder vectors
    • b45e22e4a9a296be6b869300b0f176d96e21708d fix(db): preserve shared file symbols on repo delete
    • 89789f398362d83828b37b4e87fbcf6e5e0915eb fix(db): preserve pre-vector migration upgrades
    • 9f311a77b8a2e58e92ab94d8fbd097863d38e93a test(retrieval): refresh seed evaluation artifact
    • `716e4666949915103950c2d83c59e8
  3. v0.13.52026-08-26 · 2026-08-26 01:55 UTC
    查看更新说明

    Added

    • Direct stored-response continuation: Added sdl.retrieve responseGet so agents can page stored responses through the compact Code Mode surface instead of switching to a separate workflow wrapper.

    Changed

    • Continuation registration and recovery: Registered direct response retrieval as non-graph retrieval, kept canonical continuation arguments executable across inline, auto, and handle modes, and synchronized production tool registration.
    • Agent guidance and documentation: Updated SDL instructions, workflow templates, tool recipes, and the Code Mode deep dive to teach direct continuation and the current result-projection contract.

    Fixed

    • Response continuation trust boundary: Reject unknown continuation arguments and nested repository IDs, enforce the continuation envelope, preserve direct recovery actions through projection, and isolate retrieve-schema imports.
    • Delta preview fidelity: Preserve complete delta preview metadata and output fingerprints through projection and paging while rejecting incomplete preview metadata.
    • Strict MCP output schemas: Accept the emitted truncated symbol-card dependency counts and complete retrieval/delta result shapes without weakening validation.
    • Bounded Windows CI tests: Stream per-file progress, terminate hung test process trees after ten minutes, and cap the cross-platform test job at 45 minutes instead of consuming GitHub's six-hour limit.
    • Migration guidance: Restored the exact repo.status detail and file.read response-mode upgrade instructions for the 0.13.4 output-contract migration.

    Engineering

    • Executable contract coverage: Expanded determinism fixtures and focused registration, recovery, schema-wire, continuation-mode, delta paging, and producer-contract tests across the public MCP surfaces.

    34 commits from 1 contributor

    Commits since v0.13.4

    • chore(release): v0.13.5 (2e34d7f9)
    • docs: restore output migration guidance (44194c97)
    • docs: clarify projected delta contract (f5e65d06)
    • fix: preserve delta output fingerprint detail (500e5e15)
    • test: cover delta preview producer contract (23e8bb75)
    • fix: tighten projected delta metadata (b6d09568)
    • fix: align strict MCP output schemas (5d225412)
    • docs: plan delta preview schema tightening (97bbcd62)
    • docs: design delta preview schema tightening (91c18639)
    • Clarify MCP result projection guidance and coverage (4047f900)
    • docs: clarify direct response continuation (ba3bdf58)
    • test: cover production continuation registration (77e44587)
    • test: lock response continuation contracts (fe716da7)
    • test: exercise response continuation modes (1642b0e6)
    • fix: preserve direct response continuation (9a9cedee)
    • fix: reject nested response repository IDs (af9fde6c)
    • fix: enforce response continuation envelope (55926789)
    • docs: plan response continuation review fixes (472f86b5)
    • docs: resolve response continuation review design (79ae50a6)
    • docs: design response continuation review fixes (fce26277)
    • docs: teach direct response continuation (f5b14ea7)
    • fix: isolate retrieve schema import (50fdd3ee)
    • test: classify response continuation as non-graph retrieval (8a1e6d8c)
    • test: reject legacy context recovery shape (2ff016ea)
    • test: expect direct context response continuation (36ab49eb)
    • test: cover response continuation contract (5e20f640)
    • docs: describe Code Mode response continuation (564e1e7e)
    • feat: continue stored responses through sdl.retrieve (faba96a0)
    • fix: reject unknown response continuation args (589e752f)
    • feat: validate direct response continuations (de715b0e)
    • feat: expose response retrieval through sdl.retrieve (270de2e4)
    • docs: plan Code Mode response continuation (3bb335a1)
    • docs: design Code Mode response continuation (fe2b9dc1)
    • Document comprehensive output contracts and observability (5fb3c8a7)
    • fix(ci): bound hanging test processes (a136d56f)
  4. v0.13.4SDL-MCP v0.13.42026-08-24 · 2026-08-24 13:20 UTC
    查看更新说明

    Added

    • Model-facing output contracts: Added deterministic compact, standard, and full projections, combined response budgets, explicit diagnostic opt-in, sanitized artifact handles, and public-schema validation.
    • Tool-output observability: Added projection telemetry, bounded health aggregation, and dashboard visibility for response size, truncation, artifact use, and contract failures.
    • Durable lifetime metrics: Added repository-scoped cumulative sessions, bounded capacity and overflow accounting, locked generation persistence, crash recovery, read-only reload, coordinated checkpoints, and shutdown persistence.
    • Accessible dashboard editing: Added deterministic persisted layouts, keyboard and pointer panel editing, safe cancellation/reset behavior, metric scope and freshness modeling, and durable lifetime panels.

    Changed

    • Compact responses by default: Status, usage, action discovery, retrieval, workflow, and runtime surfaces now favor bounded model-facing output. Large file reads, deltas, and response artifacts use recoverable paging handles.
    • Workflow and runtime projection: Removed redundant success metadata while preserving canonical results for piping and accounting. Failures now propagate explicit error details and recoverable output.
    • Agent safety boundaries: Index refresh requires explicit approval, repository inspection is routed away from runtime commands, and structural versus semantic staleness now produces safer recovery guidance.
    • Context and retrieval behavior: Refined context coverage, separated semantic detail from diagnostics, aligned projected code output, clarified PR-risk output, and made same-version deltas explicit successes.

    Fixed

    • Recovery and paging: Recovery actions are executable, typed, registered, and preserved through cyclic or deeply nested errors. Workflow truncation, response paging, runtime output, file reads, and deltas retain usable recovery paths.
    • Lifetime observability correctness: Hardened admission bounds, repository attribution, locking, crash cleanup, publication generations, aliases, checkpoints, HTTP/SSE delivery, and shutdown races.
    • Dashboard correctness: Hardened malformed-envelope handling, timestamp ordering, layout coordinates, nested controls, reset barriers, replay protection, polling, and same-repository client races.
    • CI, installation, and runtime reliability: Restored packed Windows FTS verification, isolated memory-test repositories, added native-crash retry diagnostics, verified LadybugDB after global installation, fixed Kotlin grammar-wrapper loading, and repaired workflow argument injection and family projections.

    Engineering

    • Public contract verification: Added schema-node coverage and executable verification across every public non-mutating action, isolated mutating-tool checks, deterministic inventory enforcement, and LF-stable generated documentation.
    • HNSW benchmarking: Added the reviewed scalar-quantization benchmark design, aggregation protocol, compatibility requirements, and implementation plan.
    • Agent workflow maintenance: Preserved benchmark and slice-projection compatibility, updated synchronized workflow expectations, and removed the obsolete skill-loading hook.

    166 commits from 1 contributor

    Commits since v0.13.3

    • chore(release): v0.13.4 (3e72bc5f)
    • Reuse projected response schema for public model validation (6585803c)
    • Fix runtime recovery output and grammar wrapper loading (ec6490b6)
    • Fix workflow family result projection (f9dbcdcd)
    • Validate repo status responses against their public schema (58ceadba)
    • Fix workflow argument injection and response paging (6d7ee62f)
    • Stabilize workflow and runtime response projections (bc31588d)
    • test(contract): finalize all-tool verification (01206081)
    • docs(contract): define projection and recovery guarantees (ddee35f1)
    • test(contract): isolate mutating tool coverage (95248840)
    • test
  5. v0.13.3SDL-MCP v0.13.32026-08-08 · 2026-08-08 20:22 UTC
    查看更新说明

    Added

    Changed

    Fixed

    • Engine-affine live parsing and graph integrity: Added the native parseContent native:1 contract, persisted exact file/repository parser provenance, and made live drafts and saved-file reconciliation reuse the engine that created durable symbols without cross-engine fallback. Graph verification and complete parser coverage now publish together for the same version/revision, while phase failures and contract mismatches fail closed. Migration 25 creates the provenance schema, but pre-provenance indexes require SDL-MCP to be stopped and rebuilt with sdl-mcp index --force --safe-rebuild <absolute-new-path>.
    • Cross-platform HNSW benchmark fixtures: Derived benchmark source paths with Node's platform-native resolver so parser tests validate absolute paths on both Windows and Ubuntu.
    • Code-scanning hardening: Replaced polynomial regex paths with linear processing and encoded generated Codex hook paths before shell execution.

    Commits since v0.13.2

    • Release v0.13.3 (c63e0bc3)
    • Preserve semantic readiness for intentional embedding backlogs (8e1a0cfc)
    • Increase recovery test timing margins (8493b353)
    • Route branch-built addon through Windows FTS regression tests (17bee305)
    • Normalize structured LSP diagnostic messages (e1e19c29)
    • Preserve graph-integrity worker errors and revision safety (49b574d8)
    • Preserve native symbol IDs in parity checks (a51ecbcf)
    • fix: complete markdown table escaping (0c4f1ee9)
    • Report native addon diagnostics in doctor checks (c2b5bb83)
    • Align safe rebuilds with in-session HNSW lifecycle (ffaa3271)
    • fix: harden parser coverage shadow copies (d0aa822d)
    • docs: clarify partial parser coverage (54825a75)
    • fix: reject null parser provenance ownership (fe1d3520)
    • fix: decouple graph verification from parser coverage (5ad3a128)
    • Remove obsolete implementation plans (50d7bece)
    • fix(native): isolate live content parsing (84c10ce7)
    • docs: explain engine-affine live parsing (2a2b2b6b)
    • test(live-index): cover native mjs integrity (b7cf9a31)
    • fix(live-index): keep parser identity engine-affine (8cd2b4af)
    • feat(live-index): dispatch by parser identity contract (d914aa82)
    • feat(indexer): bind parser provenance to graph verification (2fd958b5)
    • feat(db): persist parser provenance coverage (fd1ffd6b)
    • feat(indexer): define parser identity contracts (5b5a6951)
    • feat(indexer): expose native content parser capability (572be753)
    • feat(native): parse in-memory source content (fb7ae558)
    • docs: plan engine-affine live parsing (59ab1cbc)
    • docs: design engine-affine live parsing (a3523302)
    • Harden code scanning against regex backtracking and shell injection (6e8d6b43)
    • test: make HNSW benchmark fixtures portable (33d9a6b6)

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

    Symbol Delta Ledger

    Cards-first code context for AI coding agents.

    Get started · Documentation · MCP tools · npm

    npm version npm downloads GitHub commit activity RoastMyCode: A CI Supported Node.js

    Work from the symbols that matter

    SDL-MCP indexes a repository into a symbol graph and gives coding agents a controlled path from compact metadata to source code. Instead of starting with full files, an agent can search symbols, inspect cards, build a task-scoped slice, and request a bounded code window only when it needs one.

    The result is a smaller, more deliberate context surface for debugging, reviews, implementation work, and repository exploration. SDL-MCP runs locally and supports the Model Context Protocol over stdio or HTTP.

    Start in a few minutes

    SDL-MCP requires Node.js 24 or later. For an interactive first install, run the wrapper package from the repository you want to index:

    npx create-sdl-mcp
    

    For a standard global install, initialize the repository, verify it, then start the stdio server:

    npm install -g sdl-mcp
    cd <repository>
    sdl-mcp init
    sdl-mcp doctor
    sdl-mcp serve --stdio
    

    Use sdl-mcp init -y --auto-index for non-interactive setup. The Getting Started guide covers the setup wizard, supported clients, HTTP transport, and configuration examples.

    A controlled retrieval loop

    1. Index the repository into symbols, relationships, and compact metadata.
    2. Start with symbol search, task-shaped context, or graph slicing.
    3. Escalate through progressively richer views only when the task requires more detail.

    The Iris Gate Ladder makes the escalation explicit. Cards, skeletons, hot paths, and policy-gated source windows let an agent ask for the least code that can answer its question.

    Choose the tool surface that fits the client

    The generated tool inventory is the source of truth for registered tools and mode counts.

    ModeRegistered surface
    Flat38 tools: 2 universal tools and 36 flat tools
    Gateway6 tools: 2 universal tools and 4 gateway namespaces
    Gateway with legacy42 tools: 2 universal, 4 gateway, and 36 flat tools
    Code Mode exclusive7 tools: sdl.action.search, sdl.context, sdl.file, sdl.info, sdl.manual, sdl.retrieve, and sdl.workflow

    Code Mode provides a compact task-oriented surface. Gateway mode groups the regular actions into sdl.agent, sdl.code, sdl.query, and sdl.repo. The MCP Tools Reference explains requests and responses for the installed surface.

    Build context from repository structure

    Symbol cards

    Each indexed symbol has a compact card with its identity, signature, summary, relationships, and other retrieval metadata. Cards give an agent a place to begin without opening a full source file.

    Graph slicing

    Graph slicing follows repository relationships rather than directory boundaries. Give SDL-MCP a task or a starting symbol and it returns a budgeted subgraph that can be refreshed or expanded through spillover.

    Read about graph slicing · Read about task-shaped context

    Understand change and work against current code

    Delta packs and blast radius

    SDL-MCP can compare indexed versions, identify changed symbols, and trace affected relationships. sdl.pr.risk.analyze packages change evidence and test recommendations for pull-request review.

    Live indexing

    Draft-buffer updates can appear in a live overlay before the underlying file is saved. An accepted save then queues targeted reconciliation; configured SCIP, LSP, or parser preparation runs in the background and publishes only the latest saved generation. Retrieval continues from the committed graph and, when present, the overlay while that work prepares.

    Read about delta packs · Read about live indexing

    Use compiler and provider facts when they are available

    SDL-MCP uses tree-sitter for repository structure and can ingest SCIP and language-provider facts through provider-first indexing. This adds precise cross-references where a provider covers the file and falls back to the regular path for files it does not cover.

    Read about SCIP integration · Read about provider-first indexing

    Keep useful knowledge with the work

    Development memories are opt-in. When enabled, they store decisions and task notes with repository links so later work can retrieve them alongside the relevant context. Memory behavior and storage rules are documented in the Memory Protocol.

    Keep tool registration compact

    Gateway mode reduces the visible regular action surface to four namespace tools while preserving server-side validation and routing. Use it when a client benefits from fewer tool choices; use the flat surface when direct tool names are more useful.

    Read about the Tool Gateway · Read about Code Mode

    Operate the repository with guardrails

    Policy settings govern raw source windows. The runtime execution surface also applies configured executable, working-directory, environment, concurrency, and timeout controls. For HTTP deployments, SDL-MCP includes the graph viewer and observability dashboard.

    Governance and policy · Runtime execution · Graph viewer · Observability dashboard

    Documentation map

    If you need to...Start here
    Install, connect an agent, or choose a transportGetting Started
    Inspect the current MCP surfaceGenerated Tool Inventory and MCP Tools Reference
    Configure a repositoryConfiguration Reference and Configuration Examples
    Run CLI commandsCLI Reference
    Follow retrieval and editing workflowsAgent Workflows
    Diagnose setup or runtime issuesTroubleshooting
    Browse every public documentDocumentation Hub

    License

    SDL-MCP is source-available. The Community License permits use, running, and modification, including internal business use. A commercial license is required before selling, licensing, sublicensing, bundling, embedding, or distributing SDL-MCP as part of a monetized product.