xdebug-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 kpanuragh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+# Xdebug MCP Server
+
+[![npm version](https://badge.fury.io/js/xdebug-mcp.svg)](https://www.npmjs.com/package/xdebug-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An MCP (Model Context Protocol) server that provides PHP debugging capabilities through Xdebug's DBGp protocol. This allows AI assistants like Claude to directly debug PHP applications.
+
+## Features
+
+### Core Debugging
+- **Full Debug Control**: Step into, step over, step out, continue, stop
+- **Breakpoints**: Line breakpoints, conditional breakpoints, exception breakpoints, function call breakpoints
+- **Variable Inspection**: View all variables, get specific variables, set variable values
+- **Expression Evaluation**: Evaluate PHP expressions in the current context
+- **Stack Traces**: View the full call stack
+- **Multiple Sessions**: Debug multiple PHP scripts simultaneously
+- **Docker Support**: Works with PHP running in Docker containers
+
+### Advanced Features
+- **Watch Expressions**: Persistent watches that auto-evaluate on each break with change detection
+- **Logpoints**: Log messages without stopping execution using `{$var}` placeholders
+- **Memory Profiling**: Track memory usage and execution time between breakpoints
+- **Code Coverage**: Track which lines were executed during debugging
+- **Request Context**: Capture `$_GET`, `$_POST`, `$_SESSION`, `$_COOKIE`, headers automatically
+- **Step Filters**: Skip vendor/library code during stepping
+- **Debug Profiles**: Save and restore breakpoint configurations
+- **Session Export**: Export debug sessions as JSON or HTML reports
+
+## Installation
+
+### From npm (Recommended)
+
+```bash
+npm install -g xdebug-mcp
+```
+
+### From Source
+
+```bash
+git clone https://github.com/kpanuragh/xdebug-mcp.git
+cd xdebug-mcp
+npm install
+npm run build
+```
+
+## MCP Server Configuration
+
+### For Claude Code
+
+Add the xdebug-mcp server to your MCP configuration (`.mcp.json` or Claude settings):
+
+**Using npm global install:**
+
+```json
+{
+  "mcpServers": {
+    "xdebug": {
+      "command": "xdebug-mcp",
+      "env": {
+        "XDEBUG_PORT": "9003",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+**Using npx:**
+
+```json
+{
+  "mcpServers": {
+    "xdebug": {
+      "command": "npx",
+      "args": ["-y", "xdebug-mcp"],
+      "env": {
+        "XDEBUG_PORT": "9003",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+### With Path Mappings (for Docker)
+
+When debugging PHP in Docker containers, you need path mappings to translate container paths to host paths:
+
+```json
+{
+  "mcpServers": {
+    "xdebug": {
+      "command": "xdebug-mcp",
+      "env": {
+        "XDEBUG_PORT": "9003",
+        "PATH_MAPPINGS": "{\"/var/www/html\": \"/home/user/projects/myapp\"}",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+## PHP/Xdebug Configuration
+
+### php.ini (or xdebug.ini)
+
+```ini
+[xdebug]
+zend_extension=xdebug
+
+; Enable step debugging
+xdebug.mode=debug
+
+; Start debugging on every request
+xdebug.start_with_request=yes
+
+; Host where MCP server is running
+; For Docker: use host.docker.internal
+; For local PHP: use 127.0.0.1
+xdebug.client_host=host.docker.internal
+
+; Port where MCP server listens
+xdebug.client_port=9003
+
+; IDE key (optional, for filtering)
+xdebug.idekey=mcp
+```
+
+### Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  php:
+    image: php:8.2-apache
+    volumes:
+      - ./src:/var/www/html
+      - ./xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini
+    extra_hosts:
+      - "host.docker.internal:host-gateway"  # Required for Linux
+    environment:
+      - XDEBUG_MODE=debug
+      - XDEBUG_CONFIG=client_host=host.docker.internal client_port=9003
+```
+
+## Available MCP Tools (41 Total)
+
+### Session Management
+
+| Tool | Description |
+|------|-------------|
+| `list_sessions` | List all active debug sessions |
+| `get_session_state` | Get detailed state of a session |
+| `set_active_session` | Set which session is active |
+| `close_session` | Close a debug session |
+
+### Breakpoints
+
+| Tool | Description |
+|------|-------------|
+| `set_breakpoint` | Set a line or conditional breakpoint |
+| `set_exception_breakpoint` | Break on exceptions |
+| `set_call_breakpoint` | Break on function calls |
+| `remove_breakpoint` | Remove a breakpoint |
+| `update_breakpoint` | Enable/disable or modify a breakpoint |
+| `list_breakpoints` | List all breakpoints |
+
+### Execution Control
+
+| Tool | Description |
+|------|-------------|
+| `continue` | Continue to next breakpoint |
+| `step_into` | Step into function calls |
+| `step_over` | Step over (skip function internals) |
+| `step_out` | Step out of current function |
+| `stop` | Stop debugging |
+| `detach` | Detach and let script continue |
+
+### Inspection
+
+| Tool | Description |
+|------|-------------|
+| `get_stack_trace` | Get the call stack |
+| `get_contexts` | Get available variable contexts |
+| `get_variables` | Get all variables in scope |
+| `get_variable` | Get a specific variable |
+| `set_variable` | Set a variable's value |
+| `evaluate` | Evaluate a PHP expression |
+| `get_source` | Get source code |
+
+### Watch Expressions
+
+| Tool | Description |
+|------|-------------|
+| `add_watch` | Add a persistent watch expression |
+| `remove_watch` | Remove a watch expression |
+| `evaluate_watches` | Evaluate all watches and detect changes |
+| `list_watches` | List all active watches |
+
+### Logpoints
+
+| Tool | Description |
+|------|-------------|
+| `add_logpoint` | Add a logpoint with message template |
+| `remove_logpoint` | Remove a logpoint |
+| `get_logpoint_history` | View log output and hit statistics |
+
+### Profiling
+
+| Tool | Description |
+|------|-------------|
+| `start_profiling` | Start memory/time profiling |
+| `stop_profiling` | Stop profiling and get results |
+| `get_profile_stats` | Get current profiling statistics |
+| `get_memory_timeline` | View memory usage over time |
+
+### Code Coverage
+
+| Tool | Description |
+|------|-------------|
+| `start_coverage` | Start tracking code coverage |
+| `stop_coverage` | Stop and get coverage report |
+| `get_coverage_report` | View coverage statistics |
+
+### Debug Profiles
+
+| Tool | Description |
+|------|-------------|
+| `save_debug_profile` | Save current configuration as a profile |
+| `load_debug_profile` | Load a saved debug profile |
+| `list_debug_profiles` | List all saved profiles |
+
+### Additional Tools
+
+| Tool | Description |
+|------|-------------|
+| `capture_request_context` | Capture HTTP request context |
+| `add_step_filter` | Add filter to skip files during stepping |
+| `list_step_filters` | List step filter rules |
+| `get_function_history` | View function call history |
+| `export_session` | Export session as JSON/HTML report |
+| `capture_snapshot` | Capture debug state snapshot |
+
+## Usage Examples
+
+### Setting a Breakpoint
+
+```
+Use set_breakpoint with file="/var/www/html/index.php" and line=25
+```
+
+### Conditional Breakpoint
+
+```
+Use set_breakpoint with file="/var/www/html/api.php", line=42, condition="$userId > 100"
+```
+
+### Watch Expression
+
+```
+Use add_watch with expression="$user->email"
+Use add_watch with expression="count($items)"
+```
+
+### Logpoint
+
+```
+Use add_logpoint with file="/var/www/html/api.php", line=50, message="User {$userId} accessed {$endpoint}"
+```
+
+### Inspecting Variables
+
+```
+Use get_variables to see all local variables
+Use get_variable with name="$user" to inspect a specific variable
+Use evaluate with expression="count($items)" to evaluate an expression
+```
+
+### Capture Request Context
+
+```
+Use capture_request_context to see $_GET, $_POST, $_SESSION, cookies, and headers
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `XDEBUG_PORT` | `9003` | Port to listen for Xdebug connections |
+| `XDEBUG_HOST` | `0.0.0.0` | Host to bind |
+| `COMMAND_TIMEOUT` | `30000` | Command timeout in milliseconds |
+| `PATH_MAPPINGS` | - | JSON object mapping container to host paths |
+| `MAX_DEPTH` | `3` | Max depth for variable inspection |
+| `MAX_CHILDREN` | `128` | Max children to return for arrays/objects |
+| `MAX_DATA` | `2048` | Max data size per variable |
+| `LOG_LEVEL` | `info` | Log level: debug, info, warn, error |
+
+## How It Works
+
+1. **MCP Server starts** and listens for Xdebug connections on port 9003
+2. **PHP script runs** with Xdebug enabled
+3. **Xdebug connects** to the MCP server via DBGp protocol
+4. **AI uses MCP tools** to control debugging (set breakpoints, step, inspect)
+5. **DBGp commands** are sent to Xdebug, responses parsed and returned
+
+```
+┌─────────────┐     MCP/stdio      ┌─────────────┐     DBGp/TCP      ┌─────────────┐
+│   Claude    │ ◄────────────────► │  xdebug-mcp │ ◄───────────────► │   Xdebug    │
+│  (AI Agent) │                    │   Server    │                   │  (in PHP)   │
+└─────────────┘                    └─────────────┘                   └─────────────┘
+```
+
+## Troubleshooting
+
+### No debug sessions appearing
+
+1. Check that Xdebug is installed: `php -v` should show Xdebug
+2. Verify Xdebug config: `php -i | grep xdebug`
+3. Ensure `xdebug.client_host` points to the MCP server
+4. Check firewall allows connections on port 9003
+
+### Connection issues with Docker
+
+1. For Linux, add `extra_hosts: ["host.docker.internal:host-gateway"]`
+2. Verify container can reach host: `curl host.docker.internal:9003`
+
+### Breakpoints not hitting
+
+1. Ensure file paths match exactly (use container paths for Docker)
+2. Check breakpoint is resolved: `list_breakpoints`
+3. Verify script execution reaches that line
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Configuration Management
+ */
+import { z } from 'zod';
+declare const ConfigSchema: z.ZodObject<{
+    dbgpPort: z.ZodDefault<z.ZodNumber>;
+    dbgpHost: z.ZodDefault<z.ZodString>;
+    commandTimeout: z.ZodDefault<z.ZodNumber>;
+    pathMappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    maxDepth: z.ZodDefault<z.ZodNumber>;
+    maxChildren: z.ZodDefault<z.ZodNumber>;
+    maxData: z.ZodDefault<z.ZodNumber>;
+    logLevel: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
+}, "strip", z.ZodTypeAny, {
+    dbgpPort: number;
+    dbgpHost: string;
+    commandTimeout: number;
+    maxDepth: number;
+    maxChildren: number;
+    maxData: number;
+    logLevel: "debug" | "info" | "warn" | "error";
+    pathMappings?: Record<string, string> | undefined;
+}, {
+    dbgpPort?: number | undefined;
+    dbgpHost?: string | undefined;
+    commandTimeout?: number | undefined;
+    pathMappings?: Record<string, string> | undefined;
+    maxDepth?: number | undefined;
+    maxChildren?: number | undefined;
+    maxData?: number | undefined;
+    logLevel?: "debug" | "info" | "warn" | "error" | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;
+export declare function getDefaultConfig(): Config;
+export {};

package/dist/config.js

@@ -0,0 +1,47 @@
+/**
+ * Configuration Management
+ */
+import { z } from 'zod';
+import { logger } from './utils/logger.js';
+const ConfigSchema = z.object({
+    // DBGp server settings
+    dbgpPort: z.number().int().positive().default(9003),
+    dbgpHost: z.string().default('0.0.0.0'),
+    commandTimeout: z.number().int().positive().default(30000),
+    // Path mappings for Docker
+    pathMappings: z.record(z.string(), z.string()).optional(),
+    // Variable inspection limits
+    maxDepth: z.number().int().positive().default(3),
+    maxChildren: z.number().int().positive().default(128),
+    maxData: z.number().int().positive().default(2048),
+    // Logging
+    logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+});
+export function loadConfig() {
+    const rawConfig = {
+        dbgpPort: parseInt(process.env.XDEBUG_PORT || '9003', 10),
+        dbgpHost: process.env.XDEBUG_HOST || '0.0.0.0',
+        commandTimeout: parseInt(process.env.COMMAND_TIMEOUT || '30000', 10),
+        maxDepth: parseInt(process.env.MAX_DEPTH || '3', 10),
+        maxChildren: parseInt(process.env.MAX_CHILDREN || '128', 10),
+        maxData: parseInt(process.env.MAX_DATA || '2048', 10),
+        logLevel: process.env.LOG_LEVEL || 'info',
+    };
+    // Parse path mappings from JSON if provided
+    if (process.env.PATH_MAPPINGS) {
+        try {
+            rawConfig.pathMappings = JSON.parse(process.env.PATH_MAPPINGS);
+        }
+        catch {
+            logger.warn('Failed to parse PATH_MAPPINGS environment variable');
+        }
+    }
+    const config = ConfigSchema.parse(rawConfig);
+    // Apply log level
+    logger.setLevel(config.logLevel);
+    return config;
+}
+export function getDefaultConfig() {
+    return ConfigSchema.parse({});
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAY,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,uBAAuB;IACvB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACnD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC;IACvC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAE1D,2BAA2B;IAC3B,YAAY,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAEzD,6BAA6B;IAC7B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IACrD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IAElD,UAAU;IACV,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;CACrE,CAAC,CAAC;AAIH,MAAM,UAAU,UAAU;IACxB,MAAM,SAAS,GAA4B;QACzC,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,MAAM,EAAE,EAAE,CAAC;QACzD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,SAAS;QAC9C,cAAc,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,EAAE,EAAE,CAAC;QACpE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,GAAG,EAAE,EAAE,CAAC;QACpD,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,KAAK,EAAE,EAAE,CAAC;QAC5D,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,MAAM,EAAE,EAAE,CAAC;QACrD,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;KAC1C,CAAC;IAEF,4CAA4C;IAC5C,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,SAAS,CAAC,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjE,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAE7C,kBAAkB;IAClB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAoB,CAAC,CAAC;IAE7C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC"}

package/dist/dbgp/connection.d.ts

@@ -0,0 +1,52 @@
+/**
+ * DBGp Connection Handler
+ * Handles a single Xdebug connection with message parsing and command sending.
+ */
+import * as net from 'net';
+import { EventEmitter } from 'events';
+import { DbgpResponse, InitPacket, StackFrame, Context, Property, Breakpoint, StreamData } from './types.js';
+export interface DbgpConnectionEvents {
+    init: (packet: InitPacket) => void;
+    response: (response: DbgpResponse) => void;
+    stream: (data: StreamData) => void;
+    close: () => void;
+    error: (error: Error) => void;
+}
+export declare class DbgpConnection extends EventEmitter {
+    private socket;
+    private commandTimeout;
+    private buffer;
+    private parserState;
+    private expectedLength;
+    private transactionId;
+    private pendingCommands;
+    private commandQueue;
+    private xmlParser;
+    private closed;
+    initPacket: InitPacket | null;
+    readonly id: string;
+    readonly remoteAddress: string;
+    constructor(socket: net.Socket, commandTimeout?: number);
+    private handleData;
+    private processBuffer;
+    private handleMessage;
+    private parseInitPacket;
+    private parseResponse;
+    private parseStream;
+    sendCommand(command: string, args?: Record<string, string>, data?: string): Promise<DbgpResponse>;
+    private processQueue;
+    private escapeArg;
+    private handleClose;
+    close(): void;
+    get isConnected(): boolean;
+    parseStackFrames(response: DbgpResponse): StackFrame[];
+    parseContexts(response: DbgpResponse): Context[];
+    parseProperties(response: DbgpResponse): Property[];
+    parseProperty(response: DbgpResponse): Property | null;
+    private parsePropertyNode;
+    parseBreakpoints(response: DbgpResponse): Breakpoint[];
+    parseBreakpointSet(response: DbgpResponse): {
+        id: string;
+        resolved: boolean;
+    };
+}