DebugMCP (MCP Server) - 赋予 AI 智能体操作调试能力

让 AI 智能体在 VS Code 中调试你的代码——设置断点、单步执行、检查变量和计算表达式。适用于 Codex、GitHub Copilot、GitHub Copilot CLI、Cline、Cursor、Windsurf、Roo Code 以及任何兼容 MCP 的助手。兼容任何 VS Code 支持的编程语言。

⭐ 如果你觉得 DebugMCP 有用，请 在 GitHub 上给仓库点星！ 这有助于他人发现该项目，并激励我们持续开发。

📢 开发者须知：此扩展由 ozzafar@microsoft.com 和 orbarila@microsoft.com 维护。我们欢迎反馈和贡献，以帮助改进此扩展。

🎬 观看 DebugMCP 的实际操作——你的 AI 助手自主设置断点、单步执行代码，并直接在 VS Code 中检查变量。

✨ 新增内容

2.2

• 跨智能体 debug-live 技能安装——系统化调试工作流以 Agent Skill 的形式提供，现在已安装到标准技能目录——~/.agents/skills/（兼容技能的工具链（包括 VS Code 智能体模式）所认可的跨智能体位置）以及 ~/.copilot/skills/（如果存在）——因此它可以在任何地方被发现，而不是被复制到每个智能体的配置旁边，而那里没有任何东西会扫描它（修复了 #105，即 VS Code 从未加载该技能的问题）。服务器还宣传 MCP instructions，并且 start_debugging 工具指向该技能以获取完整工作流。

• 暂停运行中的程序——新的 pause_execution 工具可以中断自由运行的程序，并停在其当前位置，即使没有设置断点（非常适合繁忙循环和嵌入式/裸机目标），这样你就可以检查状态或从那里继续单步执行。

• 通过 VS Code 测试 API 进行稳健调试——带有 testName 的 start_debugging 使用 VS Code 测试 API 来发现并启动测试，从而在各种语言测试运行器（pytest、Jest/Vitest、Java、.NET、Go 等）的单个测试用例中产生一致的断点命中。

Related MCP server: MCP Server for VS Code

🚀 快速安装

从 VS Code 市场安装 或使用直接链接：vscode:extension/ozzafar.debugmcpextension

目录

• 概述

• 功能

• 安装

• 快速开始

• 支持的 AI 助手

• 支持的语言

• 配置

• 常见问题

• 故障排除

• 工作原理

• 贡献

• 许可证

概述

DebugMCP 是一个 MCP 服务器，让 AI 编码智能体完全控制 VS Code 调试器。你的 AI 助手无需阅读日志或猜测，即可自主设置断点、启动调试会话、逐行单步执行代码、检查变量值并计算表达式——就像人类开发者一样。它 100% 在本地运行，无需任何配置，并且开箱即用地与任何兼容 MCP 的 AI 助手配合使用。

功能

🔧 工具

注意： MCP 服务器为调试器操作提供工具，而程序性 工作流指南（何时调试、如何构建根本原因调查、 语言特定的怪癖）位于配套的 Agent Skill 中。 工具描述保持简洁和行为化；扩展将 debug-live 技能 安装到标准技能目录（~/.agents/skills/，以及 ~/.copilot/skills/（如果存在）） 以便兼容技能的工具链按需加载完整工作流。服务器还 宣传 MCP instructions，在调试前将智能体指向它。

🎯 调试最佳实践

DebugMCP 遵循系统化调试实践，以有效解决问题：

• 从入口点开始：从函数入口点或主执行路径开始调试

• 遵循执行流程：使用逐步执行来理解代码流程

• 根本原因分析：不要停留在症状上——找到根本原因

🛡️ 安全与可靠性

• 安全通信：所有 MCP 通信都使用安全协议

• 本地运行：MCP 服务器 100% 在本地运行，无外部通信，无需凭据

• 状态验证：对调试状态和操作进行稳健验证

