# regexguard-mcp-server

[![Glama score](https://glama.ai/mcp/servers/wedo911/regexguard-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/wedo911/regexguard-mcp-server)

An [MCP](https://modelcontextprotocol.io) server that gives any AI agent a
way to sanity-check a regex it just generated -- both what it actually
matches and whether it's safe to run against untrusted input -- before
shipping it. Fully local: no API key, no network call, no dependency
beyond the MCP SDK and Zod.

## Why

Regexes are a notoriously easy place to introduce a bug that looks fine in
every example you happen to test. Two failure modes in particular are both
common and easy to miss by eye:

1. **It doesn't match what you think it matches.** `explain_regex` turns
   the pattern into a real syntax tree and describes it in plain English,
   so "does this actually require at least one digit?" has a fast answer
   that doesn't depend on trusting your own reading of nested brackets.
2. **It's a denial-of-service vector.** A regex with nested quantifiers
   (`(a+)+`) or ambiguous alternation inside a repeated group (`(a|a)+`)
   can make a backtracking engine take *exponential* time on a crafted (or
   even accidental) non-matching input -- this is
   [ReDoS](https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS),
   a real and repeatedly-exploited vulnerability class, and a plausible
   defect in any regex an agent writes without testing it against
   adversarial input. `check_redos_risk` flags the structural shape
   **without ever executing the pattern** -- it's safe to run on untrusted
   or deliberately malicious regex source.

## Tools

### `explain_regex`

Parses a pattern into an AST and returns a plain-English description of
what it matches.

### `check_redos_risk`

Statically analyzes a pattern's structure for nested quantifiers and
ambiguous alternation inside a repeated group -- the two classic causes of
catastrophic backtracking. Returns `"safe"`, `"high"`, or `"critical"`,
with a specific finding for each issue found.

Both tools share one parser
([`src/services/parser.ts`](src/services/parser.ts)): a real recursive-descent
regex parser (literals, character classes, shorthand classes, anchors,
capturing/non-capturing/named groups, lookaround, alternation, quantifiers,
backreferences), not a bag of string-matching heuristics against the
pattern's raw source text.

**This is a heuristic structural check, not a formal verifier** --
`check_redos_risk` can tell you a pattern has the textbook exponential-blowup
shape; it can't prove a pattern is fast on all inputs, and there are ReDoS
patterns outside the two shapes it currently detects. Treat a `"safe"`
result as "nothing obvious found," not a guarantee.

## Install and configure

```bash
git clone https://github.com/wedo911/regexguard-mcp-server.git
cd regexguard-mcp-server
npm install
npm run build
```

Add it to your MCP client's config (e.g. `claude_desktop_config.json`, or a
project's `.mcp.json` for Claude Code):

```json
{
  "mcpServers": {
    "regexguard": {
      "command": "node",
      "args": ["/absolute/path/to/regexguard-mcp-server/dist/index.js"]
    }
  }
}
```

## Run the tests

```bash
npm run build
node --test tests/parser.test.mjs tests/explain.test.mjs tests/redosCheck.test.mjs
```

44 tests cover the parser grammar, the explanation output, and both true
positives (`(a+)+`, `(a*)*`, `(a|a)+`, `(a|ab)+`, patterns nested inside
non-capturing groups) and true negatives (`(cat|dog)+`, a realistic
username pattern, a realistic email pattern, sibling — not nested —
repetitions) for the ReDoS check, so the false-positive rate on ordinary
patterns is a tested property, not a hope.

## Try it without a client

```bash
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name check_redos_risk \
  --tool-arg pattern='^(([a-zA-Z0-9])+([\.-]?([a-zA-Z0-9])+)*)$'
```

## License

MIT — see [LICENSE](LICENSE).