Refactor MCP

🚀 refactor-mcp

refactor-mcp 是一个模型上下文协议（MCP）服务器，为编码代理提供强大的重构工具。它可以在两种模式下运行：

• MCP 服务器模式（默认）：可与 Claude Code 等支持 MCP 的客户端集成。
• CLI 模式：可直接在命令行中使用，用于独立的代码重构任务。

🚀 快速开始

refactor-mcp 是一个基于模型上下文协议（MCP）的服务器，为编码代理提供强大的代码重构工具。它支持两种运行模式，满足不同场景的需求。

运行模式

• MCP 服务器模式（默认）：可与 Claude Code 等支持 MCP 的客户端集成。
• CLI 模式：可直接在命令行中使用，用于独立的代码重构任务。

✨ 主要特性

此 MCP 服务器实现了两个主要工具，以协助进行代码重构：

🔧 code_refactor

可基于正则表达式在文件中执行搜索和替换操作，并具备高级过滤功能。 参数：

• search_pattern（字符串） - 要搜索的正则表达式模式。
• replace_pattern（字符串） - 替换模式（支持 $1、$2 等捕获组）。
• context_pattern（字符串，可选） - 仅替换此上下文中的匹配项。
• file_pattern（字符串，可选） - 用于限制文件范围的 glob 模式（例如 *.js、src/**/*.ts）。

示例：

// 将 foo() 调用替换为 bar() 调用
code_refactor("foo\\((.+)\\)", "bar($1)")

// 替换前: let k = foo(1,2,3);
// 替换后:  let k = bar(1,2,3);

上下文感知的重构：

// 仅在导入语句中替换 "legacy_sdk"
code_refactor("legacy_sdk", "brand_new_sdk", "import")

🔍 code_search

搜索正则表达式模式，并返回带有精确行号的文件位置。 参数：

• search_pattern（字符串） - 要搜索的正则表达式模式。
• context_pattern（字符串，可选） - 通过周围上下文过滤匹配项。
• file_pattern（字符串，可选） - 用于限制搜索范围的 glob 模式。

示例：

code_search("foo\\(.+\\)")

// 结果:
// ./src/utils.js (行号: 15)
// ./src/helpers.ts (行号: 23 - 27)

📦 安装指南

快速安装

MCP 服务器模式（适用于 Claude Code 和其他 MCP 客户端）：

# 全局安装以集成 MCP
npm install -g @myuon/refactor-mcp

# 或者使用 npx（推荐用于 MCP 客户端）
npx @myuon/refactor-mcp@latest

CLI 模式（用于直接在命令行中使用）：

# 搜索模式
npx @myuon/refactor-mcp@latest cli search -p "function.*\(" -f "src/**/*.js"

# 带预览的重构
npx @myuon/refactor-mcp@latest cli refactor -s "const (\w+)" -r "let \$1" --dry-run

开发环境安装

# 克隆仓库并安装依赖
git clone https://github.com/myuon/refactor-mcp.git
cd refactor-mcp
npm install

💻 使用示例

CLI 模式

你可以在主命令后添加 cli 直接从命令行使用重构工具：

# 搜索模式
refactor-mcp cli search -p "function (.*) \{" -f "src/**/*.ts"

# 搜索并显示匹配内容
refactor-mcp cli search -p "function (.*) \{" -f "src/**/*.ts" --print

# 带预演的重构（预览更改）
refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run

# 重构并显示匹配内容
refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --print --dry-run

# 带文件模式的重构
refactor-mcp cli refactor -s "old_function" -r "new_function" -f "src/**/*.js"

# 上下文感知的重构
refactor-mcp cli refactor -s "legacy_sdk" -r "new_sdk" -c "import" -f "src/**/*.ts"

CLI 命令：

• search - 搜索代码模式
  • -p, --pattern <pattern> - 要搜索的正则表达式模式。
  • -c, --context <context> - 可选的上下文模式，用于过滤匹配项。
  • -f, --files <files> - 可选的文件 glob 模式，用于限制搜索范围。
  • --print - 将匹配内容打印到标准输出。
  • --matched - 仅显示带有捕获组的匹配文本。
• refactor - 使用正则表达式替换重构代码
  • -s, --search <search> - 要搜索的正则表达式模式。
  • -r, --replace <replace> - 替换模式（支持 $1、$2 等）。
  • -c, --context <context> - 可选的上下文模式，用于过滤匹配项。
  • -f, --files <files> - 可选的文件 glob 模式，用于限制搜索范围。
  • --dry-run - 预览更改而不修改文件。
  • --print - 将匹配内容和替换内容打印到标准输出。

⚠️ 重要提示

在命令行的替换模式中使用捕获组时，需要对美元符号进行转义：\$1、\$2 等。 示例：refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run 这可以防止 shell 将 $1 解释为 shell 变量。

MCP 服务器模式（默认）

默认情况下，refactor-mcp 通过标准输入输出传输作为 MCP 服务器运行：

# 以 MCP 服务器模式运行（默认模式）
refactor-mcp

# 或者使用 npx 显式运行
npx @myuon/refactor-mcp@latest

开发模式

npm run dev          # 在开发模式下运行服务器
npm run dev:cli      # 在开发模式下使用参数运行 CLI
npm run cli          # 直接运行 CLI（用于测试）
npm run build        # 为生产环境构建
npm start            # 运行构建后的服务器（MCP 模式）

代码质量检查

npm run check        # 运行所有质量检查
npm run lint         # 运行 ESLint
npm run format       # 使用 Prettier 格式化代码
npm test             # 运行测试

📚 详细文档

MCP 集成

此服务器使用模型上下文协议与兼容的客户端进行通信。它通过标准输入输出传输运行，可集成到任何支持 MCP 的环境中。

Claude Code 集成

对于 Claude Code 用户，你可以使用以下命令轻松添加此 MCP 服务器：

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

手动配置

添加到你的 MCP 客户端配置中：

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

替代配置（本地安装）

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

🔧 技术细节

• 框架：用于 TypeScript 的模型上下文协议 SDK。
• 运行时：使用 ES 模块的 Node.js。
• 验证：使用 Zod 模式进行类型安全的输入验证。
• 文件操作：使用支持 glob 模式匹配的原生 fs 模块。
• 测试：使用 Vitest 进行全面的测试覆盖。

🤝 贡献指南

1. 安装依赖：npm install
2. 运行测试：npm test
3. 检查代码质量：npm run check
4. 构建项目：npm run build

📄 许可证

本项目采用 MIT 许可证。