xdebug

Xdebug MCP サーバー

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

機能

コアデバッグ

• 完全なデバッグ制御: ステップイン、ステップオーバー、ステップアウト、続行、停止
• ブレークポイント: 行ブレークポイント、条件付きブレークポイント、例外ブレークポイント、関数呼び出しブレークポイント
• 変数の検査: すべての変数の表示、特定の変数の取得、変数値の設定
• 式の評価: 現在のコンテキストで PHP 式を評価
• スタックトレース: 完全なコールスタックの表示
• 複数セッション: 複数の PHP スクリプトを同時にデバッグ
• Docker サポート: Docker コンテナ内で動作する PHP でも利用可能

高度な機能

• ウォッチ式: 各ブレーク時に自動評価され、変更を検出する永続的なウォッチ
• ログポイント: {$var} プレースホルダーを使用して、実行を停止せずにメッセージをログ出力
• メモリプロファイリング: ブレークポイント間のメモリ使用量と実行時間を追跡
• コードカバレッジ: デバッグ中に実行された行を追跡
• リクエストコンテキスト: $_GET、$_POST、$_SESSION、$_COOKIE、ヘッダーを自動的にキャプチャ
• ステップフィルター: ステップ実行中に vendor/ライブラリのコードをスキップ
• デバッグプロファイル: ブレークポイント設定の保存と復元
• セッションのエクスポート: デバッグセッションを 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 の場合

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"
      }
    }
  }
}

DBGp プロキシ登録を使用する場合

すでに DBGp プロキシを使用している場合は、mcp-config.example.json をデフォルトの直接リスナーの例としてそのまま使い、プロキシ登録には mcp-config.proxy.example.json から始めてください。

プロキシモードには以下が必要です:

• xdebug-mcp の TCP リスナーモード (XDEBUG_SOCKET_PATH ではない)
• XDEBUG_PORT 用の 9006、9007、9008 などの一意のコールバックポート
• DBGP_PROXY_HOST、DBGP_PROXY_PORT、DBGP_IDEKEY

完全なセットアップ、マルチエージェントの例、PHP/Xdebug プロキシの設定については、DBGp プロキシ登録ガイドを参照してください。

PHP/Xdebug の設定

php.ini (または xdebug.ini)

[xdebug]
zend_extension=xdebug

; Enable step debugging
xdebug.mode=debug

; Start debugging on every request
xdebug.start_with_request=yes

; Host where MCP server is running
; For Docker: use host.docker.internal
; For local PHP: use 127.0.0.1
xdebug.client_host=host.docker.internal

; Port where MCP server listens
xdebug.client_port=9003

; IDE key (optional, for filtering)
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"  # Required for Linux
    environment:
      - XDEBUG_MODE=debug
      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003

Unix ドメインソケットの使用

ローカルシステムでのパフォーマンス向上とセットアップの簡素化のために、TCP の代わりに Unix ドメインソケットを使用できます。Unix ソケットはネットワークスタックのオーバーヘッドを排除し、同一マシン上でのデバッグに最適です。

利点:

• ⚡ 低レイテンシ (TCP/IP スタックのオーバーヘッドなし)
• 🔒 優れたセキュリティ (ポートバインディングの代わりにファイルパーミッション)
• 📦 簡単なセットアップ (ポート管理が不要)
• 🚀 ローカルデバッグにおける高速な通信

MCP 設定 (Unix ソケット):

{
  "mcpServers": {
    "xdebug": {
      "command": "xdebug-mcp",
      "env": {
        "XDEBUG_SOCKET_PATH": "/tmp/xdebug.sock",
        "LOG_LEVEL": "info"
      }
    }
  }
}

PHP/Xdebug 設定:

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=unix:///tmp/xdebug.sock

ソケットファイルのパーミッション:

ソケットファイルはデフォルトのパーミッションで作成されます。アクセスを制限するには、次のいずれかを行います:

# After MCP server starts
chmod 600 /tmp/xdebug.sock

# Or use a secure directory
mkdir -p ~/.xdebug && chmod 700 ~/.xdebug
# Then set XDEBUG_SOCKET_PATH=$HOME/.xdebug/xdebug.sock

自動クリーンアップ:

XDEBUG_SOCKET_PATH が設定されている場合、サーバーは次のように動作します:

• TCP ポートの代わりに指定された Unix ソケットでリッスンします
• 起動時に古いソケットファイルを自動的にクリーンアップします (「address in use」エラーを防ぎます)
• シャットダウン時にソケットファイルを自動的にクリーンアップします
• TCP モードと同じデバッグツールと機能を使用します

Unix ソケットを使用すべき場合:

• ✅ ローカルの PHP 開発 (最高のパフォーマンス)
• ✅ 同一マシン上でのデバッグ
• ✅ 高頻度のブレークポイントヒット
• ❌ リモートデバッグ (代わりに TCP を使用してください)

Unix ソケットのサポートは @dkd-kaehm による Issue #1 でリクエストされました

利用可能な MCP ツール (全 41 個)

セッション管理