安装

快速安装选项

选项 1：直接链接（最快）

• 点击此链接：vscode:extension/ozzafar.debugmcpextension

• 或在浏览器中复制粘贴：vscode:extension/ozzafar.debugmcpextension

选项 2：VS Code 市场

• 访问：https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension

• 点击“安装”

选项 3：在 VS Code 内

1. 打开 VSCode

2. 转到扩展（Ctrl+Shift+X / Cmd+Shift+X）

3. 搜索“DebugMCP”

4. 点击安装

5. 扩展自动激活并注册为 MCP 服务器

验证

安装后，你应该看到：

• 已安装扩展中的 DebugMCP 扩展

• MCP 服务器自动在端口 3001 上运行（可配置）

• 调试工具可供连接的 AI 助手使用

📝 注意：无需额外的调试规则说明——扩展开箱即用。

💡 提示：在 AI 助手中为所有 debugmcp 工具启用自动批准，以创建无缝的调试工作流，避免频繁的批准中断。

快速开始

1. 安装扩展（参见 安装）

2. 在 VSCode 中打开你的项目

3. 让 AI 进行调试——它现在可以设置断点、启动调试并分析你的代码！

支持的 AI 助手

DebugMCP 可与任何兼容 MCP 的 AI 助手配合使用。它会自动检测并提供注册到：

支持的语言

DebugMCP 支持使用各自的 VSCode 扩展对以下语言进行调试：

配置

MCP 服务器配置（推荐）

该扩展会自动运行一个 MCP 服务器。它会弹出一条消息，在你的 AI 助手中自动注册 MCP 服务器。

你也可以通过命令面板手动触发注册：

• DebugMCP: Show Agent Selection Popup

手动 MCP 服务器注册（可选）

🔄 自动迁移：如果你之前使用 SSE 传输配置过 DebugMCP，扩展会在激活时自动将你的配置迁移到新的 Streamable HTTP 传输。

Cline

添加到你的 Cline 设置或 cline_mcp_settings.json 中：

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - AI-powered debugging assistant"
    }
  }
}

GitHub Copilot

添加到你的 VS Code 设置（settings.json）中：

{
  "mcp": {
    "servers": {
      "debugmcp": {
        "type": "http",
        "url": "http://localhost:3001/mcp",
        "description": "DebugMCP - Multi-language debugging support"
      }
    }
  }
}

GitHub Copilot CLI

添加到 ~/.copilot/mcp-config.json（如果设置了 COPILOT_HOME，则为 ${COPILOT_HOME}/mcp-config.json）：

{
  "mcpServers": {
    "debugmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "tools": ["*"]
    }
  }
}

Cursor

添加到 Cursor 的 MCP 设置中：

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Codex

向 Codex 注册 DebugMCP：

codex mcp add debugmcp --url http://localhost:3001/mcp

或者将等效配置添加到 ~/.codex/config.toml（如果设置了 CODEX_HOME，则为 ${CODEX_HOME}/config.toml）：

[mcp_servers.debugmcp]
url = "http://localhost:3001/mcp"

Windsurf

添加到 Windsurf 的 MCP 设置中（~/.windsurf/mcp_settings.json 或工作区的 .windsurf/mcp_settings.json）：

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Roo Code

添加到 Roo Code 的 MCP 设置中：

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Antigravity

添加到 Antigravity 的 MCP 设置中：

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

扩展设置

在 VSCode 设置中配置 DebugMCP 行为：

{
  "debugmcp.serverPort": 3001,
  "debugmcp.timeoutInSeconds": 180,
  "debugmcp.bindHost": ["127.0.0.1", "::1"]
}

安全模型

DebugMCP 通过一个未经身份验证的本地 HTTP 端点暴露强大的调试器原语（evaluate_expression、start_debugging 等）。为了保持该接口的安全，服务器强制执行四项控制：

