### Install and Enable AI Debugging Guide

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/README.md

Installs the Xdebug MCP server via Composer and configures it to use the AI debugging guide for the current project. Alternatively, it shows how to set up the guide globally.

```bash
# Install via Composer (if not already done)
composer require koriym/xdebug-mcp

# Enable AI debugging guide for this project
echo "@vendor/koriym/xdebug-mcp/docs/debug_guideline_for_ai.md" >> CLAUDE.md

# Alternative: Global setup (affects ALL projects - use with caution)
# mkdir -p ~/.claude
# cp vendor/koriym/xdebug-mcp/docs/debug_guideline_for_ai.md ~/.claude/
# echo "@debug_guideline_for_ai.md" >> ~/.claude/CLAUDE.md
```

--------------------------------

### Setup and Basic Execution Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

Provides commands to clone the xdebug-mcp repository, install dependencies, create a simple test PHP file, and then analyze its execution using xtrace with AI context.

```bash
# 1. Clone from GitHub
git clone https://github.com/koriym/xdebug-mcp.git
cd xdebug-mcp && composer install

# 2. Create a simple test
echo '<?php
$result = "success";
if (rand(0,1)) { $result = null; }
echo $result;
?>' > test.php

# 3. Let AI analyze execution
./vendor/bin/xtrace --context="Find why \$result becomes null" -- php test.php
```

--------------------------------

### Install Desktop

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/AGENTS.md

Installs desktop related components.

```bash
composer install-desktop
```

--------------------------------

### Example Workflow: Performance Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Example of AI running xprofile with context for performance analysis of a test suite.

```bash
./bin/xprofile --context="Performance analysis of debug test suite" tests/fixtures/debug_test.php
```

--------------------------------

### Install Dependencies and Verify Environment

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/demo/README.md

Before running the demos, navigate to the project root, install Composer dependencies, and verify your Xdebug environment.

```bash
cd ..

composer install

./bin/check-env
```

--------------------------------

### Example Workflow: Comparative Execution Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Example of AI running xcompare with context to compare execution with different inputs.

```bash
./bin/xcompare --break=src/User.php:42 --run-a="php login.php valid" --run-b="php login.php invalid" --context="Compare authentication behavior"
```

--------------------------------

### Verify Xdebug and MCP Setup

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/AGENTS.md

Verifies Xdebug installation and sets up MCP/Claude integration.

```bash
bin/check-env
```

--------------------------------

### Example Workflow: Code Coverage Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Example of AI running xcoverage with context for code coverage analysis of tests.

```bash
./bin/xcoverage --context="Code coverage analysis for UserController tests" tests/fixtures/MyTest.php
```

--------------------------------

### Example Workflow: Debugging Buggy Script

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Example of AI running xstep with context for debugging a specific script.

```bash
./bin/xstep --context="Debugging buggy calculation script with division by zero" --exit-on-break tests/fixtures/buggy_script.php
```

--------------------------------

### Open Human Developer Guide

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/README.md

Opens the human developer guide in the default system browser or the configured code editor.

```bash
# View human developer guide
open vendor/koriym/xdebug-mcp/docs/debug_guideline_for_humans.md

# Or use your preferred editor
code vendor/koriym/xdebug-mcp/docs/debug_guideline_for_humans.md
```

--------------------------------

### Install MCP

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/AGENTS.md

Installs MCP specific components.

```bash
composer install-mcp
```

--------------------------------

### Install Dependencies

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/AGENTS.md

Installs project dependencies using Composer.

```bash
composer install
```

--------------------------------

### Example Workflow: Execution Flow Tracing

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Example of AI running xtrace with context for execution flow analysis of a function.

```bash
./bin/xtrace --context="Execution flow analysis of authentication process" src/MyClass.php
```

--------------------------------

### xprofile - Examples

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Examples of using xprofile with different options. Use to profile specific scripts, analyze JSON output, or focus on vendor code performance.

```bash
~/.composer/vendor/bin/xprofile --context="Optimize processing" -- php process.php
```

```bash
~/.composer/vendor/bin/xprofile --json -- php script.php
```

```bash
~/.composer/vendor/bin/xprofile --include-vendor="doctrine/*" -- php app.php
```

--------------------------------

### Batch Processing Script Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

A bash script template for batch processing trace files. This is a starting point for automating analysis on multiple trace files.

```bash
#!/bin/bash

```

--------------------------------

### Docker Integration Examples

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms-full.txt

Illustrates how to use Xdebug MCP tools within a Docker environment. These examples show running debugging and tracing commands for applications managed by Docker Compose.

```bash
xstep --break="/app/script.php:42" --exit-on-break -- \
  docker compose run --rm php php /app/script.php

xtrace -- docker compose run --rm php php /app/script.php
```

--------------------------------

### xstep - Track Authentication Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Example of using xstep to track authentication flow by stepping through code. Use to understand variable states during critical processes like user authentication.

```bash
~/.composer/vendor/bin/xstep --break="user.php:42" --steps=20 --context="Track auth" -- php user.php
```

--------------------------------

### Serve Presentation Locally

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/README.md

Starts a local HTTP server in the 'slide' directory to view the presentation. Opens the presentation in the default web browser.

```bash
cd slide && python3 -m http.server 8000
open http://localhost:8000
```

--------------------------------

### Start Profiling with MCP Tool

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/fake/COMPREHENSIVE_MCP_TEST_EN.md

Use this command to start profiling when MCP tools are accessible. Ensure you verify the actual results after execution.

```bash
mcp__xdebug__xdebug_start_profiling
```

--------------------------------

