# SPX MCP Server

Web-only MCP server for `php-spx` reports. It calls the embedded SPX web endpoints, parses the full report, and returns LLM-sized JSON summaries instead of raw event streams.

## Prerequisites

- Node.js 20 or newer
- An application with the `spx` PHP extension enabled for HTTP profiling
- SPX HTTP access configured, for example:

```ini
spx.http_enabled=1
spx.http_key="dev"
spx.http_ip_whitelist="127.0.0.1"
```

## Build

```bash
npm install
npm run build
```

The built stdio entry point is:

```text
/path/to/spx-mcp-server/dist/index.js
```

Set these environment variables in your agent config, or pass them per tool call:

```text
SPX_BASE_URL=http://localhost
SPX_KEY=dev
```

## Install In Codex CLI

Edit `~/.codex/config.toml` and add:

```toml
[mcp_servers.spx]
command = "node"
args = ["/path/to/spx-mcp-server/dist/index.js"]
env = { SPX_BASE_URL = "http://localhost", SPX_KEY = "dev" }
```

Restart Codex CLI after editing the file.

## Install In Claude Code

Local project config:

```bash
claude mcp add --transport stdio --scope project \
  --env SPX_BASE_URL=http://localhost \
  --env SPX_KEY=dev \
  spx -- node /path/to/spx-mcp-server/dist/index.js
```

User-wide config:

```bash
claude mcp add --transport stdio --scope user \
  --env SPX_BASE_URL=http://localhost \
  --env SPX_KEY=dev \
  spx -- node /path/to/spx-mcp-server/dist/index.js
```

Verify:

```bash
claude mcp list
claude mcp get spx
```

Equivalent `.mcp.json` project config:

```json
{
  "mcpServers": {
    "spx": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/spx-mcp-server/dist/index.js"],
      "env": {
        "SPX_BASE_URL": "http://localhost",
        "SPX_KEY": "dev"
      }
    }
  }
}
```

## Install In Cline

Cline is a popular open-source VS Code agent with MCP support.

For Cline CLI, run:

```bash
cline mcp
```

Then add a local stdio server with:

```text
name: spx
command: node
args: /path/to/spx-mcp-server/dist/index.js
env:
  SPX_BASE_URL=http://localhost
  SPX_KEY=dev
```

For the VS Code extension, open the Cline MCP Servers settings and add this JSON:

```json
{
  "mcpServers": {
    "spx": {
      "command": "node",
      "args": ["/path/to/spx-mcp-server/dist/index.js"],
      "env": {
        "SPX_BASE_URL": "http://localhost",
        "SPX_KEY": "dev"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

## Install In OpenClaw

OpenClaw is an open-source personal agent/gateway that can manage outbound MCP servers under `mcp.servers`.

Edit `~/.openclaw/openclaw.json` or the file pointed to by `OPENCLAW_CONFIG_PATH`:

```json5
{
  mcp: {
    servers: {
      spx: {
        command: "node",
        args: ["/path/to/spx-mcp-server/dist/index.js"],
        env: {
          SPX_BASE_URL: "http://localhost",
          SPX_KEY: "dev",
        },
      },
    },
  },
}
```

Check the saved config:

```bash
openclaw mcp status --verbose
openclaw mcp probe spx
```

## Basic Workflow

1. Call `profile_url` for the web URL you want to profile.
2. Call `list_reports`.
3. Pick the newest matching report.
4. Call `analyze_report` or `get_hot_paths`.

## Tools

- `profile_url`: sends one HTTP request with SPX cookies enabled.
- `list_reports`: reads `?SPX_UI_URI=/data/reports/metadata`.
- `get_report_metadata`: reads one report metadata JSON.
- `analyze_report`: downloads and parses `?SPX_UI_URI=/data/reports/get/<key>`.
- `get_hot_paths`: returns the most expensive call paths.
- `get_function_profile`: returns one function's aggregate and callers/callees.
- `get_raw_events`: returns a paginated debug slice of raw events.

The analyzer limits output by default. Large SPX reports can contain millions of events, so full raw report output is intentionally not exposed as a normal tool result. `get_raw_events` is capped at 1000 events per call and is intended for debugging parser or analyzer behavior.

## References

- Claude Code MCP configuration: https://code.claude.com/docs/en/mcp
- Cline MCP configuration: https://github.com/cline/cline/blob/main/docs/mcp/mcp-overview.mdx
- OpenClaw MCP configuration: https://docs.openclaw.ai/gateway/configuration-reference