README

PHPRegex MCP

An MCP server for coding agents: validate, explain, format, transpile and judge PCRE patterns for ReDoS, read-only, over stdio.

A coding agent that writes a preg_match() call can ask this server whether the pattern compiles on the project's PHP, what it means, how it lays out over lines, how it reads in JavaScript, HTML or Python, and whether it backtracks catastrophically. Every answer comes from the library that judges patterns for a PHP version and the PCRE2 it bundles, and every tool is read-only.

Documentation: php-regex.com — the MCP guide wires the server into Claude Code, Claude Desktop, Cursor, Zed and VS Code.

Features

Five tools, each a question about one pattern written as in PHP source (/…/flags, delimiters included): regex_validate, regex_explain, regex_format, regex_transpile and regex_redos.
Every tool answers a text for a client that reads prose, and a structured document for one that reads data: the document regex <command> --json prints for the same question, one contract for the CLI and the server.
An invalid pattern, a construct a dialect cannot express, a limit of the library: a flagged tool result carrying the CLI's error envelope, so the agent reads the message and fixes the pattern. A protocol error is for the protocol only: an unknown tool, an argument the schema refuses.
Every tool takes php_version and pcre_version; the server's --php-version, --pcre-version and --locale are the defaults; without them, the running PHP.
Every tool is read-only and idempotent, and says so to the client; a client may call them without asking.
The regex_redos tool has a confirmed mode that replays the witness through the engine on this machine, bounded by the library's own caps.

Installation

composer require --dev php-regex/regex-mcp

Requires PHP 8.1 or newer with the fileinfo extension (and mbstring, which the parser needs). The binary is installed as vendor/bin/regex-mcp; --help prints its options, --version the release it was built from. The regex.phar carries the server too: php regex.phar mcp starts it with nothing else installed.

Usage

Start the server as a client does, over stdin and stdout:

vendor/bin/regex-mcp
vendor/bin/regex-mcp --php-version=8.2
vendor/bin/regex mcp --php-version=8.2 --pcre-version=10.40

A client configuration names the command. Claude Code:

claude mcp add php-regex -- /path/to/project/vendor/bin/regex-mcp --php-version=8.2

Claude Desktop, Cursor and the others take the same command in their JSON settings; the MCP guide holds each snippet. Name the binary by its absolute path: a desktop client starts the server with no project directory and no promise about PATH.

The tools

Tool	Arguments	Answers
`regex_validate`	`pattern`	whether the target PHP compiles the pattern: the error, its byte offset, a hint. An invalid pattern is the answer, not a failure
`regex_explain`	`pattern`	the pattern in plain language, construct by construct
`regex_format`	`pattern`, `width` (default 80), `compact`	the pattern laid out over lines under `x`, or compacted to one line; the result matches exactly what the pattern given matches
`regex_transpile`	`pattern`, `target` (`js`, `html`, `python`), `python_version`	the pattern in the dialect, with every note on what was rewritten and every warning on what matches differently; a construct the dialect cannot express is refused with its reason
`regex_redos`	`pattern`, `mode` (`theoretical`, `confirmed`), `threshold`	severity, complexity, the witness that pumps the backtracking, the hotspots, the recommendations

Every tool also takes php_version and pcre_version. The structured answer of each tool is the document the CLI prints: regex validate --json, regex explain --json, regex format --json, regex transpile --json, and the redos member of regex analyze --json, all described in the JSON output reference.

A tool call with /^(a+)+$/ answers, as text:

Exponential backtracking (proven)
Unbounded quantifier detected. May cause backtracking on non-matching input. …

and, as structured content, the ReDoS analysis object: severity, complexity, witness (prefix, pump, suffix), hotspots and the rest.

Integration

The server is one class, started by the CLI's regex mcp and by vendor/bin/regex-mcp alike:

use PHPRegex\Mcp\Application;

exit((new Application())->run(['php_version' => '8.2']));

The tools run without the protocol: ToolCatalog::v1() lists them, and each one answers a ToolResult from an array of arguments, which is how they are tested.

use PHPRegex\Mcp\ToolCatalog;

$result = ToolCatalog::v1(['php_version' => '8.2'])->get('regex_validate')->tool->execute(['pattern' => '/a+/']);
$result->text;       // "Valid."
$result->structured; // ['pattern' => '/a+/', 'validation' => [...]]
$result->isError;    // false

The protocol is spoken by the official PHP SDK, mcp/sdk, through one class of this package; the SDK is experimental, pinned to one minor, and a change of SDK is a change of that class alone.

Documentation

MCP guide — client configurations, the tools, troubleshooting.
JSON output reference — the documents the tools answer.
Backward compatibility promise — what stays stable across releases.

Resources

Upgrading from 1.x — moving from yoeunes/regex-parser 1.3 to 2.0, every change that needs one on your side
Documentation
Report issues and send pull requests in the main PHPRegex repository
Changelog

License

MIT. See LICENSE.

The server depends on mcp/sdk, the official Model Context Protocol SDK for PHP, which is released under the Apache License 2.0; the license is permissive and the code of this package stays MIT.

php-regex / regex-mcp

Package info

Security

Fund package maintenance!

Statistics