Refactor MCP

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)

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

Install Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

Tools

A Model Context Protocol server that provides powerful regex-based code refactoring and search tools for Coding Agents.

Related MCP Servers

mcp-server-code-assist
abhishekbhakat
A
security
A
license
A
quality
A Model Context Protocol server that provides tools for code modification and generation via Large Language Models, allowing users to create, modify, rewrite, and delete files using structured XML instructions.
Last updated -
12
Python
MIT License
Codebase MCP
DeDeveloper23
-
security
A
license
-
quality
A Model Context Protocol server that enables AI agents to retrieve and understand entire codebases at once, providing tools to analyze local workspaces or remote GitHub repositories.
Last updated -
9
TypeScript
MIT License
Docs MCP Server
buger
A
security
A
license
A
quality
A flexible Model Context Protocol server that makes documentation or codebases searchable by AI assistants, allowing users to chat with code or docs by simply pointing to a git repository or folder.
Last updated -
1
22
36
JavaScript
MIT License
Code Merge MCP
yy1588133
A
security
A
license
A
quality
A Model Context Protocol server that helps large language models process code repositories by providing file tree generation, code merging, and code analysis capabilities.
Last updated -
3
14
JavaScript
MIT License

View all related MCP servers