refactor-mcp

A Model Context Protocol (MCP) server that provides powerful refactoring tools for Coding Agents. It can run in two modes:

MCP Server Mode (default): Integrates with MCP-compatible clients like Claude Code
CLI Mode: Direct command-line usage for standalone refactoring tasks

Features

This MCP server implements two main tools to assist with code refactoring:

🔧 code_refactor

Performs regex-based search and replace operations across files with advanced filtering capabilities.

Parameters:

search_pattern (string) - Regular expression pattern to search for
replace_pattern (string) - Replacement pattern (supports capture groups like $1, $2)
context_pattern (string, optional) - Only replace matches within this context
file_pattern (string, optional) - Glob pattern to limit files (e.g., *.js, src/**/*.ts)

Example:

// Replace foo() calls with bar() calls code_refactor("foo\$(.+)\$", "bar($1)") // Before: let k = foo(1,2,3); // After: let k = bar(1,2,3);

Context-aware refactoring:

// Only replace "legacy_sdk" within import statements code_refactor("legacy_sdk", "brand_new_sdk", "import")

🔍 code_search

Searches for regex patterns and returns file locations with precise line numbers.

Parameters:

search_pattern (string) - Regular expression pattern to search for
context_pattern (string, optional) - Filter matches by surrounding context
file_pattern (string, optional) - Glob pattern to limit search scope

Example:

code_search("foo\$.+\$") // Result: // ./src/utils.js (line: 15) // ./src/helpers.ts (lines: 23-27)

Related MCP server: Codebase MCP

Installation

Quick Start

MCP Server Mode (for Claude Code and other MCP clients):

# Install globally for MCP integration npm install -g @myuon/refactor-mcp # Or use with npx (recommended for MCP clients) npx @myuon/refactor-mcp@latest

CLI Mode (for direct command-line usage):

# Search for patterns npx @myuon/refactor-mcp@latest cli search -p "function.*\(" -f "src/**/*.js" # Refactor with preview npx @myuon/refactor-mcp@latest cli refactor -s "const (\w+)" -r "let \$1" --dry-run

For Development

# Clone and install dependencies git clone https://github.com/myuon/refactor-mcp.git cd refactor-mcp npm install

Usage

CLI Mode

You can use the refactor tools directly from the command line by adding cli after the main command:

# Search for patterns refactor-mcp cli search -p "function (.*) \{" -f "src/**/*.ts" # Search with matched content display refactor-mcp cli search -p "function (.*) \{" -f "src/**/*.ts" --print # Refactor with dry-run (preview changes) refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run # Refactor with matched content display refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --print --dry-run # Refactor with file pattern refactor-mcp cli refactor -s "old_function" -r "new_function" -f "src/**/*.js" # Context-aware refactoring refactor-mcp cli refactor -s "legacy_sdk" -r "new_sdk" -c "import" -f "src/**/*.ts"

CLI Commands:

search - Search for code patterns
- -p, --pattern <pattern> - Regular expression pattern to search for
- -c, --context <context> - Optional context pattern to filter matches
- -f, --files <files> - Optional file glob pattern to limit search scope
- --print - Print matched content to stdout
- --matched - Show only matched text with capture groups
refactor - Refactor code with regex replacement
- -s, --search <search> - Regular expression pattern to search for
- -r, --replace <replace> - Replacement pattern (supports $1, $2, etc.)
- -c, --context <context> - Optional context pattern to filter matches
- -f, --files <files> - Optional file glob pattern to limit search scope
- --dry-run - Preview changes without modifying files
- --print - Print matched content and replacements to stdout

Important Notes:

When using capture groups in replacement patterns on the command line, escape the dollar sign: \$1, \$2, etc.
Example: refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run
This prevents the shell from interpreting $1 as a shell variable

MCP Server Mode (Default)

By default, refactor-mcp runs as an MCP server via stdio transport:

# Run as MCP server (default mode) refactor-mcp # Or explicitly with npx npx @myuon/refactor-mcp@latest

Development

npm run dev # Run server in development mode npm run dev:cli # Run CLI in development mode with arguments npm run cli # Run CLI directly (for testing) npm run build # Build for production npm start # Run built server (MCP mode)

Code Quality

npm run check # Run all quality checks npm run lint # Run ESLint npm run format # Format code with Prettier npm test # Run tests

MCP Integration

This server uses the Model Context Protocol to communicate with compatible clients. It runs via stdio transport and can be integrated into any MCP-compatible environment.

Claude Code Integration

For Claude Code users, you can easily add this MCP server with:

claude mcp add refactor npx @myuon/refactor-mcp@latest

Manual Configuration

Add to your MCP client configuration:

{ "mcpServers": { "refactor-mcp": { "command": "npx", "args": ["@myuon/refactor-mcp@latest"] } } }

Alternative Configuration (Local Installation)

{ "mcpServers": { "refactor-mcp": { "command": "refactor-mcp" } } }

Architecture

Framework: Model Context Protocol SDK for TypeScript
Runtime: Node.js with ES modules
Validation: Zod schemas for type-safe input validation
File Operations: Native fs module with glob pattern matching
Testing: Vitest with comprehensive test coverage

Contributing

Install dependencies: npm install
Run tests: npm test
Check code quality: npm run check
Build: npm run build

License

MIT

Refactor MCP