mcp-debugger

mcp-debugger

基于 MCP 的无头式 Agent 调试器——让你的 AI Agent 调试十种语言的运行中程序。

🎯 概述

mcp-debugger 是一种模型上下文协议（MCP）服务，可将逐步调试功能作为结构化工具调用开放出来。它让 AI Agent 能够在十种语言中为运行中的程序设置断点、检查变量、求值表达式并逐步执行，同时通过调试适配器协议（DAP）驱动真实的语言调试器。

无需 IDE。 mcp-debugger 可以在任何能运行 Node.js 的地方运行：CI 运行器、Docker 容器、Kubernetes Pod、SSH 主机，以及云端编码 Agent 所在的沙箱。它专为 IDE 无法涉足的环境而生。

何时使用 mcp-debugger，何时使用绑定 IDE 的调试服务

Microsoft 的 DebugMCP 通过 MCP 提供 VS Code 调试器，是 Agent 在运行中的 VS Code 内部 工作时的不错选择。这两个项目在架构上做出了不同的取舍：

	mcp-debugger	microsoft/DebugMCP
无头运行（CI、容器、k8s、云端 Agent）	✅ 独立 Node 进程	❌ 需要运行中的 VS Code
传输方式	stdio + Streamable HTTP	Streamable HTTP（localhost）
分发方式	npx、npm、Docker 镜像	VS Code Marketplace 扩展
无需 IDE 的远程附加	✅ debugpy / rdbg / JDWP，包括通过端口转发连接 Pod	❌
按会话隔离进程	✅ 每个会话一个代理进程	共用 VS Code 实例
Java 热替换和 Flutter 热重载（hot_reload）	✅	❌
可订阅为 MCP 资源的被调试程序输出	✅	❌
与 Agent 并行的 IDE 内调试体验	✅ 只读 IDE 镜像（expose_session）——IDE 加入 Agent 的实时会话	✅ 原生
不暂停程序的日志断点（适合生产环境的值监视）	✅ logMessage 断点	✅ 通过 VS Code
按内容／函数地址定位的断点（statement:、function:、expectedContent）	✅ 原生支持 Agent 的定位方式，修改代码后依然有效	—
默认启用密钥脱敏	✅ 变量／求值结果／输出掩码 + 最小权限模式	—
Kubernetes 临时调试 Sidecar（原生按 PID 附加）	✅ kubectl debug 流程	❌
C/C++	✅ 通过 CodeLLDB（启动 + 按 PID 附加）	✅ 通过 VS Code 扩展
COBOL	✅ 通过 GnuCOBOL + CodeLLDB（启动 + 按 PID 附加，变量以 COBOL 形式显示）	—
Dart/Flutter	✅ 通过 SDK 自带的调试适配器（启动 + 按 VM 服务 URI 附加；现已支持 Dart，Flutter 运行器已接入并将在后续里程碑发布）	—
PHP	❌	✅ 通过 VS Code 扩展
语言	Python、JS/TS、Ruby、Rust、Go、Java、.NET、C/C++、COBOL、Dart/Flutter	Python、JS/TS、Ruby、Rust、Go、Java、.NET、C/C++、PHP

如果你的 Agent 在终端、流水线或云沙箱中运行，或者需要附加到另一台机器上的进程，就应该使用 mcp-debugger。

🆕 v0.25.0 — COBOL 调试现已推出（GnuCOBOL + CodeLLDB，支持以 COBOL 形式显示变量、感知 PERFORM 的单步执行和段落断点）；现在 CodeLLDB 以各平台软件包的形式发布，Rust 和 C/C++ 也可在 npm 支持安装的所有平台上开箱即用。新增功能还包括：mcp-debugger doctor、Kubernetes 调试指南、限制为 127.0.0.1 并检查 Host/Origin 的 HTTP 传输、说明运行如何结束的启动响应、Go 和 Docker JavaScript 的退出代码，以及更轻量的启动过程。完整发布历史请参阅 CHANGELOG。

✨ 主要功能