ツール	説明
list_sessions	すべてのアクティブなデバッグセッションを一覧表示します
get_session_state	セッションの詳細な状態を取得します
set_active_session	どのセッションをアクティブにするかを設定します
close_session	デバッグセッションを閉じます

ブレークポイント

ツール	説明
set_breakpoint	行ブレークポイントまたは条件付きブレークポイントを設定します (保留中のブレークポイントをサポート)
set_exception_breakpoint	例外でブレークします (保留中のブレークポイントをサポート)
set_call_breakpoint	関数呼び出しでブレークします (保留中のブレークポイントをサポート)
remove_breakpoint	ブレークポイントを削除します (保留中のブレークポイントでも動作します)
update_breakpoint	ブレークポイントを有効化/無効化または変更します
list_breakpoints	保留中のものを含むすべてのブレークポイントを一覧表示します

保留中のブレークポイント: デバッグセッションの開始前にブレークポイントを設定できます。これらは「保留中のブレークポイント」として保存され、PHP スクリプトが Xdebug で接続したときに自動的に適用されます。これは、ページの読み込みやスクリプトの実行をトリガーする前にブレークポイントを設定する場合に便利です。

実行制御

ツール	説明
continue	次のブレークポイントまで続行します
step_into	関数呼び出しの中にステップインします
step_over	ステップオーバーします (関数内部をスキップします)
step_out	現在の関数からステップアウトします
stop	デバッグを停止します
detach	デタッチしてスクリプトを続行させます

検査

ツール	説明
get_stack_trace	コールスタックを取得します
get_contexts	利用可能な変数コンテキストを取得します
get_variables	スコープ内のすべての変数を取得します
get_variable	特定の変数を取得します
set_variable	変数の値を設定します
evaluate	PHP 式を評価します
get_source	ソースコードを取得します

ウォッチ式

ツール	説明
add_watch	永続的なウォッチ式を追加します
remove_watch	ウォッチ式を削除します
evaluate_watches	すべてのウォッチを評価し、変更を検出します
list_watches	すべてのアクティブなウォッチを一覧表示します

ログポイント

ツール	説明
add_logpoint	メッセージテンプレート付きのログポイントを追加します
remove_logpoint	ログポイントを削除します
get_logpoint_history	ログ出力とヒット統計を表示します

プロファイリング

ツール	説明
start_profiling	メモリ/時間のプロファイリングを開始します
stop_profiling	プロファイリングを停止して結果を取得します
get_profile_stats	現在のプロファイリング統計を取得します
get_memory_timeline	時間の経過に伴うメモリ使用量を表示します

コードカバレッジ

ツール	説明
start_coverage	コードカバレッジの計測を開始します
stop_coverage	計測を停止し、カバレッジレポートを取得します
get_coverage_report	カバレッジ統計を表示します

デバッグプロファイル

ツール	説明
save_debug_profile	現在の設定をプロファイルとして保存します
load_debug_profile	保存されたデバッグプロファイルを読み込みます
list_debug_profiles	保存されたすべてのプロファイルを一覧表示します

その他のツール

ツール	説明
capture_request_context	HTTP リクエストコンテキストをキャプチャします
add_step_filter	ステップ実行中にファイルをスキップするフィルターを追加します
list_step_filters	ステップフィルタールールを一覧表示します
get_function_history	関数呼び出し履歴を表示します
export_session	セッションを JSON/HTML レポートとしてエクスポートします
capture_snapshot	デバッグ状態のスナップショットをキャプチャします

使用例

ブレークポイントの設定

Use set_breakpoint with file="/var/www/html/index.php" and line=25

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

Use set_breakpoint with file="/var/www/html/api.php", line=42, condition="$userId > 100"

ウォッチ式

Use add_watch with expression="$user->email"
Use add_watch with expression="count($items)"

ログポイント

Use add_logpoint with file="/var/www/html/api.php", line=50, message="User {$userId} accessed {$endpoint}"

変数の検査

Use get_variables to see all local variables
Use get_variable with name="$user" to inspect a specific variable
Use evaluate with expression="count($items)" to evaluate an expression

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

Use capture_request_context to see $_GET, $_POST, $_SESSION, cookies, and headers

環境変数

変数	デフォルト	説明
XDEBUG_PORT	9003	Xdebug 接続を待ち受けるポート（TCP モード）
XDEBUG_HOST	0.0.0.0	バインドするホスト（TCP モード）
XDEBUG_SOCKET_PATH	-	Unix ドメインソケットのパス（例: /tmp/xdebug.sock）。設定すると、TCP ではなく Unix ソケットを使用します
COMMAND_TIMEOUT	30000	コマンドのタイムアウト（ミリ秒）
PATH_MAPPINGS	-	コンテナからホストへのパスをマッピングする JSON オブジェクト
MAX_DEPTH	3	変数検査の最大深度
MAX_CHILDREN	128	配列/オブジェクトに対して返す子要素の最大数
MAX_DATA	2048	変数ごとの最大データサイズ
LOG_LEVEL	info	ログレベル: debug、info、warn、error

