Patch MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to safely apply unified diff patches to files with comprehensive security validation.

Version: 2.0.0 | Status: Beta | Tools: 7 | Test Coverage: 84% (286 tests)

Why Patch MCP Server?

Enable your AI assistant to:

• ✅ Apply code changes using standard unified diff format
• ✅ Validate patches before applying them
• ✅ Create and restore backups automatically
• ✅ Revert changes safely if something goes wrong
• ✅ Apply multiple changes atomically via multi-hunk patches
• ✅ Test changes with dry-run mode before committing

All with built-in security (no symlinks, binary files, or directory traversal) and automatic rollback on failures.

Why Use Patch Tools Instead of Direct Editing?

For AI assistants and developers, apply_patch provides significant advantages over traditional Edit operations:

Real-World Example

Task: Update 3 config values in one file

• Edit: 3 separate tool calls, no atomicity, hard to review
• apply_patch: 1 call with 3 hunks, atomic operation, clear diff

Bottom line: For most file modifications, apply_patch is more efficient, safer, and clearer than Edit operations.

Quick Start

Installation

# Clone the repository
git clone https://github.com/shenning00/patch_mcp.git
cd patch_mcp

# Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Configure with Claude Desktop

Add to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

{
  "mcpServers": {
    "patch": {
      "command": "python",
      "args": ["-m", "patch_mcp"],
      "cwd": "/path/to/patch_mcp"
    }
  }
}

Restart Claude Desktop and the patch tools will be available.

Run Standalone

python -m patch_mcp

The server runs in stdio mode and communicates via the Model Context Protocol.

Available Tools

The server provides 7 tools for comprehensive patch management:

Core Patch Operations

1. `apply_patch` - Apply a unified diff patch to a file

2. `validate_patch` - Check if a patch can be applied (read-only)

3. `revert_patch` - Reverse a previously applied patch

4. `generate_patch` - Create a patch from two file versions

Analysis & Inspection

5. `inspect_patch` - Analyze patch content without files

Backup & Recovery

6. `backup_file` - Create timestamped backups

7. `restore_backup` - Restore from backups

Example: How an AI Assistant Uses This Server

Scenario 1: Simple Code Modification

AI Assistant's thought process:

> "The user wants to change the timeout from 30 to 60 seconds in config.py. I'll use the patch server to do this safely."

AI uses tools:

1. Generate the patch:

Tool: generate_patch
Args: {
  "original_file": "config.py",
  "modified_file": "config_new.py"
}

2. Validate it can be applied:

Tool: validate_patch
Args: {
  "file_path": "config.py",
  "patch": "--- config.py\n+++ config.py\n@@ -10,3 +10,3 @@\n-timeout = 30\n+timeout = 60"
}
Result: {
  "success": true,
  "can_apply": true,
  "preview": {"lines_to_add": 1, "lines_to_remove": 1}
}

3. Create backup before applying:

Tool: backup_file
Args: {"file_path": "config.py"}
Result: {"backup_file": "config.py.backup.20250118_143052"}

4. Apply the patch:

Tool: apply_patch
Args: {
  "file_path": "config.py",
  "patch": "--- config.py\n+++ config.py\n@@ -10,3 +10,3 @@\n-timeout = 30\n+timeout = 60"
}
Result: {"success": true, "applied": true}

AI reports to user:

> "I've updated the timeout from 30 to 60 seconds in config.py. A backup was created at config.py.backup.20250118_143052 in case you need to revert."

Scenario 2: Multi-file Refactoring with Dry Run

AI Assistant's thought process:

> "The user wants to rename a function across 3 files. I should test this first with dry-run, then apply atomically."

AI uses tools:

1. Test each patch with dry-run:

Tool: apply_patch
Args: {
  "file_path": "utils.py",
  "patch": "...",
  "dry_run": true
}
Result: {"success": true, "changes": {"lines_added": 5, "lines_removed": 5}}

2. Apply all patches:

Applies each patch with backups and validation

AI reports to user:

> "I've renamed the function across utils.py, handlers.py, and tests.py. All changes were validated first and applied atomically."

Scenario 3: Something Goes Wrong

AI Assistant's thought process:

> "The patch failed to apply. I should revert to the backup."

AI uses tools:

Tool: restore_backup
Args: {
  "backup_file": "config.py.backup.20250118_143052"
}
Result: {"success": true, "restored_to": "config.py"}

AI reports to user:

> "The patch couldn't be applied because the file content didn't match. I've restored the original file from backup. The file may have been modified since we discussed the change."

Security Features

All operations include comprehensive security checks:

• 🔒 Symlink Protection - Symlinks are rejected (security policy)
• 🔒 Binary File Detection - Binary files automatically detected and rejected
• 🔒 Size Limits - Maximum 10MB file size
• 🔒 Disk Space Validation - Ensures 100MB+ free space before operations
• 🔒 Path Traversal Protection - Prevents directory escaping
• 🔒 Permission Checks - Validates read/write permissions
• 🔒 Atomic Operations - File replacements use atomic rename

See SECURITY.md for detailed security information.

Multi-Hunk Patches

A powerful feature: apply multiple changes to different parts of a file atomically in a single patch:

--- config.py
+++ config.py
@@ -10,3 +10,3 @@
 # Connection settings
-timeout = 30
+timeout = 60

@@ -25,3 +25,3 @@
 # Retry settings
-retries = 3
+retries = 5

@@ -50,3 +50,3 @@
 # Debug settings
-debug = False
+debug = True

All three changes are applied together or none are applied. If any hunk fails, the entire patch is rejected.

Documentation

Documentation

• **SECURITY.md** - Security policy and best practices
• **WORKFLOWS.md** - Error recovery workflow patterns
• **CONTRIBUTING.md** - Contributing guidelines
• **CHANGELOG.md** - Version history and changes

Error Types

The server provides 10 distinct error types for precise error handling:

Standard Errors:

• `file_not_found`, `permission_denied`, `invalid_patch`, `context_mismatch`, `encoding_error`, `io_error`

Security Errors:

• `symlink_error`, `binary_file`, `disk_space_error`, `resource_limit`

Testing & Quality

• 286 tests (all passing)
• 84% code coverage across all modules
• Strict type checking with mypy
• Code formatting with black
• Linting with ruff
• CI/CD via GitHub Actions (Linux, macOS, Windows)

# Run tests
pytest tests/ -v --cov=src/patch_mcp

# Check code quality
black src/patch_mcp tests/
ruff check src/patch_mcp tests/
mypy src/patch_mcp --strict

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

• Development setup
• Testing guidelines
• Code quality standards
• Commit message conventions

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author: Scott Henning

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md for vulnerability reporting

Model Context Protocol

This server implements the Model Context Protocol (MCP), an open protocol that enables AI assistants to securely interact with local tools and data sources.

Learn more:

• MCP Documentation
• MCP Specification
• Claude Desktop Integration

Last Updated: 2025-10-19 | Phase: 5 of 5 (Beta) | Tools: 7/7