| name | xdebug |
| description | PHP debugging and analysis tools using Xdebug. Use when asked to trace, debug, profile, or analyze coverage of PHP code. Trigger phrases include "trace this function", "profile this code", "check coverage", "debug PHP", "set breakpoint", "find the bottleneck", "why is this slow", "トレース", "プロファイル", "カバレッジ". |
Xdebug MCP Tools
Non-invasive PHP debugging and analysis tools. No var_dump() or code modification needed.
Tool Paths
Tools are installed globally via composer. Use absolute paths:
| Tool | Path |
|---|
| xtrace | ~/.composer/vendor/bin/xtrace |
| xstep | ~/.composer/vendor/bin/xstep |
| xprofile | ~/.composer/vendor/bin/xprofile |
| xcoverage | ~/.composer/vendor/bin/xcoverage |
| xback | ~/.composer/vendor/bin/xback |
Tool Selection Guide
| User Request | Tool |
|---|
| Trace, execution flow, show function calls | xtrace |
| Step debugging, breakpoints, inspect variables, track variable changes | xstep |
| Profile, performance, bottlenecks, slow code | xprofile |
| Coverage, test coverage, which lines tested | xcoverage |
| Backtrace, call stack, how did we get here | xback |
"Trace" Ambiguity
The word "trace" can mean different things:
- Forward Trace →
xtrace (records execution from start to finish)
- Backtrace / Stack Trace →
xback (shows call stack at a point)
- Step through / Debug →
xstep (interactive with breakpoints)
xtrace - Forward Trace (Full)
Trace execution forward from start to finish. Captures complete execution flow, function calls, parameters, and timing data.
Output: JSON with $schema URL for semantic details and AI analysis strategies.
Key fields: {lines, functions, max_depth, db_queries}
~/.composer/vendor/bin/xtrace [--json] [--context=TEXT] [--include-vendor=PATTERNS] -- command
Examples
~/.composer/vendor/bin/xtrace --context="Debug login" -- php login.php
~/.composer/vendor/bin/xtrace --context="Test analysis" -- vendor/bin/phpunit tests/UserTest.php
~/.composer/vendor/bin/xtrace --include-vendor="bear/*" -- php app.php
When to Use
- "Trace this code"
- "Show execution flow"
- "What functions are called?"
- General PHP debugging (default choice)
xstep - Forward Trace (Step-by-Step)
Stop at breakpoint, step forward N times, record variable changes at each step. See how variable values affect branching ("this variable was X, so it went into this branch").
Output: Slim, deduplicated JSON with a $schema URL — fields you might expect inline can live elsewhere, so read the linked schema to interpret the structure and reconstruct variable state. The schema is the source of truth; do not infer the format from examples.
~/.composer/vendor/bin/xstep --break=file.php:line --steps=N [--context=TEXT] [--include-vendor=PATTERNS] -- command
Options
--break=file.php:line - Single breakpoint location--break=file.php:line:condition - Conditional (e.g., $user==null)--steps=N - Step forward N times from breakpoint--watch=EXPR - Only record steps when expression value changes (can specify multiple times)
Examples
~/.composer/vendor/bin/xstep --break="user.php:42" --steps=20 --context="Track auth" -- php user.php
~/.composer/vendor/bin/xstep --break="user.php:15:\$id==null" --steps=10 -- php user.php
~/.composer/vendor/bin/xstep --break="loop.php:10" --watch="\$i" --steps=100 -- php loop.php
~/.composer/vendor/bin/xstep --break="app.php:25" --watch="\$user->getStatus()" --watch="count(\$items)" --steps=50 -- php app.php
Workflow Tips
- Need more steps? Set new breakpoint at where you stopped, run again
- Too much variable info? Use xtrace first to see flow, then xstep for details
When to Use
- "Track how variable changes step by step"
- "Why did it branch this way?"
- "What's the variable value at line X?"
xprofile - Performance Profiler
Identify performance bottlenecks with precision data.
Output: JSON with a schema URL. time_ms/memory_mb are measured from the cachegrind summary; bottlenecks is a structured array. Read the linked schema for the field shapes — don't infer the format here.
Key fields: {time_ms, memory_mb, bottlenecks}
~/.composer/vendor/bin/xprofile [--json] [--context=TEXT] [--include-vendor=PATTERNS] -- command
Examples
~/.composer/vendor/bin/xprofile --context="Optimize processing" -- php process.php
~/.composer/vendor/bin/xprofile --json -- php script.php
~/.composer/vendor/bin/xprofile --include-vendor="doctrine/*" -- php app.php
When to Use
- "Profile this code"
- "Find bottlenecks"
- "Why is this slow?"
- "Memory usage analysis"
xcoverage - Code Coverage
Collect code coverage data for PHPUnit or any PHP script. Shows only uncovered lines (compact output).
Output: JSON with $schema URL for semantic details.
Key fields: {summary: {coverage_percent, covered_lines, uncovered_lines}, uncovered: {file: [lines]}}
~/.composer/vendor/bin/xcoverage [--include-vendor=PATTERNS] -- command
~/.composer/vendor/bin/xcoverage -- vendor/bin/phpunit
~/.composer/vendor/bin/xcoverage -- php script.php
Examples
~/.composer/vendor/bin/xcoverage -- vendor/bin/phpunit
~/.composer/vendor/bin/xcoverage --include-vendor="bear/*,ray/di" -- vendor/bin/phpunit
~/.composer/vendor/bin/xcoverage -- vendor/bin/phpunit --filter testMethod
When to Use
- "Check test coverage"
- "Which lines are tested?"
- "Find untested code"
xback - Backtrace Capture
Get call stack (backtrace) at a specific line. Shows "who called this?" - the chain of function calls that led to this point.
Output: JSON with $schema URL for semantic details.
Key fields: {backtrace: [{file, line, function, args}]}
~/.composer/vendor/bin/xback [--break=SPEC] [--depth=N] [--context=TEXT] -- command
Examples
~/.composer/vendor/bin/xback -- php script.php
~/.composer/vendor/bin/xback --break=app.php:50 -- php app.php
~/.composer/vendor/bin/xback --depth=20 -- php main.php
When to Use
- "Get backtrace at line X"
- "Show call stack"
- "How did execution reach this line?"
Common Options
| Option | Description |
|---|
--json | AI-optimized JSON output |
--context=TEXT | Add description for AI analysis |
--include-vendor=PATTERNS | Include vendor packages |
Vendor Filtering
By default, vendor code is excluded to focus on your code. Use --include-vendor when needed:
--include-vendor="bear/*"
--include-vendor="bear/*,ray/di"
--include-vendor="*/*"
JSON Schemas
