PHPocalypse

PHPocalypse-MCP provides an MCP server that lets you run PHP quality checks and unit tests on demand for vibe PHP projects. It wires standard tools like PHP-CS-Fixer, PHPStan, and PHPUnit into an MCP workflow so you can trigger checks from your MCP client without manually running multiple commands.

How to use

You connect to the MCP server from your MCP client and trigger predefined tools to run against your PHP project. Tools execute in sequence or on demand depending on how you configure your MCP client. The server is designed to avoid interactive prompts and focuses on producing meaningful output that your client can surface.

With the standard MCP config you point the client to run a local (stdio) server command that boots the MCP runner and points it at your project config. You will see tool results, including any PHP-CS-Fixer formatting, PHPStan analysis results, and unit test outcomes, surfaced to your MCP client.

How to install

Prerequisites you need to have installed on your system are: node, npx and tsx.

Step 1. Clone the project into your chosen directory.

Step 2. Install dependencies.

Step 3. Create the MCP config inside your Cursor (or MCP client) settings using the following snippet.

{
  "mcpServers": {
    "phpocalypse_mcp": {
      "command": "npx",
      "args": ["tsx", "/Absolute/Path/To/PHPocalypse-MCP/src/index.ts", "--config", "/Absolute/Path/To/Your/PHP/Based/Project/phpocalypse-mcp.yaml"]
    }
  }
}

Additional configuration you will need

In your PHP project, create a file named phpocalypse-mcp.yaml. This file defines the tools you want the MCP server to run against your project.

tools:
  - name: php-cs-fixer
    command: make php-cs

  - name: php-stan
    command: /vendor/bin/phpstan analyse -c phpstan.neon --memory-limit=-1

  - name: tests-unit
    command: docker compose run --rm php ./vendor/bin/phpunit --testsuite=Unit

  - name: tests-behat
    command: task behat -- --no-interaction

Caveats and notes

This MCP is a proof of concept and may not work in every scenario. Interactive CLI input, such as prompts for missing snippets in certain tools, will not be supported. If a tool requires user input, ensure it runs in a non-interactive mode and outputs meaningful results instead.

Some outputs can be large and may not be handled perfectly yet. If you encounter issues, try refining the tool commands to produce more compact output.

Available tools

php-cs-fixer

Runs PHP-CS-Fixer to automatically format PHP code according to configured rules.

php-stan

Invokes PHPStan to perform static analysis on the PHP project using a specific configuration.

tests-unit

Runs the unit test suite via Docker Compose, executing unit tests defined in PHPUnit.

tests-behat

Executes Behat tests in non-interactive mode to validate behavior.