mcp-rector-warm

Rector is great. Its cold start is not. Every rector process boots Rector from scratch before a single rule fires, on every file. Keep Rector warm and pay that boot once. Same output as cold. up to 10× faster per file on Laravel and Symfony.

Two ways in, one warm engine:

• an MCP server that gives your AI agent a fast Rector;
• a language server that puts Rector's fixes in your editor.

Who it's for • Get started • AI agent • Editor • Validation loop • Numbers • Docs

---

Who it's for

You…	You get	Use
let an AI agent refactor PHP	Rector as a tool your agent calls after every edit	MCP server
want Rector in your editor	Rector's fixes flagged as you type, one click to apply	Language server
run Rector in a validation loop	A warm Rector you call file by file, without paying the boot each time	MCP server

Both ship in one package. Run one, or both side by side.

Same answers. Just faster.

• Up to 10× faster per file on Laravel and Symfony, at the median.
• Identical output. Every warm answer in the benchmark was byte-identical to a cold rector process, and CI checks warm output against a fresh cold Rector run.
• Keep cold Rector in your CI. Warm is editor feedback: fast, and built to match cold. Keep vendor/bin/rector process --dry-run in CI as the gate, the same as without this tool.
• One-time boot. The first call boots Rector, once per server. An idle server costs nothing.
• Edit rector.php freely. Config changes apply on the next call. No restart.

The fastest mode is on by default: a long-lived session child keeps Rector's analysis warm between calls (numbers, what it watches). Set MCP_RECTOR_WARM_SESSION=0 to turn it off. Every write -- rector_process with dryRun: false, an LSP code action, rector-warm.fixWorkspace -- always forks fresh from a pristine worker, never the session, whatever it's set to.

Get started

composer global require dpt/mcp-rector-warm

That's the install. PHP 8.2+, Rector ^2.4 comes along as a normal Composer dependency. Now pick where Rector should run.

Rector in your AI agent

For: anyone who lets Claude, Copilot agent mode, Cursor, Cline or another agent refactor PHP.

• Your agent can run Rector after every edit, without waiting for Rector to boot each time -- automatically with Claude Code via supertool (below), on request with any other client.
• Preview first. The agent sees the diff; files change only when it asks to write.
• Stays inside your project. Paths outside the working directory are refused.
• Any MCP client. Claude Desktop, VS Code, Cursor, Cline, Continue, Zed.

With Claude Code (recommended)

Plain MCP has a gap: the agent has to remember to call rector_process, and in practice it forgets, or calls it only at the end. claude-supertool closes that gap -- its rector-mcp validator runs this server after every edit made through a supertool op, and puts the result in the edit's own output, so "runs Rector after every edit" is a fact about the tool instead of a hope about the agent.

Install the plugin, once per machine:

/plugin marketplace add Digital-Process-Tools/claude-marketplace
/plugin install supertool@dpt-plugins

Restart your Claude Code session afterward -- the plugin's hook only registers at session start.

Then, as a project dependency -- not the global install above, since .supertool.json below points at vendor/bin/:

composer require --dev dpt/mcp-rector-warm

and a minimal .supertool.json:

{
  "presets": ["mcp"],
  "mcp": {
    "rector-warm": {
      "cmd": ["vendor/bin/mcp-rector-warm", "--config=rector.php"],
      "match": "*.php",
      "timeout": 120,
      "idle_timeout": 1800
    }
  },
  "validators": {
    "rector": {
      "cmd": "MCP_RECTOR_CONFIG=rector.php MCP_RECTOR_BIN=vendor/bin/mcp-rector-warm {python} {supertool_dir}/validators/rector-mcp/rector-mcp.py {file}",
      "match": "*.php",
      "hooks_into": ["edit", "replace", "replace_lines", "paste", "vim"],
      "mcp_autospawn": true,
      "timeout": 120
    }
  }
}