1. 仅回环绑定。 HTTP 服务器默认绑定到 IPv4 和 IPv6 回环地址（127.0.0.1 和 ::1），因此网络上的其他主机无法访问 http://<your-ip>:3001/mcp。同时绑定两个地址族可确保将 localhost 解析为任一地址族的客户端都能成功连接。debugmcp.bindHost 设置（字符串或字符串数组）允许你选择不同的接口（例如，将端口转发到远程容器时），但这样做会将未经身份验证的调试器暴露给任何可以路由到该地址的对象——不要将其指向 0.0.0.0 或不受信任网络上的局域网地址。

2. Host / Origin 头验证。 每个请求都必须携带一个 Host 头，其值为回环地址（localhost、127.0.0.1 或 [::1]）；Host 中的任何端口后缀也必须与服务器的监听端口匹配。任何其他 Host 值的请求——包括通过恶意网页的 DNS 重绑定到达的请求——都会被拒绝并返回 HTTP 403。当存在 Origin 头时，也会对其应用相同的回环检查。

3. 最小权限变量检查。 get_variables_values 需要显式的 variableNames 列表（最多 50 个，不支持通配符），并且只返回这些变量。它不再转储作用域中的每个变量，此前这会把代理从未请求过的无关进程状态交给它。使用 list_variable_names 来发现存在哪些变量；该工具只返回名称和类型，从不读取值。

4. 变量检查时的机密信息脱敏。 名称带有凭据特征或值匹配已知凭据形状的变量，会在响应离开扩展之前被替换为 <redacted: possible secret>。evaluate_expression 返回的求值结果也涵盖在内。当 get_variables_values 或 evaluate_expression 展开复杂值时，子项仅按名称和类型列出。当需要某个子项的值时，请使用带有精确子项路径的 evaluate_expression。每次响应的递归展开总计上限为 100 个子字段。空值（None、undefined、''）永远不会被脱敏，因此"我的令牌是空的"这类错误仍然可以调试。脱敏始终开启，无法关闭。

常见问题

DebugMCP 可与任何兼容 MCP 的 AI 助手配合使用，包括 GitHub Copilot、GitHub Copilot CLI、Cline、Cursor、Codex、Windsurf、Roo Code、Antigravity 等。如果你的助手支持模型上下文协议（Model Context Protocol），它就可以使用 DebugMCP。

是的。DebugMCP 以 extensionKind: workspace 的 VS Code 扩展运行，因此它会在你的代码所在的远程环境中激活。MCP 服务器在该远程上下文中运行于 localhost 上。

不需要。DebugMCP 会根据文件的语言/扩展名自动生成合适的调试配置。如果你有 launch.json，它会自动选择最相关的配置。

不会。DebugMCP 100% 在本地运行。MCP 服务器运行在 localhost 上，任何代码、变量或调试数据都不会被发送到外部服务。AI 助手与 MCP 服务器的通信完全在你的本地机器内进行。

在 VS Code 设置中更改端口："debugmcp.serverPort": 3002（或任何可用端口）。然后更新你的 AI 助手的 MCP 配置以使用新端口。

可以。将 testName 参数传递给 start_debugging 即可调试特定的测试方法。DebugMCP 会配置调试会话，使其在该测试中运行并在断点处暂停。

请确保 DebugMCP 已注册到你的 AI 助手的 MCP 设置中。扩展应该会自动检测并提供自我注册。如果没有，请参阅手动 MCP 服务器注册部分。另外，为获得更流畅的工作流程，请为 DebugMCP 工具启用自动批准。

是的。DebugMCP 支持用于 C#/.NET 调试的 .cs 文件和 .csproj 项目文件，包括 ASP.NET 应用程序。

故障排除

常见问题

MCP 服务器无法启动

• 症状：AI 助手无法连接到 DebugMCP

• 解决方案：

  • 检查端口 3001 是否可用

  • 重启 VSCode

  • 确认扩展已安装并激活

调试会话未在断点处停止

