Xdebug MCP

🚀 Xdebug MCP Server

Xdebug MCP Server 是一个 MCP（模型上下文协议）服务器，它通过 Xdebug 的 DBGp 协议提供 PHP 调试功能，让像 Claude 这样的 AI 助手能够直接调试 PHP 应用程序。

🚀 快速开始

要使用 Xdebug MCP Server，你需要完成以下几个步骤：

1. 安装 Xdebug MCP Server。
2. 配置 MCP Server。
3. 配置 PHP/Xdebug。
4. 使用 MCP 工具进行调试。

✨ 主要特性

核心调试功能

• 全面调试控制：支持单步进入、单步跳过、单步跳出、继续执行、停止调试等操作。
• 断点设置：支持行断点、条件断点、异常断点和函数调用断点。
• 变量检查：可以查看所有变量、获取特定变量以及设置变量值。
• 表达式求值：在当前上下文中计算 PHP 表达式。
• 堆栈追踪：查看完整的调用栈。
• 多会话调试：可同时调试多个 PHP 脚本。
• Docker 支持：能与运行在 Docker 容器中的 PHP 配合使用。

高级功能

• 监视表达式：持续监视表达式，在每次断点处自动求值并检测变化。
• 日志点：使用 {$var} 占位符记录消息，而无需停止执行。
• 内存分析：跟踪断点之间的内存使用情况和执行时间。
• 代码覆盖率：跟踪调试期间执行的代码行。
• 请求上下文：自动捕获 $_GET、$_POST、$_SESSION、$_COOKIE 和请求头。
• 单步过滤：在单步执行时跳过供应商/库代码。
• 调试配置文件：保存和恢复断点配置。
• 会话导出：将调试会话导出为 JSON 或 HTML 报告。

📦 安装指南

从 npm 安装（推荐）

npm install -g xdebug-mcp

从源代码安装

git clone https://github.com/kpanuragh/xdebug-mcp.git
cd xdebug-mcp
npm install
npm run build

📚 详细文档

MCP Server 配置

针对 Claude Code

将 xdebug-mcp 服务器添加到你的 MCP 配置（.mcp.json 或 Claude 设置）中：

使用 npm 全局安装：

{
  "mcpServers": {
    "xdebug": {
      "command": "xdebug-mcp",
      "env": {
        "XDEBUG_PORT": "9003",
        "LOG_LEVEL": "info"
      }
    }
  }
}

使用 npx：

{
  "mcpServers": {
    "xdebug": {
      "command": "npx",
      "args": ["-y", "xdebug-mcp"],
      "env": {
        "XDEBUG_PORT": "9003",
        "LOG_LEVEL": "info"
      }
    }
  }
}

带有路径映射（用于 Docker）

在调试 Docker 容器中的 PHP 时，需要进行路径映射，将容器路径转换为主机路径：

{
  "mcpServers": {
    "xdebug": {
      "command": "xdebug-mcp",
      "env": {
        "XDEBUG_PORT": "9003",
        "PATH_MAPPINGS": "{\"/var/www/html\": \"/home/user/projects/myapp\"}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

PHP/Xdebug 配置

php.ini（或 xdebug.ini）

[xdebug]
zend_extension=xdebug

; 启用单步调试
xdebug.mode=debug

; 在每个请求上开始调试
xdebug.start_with_request=yes

; MCP 服务器运行的主机
; 对于 Docker：使用 host.docker.internal
; 对于本地 PHP：使用 127.0.0.1
xdebug.client_host=host.docker.internal

; MCP 服务器监听的端口
xdebug.client_port=9003

; IDE 密钥（可选，用于过滤）
xdebug.idekey=mcp

Docker Compose

version: '3.8'

services:
  php:
    image: php:8.2-apache
    volumes:
      - ./src:/var/www/html
      - ./xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini
    extra_hosts:
      - "host.docker.internal:host-gateway"  # Linux 需要此配置
    environment:
      - XDEBUG_MODE=debug
      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003

可用的 MCP 工具（共 41 个）

会话管理

断点设置

待处理断点：你可以在调试会话开始前设置断点。这些断点会被存储为“待处理断点”，并在 PHP 脚本通过 Xdebug 连接时自动应用。这对于在触发页面加载或脚本执行之前设置断点非常有用。

执行控制

检查功能

监视表达式

日志点

性能分析

代码覆盖率

调试配置文件

其他工具

环境变量

工作原理

1. MCP 服务器启动：监听端口 9003 上的 Xdebug 连接。
2. PHP 脚本运行：启用 Xdebug。
3. Xdebug 连接：通过 DBGp 协议连接到 MCP 服务器。
4. AI 使用 MCP 工具：控制调试过程（设置断点、单步执行、检查变量等）。
5. DBGp 命令发送：发送到 Xdebug，解析响应并返回。

┌─────────────┐     MCP/stdio      ┌─────────────┐     DBGp/TCP      ┌─────────────┐
│   Claude    │ ◄────────────────► │  xdebug-mcp │ ◄───────────────► │   Xdebug    │
│  (AI Agent) │                    │   Server    │                   │  (in PHP)   │
└─────────────┘                    └─────────────┘                   └─────────────┘

故障排除

没有调试会话显示

1. 检查 Xdebug 是否安装：php -v 应显示 Xdebug。
2. 验证 Xdebug 配置：php -i | grep xdebug。
3. 确保 xdebug.client_host 指向 MCP 服务器。
4. 检查防火墙是否允许端口 9003 上的连接。

Docker 连接问题

1. 对于 Linux，添加 extra_hosts: ["host.docker.internal:host-gateway"]。
2. 验证容器是否可以访问主机：curl host.docker.internal:9003。

断点未触发

1. 确保文件路径完全匹配（对于 Docker，使用容器路径）。
2. 检查断点是否已解析：list_breakpoints。
3. 验证脚本执行是否到达该行。

💻 使用示例

设置断点

使用 set_breakpoint，参数为 file="/var/www/html/index.php" 和 line=25

条件断点

使用 set_breakpoint，参数为 file="/var/www/html/api.php"，line=42，condition="$userId > 100"

监视表达式

使用 add_watch，表达式为 "$user->email"
使用 add_watch，表达式为 "count($items)"

日志点

使用 add_logpoint，参数为 file="/var/www/html/api.php"，line=50，message="User {$userId} accessed {$endpoint}"

检查变量

使用 get_variables 查看所有局部变量
使用 get_variable，参数为 name="$user" 检查特定变量
使用 evaluate，表达式为 "count($items)" 计算表达式

捕获请求上下文

使用 capture_request_context 查看 $_GET、$_POST、$_SESSION、cookie 和请求头

📄 许可证

本项目采用 MIT 许可证。

👥 贡献

欢迎贡献代码！请随时提交拉取请求。