Qwen DAP MCP — C/C++ Debugger for Claude Code, Codex & Qwen

Qwen DAP MCP — 面向 Claude Code、Codex、Qwen 和 AI 编码 Agent 的原生调试器 MCP

使用 Claude Code、OpenAI Codex CLI、Qwen Code、Gemini CLI 和其他兼容 MCP 的本地编码 Agent，调试原生 C/C++ 崩溃、挂起、死锁、Windows minidump 和 core dump。 通过调试适配器协议（DAP）和模型上下文协议（MCP）连接真正的 GDB、LLDB 或 CodeLLDB 调试器。

qwen-dap-mcp 是一个本地的 调试适配器协议（DAP）→ 模型上下文协议（MCP） 桥接工具，用于原生崩溃调试、挂起/死锁排查、崩溃转储、差分运行时分析、远程目标，以及有范围约束的修复/验证工作流。

最初为 Qwen Code 设计，但也可与其他本地 stdio MCP 客户端搭配使用，包括 Claude Code 和 Codex CLI。AI 模型可以在云端运行；调试器桥接工具和目标二进制文件仍运行在启动 MCP 进程的环境中。

快速开始 · 功能 · 调试器支持 · 安全设计 · 文档 · 参与贡献

由 SLP-DEV1 维护的原项目 Apache-2.0 分支。 维护中的源代码位于 spk-c/Qwen-dap-mcp；npm 发布 @slp-dev1/qwen-dap-mcp。GitHub 的 main 可能比最新发布的 npm 版本更新。请参阅分支说明和 TypeScript 迁移状态。

实际演示：C++ 崩溃 → 证据 → 验证

这是架构/工作流示意图，并非录制的 AI 会话或虚构的调试器记录。 在项目自带的 C++ 测试样例中复现一次真实的故意崩溃，收集 GDB 回溯，在仅限临时副本中应用示意性更改，然后运行同一命令：

bash scripts/demo-native-crash.sh

需要 Linux、g++ 和 gdb。CI 也会使用真实调试器运行此演示。查看分步验证演示和 Claude/Codex MCP 设置指南。

存在的原因

编码 Agent 可以读取源代码并提出补丁，但仅凭源代码往往无法可靠地诊断原生故障。真正有用的证据存在于运行时：线程堆栈、寄存器、局部变量、反汇编、异常状态、模块、内存、等待状态、符号和崩溃转储。

qwen-dap-mcp 通过 MCP 提供这些证据，并在原始调试器基本操作之上增加了面向 Agent 的工作流：

• 证据优先 — 检查实际发生故障的进程，而不是根据源代码猜测。
• 高级工作流 — 崩溃、挂起、差异分析、因果追踪、进度探测、运行时报告、转储和验证工具均为 Agent 设计，而非供人操作调试器控制台。
• 有界自动化 — 自主修复／验证状态明确且可序列化，并限制迭代次数，还会重新检查原始复现条件。
• 默认界面精简 — 默认显示 18 个核心 Agent 工具；取证工作流和原始 DAP 控制则作为单独的可选层级。
• 默认本地运行 — MCP 服务通过 stdio 通信，调试器适配器在本地运行，除非你明确配置经过验证的远程目标。

快速开始

Qwen Code

安装当前已发布的 npm 版本：

qwen extensions install @slp-dev1/qwen-dap-mcp

或者直接从维护中的 GitHub 仓库安装最新代码（可能领先于 npm）：

qwen extensions install spk-c/Qwen-dap-mcp

在 Qwen Code 中运行 /mcp 和 /skills，确认已发现 qwen-dap-mcp 服务和 native-runtime-debug 技能。

**前提条件：**Node.js 20+，以及单独安装的受支持原生 DAP 调试器（CodeLLDB、LLVM lldb-dap 或 GNU GDB DAP）。此软件包是桥接工具，不包含调试器。请参阅平台设置。

Claude Code

使用安装了 Node.js 20+ 和原生 DAP 调试器的本地 Claude Code CLI：

claude mcp add --transport stdio --scope user qwen-dap-mcp -- npx -y @slp-dev1/qwen-dap-mcp
claude mcp list

请参阅 Claude Code 原生调试指南，了解设置检查、测试提示词、Windows 注意事项和安全边界。

OpenAI Codex CLI

codex mcp add qwen-dap-mcp -- npx -y @slp-dev1/qwen-dap-mcp
codex mcp list

请参阅 Codex CLI + IDE 调试指南和带版本的 Codex TOML 配置。

Gemini CLI、Cursor、VS Code Copilot 和其他客户端

使用指向 npx -y @slp-dev1/qwen-dap-mcp 的本地 stdio MCP 条目。这些客户端的配置架构各不相同：Gemini CLI 和 Cursor 使用 mcpServers，而 VS Code 的 .vscode/mcp.json 使用 servers。请参阅多客户端设置与兼容性矩阵和经过测试的配置示例。

