Merge pull request #85 from koriym/claude/observation-suggestions-721dka

Clean up stray files, unify prepend filters, fix stale CLAUDE.md references

Author: koriym

CLAUDE.md

@@ -90,14 +90,15 @@ php -dxdebug.mode=debug tests/fixtures/debug_test.php    # Run PHP script with X
 
 ### Core Components
 
-- **McpServer.php**: Main MCP protocol handler that processes JSON-RPC requests and delegates to XdebugClient
+- **McpServer.php**: Main MCP protocol handler that processes JSON-RPC requests and delegates to the debug/trace/profile/coverage components
   - Implements multiple MCP tools across debugging, profiling, and coverage categories
   - Handles JSON-RPC 2.0 protocol validation and routing
   - Supports debug mode via MCP_DEBUG environment variable
-- **XdebugClient.php**: Xdebug protocol client that communicates directly with Xdebug via sockets
-  - Socket-based communication with Xdebug daemon
+- **DebugServer.php**: DBGp debug server that listens on a TCP socket and drives interactive step debugging with Xdebug
+  - Socket-based DBGp communication with Xdebug
   - XML response parsing and transaction management
-  - Connection lifecycle and error handling
+  - Connection lifecycle and session management (see "Interactive Step Debugging Workflow" below)
+- **XdebugRunner.php / XdebugTracer.php / XdebugProfiler.php**: Spawn PHP with the appropriate Xdebug mode (trace/profile/coverage) for the non-interactive CLI tools
 - **bin/xdebug-mcp**: Executable entry point that instantiates and runs McpServer
   - CLI interface with argument parsing
   - Standard input/output handling for MCP protocol
@@ -136,8 +137,8 @@ The server exposes multiple tools via MCP across main categories:
 
 ### Architecture Flow
 1. MCP client sends JSON-RPC requests to McpServer
-2. McpServer validates and routes tool calls to XdebugClient methods
-3. XdebugClient communicates with Xdebug via socket protocol
+2. McpServer validates and routes tool calls to the relevant component (DebugServer for interactive debugging, XdebugRunner/Tracer/Profiler for trace/profile/coverage)
+3. That component communicates with Xdebug (DBGp socket for debugging, or a spawned PHP process with Xdebug enabled for trace/profile/coverage)
 4. Results are returned through MCP protocol back to client
 
 ### Testing Infrastructure
@@ -283,12 +284,11 @@ The Xdebug trace functionality enables AI assistants to analyze detailed executi
 
 **Quick Trace Testing**
 ```bash
-# Run comprehensive trace tests
-./bin/xtrace
+# Trace any PHP script (vendor code excluded by default)
+./bin/xtrace tests/fixtures/debug_test.php
 
-# Individual trace testing methods
-php -dzend_extension=xdebug -dxdebug.mode=trace bin/simple-trace-test.php
-php -dzend_extension=xdebug -dxdebug.mode=trace bin/mcp-trace-test.php
+# Direct Xdebug invocation, equivalent to what xtrace runs under the hood
+php -dzend_extension=xdebug -dxdebug.mode=trace tests/fixtures/debug_test.php
 ```
 
 **MCP-based Trace Collection**
@@ -320,7 +320,7 @@ Trace files (`.xt` format) contain structured execution data:
 - **Parameters**: Function arguments and values
 
 **Example Trace Output:**
-```
+```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
@@ -479,7 +479,7 @@ When MCP tools exceed 10% of context, Claude Code's Tool Search feature dynamica
 **For Interactive Step Debugging:**
 - User: "Debug this code", "Set breakpoints", "Step through execution", "Inspect variables"
 - AI automatically runs: `./bin/xstep path/to/file.php`
-- **IMPORTANT**: Requires XdebugClient to be listening first (see Step Debugging Workflow below)
+- **IMPORTANT**: `./bin/xstep` is a single command that internally builds a DebugServer and spawns the target, so no separate listener is required (see Step Debugging Workflow below)
 
 **For Execution Flow Analysis:**
 - User: "Trace execution", "Show function calls", "Analyze execution flow"
