AI导哈

Python调试服务器

PDB MCP服务器是一个用于Python调试的工具，支持通过pdb进行脚本调试和pytest测试调试，并提供Claude代码插件的结构化调试工作流。

  • by zc277584121
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 zc277584121/pdb-mcp

使用说明

PDB MCP服务器

使用pdb进行Python调试的模型上下文协议（MCP）服务器，捆绑为 Claude代码插件 使用调试最佳实践。

特性

  • 启动调试会话：使用pdb在调试模式下启动Python脚本
  • 启动Pytest调试会话：在测试失败时使用自动pdb运行pytest
  • 执行PDB命令：发送命令以控制调试会话
  • 自动检测Python解释器：自动使用虚拟环境Python
  • 模块化架构：会话和服务器模块的关注点完全分离
  • Claude代码插件：包括教授Claude结构化调试工作流程和最佳实践的技能

安装

从PyPI安装

pip install pdb-mcp

使用紫外线进行安装（推荐）⚡️

uvx 将自动安装软件包并运行命令。

uvx pdb-mcp

开发安装

pip install -e .

用法

作为MCP服务器

运行服务器：

pdb-mcp

服务器公开了三个工具：

1. start_debug

启动Python脚本的调试会话。

参数：

  • script_path （必填）：要调试的Python脚本的路径
  • python_path （必填）：正在调试的项目的Python解释器的路径
  • working_directory （必填）：运行命令的目录（应该是项目目录）
  • args （可选）：传递给脚本的命令行参数
  • timeout （可选）：在没有新输出的情况下等待返回的时间（默认值：5.0）。只要有新的输出，就会一直等待。
  • env （可选）：为调试会话设置的环境变量（例如，{“DEBUG”：“1”}）

例子：

{
  "script_path": "test_script.py",
  "python_path": "/path/to/python",
  "working_directory": "/path/to/project",
  "env": {"DEBUG": "1"}
}

2. start_pytest_debug

启动pytest调试会话，该会话在测试失败时自动进入pdb。

参数：

  • args （必需）：在“pytest--pdb”之后传递的参数。可以包括测试路径、过滤器和pytest选项（例如，“tests/test_example.py-v”、“-k test_login”、“-x test_auth.py”）
  • python_path （必填）：正在调试的项目的Python解释器的路径
  • working_directory （必填）：运行命令的目录（应该是项目目录）
  • timeout （可选）：在没有新输出的情况下等待返回的时间（默认值：10.0秒）。只要有新的输出，就会一直等待。
  • env （可选）：为调试会话设置的环境变量（例如，{“DEBUG”：“1”}）

例子：

{
  "args": "tests/test_example.py -v",
  "python_path": "/path/to/python",
  "working_directory": "/path/to/project",
  "env": {"DEBUG": "1"}
}

3. execute_pdb_command

在活动调试会话中执行pdb命令。

参数：

  • command （必填）：要执行的pdb命令
  • timeout （可选）：返回前等待无新输出的时间（秒）（默认值：5.0）

可用命令：

  • n （next）：执行下一行（不要进入函数）
  • s （step）：执行下一行（进入函数）
  • b <line>：在第行设置断点（例如。， b 10)
  • b <file>:<line>：在另一个文件中设置断点（例如。， b utils.py:5)
  • l （列表）：显示当前行周围的代码
  • p <var>：打印变量值（例如。， p user_name)
  • c （continue）：继续执行，直到下一个断点
  • q （退出）：退出调试会话
  • h （help）：显示所有命令的帮助
  • r （return）：执行直到当前函数返回
  • w （where）：显示调用堆栈
  • cl <breakpoint>：清除断点
  • a （args）：打印当前函数的参数

例子：

{
  "command": "n"
}

测试

基本脚本调试

提供了一个示例测试脚本： test_script.py

运行自动测试：

uv run python test_mcp_client.py

调试工作流程示例：

  1. 开始调试： start_debug 随着 script_path = "test_script.py"
  2. 步骤代码： execute_pdb_command 随着 command = "n"
  3. 查看代码： execute_pdb_command 随着 command = "l"
  4. 打印变量： execute_pdb_command 随着 command = "p num"
  5. 继续： execute_pdb_command 随着 command = "c"
  6. 退出： execute_pdb_command 随着 command = "q"

Pytest调试

提供了一个示例测试文件： test_example.py

运行pytest调试测试：

uv run python test_pytest_client.py

测试将：

  1. 使用运行pytest -x --pdb 旗帜
  2. 在第一次测试失败时停止
  3. 断言失败时掉入pdb
  4. 允许您检查变量和调试

配置

要与Claude Desktop或其他MCP客户端一起使用，请添加到您的配置文件中（例如。， claude_desktop_config.json):

使用uvx（推荐）

