正则替换工具

regex-replace-mcp

Shared Rust engine for safe regex find-and-replace across files, exposed through MCP, a two-phase JSON CLI, and a native Pi tool.

Installation

Run the project deploy script:

./deploy.sh

It builds and installs both Rust binaries, then registers this repository as a local Pi package. Restart Pi after installation so it loads the native extension.

For MCP-only installation:

cargo install --git https://github.com/Osso/regex-replace-mcp

MCP Configuration

Add to your Claude Code MCP config (~/.claude.json):

{
  "mcpServers": {
    "regex-replace": {
      "type": "stdio",
      "command": "/path/to/regex-replace-mcp",
      "args": []
    }
  }
}

Tools

regex_search

Search for regex pattern matches across files.

Parameters:

• pattern: Regex pattern (Rust regex syntax)
• files: Glob pattern for files (e.g., src/**/*.rs)
• limit: Maximum matches to return (default: 50)

regex_replace

Replace text matching a regex pattern across multiple files.

Parameters:

• pattern: Regex pattern (Rust regex syntax)
• replacement: Replacement string with capture group support
• files: Glob pattern for files
• dry_run: Preview changes without writing (default: false)

Native Pi Tool

The regex_replace tool accepts:

• files: gitignore-aware glob relative to the current working directory.
• pattern: Rust regex syntax.
• replacement: replacement string with $1, $2, and $0 captures.
• expectedMatches: required exact match count.
• dryRun: preview without writing.
• maxFiles, maxTotalBytes, maxMatches: optional safety limits (defaults: 100 files, 10 MiB, and 10,000 matches). Normal model calls should omit these parameters so the documented defaults apply; explicit non-default values remain allowed when the user requests them.

The tool requires approval. Native Pi result details contain compact summary fields (dryRun, totalReplacements, and filesModified) plus a bounded diff, keeping serialized details below Pi's 10 KiB runtime cap. Oversized diffs are explicitly marked as truncated in both result details and model output instead of causing Invalid replacement details. Non-dry runs use a two-phase protocol. Pi previews the plan, locks every canonical target through its file-mutation queue, and applies only if the frozen targets still produce the same plan hash. Each file is replaced via an atomic rename; multi-file failures use transaction-like rollback rather than claiming literal cross-file atomic visibility.

Capture Groups

Use $1, $2, etc. for capture groups in replacements:

pattern: "fn (\w+)\(\)"
replacement: "fn $1_v2()"

Literal $ in replacements (like $request) stays literal - only $ followed by digits is treated as a capture group reference.

License

MIT