@@ -708,7 +708,7 @@ php -dzend_extension=xdebug -dxdebug.mode=trace \
 ### Trace File Analysis Guide
 
 **Trace file structure (.xt format):**
-```
+```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
@@ -725,26 +725,28 @@ Level | FuncID | Time    | Memory  | Function    | File:Line  | Parameters
 ### Response Examples
 
 **❌ Wrong Response (Prohibited):**
-```
+````text
 "Add this debug code to see the variable value:
 ```php
 var_dump($user);  // Add this line
-echo "Checkpoint reached"; // Add this line  
+echo "Checkpoint reached"; // Add this line
 print_r($_POST); // Add this line
 ```
+"
+````
 
 **✅ Correct Response (Required):**
-```
+````text
 "Let's trace the execution to see the variable states:
 ```bash
 ./bin/xtrace user_auth.php
 ```
-This will show us the actual $user variable value at each step without modifying the code. 
+This will show us the actual $user variable value at each step without modifying the code.
 The trace file will reveal:
 - Where $user is initialized (or should be)
 - What value it has at each function call
 - The exact execution path leading to the error"
-```
+````
 
 ### MCP Tools Priority Order
 
@@ -795,55 +797,41 @@ Follow these principles for all PHP debugging tasks to ensure consistent, profes
 
 **Required Sequence for Step Debugging:**
 
-1. **Start XdebugClient first** (must be listening before script execution)
-   ```bash
-   php test_new_xdebug_debug.php &
-   ```
+`./bin/xstep` is a single command. Internally it builds a `DebugServer` that
+both listens on port 9004 **and** spawns the target script with Xdebug
+configured to connect back to it, so you do not start a separate listener.
+
+```bash
+# One command: DebugServer listens and launches the target script
+./bin/xstep target_script.php
 
