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

• Supports multi-hunk patches (apply multiple changes atomically)
• Dry-run mode for testing without modification
• Automatic validation before application

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

• Preview changes before applying
• Detect context mismatches
• See affected line ranges

3. **revert_patch** - Reverse a previously applied patch

• Undo changes safely
• Works with multi-hunk patches
• Requires exact original patch

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

• Compare original and modified files
• Generate standard unified diff format
• Configurable context lines

Analysis & Inspection

5. **inspect_patch** - Analyze patch content without files

• See what files are affected
• Count hunks and line changes
• Supports multi-file patches

Backup & Recovery

6. **backup_file** - Create timestamped backups

• Format: filename.backup.YYYYMMDD_HHMMSS
• Preserves file metadata
• Automatic disk space checks

7. **restore_backup** - Restore from backups

• Auto-detect original location
• Safety checks before overwriting
• Force option available

---

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