README

An MCP server that exposes php-spx profiling reports to LLM agents.

It gives an assistant read access to those profiles so it can list them, read a report's metadata, walk its call graph, get a flat per-function profile, and trace a function's callers directly from the conversation, instead of through the SPX web UI.

Important

Only the SPX v0.5 report format is supported.

How it works

php-spx writes one report per profiled request/command to a data directory: a <key>.json metadata sidecar plus a compressed body (<key>.txt.gz or <key>.txt.zst). This server reads that directory and serves the reports over MCP's stdio transport. It reads the reports; it does not modify them.

Requirements

• PHP >= 8.3
• ext-zlib (to read .txt.gz reports)
• ext-zstd (optional, only to read .txt.zst reports)
• A directory of php-spx reports to read

Installation

Install a standalone, runnable copy with Composer:

composer create-project noisebynorthwest/php-spx-mcp

This creates a php-spx-mcp/ directory with dependencies installed; its bin/server.php is the entry point referenced below.

Alternatively, clone the repository:

git clone https://github.com/NoiseByNorthwest/php-spx-mcp.git
cd php-spx-mcp
composer install --no-dev

Configuration

The server reads reports from the directory given by the SPX_DATA_DIR environment variable, defaulting to /tmp/spx. Point it at the directory where php-spx stores its reports.

Register the server with your MCP client (stdio transport). For example:

{
  "mcpServers": {
    "php-spx": {
      "command": "php",
      "args": ["/absolute/path/to/php-spx-mcp/bin/server.php"],
      "env": {
        "SPX_DATA_DIR": "/tmp/spx"
      }
    }
  }
}

Tools

find_reports

Find reports with server-side filters, returning their essential metadata so a follow-up get_report_metadata call is usually unnecessary.

Returns a list of { key, timestamp, descriptor, wall_time_ms }, most recent first. descriptor is the request URI or CLI command line, depending on the report.

get_report_metadata

Get the full metadata for a report (enabled metrics, URL/command, duration, memory, etc.).

get_aggregated_call_graph

Get the aggregated, pruned call graph for a report.

Children are sorted by value descending, and every non-root node carries its source location (file, lineNumber).

Zooming with root_stack

The full graph can be large. To focus on a subtree, pass root_stack, the path of calls from the root down to the call you want to re-root on. Each entry is a function name as shown in the graph:

[
  "/usr/local/bin/composer",
  "phar:///usr/local/bin/composer/bin/composer",
  "Composer\\Autoload\\ClassLoader::loadClass"
]

A function name uniquely identifies a function, so an entry matching several calls under the current node is rejected.

The result is re-rooted on the call the path lands on, and pruning then applies relative to that subtree's own value, so pruning_relative_threshold: 0.01 after zooming means "drop calls below 1% of the focused call".

get_flat_profile

Get the flat profile: per-function metric totals aggregated across all call contexts, sorted by exclusive (self) metric descending. This surfaces functions that are cheap individually but expensive across many call sites, which the call graph spreads across separate nodes.

Each entry reports { name, file, lineNumber, calls, exclusive, exclusiveRelative, inclusive, inclusiveRelative }. Exclusive is a function's own metric (excluding callees); inclusive includes callees. Both stay correct under recursion: inclusive counts only the outermost frame of a recursive chain.

get_callers

Get the inverted (callers) call graph anchored on a function: starting from the function, walk up through its callers to the entry point, attributing to each caller path the share of the function's metric flowing through it. The bottom-up counterpart of get_aggregated_call_graph, used to find who is responsible for a function flagged by get_flat_profile.

The inverted root's value equals the function's inclusive total from get_flat_profile.

Metrics

The metric parameter accepts any of the metrics SPX can emit. Only metrics actually recorded in the targeted report are valid; the rest are rejected per report.

Dev

Install dependencies

composer install 

Apply CS Fixer fixes

composer cs-fix

QA

composer phpcs && composer cs-check && composer phpstan && ./vendor/bin/phpunit

License

MIT