{
  "mcpServers": {
    "pdb-debugger": {
      "command": "uvx",
      "args": ["--from", "pdb-mcp", "pdb-mcp"]
    }
  }
}

使用本地开发版本

{
  "mcpServers": {
    "pdb-debugger": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/pdb-mcp",
        "run",
        "pdb-mcp"
      ]
    }
  }
}

替换 /path/to/pdb-mcp 与这个项目的实际路径。

建筑

项目结构

src/pdb_mcp/
├── __init__.py      # Entry point and main function
├── session.py       # PdbSession class for managing pdb processes
└── server.py        # MCP server and tool definitions

会话管理

这 PdbSession 类维护一个持久的pdb进程：

  • 用途 subprocess.Popen 使用目标脚本启动pdb
  • 通过stdin/stdout管道进行通信
  • 后台线程异步读取输出
  • 在命令执行之间维护调试会话状态
  • 自动从虚拟环境中检测Python解释器

Python解释器配置

这 python_path 参数指定Python解释器 客户项目 （不是服务器的环境）：

  • 必需参数：代理应提供项目的Python解释器路径
  • 典型值:
    • .venv/bin/python 或 venv/bin/python 用于虚拟环境
    • /usr/bin/python3 系统Python
    • conda或其他环境的自定义路径
  • 后备方案：如果未提供或为空，则返回 "python" 命令（使用系统PATH）

注： 服务器不使用自己的Python(sys.executable)因为MCP服务器可能在与正在调试的客户端项目不同的环境中运行。

工作目录配置

两者 start_debug 和 start_pytest_debug 要求a working_directory 参数：

  • 必需参数：应该是项目的根目录或包含脚本的目录
  • 目的：确保脚本在正确的目录上下文中运行
  • 用例:
    • 使用相对文件路径的脚本
    • 具有特定目录结构要求的项目
    • 从项目根目录加载配置文件
  • 代理集成：代理（如Claude）通常知道项目目录，应该提供它

例子：

{
  "script_path": "src/main.py",
  "working_directory": "/home/user/myproject"
}

这相当于运行：

cd /home/user/myproject && python -m pdb src/main.py

智能输出等待

服务器使用智能输出等待机制：

  • 单个超时参数：返回前等待没有新输出的时间
  • 没有总时间限制：只要有新的输出，服务器就会一直等待
  • 自适应：快速命令返回速度快，慢速命令获得所需的时间
  • 用户可配置：所有工具都接受 timeout 参数

它是如何工作的：

  1. 服务器每0.1秒连续检查一次输出
  2. 每次有新的输出到达时，空闲定时器都会重置
  3. 当没有新的输出时 timeout 秒，它返回
  4. 无论脚本运行多长时间，如果它继续产生输出，服务器都会等待

默认超时值：

  • start_debug：5.0秒（pdb通常快速启动）
  • start_pytest_debug：10.0秒（测试可能会缓慢产生输出）
  • execute_pdb_command：5.0秒（大多数命令都很快）

例子： 运行10秒但每0.5秒打印一次的脚本可以很好地使用 timeout=3.0，因为空闲时间从不超过3秒。

Claude代码插件

这个项目也是 Claude代码插件 它提供调试最佳实践作为技能。当作为插件安装时，Claude会自动收到结构化的调试指导。

插件安装

# Install as a Claude Code plugin
claude plugin add /path/to/pdb-mcp

或在本地进行测试：

claude --plugin-dir /path/to/pdb-mcp

包含的技能

PDB调试最佳实践

调试Python脚本时自动激活。指导克劳德：

  • 分析代码并规划断点 之前 启动调试会话
  • 根据问题类型在战略位置设置断点
  • 在每个断点处遵循系统调查模式
  • 针对不同的调试场景使用高效的pdb命令

Pytest调试最佳实践

调试测试失败时自动激活。指导克劳德：

  • 选择正确的调试模式(--pdb vs --trace)根据故障类型
  • 调试前缩小到特定的失败测试
  • 浏览调用堆栈以查找应用程序代码中的根本原因
  • 处理常见的pytest模式（夹具、参数化测试、模拟）

插件结构

pdb-mcp/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest
├── .mcp.json                    # MCP server configuration
├── skills/
│   ├── pdb-debugging/
│   │   ├── SKILL.md             # Core debugging best practices
│   │   └── references/
│   │       ├── debugging-workflows.md    # Detailed workflows
│   │       └── pdb-commands-cheatsheet.md # Command reference
│   └── pytest-debugging/
│       ├── SKILL.md             # Pytest debugging best practices
│       └── references/
│           └── pytest-debug-patterns.md  # Advanced patterns
└── src/pdb_mcp/                 # MCP server source code

许可证

有关详细信息，请参阅LICENSE文件。

相关 MCP