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:

$3

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:
``javascript
// 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:
`javascript
// Only replace "legacy_sdk" within import statements
code_refactor("legacy_sdk", "brand_new_sdk", "import")
`

$3

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:
`javascript
code_search("foo\\(.+\\)")

// Result:
// ./src/utils.js (line: 15)
// ./src/helpers.ts (lines: 23-27)
`

Installation

$3

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


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):
`bash


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
`

$3

`bash

Clone and install dependencies

git clone https://github.com/myuon/refactor-mcp.git
cd refactor-mcp
npm install
`

Usage

$3

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

`bash


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 - Regular expression pattern to search for
- -c, --context - Optional context pattern to filter matches
- -f, --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

- Regular expression pattern to search for
- -r, --replace - Replacement pattern (supports $1, $2, etc.)
- -c, --context - Optional context pattern to filter matches
- -f, --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

$3


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

`bash


Run as MCP server (default mode)

refactor-mcp

Or explicitly with npx

npx @myuon/refactor-mcp@latest
`

$3

`bash
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)
`

$3

`bash
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.

$3

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

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

$3

Add to your MCP client configuration:

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

$3


`json
{
"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

1. Install dependencies: npm install
2. Run tests: npm test
3. Check code quality: npm run check
4. Build: npm run build`

License

MIT