# Xdebug MCP

## Overview

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

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

## Core Purpose

- AI-Driven PHP Analysis: Enable AI assistants to understand PHP application behavior through runtime data
- Universal Debugging Tool: Works with any PHP application, framework, or codebase without modification
- Non-invasive: Zero code modifications required - no var_dump() debugging
- Performance Profiling: Microsecond-precision timing and bottleneck identification
- Code Coverage Analysis: Comprehensive test coverage reports and analysis

## CLI Tools

| Tool | Purpose |
|------|---------|
| `xstep` | Breakpoint debugging, variable inspection |
| `xtrace` | Execution flow analysis |
| `xprofile` | Performance profiling |
| `xcoverage` | Code coverage analysis |
| `xback` | Call stack at breakpoint |

## Installation

### Quick Start

```bash
# Install globally via Composer
composer global require koriym/xdebug-mcp

# Verify Xdebug
~/.composer/vendor/bin/check-env
```

### Claude Code Plugin

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

### MCP Configuration (Cursor/Windsurf)

Create `.mcp.json` in your project root:

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

## Requirements

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

## Usage Examples

### Natural Language (Claude Code)

```text
"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"
```

### CLI Tools

```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
```

### Conditional Breakpoints

```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
```

## Documentation

- `CLAUDE.md`: AI integration instructions
- `docs/debug_guideline_for_ai.md`: AI debugging methodology
- `docs/schemas/`: JSON schemas for tool outputs
- `docs/TROUBLESHOOTING.md`: Common issues and solutions

## 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 work independently of both MCP and plugins.

## GitHub Repository

https://github.com/koriym/xdebug-mcp