README

Debug PHP with Natural Language — No var_dump(), No Guesswork

AI-powered PHP debugging tools using Xdebug's runtime analysis. Works with Claude Code (plugin), Cursor, Windsurf (MCP), and CLI.

Natural Language Debugging

Just tell your AI assistant what you want:

English:

"Debug script.php and find why $user is null at line 42"
"Profile api.php and find the performance bottleneck"
"Trace the authentication flow in login.php"
"Check test coverage for UserService"

日本語:

"script.phpをデバッグして、42行目で$userがnullになる原因を調べて"
"api.phpのパフォーマンスボトルネックを見つけて"
"login.phpの認証フローをトレースして"
"UserServiceのテストカバレッジを確認して"

The AI automatically selects the appropriate tool, executes it, and analyzes the results.

Requirements

PHP 8.1+
Xdebug 3.x extension (installed, but not enabled by default)
AI assistant: Claude Code (plugin), Cursor/Windsurf (MCP), or CLI

💡 Performance Tip: Keep Xdebug disabled in php.ini for daily use. This tool loads Xdebug on-demand only when needed.

Quick Start

1. Install

composer global require koriym/xdebug-mcp

2. Verify Xdebug

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

3. Setup AI Integration

Claude Code:

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

Cursor / Windsurf: See MCP Configuration below.

4. Restart your AI assistant and try it

# Download demo files
git clone --depth 1 https://github.com/koriym/xdebug-mcp.git /tmp/xdebug-demo

# Ask Claude to debug
"Debug /tmp/xdebug-demo/demo/buggy.php and find the bugs"

Or use the skill directly:

/xdebug

Try CLI Tools

Run the demo examples to see each tool in action:

# Debug buggy code with breakpoints (JSON output)
./bin/xstep --break="demo/buggy.php:22" -- php demo/buggy.php

# Trace execution flow
./bin/xtrace --context="Debug demo" -- php demo/buggy.php

# Profile performance bottlenecks
./bin/xprofile --json -- php demo/slow.php

# Analyze code coverage
./bin/xcoverage -- php demo/coverage.php

# Get stack trace at breakpoint
./bin/xback --break="demo/buggy.php:44" -- php demo/buggy.php

Each command outputs structured JSON data that AI can analyze to provide debugging insights.

How It Works

flowchart LR
    A[You] -->|"Debug login.php"| B[AI Assistant]
    B -->|CLI / MCP| C[xtrace, xstep, ...]
    C -->|Runtime Analysis| D[Xdebug]
    D -->|JSON| C
    C -->|Results| B
    B -->|Explanation| A

No var_dump(). No code modification. No guesswork.

Available Tools

Tool	Purpose	Example Prompt
`xstep`	Breakpoint debugging, variable inspection	"Stop at line 42 and show me the variables"
`xtrace`	Execution flow analysis	"Trace how the request flows through the app"
`xprofile`	Performance profiling	"Find what's making this endpoint slow"
`xcoverage`	Code coverage analysis	"Which lines aren't covered by tests?"
`xback`	Call stack at breakpoint	"Show me how we got to this error"

CLI Usage

For direct command-line usage without AI:

# Trace execution
xtrace -- php script.php

# Profile performance
xprofile -- php api.php

# Debug with conditional breakpoint
xstep --break='script.php:42:$user==null' --exit-on-break -- php script.php

# Code coverage
xcoverage -- vendor/bin/phpunit

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

Run --help on any tool for detailed options.

MCP Configuration

For Cursor, Windsurf, and other MCP-compatible tools.

Create .mcp.json in your project root:

{
  "mcpServers": {
    "xdebug": {
      "command": "php",
      "args": ["/Users/YOUR_USERNAME/.composer/vendor/bin/xdebug-mcp"]
    }
  }
}

Find the correct path: which xdebug-mcp

Interactive REPL

For hands-on debugging without AI, use the interactive debugger:

xstep --break="script.php:42" -- php script.php

Commands:

Command	Description
`s`	Step into function
`o`	Step over line
`out`	Step out of function
`c`	Continue execution
`p <var>`	Print variable (e.g., `p $user`)
`bt`	Show backtrace
`l`	List source code
`q`	Quit debugger

Docker Support

All tools work with Docker, Podman, and Kubectl:

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

The tools automatically detect container runtime and configure Xdebug networking.

See tests/docker/README.md for details.

For Developers

See tests/ai/README.md for tool discoverability testing.

AI Native Design

This tool is designed specifically for AI consumption, not adapted from human interfaces.

Debugger for Humans	AI Native (this tool)
Step-by-step interaction	One-shot batch execution
Session management required	Stateless CLI
Multiple tool calls	Single command, complete data
Manual log placement	Automatic full trace

Why it matters:

Fewer tokens: One command returns all data vs. many back-and-forth calls
No session errors: Stateless design eliminates timeout/connection issues
Comprehensive data: xtrace captures everything; AI filters what it needs

Why "xdebug-mcp"?

This project started as an MCP (Model Context Protocol) server for AI-powered PHP debugging. While MCP remains supported for tools like Cursor and Windsurf, we now recommend the plugin approach for Claude Code users — it's simpler and requires no MCP configuration.

The CLI tools (xstep, xtrace, xprofile, xcoverage, xback) work independently of both MCP and plugins.

Resources

Troubleshooting - Setup issues
Forward Trace Guide - AI debugging methodology
llms.txt - LLM-readable documentation
Motivation - Why we built this
Xdebug Docs - Official documentation

Stop debugging blind. Just ask your AI.

koriym / xdebug-mcp

Maintainers

Details