GlitterKill/sdl-mcp

# SDL-MCP      SDL-MCP (Symbol Delta Ledger MCP Server) 是一个面向编码 Agent 的以卡片为优先的上下文系统。 SDL-MCP 不再首先打开大文件，而是将仓库索引化为符号卡片和图边，以便 Agent 可以： - 首先搜索和检索小型、结构化的上下文 - 使用 token 预算构建特定任务的图切片 - 通过版本间的增量刷新上下文 - 通过策略控制的访问请求代码窗口 ## 为什么它有助于编码 Agent - 默认通过卡片/切片/骨架降低 token 使用量 - 通过依赖感知的上下文检索实现更好的相关性 - 通过策略控制和审计实现更安全的上下文访问 - 通过增量索引和刷新工作流实现更快的迭代 - KuzuDB 支持的图持久化意味着索引只需进行一次，而不是每次会话都进行 - 符号卡片和切片中包含置信度感知的调用解析过滤和 pass2 来源 - 支持 TypeScript, JavaScript, Python, Go, Java, C#, C, C++, PHP, Rust, Kotlin, 和 Shell ## Claude Opus 4.6 高层概述 问题：“审查 SDL-MCP 的代码，并向潜在新用户解释这个 MCP 服务器的作用以及使用它的好处。” 回答：“# 什么是 SDL-MCP？ **SDL-MCP** (Symbol Delta Ledger - Model Context Protocol) 是一个 MCP 服务器，它从根本上改变了 AI 编程助手与您的代码库交互的方式。SDL-MCP 不再将整个文件倾倒到 AI 的上下文窗口中，而是提供 一种结构化、token 高效的方式，为 AI Agent 提供所需的精确代码上下文——仅此而已。 ## 它解决的问题 当像 Claude 这样的 AI 助手处理代码时，它们通常会读取整个文件——有时是许多文件——以了解 足够的上下文来帮助您。这是一种浪费： - **上下文窗口很快被填满。** 一个适度的代码库很容易超过 token 限制。 - **不相关的代码稀释了注意力。** AI 花费 token 处理与您的任务无关的代码。 - **不知道发生了什么变化。** 每次交互都从零开始，没有增量理解。 SDL-MCP 通过维护代码库的**持久化、索引化理解**并通过 **Iris Gate Ladder** 提供上下文来解决 这三个问题。 ## 它是如何工作的 ### 1. 符号索引 SDL-MCP 默认使用 Rust 原生索引器解析您的 TypeScript/JavaScript 代码库，并以 TypeScript tree-sitter 路径作为回退，将 每个函数、类、接口、类型和变量提取为 **Symbol Cards** —— 包含以下内容的紧凑元数据记录： 符号的签名、简要摘要、依赖边以及如扇入/扇出等指标。 统计数据不言自明：此仓库在 **1,553 个文件**中包含 **11,475 个符号**，并跟踪了 **261,813 条依赖边**。完整的卡片转储大约需要 230 万个 token。而概览仅需 **825 个 token** —— 压缩比高达 **2,782 倍**。 ### 2. Iris Gate Ladder (4 个阶梯) SDL-MCP 不再说“这是整个文件”，而是使用 **Iris Gate Ladder** 逐步提供详细上下文。这种方法确保 AI Agent 拥有有效的最小上下文，从而节省您的 token 预算。 | 阶梯 | 工具 | 预估 Token | 何时使用 | |------|------|------------|-----------| | **1. Symbol Cards** | `sdl.symbol.getCard` | ~50 tokens | 始终从这里开始：签名、摘要和依赖项。 | | **2. Skeleton IR** | `sdl.code.getSkeleton` | ~200 tokens | 了解不含函数体的逻辑流程和结构。 | | **3. Hot-Path Excerpt** | `sdl.code.getHotPath` | ~500 tokens | 验证上下文中特定标识符的用法。 | | **4. Raw Code Window** | `sdl.code.needWindow` | ~2,000 tokens | 最后的手段：通过策略控制访问完整源码。 | 大多数问题可以在第 1-2 阶梯解决，而无需阅读原始代码。 ### 3. Graph Slices 当 AI 需要理解任务周围的上下文时，SDL-MCP 会构建一个 **任务范围子图** —— 由调用、导入和配置边连接的相关 符号切片，按相关性评分并受 token 预算限制。这意味着 AI 获取的是与任务最相关的 20-30 个符号，而不是任意的目录列表。 ### 4. Delta Packs 当代码发生变化时，SDL-MCP 计算**符号级别的差异** —— 不是行级差异，而是对签名、不变量和副作用的语义更改。 它还计算**影响范围**：哪些其他符号受变更影响， 按接近度和重要性排名。 ### 5. Proof-of-Need Gating (需求证明门控) 原始代码访问需要理由。AI 必须说明*为什么*需要代码，*期望找到什么标识符*，以及*需要多少行*。请求会被审计。 这可以防止懒惰的“直接读取整个文件”模式，并 保持 token 使用受到约束。 ## 主要优势 **对于 AI 辅助开发：** - 与读取原始文件相比，每个编码任务**减少 10-50 倍 token** - **更相关的上下文** —— 基于图的切片能找到基于目录的方法容易遗漏的相关代码 - **增量理解** —— delta packs 意味着 AI 不会重新阅读未更改的代码 - **审计追踪** —— 每次原始代码访问都会记录理由 **对于大型代码库：** - 扩展到数千个文件而不会耗尽上下文窗口 - 符号级别的跟踪可以经受空格更改和琐碎的重构 - KuzuDB 支持的图持久化意味着索引只需进行一次，而不是每次会话都进行 **对于团队：** - 通过可配置的策略实现一致的上下文治理 - 影响范围分析在变更落地前展示其连锁反应 - 作为标准 MCP 服务器运行 —— 兼容任何支持 MCP 的客户端 ## 实际设置 SDL-MCP 作为 CLI 运行，包含 5 个命令： ``` sdl-mcp init # Create config + graph DB path sdl-mcp index # Index your repositories sdl-mcp serve # Start the MCP server (stdio or HTTP) sdl-mcp doctor # Health check sdl-mcp version # Version info Once running, any MCP client (Claude Code, Claude Desktop, etc.) connects to it and gains access to 24 tools for navigating your codebase efficiently. --- In Summary SDL-MCP is a code context server that treats your codebase like a searchable knowledge graph rather than a pile of text files. It gives AI assistants surgical access to exactly what they need, dramatically reducing token waste while improving the quality of code understanding. Think of it as giving your AI a proper IDE-level understanding of your code, rather than having it grep through files." ## 快速开始 ### 安装 ```bash npm install -g sdl-mcp ``` 或者在不全局安装的情况下运行： ``` npx --yes sdl-mcp@latest version ``` ### 配置和初始化 ``` # 提示：如果你使用的是 npx，请将 `sdl-mcp` 替换为 `npx --yes sdl-mcp@latest`。 # 1) 设置 config 位置变量，然后打开一个新终端 setx SDL_CONFIG_HOME "C:\[your path]" # 2) 单行非交互式设置（包含 inline index + doctor） sdl-mcp init -y --auto-index --config "C:\[same path as SDL_CONFIG_HOME]" # 3) 启动 MCP server（用于编码 agent 的 stdio） sdl-mcp serve --stdio # 可选：启动 HTTP transport 用于 graph explorer + REST endpoints sdl-mcp serve --http --host localhost --port 3000 # 可选：如果你的环境存在 watcher 不稳定性，请禁用 watch mode sdl-mcp serve --stdio --no-watch # 4) 从 agent-workflows.md 复制 agent 指令，并将其粘贴到你项目的 AGENTS.md 文件中。 ``` ## 核心功能集 - 使用 tree-sitter 适配器进行多语言仓库索引 - 默认使用原生 Rust pass-1 索引引擎 (`indexing.engine: "rust"`，TypeScript 回退) - 实时编辑器缓冲区索引，支持草稿感知的符号/搜索/切片读取、保存时的 Kuzu 补丁、后台协调和自动检查点压缩 (`liveIndex.*`) - 包含签名、依赖项、指标和版本控制的 Symbol cards - 包含句柄、租约、刷新和溢出的 Graph slices - 图增强：在卡片/切片/概览/影响范围中展示聚类（社区检测）+ 流程（调用链追踪） - 通用 pass2 解析器注册表，包含 TypeScript/JavaScript 语义 pass2 和 Go pass2，通过 `symbol.getCard` 和 `slice.build` 提供置信度评分的调用元数据 - 支持放大器评分的 Delta 分析和影响范围 - 语义符号搜索重排序 (`sdl.symbol.search` 并设置 `semantic: true`) - LLM 生成的符号摘要，支持可配置的并发和批处理 (`semantic.summaryModel`, `summaryMaxConcurrency`, `summaryBatchSize`) - 代码访问阶梯：`getSkeleton` -> `getHotPath` -> `needWindow` - 策略管理 (`sdl.policy.get` / `sdl.policy.set`) - 仓库概览和热点检查 (`sdl.repo.overview`) - PR 风险分析 (`sdl.pr.risk.analyze`) - Agent 编排工具 (`sdl.agent.orchestrate`) - 带有状态指标的预测性预取启发式算法 (`prefetchStats`) - 用于高效增量索引的文件监视防抖 (`indexing.watchDebounceMs`) - 用于编辑器缓冲区解析和空闲检查点的实时覆盖控制 (`liveIndex.debounceMs`, `liveIndex.idleCheckpointMs`, `liveIndex.maxDraftFiles`) - 符号卡片中的规范测试映射 (`metrics.canonicalTest`) - Graph HTTP 接口和浏览器探索器 (`/api/graph/*`, `/ui/graph`) - `sdl-mcp-vscode/` 中的 VSCode 扩展 MVP - 同步构件导出/导入/拉取工作流 ## CLI 命令 - `init` - 引导配置和可选的客户端模板 - `doctor` - 验证运行时、配置、数据库路径、语法、仓库访问和调用解析能力 - `index` - 索引仓库（可选监视） - `serve` - 运行 MCP 服务器 (`--stdio` 或 `--http`) - `export` - 导出同步构件 - `import` - 导入同步构件 - `pull` - 按版本/提交拉取并带有回退行为 - `benchmark:ci` - 运行 CI 基准检查，包括边缘精度回归门控 - `summary` - 生成 token 受限的复制/粘贴上下文摘要 - `health` - 计算复合索引健康分数和徽章/json 输出 - `version` - 显示版本和环境信息 ## MCP 工具 - Repository: `sdl.repo.register`, `sdl.repo.status`, `sdl.repo.overview`, `sdl.index.refresh` - Symbols: `sdl.symbol.search`, `sdl.symbol.getCard` - Context: `sdl.context.summary` - 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` 参见：[MCP 工具参考](./docs/mcp-tools-reference.md) ## 文档 - [文档中心](./docs/README.md) - [Iris Gate Ladder](./docs/IRIS_GATE_LADDER.md) - 上下文升级方法论 - [架构](./docs/ARCHITECTURE.md) - 技术栈和数据流 - [入门指南](./docs/getting-started.md) - [CLI 参考](./docs/cli-reference.md) - [MCP 工具参考](./docs/mcp-tools-reference.md) - [配置参考](./docs/configuration-reference.md) - [Agent 工作流](./docs/agent-workflows.md) - [故障排除](./docs/troubleshooting.md) - [VSCode 扩展 README](./sdl-mcp-vscode/README.md) - [旧版用户指南](./docs/USER_GUIDE.md) ## 开发 ``` npm run build npm run typecheck npm run lint npm test # 可选 native addon + parity checks npm run build:native npm run test:native-parity ``` 基准测试工具 (npm 脚本): - `npm run benchmark:real` - `npm run benchmark:matrix` - `npm run benchmark:sweep` Phase A 基准锁定文件： - `scripts/benchmark/phase-a-benchmark-lock.json` 锁定 TS/Python/Tier-3 仓库，用于可复现的基线运行。 ## 许可证 本项目是**源码可用**的。 - **免费使用 (社区许可证)：** 您可以根据 [`LICENSE`](./LICENSE) 中的条款将本软件用于任何目的，包括**内部商业用途**，包括使用、运行和修改本软件。 - **商业分发/嵌入：** 在**销售、许可、再许可、捆绑、嵌入或分发**本软件（或修改版本）**作为付费或货币化产品或服务的一部分之前**，您必须获得**商业许可证**。参见 [`COMMERCIAL_LICENSE.md`](./COMMERCIAL_LICENSE.md)。 如果您不确定您的使用是否属于“商业分发/嵌入”，请联系 **gmullins.gkc@gmail.com**。

标签：AI编程助手, KuzuDB, MCP服务器, MITM代理, RAG, Rust, SOC Prime, Token优化, WebSocket, 上下文窗口, 上下文管理, 代码图谱, 代码导航, 代码检索, 依赖分析, 可视化界面, 增量更新, 开发工具, 暗色界面, 符号索引, 策略控制, 结构化数据, 编码智能体, 网络流量审计, 自动化攻击