feat: Feature complete

Author: MiniCodeMonkey

README.md

@@ -0,0 +1,244 @@
+# Experimental PHP SPX MCP Server 🚀
+
+An MCP (Model Context Protocol) server for **Laravel applications** that brings the power of [PHP SPX profiler](https://github.com/NoiseByNorthwest/php-spx) to Claude Code. Analyze PHP application performance with AI assistance, getting intelligent insights into bottlenecks, memory usage, database queries, and more.
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![PHP Version](https://img.shields.io/badge/php-%5E8.1-blue)
+
+## 🎯 What is This?
+
+The PHP SPX MCP Server is a bridge between the powerful PHP SPX profiler and Claude Code (or any MCP-compatible AI client). It enables you to:
+
+- 🔍 **Analyze performance profiles** with natural language queries
+- 📊 **Get AI-powered insights** into bottlenecks and optimization opportunities
+- 🎯 **Identify N+1 queries**, memory leaks, and slow functions automatically
+- 📈 **Visualize call trees**, execution timelines, and middleware chains
+- 💡 **Receive actionable recommendations** for performance improvements
+
+Instead of manually digging through profiler data, simply ask Claude: *"What's causing the slowest response times?"* or *"Are there any N+1 query issues?"*
+
+## 🛠️ Prerequisites
+
+### PHP SPX Extension
+
+You must have the PHP SPX extension installed and configured. Please refer to the official installation instructions at:
+
+**[https://github.com/NoiseByNorthwest/php-spx](https://github.com/NoiseByNorthwest/php-spx)**
+
+**Important:** Make sure to configure the `spx.data_dir` setting in your `php.ini`. This is where SPX will store profile data, and the MCP server needs to read from this location.
+
+Example configuration:
+```ini
+extension=spx.so
+spx.data_dir="/tmp/spx"
+```
+
+## 📦 Installation
+
+Install the SPX MCP Server via Composer in your Laravel project:
+
+```bash
+composer require codemonkey/spx-mcp-server --dev
+```
+
+## ⚙️ Configuration
+
+### Configure with Claude Code
+
+The easiest way to configure the MCP server with Claude Code is using the built-in installation command:
+
+```bash
+php artisan spx-mcp:install
+```
+
+This will automatically add the SPX MCP server to your Claude Code configuration.
+
+### Manual Configuration
+
+Alternatively, you can manually add the server to your Claude Code configuration file (`~/.config/claude-code/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "spx-mcp": {
+      "command": "php",
+      "args": ["artisan", "spx-mcp:start"],
+      "cwd": "/path/to/your/laravel/project"
+    }
+  }
+}
+```
+
+### Environment Variables
+
+You can customize the SPX MCP server behavior using environment variables in your `.env` file:
+
+```env
+# Enable/disable the SPX MCP server
+SPX_MCP_ENABLED=true
+
+# SPX data directory (should match your php.ini configuration)
+SPX_DATA_DIR=/tmp/spx
+```
+
+You can also publish the configuration file for more control:
+
+```bash
+php artisan vendor:publish --tag=spx-mcp-config
+```
+
+## 🎮 Usage
+
+### 1. Generate SPX Profiles
+
+Generate performance profiles by triggering SPX during your application requests. Add the SPX trigger to your request URL:
+
+```bash
+# Using the default key "dev"
+curl "http://your-app.test/your-endpoint?SPX_KEY=dev&SPX_UI_URI=/"
+```
+
+Or use the SPX web UI to control profiling: `http://your-app.test/?SPX_KEY=dev&SPX_UI_URI=/`
+
+Profiles will be saved to your configured `spx.data_dir`.
+
+### 2. Analyze with Claude Code
+
+Once you have generated profiles, open Claude Code and start asking questions:
+
+**Example queries:**
+
+- *"List all available SPX profiles"*
+- *"Analyze the latest profile and show me the slowest functions"*
+- *"Are there any N+1 database query issues?"*
+- *"What middleware is taking the most time?"*
+- *"Show me the call tree for the most recent profile"*
+- *"Which third-party packages are impacting performance?"*
+- *"Find any recursive functions and their overhead"*
+- *"What's the wall time vs CPU time distribution?"*
+
+Claude will use the MCP tools to parse your SPX profiles and provide intelligent analysis and recommendations.
+
+## 🧰 Available MCP Tools
+
+The SPX MCP server provides the following analysis tools:
+
+| Tool | Description |
+|------|-------------|
+| `list_profiles` | List all available SPX profiles |
+| `get_slowest_functions` | Get functions with highest exclusive execution time |
+| `get_most_called_functions` | Get most frequently called functions |
+| `get_memory_hogs` | Get functions using the most memory |
+| `get_cpu_intensive_functions` | Get CPU-intensive functions |
+| `get_call_tree` | Get hierarchical call tree structure |
+| `get_timeline_view` | Get chronological execution timeline |
+| `get_recursive_functions` | Identify recursive function calls |
+| `get_wall_time_distribution` | Analyze I/O vs CPU time distribution |
+| `get_autoloading_overhead` | Analyze autoloading performance impact |
+| `get_third_party_package_impact` | Analyze third-party package performance |
+| `get_database_queries` | Analyze database operations and detect N+1 queries |
+| `get_redis_operations` | Analyze Redis/cache operations |
+| `get_io_operations` | Analyze file, network, and socket I/O |
+| `get_middleware_analysis` | Analyze middleware execution order and timing |
+
+## 📊 Example Analysis
+
+```
+You: "Analyze the latest profile for performance issues"
+
+Claude: I've analyzed your latest profile. Here are the key findings:
+
+🔴 Critical Issues:
+1. N+1 Query Detected: User::with('posts') is executing 156 queries
+   - Location: UserController::index
+   - Impact: 2.3s of database time
+   - Fix: Use eager loading with constraints
+
+2. Slow Function: ImageProcessor::resize
+   - Exclusive time: 1.8s
+   - Called: 45 times
+   - Recommendation: Consider async processing or caching
+
+🟡 Optimization Opportunities:
+1. Autoloading overhead: 340ms across 89 class loads
+   - Consider using composer dump-autoload -o
+
+2. Middleware: AuthMiddleware taking 180ms
+   - Session queries could be cached
+
+📈 Overall Stats:
+- Total execution time: 4.2s
+- Peak memory: 45MB
+- Total function calls: 12,847
+```
+
+## 🏗️ How It Works
+
+1. **Profile Generation**: PHP SPX profiles your application and stores detailed execution traces
+2. **Profile Parsing**: The MCP server reads and parses SPX profile files (compressed `.txt.gz` format)
+3. **Data Analysis**: Profiles are analyzed to extract metrics like execution time, memory, call counts, etc.
+4. **MCP Tools**: Analysis results are exposed as MCP tools that Claude can invoke
+5. **AI Insights**: Claude uses the tools to answer your questions and provide recommendations
+
+## 🔧 Development
+
+### Running Tests
+
+```bash
+./vendor/bin/pest
+```
+
+### Project Structure
+
+```
+spx-mcp-server/
+├── src/
+│   ├── Mcp/
+│   │   ├── SPX/
+│   │   │   └── ProfileParser.php    # Core profile parsing logic
+│   │   ├── Tools/                    # Individual MCP tools
+│   │   └── McpServer.php             # MCP server implementation
+│   ├── Console/
+│   │   ├── StartCommand.php          # Start MCP server command
+│   │   └── InstallCommand.php        # Installation helper
+│   └── SPXMcpServiceProvider.php     # Laravel service provider
+├── config/
+│   └── spx-mcp.php                   # Configuration file
+└── tests/                             # Test suite
+```
+
+## 🐛 Troubleshooting
+
+**SPX profiles not being created?**
+- Verify SPX is installed: `php -m | grep spx`
+- Check your `php.ini` configuration
+- Ensure `spx.data_dir` is configured and writable
+- Refer to [PHP SPX documentation](https://github.com/NoiseByNorthwest/php-spx)
+
+**MCP server not connecting?**
+- Verify the path in your Claude Code config is correct
+- Check that the server starts: `php artisan spx-mcp:start`
+- Review logs in `storage/logs/laravel.log`
+
+**No profiles showing in Claude?**
+- Verify profiles exist in your SPX data directory
+- Check the `SPX_DATA_DIR` environment variable matches your `php.ini` setting
+- Ensure profiles have `.txt.gz` extension
+
+## 📝 License
+
+This package is open-sourced software licensed under the [MIT license](LICENSE).
+
+## 🙏 Credits
+
+- Built on [PHP SPX](https://github.com/NoiseByNorthwest/php-spx) by NoiseByNorthwest
+- Uses Laravel's [MCP package](https://github.com/laravel/mcp)
+- Created by [Mathias Hansen](https://codemonkey.io)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+Made with ❤️ by developers who hate performance issues

src/Mcp/SPX/ProfileParser.php

@@ -15,12 +15,19 @@ class ProfileParser
     private array $recursionTracking = [];
 
     /**
-     * @param array $enabledMetrics Associative array of metric_key => bool from JSON metadata
+     * @param array $enabledMetrics Array of metric names or associative array of metric_key => bool from JSON metadata
      */
     public function __construct(array $enabledMetrics)
     {
         ini_set('memory_limit', '-1');
-        $this->metrics = array_keys(array_filter($enabledMetrics));
+        // Handle both plain array ["wt", "ct", ...] and associative array ["wt" => true, "ct" => false, ...]
+        if (array_keys($enabledMetrics) === range(0, count($enabledMetrics) - 1)) {
+            // Plain array - use directly
+            $this->metrics = $enabledMetrics;
+        } else {
+            // Associative array - filter and extract keys
+            $this->metrics = array_keys(array_filter($enabledMetrics));
+        }
     }
 
     protected function log(string $line): void
@@ -200,9 +207,10 @@ private function calculateStats(): void
                 }
 
                 // Calculate inclusive metrics (total time/memory in function)
-                $wallTime = ($event['metrics']['wt'] ?? 0) - ($frame['start_metrics']['wt'] ?? 0);
+                // Note: SPX metrics are in nanoseconds, convert to microseconds
+                $wallTime = (($event['metrics']['wt'] ?? 0) - ($frame['start_metrics']['wt'] ?? 0)) / 1000;
                 $memory = ($event['metrics']['mu'] ?? 0) - ($frame['start_metrics']['mu'] ?? 0);
-                $cpuTime = ($event['metrics']['ct'] ?? 0) - ($frame['start_metrics']['ct'] ?? 0);
+                $cpuTime = (($event['metrics']['ct'] ?? 0) - ($frame['start_metrics']['ct'] ?? 0)) / 1000;
 
                 $this->functionStats[$funcIdx]['inclusive_time'] += $wallTime;
                 $this->functionStats[$funcIdx]['inclusive_memory'] += $memory;
@@ -223,7 +231,7 @@ private function calculateStats(): void
 
                 // Update recursion tracking
                 if (isset($this->recursionTracking[$funcIdx])) {
-                    $this->recursionTracking[$funcIdx]['total_time'] += $wallTime;
+                    $this->recursionTracking[$funcIdx]['total_time'] += $exclusiveTime;
                 }
 
                 // Timeline entry
@@ -244,6 +252,17 @@ private function calculateStats(): void
                     $callStack[$parentIdx]['children_time'] += $wallTime;
                     $callStack[$parentIdx]['children_memory'] += $memory;
                     $callStack[$parentIdx]['children_cpu'] += $cpuTime;
+
+                    // Handle recursion: subtract exclusive time from recursive parent's children
+                    // This prevents double-counting in recursive scenarios
+                    for ($k = count($callStack) - 1; $k >= 0; $k--) {
+                        if ($callStack[$k]['func_idx'] === $funcIdx) {
+                            $callStack[$k]['children_time'] -= $exclusiveTime;
+                            $callStack[$k]['children_memory'] -= $exclusiveMemory;
+                            $callStack[$k]['children_cpu'] -= $exclusiveCpu;
+                            break;
+                        }
+                    }
                 }
             }
         }
@@ -505,7 +524,7 @@ public function getAutoloadingOverhead(): array
                 strpos($funcName, 'require') !== false ||
                 strpos($funcName, 'spl_autoload_call') !== false) {
 
-                $autoloadStats['total_time'] += $stat['inclusive_time'];
+                $autoloadStats['total_time'] += $stat['exclusive_time'];
                 $autoloadStats['total_calls'] += $stat['call_count'];
                 $autoloadStats['functions'][] = $stat;
             }
@@ -542,7 +561,7 @@ public function getThirdPartyPackageImpact(): array
                     ];
                 }
 