mcp_autospawn: true lets the validator start the warm daemon itself on first use, so there is nothing to register as a separate MCP server. After an edit to a PHP file, supertool's own output carries a [validators] block with either rector-mcp : ok or the Rector finding, right where the edit happened:

[validators]
rector-mcp  : 1 err       (5.6s)
     rector.refactor  Would apply ReadOnlyPropertyRector

The honest caveat: this only fires on an edit made through one of supertool's own mutating ops (edit, paste, replace, replace_lines, vim) -- not through Claude Code's built-in Edit/Write tools, which write to disk with no validator and no rollback. To make supertool the only edit route, deny the native tools in the project's .claude/settings.json:

{
  "permissions": {
    "deny": ["Edit", "Write", "MultiEdit", "NotebookEdit"]
  }
}

That is a project decision, not something this server or supertool does for you -- see claude-supertool's README, "Hard-block native tools", for the full list (it also covers the raw shell commands supertool replaces) and the headless-session equivalent.

Full supertool setup →, including the optional phpstan validator (backed by mcp-phpstan-warm) alongside this one.

Any other MCP client

Add it to Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "rector": {
      "command": "mcp-rector-warm",
      "args": [
        "--working-dir=/path/to/your/project",
        "--config=/path/to/your/project/rector.php"
      ]
    }
  }
}

Restart Claude and ask: "Run Rector on src/Foo.php". Done.

Full setup → VS Code and other clients, the rector_process tool, timeouts.

Rector in your editor

For: PHP developers who want Rector's suggestions where they write code, not in a terminal afterwards.

• Fixes appear as you type, on unsaved edits too, not only on save.
• One click to apply one rule, the whole file, or the whole project, without touching files that have unsaved changes.
• A broken file never looks clean. A syntax error or a bad config shows up as an error.
• Change rector.php, see it at once. Open files re-check when the config changes.

Point your editor's LSP client at:

rector-warm-lsp --working-dir=/path/to/project

for PHP files, with composer.json / rector.php as root markers.

Full setup → copy-paste configs for Neovim and Helix (tested in CI), Zed, Sublime Text and PhpStorm.

Rector in your validation loop

For: teams and tools that run Rector after every generated change, as a check.

• Start once, call per file. No boot on each check after the first.
• Plain MCP over stdio. Drive it from any MCP client library (Python, Node, Go…).
• Failures are real errors. A bad path, a missing config or a Rector exception comes back as an error, never as a silent pass.

mcp-rector-warm --working-dir=/path/to/project --config=/path/to/project/rector.php

Full setup →

This repo dogfoods exactly that setup on itself (#201): .supertool.json runs this checkout's own bin/mcp-rector-warm and mcp-phpstan-warm as claude-supertool validators on every PHP edit, plus phplint/py-compile/bash-check/jsonlint/ yaml-check for the cheap syntax checks. See CONTRIBUTING.md for what that means for a pull request.

The numbers

Up to 10× faster per file on Laravel and Symfony with the warm session (on by default), 3.3–4.1× with MCP_RECTOR_WARM_SESSION=0. Every warm answer was byte-identical to cold -- including every write, which never goes through the session either way.

Machine, method, full table, reproduce it on your project →

Install

composer global require dpt/mcp-rector-warm

Puts mcp-rector-warm and rector-warm-lsp on your $PATH. As a project dependency, both are in vendor/bin/.

Documentation

• MCP server: every client setup, the rector_process tool, options, the call timeout, compatibility.
• Language server: editor setup, diagnostics, quick-fixes, unsaved buffers, fix-all, limits.
• How it works: architecture, config reloads, Windows and other PHP builds without pcntl.
• Benchmark: method, full numbers, how to reproduce.
• FAQ.
• The language server, for the Rector maintainers: design, correctness checks, known limits.

Credits

• Rector by Tomas Votruba 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

• Rector docs — config, rules, sets.
• Rector on Packagist — the upstream package.
• claude-supertool — DPT's batched-ops Claude Code companion; integrates this server as a validator.

License

Community License — see LICENSE. Built by Digital Process Tools.