### Incorrect Step Debugging Order

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

This example shows the wrong sequence for step debugging, where the script runs and exits before the XdebugClient starts listening, preventing a connection.

```bash
./bin/xstep script.php    # Script runs and exits
php test_new_xdebug_debug.php &  # Too late - no connection
```

--------------------------------

### Check Environment

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/AGENTS.md

Verifies the project environment setup.

```bash
composer check-env
```

--------------------------------

### Login Performance Executive Summary Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

Example JSON output for an executive summary of login performance analysis. Highlights total execution time and top optimization targets.

```json
{
  "📋 executive_summary": {
    "⏱️ total_execution_time": 2.5,
    "🎯 top_optimization_targets": [
      {
        "🏷️ function_name": "User::validateCredentials",
        "⏱️ duration_seconds": 1.8,
        "💡 optimization_priority": "critical"
      }
    ]
  }
}
```

--------------------------------

### MCP Configuration Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Example of an MCP configuration file (`.mcp.json`) to register xdebug-mcp servers. This allows MCP-capable clients to use xdebug-mcp tools.

```json
{
  "mcpServers": {
    "xdebug": {
      "command": "php",
      "args": ["/ABSOLUTE/PATH/TO/xdebug-mcp"]
    }
  }
}
```

--------------------------------

### Install PHP 8.x on Ubuntu

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/TROUBLESHOOTING.md

Install the PHP 8.2 CLI and Xdebug extension on Ubuntu systems.

```bash
sudo apt-get install php8.2-cli php8.2-xdebug
```

--------------------------------

### Run MCP Server (Alternative)

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Starts the MCP server using PHP's execution context.

```bash
php bin/xdebug-mcp
```

--------------------------------

### xstep - Multiple Watch Variables Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Example of using xstep with multiple watch expressions. Use to track changes in several variables or function return values simultaneously.

```bash
~/.composer/vendor/bin/xstep --break="app.php:25" --watch="\$user->getStatus()" --watch="count(\$items)" --steps=50 -- php app.php
```

--------------------------------

### Check Xdebug Installation

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/TROUBLESHOOTING.md

Verify if the Xdebug extension is installed and loaded correctly in your PHP environment.

```bash
php -m | grep xdebug
php -r "var_dump(extension_loaded('xdebug'));"
```

--------------------------------

### Start MCP Server with xdebug-mcp

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/bin/README.md

Start the main MCP protocol server for AI assistant communication. Enable debug logging with MCP_DEBUG=1.

```bash
./xdebug-mcp
```

```bash
MCP_DEBUG=1 ./xdebug-mcp
```

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./xdebug-mcp
```

--------------------------------

### Install Xdebug-MCP

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

Use Composer to install the Xdebug-MCP package.

```bash
composer require koriym/xdebug-mcp
```

--------------------------------

### Run MCP Server

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Starts the MCP server, the main entry point for the protocol handler.

```bash
./bin/xdebug-mcp
```

--------------------------------

### Install Xdebug on Different OS

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/TROUBLESHOOTING.md

Provides commands for installing the Xdebug extension on macOS, Ubuntu/Debian, CentOS/RHEL, or via manual PECL installation.

```bash
# macOS with Homebrew
brew install php-xdebug

# Ubuntu/Debian
sudo apt-get install php-xdebug

# CentOS/RHEL
sudo yum install php-xdebug

# Manual installation
sudo pecl install xdebug
```

--------------------------------

### Start Interactive Debugging Session

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/fake/COMPREHENSIVE_MCP_TEST_EN.md

Initiate an interactive debugging session by first starting the XdebugClient and then executing the script with the debug tool.

```bash
php test_new_xdebug_debug.php &
```

--------------------------------

### xstep - Watch Variable Changes Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Example of using xstep to watch specific variable changes during execution. Use to monitor how key variables evolve over multiple steps, especially in loops.

```bash
~/.composer/vendor/bin/xstep --break="loop.php:10" --watch="\$i" --steps=100 -- php loop.php
```

--------------------------------

### Conditional Tracing for Specific Scenarios

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

Use this command to start tracing only when a specific condition is met, avoiding code pollution and production risks. This example triggers tracing when User ID is 0.

```bash
./vendor/bin/xstep --break='User.php:85:$userId==0' --steps=100 --exit-on-break -- php app.php
```

--------------------------------

### xtrace - Examples

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Examples of using xtrace with different contexts and include-vendor patterns. Use to trace specific code sections or analyze vendor code.

```bash
~/.composer/vendor/bin/xtrace --context="Debug login" -- php login.php
```

```bash
~/.composer/vendor/bin/xtrace --context="Test analysis" -- vendor/bin/phpunit tests/UserTest.php
```

```bash
~/.composer/vendor/bin/xtrace --include-vendor="bear/*" -- php app.php
```

--------------------------------

### Good Context Examples

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/debug_guideline_for_ai.md

Examples of using the `--context` flag to provide self-explanatory debugging data. This makes debug sessions understandable by any AI and facilitates sharing.

```bash
--context="Testing user authentication with valid credentials"
--context="Debugging login failure after password reset"
--context="Investigating memory leak in data processing loop"
--context="Profiling database query performance in user dashboard"
--context="Validating email sending functionality in ContactForm"
```

--------------------------------

### Performance Comparison Results Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

Example JSON output detailing the performance difference between two trace analyses. Shows percentage change and time difference in execution.

```json
{
  "📈 execution_time_diff": {
    "📊 percentage_change": -65.2,
    "⏱️ time_difference": -1.8
  },
  "💡 interpretation": [
    "🚀 Significant performance improvement: 65.2% faster execution",
    "✅ Overall function performance improved (15 improvements vs 2 regressions)"
  ]
}
```

--------------------------------

### Correct Step Debugging Order

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

This demonstrates the correct sequence for interactive step debugging: start the XdebugClient, verify it's listening, and then execute the target script.

```bash
php test_new_xdebug_debug.php &  # XdebugClient listening
lsof -i :9004                    # Verify LISTEN state  
./bin/xstep script.php    # Script connects to waiting client
```

--------------------------------

### Forward Trace™ Debugging Example with Steps

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/debug_guideline_for_ai.md

Use the x-debug command with breakpoints and step limits to capture the full execution flow, similar to recording a video, for comprehensive AI analysis.

```bash
./bin/x-debug --break="script.php:10:$user==null" --steps=300 --exit-on-break

