Xdebug MCP

🚀 Xdebug MCP Server

XdebugのDBGpプロトコルを通じてPHPのデバッグ機能を提供するMCP（Model Context Protocol）サーバーです。これにより、ClaudeなどのAIアシスタントが直接PHPアプリケーションをデバッグできるようになります。

🚀 クイックスタート

Xdebug MCP Serverを使用することで、AIアシスタントがPHPアプリケーションを直接デバッグできます。以下の手順に従ってセットアップしてください。

✨ 主な機能

コアデバッグ機能

• 完全なデバッグ制御：ステップイン、ステップオーバー、ステップアウト、続行、停止
• ブレークポイント：行ブレークポイント、条件付きブレークポイント、例外ブレークポイント、関数呼び出しブレークポイント
• 変数検査：すべての変数を表示、特定の変数を取得、変数の値を設定
• 式評価：現在のコンテキストで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サーバーの設定

Claude Code用の設定

MCP設定（.mcp.jsonまたはClaude設定）にxdebug-mcpサーバーを追加します。

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で接続すると自動的に適用されます。ページロードまたはスクリプト実行をトリガーする前にブレークポイントを設定するのに便利です。

実行制御

検査

ウォッチ式

ログポイント

プロファイリング

コードカバレッジ

デバッグプロファイル

追加ツール

💻 使用例

ブレークポイントの設定

file="/var/www/html/index.php" と line=25 を指定して set_breakpoint を使用

条件付きブレークポイント

file="/var/www/html/api.php"、line=42、condition="$userId > 100" を指定して set_breakpoint を使用

ウォッチ式

expression="$user->email" を指定して add_watch を使用
expression="count($items)" を指定して add_watch を使用

ログポイント

file="/var/www/html/api.php"、line=50、message="User {$userId} accessed {$endpoint}" を指定して add_logpoint を使用

変数の検査

すべてのローカル変数を表示するには get_variables を使用
特定の変数を検査するには name="$user" を指定して get_variable を使用
式を評価するには expression="count($items)" を指定して evaluate を使用

リクエストコンテキストのキャプチャ

$_GET、$_POST、$_SESSION、クッキー、およびヘッダーを表示するには capture_request_context を使用

環境変数

動作原理

1. MCPサーバーが起動し、ポート9003でXdebug接続を待機します。
2. PHPスクリプトが実行され、Xdebugが有効になっています。
3. XdebugがMCPサーバーに接続します（DBGpプロトコルを使用）。
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. スクリプトの実行がその行に到達することを確認します。

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。

📄 ライセンス

MIT