**云端执行边界：**Claude Code 或 Codex CLI 可以调用云端 AI 模型，同时 CLI 和调试器仍在你的桌面设备上运行。仅使用浏览器的 Claude.ai/ChatGPT 会话或远程 Codex 任务，无法自动访问你电脑上的本地 stdio MCP 服务或 Windows 进程。远程调试需要单独授权本地执行或使用受保护的连接；切勿将原始调试器端口暴露到公共互联网。

其他 stdio MCP 客户端

使用 npx 运行已发布的软件包：

npx -y @slp-dev1/qwen-dap-mcp --help
npx -y @slp-dev1/qwen-dap-mcp --version

使用可信的本地 MCP 客户端进行配置：

{
  "mcpServers": {
    "qwen-dap-mcp": {
      "command": "npx",
      "args": ["-y", "@slp-dev1/qwen-dap-mcp"]
    }
  }
}

启动时未指定 --help 或 --version，CLI 将以本地 stdio MCP 服务模式运行。客户端配置语法可能有所不同。

更新现有安装

使用已安装的 Qwen Code 版本中的扩展管理器更新基于 npm 的 Qwen 扩展，或使用上面的命令重新安装软件包。对于 npx，请重启 MCP 客户端以使用新解析的版本。npm 发布版本不可更改：只有发布新软件包版本后，README 的更改才会显示在 npmjs.com 上，而不是 GitHub 的 README 更改后立即显示。

MCP 客户端兼容性

客户端	本地 MCP 设置	验证方式
Qwen Code	Qwen 扩展	/mcp 和 /skills
Claude Code	本地 stdio claude mcp add	claude mcp list 和 /mcp
OpenAI Codex CLI	本地 stdio codex mcp add	codex mcp list 和 /mcp
Gemini CLI	settings.json mcpServers	gemini mcp list
Cursor	桌面端 MCP 设置	Cursor 中已连接的工具
VS Code 中的 GitHub Copilot	.vscode/mcp.json servers	Agent 模式下的 MCP 工具
仅浏览器 / 云端任务	不支持直接使用本地 stdio	需要独立的安全执行路径

项目包含与 Claude Code、Codex CLI 和 Gemini 客户端身份配合使用的 自动协议级 stdio initialize + tools/list 冒烟测试。这些测试可验证共享的 MCP 服务协议和示例配置的一致性，但不能验证专有客户端应用内的完整端到端行为。原生调试器 E2E 检查会单独运行。在构建后的代码库中运行 npm run test:clients。

30 秒示例

You: Debug why app.exe crashes with --repro

Coding agent
  ↓
qwen-dap-mcp starts a DAP debugger
  ↓
captures the native failure + project-controlled frame
  ↓
correlates stack + registers + locals + disassembly
  ↓
backtracks runtime evidence toward the likely producer
  ↓
agent applies a minimal source fix
  ↓
builds and repeats the original reproduction
  ↓
verifies whether the original crash fingerprint is gone

MCP 服务提供调试器证据和有界工作流状态。源代码编辑、构建、测试和源代码控制操作仍由编码 Agent 使用其常规授权工具完成。

功能

问题	面向 Agent 的能力
原生崩溃	诊断已停止的进程、识别项目帧、收集运行时证据，并执行有界的修复 / 验证循环
卡顿或死锁	观察进程、在需要时暂停、捕获所有线程的堆栈、分类等待状态，并审慎地找出可能的死锁
正常运行与异常运行	以语义方式比较已停止的会话，同时过滤原始 ASLR / 地址噪声
可疑值	使用数据断点 / 观察点和有界时间追踪，追踪实际写入者
运行时因果关系	使用 debug_causal_trace 构建有界的可疑值使用者 → 写入者 / 产生者链
疑似忙循环	使用 debug_progress_probe 对运行中的目标进行恢复 / 暂停采样，以区分重复状态和观察到的执行进展
记录 / 回放目标	使用受能力限制的 debug_reverse_execution，通过 DAP stepBack / reverseContinue 向后移动
崩溃集群分诊	构建 debug_runtime_report 指纹，使用 debug_cluster_crashes 对其聚类，并使用 debug_regression_oracle 对回归复现进行分类
子进程 / 分叉信号	使用 debug_child_requests 检查默认关闭的适配器 startDebugging 请求，不自动启动子会话
崩溃转储	检查 Windows minidump 和受支持的 LLDB / GDB 事后分析目标，不启动发生故障的程序
远程原生目标	通过经过验证的 gdbserver / lldb-server gdbserver 端点附加，优先使用环回地址
多个目标	保持隔离的 DAP 会话，并按 sessionId 路由请求
Agent 安全性	保持默认接口为高层级，并可选择使用 HOL Guard 限制可执行 / 可变更状态的 DAP 操作
对象生命周期 / UAF	关联指针写入者、消毒器证据、反向单步以及分配 / 释放提示
符号不匹配	将适配器符号状态与有界的本地二进制文件 / PDB 标识证据进行比较
崩溃集群	批量进行事后分析，并按精确匹配 / 语义 / 类型分组
离线交接	导出结构化证据和 SARIF，无需让目标继续运行

