Patch File MCP

Patch File MCP

ブロック形式を使用して既存のファイルにパッチを適用する MCP サーバーです。AI エージェント（Claude など）が、プロジェクト内のファイルを正確に変更できます。

概要

Patch File MCP は、ブロック形式のパッチを適用してファイルを変更するシンプルな方法を提供します。主なメリットは次のとおりです。

• ファイル全体を書き換えずに、特定の部分だけを対象に変更できます
• 1 回のリクエストで、同じファイルに複数のパッチを適用できます
• テキストの完全一致と一意性の検証により、安全性を確保します
• ほとんどのファイル編集タスクにおいて、desktop-commander の edit_block ツールより優れた代替手段です

インストール

uvx を使用する

この方法では、uv Python パッケージマネージャーに含まれる uvx を使用して、サーバーを永続的にインストールせずに実行します。

前提条件

まだインストールしていない場合は、uv から uvx をインストールしてください。

MCP クライアントを設定する（Claude Desktop、Cursor など）

以下の設定を既存の設定ファイル（例：claude_desktop_config.json）に統合してください。

{
  "mcpServers": {
    "patch-file": {
      "command": "uvx",
      "args": [
        "patch-file-mcp",
        "--allowed-dir", "/Users/your-username/projects",
        "--allowed-dir", "/Users/your-username/Documents/code"
      ]
    }
  }
}

注： /Users/your-username を、ご自身のプロジェクトおよびコードのディレクトリへの実際のパスに置き換えてください。

ソースからインストールする

前提条件

• Python 3.11 以降
• Pip パッケージマネージャー

リポジトリをクローンする

git clone https://github.com/your-username/patch-file-mcp.git
cd patch-file-mcp
python -m venv venv
source venv/bin/activate
pip install -e .

MCP クライアントを設定する（Claude Desktop、Cursor など）

以下の設定を既存の設定ファイル（例：claude_desktop_config.json）に統合してください。

{
  "mcpServers": {
    "patch-file": {
      "command": "path/to/your/venv/bin/patch-file-mcp",
      "args": [
        "--allowed-dir", "/Users/your-username/projects",
        "--allowed-dir", "/Users/your-username/Documents/code"
      ]
    }
  }
}

注： /Users/your-username を、ご自身のプロジェクトおよびコードのディレクトリへの実際のパスに置き換えてください。

引数

--allowed-dir 引数は、サーバーがアクセスできるディレクトリを指定するために使用します。複数回指定して、複数のディレクトリへのアクセスを許可できます。許可されたディレクトリ内のすべてのディレクトリにもアクセスできます。 この引数は省略可能です。指定しない場合、サーバーがアクセスできるのは、サーバーを実行しているユーザーのホームディレクトリのみです。

使用方法

MCP サーバーは、指定した設定に基づいてクライアント（例：Claude Desktop）が起動します。サーバーを手動で起動する必要はありません。

ツール

Patch File MCP は、主なツールを 1 つ提供します。

patch_file

ブロック形式のパッチ／編集を適用してファイルを更新します。

patch_file(file_path: str, patch_content: str)

• file_path：パッチを適用するファイルへのパス。
• patch_content：SEARCH／REPLACE マーカーを使用したブロック形式で、ファイル内から検索して置換する内容。複数のブロックに対応しています。

パッチの内容は、次の形式にする必要があります。

<<<<<<< SEARCH
Text to find in the file
=======
Text to replace it with
>>>>>>> REPLACE

1 回のリクエストに、複数の検索・置換ブロックを含めることができます。

<<<<<<< SEARCH
First text to find
=======
First replacement
>>>>>>> REPLACE
<<<<<<< SEARCH
Second text to find
=======
Second replacement
>>>>>>> REPLACE

このツールは、変更対象のセクションが正しいことを確認するため、各検索テキストがファイル内にちょうど 1 回だけ出現することを検証します。検索テキストが複数回出現する場合や見つからない場合は、エラーを報告します。

ワークフローの例

1. プロジェクト内のファイルの変更について、Claude との会話を開始します
2. Claude が、希望する変更を行うブロック形式のパッチを生成します
3. Claude が patch_file を使用して、ファイルに変更を適用します
4. パッチの適用に失敗した場合、Claude が問題の解決に役立つ詳細なエラー情報を提示します

セキュリティに関する考慮事項

• ファイル操作はすべて、許可されたディレクトリに制限されます
• 正しい箇所を対象にするため、検索テキストはファイル内にちょうど 1 回だけ出現する必要があります
• 詳細なエラー報告により、問題を特定して修正できます
• 各パッチ操作は、適用前に検証されます

類似ツールと比べたメリット

• 1 回の操作で複数のブロックに対応：1 回の呼び出しで複数の変更を適用できます
• 安全性チェック：完全一致によって、正しいセクションが変更されることを確認します
• 詳細なエラー：パッチを適用できない場合に、明確なフィードバックを提供します

依存関係

• fastmcp (>=2.2.0, <3.0.0)

ライセンス

MIT