dsh-mcp-server-clangd

把 clangd 包成一个 stdio MCP server，向 DSH（DeepSeek Harness）里的 agent 暴露 7 个只读的 C/C++ 语义查询工具：定义、悬停、引用、诊断、文档符号、工作区符号、健康检查。

• 零第三方依赖：MCP JSON-RPC 与 LSP 客户端都是手写的（Node.js ≥ 20，ESM，只用 node: 内置模块）。

• 只读：不发送 rename / format / codeAction / applyEdit，不写你的源码。

• 位置统一 1-based（行、列），列按 UTF-16 码元计；内部再转成 LSP 的 0-based。

• 业务失败不抛给 MCP 层：始终返回 {ok:false, code, message, hint, details}，isError 为 false，agent 能读懂错误并自行纠正参数。

为什么需要它

clangd 只说 LSP，DSH agent 只会调 MCP 工具。中间这层桥负责：

1. 管好 clangd 进程（懒启动、崩溃重启、退出清理）；

2. 把 compile_commands.json、路径白名单、文件大小、请求超时这些工程性约束前置成结构化错误；

3. 把 LSP 的 0-based 位置、Location | LocationLink、MarkupContent 等细节归一成稳定的 JSON。

Related MCP server: mcp-lsp-v1

工具

在 DSH 里，工具全名是 mcp__clangd-bridge__clangd_definition 这种形式（取决于 serverName）。

公共参数

• file：绝对路径，或相对 projectRoot 的路径；必须落在 allowedRoots 内，扩展名必须是 C/C++ 头/源文件。

• line / column：1-based 整数；超出文件范围返回 POSITION_OUT_OF_RANGE，不静默 clamp。

• limit：1..200，默认取配置 maxResults（200）。

成功/失败信封

{ "ok": true, "file": "D:/proj/a.cpp", "locations": [], "truncated": false, "meta": { "elapsedMs": 12, "clangdPid": 1234, "truncated": false, "slow": false } }

{ "ok": false, "code": "PATH_OUTSIDE_ALLOWED_ROOTS", "message": "路径不在允许范围内", "hint": "把该目录加入 allowedRoots，或改用 projectRoot 内的文件", "details": { "file": "C:/Windows/win.ini" } }

meta.slow 在耗时超过 5 秒时为 true；meta.documentVersion 只在文档类工具里出现。

列表类工具（definition / references / diagnostics / document_symbols / workspace_symbols）的 truncated 同时出现在顶层与 meta.truncated（两者一致），严格 schema 直接取顶层即可；clangd_references 的顶层字段是 locations（不是 references）。

安装与运行

要求：Node.js ≥ 20；一个可用的 clangd；目标工程有 compile_commands.json（CMake 加 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON，或 bear/compiledb 生成）。

# 1) 放到任意位置（目录名可以带空格）
# 2) 准备配置
copy clangd-bridge.example.json clangd-bridge.json
# 3) 自检
node src/server.js --config clangd-bridge.json --print-config

也可以直接用环境变量跑，不写配置文件：

$env:CLANGD_PATH = "D:/Code/llvm/bin/clangd.exe"
$env:CLANGD_PROJECT_ROOT = "D:/proj/build"
node src/server.js

配置

优先级：CLI --config > 环境变量 > 配置文件 > 默认值。配置文件默认从 cwd/clangd-bridge.json 读，也可用 CLANGD_BRIDGE_CONFIG 指定。

环境变量：CLANGD_BRIDGE_CONFIG、CLANGD_PATH、CLANGD_PROJECT_ROOT、CLANGD_COMPILE_COMMANDS_DIR、CLANGD_ALLOWED_ROOTS（分号分隔）、CLANGD_REQUEST_TIMEOUT_MS、CLANGD_LOG_LEVEL。

env 只接受白名单键（PATH、INCLUDE、LIB、LIBPATH、SYSTEMROOT、TEMP、TMP、USERPROFILE、COMSPEC、PATHEXT、CLANGD_* 等）；其他键会被 CONFIG_INVALID 拒绝，避免把 API key 之类的东西塞进子进程。

在 DSH 里注册

本仓库不会自动改你的 DSH profile。把下面片段合并进对应 agent preset 的 cordis.patch.yml（或设置页的 MCP 配置），然后重载：

