Patch File MCP

🚀 File Patch MCP Server

A MCP server for patching existing files in block format, enabling AI agents like Claude to make precise modifications to project files.

🚀 Quick Start

The File Patch MCP Server offers a straightforward way to modify files by applying block - formatted patches. It allows AI agents such as Claude to make precise changes to project files.

✨ Features

• Precise Modifications: It can precisely modify specific parts of a file without rewriting the entire content.
• Multiple Patch Operations: Supports multiple patch operations on the same file in a single request.
• Security Assurance: Ensures security through exact text matching and uniqueness verification.
• Better Alternative: A superior alternative to the desktop commander tool edit_block for most file - editing tasks.

📦 Installation

Using uvx

This method uses uvx (from the uv Python package manager) to run the server without permanent installation:

Prerequisites

If you haven't installed uvx yet, install it from uv.

Setting up the MCP Client (Claude Desktop, Cursor, etc.)

Merge the following configuration with your existing configuration file (e.g., 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"
      ]
    }
  }
}

⚠️ Important Note

Replace /Users/your-username with your actual project and document paths.

Installation from Source Code

Prerequisites

• Python 3.11 or higher
• Pip package manager

Clone the Repository

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 .

Setting up the MCP Client (Claude Desktop, Cursor, etc.)

Merge the following configuration with your existing configuration file (e.g., 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"
      ]
    }
  }
}

⚠️ Important Note

Replace /Users/your-username with your actual project and document paths.

🔧 Technical Details

The --allowed-dir parameter is used to specify the directories that the server can access. You can use it multiple times to allow access to multiple directories. All sub - directories within the allowed directories are also permitted. This is an optional parameter. If not provided, the server can only access the home directory of the user running the server.

💻 Usage Examples

Basic Usage

The File Patch MCP provides a main tool:

patch_file

Update a file through block - formatted patches/edits.

patch_file(file_path: str, patch_content: str)

• file_path: The path of the file to be patched.
• patch_content: The text content for patching/editing in block format.

This function supports the following optional parameters:

• encoding: Specifies the encoding method of the file, defaulting to 'utf-8'.
• errors: Specifies how to handle encoding errors, with optional values 'strict', 'ignore', or 'replace', defaulting to 'strict'.

Patch Format

The patch content should use the standard diff format. For example:

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

Example

Suppose the content of the file message.txt is:

Hello,

This is a test.

Run the following code:

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)

After applying the patch, the file content will become:

Hello,

This is a test from
Claude!

🛡️ Security Considerations

• File Operation Restrictions: By default, the server can only access the directory where it runs and the directories specified by the --allowed-dir parameter.
• Text Matching Uniqueness: Each patch block must uniquely correspond to the content of the target file to avoid accidental overwriting or conflicts.
• Error Reporting: Detailed error information will assist in debugging any patch application failures.

📦 Dependencies

• fastapi (>=0.68.0, <1.0.0)
• uvicorn (>=0.15.0, <1.0.0)

📄 License

MIT