Debug MCP

🚀 Debug-MCP：基于模型上下文协议的Python调试工具

Debug-MCP是一款Python调试工具，它通过简洁的API和命令行界面（CLI）提供基于断点的调试功能，旨在与AI助手和开发工具集成，为开发者提供高效、安全的调试体验。

English | 日本語

✨ 主要特性

• 基于DAP的高级调试：使用微软的debugpy进行生产级调试。
  • 断点调试：设置断点并在运行时检查局部变量。
  • 单步执行：支持真正的逐行进入、逐行跳过和逐行跳出操作。
  • 无数据损坏：隔离的进程执行避免了sys.modules问题。
  • 环境感知：自动使用目标项目的Python解释器。
• 会话管理：具有超时保护的隔离调试会话。
• 双接口设计：
  • 命令行界面（CLI）：交互式调试，输出美观的表格。
  • MCP服务器：基于官方MCP SDK，便于AI助手集成。
• 安全执行：具有可配置限制的沙盒子进程执行。
• 类型安全：使用Pydantic v2模式进行请求/响应验证。
• 异步支持：基于MCP SDK构建，完全支持异步/等待。
• 全面测试：共254个测试（119个单元测试 + 122个集成测试 + 13个探索性测试），覆盖DAP工作流、会话管理和边缘情况。
• 旧版兼容性：可选的bdb模式，确保向后兼容。

🚀 快速开始

📦 安装指南

# 克隆仓库
git clone https://github.com/your-org/Debug-MCP.git
cd Debug-MCP

# 创建虚拟环境
uv venv

# 安装并支持CLI
uv pip install -e ".[cli]"

VS Code Copilot集成

要在VS Code中使用此工具与GitHub Copilot集成，请设置MCP服务器配置。

详细说明请参阅VS Code设置指南。

快速设置（从Debug-MCP仓库使用）：

1. 创建MCP配置目录（macOS/Linux）：

   mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat
   

2. 编辑mcp.json文件：

   {
     "mcpServers": {
       "python-debug": {
         "command": "uv",
         "args": ["run", "mcp-debug-server", "--workspace", "${workspaceFolder}"],
         "env": {"PYTHONUNBUFFERED": "1"}
       }
     }
   }
   

3. 重启VS Code

从其他仓库使用： 使用此工具时，需指定Debug-MCP的安装路径：

