mcp-multi-edit

Multi Edit MCP サーバー

Claude が 1 回のツール呼び出しで複数の検索と置換を実行できるようにする MCP サーバーです。アトミック性が保証され、すべての編集が成功するか、何も適用されないかのどちらかになります。

Essential AI Solutions が Claude Code と Claude Desktop 向けに開発しました。

Multi Edit を使う理由

Claude に組み込まれている Edit ツールでは、1 回の呼び出しにつき検索と置換を 1 件しか処理できません。ファイル内の変数名を変更したり、複数のファイルをリファクタリングしたりする場合、個別のツール呼び出しが何十回も必要になり、それぞれがコンテキストトークンを消費し、遅延も増加します。

Multi Edit なら、複数の操作を 1 回の呼び出しにまとめられます：

Without multi_edit:      105 tool calls   |   15,750 tokens
With multi_edit:          21 tool calls   |    7,850 tokens   (-80% calls, -50% tokens)
With multi_edit_files:     6 tool calls   |    4,550 tokens   (-94% calls, -71% tokens)

ベンチマークは、現実的なシナリオ（一括リネーム、ロギングの移行、ファイル横断リファクタリング）で実行されています。 詳細については、benchmarks/results/BENCHMARK-REPORT.md をご覧ください。

クイックスタート

Claude Code

プロジェクトのルートに .mcp.json を追加します：

{
  "mcpServers": {
    "Multi Edit from Essential AI Solutions (essentialai.uk)": {
      "command": "npx",
      "args": ["-y", "@essentialai/mcp-multi-edit"]
    }
  }
}

Claude Code を再起動します。次に、付属の CLAUDE.md をプロジェクトのルートに追加すると、Claude は組み込みの Edit ツールよりも multi_edit を 自動的に優先して使用します：

## Editing Files

When making multiple edits to the same file or across multiple files,
prefer using the `multi_edit` and `multi_edit_files` MCP tools over
the built-in Edit tool. These batch edits atomically in a single call.

これで完了です。Claude は、multi_edit が適切な場合にいつでも使用するようになります。

表示名： Claude Code は、mcpServers 内のキー名をサーバーの表示名として使用します。キーは任意の名前に変更できます。

別の方法： CLI を使ったワンライナー：

claude mcp add --transport stdio multi-edit -- npx -y @essentialai/mcp-multi-edit

注： CLI で使えるのは、文字、数字、ハイフン、アンダースコアだけを含むシンプルな名前です。ブランド名を含む完全な表示名を使うには、上記の .mcp.json を使用してください。

Claude Desktop

設定ファイル（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します：

{
  "mcpServers": {
    "Multi Edit from Essential AI Solutions (essentialai.uk)": {
      "command": "npx",
      "args": ["-y", "@essentialai/mcp-multi-edit"]
    }
  }
}

Claude Desktop を再起動します。

インストールガイド全文： docs/installation.md

ツール

multi_edit -- 1 つのファイルに対する複数の編集

1 つのファイルに対する複数の検索と置換をまとめて実行します。編集は順番に、アトミックに適用されます。

{
  "file_path": "/project/src/app.ts",
  "edits": [
    { "old_string": "const oldName = getValue()", "new_string": "const newName = getValue()" },
    { "old_string": "console.log", "new_string": "logger.info", "replace_all": true }
  ]
}

パラメーター	型	デフォルト	説明
file_path	string	必須	ファイルの絶対パス
edits	array	必須	検索と置換の操作（順番に適用）
edits[].old_string	string	必須	検索するテキスト（完全一致）
edits[].new_string	string	必須	置換後のテキスト
edits[].replace_all	boolean	false	一致する箇所をすべて置換
dry_run	boolean	false	変更を適用せずにプレビュー
backup	boolean	true	編集前に .bak バックアップを作成

multi_edit_files -- 複数のファイルに対する 1 つのアトミックな操作

複数のファイルにまたがる編集をまとめて実行します。いずれかのファイルで失敗した場合、すべてのファイルが自動的にロールバックされます。

{
  "files": [
    {
      "file_path": "/project/src/types.ts",
      "edits": [
        { "old_string": "interface UserData {", "new_string": "interface UserProfile {" }
      ]
    },
    {
      "file_path": "/project/src/api.ts",
      "edits": [
        { "old_string": "UserData", "new_string": "UserProfile", "replace_all": true }
      ]
    }
  ]
}

パラメーター	型	デフォルト	説明
files	array	必須	ファイル編集操作の配列
files[].file_path	string	必須	ファイルの絶対パス
files[].edits	array	必須	このファイルに対する編集（上記と同じ形式）
dry_run	boolean	false	変更を適用せずにプレビュー

使用例付きの完全なガイド： docs/usage.md

機能

• アトミック操作 -- すべての編集が成功するか、どれも適用されません。中途半端な状態にはなりません
• 複数ファイルのロールバック -- いずれかのファイルで失敗した場合、変更済みのファイルはすべて元に戻されます
• ドライランプレビュー -- コミット前に、変更内容を正確に確認できます
• 自動バックアップ -- 編集の前に毎回 .bak ファイルが作成されます（backup: false で無効化できます）
• 構造化エラー -- 自動リトライのための復旧ヒントを含む、機械可読なエラーコードです
• 競合検出 -- old_string が複数の箇所に一致した場合に警告します
• パス検証 -- 絶対パスの強制、シンボリックリンクの解決、存在確認を行います

エラーコード

コード	リトライ可能	説明
MATCH_NOT_FOUND	はい	ファイル内に old_string が見つかりません
AMBIGUOUS_MATCH	はい	old_string が複数の箇所に一致します
VALIDATION_FAILED	はい	入力スキーマが無効です
FILE_NOT_FOUND	いいえ	ファイルが存在しません
PERMISSION_DENIED	いいえ	ファイルの権限が不足しています
BACKUP_FAILED	いいえ	バックアップファイルを作成できませんでした

retryable が true の場合、Claude はレスポンス内の recovery_hints を読み取り、入力を調整して自動的にリトライします。

トラブルシューティングガイド： docs/troubleshooting.md

要件

• Node.js 20 以降
• Claude Code または Claude Desktop

開発

npm install           # Install dependencies
npm run build         # Compile TypeScript
npm test              # Run 264 tests
npm run test:coverage # Coverage report (90%+)
npm run benchmark     # Run benchmark suite
npm run dev           # Watch mode

プロジェクト構成

src/
  index.ts              # MCP server entry (stdio transport)
  server.ts             # Server factory and tool registration
  tools/
    multi-edit.ts       # multi_edit tool handler
    multi-edit-files.ts # multi_edit_files tool handler
  core/
    editor.ts           # File editing engine (atomic read-modify-write)
    validator.ts        # Zod input validation schemas
    reporter.ts         # Result formatting and diff generation
    errors.ts           # Error classification and envelope creation
  types/
    index.ts            # TypeScript type definitions

ドキュメント

ドキュメント	説明
インストールガイド	Claude Code と Claude Desktop のすべてのセットアップ方法
使用ガイド	例を含む詳細なツールリファレンス
トラブルシューティング	よくある問題と解決方法
変更履歴	バージョン履歴
ベンチマークレポート	パフォーマンス測定結果

ライセンス

PolyForm Noncommercial License 1.0.0

個人利用および非商用利用は無料です。商用ライセンスについては、[email protected] までお問い合わせください。

---

Essential AI Solutions が開発