工具集

默认的 agent 工具集有意仅开放 18 个核心工具，以减少编码模型在较少使用的取证工作流上花费的上下文和选择精力。

核心工具	用途
debug_this_crash	高层级原生崩溃诊断和有界自主验证
debug_this_hang	高层级挂起／死锁排查
debug_compare_runs	对基线和失败的已停止会话进行语义比较
debug_trace_value	对可疑值进行有界时间追踪
debug_causal_trace	为可疑运行时状态提供从消费者到写入者的证据
debug_progress_probe	对无进展和忙循环进行恢复／暂停采样排查
debug_runtime_report	指纹、符号、消毒器证据、内存风险、ABI/API 分析、假设和断点规划
debug_trace_lifetime	对象／指针生命周期和写入者溯源
debug_adaptive_evidence	经济 → 中等 → 完整的有界证据收集
debug_diagnose_stop	诊断当前调试器停止状态
debug_source_disassembly	将源代码与附近的原生指令关联起来
debug_find_writer	在写入受监视值的代码处停止
debug_run_to_stop	继续运行／启动程序，直至到达有界且有意义的停止位置
debug_open_dump	打开受支持的事后转储／核心文件目标
debug_snapshot	捕获结构化运行时证据
debug_status	检查调试器／会话状态
debug_disconnect	正常结束调试器会话
debug_sessions	创建、检查和移除隔离会话

需要深入调查时，设置 QWEN_DAP_MCP_TOOLSET=forensics。它会继续隐藏原始手动 DAP 工具集，同时添加以下工具：

仅限取证的工具	用途
debug_reverse_execution	受能力限制的 reverseContinue / stepBack
debug_cluster_crashes	对规范化崩溃报告进行聚类
debug_regression_oracle	将复现分类为原始／已更改／无法确定
debug_child_requests	检查失败即关闭的子进程／fork 反向请求
debug_adopt_child	当 QWEN_DAP_MCP_CHILD_DEBUG=1 时，将一个经审查的 startDebugging 子进程显式纳入隔离会话
debug_time_travel	有界 rr 录制／回放规划和反向工作流
debug_thread_timeline	多线程进度和显式所有者锁图
debug_symbol_doctor	二进制身份、本地符号和 PDB/DWARF 不匹配诊断
debug_dump_batch	有界崩溃转储集群分析
debug_crash_families	精确／语义／系列崩溃比较
debug_cpp_object	只读 C++ 对象／vtable 检查
debug_evidence_bundle	JSON/Markdown/SARIF 证据交接
debug_adapter_doctor	适配器能力、rr 和安全配置文件审计

仅当确实需要原始堆栈／作用域／变量、手动断点／监视点、求值、内存读取、单步执行或适配器专属控件时，才设置 QWEN_DAP_MCP_TOOLSET=full。参阅 docs/toolsets.md。

调试器支持

适配器／目标	支持的用途
CodeLLDB	本地原生启动／附加和 Windows minidump 工作流
LLVM lldb-dap	原生启动／附加、核心文件检查和 lldb-server gdbserver 远程附加
GNU GDB 14+ DAP	原生启动／附加、核心文件工作流和加固的 gdbserver 远程附加

适配器发现、先决条件和特定平台的设置说明见 docs/README.md。

不止是原始 DAP

原始 DAP 的设计本就偏底层。qwen-dap-mcp 在完整工具集中保留了对原始调试器的访问，但默认功能侧重于 Agent 能够直接推理的工作流。

	仅源代码	原始 DAP	qwen-dap-mcp Agent 工具
运行时调试器证据	—	✓	✓
高层崩溃诊断	—	—	✓
全线程挂起排查	—	手动	✓
良好与不良语义差异对比	—	手动	✓
明确限定范围的修复／验证状态	—	—	✓
验证指纹	—	—	✓
因果写入者链	—	手动	✓
进度采样／忙循环排查	—	手动	✓
Sanitizer、符号和 ABI 报告关联分析	—	手动	✓

安全设计

调试器可以执行并修改目标状态，因此桥接层会明确管控这项能力。