# AI sees the complete 🎥 movie:
# Step 1: $id = getUserId() → returns 42
# Step 2: $user = findUser($id) → DB query success
# Step 3: validateUser($user) → validation passes
# Step 4: $permissions = getPermissions($user) → returns null
# Step 5: checkAccess($permissions) → CRASH! null access
```

--------------------------------

### xstep - Conditional Breakpoint Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Example of using xstep with a conditional breakpoint. Use when you need to stop execution only when a specific condition is met.

```bash
~/.composer/vendor/bin/xstep --break="user.php:15:\$id==null" --steps=10 -- php user.php
```

--------------------------------

### Verify PHPUnit Installation

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/TROUBLESHOOTING.md

Confirm that PHPUnit is installed correctly and accessible by checking its version. This is a prerequisite for running tests and integrating with Xdebug profiling.

```bash
vendor/bin/phpunit --version
```

--------------------------------

### Starting Xdebug Trace

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/MOTIVATION.md

This snippet shows how to initiate an Xdebug trace, which captures detailed execution information. This is a prerequisite for feeding runtime data to AI tools.

```php
xdebug_start_trace();
```

--------------------------------

### Context Examples for AI Debugging Scenarios

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Provide descriptive context strings for various debugging scenarios to enhance AI understanding. These examples cover unit testing, bug investigation, performance analysis, and feature development.

```bash
--context="Unit test for UserService::authenticate() method with valid login"
```

```bash
--context="Testing PaymentProcessor edge case with expired credit card"
```

```bash
--context="Validating email sending functionality in ContactForm"
```

```bash
--context="Debugging login failure - users can't authenticate after password reset"
```

```bash
--context="Investigating memory leak in data processing loop"
```

```bash
--context="Troubleshooting payment gateway timeout during checkout"
```

```bash
--context="Profiling database query performance in user dashboard"
```

```bash
--context="Analyzing memory usage spike during bulk data import"
```

```bash
--context="Investigating slow response times in API endpoint"
```

```bash
--context="Testing new shopping cart calculation logic"
```

```bash
--context="Validating multi-step form submission workflow"
```

```bash
--context="Debugging new authentication middleware integration"
```

--------------------------------

### Schema-Backed JSON Output Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Example of JSON output from an xdebug-mcp tool, including a schema URL for verification. This format provides machine-verifiable and self-describing data.

```json
{
  "$schema": "https://koriym.github.io/xdebug-mcp/schemas/xstep.json",
  "breaks": [
    {
      "location": {"file": "demo/buggy.php", "line": 22},
      "variables": {"$user": "NULL", "$id": "42"}
    }
  ],
  "trace": { "...": "..." }
}
```

--------------------------------

### CLI Tool Examples

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms-full.txt

Demonstrates common CLI commands for Xdebug MCP tools. These include breakpoint debugging, execution tracing, performance profiling, and code coverage analysis.

```bash
# Debug with breakpoint
xstep --break="script.php:42" -- php script.php

# Trace execution flow
xtrace --context="Debug login" -- php login.php

# Profile performance
xprofile --json -- php api.php

# Code coverage
xcoverage -- vendor/bin/phpunit

# Stack trace at breakpoint
xback --break="app.php:50" -- php app.php
```

--------------------------------

### Install Claude Code Plugin

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms.txt

Install the Xdebug MCP plugin for Claude Code. This enables direct integration with the Claude Code AI assistant.

```text
/plugin marketplace add koriym/xdebug-mcp
/plugin install xdebug@xdebug-mcp
```

--------------------------------

### Verify Xdebug Installation

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Verify that the Xdebug environment is set up correctly using the provided check-env script.

```bash
"$(composer global config bin-dir --absolute --quiet)/check-env"
```

--------------------------------

### Human-AI Debugging Workflow Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/debug_guideline_for_humans.md

Demonstrates a collaborative debugging process where a human sets up Forward Trace capture, and AI analyzes the runtime data to suggest a fix.

```bash
# 1. Human sets up capture
./bin/xstep --break='Cart.php:89:$total<0' --exit-on-break --context="Negative cart total investigation" -- php checkout.php

# 2. Forward Trace captures the problem moment
# Output: Complete execution trace + JSON data

# 3. Human asks AI to analyze
claude --continue "Analyze why the cart total became negative"

# 4. AI provides specific analysis:
# "At line 67, removeItem() doesn't call recalculateDiscount(). 
#  $50 discount applied to $30 cart = -$20 total.
#  Fix: Add $this->recalculateDiscount() after removeItem()"