• 🌐 多语言支持 – 清晰的适配器模式，支持任意语言
• 🐍 通过 debugpy 调试 Python – 完整支持 DAP 协议
• 💎 通过 rdbg 调试 Ruby – 支持启动和附加工作流，包括远程附加到容器和 Kubernetes Pod
• 🟨 通过 js-debug 调试 JavaScript（Node.js） – 使用 VSCode 久经验证的调试器
• 🦀 通过 CodeLLDB 调试 Rust – 调试 Rust 和 Cargo 项目（Linux/macOS；Windows 需要 GNU 工具链 — 请参阅 Rust on Windows）
• 🐹 通过 Delve 调试 Go – 完整支持 Go 程序的 DAP
• ☕ 通过 JDI 桥接调试 Java – 支持启动和附加模式，要求 JDK 21+
• 🔷 通过 netcoredbg 调试 .NET/C# – 完整支持 DAP，可调试 .NET 应用
• ⚙️ 通过 CodeLLDB 调试 C/C++ – 启动预编译二进制文件或单独的源文件（自动编译），按 PID 附加；通过配置透传支持 core dump 和 gdbserver/rr 目标
• 🧮 通过 GnuCOBOL + CodeLLDB 调试 COBOL – 启动 .cob/.cbl 源文件（通过 cobc 自动编译）或预编译可执行文件，按 PID 附加；支持 WORKING-STORAGE / LOCAL-STORAGE / LINKAGE 作用域，可解码 DISPLAY、COMP、COMP-3 和 88 级值，在 copybook 中设置断点，按语句粒度单步执行，并在 libcob 运行时错误（类似 S0C7/SSRANGE）时暂停 — 专为主机到 GnuCOBOL 的迁移打造（指南）
• 🐦 通过 Dart/Flutter SDK 自带的调试适配器调试 Dart/Flutter – 启动 Dart 程序和 package:test 文件（dart debug_adapter），或启动 Flutter 应用和测试（flutter debug-adapter）；根据 pubspec.yaml 和程序路径自动检测运行器；通过服务 URI 或服务信息文件附加到运行中的 VM；支持条件断点、日志点、Unhandled/All 异常筛选器和 noDebug。不包含任何随附依赖 — 机器上的 Dart 或 Flutter SDK 就是调试器。目前支持 Dart；Flutter 运行器已接通，并在 spike 阶段于 Windows 桌面和 Android 模拟器上完成测量，将在后续里程碑中发布（指南）
• 🧪 用于测试的模拟适配器 – 无需外部依赖即可测试
• 🛰️ IDE 外调试与远程附加 – 通过主机/端口附加到另一台机器或容器内的进程（Python 使用 debugpy、Ruby 使用 rdbg、JavaScript 使用 V8 检查器、Java 使用 JDWP、Dart/Flutter 使用 VM 服务 URI），并支持源路径映射；原生代码（C/C++、COBOL）可按 PID 附加，本地 Node.js 进程也可按 PID 附加，mcp-debugger 会为其打开检查器（JavaScript）。Python 和 Ruby 采用直接连接附加 — 调试引擎已在目标进程内运行，因此无需本地安装 Python 或 Ruby；JavaScript、Java、.NET、C/C++、COBOL 和 Dart/Flutter 则会启动本地适配器；其中只有 Java（需要 JDK）、.NET（需要 netcoredbg）和 Dart/Flutter（需要 Dart 或 Flutter SDK，由其自带的调试适配器完成工作）需要安装工具链，因为 JavaScript、C/C++ 和 COBOL 的调试引擎已随软件包提供。list_supported_languages 会报告各模式的可用性及原因
• 🎯 编辑后仍有效的断点 – 可按内容定位（statement: "total = sum(prices)"）、按符号定位（function: "main"），或使用 expectedContent 验证行内容；锚点会在 restart_debugging 后重新解析，匹配较弱时会发出醒目警告
• 🪵 日志点 – 使用 logMessage: "x={x}" 调用 set_breakpoint，即可将插值后的值流式写入 get_output，且不会暂停 — 可安全地在生产环境热点路径上观察值
• 🧰 完整的断点生命周期 – list_breakpoints / remove_breakpoint / clear_breakpoints 可在运行中实时使用；restart_debugging 会使用相同配置重新启动，并在一次调用中重新应用所有设置
• 📡 缓冲程序输出 – get_output 会通过游标返回被调试程序的 stdout/stderr，每个会话还会将其记录文本公开为可订阅的 MCP 资源
• 💥 默认启用崩溃状态调试 – 启动的会话会在未捕获异常时暂停，并实时提供堆栈和局部变量（breakOnExceptions；异常类/消息通过 lastStop 提供）
• 🪞 只读 IDE 镜像 – expose_session 会打开一个受令牌保护的环回 DAP 端点，让人工使用的 IDE 能检查 Agent 的实时会话，而不会接管控制权
• ☸️ Kubernetes 调试 – 对解释型运行时使用端口转发附加，对原生进程使用 kubectl debug --target + 按 PID 附加（操作步骤，即用型清单）
• 🔌 STDIO 和 Streamable HTTP 传输 – 兼容任何 MCP 客户端（旧版 SSE 传输已弃用）
• 📦 零运行时依赖 – 通过 esbuild + tsup 提供自包含软件包
• ⚡ 可直接通过 npx 运行 – 使用 npx @debugmcp/mcp-debugger 直接运行，无需安装
• 🐳 Docker 和 npm 软件包 – 可部署到任何地方
• 🤖 专为 AI Agent 打造 – 提供结构化 JSON 响应，便于解析
• 🔒 默认启用机密信息脱敏 – 在变量、求值和输出结果传给 Agent 前，会将类似凭证的值（API 密钥、令牌、私钥）替换为带标签的占位符（详情；使用 DEBUG_MCP_NO_REDACT=1 可选择退出）
• 🛡️ 路径验证 – 防止因文件不存在而崩溃
• 📝 面向 AI 的代码行上下文 – 提供智能断点定位和代码上下文
• ✅ 全面的测试套件 – 覆盖每个适配器的单元、集成和端到端测试（CI 状态）

