Patch File MCP

🚀 文件補丁 MCP 服務器

文件補丁 MCP 服務器提供了一種通過塊格式修補現有文件的方式，讓 AI 代理（如 Claude）能夠對項目文件進行精確修改，解決了文件修改時需重寫全量內容的問題，提升了文件修改的效率和安全性。

🚀 快速開始

文件補丁 MCP 提供了一種簡單的方式來通過應用塊格式的補丁來修改文件。其主要優點包括：

• 可以針對文件的特定部分進行精準修改，而無需重寫整個內容
• 支持在單個請求中對同一文件進行多次補丁操作
• 通過精確文本匹配和唯一性驗證確保安全性
• 桌面指揮官工具 edit_block 的更優替代方案，適用於大多數文件編輯任務

📦 安裝指南

使用 uvx

這種方法使用 uvx（來自 uv Python 包管理器）在不進行永久安裝的情況下運行服務器：

先決條件

如果你還沒有安裝 uvx，請從 uv 安裝。

設置 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 替換為你自己的實際項目和文檔路徑。

💻 使用示例

基礎用法

文件補丁 MCP 提供一個主要工具 patch_file，用於通過塊格式的補丁/編輯來更新文件。

from patch_file import patch_file

# 補丁內容
patch = """--- a/message.txt
+++ b/message.txt
@@ -1,3 +1,4 @@
 Hello,
 
-This is a test.
+This is a test from
+Claude!
"""
# 調用 patch_file 函數進行文件補丁操作
patch_file("message.txt", patch)

高級用法

patch_file 函數還支持指定編碼方式和處理編碼錯誤的方式：

from patch_file import patch_file

patch = """--- a/message.txt
+++ b/message.txt
@@ -1,3 +1,4 @@
 Hello,
 
-This is a test.
+This is a test from
+Claude!
"""
# 指定編碼方式為 utf-8，處理編碼錯誤的方式為 ignore
patch_file("message.txt", patch, encoding='utf-8', errors='ignore')

📚 詳細文檔

參數說明

--allowed-dir 參數用於指定服務器可以訪問的目錄。你可以多次使用它來允許訪問多個目錄。所有允許目錄中的子目錄也都是允許的。這是一個可選參數。如果沒有提供，則服務器只能訪問運行服務器的用戶的主目錄。

補丁格式

補丁內容應使用標準的 diff 格式。例如：

--- a/file.txt
+++ b/file.txt
@@ -1,3 +1,4 @@
 Hello,
 
-This is a test.
+This is a test from
+Claude!

示例說明

假設文件 message.txt 內容為：

Hello,

This is a test.

運行以下代碼：

from patch_file import patch_file

patch = """--- a/message.txt
+++ b/message.txt
@@ -1,3 +1,4 @@
 Hello,
 
-This is a test.
+This is a test from
+Claude!
"""

patch_file("message.txt", patch)

補丁應用後，文件內容將變為：

Hello,

This is a test from
Claude!

🔧 技術細節

安全考慮

• 文件操作限制：默認情況下，服務器只能訪問其運行目錄以及通過 --allowed-dir 參數指定的目錄。
• 文本匹配唯一性：每個補丁塊必須唯一地對應於目標文件的內容，以避免意外的覆蓋或衝突。
• 錯誤報告：詳細的錯誤信息將幫助調試任何補丁應用失敗的情況。

依賴項

• fastapi（>=0.68.0，<1.0.0）
• uvicorn（>=0.15.0，<1.0.0）

📄 許可證

本項目採用 MIT 許可證。