-2. **Verify port availability**
-   ```bash
-   lsof -i :9004  # Must show PHP process LISTENING
-   ```
+# Run it in the background when an AI/MCP client will drive the session
+./bin/xstep target_script.php &
+```
 
-3. **Execute target script with Xdebug**
-   ```bash
-   ./bin/xstep target_script.php
-   ```
+To control the session from MCP tools, run it in the background (`&`); see the
+"CRITICAL: AI Interactive Debugging Workflow" section above for the exact tool
+sequence (no `xdebug_connect` needed — the session is already established).
 
 ### Connection Architecture
 
 **Xdebug Connection Model:**
-- **Xdebug (script)**: Acts as **client** - connects to debugger
-- **XdebugClient**: Acts as **server** - listens on port 9004
+- **Xdebug (target script)**: Acts as **client** - connects back to the debugger
+- **DebugServer** (`./bin/xstep`): Acts as **server** - listens on port 9004
 - **Protocol**: DBGp over TCP socket
 - **Port**: 9004 (conflict-free with IDEs that use 9003)
 
-### Common Connection Failures
-
-**❌ Wrong Order:**
-```bash
-./bin/xstep script.php    # Script runs and exits
-php test_new_xdebug_debug.php &  # Too late - no connection
-```
-
-**✅ Correct Order:**
-```bash
-php test_new_xdebug_debug.php &  # XdebugClient listening
-lsof -i :9004                    # Verify LISTEN state  
-./bin/xstep script.php    # Script connects to waiting client
-```
-
 ### Verification Steps
 
 **Successful Connection Indicators:**
-- XdebugClient shows: `[XdebugClient] Xdebug connected!`
+- Debug server shows: `[DebugServer] Xdebug connected!`
 - Script pauses at first line waiting for debugger commands
 - Breakpoints can be set and variables inspected
 
 **Failed Connection Indicators:**
 - Script executes immediately without pausing
-- No connection messages in XdebugClient output
-- `Address already in use` errors when starting XdebugClient
+- No connection messages in debug server output
+- `Address already in use` errors when starting the debug server
 
 ### Step Debugging vs Trace Analysis
 

breakpoint_test.php

@@ -26,6 +26,7 @@
         <exclude>
             <directory>src/Exceptions</directory>
             <file>src/prepend_filter.php</file>
+            <file>src/prepend_trace.php</file>
         </exclude>
     </source>
 </phpunit>

phpunit.xml

@@ -349,7 +349,7 @@ private function executeTargetScript(): void
                     // Local PHP command
                     $scriptName = basename($this->targetScript, '.php');
                     $traceFile = '/tmp/trace-%t-' . $scriptName . '.xt';
-                    $prependFilter = __DIR__ . '/../prepend_filter.php';
+                    $prependFilter = __DIR__ . '/prepend_trace.php';
 
                     // Get appropriate Xdebug flag (empty if already loaded)
                     $xdebugFlag = XdebugFinder::getXdebugFlag();
@@ -397,7 +397,7 @@ private function executeTargetScript(): void
                 // Default: simple script execution
                 $scriptName = basename($this->targetScript, '.php');
                 $traceFile = '/tmp/trace-%t-' . $scriptName . '.xt';
-                $prependFilter = __DIR__ . '/../prepend_filter.php';
+                $prependFilter = __DIR__ . '/prepend_trace.php';
 
                 // Get appropriate Xdebug flag (empty if already loaded)
                 $xdebugFlag = XdebugFinder::getXdebugFlag();

prepend_filter.php

@@ -7,12 +7,15 @@
 use function array_filter;
 use function array_map;
 use function array_values;
+use function dirname;
 use function explode;
 use function fnmatch;
+use function getenv;
 use function glob;
 use function in_array;
 use function is_array;
 use function is_dir;
+use function is_string;
 use function rtrim;
 use function str_replace;
 use function strlen;
@@ -63,6 +66,49 @@ public static function excludePaths(string $vendorPath, string|null $includeVend
         return $excludePaths;
     }
 
+    /**
+     * Locate the project's vendor directory relative to this package.
+     *
+     * Resolves against this class file (not the caller) so every auto-prepend
+     * script shares the same lookup. Handles both local development
+     * (project root) and Composer installs (vendor/koriym/xdebug-mcp).
+     * Returns null when no vendor directory exists.
+     */
+    public static function locateVendorDir(): string|null
+    {
+        $candidates = [
+            dirname(__DIR__, 2) . DIRECTORY_SEPARATOR . 'vendor',  // local dev: <root>/vendor
+            dirname(__DIR__, 5) . DIRECTORY_SEPARATOR . 'vendor',  // composer: vendor/koriym/xdebug-mcp/src/Utilities -> <root>/vendor
+        ];
+
+        foreach ($candidates as $candidate) {
+            if (is_dir($candidate)) {
+                return $candidate;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Resolve the include-vendor patterns from the environment.
+     *
+     * Honours XDEBUG_MCP_INCLUDE_VENDOR (primary) and COVERAGE_INCLUDE_VENDOR
+     * (legacy) so trace, profile and coverage tooling behave identically.
+     * Returns null when neither is set.
+     */
+    public static function includeVendorFromEnv(): string|null
+    {
+        foreach (['XDEBUG_MCP_INCLUDE_VENDOR', 'COVERAGE_INCLUDE_VENDOR'] as $name) {
+            $value = getenv($name);
+            if (is_string($value) && $value !== '') {
+                return $value;
+            }
+        }
+
+        return null;
+    }
+
     /** @param list<string>|string|null $patterns */
     public static function matchesPackage(string $packageName, array|string|null $patterns): bool
     {

src/DebugServer.php

@@ -13,7 +13,6 @@
 use function array_merge;
 use function array_unshift;
 use function count;
-use function dirname;
 use function escapeshellarg;
 use function explode;
 use function fclose;
@@ -108,7 +107,7 @@ public function executeTrace(string $targetFile, array $phpArgs = []): string
         echo "🔍 Tracing: $targetFile\n";
 
         // Build command with Xdebug trace enabled (detailed mode)
-        $prependFilter = dirname(__DIR__) . '/prepend_filter.php';
+        $prependFilter = __DIR__ . '/prepend_trace.php';
 
         // Get appropriate Xdebug flag (empty if already loaded)
         $xdebugFlag = XdebugFinder::getXdebugFlag();