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 許可證。