sdl-mcp-symbol-delta-ledger

用途

SDL-MCP（Symbol Delta Ledger）是一个以策略为中心的上下文预算层，面向 AI 编程智能体，用于把庞大散乱的代码库转化为紧凑、高信号的上下文。它通过将代码索引成可搜索的符号图，依据 Iris Gate Ladder 升级系统精确供给恰当数量的上下文，据称可实现 4-20 倍的 token 节省。

主要能力

符号卡片（Symbol Cards）：每个函数、类、接口、类型与变量生成约 100 token 的元数据记录，而非约 2000 token 的原始代码。
图切片（Graph Slicing）：沿依赖图（而非目录边界）获取 token 预算内最相关的 N 个符号。
Iris Gate Ladder：四层上下文升级机制，从紧凑卡片逐级提升到完整源码（受策略门控）。
Delta Packs 与影响半径（Blast Radius）：语义变更智能，展示变更的含义以及受影响的代码范围。
实时索引（Live Indexing）：反映未保存编辑器改动的实时代码智能。
按任务形态检索（Task-Shaped Retrieval）：上下文引擎，为 debug/review/implement/explain 任务选择合适的层级与证据。

安装与使用方式

前置条件：需要 Node.js 24 及以上版本。

全局安装：

# Install globally
npm install -g sdl-mcp

# Non-interactive setup with auto-indexing
sdl-mcp init -y --auto-index

# Start MCP server
sdl-mcp serve --stdio

使用 npx：

# Quick start with wrapper
npx create-sdl-mcp

# Or direct npx usage
npx --yes sdl-mcp@latest init -y --auto-index
npx --yes sdl-mcp@latest serve --stdio

MCP 客户端配置（例如 Claude Desktop）：

{
  "mcpServers": {
    "sdl-mcp": {
      "command": "sdl-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

或使用 npx：

{
  "mcpServers": {
    "sdl-mcp": {
      "command": "npx",
      "args": ["--yes", "sdl-mcp@latest", "serve", "--stdio"]
    }
  }
}

主要 CLI 命令包括初始化（sdl-mcp init，支持 -y --auto-index 及 --config-only）、索引（sdl-mcp index，支持 --incremental、--force）、启动服务（sdl-mcp serve --stdio，支持 --verbose）、健康与诊断（sdl-mcp health、sdl-mcp summary --task）以及配置管理（sdl-mcp config get、sdl-mcp config set key=value）。

MCP 工具 API

工具涵盖：符号卡片与搜索（sdl.symbol.card、sdl.symbol.search）、图切片（sdl.slice.build、sdl.slice.refresh）、Iris Gate Ladder 升级（sdl.iris.skeleton、sdl.iris.hotPath、sdl.iris.rawSource）、按任务形态的上下文（sdl.context）、Delta 与影响半径（sdl.delta.pack、sdl.pr.risk.analyze）、实时索引（sdl.buffer.push、sdl.buffer.clear）、沙箱运行时执行（sdl.runtime.execute、sdl.runtime.queryOutput）以及反馈循环（sdl.agent.feedback）。资料中给出了各工具的请求参数示例与常见使用模式（高效代码理解、依赖感知上下文、受控升级、按任务形态检索、变更影响分析、实时开发流、反馈驱动改进），并附有调试认证问题的完整示例流程。

配置

SDL-MCP 将配置存储在 .sdl-mcp/config.json 中，可配置语言开关（typescript、python、go）、索引排除项与并行度、源策略门控（rawSourceGate）、运行时执行允许列表与沙箱约束（cwdJail、timeout）、codeMode 预算以及混合检索阈值等。可通过 sdl-mcp config set 更新。

适用场景

适用于 AI 编程智能体在大型代码库中进行调试、代码评审、功能实现与代码解释等任务，帮助在有限 token 预算下获取高信号上下文，并通过语义差异与影响半径分析判断变更影响与 PR 风险。

限制与注意事项

需要 Node.js 24+；安装时可能出现 peer dependency 警告、tree-sitter 语法问题、索引失败、搜索质量偏低、切片过大或过小、原始源码被策略拒绝、运行时执行被拒或超时等情况，资料给出了相应的排查与配置调整方法。未提供的价格、收费模式等信息暂未提供。