🧠 Agent 技能

工具告诉 Agent 能做什么；技能则教会它 如何出色地调试。此仓库提供了一项 Agent 技能，涵盖会话黄金路径、根因分析原则（优先二分法，而非逐行单步执行）、附加／远程调试方案，以及各语言的特有问题：

# Claude Code (user-level)
cp -r skills/debugging ~/.claude/skills/mcp-debugger
# Cross-agent directories (Copilot CLI and friends)
cp -r skills/debugging ~/.agents/skills/mcp-debugger

连接时，服务还会通过 MCP instructions 提供精简指南，并提供任何 MCP 客户端都可请求的 debugging-workflow 提示词。详情请参阅 skills/debugging/README.md。

🎬 实际演示

• 自动调试失败的 CI 测试 – 一个组合式 GitHub Action，在测试失败时启动 mcp-debugger 和 Agent，并发布根因分析
• 故障 Pod 演练 – 通过端口转发连接到 Kubernetes 中运行异常的 Python 服务（教程）
• 原生故障 Pod – 编译型代码的相同演练：临时调试 sidecar + 按 PID 附加，无需进程内 Agent

🚀 快速开始

**要求：**服务端需要 Node.js 22+。调试各语言时，还需安装对应的工具链（Python + debugpy、Ruby + debug gem / rdbg、Node.js、Go + Delve、JDK 21+、.NET SDK、Rust 工具链、C/C++ 编译器 — g++/clang++，仅在启动源文件时需要 — 用于启动 COBOL 源文件的 GnuCOBOL 3.1.2+，或 Dart/Flutter 所需的 Dart SDK — Flutter 已内置）。不确定安装了哪些工具？运行 npx @debugmcp/mcp-debugger doctor，查看各适配器的工具链报告。