# 5. Human implements the fix (no more guesswork!)
```

--------------------------------

### Example Xdebug Argument Injection

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/docker/README.md

Illustrates how the XdebugRunner class transforms a Docker command to inject Xdebug arguments.

```text
Input:  docker compose run --rm php php /app/test.php
Output: docker compose run --rm php php -dxdebug.mode=trace -dxdebug.start_with_request=yes ... /app/test.php
```

--------------------------------

### Xdebug Raw Output Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

This shows the raw output format from Xdebug trace files, detailing function calls, timing, memory, and parameters.

```text
2    1    0    0.000489    401872    testFunction    1    test.php    35    2    $a=null $b=10
2    1    1    0.000521    403216
2    1    R              array(3) { [0]=>int(1) [1]=>int(2) [2]=>int(3) }
```

--------------------------------

### Run Trace with docker compose exec

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/docker/README.md

Starts a Docker container in the background and then runs a trace test using docker compose exec.

```bash
docker compose -f tests/docker/docker-compose.yml up -d
./bin/xtrace -- \
  docker compose -f tests/docker/docker-compose.yml exec -T php php /app/test_script.php
```

--------------------------------

### Example .xt Trace File Format

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/debug_guideline_for_ai.md

This table illustrates the format of an .xt trace file, showing function calls, execution time, memory usage, and parameters/return values.

```text
Level   FuncID  Time    Memory  Function    UserDef  File:Line  Params/Return
0       1       0.001   384000  {main}      1        test.php:1  
1       2       0.002   384100  calculate   1        test.php:15 $n = 10
1       2       0.003   384200                                   R 100
```

--------------------------------

### Trace File Structure Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Understand the structure of an Xdebug trace file (.xt format) to analyze function hierarchy, memory usage, parameters, time, and execution location.

```text
Level | FuncID | Time    | Memory  | Function    | File:Line  | Parameters
0     | 1      | 0.001   | 384000  | {main}      | tests/fixtures/debug.php:1 | 
1     | 2      | 0.002   | 384100  | calculate() | tests/fixtures/debug.php:15| $n = 10
1     | 3      | 0.003   | 384200  | validate()  | tests/fixtures/debug.php:20| $data = array(3)
```

--------------------------------

### Install Xdebug MCP via Composer

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms.txt

Install the Xdebug MCP tool globally using Composer. This command makes the CLI tools available in your system's PATH.

```bash
composer global require koriym/xdebug-mcp

~/.composer/vendor/bin/check-env
```

--------------------------------

### Conditional Breakpoint Examples

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms-full.txt

Shows how to set conditional breakpoints and record variable evolution during execution. These commands allow for more targeted debugging and analysis.

```bash
# Stop when $user is null
xstep --break='User.php:42:$user==null' --exit-on-break -- php app.php

# Record 100 steps of variable evolution
xstep --break='loop.php:15' --steps=100 -- php script.php
```

--------------------------------

### Schema-Guided AI Analysis JSON

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

An example of how AI can interpret trace data when guided by a schema, providing structured analysis and context.

```json
{
  "trace_file": "/tmp/trace.1034012359.xt",
  "total_lines": 847,
  "unique_functions": 23,
  "max_call_depth": 12,
  "database_queries": 15,
  "specification": "https://xdebug.org/docs/trace",
  "analysis_context": "Debugging user authentication flow with database queries",
  "content": ["2\t1\t0\t0.000489\t401872\ttestFunction\t1\t\ttest.php\t35\t2\t$a=null $b=10"]
}
```

--------------------------------

### Build and Verify Docker Test Container

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/docker/README.md

Builds the Docker test container and verifies its PHP version and Xdebug installation.

```bash
docker compose build
docker compose run --rm php php -v
docker compose run --rm php php -m | grep xdebug
```

--------------------------------

### Run MCP Server with Debug Logging

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Starts the MCP server with debug logging enabled via an environment variable.

```bash
MCP_DEBUG=1 php bin/xdebug-mcp
```

--------------------------------

### AI Debugging Workflow: Before (Interactive)

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/ADR-001-forward-trace-only-approach.md

Example of the workflow for AI debugging using traditional interactive methods, involving setting breakpoints and stepping through code execution.

```bash
# Set breakpoint → Connect → Step → Inspect → Step → Inspect...
xdebug_set_breakpoint(...) → xdebug_step_into() → xdebug_get_variables()
```

--------------------------------

### Example Trace Output Structure

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Illustrates the column structure of Xdebug trace files (.xt format). Understanding this format is crucial for analyzing execution flows and variable states.

```text
Level  Func ID  Time Index  Memory  Function Name      User Def  Filename         Line  Params
0      1        0.0001      384000  {main}            1         tests/fixtures/debug.php   1     
1      2        0.0002      384100  fibonacci         1         tests/fixtures/debug.php   15    $n = 8
1      3        0.0003      384200  fibonacci         1         tests/fixtures/debug.php   15    $n = 7
```

--------------------------------

### Start Trace via MCP

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Initiate an Xdebug trace using an MCP JSON-RPC call. This is part of the MCP-based trace collection process.

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"xdebug_start_trace","arguments":{}}}' | php bin/xdebug-mcp
```

--------------------------------

### Install Xdebug MCP as a Codex Skill

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Clone the Xdebug MCP repository and copy the skills to the Codex skills directory.

```bash
git clone --depth 1 https://github.com/koriym/xdebug-mcp.git /tmp/xdebug-mcp
mkdir -p ~/.codex/skills
cp -r /tmp/xdebug-mcp/skills/xdebug ~/.codex/skills/
```

--------------------------------

### Start Interactive Xdebug Session (Background)

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Initiate an Xdebug session in the background using `xstep`. This establishes a waiting Xdebug session ready for MCP commands on port 9004.

