AI导哈

Python调试服务

通过自然语言启用AI代理调试Python代码，提供pytest JSON报告和DAP协议控制。

  • by markomanninen
  • Python
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 markomanninen/mcp-debugpy

使用说明

mcp调试程序

MCP服务器，用于使用debugpy和Debug Adapter Protocol进行AI辅助Python调试。

允许AI代理通过自然语言调试Python代码。此MCP服务器提供：

  • pytest JSON 机器可读故障报告
  • DAP（调试适配器协议） 直播控制 debugpy 会话（断点、继续、变量）
  • MCP服务器 公开工具：运行测试、读取JSON和发送DAP命令

快速启动

macOS/Linux：

git clone <this-folder>
cd mvp-agent-debug
./setup.sh

# Activate the venv and run demos/tests:
source .venv/bin/activate
python src/dap_stdio_direct.py        # direct adapter walkthrough
python -m pytest tests/test_mcp_server.py  # verify MCP tooling

窗户：

git clone <this-folder>
cd mvp-agent-debug
setup.bat

REM Activate the venv and run demos/tests:
.venv\Scripts\activate
python src\dap_stdio_direct.py
python -m pytest tests\test_mcp_server.py

安装（从源代码）：

python -m pip install -e '.[dev]'

重要： 在每次提交之前安装git钩子来运行CI检查：

./scripts/install-hooks.sh

这可以通过在允许提交之前自动运行ruff、black、mypy和pytest来防止CI失败。

激活virtualenv项目后运行CLI：

mcp-debug-server --help

然后使用VS Code和/或Claude注册MCP服务器，以便他们可以自动启动它：

python scripts/configure_mcp_clients.py

打开您的MCP感知聊天界面并调用以下工具 run_tests_json 或 dap_launch （参见 docs/mcp_usage.md 完整的演练）。

示例应用程序故意包含一个错误来演示失败的测试和一个交互式断点。

可选助手

跑 python scripts/configure_mcp_clients.py 检测现有的VS Code/Claude MCP条目，交互式地添加/更新/删除它们，并生成Claude代码段。适用于macOS、Linux和Windows。

开发人员工具

此存储库使用预提交挂钩和CI进行linting、格式化和类型检查。

在本地安装挂钩：

source .venv/bin/activate
pip install pre-commit
pre-commit install
pre-commit run --all-files

如果您更喜欢手动运行挂钩，则CI会运行 ruff, black --check，以及 mypy 之前 pytest.

📘 有关每个MCP工具的分步演练（包括VS Code和Claude的建议代理工作流），请参阅 docs/mcp_usage.md.

使用MCP工具

重要：MCP服务器由MCP客户端自动管理。您不需要从命令行手动启动此服务器。相反，在MCP客户端（VS Code或Claude Desktop）中配置它，它将在需要时自动启动。

配置

VS Code

添加到您的 settings.json:

{
  "mcp.servers.agentDebug": {
    "command": "/path/to/your/project/.venv/bin/python",
    "args": ["src/mcp_server.py"],
    "cwd": "/path/to/your/project",
    "env": {
      "PYTHONPATH": "/path/to/your/project/src"
    }
  }
}

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "agentDebug": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["src/mcp_server.py"],
      "cwd": "/path/to/your/project",
      "env": {
        "PYTHONPATH": "/path/to/your/project/src"
      }
    }
  }
}

手动测试（仅协议开发）

在正常使用情况下，您永远不应该运行 python src/mcp_server.py 您自己——MCP客户端自动生成和管理流程。以下注释仅适用于构建自定义MCP客户端或尝试原始协议流量的开发人员。

步骤1-在MCP客户端注册服务器

  • VS代码（AI聊天+MCP扩展） --运行辅助脚本（支持添加/更新/删除）或手动添加条目。

    # Optional helper that updates VS Code settings and writes a Claude snippet
python scripts/configure_mcp_clients.py

    如果手动配置，请将此添加到 settings.json:

    {
  "mcp.servers.agentDebug": {
    "command": "${workspaceFolder}/.venv/bin/python", // Windows: ".venv\\Scripts\\python.exe"
    "args": ["src/mcp_server.py"],
    "cwd": "${workspaceFolder}"
  }
}

    每当您打开聊天时，VS Code都会自动生成和管理服务器。

  • 克劳德桌面 --打开 设置→ 模型上下文协议→ 添加服务器 并输入（或粘贴生成的代码段）：

    Command: /full/path/to/.venv/bin/python
Arguments: src/mcp_server.py
Working dir: /full/path/to/mvp-agent-debug

    克劳德根据需要启动流程，并在空闲时将其拆除。

  • 手动/CLI使用（仅用于协议调试） --发射 python src/mcp_server.py 直接将阻止您的终端等待MCP框架的JSON消息。仅当您正在编写自定义MCP客户端并且需要原始stdin/stdout端点时，才执行此操作。

步骤2–在debugpy下启动示例应用程序

  • 示例工具请求：

    {
  "name": "dap_launch",
  "input": {
    "program": "src/sample_app/app.py",
    "cwd": ".",
    "breakpoints": [8],
    "wait_for_breakpoint": true
  }
}

响应包括初始化/发射有效载荷以及最终的 stoppedEvent 一旦第8行被击中。如果您希望跳过终端噪音，请删除或保留 [dap:event] … 调试打印 src/dap_stdio_client.py--它们纯粹是诊断性的。

步骤3-检查并恢复

  • 呼叫 dap_locals 获取线程、堆栈帧、作用域和局部变量。
  • 使用 dap_continue （可选择使用特定 thread_id)恢复执行。
  • 呼叫 dap_shutdown 当你完成时；它清晰地分解了适配器进程。

步骤4–通过MCP运行测试

  • 示例工具请求：

    { "name": "run_tests_json" }

或者专注于一个子集 run_tests_focus.

存储库布局

  • src/sample_app/app.py –有bug的小应用程序（导致示例失败）
  • src/sample_app/tests/test_app.py –pytest套件涵盖了该bug
  • src/dap_stdio_client.py –与stdio客户端对话 debugpy.adapter，处理反向请求
  • src/dap_stdio_direct.py –直接适配器演练（初始化→ 断点→ 配置完成→ 发射→ 步进）
  • src/mcp_server.py –stdio MCP表面结合了pytest助手和DAP启动/检查工具
  • tests/test_mcp_server.py –伪造适配器以验证重试和控制流的单元测试
  • examples/ –带有xfailed测试和详细README的其他小项目
    • examples/math_bug –算术错误演示
    • examples/async_worker –异步收集bug演示
    • examples/gui_counter –Tkinter计数器UI展示GUI调试
    • examples/web_flask –用于服务器端演练的Flask端点
  • docs/testing.md –所有自动化测试的综合说明
  • STATUS.md / FINAL_REPORT.md –维护人员的项目快照

需求

  • requirements.txt –运行时依赖关系（MCP服务器、调试程序、Flask）
  • requirements-dev.txt –仅测试依赖关系（pytest、pytest-asyncio、JSON报告）

贡献

看 CONTRIBUTING.md 获取本地设置提示和测试指导。

安全

将调试服务器绑定到 127.0.0.1 并为远程主机使用SSH隧道。

相关 MCP