- id: mcp-clangd-bridge
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: clangd-bridge
    transport: stdio
    command: 'C:\Program Files\nodejs\node.exe'
    args:
      - 'D:/workplace/dsh-mcp-server-clangd/src/server.js'
    env:
      CLANGD_BRIDGE_CONFIG: 'D:/workplace/dsh-mcp-server-clangd/clangd-bridge.json'
    toolCallTimeoutMs: 120000
    failOnStartupError: false
    reconnect:
      enabled: true
      initialDelayMs: 1000
      maxDelayMs: 10000
      maxAttempts: 3

注意：initialize 阶段不会启动 clangd（只做进程内检查），所以 DSH 的 stdio 探活不会因为大工程索引而超时；第一次真正查询或 clangd_health {start:true} 才拉起进程。

错误码

只读保证与副作用

• 桥只发 initialize、textDocument/didOpen|didChange|didClose、definition、hover、references、documentSymbol、workspace/symbol、shutdown。

• 不发 rename、formatting、codeAction、applyEdit、workspace/executeCommand。

• 唯一的磁盘副作用来自 clangd 自己：在 compileCommandsDir 下写 .cache/clangd/index（--background-index 时）。桥不写源码、不生成 compile db。

• 日志写到临时目录（或配置的 log.dir）与 stderr，不污染 stdout。

诊断与重启语义：

• 诊断缓存按 URI 管理：首次 didOpen 与内容变化 didChange 之前清空该 URI 的旧诊断，只有内容未变（mtime/size 相同）时才复用缓存——避免把上一次的诊断当成当前结果。

• clangd 退出/重启时清空全部诊断缓存与文档记录（不发 didClose）；下一次查询会重新 didOpen（version 从 1 开始），并重新等待 publishDiagnostics。

• clangd_health 的 checks 包含 log.dir 与 queryDriver 两项：前者校验日志目录在 projectRoot/系统临时目录内，后者在启用时给出高风险警告、被禁用时给出原因。

测试与验收

npm test          # 单元 + 集成（集成组需要 clangd，找不到时自动 skip）
npm run accept    # 场景化验收：A health / B definition / C diagnostics / D 缺 compile db / E 路径越界 …

npm test 不联网、零依赖；集成组会真实启动 clangd，约 2 秒跑完（fixture 很小）。

fixtures 的 compile_commands.json 不入库：测试与验收脚本会读 compile_commands.template.json，把 {{CLANGXX}}、{{FIXTURE_DIR}} 换成本机值后再生成。编译器默认取 clangd-bridge.json 里 clangd 同目录的 clang++，也可以用 CLANGXX 指定：

$env:CLANGXX = 'D:/llvm/bin/clang++.exe'
npm test

Windows 注意：某些 DSH 沙箱会拦截 Node 子进程的管道（spawn EPERM）。npm test / npm run accept 请在普通终端或 danger-full-access 下运行；这不是桥的问题。

已知限制（v0.1）

• 只读；没有补全、重命名、格式化、代码操作。

• clangd_definition 在 backgroundIndex:false 且没有索引时，跨翻译单元可能只返回头文件里的声明（clangd 行为，不是桥的裁剪）。

• MSVC 风格的 compile db 可以读（compilerKind:"msvc"），但 clangd 对 cl.exe 参数的理解有限，诊断可能有假阳性；clangd_health 会给出警告。

• 不做 --enable-config（避免读到用户 .clangd 之外的隐式行为），需要时自行在 extraArgs 思路之外扩展。

• 一台机器上多个 DSH 会话会各自起一个 clangd；v0.1 不做跨进程复用。

目录

src/
  server.js          MCP stdio 层（换行分隔 JSON-RPC）
  config.js          配置合并/校验/环境变量
  compileDb.js       compile_commands.json 检查
  errors.js          错误码与中文 hint
  log.js             stderr + 文件日志（轮转）
  paths.js           URI/位置/白名单/文件读取
  lsp/
    framing.js       Content-Length 分帧
    client.js        clangd 进程 + LSP 请求/通知
    documents.js     didOpen/didChange/LRU
    normalize.js     LSP 结果 → 稳定 JSON
  tools/             7 个工具的实现
tests/               unit / integration / fixtures（compile_commands 由模板生成）
scripts/accept.mjs   场景化验收

License

MIT