```bash
./bin/xstep target_script.php &
```

--------------------------------

### Interactive REPL Debugging

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Start an interactive debugging session using xrepl with a specified breakpoint and PHP script.

```bash
xrepl --break="script.php:42" -- php script.php
```

--------------------------------

### CLI Tool Table

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms-full.txt

Provides a summary of available CLI tools, their purposes, and example usage. This table serves as a quick reference for the different functionalities offered by Xdebug MCP.

```text
| Tool | Purpose | Example |
|------|---------|---------|
| `xstep` | Breakpoint debugging | `xstep --break="file.php:42" -- php script.php` |
| `xtrace` | Execution flow analysis | `xtrace -- php script.php` |
| `xprofile` | Performance profiling | `xprofile --json -- php api.php` |
| `xcoverage` | Code coverage analysis | `xcoverage -- vendor/bin/phpunit` |
| `xback` | Call stack at breakpoint | `xback --break="file.php:50" -- php app.php` |
```

--------------------------------

### CLI Tool: Code Coverage Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms.txt

Use the `xcoverage` CLI tool to generate code coverage reports. This example shows how to run it with PHPUnit.

```bash
xcoverage -- vendor/bin/phpunit
```

--------------------------------

### GitHub Actions CI/CD Integration for Performance Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/README.md

Example GitHub Actions workflow step for running Xdebug trace analysis and summary. It includes enabling Xdebug tracing, analyzing traces, and validating results.

```yaml
# GitHub Actions example
- name: Performance Analysis
  run: |
    php -dxdebug.mode=trace tests/PerformanceTest.php
    ./xdebug-profiler/bin/trace-analyze /tmp/trace.*.xt --validate
    ./xdebug-profiler/bin/trace-summary analysis-result.json
```

--------------------------------

### Example xstep.json Schema Output

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/fake/README.md

Illustrates the structure of the JSON output generated by Forward Trace tests, conforming to the xstep.json schema. This format is used for AI analysis of variable evolution and control flow.

```json
{
    "$schema": "https://koriym.github.io/xdebug-mcp/schemas/xstep.json",
    "context": "Your description here", 
    "breaks": [
        {
            "step": 1,
            "location": {"file": "pattern.php", "line": 8},
            "variables": {
                "$counter": "int: 0",
                "$items": "array: [0: \"apple\", 1: \"banana\"]"
            }
        }
    ],
    "trace": {
        "file": "/tmp/trace.123456.xt",
        "content": ["Version: 3.4.4", "..."]
    }
}
```

--------------------------------

### Integrate with Xdebug MCP Server

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/README.md

Example of using the MCP server with Xdebug to trace PHP scripts and provide context for analysis. Useful for analyzing user workflow.

```bash
mcp__xdebug__x-trace --script="php app.php" --context="User workflow analysis"
```

--------------------------------

### Check Xdebug Installation in Docker

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/docker/README.md

Command to verify if Xdebug is installed and enabled within the Docker container.

```bash
docker compose run --rm php php -m | grep xdebug
```

--------------------------------

### AI Debugging Workflow: After (Forward Trace)

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/ADR-001-forward-trace-only-approach.md

Example of the optimized AI debugging workflow using Forward Trace with conditional breakpoints and context capture for comprehensive execution analysis.

```bash
# Complete execution analysis with conditional capture
./bin/xstep script.php \
  --breakpoint 'User.php:42:$user==null' \
  --context 'User validation analysis'
```

--------------------------------

### Common Mistakes in Interactive Debugging Setup

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/fake/COMPREHENSIVE_MCP_TEST_EN.md

These bash commands illustrate common errors when attempting to test interactive debugging features, such as testing MCP tools directly or executing scripts without a proper connection target.

```bash
# ❌ Mistake 1: Testing MCP tools directly
mcp__xdebug__xdebug_connect  # This alone is insufficient

# ❌ Mistake 2: Executing script directly  
XDEBUG_TRIGGER=1 php -dxdebug.mode=debug test.php  # No connection target

# ❌ Mistake 3: Wrong sequence
./bin/xdebug-debug test.php  # XdebugClient not started
php test_new_xdebug_debug.php &

```

--------------------------------

### Dockerfile for Xdebug Trace Analyzer Environment

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

A Dockerfile to set up an environment for running Xdebug trace analysis. It installs PHP, Xdebug, copies the analyzer, and configures Xdebug for tracing.

```dockerfile
# Dockerfile for analysis environment
FROM php:8.2-cli

# Install Xdebug
RUN pecl install xdebug && docker-php-ext-enable xdebug

# Copy analyzer
COPY xdebug-profiler /app/xdebug-profiler

# Configure Xdebug for trace
RUN echo "xdebug.mode=trace" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini && \
    echo "xdebug.trace_output_dir=/tmp" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

WORKDIR /app
```

--------------------------------

### Get Stack Trace with xback

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Use the xback tool to get a stack trace at a specific breakpoint in the code.

```bash
./bin/xback --break="demo/buggy.php:44" -- php demo/buggy.php
```

--------------------------------

### Download Demo Files

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Download the demo files for Xdebug MCP to test its functionality.

```bash
git clone --depth 1 https://github.com/koriym/xdebug-mcp.git /tmp/xdebug-demo
```

--------------------------------

### Troubleshooting Breakpoints Not Hitting

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/debug_guideline_for_humans.md

Ensure breakpoints are hit by verifying file paths (use absolute paths), checking line numbers, and validating condition syntax. Start with simple conditions.