接続モード: TCP と Unix ソケット

機能	TCP	Unix ソケット
セットアップ	簡単（デフォルト）	シンプル（環境変数を1つ設定するだけ）
パフォーマンス	良好	優秀（低レイテンシ）
セキュリティ	ネットワークからポートにアクセス可能	ファイルベースのパーミッション
リモートデバッグ	✅ 対応	❌ ローカルのみ
Docker	✅ host.docker.internal で動作	❌ ボリュームマウントが必要
古いソケット	手動でのポートクリーンアップ	自動クリーンアップ
デフォルト	XDEBUG_PORT=9003	無効（TCP を使用）

簡単な判断ガイド:

• 🏠 ローカル開発ですか？ → 最高のパフォーマンスを得るには Unix ソケットを使用してください
• 🐳 同じマシン上の Docker ですか？ → ボリュームマウントを併用して Unix ソケットを使用してください
• 🌐 リモートサーバーですか？ → TCP を使用してください
• 🚀 最大速度を求めますか？ → Unix ソケットを使用してください
• 📝 わからないですか？ → まず TCP（デフォルト）で始め、必要に応じて Unix ソケットに切り替えてください

仕組み

1. MCP サーバーが起動し、Xdebug 接続（TCP ポート 9003 または Unix ソケット）を待ち受けます
2. PHP スクリプトが Xdebug を有効にして実行されます
3. Xdebug が DBGp プロトコルを介して MCP サーバーに接続します
4. AI が MCP ツールを使用してデバッグを制御します（ブレークポイントの設定、ステップ実行、検査）
5. DBGp コマンドが Xdebug に送信され、応答が解析されて返されます

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

接続オプション:

• TCP（デフォルト）: xdebug.client_host=127.0.0.1 + XDEBUG_PORT=9003
• Unix ソケット: xdebug.client_host=unix:///tmp/xdebug.sock + XDEBUG_SOCKET_PATH=/tmp/xdebug.sock

トラブルシューティング

デバッグセッションが表示されない

1. Xdebug がインストールされていることを確認します: php -v で Xdebug が表示されるはずです
2. Xdebug の設定を確認します: php -i | grep xdebug
3. xdebug.client_host が MCP サーバーを指していることを確認します
4. TCP の場合: ファイアウォールがポート 9003 への接続を許可していることを確認します
5. Unix ソケットの場合: ソケットパスが存在し、正しいパーミッションが設定されていることを確認します: ls -la /tmp/xdebug.sock
6. MCP サーバーのログを確認します: 詳細な出力を得るには LOG_LEVEL=debug を設定します

Docker での接続の問題

1. Linux の場合は、extra_hosts: ["host.docker.internal:host-gateway"] を追加します
2. コンテナがホストに到達できることを確認します: curl host.docker.internal:9003
3. コンテナ内の Xdebug ログを確認します: docker logs <container-id> | grep xdebug

Unix ソケットの問題

1. 「Address already in use」: ソケットファイルがクリーンアップされていません
   • 手動で削除: rm -f /tmp/xdebug.sock
   • MCP サーバーは次回の起動時に自動的にクリーンアップします
2. 「Permission denied」: ソケットファイルのパーミッションを確認してください
   • ソケットを一覧表示: ls -la /tmp/xdebug.sock
   • PHP と同じユーザーで実行: ps aux | grep php
3. php.ini のソケットパス:
   • 正しい: xdebug.client_host=unix:///tmp/xdebug.sock
   • 誤り: xdebug.client_host=unix:/tmp/xdebug.sock (/ が 1 つ足りません)

ブレークポイントに到達しない

1. ファイルパスが完全に一致していることを確認してください (Docker の場合はコンテナのパスを使用)
2. ブレークポイントが解決されているか確認: list_breakpoints
3. スクリプトの実行がその行に到達しているか検証してください
4. xdebug.start_with_request=yes が設定されているか確認してください
5. 基本的な設定が機能するか、簡単なファイルで試してください

パフォーマンスの問題

1. ステップ実行が遅い場合は、COMMAND_TIMEOUT を増やしてください:
   • デフォルト: 30000ms (30 秒)
   • 低速なシステムでは試してください: COMMAND_TIMEOUT=60000
2. Unix ソケットの場合、ソケットが高速なファイルシステム上にあることを確認してください (ネットワークマウントではないこと)
3. システム負荷を確認: top - 過剰なコンテキストスイッチングはデバッグを遅くします

サーバーが起動しない

1. ポートが使用中 (TCP):
   • プロセスを検索: lsof -i :9003
   • 強制終了: kill -9 <pid>
2. 設定が不正:
   • 環境変数を検証: echo $XDEBUG_SOCKET_PATH
   • パス名のタイプミスを確認してください
3. Permission denied:
   • Unix ソケットの場合、親ディレクトリへの書き込み権限を確認してください
   • 例: mkdir -p ~/.xdebug && chmod 700 ~/.xdebug

コントリビューション

コントリビューションを歓迎します! お気軽に Pull Request を送ってください。

ライセンス

MIT