• 症状：已设置断点，但执行没有暂停

• 解决方案：

  • 确保正在调试正确的文件

  • 检查断点行号是否正确

  • 确认已安装相应的语言调试器扩展

调试停止时另一个 VS Code 窗口获得焦点

• 症状：打开多个 VS Code 窗口时，被调试的窗口在命中断点或完成单步执行时会跳到前台

• 解决方案：在你的用户或工作区设置中禁用 VS Code 原生的断点聚焦行为：

  {
    "debug.focusWindowOnBreak": false,
    "debug.focusEditorOnBreak": false
  }

  debug.focusWindowOnBreak 可防止被调试的窗口获得操作系统焦点。可选的 debug.focusEditorOnBreak 设置还可防止 VS Code 将焦点移到已停止的源编辑器上。DebugMCP 不会自动更改这些持久性偏好设置。

配置未被自动检测

• 症状：扩展不会提示您与 AI 助手注册

• 解决方案：

  • 从命令面板（Ctrl+Shift+P / Cmd+Shift+P）运行 DebugMCP: Show Agent Selection Popup

  • 手动添加配置（参见 手动 MCP 服务器注册）

工作原理

架构

AI Agent (Copilot/Cline/Cursor/Codex) → MCP/Streamable HTTP → DebugMCPServer → DebuggingHandler → VS Code Debug API

启动配置集成

该扩展智能地处理调试配置：

• 现有的 launch.json：如果存在 .vscode/launch.json 文件，它将：

  • 搜索相关配置

  • 当代理明确提供 configurationName 时予以遵循

  • 支持 JSONC（带注释和尾随逗号的 JSON）

• 默认配置：如果省略 configurationName，或未找到匹配的命名配置，它会根据文件扩展名检测为每种语言创建适当的默认配置

要求

• 安装了相应语言扩展的 VSCode：

  • Python：Python 扩展 用于 .py 文件

  • JavaScript/TypeScript：内置 Node.js 调试器或 JavaScript 调试器扩展

  • Java：Java 扩展包

  • C#/.NET：C# 扩展

  • C/C++：C/C++ 扩展

  • Go：Go 扩展

  • Rust：rust-analyzer 扩展

  • PHP：PHP 调试扩展

  • Ruby：Ruby 扩展 支持调试

• 兼容 MCP 的 AI 助手（Copilot、Cline、Cursor、Codex、Windsurf、Roo Code 等）

开发

要构建扩展：

npm install
npm run compile

要运行 lint：

npm run lint

要运行测试：

npm test

贡献

本项目欢迎贡献和建议。大多数贡献需要您同意一份贡献者许可协议（CLA），声明您有权且确实授予我们使用您贡献的权利。详情请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并适当地装饰 PR（例如状态检查、评论）。只需遵循机器人提供的说明。您只需在我们使用 CLA 的所有仓库中执行一次此操作。

本项目已采用 Microsoft 开源行为准则。更多信息请参阅 行为准则常见问题解答 或通过 opencode@microsoft.com 联系我们提出任何其他问题或评论。

安全性

安全漏洞应按照 https://aka.ms/SECURITY.md 上的指南进行报告。请不要通过公开的 GitHub 问题报告安全漏洞。

商标

本项目可能包含项目、产品或服务的商标或徽标。Microsoft 商标或徽标的授权使用须遵守并遵循 Microsoft 商标和品牌指南。在本项目的修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 赞助。任何第三方商标或徽标的使用均受该第三方政策的约束。

⭐ 支持 DebugMCP

如果 DebugMCP 帮助您更快地调试，请考虑在 GitHub 上给它一个星标！星标有助于项目获得曝光度并吸引贡献者。

⭐ 在 GitHub 上为 DebugMCP 加星标

星标历史

许可证

MIT 许可证 - 详见 LICENSE

此扩展由 Oz Zafar、Ori Bar-Ilan 和 Karin Brisker 创建。