```bash
# Verify file path is correct (use absolute paths)
./bin/xstep --break='/full/path/to/file.php:42' -- php script.php

# Check if line number exists
wc -l file.php  # Should be > your line number

# Verify condition syntax
# Use simple conditions first: $var==null, $var>0, empty($var)
```

--------------------------------

### Show MCP Server Help

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Displays available command-line options and usage for the MCP server.

```bash
php bin/xdebug-mcp --help
```

--------------------------------

### Performance Analysis with xprofile

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/bin/README.md

Profile slow endpoints to identify performance bottlenecks. Use the --context option to document the analysis scope.

```bash
./xprofile --context="Payment processing bottleneck analysis" -- php checkout.php
```

--------------------------------

### Analysis Result Schema Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/docs/ARCHITECTURE.md

An example of the structured JSON output schema used for AI consumption, including metadata, statistics, and performance analysis.

```json
{
  "📊 metadata": {
    "🕒 generated_at": "2025-08-31T12:00:00Z",
    "📁 source_trace_file": "/tmp/trace.xt",
    "⏱️ total_execution_time": 1.234,
    "💾 peak_memory_usage": 7654321
  },
  "📈 statistics": {
    "🔢 unique_functions_count": 123,
    "📂 unique_files_count": 45,
    "🏷️ vendor_vs_user": {
      "👤 user_functions": 67,
      "📦 vendor_functions": 34,
      "⚙️ internal_functions": 22
    }
  },
  "🚀 performance_analysis": {
    "🐌 slowest_functions": [...],
    "💾 memory_intensive_functions": [...],
    "⚠️ performance_warnings": [...] 
  },
  "🗂️ function_index": {...},
  "📂 file_index": {...}
}
```

--------------------------------

### Reveal.js Initialization

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

Basic configuration for initializing Reveal.js with common options for presentations.

```javascript
Reveal.initialize({
  hash: true,
  transition: 'slide',
  transitionSpeed: 'default',
  backgroundTransition: 'fade',
  controls: true,
  progress: true,
  center: true,
  touch: true,
  loop: false,
  rtl: false,
  navigationMode: 'default',
  shuffle: false,
  fragments: true,
  fragmentInURL: false,
  embedded: false,
  help: true,
  showNotes: false,
  autoPlayMedia: null,
  autoSlide: 0,
  autoSlideStoppable: true,
  mouseWheel: false,
  hideInactiveCursor: true,
  hideCursorTime: 5000,
  previewLinks: false,
  keyboard: true,
  plugins: [ RevealHighlight, RevealNotes ]
});
```

--------------------------------

### Memory Intensive Functions Analysis Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

Example JSON output for memory-intensive functions analysis. Identifies functions with high memory consumption and suggests optimization strategies.

```json
{
  "💾 memory_intensive_functions": [
    {
      "🏷️ function_name": "DataProcessor::loadLargeDataset",
      "💾 memory_delta_formatted": "+50.2MB",
      "💡 optimization_priority": "critical",
      "💡 suggestion": "Consider streaming or chunked processing"
    }
  ]
}
```

--------------------------------

### xprofile - Basic Usage

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Identify performance bottlenecks with precision data. Captures execution time, memory usage, and automatically identifies bottlenecks. Use for performance optimization.

```bash
~/.composer/vendor/bin/xprofile [--json] [--context=TEXT] [--include-vendor=PATTERNS] -- command
```

--------------------------------

### Run User Demo with Claude

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/tests/ai/README.md

Execute the user demo by instructing Claude to read and follow instructions in `tests/ai/demo.md`. Results will be stored in `tests/ai/demo-results/`.

```bash
claude
> Read tests/ai/demo.md and follow the instructions.
```

--------------------------------

### Schema-Validated JSON Output Example

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/debug_guideline_for_ai.md

An example of the JSON output generated by Forward Trace tools, which is schema-validated for consistent AI analysis. It includes breakpoint information and trace file details.

```json
{
  "$schema": "https://koriym.github.io/xdebug-mcp/schemas/xstep.json",
  "breaks": [
    {
      "step": 1,
      "location": {"file": "file.php", "line": 17},
      "variables": {
        "$total": "int: 0",
        "$items": "array: []"
      }
    }
  ],
  "trace": {
    "file": "/tmp/trace.1034012359.xt",
    "content": ["..."]
  }
}
```

--------------------------------

### Correct Step Recording Command Format

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/TROUBLESHOOTING.md

Demonstrates the correct syntax for the `--steps` parameter in the `xstep` command, requiring an equals sign.

```bash
# ✅ Correct format
./bin/xstep --break="loop.php:15" --steps=100 -- php script.php

# ❌ Wrong format
./bin/xstep --break="loop.php:15" --steps 100  # Missing equals sign
```

--------------------------------

### Profile Performance with xprofile

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Use the xprofile tool to profile performance bottlenecks in a PHP script. Outputs JSON.

```bash
./bin/xprofile --json -- php demo/slow.php
```

--------------------------------

### Run Psalm Static Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/AGENTS.md

Executes static analysis using Psalm.

```bash
composer psalm
```

--------------------------------

### Get Stack Trace at Breakpoint

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Capture a stack trace at a specific breakpoint in a PHP script using xback.

```bash
xback --break='app.php:50' -- php app.php
```

--------------------------------

### Performance Investigation and Summary

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

Analyze trace files for performance issues, generate a summary JSON, and extract top performance bottlenecks. Requires trace files to be generated first.