{
  "mcpServers": {
    "python-debug": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Debug-MCP",
        "run",
        "mcp-debug-server",
        "--workspace",
        "${workspaceFolder}"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

请将/absolute/path/to/Debug-MCP替换为实际的Debug-MCP安装路径。

使用Copilot Chat：

@workspace 在src/main.py的第42行设置断点，并显示该点的局部变量。

完整的配置示例请参阅mcp-config-example.json。

💻 使用示例

命令行界面（CLI）使用示例（推荐用于交互式调试）

# 启动调试会话
SESSION_ID=$(uv run mcp-debug start-session src/app.py | jq -r .sessionId)

# 运行到断点并检查局部变量
uv run mcp-debug run-to-breakpoint $SESSION_ID src/app.py 42 --format table

# 继续执行到下一个断点
uv run mcp-debug continue $SESSION_ID src/app.py 100 --format table

# 检查会话状态
uv run mcp-debug state $SESSION_ID --format table

# 结束会话
uv run mcp-debug end $SESSION_ID

更多CLI示例请参阅快速入门指南。

API使用示例（Python集成）

from pathlib import Path
from mcp_debug_tool.sessions import SessionManager
from mcp_debug_tool.schemas import StartSessionRequest, BreakpointRequest

# 初始化
workspace = Path.cwd()
manager = SessionManager(workspace)

# 创建会话
req = StartSessionRequest(entry="src/main.py", args=["--verbose"])
session = manager.create_session(req)

# 运行到断点
bp_req = BreakpointRequest(file="src/main.py", line=15)
result = manager.run_to_breakpoint(session.sessionId, bp_req)

if result.hit:
    print(f"在 {result.frameInfo.file}:{result.frameInfo.line} 处暂停")
    print(f"局部变量: {result.locals}")

# 继续执行
continue_result = manager.continue_execution(
    session.sessionId, 
    BreakpointRequest(file="src/main.py", line=42)
)

# 清理会话
manager.end_session(session.sessionId)

🔧 技术细节

安全与限制

执行限制

• 超时时间：每个断点操作的超时时间为20秒（可配置）。
• 输出捕获：每个会话的最大输出捕获量为10MB。
• 变量深度：局部变量检查的最大嵌套级别为2级。
• 集合大小：列表/字典中最多显示50个项目。
• 字符串长度：字符串在截断前的最大长度为256个字符。

安全措施

• 路径验证：只允许使用项目相对路径（不允许..遍历）。
• 子进程隔离：被调试程序在隔离的子进程中运行。
• 工作目录：锁定到工作区根目录。
• 无网络访问：被调试程序没有特殊的网络访问权限（应用程序代码仍可使用网络）。

⚠️ 重要提示

调试器在执行用户代码时限制较少，请仅调试受信任的代码。

架构

当前实现（v2 - 基于DAP）

Debug-MCP现在使用DAP（调试适配器协议） 通过debugpy进行生产调试：

┌─────────────────────────────────────────────────┐
│ MCP服务器 (server.py)                           │
│ - 官方MCP SDK (异步)                            │
│ - 工具注册与路由                                │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ 会话管理器 (sessions.py)                        │
│ - 生命周期管理                                 │
│ - DAP/bdb模式选择                               │
└────────────────┬────────────────────────────────┘
                 │
                 ▼ (DAP模式 - 默认)
┌─────────────────────────────────────────────────┐
│ DAP同步包装器 (dap_wrapper.py)                  │
│ - 同步DAP接口                                   │
│ - 事件队列管理                                 │
│ - 超时处理                                     │
└────────────────┬────────────────────────────────┘
                 │ DAP协议 (JSON-RPC)
                 ▼
┌─────────────────────────────────────────────────┐
│ debugpy服务器 (独立进程)                        │
│ - 微软官方DAP实现                               │
│ - 处理断点、单步执行、变量检查                  │
│ - 管理目标脚本执行                              │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ 目标Python脚本                                  │
│ - 在隔离进程中运行                              │
│ - 完全访问目标依赖项                            │
│ - 无sys.modules损坏                             │
└─────────────────────────────────────────────────┘

为什么选择DAP（debugpy）？

• ✅ 无sys.modules损坏 - 在单独的进程中运行。
• ✅ 真正的单步执行 - 跨步骤保持执行状态。
• ✅ 自动环境处理 - 使用目标Python解释器。
• ✅ 行业标准 - 微软经过实战检验的实现。
• ✅ 功能丰富 - 支持逐行进入/跳过/跳出、条件断点、监视表达式。
• ✅ 面向未来 - 易于扩展高级调试功能。

通信流程：

1. MCP客户端（VS Code Copilot） → MCP服务器（工具调用）
2. 服务器 → 会话管理器（通过异步包装器的同步方法）
3. 会话管理器 → DAP同步包装器（管理DAP会话）
4. DAP同步包装器 ↔ debugpy服务器（通过套接字使用DAP协议）
5. debugpy捕获局部变量 → DAP同步包装器 → 会话管理器 → 服务器 → 客户端

旧版bdb模式

基于bdb的实现仍然可用，以确保兼容性（useDap=false）：

会话管理器 → runner_main.py (子进程) → 调试控制器 (bdb)

然而，DAP现在是默认模式，建议在所有用例中使用。bdb模式存在已知问题：

• 多次运行时会出现sys.modules损坏。
• 没有真正的单步执行（基于重放）。
• 复杂的PYTHONPATH管理。

文件组织（2025-11-03）

活动文件（生产环境）：

• ✅ server.py - MCP SDK服务器
• ✅ sessions.py - 会话生命周期管理
• ✅ dap_wrapper.py - DAP同步包装器（主要）
• ✅ dap_client.py - 底层DAP协议客户端（主要）
• ✅ schemas.py - Pydantic模型
• ✅ utils.py - 变量表示辅助函数和路径实用工具

旧版文件（兼容性）：

• ⚠️ debugger.py - 基于bdb的引擎（旧版，使用useDap=false）
• ⚠️ runner_main.py - bdb子进程运行器（旧版）

已移除文件：

• runner.py - 旧的多进程方法（2025-10-30移除）

开发

环境设置

详细的设置说明请参阅docs/development.md。

快速命令：

# 运行所有测试（254个测试：119个单元测试 + 122个集成测试 + 13个探索性测试）
uv run pytest

# 仅运行单元测试
uv run pytest tests/unit/

# 仅运行集成测试
uv run pytest tests/integration/

# 运行测试并生成覆盖率报告
uv run pytest --cov=src/mcp_debug_tool --cov-report=html

# 代码检查
uv run ruff check .

# 代码格式化
uv run ruff format .

# 自动修复代码检查问题
uv run ruff check --fix .

项目结构

Debug-MCP/
├── src/
│   ├── mcp_debug_tool/      # 核心调试引擎
│   │   ├── server.py        # MCP SDK服务器 (v2.0+)
│   │   ├── sessions.py      # 会话管理 (DAP/bdb模式选择)
│   │   ├── dap_wrapper.py   # DAP同步包装器 (主要)
│   │   ├── dap_client.py    # DAP协议客户端 (主要)
│   │   ├── debugger.py      # 基于bdb的调试器 (旧版, 使用useDap=false)
│   │   ├── runner_main.py   # bdb子进程运行器 (旧版)
│   │   ├── schemas.py       # Pydantic模型
│   │   └── utils.py         # 变量表示辅助函数
│   └── cli/
│       └── main.py          # Typer CLI
├── tests/
│   ├── unit/                # 单元测试 (调试器、模式、DAP、会话)
│   └── integration/         # 集成测试 (DAP工作流、bdb兼容性)
├── specs/
│   └── 001-python-debug-tool/  # 规范文档
└── docs/                    # 附加文档
    ├── dap-phase*-*.md      # DAP集成文档
    └── roadmap.md           # 未来增强计划

📚 详细文档

• VS Code设置指南 - 如何在VS Code中使用MCP工具与Copilot集成 ⭐
• 快速入门指南 - CLI和API使用示例
• 规范文档 - 完整的功能规范
• 数据模型 - 实体模式和验证规则
• 研究文档 - 设计决策和原理
• 开发指南 - 设置和贡献指南
• 性能调优 - 超时和资源配置
• 路线图 - 计划中的v2功能

当前状态

v2.0已发布！DAP集成完成 🎉

• ✅ 阶段1：基础功能（完成 - 6/6测试通过）
• ✅ 阶段2：核心逻辑（完成 - 28/28测试通过）
• ✅ 阶段3：会话生命周期（完成 - 29/29测试通过）
• ✅ 阶段4：断点操作（完成 - 41/41测试通过）
• ✅ 阶段5：错误可见性（完成 - 71/71测试通过）
• ✅ 阶段6：MCP SDK迁移（完成 - 基于SDK的服务器，支持异步）
• ✅ 阶段7：DAP集成（完成 - 生产级debugpy集成）

v2.0的新特性：

• DAP（debugpy）现在是默认模式 - 不再有sys.modules损坏问题！
• 真正的单步执行 - 逐行进入、逐行跳过、逐行跳出功能均正常工作。
• 自动环境处理 - 使用目标项目的Python解释器。
• 行业标准协议 - 微软经过实战检验的实现。
• 增强的可靠性 - 隔离的进程执行防止崩溃。
• 向后兼容 - 旧版bdb模式仍然可用，可通过useDap=false启用。

从v1.x迁移：

• 现有代码可以直接使用（默认启用DAP）。
• 若要显式使用bdb：StartSessionRequest(entry="...", useDap=False)。
• 建议：默认使用DAP以获得最佳效果。

限制（v2）

• 仅支持脚本入口：不支持模块（python -m）或pytest目标（计划在v2.1中支持）。
• 单线程：不支持多线程调试（计划在v2.1中支持）。
• 行断点：条件断点尚未通过MCP暴露（DAP支持）。

✅ v1已解决的问题：

• 无单步执行功能 → 现在可用：逐行进入、逐行跳过、逐行跳出。
• sys.modules损坏 → 已修复：DAP使用隔离进程。
• Python环境不匹配 → 已修复：使用目标解释器。

计划中的v2.1+增强功能请参阅docs/roadmap.md。

贡献

1. 分叉仓库。
2. 创建功能分支 (git checkout -b feature/amazing-feature)。
3. 进行更改并编写测试。
4. 运行测试和代码检查 (uv run pytest && uv run ruff check .)。
5. 提交更改 (git commit -m '添加出色的功能')。
6. 推送到分支 (git push origin feature/amazing-feature)。
7. 打开拉取请求。

📄 许可证

本项目采用MIT许可证，请参阅LICENSE文件获取详细信息。

致谢

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

• debugpy - 微软的Python调试器（DAP实现）
• MCP SDK - 模型上下文协议Python SDK
• bdb/pdb - Python的标准调试器框架（旧版模式）
• Pydantic - 使用Python类型注解进行数据验证
• Typer - 基于Click构建的CLI框架
• Rich - 美观的终端格式化工具
• pytest - 测试框架