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 許可證。

👥 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。