使用说明
调试MCP：通过模型上下文协议进行Python调试
Python调试工具，通过干净的API和CLI公开基于断点的调试功能，专为与AI助手和开发工具集成而设计。
英语| 日本语
特性
- 通过DAP进行高级调试：使用Microsoft的debugpy进行生产就绪调试
- 断点调试：设置断点并在运行时检查局部变量
- 步骤执行：真正的介入、超越、退出操作
- 无腐败：独立的进程执行可防止sys.modules问题
- 环境感知：自动使用目标项目的Python解释器
- 会话管理：具有超时保护的隔离调试会话
- 双接口:
- 命令行界面：交互式调试，具有漂亮的表输出
- MCP服务器：基于MCP SDK的AI助手官方集成
- 安全执行：具有可配置限制的沙盒子流程执行
- 类型安全：用于请求/响应验证的Pydantic v2模式
- 异步支持：基于MCP SDK构建，完全支持async/await
- 综合测试：254个测试（119个单元+122个集成+13个探索），涵盖DAP工作流程、会话管理和边缘案例
- 传统兼容性：可选的bdb模式可实现向后兼容性
快速开始
安装
# Clone repository
git clone https://github.com/your-org/Debug-MCP.git
cd Debug-MCP
# Create virtual environment
uv venv
# Install with CLI support
uv pip install -e ".[cli]"
VS代码副本集成
要在VS Code中将此工具与GitHub Copilot一起使用，请设置MCP服务器配置。
看 VS代码设置指南 详细说明。
快速设置（从调试MCP存储库使用）：
-
创建MCP配置目录（macOS/Linux）：
mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat -
编辑
mcp.json文件：{ "mcpServers": { "python-debug": { "command": "uv", "args": ["run", "mcp-debug-server", "--workspace", "${workspaceFolder}"], "env": {"PYTHONUNBUFFERED": "1"} } } } -
重新启动VS代码
从另一个存储库使用：
从其他存储库使用此工具时，请指定调试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 使用调试MCP安装的实际路径。
使用Copilot聊天：
@workspace Set a breakpoint at line 42 in src/main.py and
show me the local variables at that point.
看 mcp-config-example.json 以获得完整的配置示例。
CLI用法（建议用于交互式调试）
# Start a debug session
SESSION_ID=$(uv run mcp-debug start-session src/app.py | jq -r .sessionId)
# Run to breakpoint and inspect locals
uv run mcp-debug run-to-breakpoint $SESSION_ID src/app.py 42 --format table
# Continue to next breakpoint
uv run mcp-debug continue $SESSION_ID src/app.py 100 --format table
# Check session state
uv run mcp-debug state $SESSION_ID --format table
# End session
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
# Initialize
workspace = Path.cwd()
manager = SessionManager(workspace)
# Create session
req = StartSessionRequest(entry="src/main.py", args=["--verbose"])
session = manager.create_session(req)
# Run to breakpoint
bp_req = BreakpointRequest(file="src/main.py", line=15)
result = manager.run_to_breakpoint(session.sessionId, bp_req)
if result.hit:
print(f"Paused at {result.frameInfo.file}:{result.frameInfo.line}")
print(f"Locals: {result.locals}")
# Continue execution
continue_result = manager.continue_execution(
session.sessionId,
BreakpointRequest(file="src/main.py", line=42)
)
# Cleanup
manager.end_session(session.sessionId)
安全和限制
执行限制
- 超时：每个断点操作20秒（可配置）
- 输出捕获：每个会话最大10MB
- 可变深度：局部变量检查中最多2级嵌套
- 收藏大小：列表/字典中最多显示50个项目
- 字符串长度：截断前最多256个字符
安全
- 路径验证：只允许项目相对路径（否
..遍历） - 子流程隔离：Debuggee在独立的子进程中运行
- 工作目录：锁定到工作区根目录
- 没有网络：Debuggee没有特殊的网络访问权限（应用程序代码仍可能使用网络）
⚠️ 重要：调试器以最小的限制执行用户代码。仅调试受信任的代码。
建筑
当前实施（v2-基于DAP）
调试MCP现在使用 DAP（调试适配器协议） 通过debugpy进行生产调试：
┌─────────────────────────────────────────────────┐
│ MCP Server (server.py) │
│ - Official MCP SDK (async) │
│ - Tool registration & routing │
└────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Session Manager (sessions.py) │
│ - Lifecycle management │
│ - DAP/bdb mode selection │
└────────────────┬────────────────────────────────┘
│
▼ (DAP mode - default)
┌─────────────────────────────────────────────────┐
│ DAPSyncWrapper (dap_wrapper.py) │
│ - Synchronous DAP interface │
│ - Event queue management │
│ - Timeout handling │
└────────────────┬────────────────────────────────┘
│ DAP Protocol (JSON-RPC)
▼
┌─────────────────────────────────────────────────┐
│ debugpy Server (separate process) │
│ - Microsoft's official DAP implementation │
│ - Handles breakpoints, stepping, variables │
│ - Manages target script execution │
└────────────────┬────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ Target Python Script │
│ - Runs in isolated process │
│ - Full access to target dependencies │
│ - No sys.modules corruption │
└─────────────────────────────────────────────────┘
为什么选择DAP（debugpy）？
- ✅ 没有sys.modules损坏 -在单独的进程中运行
- ✅ 真正的步骤执行 -跨步骤维护执行状态
- ✅ 自动环境处理 -使用目标Python解释器
- ✅ 行业标准 -微软久经考验的实施
- ✅ 丰富的功能 -介入/结束/退出、条件断点、观察表达式
- ✅ 经得起未来考验 -易于扩展，具有高级调试功能
通信流程：
- MCP客户端（VS代码副本）→ MCP服务器（工具调用）
- 服务器→ SessionManager（通过异步包装器同步方法）
- 会话管理器→ DAPSyncWrapper（管理DAP会话）
- DAPSyncWrapper↔ debugpy服务器（套接字上的DAP协议）
- debugpy捕获本地变量→ DAPSyncWrapper→ 会话管理器→ 服务器→ 客户端
传统bdb模式
基于bdb的实现仍然可以兼容(useDap=false):
SessionManager → runner_main.py (subprocess) → DebugController (bdb)
然而， DAP现在是默认设置 并推荐用于所有用例。bdb模式存在已知问题：
- sys.modules损坏，多次运行
- 没有真正的步骤执行（基于回放）
- 复杂的巨蟒管理
文件组织（2025-11-03）
活动文件（生产）:
- ✅
server.py-MCP SDK服务器 - ✅
sessions.py-会话生命周期管理 - ✅
dap_wrapper.py-DAP同步包装器（主） - ✅
dap_client.py-低级DAP协议客户端（主） - ✅
schemas.py-Pydantic模型 - ✅
utils.py-变量repr助手和路径实用程序
旧文件（兼容性）:
- ⚠️
debugger.py-基于bdb的引擎（遗留，使用useDap=false) - ⚠️
runner_main.py-bdb子流程运行器（遗留）
已删除文件:
- ~~
runner.py~~旧的多处理方法（2025-10-30年删除）
发展
设置
看 docs/development.md 有关详细的设置说明。
快速命令：
# Run all tests (254 tests: 119 unit + 122 integration + 13 exploration)
uv run pytest
# Run only unit tests
uv run pytest tests/unit/
# Run only integration tests
uv run pytest tests/integration/
# Run tests with coverage
uv run pytest --cov=src/mcp_debug_tool --cov-report=html
# Lint
uv run ruff check .
# Format
uv run ruff format .
# Auto-fix lint issues
uv run ruff check --fix .
项目结构
Debug-MCP/
├── src/
│ ├── mcp_debug_tool/ # Core debugging engine
│ │ ├── server.py # MCP SDK-based server (v2.0+)
│ │ ├── sessions.py # Session management (DAP/bdb mode selection)
│ │ ├── dap_wrapper.py # DAP synchronous wrapper (PRIMARY)
│ │ ├── dap_client.py # DAP protocol client (PRIMARY)
│ │ ├── debugger.py # bdb-based debugger (LEGACY, use useDap=false)
│ │ ├── runner_main.py # bdb subprocess runner (LEGACY)
│ │ ├── schemas.py # Pydantic models
│ │ └── utils.py # Variable repr helpers
│ └── cli/
│ └── main.py # Typer CLI
├── tests/
│ ├── unit/ # Unit tests (debugger, schemas, DAP, sessions)
│ └── integration/ # Integration tests (DAP workflows, bdb compat)
├── specs/
│ └── 001-python-debug-tool/ # Specification documents
└── docs/ # Additional documentation
├── dap-phase*-*.md # DAP integration documentation
└── roadmap.md # Future enhancements
文档
- VS代码设置指南 -如何在VS Code Copilot中使用MCP工具⭐
- 快速入门指南 -CLI和API使用示例
- 规格说明 -完整的功能规格
- 数据模型 -实体模式和验证规则
- 研究 -设计决策和基本原理
- 开发指南 -设置和贡献指南
- 性能调整 -超时和资源配置
- 路线图 -计划中的v2功能
当前状态
v2.0发布了！DAP集成完成 🎉
- ✅ 第一阶段：基础（完成-6/6项测试通过）
- ✅ 第2阶段：核心逻辑（完成-28/28测试通过）
- ✅ 第3阶段：会话生命周期（完成-29/29测试通过）
- ✅ 第4阶段：断点操作（完成-41/41测试通过）
- ✅ 第5阶段：错误可见性（完成-71/71测试通过）
- ✅ 第6阶段：MCP SDK迁移（完整-基于SDK的服务器，支持异步）
- ✅ 第7阶段：DAP集成（完整-生产就绪调试集成）
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模块损坏~~→ 固定的：DAP使用隔离进程
- ~~ Python环境不匹配~~→ 固定的：使用目标解释器
看 docs/roadmap.md 用于计划中的v2.1+增强功能。
贡献
- 分叉存储库
- 创建要素分支(
git checkout -b feature/amazing-feature) - 通过测试进行更改
- 运行测试和梳理(
uv run pytest && uv run ruff check .) - 提交更改(
git commit -m 'Add amazing feature') - 推送到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
MIT许可证-请参阅 许可证 详细信息文件
致谢
内置：