• MCP 服务不会暴露任意 Shell 工具。
• MCP 服务不会暴露源码写入原语。
• 默认 Agent 功能中不包含通用内存写入原语。
• 远程端点会经过验证，访问非环回地址必须明确加入允许列表。
• 自主工作流状态是明确的，而非隐藏在后台循环中。
• 可选的 HOL Guard 2.2+ 集成可在受保护的适配器启动前，或可执行／会修改状态的 DAP 操作跨越调试器边界前，以故障关闭方式阻止操作。

请参阅 docs/hol-guard.md 和 SECURITY.md 中的完整策略和威胁模型。

开发与可复现验证

该仓库包含原生崩溃、挂起、事后分析、Windows minidump 和远程调试器测试样例。在开发环境的检出目录中：

npm ci
npm run check
npm run check:pack

检查包括源代码／构建完整性、MCP 测试、文档一致性，以及对实际 npm 压缩包的检查。原生适配器端到端测试在专用 CI 任务中运行，并且需要满足相应的调试器／工具链前提。请参阅集成测试和基准测试框架；未经记录且可复现的结果，不会作出任何性能声明。

实用调试教程

以下专题教程介绍了如何设置、预期的调试器证据以及实际原生目标的限制；MCP 桥接层不捆绑调试器。

• 使用 Qwen Code 调试 C/C++ 崩溃 — 重现原生崩溃，捕获堆栈／寄存器／局部变量证据，并验证修复。
• 使用 CodeLLDB 调试 Windows minidump — 使用匹配的可执行文件和符号检查崩溃转储，无需重新运行发生崩溃的进程。
• GDB／LLDB MCP 设置与故障排查 — 安装支持 DAP 的适配器，发现 MCP 工具并解决常见的适配器问题。
• 可复现的原生崩溃与修复验证演示 — 构建实际的自有 C++ 测试样例，收集 GDB SIGSEGV 回溯，应用临时保护措施，并使用相同参数重新运行。

MCP Registry 发现

当匹配的 npm 版本和官方 Registry 发布成功时，维护中的软件包会以 io.github.spk-c/qwen-dap-mcp 发布其 MCP 元数据。这与原作者的任何历史 Registry 条目无关。请参阅发布与 Registry 验证；条目本身并不能证明某项功能存在，必须先验证对应的确切软件包版本。

发现维护中的分支： 官方 MCP Registry · npm · 源代码与校验和 · 适用于目录的条目与归属说明。

文档

请从文档索引开始。

主题	指南
macOS 实验性支持	docs/macos.md
Windows 上的 CodeLLDB	docs/CODELLDB_WINDOWS.md
LLVM lldb-dap	docs/lldb-dap.md
GNU GDB DAP	docs/gdb-dap.md
远程调试	docs/remote-debugging.md
挂起／死锁分析	docs/hang-debugging.md
差分调试	docs/differential-debugging.md
运行时调试 v2	docs/runtime-debugging-v2.md
Agent 与完整工具集	docs/toolsets.md
HOL Guard 集成	docs/hol-guard.md
发布／版本	docs/publishing.md

贡献与源码构建

要求：Node.js 20+。

git clone https://github.com/spk-c/Qwen-dap-mcp.git
cd qwen-dap-mcp
npm ci
npm run check

src/**/*.ts 是 51 个运行时模块的唯一事实来源；生成的 JavaScript 镜像文件和声明文件由 CI 检查。TypeScript strict: true 的完整迁移已完成（问题 #24，PR #52–#56）。CI 要求严格模式编译诊断为零；原生调试器支持仍仅限于 CI 中经过测试的适配器和场景。

提交拉取请求前，请参阅 CONTRIBUTING.md。

分发与发布状态

• npm： @slp-dev1/qwen-dap-mcp — 可安装的已发布版本；请先验证 npm 版本，再假定其包含某项 GitHub 更改。
• 维护中的源代码与 Qwen 扩展： spk-c/Qwen-dap-mcp — qwen extensions install spk-c/Qwen-dap-mcp。
• 发布归档与变更日志： GitHub Releases 和 CHANGELOG.md。
• 发布： 发布由经过验证的 main 提交上的有意 vX.Y.Z 标签或手动触发工作流来启动；npm Trusted Publishing 使用 GitHub Actions OIDC，无需长期有效的 npm 发布令牌。

npm 条目会从已发布 tarball 内的 README 更新。在下次发布之前，GitHub README 与 npm README 可能会暂时不同。

贡献

欢迎提交 Bug 报告、可复现的原生故障案例、适配器兼容性发现、文档修复和有针对性的功能提案。请确保新增内容有证据支持，并优先考虑面向 Agent 的高层工作流，而不是扩展默认功能范围以纳入原始调试器命令。

如果这个项目帮你省下了一次调试时间，欢迎为仓库点亮星标——这有助于其他 MCP 和编码 Agent 用户发现它。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。