```bash
# Analyze with context
./bin/trace-analyze /tmp/slow-request.xt --context="Investigating slow API endpoint performance"

# Generate summary
./bin/trace-summary summary analysis-result.json

# Extract top bottlenecks
./bin/trace-bottlenecks analysis-result.json 5
```

--------------------------------

### TraceUtils Key Methods

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/docs/ARCHITECTURE.md

Provides advanced utilities for comparing trace analyses, generating summary reports, and extracting performance bottlenecks.

```php
public static function compareTwoAnalyses(array $analysis1, array $analysis2): array
public static function generateSummaryReport(array $analysis): array
public static function extractTopBottlenecks(array $analysis, int $limit = 10): array
```

--------------------------------

### Verify Xdebug Trace Generation

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/README.md

Check if the Xdebug extension is installed and enabled in your PHP environment. This helps diagnose issues where traces are not being generated.

```bash
# Verify Xdebug trace generation
php -m | grep xdebug
```

--------------------------------

### Performance Profiling with xprofile

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/bin/README.md

Profile PHP script performance with microsecond precision. Use the --context option for AI analysis and --json for MCP integration.

```bash
./xprofile -- php script.php
```

```bash
./xprofile --context="API endpoint performance" -- php api.php
```

```bash
./xprofile --json -- php slow-script.php
```

--------------------------------

### Using Xdebug Trace Analyzer with Docker

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

Commands to build a Docker image for the trace analyzer and run it to analyze a trace file. It mounts the current directory to share files.

```bash
# Use with Docker
docker build -t trace-analyzer .
docker run -v $(pwd):/app trace-analyzer \
  /app/xdebug-profiler/bin/trace-analyze /tmp/trace.xt --context="Docker analysis"
```

--------------------------------

### Interactive Debugging with xstep

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/bin/README.md

Start an interactive debugging session with conditional breakpoints. Use this to pause execution at specific lines or under certain conditions.

```bash
./xstep --break='script.php:10' -- php script.php
```

```bash
./xstep --break='User.php:42:$id==null' -- php script.php
```

```bash
./xstep --break='loop.php:15' --steps=100 -- php script.php
```

```bash
./xstep --break='Auth.php:20:empty($token),User.php:85:$id==0' -- php app.php
```

--------------------------------

### Compare Performance Before and After Optimization

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

Analyze trace files before and after implementing an optimization (like caching) and compare the results. This helps quantify the performance improvement.

```bash
# Before optimization
./bin/trace-analyze /tmp/before-cache.xt --context="Before implementing cache" > before.json

# After optimization  
./bin/trace-analyze /tmp/after-cache.xt --context="After implementing cache" > after.json

# Compare results
./bin/trace-compare before.json after.json
```

--------------------------------

### Basic Trace Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

Generate a trace file using PHP and then analyze it with the trace-analyze tool. Specify the output directory for trace files.

```bash
# Generate a trace file first
php -dxdebug.mode=trace -dxdebug.start_with_request=yes -dxdebug.trace_output_dir=/tmp your-app.php

# Analyze the trace
./xdebug-profiler/bin/trace-analyze /tmp/trace.12345.xt --context="Basic application analysis"
```

--------------------------------

### Validate JSON Structure for Breakpoints

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/TROUBLESHOOTING.md

Shows examples of invalid and valid JSON structures for specifying breakpoints, highlighting the need for proper quoting and syntax.

```json
// ❌ Missing quotes in condition
{"breakpoints": "User.php:42:$id==null"}

// ✅ Properly escaped condition  
{"breakpoints": "User.php:42:$id==null"}

// ❌ Invalid JSON structure
{"script": "test.php" "context": "test"}

// ✅ Valid JSON structure
{"script": "test.php", "context": "test"}
```

--------------------------------

### Batch Process Multiple Traces

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/README.md

Example of processing multiple trace files in a loop using a bash script. This is useful for analyzing a series of traces efficiently.

```bash
# Process multiple traces
for trace in /tmp/trace.*.xt; do
    ./bin/trace-analyze "$trace" --context="Batch analysis $(basename $trace)"
done
```

--------------------------------

### Profile Performance via CLI

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/README.md

Directly use the xprofile CLI command to profile the performance of a PHP script.

```bash
xprofile -- php api.php
```

--------------------------------

### Check Environment with check-env

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/bin/README.md

Verify the PHP environment for Xdebug installation and configuration. This script checks PHP version, Xdebug extension, required modes, and port availability.

```bash
./check-env
# Verifies: PHP version, Xdebug extension, required modes, port availability
```

--------------------------------

### AI Analysis Strategies JSON Schema

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/README.md

Example JSON structure defining AI analysis strategies, including approach, workflow, and interpretation guidelines for performance metrics.

```json
{
  "x-ai-strategies": {
    "analysis_approach": "performance_first",
    "optimization_workflow": ["warnings", "slowest", "memory", "frequency"],
    "interpretation_guide": {
      "execution_time": "Functions >0.1s warrant investigation",
      "memory_usage": "Deltas >1MB indicate significant allocations"
    }
  }
}
```

--------------------------------

### Microsecond-Precision Performance Profiling

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

Use xprofile to perform microsecond-precision performance profiling on PHP scripts. The AI analyzes bottlenecks and provides optimization suggestions.

```bash
./vendor/bin/xprofile --context="API performance analysis" -- php slow_api.php
```

--------------------------------

### Stop Trace and Get File Location

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Stop the Xdebug trace and retrieve the file location using an MCP JSON-RPC call. This completes the trace collection process.

```bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"xdebug_stop_trace","arguments":{}}}' | php bin/xdebug-mcp
```

--------------------------------