-                $packages[$package]['total_time'] += $stat['inclusive_time'];
+                $packages[$package]['total_time'] += $stat['exclusive_time'];
                 $packages[$package]['total_calls'] += $stat['call_count'];
                 $packages[$package]['functions'][] = $stat;
             }
@@ -582,7 +601,7 @@ public function getDatabaseQueries(): array
                 strpos($funcName, 'PDO::') !== false ||
                 strpos($funcName, 'mysqli') !== false) {
 
-                $queries['total_time'] += $stat['inclusive_time'];
+                $queries['total_time'] += $stat['exclusive_time'];
                 $queries['total_queries'] += $stat['call_count'];
 
                 // Categorize by operation type
@@ -633,7 +652,7 @@ public function getRedisOperations(): array
                 stripos($funcName, 'Cache\\RedisStore') !== false ||
                 stripos($funcName, 'Predis') !== false) {
 
-                $redis['total_time'] += $stat['inclusive_time'];
+                $redis['total_time'] += $stat['exclusive_time'];
                 $redis['total_operations'] += $stat['call_count'];
 
                 // Categorize by operation type
@@ -682,22 +701,22 @@ public function getIOOperations(): array
 
             // File I/O
             if (preg_match('/^(file_|fread|fwrite|fopen|fclose|file_get_contents|file_put_contents|readfile|is_file|is_dir|scandir|glob)/i', $funcName)) {
-                $io['file']['total_time'] += $stat['inclusive_time'];
+                $io['file']['total_time'] += $stat['exclusive_time'];
                 $io['file']['total_operations'] += $stat['call_count'];
                 $io['file']['functions'][] = $stat;
             } // Network I/O
             elseif (stripos($funcName, 'curl_') !== false ||
                 stripos($funcName, 'http') !== false ||
                 stripos($funcName, 'guzzle') !== false ||
                 stripos($funcName, 'RPC::call') !== false) {
-                $io['network']['total_time'] += $stat['inclusive_time'];
+                $io['network']['total_time'] += $stat['exclusive_time'];
                 $io['network']['total_operations'] += $stat['call_count'];
                 $io['network']['functions'][] = $stat;
             } // Socket I/O
             elseif (stripos($funcName, 'socket_') !== false ||
                 stripos($funcName, 'SocketRelay') !== false ||
                 stripos($funcName, 'stream_socket') !== false) {
-                $io['socket']['total_time'] += $stat['inclusive_time'];
+                $io['socket']['total_time'] += $stat['exclusive_time'];
                 $io['socket']['total_operations'] += $stat['call_count'];
                 $io['socket']['functions'][] = $stat;
             }
@@ -752,9 +771,9 @@ public function getMiddlewareAnalysis(): array
                 // Find corresponding function stats
                 if (isset($this->functionStats[$entry['func_idx']])) {
                     $stat = $this->functionStats[$entry['func_idx']];
-                    $middleware['middleware_list'][$middlewareName]['total_time'] += $stat['inclusive_time'];
+                    $middleware['middleware_list'][$middlewareName]['total_time'] += $stat['exclusive_time'];
                     $middleware['middleware_list'][$middlewareName]['call_count'] += $stat['call_count'];
-                    $middleware['total_time'] += $stat['inclusive_time'];
+                    $middleware['total_time'] += $stat['exclusive_time'];
                     $middleware['total_calls'] += $stat['call_count'];
                 }
 

src/Mcp/Tools/GetAutoloadingOverhead.php

@@ -36,10 +36,10 @@ public function handle(Request $request): Response
 
         foreach (array_slice($autoloadStats['functions'], 0, $limit) as $func) {
             $output .= sprintf("  %s\n", substr($func['name'], 0, 50));
-            $output .= sprintf("    Time: %s\n", $this->formatTime($func['inclusive_time']));
+            $output .= sprintf("    Time: %s\n", $this->formatTime($func['exclusive_time']));
             $output .= sprintf("    Calls: %d\n", $func['call_count']);
             if ($func['call_count'] > 0) {
-                $output .= sprintf("    Avg: %s\n", $this->formatTime($func['inclusive_time'] / $func['call_count']));
+                $output .= sprintf("    Avg: %s\n", $this->formatTime($func['exclusive_time'] / $func['call_count']));
             }
             $output .= "\n";
         }