Patch File MCP

Patch File MCP

一个用于以块格式修补现有文件的 MCP 服务。这让 AI Agent（如 Claude）能够对项目中的文件进行精确修改。

概述

Patch File MCP 提供了一种简单的方式，可通过应用块格式补丁来修改文件。主要优势包括：

• 对文件的特定部分进行针对性修改，无需重写全部内容
• 支持在单个请求中对同一文件应用多个补丁
• 通过精确文本匹配和唯一性验证确保安全
• 对于大多数文件编辑任务，它是 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 提供一个主要工具：

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

你可以在单个请求中包含多个搜索-替换块：

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

此工具会验证每段搜索文本在文件中是否恰好出现一次，以确保修改正确的部分。如果搜索文本出现多次或未找到，则会报告错误。

工作流示例

1. 与 Claude 开始对话，讨论如何修改项目中的文件
2. Claude 生成一个块格式补丁，以实现所需修改
3. Claude 使用 patch_file 将这些修改应用到文件中
4. 如果补丁失败，Claude 会提供详细的错误信息来帮助你解决问题

安全注意事项

• 所有文件操作都限制在允许访问的目录内
• 搜索文本必须在文件中恰好出现一次，以确保定位正确
• 详细的错误报告有助于识别和解决问题
• 每项补丁操作都会在应用前进行验证

相较于类似工具的优势

• 单次操作包含多个块：一次调用即可应用多项修改
• 安全检查：通过精确匹配确保修改正确的部分
• 详细错误信息：无法应用补丁时提供清晰的反馈

依赖项

• fastmcp (>=2.2.0, <3.0.0)

许可证

MIT