-
Notifications
You must be signed in to change notification settings - Fork 7
Tools Commands
Anuragh K P edited this page Mar 23, 2026
·
1 revision
The Xdebug MCP Server exposes the following tools for debugging PHP applications.
Sets a breakpoint at a specific location in code.
Parameters:
-
file(required): Absolute file path (e.g.,/path/to/file.php) -
line(required): Line number (integer) -
condition(optional): Expression to evaluate (e.g.,$x > 10) -
hit_value(optional): Number of times to skip (e.g.,5= skip first 5 hits)
Example:
Tool: set_breakpoint
Parameters:
file: /var/www/app.php
line: 25
condition: $status === 'error'
Response:
Breakpoint set at /var/www/app.php:25
ID: bp-1234
Use Cases:
- Pause execution at specific line
- Conditional breakpoints (break when condition true)
- Skip breakpoint hits (break on Nth occurrence)
Lists all active breakpoints.
Parameters: None
Example:
Tool: get_breakpoints
Response:
Active Breakpoints:
1. /var/www/app.php:25 [ID: bp-1234]
Condition: $status === 'error'
Hits: 0
2. /var/www/app.php:42 [ID: bp-5678]
No condition
Hits: 3
Removes all breakpoints.
Parameters: None
Example:
Tool: clear_breakpoints
Response:
All breakpoints cleared (2 removed)
Continues script execution until next breakpoint or end.
Parameters: None
Example:
Tool: continue_execution
Response:
Execution paused at /var/www/app.php:42
Function: process_data()
Variables: $x = 10, $y = 20
Executes one line, entering function calls.
Parameters: None
Example:
Tool: step_into
Response:
Paused at /var/www/helpers.php:15
Function: format_string()
Use When:
- Inspecting function internals
- Tracing function execution
- Debugging function behavior
Executes one line, but skips over function calls.
Parameters: None
Example:
Tool: step_over
Response:
Paused at /var/www/app.php:26
Function: main()
Result: $formatted = "Hello World"
Use When:
- Don't need to inspect function details
- Want to skip library/framework code
- Moving through code quickly
Executes remaining lines in current function and returns to caller.
Parameters: None
Example:
Tool: step_out
Response:
Exited /var/www/helpers.php:format_string()
Back in /var/www/app.php:25
Use When:
- Function is working correctly, want to exit
- Finished inspecting function internals
- Move to next function call
Stops debugging and terminates session.
Parameters: None
Example:
Tool: stop_execution
Response:
Debug session terminated
PHP process released
Gets all variables in current scope.
Parameters:
-
context(optional): Variable scope-
local(default): Local variables -
global: Global variables -
superglobal: Superglobals ($_GET, $_POST, etc.)
-
Example:
Tool: get_variables
Parameters:
context: local
Response:
Local Variables:
$x = 10 (integer)
$y = 20 (integer)
$name = "John Doe" (string)
$data = array(3) {
"id" => 123,
"status" => "active",
"roles" => array(2) { "user", "admin" }
}
$user = object(User) {
private $id => 123,
private $email => "john@example.com",
public $name => "John"
}
Gets a specific variable's value.
Parameters:
-
name(required): Variable name (e.g.,$user,$_GET['id']) -
depth(optional): Recursion depth for complex types (default: 1)
Example:
Tool: get_variable
Parameters:
name: $user
depth: 2
Response:
$user = object(User) #1234 {
$id => 123 (integer),
$email => "john@example.com" (string),
$roles => array(2) {
[0] => "user" (string),
[1] => "admin" (string)
},
$profile => object(Profile) #5678 {
$bio => "Developer" (string),
$avatar => "https://..." (string)
}
}
Monitor a variable and break when it changes.
Parameters:
-
name(required): Variable name to watch -
old_value(optional): Previous value (for comparison)
Example:
Tool: watch_variable
Parameters:
name: $total_price
Response:
Now watching: $total_price
Current value: 100.50
Will pause on next change
Use When:
- Variable modified unexpectedly
- Tracking value changes through functions
- Debugging state mutations
Gets current call stack.
Parameters:
-
detailed(optional): Include variable context (true/false)
Example:
Tool: get_stack_trace
Parameters:
detailed: true
Response:
Call Stack:
┌─────────────────────────────────────────┐
│ Frame 0 (current) │
│ Function: calculate_discount() │
│ File: /var/www/helpers.php:45 │
│ Variables: $price=100, $percent=10 │
└─────────────────────────────────────────┘
↑
│
┌─────────────────────────────────────────┐
│ Frame 1 │
│ Function: process_order() │
│ File: /var/www/handlers/order.php:23 │
│ Variables: $order_id=5678, $items=[...] │
└─────────────────────────────────────────┘
↑
│
┌─────────────────────────────────────────┐
│ Frame 2 (main) │
│ File: /var/www/index.php:1 │
│ Variables: (none) │
└─────────────────────────────────────────┘
Gets source code around current location.
Parameters:
-
lines(optional): Lines to fetch (e.g.,5= 5 lines before/after)
Example:
Tool: get_source_code
Parameters:
lines: 5
Response:
File: /var/www/helpers.php
Current line: 45
40 | function calculate_discount($price, $percent) {
41 | $discount = $price * ($percent / 100);
42 | $final_price = $price - $discount;
43 |
44 | if ($final_price < 0) {
45 | > return 0; // Current location
46 | }
47 |
48 | return $final_price;
49 | }
Gets code coverage metrics.
Parameters:
-
include_files(optional): File patterns to include -
exclude_files(optional): File patterns to exclude
Example:
Tool: get_code_coverage
Parameters:
include_files: ["/var/www/app/*", "/var/www/handlers/*"]
exclude_files: ["/vendor/*", "/tests/*"]
Response:
Code Coverage Report:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
File: /var/www/helpers.php
Coverage: 85% (34/40 lines)
Covered: 34 lines
Uncovered: 6 lines
File: /var/www/handlers/order.php
Coverage: 92% (23/25 lines)
Covered: 23 lines
Uncovered: 2 lines
Overall: 88% (57/65 lines)
Gets performance profiling data.
Parameters:
-
sort_by(optional):time(default),calls,memory
Example:
Tool: get_profiling_data
Parameters:
sort_by: time
Response:
Top 10 Slowest Functions:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. query_database() 2543ms (5 calls)
2. process_data() 1245ms (10 calls)
3. serialize_response() 854ms (1 call)
4. validate_input() 234ms (50 calls)
5. format_output() 123ms (100 calls)
Memory Usage:
Peak: 45.5 MB
Current: 23.8 MB
Gets current debug session information.
Parameters: None
Example:
Tool: get_session_info
Response:
Session Information:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session ID: sess-1234
Status: break
Current File: /var/www/app.php
Current Line: 25
Current Function: process_user()
Connection Mode: TCP (localhost:9003)
Runtime: 2.5 seconds
Memory: 15.2 MB
Breakpoints Set: 3
Breakpoints Hit: 1
Variables in Scope: 12
Execute multiple commands in sequence:
Example Workflow:
1. set_breakpoint(file=/var/www/app.php, line=25)
2. continue_execution()
3. get_variables(context=local)
4. get_stack_trace(detailed=true)
5. step_into()
6. get_variable(name=$result)
7. step_out()
8. stop_execution()
Tools return errors in standard format:
Error: Invalid file path
Code: INVALID_PATH
Details: File not found: /invalid/path.php
Common errors:
-
SESSION_NOT_ACTIVE- No debug session running -
BREAKPOINT_LIMIT- Maximum breakpoints reached -
INVALID_LINE_NUMBER- Line doesn't exist -
VARIABLE_NOT_FOUND- Variable doesn't exist -
CONNECTION_LOST- Lost connection to Xdebug
- Use step_over instead of step_into when not inspecting function details
- Limit variable depth when inspecting complex objects
- Use conditional breakpoints instead of manual stepping
- Clear breakpoints when done debugging
- Use Unix sockets for local debugging (faster)
- Start with breakpoints - Set key breakpoints before running
- Inspect variables incrementally - Don't dump entire objects
- Use stack trace to understand execution flow
- Watch important variables for state changes
- Profile frequently used functions
- Clean up sessions when done