PHPackages codemonkey/spx-mcp-server - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Debugging & Profiling](/categories/debugging) 4. / 5. codemonkey/spx-mcp-server ActiveLibrary[Debugging & Profiling](/categories/debugging) codemonkey/spx-mcp-server ========================= An MCP server for the PHP SPX profiler v0.2.1(5mo ago)91.9kโ†“36.7%3MITPHPPHP ^8.1 Since Oct 6Pushed 5mo ago1 watchersCompare [ Source](https://github.com/MiniCodeMonkey/spx-mcp-server)[ Packagist](https://packagist.org/packages/codemonkey/spx-mcp-server)[ RSS](/packages/codemonkey-spx-mcp-server/feed)WikiDiscussions main Synced 2d ago READMEChangelog (2)Dependencies (2)Versions (4)Used By (0) Experimental PHP SPX MCP Server ๐Ÿš€ ================================= [](#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://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)[![PHP Version](https://camo.githubusercontent.com/cc9cdea9aa96b40a822425e981b0a030e3371202973c7d57b74e8e99834f81dc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c7565)](https://camo.githubusercontent.com/cc9cdea9aa96b40a822425e981b0a030e3371202973c7d57b74e8e99834f81dc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c7565) ๐ŸŽฏ What is This? --------------- [](#-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 ---------------- [](#๏ธ-prerequisites) ### PHP SPX Extension [](#php-spx-extension) You must have the PHP SPX extension installed and configured. Please refer to the official installation instructions at: **** **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: ``` extension=spx.so spx.data_dir="/tmp/spx" ``` ๐Ÿ“ฆ Installation -------------- [](#-installation) Install the SPX MCP Server via Composer in your Laravel project: ``` composer require codemonkey/spx-mcp-server --dev ``` โš™๏ธ Configuration ---------------- [](#๏ธ-configuration) ### Configure with Claude Code [](#configure-with-claude-code) The easiest way to configure the MCP server with Claude Code is using the built-in installation command: ``` php artisan spx-mcp:install ``` This will automatically add the SPX MCP server to your Claude Code configuration. ### Manual Configuration [](#manual-configuration) Alternatively, you can manually add the server to your Claude Code configuration file (`~/.config/claude-code/config.json`): ``` { "mcpServers": { "spx-mcp": { "command": "php", "args": ["artisan", "spx-mcp:start"], "cwd": "/path/to/your/laravel/project" } } } ``` ### Environment Variables [](#environment-variables) You can customize the SPX MCP server behavior using environment variables in your `.env` file: ``` # 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: ``` php artisan vendor:publish --tag=spx-mcp-config ``` ๐ŸŽฎ Usage ------- [](#-usage) ### 1. Generate SPX Profiles [](#1-generate-spx-profiles) Generate performance profiles by triggering SPX during your application requests. Add the SPX trigger to your request URL: ``` # 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 [](#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 --------------------- [](#-available-mcp-tools) The SPX MCP server provides the following analysis tools: ToolDescription`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 ------------------ [](#-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 --------------- [](#๏ธ-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 ------------- [](#-development) ### Running Tests [](#running-tests) ``` ./vendor/bin/pest ``` ### Project Structure [](#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 ----------------- [](#-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 --------- [](#-license) This package is open-sourced software licensed under the [MIT license](LICENSE). ๐Ÿ™ Credits --------- [](#-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 -------------- [](#-contributing) Contributions are welcome! Please feel free to submit a Pull Request. --- Made with โค๏ธ by developers who hate performance issues ### Health Score 39 โ€” LowBetter than 84% of packages Maintenance72 Regular maintenance activity Popularity29 Limited adoption so far Community11 Small or concentrated contributor base Maturity36 Early-stage or recently created project Bus Factor1 Top contributor holds 80% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~56 days Total 3 Last Release 158d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/220535?v=4)[Mathias Hansen](/maintainers/MiniCodeMonkey)[@MiniCodeMonkey](https://github.com/MiniCodeMonkey) --- Top Contributors [![MiniCodeMonkey](https://avatars.githubusercontent.com/u/220535?v=4)](https://github.com/MiniCodeMonkey "MiniCodeMonkey (8 commits)")[![sixlive](https://avatars.githubusercontent.com/u/5108034?v=4)](https://github.com/sixlive "sixlive (2 commits)") ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/codemonkey-spx-mcp-server/health.svg) ``` [![Health](https://phpackages.com/badges/codemonkey-spx-mcp-server/health.svg)](https://phpackages.com/packages/codemonkey-spx-mcp-server) ``` ### Alternatives [laravel/boost Laravel Boost accelerates AI-assisted development by providing the essential context and structure that AI needs to generate high-quality, Laravel-specific code. 3.5k21.5M593](/packages/laravel-boost)[binaryk/laravel-restify Laravel REST API helpers 677415.0k](/packages/binaryk-laravel-restify)[cboxdk/statamic-mcp MCP (Model Context Protocol) server for Statamic CMS v6 โ€” gives AI assistants structured access to content, blueprints, assets, and more. 3114.5k](/packages/cboxdk-statamic-mcp)[lucianotonet/laravel-telescope-mcp MCP Server extension for Laravel Telescope 2027.2k](/packages/lucianotonet-laravel-telescope-mcp) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)