@n0zer0d4y/vulcan-file-ops 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2025-11-11
+
+### Fixed
+
+- Corrected Docker entrypoint to use dist/cli.js instead of dist/index.js for proper MCP server initialization
+- Updated Node.js base image from node:22.12-alpine to node:22-alpine for better version compatibility
+
+### Changed
+
+- Added keywords to package.json for improved NPM discoverability
+
+## [1.1.0] - 2025-11-08
+
+### Added
+
+- Multi-file editing capability for edit_file tool
+  - Support for editing up to 50 files in a single operation
+  - Mode discriminator (single/multiple) for backward compatibility
+  - Atomic operations with automatic rollback on failure
+  - Per-file configuration options (matching strategy, dryRun, failOnAmbiguous)
+  - Concurrent file processing for improved performance
+  - Detailed multi-file diff output with summary statistics
+- Comprehensive test suite for multi-file editing functionality
+- Implementation plan documentation in local_docs folder
+
+### Changed
+
+- Enhanced edit_file tool schema to support both single and multi-file modes
+- Updated README documentation with complete edit_file feature specification
+- Improved EditFileArgsSchema with explicit mode parameter for better MCP client compatibility
+
+### Fixed
+
+- Test timeout issues in shell-tool.test.ts and shell-command-path-validation.test.ts
+
 ## [1.0.1] - 2025-11-03
 
 ### Security

package/README.md

@@ -1,13 +1,12 @@
 # Vulcan File Ops MCP Server
 
 ![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)