**CodeLLDB 平台说明（npx/npm 安装）：**CodeLLDB 调试引擎通过针对各平台的可选依赖提供（@debugmcp/codelldb-win32-x64、-darwin-x64、-darwin-arm64、-linux-x64、-linux-arm64）— npm 会准确安装与你的平台匹配的依赖，因此 Rust 和 C/C++ 调试在 npm 支持的所有平台上均可开箱即用。如果使用 --omit=optional 安装，请将 CODELLDB_PATH 设置为 CodeLLDB 发布版二进制文件的路径，或使用 Docker 镜像。

适用于 MCP 客户端（Claude Desktop 等）

在 MCP 设置配置中添加：

{
  "mcpServers": {
    "mcp-debugger": {
      "command": "node",
      "args": ["C:/path/to/mcp-debugger/dist/index.js", "stdio", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
      "disabled": false,
      "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
    }
  }
}

适用于 Codex CLI、桌面应用和 IDE

使用 Codex CLI 注册已发布的 stdio 服务：

codex mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio
codex mcp list

Codex 会将此条目保存到 ~/.codex/config.toml。ChatGPT 桌面应用、Codex CLI 和 Codex IDE 扩展在同一 Codex 主机上运行时，会共用此配置。重启正在使用的桌面客户端或 IDE 扩展（或启动新的 CLI 会话），然后使用 /mcp 确认 mcp-debugger 已连接。配置和故障排除详情请参阅官方 Codex MCP 文档。

正在开发 mcp-debugger 本身？请使用可重启的源码开发代理，而非已发布的软件包。

适用于 Claude Code CLI

对于 Claude Code 用户，我们提供了自动安装脚本：

前提条件：运行安装脚本前，必须先安装 Claude CLI 并确保它位于 PATH 中。安装说明请参阅 Claude Code 文档。

# Clone the repository
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Run the installation script
./scripts/install-claude-mcp.sh

# Verify the connection (use 'claude mcp list' if claude is on your PATH)
claude mcp list

重要提示：必须提供 stdio 参数，以防止控制台输出破坏 JSON-RPC 协议。详细的设置和故障排除说明请参阅 CLAUDE.md。

面向 pi 编码 Agent

pi 0.99 及更高版本内置了 MCP 支持。已发布的 @debugmcp/mcp-debugger 软件包也是一个 pi 软件包：安装一次即可添加 mcp-debugger Agent 技能，以及一个将服务注册到 pi MCP 支持中的扩展：

pi install npm:@debugmcp/mcp-debugger  # the mcp-debugger skill, and the server via pi's built-in MCP
pi list                                # shows the package

该扩展会运行 pi install 安装到磁盘上的 CLI，因此服务与技能相匹配，并且启动时无需通过 npx 下载。它以 deferred 暴露方式注册：pi 会在系统提示词中列出调试器，模型则使用 tool_search 加载所需工具，名称为 mcp__mcp_debugger__<tool>。/mcp 会显示服务，并可在会话期间更改其暴露方式。在 ~/.pi/agent/mcp.json 中添加 mcp-debugger 条目即可替换该注册，例如通过开发代理调试源码构建版本。

若只添加服务而不添加技能：pi mcp add mcp-debugger -- npx -y @debugmcp/mcp-debugger stdio。 低于 0.99 的 pi 版本没有内置 MCP 支持；此时扩展不会执行任何操作，因此请升级 pi。

使用 Docker

docker run -i --rm -v $(pwd):/workspace debugmcp/mcp-debugger:latest

Docker 镜像原生支持调试 Python、JavaScript、Java、Rust、C/C++、COBOL 和 Dart（包含工具链——包括 GnuCOBOL 和 Dart SDK——以及共享的预打包 CodeLLDB），另加 mock 适配器。Flutter 仅支持在主机上运行：镜像不包含 Flutter SDK。镜像中的 Ruby 仅支持附加（适配器不附带 Ruby 运行时——可附加到任意本地或远程的 rdbg --open 进程）。只有 Go 和 .NET 在容器中被禁用——请在本地工具链旁通过 npm/npx 运行。使用主机编译的 Rust/C++ 二进制文件并在容器中调试时，会自动派生映射回 /workspace 的源码映射。list_supported_languages 会报告各模式（modes.launch / modes.attach）的可用情况及原因。请参阅 Docker 支持。

使用 npm

npm install -g @debugmcp/mcp-debugger
mcp-debugger --help

也可以通过 npx 使用，无需安装：

npx @debugmcp/mcp-debugger --help

通过网络（Streamable HTTP）

stdio 是默认模式，也是大多数客户端需要的模式。当服务必须在其他位置运行时 ——例如 CI 运行器、容器或 Kubernetes Pod——请改为在端口上启动：

mcp-debugger http --port 3001            # or: node dist/index.js http -p 3001

然后让客户端连接到该地址：

{
  "mcpServers": {
    "mcp-debugger": {
      "type": "http",
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

每个 HTTP 客户端都会获得独立隔离的服务：调试会话不会被其他客户端看到。客户端断开连接时若未发送 DELETE /mcp，其调试会话以及任何已暂停的附加目标都会继续运行，直到服务将其清理：SSE 流断开后 2 分钟（MCP_HTTP_STREAM_LOST_SESSION_MS），或若从未打开 SSE 流，则在空闲 30 分钟后（MCP_HTTP_STALE_SESSION_MS）。GET /health 会列出每个会话持有的资源。

端口默认为 3001，服务仅监听 127.0.0.1。--bind 0.0.0.0（或 MCP_HTTP_BIND=0.0.0.0）会监听所有网络接口——请搭配 --allowed-host 指定其他机器将使用的名称；--bind localhost 表示 127.0.0.1，且只接受 IP 地址。通过同一端口上的 GET /health 可进行存活检查，并在 listening 下报告绑定的地址和端口。旧版 sse 子命令仍然存在，但已弃用——请改用 http。

默认情况下，服务只接受来自回环地址的 Host 标头——localhost、127.0.0.1、[::1]——以防止未认证端点遭受 DNS 重绑定攻击，因为该端点可以启动进程并附加到 PID。其他机器上的客户端可通过端口转发或 SSH 隧道访问（ssh -L 3001:127.0.0.1:3001 user@server，然后访问 http://127.0.0.1:3001/mcp），也可以使用 --bind 绑定网络接口；任何其他 Host 都会收到说明原因的 403 响应。若要直接接受服务名称——例如在容器网络中访问 http://mcp-debugger:3001/mcp——请使用 --allowed-host mcp-debugger（可重复指定）或 MCP_HTTP_ALLOWED_HOSTS=mcp-debugger（以逗号分隔）启动服务。启用此选项意味着服务前方另有访问控制；不支持通配符。浏览器客户端也会根据同一列表检查其 Origin，因此跨站页面无法控制调试器。已弃用的 sse 子命令使用相同的允许列表，并接受相同的标志。

📚 工作原理

mcp-debugger 将调试操作公开为 MCP 工具，可通过结构化 JSON 参数调用：

// Tool: create_debug_session
// Request:
{
  "language": "python",  // or "ruby", "javascript", "rust", "go", "java", "dotnet", "cpp", "cobol", "dart", or "mock" for testing
  "name": "My Debug Session"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: My Debug Session"
}

🛠️ 可用工具

以下 29 个工具均已实现——参数和响应格式请参阅工具参考。

工具	描述	状态
create_debug_session	创建新的调试会话	✅ 已实现
list_debug_sessions	列出所有活动会话	✅ 已实现
list_supported_languages	显示可用的语言适配器	✅ 已实现
set_breakpoint	在文件中设置断点	✅ 已实现
list_breakpoints	列出会话的断点及其已验证状态	✅ 已实现
remove_breakpoint	按 ID 或文件和行号移除断点	✅ 已实现
clear_breakpoints	移除所有断点（可选按文件筛选）	✅ 已实现
start_debugging	开始调试脚本，或通过一次调用调试失败的测试（testRunner: "pytest"）	✅ 已实现
restart_debugging	使用相同配置重新启动，并重新应用断点	✅ 已实现
attach_to_process	将调试器附加到正在运行的进程	✅ 已实现
detach_from_process	从进程中分离调试器	✅ 已实现
expose_session	开启只读 DAP 镜像端点，供 IDE 附加并检查	✅ 已实现
unexpose_session	关闭镜像端点并断开 IDE 客户端	✅ 已实现
get_stack_trace	获取当前堆栈跟踪	✅ 已实现
list_threads	列出调试会话中的所有线程	✅ 已实现
get_scopes	获取某个栈帧的变量作用域	✅ 已实现
get_variables	获取某个作用域中的变量	✅ 已实现
get_local_variables	获取当前栈帧中的局部变量	✅ 已实现
step_over	单步越过当前行	✅ 已实现
step_into	单步进入函数	✅ 已实现
step_out	单步跳出函数	✅ 已实现
continue_execution	继续运行	✅ 已实现
wait_for_stop	阻塞，直到会话再次暂停或结束	✅ 已实现
pause_execution	暂停正在运行的程序	✅ 已实现
evaluate_expression	在调试上下文中计算表达式	✅ 已实现
get_source_context	获取源代码上下文	✅ 已实现
get_output	读取捕获的被调试程序输出（stdout/stderr）	✅ 已实现
close_debug_session	关闭会话	✅ 已实现
hot_reload	将修改后的代码应用到正在运行的程序，并保留其状态——Flutter 热重载、Java 类重定义（redefine_classes 是已弃用的别名）	✅ 已实现

🏗️ 架构：动态适配器加载

0.10.0 版引入了简洁的适配器模式，将与语言无关的核心功能与特定语言的实现分离：

┌─────────────┐     ┌────────────────┐     ┌──────────────┐     ┌─────────────────┐
│ MCP Client  │────▶│ DebugMcpServer │────▶│SessionManager│────▶│ AdapterRegistry │
└─────────────┘     └────────────────┘     └──────────────┘     └─────────────────┘
                            │                      │
                            ▼                      ▼
                    ┌──────────────┐      ┌─────────────────┐
                    │ ProxyManager │◀─────│ Language Adapter│
                    └──────────────┘      └─────────────────┘
                                                  │
              ┌───────────┬───────────┬───────────┼───────────┬───────────┬───────────┬───────────┬───────────┬───────────┬───────────┐
              │           │           │           │           │           │           │           │           │           │           │
        ┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐
        │Python    ││Ruby      ││JavaScript││Rust      ││Go        ││Java      ││.NET      ││C/C++     ││COBOL     ││Dart      ││Mock      │
        │Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   │
        └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘

添加语言支持

想为你喜欢的语言添加调试支持？请查看适配器开发指南！

💡 示例：调试 Python 代码

以下是一个完整的调试会话示例：

# buggy_swap.py
def swap_variables(a, b):
    a = b  # Bug: loses original value of 'a'
    b = a  # Bug: 'b' gets the new value of 'a'
    return a, b

第 1 步：创建调试会话

// Tool: create_debug_session
// Request:
{
  "language": "python",
  "name": "Swap Bug Investigation"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: Swap Bug Investigation"
}

第 2 步：设置断点

// Tool: set_breakpoint
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "file": "C:\\path\\to\\buggy_swap.py",
  "line": 2
}
// Response:
{
  "success": true,
  "breakpointId": "28e06119-619e-43c0-b029-339cec2615df",
  "file": "C:\\path\\to\\buggy_swap.py",
  "line": 2,
  "verified": false,
  "message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2"
}

第 3 步：开始调试

// Tool: start_debugging
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scriptPath": "C:\\path\\to\\buggy_swap.py"
}
// Response:
{
  "success": true,
  "state": "paused",
  "message": "Debugging started for C:\\path\\to\\buggy_swap.py. Current state: paused",
  "data": {
    "message": "Debugging started for C:\\path\\to\\buggy_swap.py. Current state: paused",
    "reason": "breakpoint"
  }
}

第 4 步：检查变量

首先，获取作用域：

// Tool: get_scopes
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "frameId": 3
}
// Response:
{
  "success": true,
  "scopes": [
    {
      "name": "Locals",
      "variablesReference": 5,
      "expensive": false,
      "presentationHint": "locals",
      "source": {}
    },
    {
      "name": "Globals", 
      "variablesReference": 6,
      "expensive": false,
      "source": {}
    }
  ]
}

然后获取局部变量：

// Tool: get_variables
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scope": 5
}
// Response:
{
  "success": true,
  "variables": [
    {"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false},
    {"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false}
  ],
  "count": 2,
  "variablesReference": 5
}

📖 文档

• 🗺️ 路线图 – 通往 1.0 的路径：稳定性标准、近期主题、非目标
• 📘 工具参考 – 完整的 API 文档
• 🚦 入门指南 – 初次设置
• 🏗️ 架构概览 – 多语言设计
• 🔧 适配器开发 – 添加新语言
• 🔌 动态加载架构 – 运行时发现、延迟加载、缓存
• 🧩 适配器 API 参考 – 适配器、工厂、加载器和注册表契约
• 🔄 CHANGELOG – 发布历史和升级说明
• 🐍 Python 调试指南 – Python 专属功能
• 💎 Ruby 调试指南 – 使用 rdbg 调试 Ruby，包括远程附加
• 🔬 案例研究：迟迟未返回的 initialize 响应 – 通过 mcp-debugger 调试自身，查明 Ruby 启动卡顿的根本原因
• 🔬 案例研究：将调试器附加到自身 – 通过运行中的 mcp-debugger 自己的 evaluate_expression 实时修补，以捕获 strace 无法发现的竞态
• 🔬 案例研究：总能成功的暂停 – 阅读 js-debug 自身的 CDP 跟踪，发现它的智能单步器在空闲服务上吞掉用户暂停操作
• 🔬 案例研究：无法识别其套接字的跟踪 – 在诊断工具本身上执行测量—修复—测量：一次脚本化附加运行，修复前后对比，作为验收测试
• 🟨 JavaScript 调试指南 – JavaScript/TypeScript 功能
• 🐹 Go 调试指南 – 使用 Delve 调试 Go
• ☕ Java 调试指南 – 使用 JDI bridge 调试 Java
• 🔷 .NET 调试指南 – 使用 netcoredbg 调试 .NET/C#
• ⚙️ C/C++ 调试指南 – CodeLLDB 启动、自动编译、按 PID 附加、核心转储、远程存根
• 🧮 COBOL 调试指南 – GnuCOBOL + CodeLLDB：自动编译、符合 COBOL 特性的变量、运行时错误处断点、主机迁移方案
• 🐦 Dart/Flutter 调试指南 – SDK 自带的调试适配器：运行器选择、dart test/flutter test、通过 VM-service URI 附加、Flutter 设备
• 🦀 Rust 调试指南 – CodeLLDB 设置（Windows 特定说明）
• 🐳 Docker 支持 – 容器语言、附加模式、主机二进制文件源映射
• ☸️ Kubernetes 调试 – 开箱即用的附加方案：无需注册表的清单、按语言预设、临时调试边车容器
• 🚑 JIT 诊断教程 – 在 Kubernetes 中调试运行中的服务，包括针对编译代码的临时边车容器流程
• 🤖 Agent 调试指南 – AI Agent 的正确工具使用模式
• ⚠️ 已知问题 – 当前注意事项和解决方法
• 🩺 诊断 – mcp-debugger doctor、各语言的前置条件、故障特征、环境变量参考
• 🔧 故障排除 – 常见问题和解决方案

🤝 参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

# Development setup
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Install dependencies and vendor debug adapters
pnpm install
# Vendored debug engines (Microsoft's js-debug; CodeLLDB, shared by Rust, C/C++ and COBOL)
# are downloaded automatically and verified against committed SHA-256 digest pins

# Build the project
pnpm build

# Run tests
pnpm test

# Check adapter vendoring status
pnpm vendor:status

# Force re-vendor all adapters (if needed)
pnpm vendor:force

调试适配器打包

项目会在 pnpm install 期间自动打包调试适配器：

• JavaScript：从 GitHub releases 下载 Microsoft 的 js-debug
• Rust、C/C++ 和 COBOL：为当前平台下载一份共用的 CodeLLDB 副本（packages/codelldb-common）
• 完整性：每次下载都会根据各软件包 vendor-manifest.json 中固定的 SHA-256 摘要进行验证；不匹配时构建会失败
• CI 环境：设置 SKIP_ADAPTER_VENDOR=true 可跳过打包

如需手动管理适配器：

# Check current vendoring status
pnpm vendor:status

# Re-vendor all adapters
pnpm vendor

# Clean and re-vendor (force)
pnpm vendor:force

# Clean vendor directories only
pnpm clean:vendor

在本地运行容器测试

我们使用 Act 在本地运行 GitHub Actions 工作流：

# Build the Docker image first
docker build -t mcp-debugger:local .

# Run tests with Act (use WSL2 on Windows)
act -j build-and-test --matrix os:ubuntu-latest

如需详细的测试说明，请参阅 tests/README.md。

📊 项目状态

• ✅ 已可用于生产环境：支持十种语言的适配器、29 个工具，并提供完善的多语言分发
• ✅ 架构简洁，采用动态适配器模式
• ✅ Python · Ruby · JavaScript/TypeScript · Go · Java · .NET/C#：支持完整的单步调试
• 🦀 Rust：在 Linux/macOS/Windows 上提供完整支持（Windows 需要 GNU 工具链；CodeLLDB 不支持 MSVC）
• ⚙️ C/C++：通过 CodeLLDB 支持完整的单步调试（启动 + 按 PID 附加；在 Windows 上建议使用 MinGW/DWARF — MSVC PDB 的兼容度有限）
• 🧮 COBOL：通过 GnuCOBOL + CodeLLDB 支持单步调试（启动 + 按 PID 附加；已在 Linux 和 Windows/MSYS2 上使用 GnuCOBOL 3.1.2/3.2 验证；支持感知 PERFORM 的单步执行、段落断点和 {WS-NAME} 日志点）
• 🐦 Dart/Flutter：通过 SDK 自带的调试适配器进行单步调试（dart debug_adapter、flutter debug-adapter；启动 + 通过 VM 服务 URI 附加）。目前支持 Dart；Flutter 运行器已接入，并在 spike 中于 Windows 桌面和 Android 模拟器上完成测量，将在后续里程碑中发布
• 🟢 运行时：Node.js 22+
• 📈 积极开发中：定期更新和改进 — 请参阅 Roadmap 了解迈向 1.0 的计划

🏛️ 维护者

mcp-debugger 由 Sycamore LLC 负责维护，John Franklin（@debugmcpdev）担任项目负责人。项目采用 Agent 优先的开发模式，并由人类承担责任：AI Agent 编写大部分代码；人类维护者负责每一次合并、发布和安全决策。请参阅 MAINTAINERS.md、GOVERNANCE.md 和 SUPPORT.md（含商业支持）。

供应链安全措施：固定 CI 操作、OIDC 可信发布、每个 npm 软件包均附有 sigstore 来源证明、发布版本附有 SBOM，以及我们积极维护的 OpenSSF Scorecard 评分 — 详情请参阅 SUPPLY-CHAIN-SECURITY.md。请通过 SECURITY.md 报告漏洞。

📄 许可证

MIT 许可证 — 详情请参阅 LICENSE。

👥 贡献者

• @Poyraxx — Ruby 适配器（rdbg）
• @swinyx — Go 适配器（Delve）
• @roofpig95008 — Java 适配器（JDI bridge）

🙏 致谢

本项目基于以下项目构建：

• Anthropic 的 Model Context Protocol
• Microsoft 的 Debug Adapter Protocol
• 用于 Python 调试的 debugpy
• 用于 Ruby 调试的 debug

---

为你的 AI Agent 配备真正的调试器 — 支持任意语言。