### Xdebug Configuration

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms-full.txt

Configure Xdebug for debugging, profiling, and coverage. Use port 9004 to avoid IDE conflicts. Ensure Xdebug is enabled and set to start with requests.

```ini
zend_extension=xdebug
xdebug.mode=debug,profile,coverage
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9004
xdebug.output_dir=/tmp
```

--------------------------------

### Compare var_dump vs Forward Trace

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/debug_guideline_for_humans.md

Illustrates the difference between modifying code for debugging (var_dump) and using Forward Trace for non-intrusive runtime analysis.

```php
// ❌ OLD WAY: Modify code, test, clean up, repeat
var_dump($user);

echo "Debug checkpoint 1";
print_r($cart);
die("HERE"); // Risk: accidentally commit debug code

// ✅ NEW WAY: One command, complete analysis
./bin/xstep --break='Auth.php:42:$user==null' --exit-on-break -- php app.php
// Result: Complete execution trace when $user is null, no code changes
```

--------------------------------

### Programmatic Trace Analysis in PHP

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/README.md

Demonstrates programmatic usage of the XdebugTraceAnalyzerV2 class in PHP for analyzing traces, searching functions, and validating results.

```php
// Programmatic usage
$analyzer = new XdebugTraceAnalyzerV2('/tmp/trace.xt');
$result = $analyzer->analyzeTrace('Custom analysis context');

// Search specific patterns
$authCalls = $analyzer->searchFunction('authenticate');

// Validate results
$errors = $analyzer->validateSchema();
```

--------------------------------

### Complete Environment Reset Procedure

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/TROUBLESHOOTING.md

Perform a complete reset of the Xdebug MCP environment by clearing temporary files, reinstalling dependencies, verifying the installation, and testing basic functionality.

```bash
# 1. Clear all temporary files
rm /tmp/xdebug-mcp-context.json
rm /tmp/trace.*.xt
rm /tmp/cachegrind.out.*

# 2. Reinstall dependencies
composer install --no-cache

# 3. Verify installation
./bin/check-env
composer test-json

# 4. Test basic functionality
echo '<?php echo "Reset test\n";' > reset-test.php
./bin/xtrace --context="Reset verification" -- php reset-test.php
rm reset-test.php
```

--------------------------------

### Execute Target Script with Xdebug Step Debugger

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/CLAUDE.md

Once the XdebugClient is listening, execute the target script using the xstep command. This initiates the connection from the script to the waiting debugger.

```bash
./bin/xstep target_script.php
```

--------------------------------

### Interactive Debugging Steps (Conceptual)

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/slide/index.html

Outlines a conceptual process for interactive debugging using snapshots, similar to taking multiple photos without capturing the full sequence of events.

```text
// Step 1: Set breakpoint
// Step 2: Run to breakpoint (📷 snapshot)
// Step 3: Check $user variable
// Step 4: Step into function
// Step 5: Another snapshot (📷)
// Step 6: Check another variable...

// → Multiple photos, missing the story
```

--------------------------------

### Profile Slow PHP Code with xprofile

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/demo/README.md

Use the `xprofile` tool to find performance bottlenecks in slow PHP scripts. This snippet shows the command to initiate the profiling.

```bash
ask AI "Profile demo/slow.php and find bottlenecks"
```

--------------------------------

### CLI Tool: Stack Trace at Breakpoint

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/docs/llms.txt

Use the `xback` CLI tool to get a call stack trace at a specified breakpoint. This is useful for understanding the execution context when an issue occurs.

```bash
xback --break="app.php:50" -- php app.php
```

--------------------------------

### Trace Analyze Command Line Options

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/README.md

Lists available command-line options for the trace-analyze command, including context, compact output, search, and validation.

```bash
Options:
  --context="description"     Add contextual description for AI analysis
  --compact                   Output compact JSON (no pretty printing)
  --search="function"         Search for specific function calls
  --validate                  Validate output against JSON schema
```

--------------------------------

### CI/CD Pipeline for Performance Analysis

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/profiler/examples/basic-usage.md

GitHub Actions workflow to automate performance analysis. It sets up PHP with Xdebug, runs a performance test, analyzes the trace, generates a report, and checks for regressions.

```yaml
# .github/workflows/performance.yml
name: Performance Analysis
on: [push, pull_request]

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup PHP with Xdebug
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: xdebug
          
      - name: Run Performance Test
        run: |
          php -dxdebug.mode=trace tests/PerformanceTest.php
          
      - name: Analyze Trace
        run: |
          ./xdebug-profiler/bin/trace-analyze /tmp/trace.*.xt \
            --context="CI Performance Test - Commit ${{ github.sha }}" \
            > performance-result.json
            
      - name: Generate Report
        run: |
          ./xdebug-profiler/bin/trace-summary summary performance-result.json \
            > performance-report.json
            
      - name: Check Performance Regression
        run: |
          # Fail build if performance score < 80
          SCORE=$(jq '.["📋 executive_summary"]["📊 performance_score"]' performance-report.json)
          if (( $(echo "$SCORE < 80" | bc -l) )); then
            echo "Performance regression detected: Score $SCORE"
            exit 1
          fi
```

--------------------------------

### xtrace - Basic Usage

Source: https://github.com/koriym/xdebug-mcp/blob/1.x/skills/xdebug/SKILL.md

Trace execution forward from start to finish. Captures complete execution flow, function calls, parameters, and timing data. Use for general PHP debugging.

```bash
~/.composer/vendor/bin/xtrace [--json] [--context=TEXT] [--include-vendor=PATTERNS] -- command
```