Update README to reflect changes from unified diff format to block format, enhance installation instructions, and clarify usage examples for patch_file tool.

Author: wallneradam

README.md

@@ -1,50 +1,29 @@
 # Patch File MCP
 
-An MCP Server to patch existing files using unified diff format. This allows AI agents (like Claude) to make precise changes to files in your projects.
+An MCP Server to patch existing files using block format. This allows AI agents (like Claude) to make precise changes to files in your projects.
 
 ## Overview
 
-Patch File MCP provides a simple way to modify files by applying patches in unified diff format. The key benefits include:
+Patch File MCP provides a simple way to modify files by applying patches in block format. The key benefits include:
 
 - Makes targeted changes to specific parts of files without rewriting the entire content
-- Supports multiple patches to the same file
-- Safer than complete file rewrites since it only affects the specified sections
+- Supports multiple patches to the same file in a single request
+- Ensures safety through exact text matching and uniqueness verification
 - Better alternative to the `edit_block` tool from `desktop-commander` for most file editing tasks
 
 ## Installation
 
-### Local installation
+### Using uvx
 
-#### Prerequisites
-
-- Python 3.11 or higher
-- Pip package manager
-
-#### Install from PyPI
-
-```bash
-pip install patch-file-mcp
-```
-
-#### Install from Source
-
-```bash
-git clone https://github.com/your-username/patch-file-mcp.git
-cd patch-file-mcp
-pip install -e .
-```
-
-## Usage
-
-The MCP server is started by the client (e.g., Claude Desktop) based on the configuration you provide. You don't need to start the server manually.
+This method uses `uvx` (from the `uv` Python package manager) to run the server without permanent installation:
 
-### Integration with Claude Desktop
+#### Prerequisites
 
-To use this MCP server with Claude Desktop, you need to add it to your `claude_desktop_config.json` file:
+Install `uvx` from [uv](https://docs.astral.sh/uv/installation/) if you don't have it already.
 
-#### Using uvx (Recommended)
+#### Set up MCP Client (Claude Desktop, Cursor, etc.)
 
-This method uses `uvx` (from the `uv` Python package manager) to run the server without permanent installation:
+Merge the following config with your existing config file (e.g. `claude_desktop_config.json`):
 
 ```json
 {
@@ -61,15 +40,34 @@ This method uses `uvx` (from the `uv` Python package manager) to run the server
 }
 ```
 
-#### Using pip installed version
+> **Note:** Replace `/Users/your-username` with the actual path to your own projects and code directories.
+
+### Install from Source
+
+#### Prerequisites
+
+- Python 3.11 or higher
+- Pip package manager
+
+#### Clone the repository
+
+```bash
+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 .
+```
+
+#### Set up MCP Client (Claude Desktop, Cursor, etc.)
 
-If you've installed the package with pip:
+Merge the following config with your existing config file (e.g. `claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "patch-file": {
-      "command": "patch-file-mcp",
+      "command": "path/to/your/venv/bin/patch-file-mcp",
       "args": [
         "--allowed-dir", "/Users/your-username/projects",
         "--allowed-dir", "/Users/your-username/Documents/code"
@@ -79,74 +77,82 @@ If you've installed the package with pip:
 }
 ```
 
-### Configuring Claude Desktop
+> **Note:** Replace `/Users/your-username` with the actual path to your own projects and code directories.
 
-1. Install Claude Desktop from the [official website](https://claude.ai/desktop)
-2. Open Claude Desktop
-3. From the menu, select Settings → Developer → Edit Config
-4. Add the MCP configuration above to your existing config (modify paths as needed)
-5. Save and restart Claude Desktop
+## Arguments
 
-## Tools
+The `--allowed-dir` argument is used to specify the directories that the server has access to. You can use it multiple times to allow access to multiple directories. All directories inside the allowed directories are also allowed.
+It is optional. If not provided, the server will only have access to the home directory of the user running the server.
 
-Patch File MCP provides one main tool:
+## Usage
 
-### patch_file
+The MCP server is started by the client (e.g., Claude Desktop) based on the configuration you provide. You don't need to start the server manually.
 
-Updates a file by applying a unified diff/patch to it.
+### Tools
 
-```
-patch_file(file_path: str, patch_content: str)
-```
+Patch File MCP provides one main tool:
 
-**Parameters:**
-- `file_path`: Path to the file to be patched
-- `patch_content`: Unified diff/patch content to apply to the file
+#### patch_file
 
-**Notes:**
-- The file must exist and be within an allowed directory
-- The patch must be in valid unified diff format
-- If the patch fails to apply, an error is raised
+Update the file by applying a patch/edit to it using block format.
 
-## Example Workflow
+```python
+patch_file(file_path: str, patch_content: str)
+```
+- **file_path**: Path to the file to be patched.
+- **patch_content**: Content to search and replace in the file using block format with SEARCH/REPLACE markers. Multiple blocks are supported.
 
-1. Begin a conversation with Claude about modifying a file in your project
-2. Claude generates a unified diff/patch that makes the desired changes
-3. Claude uses `patch_file` to apply these changes to your file
-4. If the patch fails, Claude might suggest using `write_file` from another MCP as an alternative
+The patch content must have the following format:
 
-## Creating Unified Diffs
+```
+<<<<<<< SEARCH
+Text to find in the file
+=======
+Text to replace it with
+>>>>>>> REPLACE
+```
 
-A unified diff typically looks like:
+You can include multiple search-replace blocks in a single request:
 
 ```
---- oldfile
-+++ newfile
-@@ -start,count +start,count @@
- context line
--removed line
-+added line
- context line
+<<<<<<< SEARCH
+First text to find
+=======
+First replacement
+>>>>>>> REPLACE
+<<<<<<< SEARCH
+Second text to find
+=======
+Second replacement
+>>>>>>> REPLACE
 ```
 
-Claude can generate these diffs automatically when suggesting file changes.
+This tool verifies that each search text appears exactly once in the file to ensure the correct section is modified. If a search text appears multiple times or isn't found, it will report an error.
 
-## Recent Changes
+## Example Workflow
+
+1. Begin a conversation with Claude about modifying a file in your project
+2. Claude generates a block format patch that makes the desired changes
+3. Claude uses `patch_file` to apply these changes to your file
+4. If the patch fails, Claude provides detailed error information to help you fix the issue
 
-### 2025-04-23 Bugfixes
-- Fixed an issue where the patch operation would fail with "Not a directory" error when trying to apply patches.
-- Updated the patching logic to use the parent directory as the root for patch application, rather than the file itself.
 
 ## Security Considerations
 
 - All file operations are restricted to allowed directories
-- The tool only modifies specified sections of files
+- Search texts must appear exactly once in the file to ensure correct targeting
+- Detailed error reporting helps identify and fix issues
 - Each patch operation is validated before being applied
 
+## Advantages over similar tools
+
+- **Multiple blocks in one operation**: Can apply several changes in a single call
+- **Safety checks**: Ensures the correct sections are modified through exact matching
+- **Detailed errors**: Provides clear feedback when patches can't be applied
+
 ## Dependencies
 
 - fastmcp (>=2.2.0, <3.0.0)
-- patch-ng (>=1.18.0, <2.0.0)
 
 ## License