Download the PHP package dpt/mcp-phpstan-warm without Composer

mcp-phpstan-warm

Stop paying PHPStan's cold-start tax on every edit. A warm-process MCP server that keeps a PHPStan worker alive via its built-in TCP worker protocol. Works with every MCP client.

FAQ

Why

PHPStan is one of the most useful tools in modern PHP — static analysis, type inference, dead code detection. It is also slow to start.

Every phpstan analyse foo.php pays the same toll: bootstrap, config parse, autoloader load, rule compilation. 1-3 seconds before a single check runs. For agents and validators that run PHPStan after every edit, that cold-start cost dominates wall time.

mcp-phpstan-warm uses PHPStan's own built-in worker subcommand — the same TCP worker protocol PHPStan uses internally for parallel analysis. First call boots the worker once. Every subsequent call reuses the live process.

Install

Makes mcp-phpstan-warm available on $PATH.

Requires PHP 8.2+. PHPStan ^2.0 is pulled as a real Composer dependency.

Use it

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Restart Claude. Ask: "Run PHPStan on src/Foo.php".

Cline / Continue / Cursor / Zed / any MCP client

Same command + args shape. The server speaks plain MCP over stdio — no client-specific glue.

Standalone

Reads MCP JSON-RPC on stdin, writes responses on stdout.

Tools exposed

phpstan_analyse

Analyse a PHP file with PHPStan.

Important: The file must be under one of the --paths declared at startup. PHPStan's worker fixes its analysed file set at boot — files outside that set will be rejected by the worker.

Returns:

• exit_code: 0 = no errors, 1 = errors found, -1 = internal error
• errors: list of PHPStan errors with file, line, message, and rule identifier
• warm_boot: true = worker reused (fast path), false = cold boot just completed

How it works

PHPStan ships a worker subcommand used internally for parallel analysis. It connects to a TCP server you open, sends a hello handshake, then waits for {"action":"analyse","files":[...]} requests and replies with {"action":"result","result":{errors,...}}.

mcp-phpstan-warm is that TCP server:

Three things worth knowing:

1. We are the TCP server, PHPStan is the client. stream_socket_server('tcp://127.0.0.1:0') opens on a random port; we pass it to phpstan worker --port=<N>. The worker dials us.

2. The analysed file set is fixed at boot. PHPStan's worker builds its dependency graph from the <paths> passed on the command line. Files outside those paths will fail or return dependency errors at analysis time. Pass all relevant paths via --paths=src,tests at startup.

3. Worker death is handled transparently. If proc_get_status() shows the worker died, the next phpstan_analyse call respawns it. The warm_boot: false flag in the response signals this happened.

FAQ

Does this replace vendor/bin/phpstan? No. Use it from MCP clients. For one-off CLI runs the regular binary is simpler.

Can I analyse multiple files at once? The current tool accepts one file per call. The underlying protocol supports "files":[...] arrays — multi-file support can be added as a separate tool.

Memory? The daemon sets memory_limit = -1. Idle worker ≈ 60-80MB resident depending on project size and PHPStan level.

Are ignoreErrors from my neon respected? Yes. At worker boot the daemon runs phpstan dump-parameters --json once to extract the project's ignoreErrors list and caches it. Every phpstan_analyse call filters worker results through that list — by identifier, message regex, or path glob — before returning errors to the MCP client. The output matches what phpstan analyse would show on the same file.

Does it survive PHPStan version updates? The TCP protocol (hello / analyse / result) is PHPStan's internal parallel transport — it's stable across patch versions. Pin a PHPStan version in your composer.json if you need determinism.

Why not just subprocess phpstan analyse and cache the result? You could. But you'd still pay the full cold-start on every cache miss (every new or modified file). The worker mode amortises that cost across the entire session.

Credits

• PHPStan by Ondřej Mirtes and contributors — the engine doing all the real work. If you ship PHP, sponsor him.
• Model Context Protocol by Anthropic — the protocol that makes this kind of tool integration possible.
• mcp/sdk — official PHP SDK, used here for stdio transport + tool discovery.

Related

• PHPStan docs — config, levels, extensions.
• PHPStan on Packagist — the upstream package.
• mcp-rector-warm — same warm-process pattern for Rector.
• mcp-phpunit-warm — same warm-process pattern for PHPUnit.
• claude-supertool — DPT's batched-ops Claude Code companion; integrates warm-process servers as validators.

License

Community License — see Digital Process Tools.