Refactor MCP

🚀 refactor - mcp

Coding Agentsに強力なリファクタリングツールを提供するModel Context Protocol (MCP)サーバーです。2つのモードで実行できます。

• MCPサーバーモード (デフォルト): Claude CodeなどのMCP互換クライアントと統合します。
• CLIモード: スタンドアロンのリファクタリングタスクを直接コマンドラインで実行します。

✨ 主な機能

このMCPサーバーは、コードのリファクタリングを支援する2つの主要なツールを実装しています。

🔧 code_refactor

高度なフィルタリング機能を備えた、ファイル全体にわたる正規表現ベースの検索と置換操作を実行します。

パラメータ:

• search_pattern (文字列) - 検索する正規表現パターン
• replace_pattern (文字列) - 置換パターン ($1、$2などのキャプチャグループをサポート)
• context_pattern (文字列、オプション) - このコンテキスト内の一致のみを置換します。
• file_pattern (文字列、オプション) - ファイルを制限するグロブパターン (例: *.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 (文字列、オプション) - 検索範囲を制限するグロブパターン

例:

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> - 検索範囲を制限するオプションのファイルグロブパターン
  • --print - 一致した内容を標準出力に印刷する
  • --matched - キャプチャグループ付きの一致したテキストのみを表示する
• refactor - 正規表現置換でコードをリファクタリングする
  • -s, --search <search> - 検索する正規表現パターン
  • -r, --replace <replace> - 置換パターン ($1、$2などをサポート)
  • -c, --context <context> - 一致をフィルタリングするオプションのコンテキストパターン
  • -f, --files <files> - 検索範囲を制限するオプションのファイルグロブパターン
  • --dry-run - ファイルを変更せずに変更をプレビューする
  • --print - 一致した内容と置換を標準出力に印刷する

重要な注意事項:

• コマンドラインで置換パターンにキャプチャグループを使用する場合は、ドル記号をエスケープしてください: \$1, \$2 など。
• 例: refactor-mcp cli refactor -s "const (\w+) = " -r "let \$1 = " --dry-run
• これにより、シェルが$1をシェル変数として解釈することを防ぎます。

MCPサーバーモード (デフォルト)

デフォルトでは、refactor-mcpはstdioトランスポートを介して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統合

このサーバーは、Model Context Protocolを使用して互換性のあるクライアントと通信します。stdioトランスポートを介して実行され、任意の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用のModel Context Protocol SDK
• ランタイム: ESモジュールを使用したNode.js
• バリデーション: 型安全な入力バリデーションのためのZodスキーマ
• ファイル操作: グロブパターンマッチングを備えたネイティブfsモジュール
• テスト: 包括的なテストカバレッジを持つVitest

🤝 コントリビューション

1. 依存関係をインストールする: npm install
2. テストを実行する: npm test
3. コード品質をチェックする: npm run check
4. ビルドする: npm run build

📄 ライセンス

MIT