+![MCP Dev](https://badge.mcpx.dev?type=dev "MCP Dev")
 [![MCP Server](https://badge.mcpx.dev?type=server "MCP Server")](https://modelcontextprotocol.io)
 [![MCP Server with Tools](https://badge.mcpx.dev?type=server&features=tools "MCP server with tools")](https://modelcontextprotocol.io)
 [![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A configurable Model Context Protocol server for secure filesystem operations that absolutely **rocks**. Enables AI assistants to dynamically access and manage file system resources with runtime directory registration and selective tool activation.
-
 **Transform your desktop AI assistants into powerful development partners.** Vulcan File Ops bridges the gap between conversational AI (Claude Desktop, ChatGPT Desktop, etc.) and your local filesystem, unlocking the same file manipulation capabilities found in AI-powered IDEs like Cursor and Cline. Write code, refactor projects, manage documentation, and perform complex file operations—matching the power of dedicated AI coding assistants. With enterprise-grade security controls, dynamic directory registration, and intelligent tool filtering, you maintain complete control while your AI assistant handles the heavy lifting.
 
 ## Table of Contents
@@ -54,7 +53,7 @@ This enhanced implementation provides:
 
 - **Dynamic Directory Access**: Runtime directory registration through conversational commands
 - **Document Support**: Read/write PDF, DOCX, PPTX, XLSX, ODT with HTML-to-document conversion
-- **Batch Operations**: Read, write, copy, move, or rename multiple files concurrently
+- **Batch Operations**: Read, write, edit, copy, move, or rename multiple files concurrently
 - **Advanced File Editing**: Pattern-based modifications with flexible matching and diff preview
 - **Flexible Reading Modes**: Full file, head/tail, or arbitrary line ranges
 - **Image Vision Support**: Attach images for AI analysis and description
@@ -76,28 +75,70 @@ This server supports multiple flexible approaches to directory access:
 
 ## Install
 
-This server requires Node.js and can be installed locally for full control.
+This server requires Node.js and can be installed globally, locally, or run directly with npx. **Most users should use npx** for instant execution without installation.
+
+### Quick Start (Recommended for Most Users)
+
+Run directly without installation:
 
 ```bash
-npm install -g vulcan-file-ops
+npx @n0zer0d4y/vulcan-file-ops --help
 ```
 
-Or install in a specific project:
+**For developers** who want to contribute or modify the code, see [Local Repository Execution](#option-4-local-repository-execution-for-developers) below.
+
+### Global Installation
+
+Install globally for system-wide access:
 
 ```bash
-npm install vulcan-file-ops
+npm install -g @n0zer0d4y/vulcan-file-ops
 ```
 
+### Local Installation
+
+Install in a specific project:
+
+```bash
+npm install @n0zer0d4y/vulcan-file-ops
+```
+
+### Prerequisites
+
+**Node.js** (version 14 or higher) must be installed on your system. This provides npm and npx, which are required to run this package.
+
+- **Download Node.js**: https://nodejs.org/
+- **Check installation**: Run `node --version` and `npm --version`
+
 ### Dependencies
 
-Requires Node.js with support for ES2022 modules. The server has no external service dependencies and operates entirely locally.
+The server has no external service dependencies and operates entirely locally. All required packages are automatically downloaded when using npx.
 
 ## Usage
 
+This server can be used directly with npx (recommended) or installed globally/locally. The npx approach requires no installation and always uses the latest version.
+
 ### Basic Configuration
 
 Add to your MCP client configuration (e.g., `claude_desktop_config.json`):
 
+#### Option 1: Using npx (Recommended - No Installation Required)
+
+```json
+{
+  "mcpServers": {
+    "vulcan-file-ops": {
+      "command": "npx",
+      "args": ["@n0zer0d4y/vulcan-file-ops"]
+    }
+  }
+}
+```
+
+#### Option 2: Using Global Installation
+
+After running `npm install -g @n0zer0d4y/vulcan-file-ops`:
+
 ```json
 {
   "mcpServers": {
@@ -108,20 +149,61 @@ Add to your MCP client configuration (e.g., `claude_desktop_config.json`):
 }
 ```
 
+#### Option 3: Using Local Installation
+
+After running `npm install @n0zer0d4y/vulcan-file-ops` in your project:
+
+```json
+{
+  "mcpServers": {
+    "vulcan-file-ops": {
+      "command": "./node_modules/.bin/vulcan-file-ops"
+    }
+  }
+}
+```
+
+#### Option 4: Local Repository Execution (For Developers)
+
+If you've cloned this repository and want to run from source:
+
+```bash
+git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
+cd vulcan-file-ops
+npm install
+npm run build
+```
+
+Then configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "vulcan-file-ops": {
+      "command": "vulcan-file-ops",
+      "args": ["--approved-folders", "/path/to/your/allowed/directories"]
+    }
+  }
+}
+```
+
+**Note:** The `vulcan-file-ops` command will be available in your PATH after building, or you can use the full path: `./dist/cli.js`
+
 ### Advanced Configuration
 
 #### Approved Folders
 
 Pre-configure specific directories for immediate access on server start:
 
-**macOS/Linux:**
+**macOS/Linux (npx):**
 
 ```json
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
+      "command": "npx",
       "args": [
+        "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
         "/Users/username/projects,/Users/username/documents"
       ]
@@ -130,14 +212,15 @@ Pre-configure specific directories for immediate access on server start:
 }
 ```
 
-**Windows:**
+**Windows (npx):**
 
 ```json
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
+      "command": "npx",
       "args": [
+        "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
         "C:/Users/username/projects,C:/Users/username/documents"
       ]
@@ -146,6 +229,24 @@ Pre-configure specific directories for immediate access on server start:
 }
 ```
 
+**Alternative: Local Repository Execution**
+
+For users running from a cloned repository (after `npm run build`):
+
+```json
+{
+  "mcpServers": {
+    "vulcan-file-ops": {
+      "command": "vulcan-file-ops",
+      "args": [
+        "--approved-folders",
+        "/Users/username/projects,/Users/username/documents"
+      ]
+    }
+  }
+}
+```
+
 **Path Format Note:**
 
 - **Windows**: Include drive letter (e.g., `C:/`, `D:/`). Use forward slashes in JSON to avoid escaping backslashes.
@@ -194,8 +295,12 @@ Exclude specific folders from directory listings:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
-      "args": ["--ignored-folders", "node_modules,dist,.git,.next"]
+      "command": "npx",
+      "args": [
+        "@n0zer0d4y/vulcan-file-ops",
+        "--ignored-folders",
+        "node_modules,dist,.git,.next"
+      ]
     }
   }
 }
@@ -209,8 +314,12 @@ Enable only specific tool categories:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
-      "args": ["--enabled-tool-categories", "read,filesystem"]
+      "command": "npx",
+      "args": [
+        "@n0zer0d4y/vulcan-file-ops",
+        "--enabled-tool-categories",
+        "read,filesystem"
+      ]
     }
   }
 }
@@ -222,8 +331,12 @@ Or enable individual tools:
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
-      "args": ["--enabled-tools", "read_file,list_directory,search_files"]
+      "command": "npx",
+      "args": [
+        "@n0zer0d4y/vulcan-file-ops",
+        "--enabled-tools",
+        "read_file,list_directory,grep_files"
+      ]
     }
   }
 }
@@ -233,14 +346,15 @@ Or enable individual tools:
 
 All configuration options can be combined:
 
-**Windows Example:**
+**Windows Example (npx):**
 
 ```json
 {
   "mcpServers": {
     "vulcan-file-ops": {
-      "command": "vulcan-file-ops",
+      "command": "npx",
       "args": [
+        "@n0zer0d4y/vulcan-file-ops",
         "--approved-folders",
         "C:/Users/username/projects,C:/Users/username/documents",
         "--ignored-folders",
@@ -250,14 +364,41 @@ All configuration options can be combined:
         "--enabled-tool-categories",
         "read,filesystem,shell",
         "--enabled-tools",
-        "list_directory,search_files,register_directory,execute_shell"
+        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
       ]
     }
   }
 }
 ```
 
-**macOS/Linux Example:**
+**macOS/Linux Example (npx):**
+
+```json
+{
+  "mcpServers": {
+    "vulcan-file-ops": {
+      "command": "npx",
+      "args": [
+        "@n0zer0d4y/vulcan-file-ops",
+        "--approved-folders",
+        "/Users/username/projects,/Users/username/documents",
+        "--ignored-folders",
+        "node_modules,dist,.git",
+        "--approved-commands",
+        "npm,node,git,ls,pwd,cat,echo",
+        "--enabled-tool-categories",
+        "read,filesystem,shell",
+        "--enabled-tools",
+        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
+      ]
+    }
+  }
+}
+```
+
+**Alternative: Local Repository Execution**
+
+For users running from a cloned repository (after `npm run build`):
 
 ```json
 {
@@ -274,7 +415,7 @@ All configuration options can be combined:
         "--enabled-tool-categories",
         "read,filesystem,shell",
         "--enabled-tools",
-        "list_directory,search_files,register_directory,execute_shell"
+        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
       ]
     }
   }
@@ -360,20 +501,46 @@ Create or replace multiple files concurrently
 
 ##### edit_file
 
-Intelligent file modification with pattern matching
+Apply precise modifications to text and code files with intelligent matching. Supports both single-file and multi-file operations.
 
-**Input:**
+**Single File Input (mode: 'single'):**
 
+- `mode` (string, optional): Set to `"single"` (default if omitted for backward compatibility)
 - `path` (string): File path
-- `edits` (array): List of edit operations (oldText, newText)
-- `dryRun` (boolean, optional): Preview changes without writing
+- `edits` (array): List of edit operations, each containing:
+  - `oldText` (string): Text to search for (include 3-5 lines of context)
+  - `newText` (string): Text to replace with
+  - `instruction` (string, optional): Description of what this edit does
+  - `expectedOccurrences` (number, optional): Expected match count (default: 1)
 - `matchingStrategy` (string, optional): Matching strategy
-  - `exact` - Character-for-character match
-  - `flexible` - Whitespace-insensitive matching
-  - `fuzzy` - Token-based regex matching
+  - `exact` - Character-for-character match (fastest, safest)
+  - `flexible` - Whitespace-insensitive matching, preserves indentation
+  - `fuzzy` - Token-based regex matching (most permissive)
   - `auto` - Try exact → flexible → fuzzy (default)
+- `dryRun` (boolean, optional): Preview changes without writing (default: false)
+- `failOnAmbiguous` (boolean, optional): Fail when matches are ambiguous (default: true)
+
+**Multi-File Input (mode: 'multiple'):**
+
+- `mode` (string): Set to `"multiple"`
+- `files` (array): Array of file edit requests (max 50), each containing:
+  - `path` (string): File path
+  - `edits` (array): List of edit operations for this file (same structure as above)
+  - `matchingStrategy` (string, optional): Per-file matching strategy
+  - `dryRun` (boolean, optional): Per-file dry-run mode
+  - `failOnAmbiguous` (boolean, optional): Per-file ambiguity handling
+- `failFast` (boolean, optional): Stop on first failure with rollback (true, default) or continue (false)
 
-**Output:** Detailed diff with statistics showing changes made
+**Features:**
+
+- Concurrent processing for multi-file operations
+- Atomic operations with automatic rollback on failure (when failFast: true)
+- Cross-platform line ending preservation
+- Detailed diff output with statistics
+
+**Output:** Detailed diff with statistics. For multi-file operations, includes per-file results and summary statistics with rollback information for atomic operations.
+
+**Important:** Use actual newline characters in oldText/newText, NOT escape sequences like `\n`.
 
 #### Filesystem Operations
 
@@ -525,6 +692,76 @@ Execute shell commands with security controls
 
 **Security:** All file/directory paths in command arguments are automatically extracted and validated against allowed directories. Commands referencing paths outside approved directories are blocked, preventing directory restriction bypasses.
 
+### Multi-File Edit Examples
+
+**Batch refactor across multiple files:**
+
+```typescript
+{
+  files: [
+    {
+      path: "src/utils.ts",
+      edits: [{
+        instruction: "Update deprecated function call",
+        oldText: "oldApi.getData()",
+        newText: "newApi.fetchData()"
+      }]
+    },
+    {
+      path: "src/components/Button.tsx",
+      edits: [{
+        instruction: "Update component prop",
+        oldText: "onClick={oldHandler}",
+        newText: "onClick={newHandler}"
+      }]
+    },
+    {
+      path: "src/hooks/useData.ts",
+      edits: [{
+        instruction: "Update hook implementation",
+        oldText: "const data = oldApi.getData()",
+        newText: "const data = newApi.fetchData()"
+      }]
+    }
+  ],
+  failFast: true  // Atomic operation - rollback all if any fails
+}
+```
+
+**Per-file configuration:**
+
+```typescript
+{
+  files: [
+    {
+      path: "config.json",
+      edits: [{
+        oldText: '"version": "1.0.0"',
+        newText: '"version": "1.1.0"'
+      }],
+      matchingStrategy: "exact"  // JSON needs exact matches
+    },
+    {
+      path: "src/app.py",
+      edits: [{
+        oldText: "def old_function():",
+        newText: "def new_function():"
+      }],
+      matchingStrategy: "flexible"  // Python indentation may vary
+    },
+    {
+      path: "README.md",
+      edits: [{
+        oldText: "## Old Section",
+        newText: "## New Section"
+      }],
+      matchingStrategy: "auto"  // Let AI decide best strategy
+    }
+  ],
+  failFast: false  // Continue even if some files fail
+}
+```
+
 ---
 
 For detailed usage examples, see [Tool Usage Guide](docs/TOOL_USAGE_GUIDE.md)

package/dist/tools/write-tools.js

@@ -3,7 +3,7 @@ import { ToolSchema } from "@modelcontextprotocol/sdk/types.js";
 import path from "path";
 import { promises as fs } from "fs";
 import { WriteFileArgsSchema, WriteMultipleFilesArgsSchema, EditFileArgsSchema, } from "../types/index.js";
-import { validatePath, writeFileContent, applyFileEdits, } from "../utils/lib.js";
+import { validatePath, writeFileContent, readFileContent, applyFileEdits, } from "../utils/lib.js";
 import { isHTMLContent, convertHTMLToPDF, convertHTMLToDOCX, } from "../utils/html-to-document.js";
 const ToolInputSchema = ToolSchema.shape.inputSchema;
 /**
@@ -53,6 +53,169 @@ async function writeFileBasedOnExtension(validPath, content) {
         await writeFileContent(validPath, content);
     }
 }
+async function processFileEditRequest(request, failOnAmbiguous = true) {
+    try {
+        const validPath = await validatePath(request.path);
+        const result = await applyFileEdits(validPath, request.edits, request.dryRun || false, request.matchingStrategy || "auto", request.failOnAmbiguous !== undefined
+            ? request.failOnAmbiguous
+            : failOnAmbiguous, true // Return metadata
+        );
+        if (typeof result === "string") {
+            throw new Error("Expected metadata but got string result");
+        }
+        // Aggregate metadata from all edits
+        const totalOccurrences = result.metadata.reduce((sum, r) => sum + r.occurrences, 0);
+        const usedStrategies = [...new Set(result.metadata.map((r) => r.strategy))];
+        const finalStrategy = result.metadata[result.metadata.length - 1]?.strategy || "exact";
+        const warning = result.metadata.find((r) => r.warning)?.warning;
+        const ambiguity = result.metadata.find((r) => r.ambiguity)?.ambiguity;
+        return {
+            path: request.path,
+            success: true,
+            strategy: finalStrategy,
+            occurrences: totalOccurrences,
+            diff: result.diff,
+            dryRun: request.dryRun,
+        };
+    }
+    catch (error) {
+        return {
+            path: request.path,
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function processMultiFileEdits(files, failFast = true) {
+    const results = [];
+    const rollbackData = [];
+    let hasFailures = false;
+    try {
+        // Process files sequentially if failFast is true, concurrently if false
+        if (failFast) {
+            // Process sequentially to stop on first failure
+            for (const request of files) {
+                // For rollback capability, read original content before editing
+                let originalContent;
+                if (failFast && !request.dryRun) {
+                    try {
+                        originalContent = await readFileContent(await validatePath(request.path));
+                    }
+                    catch (error) {
+                        // If we can't read the original content, we can't provide rollback
+                        // This is acceptable - the file might not exist or be readable
+                    }
+                }
+                const result = await processFileEditRequest(request);
+                results.push(result);
+                // Track successful edits for potential rollback
+                if (result.success &&
+                    !request.dryRun &&
+                    originalContent !== undefined) {
+                    rollbackData.push({
+                        path: request.path,
+                        originalContent,
+                    });
+                }
+                if (!result.success) {
+                    hasFailures = true;
+                    // Rollback all previously successful edits
+                    await performRollback(rollbackData);
+                    break; // Stop processing remaining files
+                }
+            }
+        }
+        else {
+            // Process all concurrently, collect all results (no rollback for concurrent mode)
+            const promises = files.map((request) => processFileEditRequest(request));
+            const allResults = await Promise.allSettled(promises);
+            for (let i = 0; i < allResults.length; i++) {
+                const settled = allResults[i];
+                const request = files[i];
+                if (settled.status === "fulfilled") {
+                    results.push(settled.value);
+                    if (!settled.value.success)
+                        hasFailures = true;
+                }
+                else {
+                    // Handle unexpected promise rejections
+                    results.push({
+                        path: request.path,
+                        success: false,
+                        error: `Unexpected error: ${settled.reason}`,
+                    });
+                    hasFailures = true;
+                }
+            }
+        }
+    }
+    catch (error) {
+        // If there's an unexpected error during processing, attempt rollback
+        if (failFast && rollbackData.length > 0) {
+            await performRollback(rollbackData);
+        }
+        throw error;
+    }
+    return {
+        results,
+        summary: {
+            total: files.length,
+            successful: results.filter((r) => r.success).length,
+            failed: results.filter((r) => !r.success).length,
+            hasFailures,
+            failFast,
+        },
+    };
+}
+async function performRollback(rollbackData) {
+    for (const item of rollbackData.reverse()) {
+        // Rollback in reverse order
+        try {
+            await writeFileContent(item.path, item.originalContent);
+        }
+        catch (rollbackError) {
+            // Log rollback failure but don't throw - we want to attempt all rollbacks
+            console.error(`Failed to rollback ${item.path}: ${rollbackError}`);
+        }
+    }
+}
+function formatMultiFileEditResults(editResults) {
+    let output = "";
+    // Summary header
+    output += `Multi-File Edit Summary:\n`;
+    output += `Total files: ${editResults.summary.total}\n`;
+    output += `Successful: ${editResults.summary.successful}\n`;
+    output += `Failed: ${editResults.summary.failed}\n`;
+    output += `Mode: ${editResults.summary.failFast ? "failFast (atomic)" : "continueOnError"}\n`;
+    if (editResults.summary.failFast && editResults.summary.hasFailures) {
+        output += `⚠️  Atomic operation failed - all successful edits were rolled back\n`;
+    }
+    output += `\n`;
+    // Individual file results
+    editResults.results.forEach((result, index) => {
+        output += `File ${index + 1}: ${result.path}\n`;
+        output += `Status: ${result.success ? "✓ SUCCESS" : "✗ FAILED"}\n`;
+        if (result.success) {
+            if (result.strategy) {
+                output += `Strategy: ${result.strategy}\n`;
+            }
+            if (result.occurrences !== undefined) {
+                output += `Occurrences: ${result.occurrences}\n`;
+            }
+            if (result.dryRun) {
+                output += `Mode: DRY RUN (no changes made)\n`;
+            }
+            if (result.diff) {
+                output += `\n${result.diff}\n`;
+            }
+        }
+        else {
+            output += `Error: ${result.error}\n`;
+        }
+        output += "\n" + "=".repeat(50) + "\n\n";
+    });
+    return output.trim();
+}
 export function getWriteTools() {
     return [
         {
@@ -80,31 +243,34 @@ export function getWriteTools() {
         },
         {
             name: "edit_file",
-            description: "Apply precise modifications to text and code files with intelligent matching. " +
-                "Performs exact text substitution with automatic fallback to flexible whitespace-insensitive matching " +
-                "and fuzzy token-based matching for maximum reliability. " +
-                "Supports multiple sequential edits in a single operation. " +
-                "Provides detailed diff output with change statistics and strategy information. " +
-                "Preserves original file formatting including indentation and line endings. " +
-                "\n\n" +
-                "Matching Strategies (in order when using 'auto'):\n" +
+            description: "Apply precise modifications to text and code files with intelligent matching.\n\n" +
+                "**Single File Editing (mode: 'single'):**\n" +
+                "Edit one file with multiple sequential edits using exact, flexible, or fuzzy matching strategies.\n\n" +
+                "**Multi-File Editing (mode: 'multiple'):**\n" +
+                "Edit multiple files concurrently in a single operation. Each file can have its own edit configuration.\n\n" +
+                "**Matching Strategies:**\n" +
                 "1. Exact: Character-for-character match (fastest, safest)\n" +
                 "2. Flexible: Whitespace-insensitive, preserves original indentation\n" +
-                "3. Fuzzy: Token-based regex matching for maximum compatibility\n" +
-                "\n" +
-                "Best Practices:\n" +
+                "3. Fuzzy: Token-based regex matching for maximum compatibility\n\n" +
+                "**Features:**\n" +
+                "- Concurrent processing for multi-file operations\n" +
+                "- Per-file matching strategy control\n" +
+                "- Dry-run preview mode\n" +
+                "- Detailed diff output with statistics\n" +
+                "- Atomic operations with rollback capability\n" +
+                "- Cross-platform line ending preservation\n\n" +
+                "**Maximum:** 50 files per multi-file operation\n\n" +
+                "**Best Practices:**\n" +
                 "- Include 3-5 lines of context before and after the change for reliability\n" +
                 "- Add 'instruction' field to describe the purpose of each edit\n" +
                 "- Use 'dryRun: true' to preview changes before applying\n" +
                 "- For multiple related changes, use array of edits (applied sequentially)\n" +
                 "- Set 'expectedOccurrences' to validate replacement count\n" +
-                "- Use 'matchingStrategy' to control matching behavior (defaults to 'auto')\n" +
-                "\n" +
-                "CRITICAL - Multi-line Content:\n" +
+                "- Use 'matchingStrategy' to control matching behavior (defaults to 'auto')\n\n" +
+                "**CRITICAL - Multi-line Content:**\n" +
                 "- Use actual newline characters in oldText/newText strings, NOT \\n escape sequences\n" +
                 "- The MCP/JSON layer handles encoding automatically\n" +
-                "- Using \\n literally will search for/write backslash+n characters (wrong!)\n" +
-                "\n" +
+                "- Using \\n literally will search for/write backslash+n characters (wrong!)\n\n" +
                 "Only works within allowed directories.",
             inputSchema: zodToJsonSchema(EditFileArgsSchema),
         },
@@ -146,11 +312,41 @@ export async function handleWriteTool(name, args) {
             if (!parsed.success) {
                 throw new Error(`Invalid arguments for edit_file: ${parsed.error}`);
             }
-            const validPath = await validatePath(parsed.data.path);
-            const result = await applyFileEdits(validPath, parsed.data.edits, parsed.data.dryRun, parsed.data.matchingStrategy, parsed.data.failOnAmbiguous);
-            return {
-                content: [{ type: "text", text: result }],
-            };
+            // Determine mode and route to appropriate handler
+            const mode = parsed.data.mode || "single";
+            if (mode === "single") {
+                // Single file mode (backward compatible)
+                if (!parsed.data.path || !parsed.data.edits) {
+                    throw new Error("Single mode requires 'path' and 'edits' fields");
+                }
+                const result = await processFileEditRequest({
+                    path: parsed.data.path,
+                    edits: parsed.data.edits,
+                    matchingStrategy: parsed.data.matchingStrategy,
+                    dryRun: parsed.data.dryRun,
+                    failOnAmbiguous: parsed.data.failOnAmbiguous,
+                });
+                if (!result.success) {
+                    throw new Error(result.error);
+                }
+                return {
+                    content: [{ type: "text", text: result.diff }],
+                };
+            }
+            else if (mode === "multiple") {
+                // Multi-file mode
+                if (!parsed.data.files) {
+                    throw new Error("Multiple mode requires 'files' field");
+                }
+                const editResults = await processMultiFileEdits(parsed.data.files, parsed.data.failFast);
+                const output = formatMultiFileEditResults(editResults);
+                return {
+                    content: [{ type: "text", text: output }],
+                };
+            }
+            else {
+                throw new Error(`Invalid mode: ${mode}`);
+            }
         }
         case "write_multiple_files": {
             const parsed = WriteMultipleFilesArgsSchema.safeParse(args);

package/dist/types/index.js

@@ -192,17 +192,66 @@ export const EditOperation = z.object({
         "Set to a specific number to validate the replacement count. " +
         "The tool will fail if actual occurrences don't match this number."),
 });
-export const EditFileArgsSchema = z.object({
-    path: z.string(),
+// Single file edit request (for multi-file operations)
+export const EditFileRequestSchema = z.object({
+    path: z.string().describe("Path to the file to edit"),
     edits: z
         .array(EditOperation)
         .min(1, "At least one edit must be provided")
-        .describe("Array of edits to apply sequentially"),
+        .describe("Array of edits to apply to this file"),
+    matchingStrategy: z
+        .enum(["exact", "flexible", "fuzzy", "auto"])
+        .optional()
+        .default("auto")
+        .describe("Matching strategy for this file:\n" +
+        "- 'exact': Strict character-for-character match (fastest, safest)\n" +
+        "- 'flexible': Whitespace-insensitive line-by-line matching\n" +
+        "- 'fuzzy': Token-based regex matching (most permissive)\n" +
+        "- 'auto': Try exact → flexible → fuzzy (recommended, default)"),
     dryRun: z
         .boolean()
         .optional()
         .default(false)
-        .describe("Preview changes using git-style diff format without writing"),
+        .describe("Preview changes for this file without writing"),
+    failOnAmbiguous: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("If true, fail when oldText matches multiple locations (unless expectedOccurrences > 1). " +
+        "If false, replace first occurrence only and warn about ambiguity."),
+});
+// Enhanced edit file schema (supports both single and multi-file with explicit mode)
+export const EditFileArgsSchema = z
+    .object({
+    // Mode discriminator
+    mode: z
+        .enum(["single", "multiple"])
+        .optional()
+        .default("single")
+        .describe("Edit mode: 'single' for one file, 'multiple' for batch editing"),
+    // Single file fields (required when mode is "single")
+    path: z
+        .string()
+        .optional()
+        .describe("Path to file (required for single mode)"),
+    edits: z
+        .array(EditOperation)
+        .min(1)
+        .optional()
+        .describe("Array of edits to apply"),
+    // Multi-file fields (required when mode is "multiple")
+    files: z
+        .array(EditFileRequestSchema)
+        .min(1, "At least one file must be provided")
+        .max(50, "Maximum 50 files per operation")
+        .optional()
+        .describe("Array of file edit requests (required for multiple mode)"),
+    failFast: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Stop processing on first file failure (true) or continue with remaining files (false)"),
+    // Global options
     matchingStrategy: z
         .enum(["exact", "flexible", "fuzzy", "auto"])
         .optional()
@@ -212,13 +261,31 @@ export const EditFileArgsSchema = z.object({
         "- 'flexible': Whitespace-insensitive line-by-line matching\n" +
         "- 'fuzzy': Token-based regex matching (most permissive)\n" +
         "- 'auto': Try exact → flexible → fuzzy (recommended, default)"),
+    dryRun: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Preview changes without writing"),
     failOnAmbiguous: z
         .boolean()
         .optional()
         .default(true)
         .describe("If true, fail when oldText matches multiple locations (unless expectedOccurrences > 1). " +
         "If false, replace first occurrence only and warn about ambiguity."),
-});
+})
+    .refine((data) => {
+    // Validate based on mode
+    if (data.mode === "single") {
+        return data.path && data.edits;
+    }
+    else if (data.mode === "multiple") {
+        return data.files;
+    }
+    return false;
+}, {
+    message: "Invalid configuration: 'path' and 'edits' required for single mode, 'files' required for multiple mode",
+})
+    .describe("Edit files with intelligent matching. Supports single file or batch multi-file operations.");
 export const MakeDirectoryArgsSchema = z.object({
     paths: z
         .union([z.string(), z.array(z.string())])

package/dist/utils/lib.js

@@ -518,7 +518,7 @@ function applyEditWithStrategy(content, edit, strategy, failOnAmbiguous) {
     }
     return result;
 }
-export async function applyFileEdits(filePath, edits, dryRun = false, matchingStrategy = "auto", failOnAmbiguous = true) {
+export async function applyFileEdits(filePath, edits, dryRun = false, matchingStrategy = "auto", failOnAmbiguous = true, returnMetadata) {
     // Read file content and detect original line ending
     const rawContent = await fs.readFile(filePath, "utf-8");
     const originalLineEnding = detectLineEnding(rawContent);
@@ -561,6 +561,12 @@ export async function applyFileEdits(filePath, edits, dryRun = false, matchingSt
             throw error;
         }
     }
+    if (returnMetadata) {
+        return {
+            diff: formattedDiff,
+            metadata: editResults
+        };
+    }
     return formattedDiff;
 }
 // Memory-efficient implementation to get the last N lines of a file

package/package.json

@@ -1,17 +1,42 @@
 {
   "name": "@n0zer0d4y/vulcan-file-ops",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "MCP server that gives Claude Desktop and other AI assistants filesystem superpowers—read, write, edit, and manage files like AI coding assistants",
   "license": "MIT",
   "author": "Lloyd Barcatan",
   "homepage": "https://github.com/n0zer0d4y/vulcan-file-ops",
   "repository": {
     "type": "git",
-    "url": "https://github.com/n0zer0d4y/vulcan-file-ops.git"
+    "url": "git+https://github.com/n0zer0d4y/vulcan-file-ops.git"
   },
   "bugs": {
     "url": "https://github.com/n0zer0d4y/vulcan-file-ops/issues"
   },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "context-engineering",
+    "ai",
+    "ai-tools",
+    "claude",
+    "claude-desktop",
+    "filesystem",
+    "file-operations",
+    "file-management",
+    "read-files",
+    "write-files",
+    "edit-files",
+    "ai-assistant",
+    "llm",
+    "llm-tools",
+    "pdf",
+    "docx",
+    "document-parsing",
+    "code-editor",
+    "typescript",
+    "ai-assisted-coding"
+  ],
   "type": "module",
   "bin": {
     "vulcan-file-ops": "dist/cli.js"