Batch Operations

Batch Operations Guide

Overview

The batch_operations tool allows you to execute multiple file operations atomically with automatic rollback on failure. This is perfect for complex multi-step operations where you need all-or-nothing execution.

Key Features

Atomic Transactions: All operations succeed or all are rolled back
Automatic Backups: Creates backups before destructive operations
Pre-execution Validation: Validates all operations before executing
Rollback on Failure: Automatically reverts changes if any operation fails
Progress Tracking: Detailed results for each operation
Validate-Only Mode: Test operations without executing them

Supported Operations

The batch_operations tool supports 8 operation types (was 6 before v4.5.14):

1. `write` - Write file

{
  "type": "write",
  "path": "/path/to/file.txt",
  "content": "file content here"
}

2. `edit` - Edit file content

{
  "type": "edit",
  "path": "/path/to/file.txt",
  "old_text": "text to replace",
  "new_text": "new text"
}

3. `search_and_replace` - Global find/replace inside a file

Added in v4.5.x as part of the 8-operation set:

{
  "type": "search_and_replace",
  "path": "/path/to/file.txt",
  "old_text": "pattern to find",
  "new_text": "replacement text"
}

4. `move` - Move/rename file

{
  "type": "move",
  "source": "/path/to/old.txt",
  "destination": "/path/to/new.txt"
}

5. `copy` - Copy file

{
  "type": "copy",
  "source": "/path/to/source.txt",
  "destination": "/path/to/destination.txt"
}

6. `delete` - Delete file

{
  "type": "delete",
  "path": "/path/to/file.txt"
}

7. `create_dir` - Create directory

{
  "type": "create_dir",
  "path": "/path/to/new/directory"
}

8. `extract` - Atomically move lines between files (v4.5.14)

Moves lines [start_line, end_line] from source to destination using the same computed bytes — written == deleted by construction, so the two halves cannot drift. Both writes are atomic (temp + rename) and revert together under atomic:true.

{
  "type": "extract",
  "source": "old-file.txt",
  "destination": "new-file.txt",
  "start_line": 10,
  "end_line": 25,
  "append": false
}

Fields:

Field	Required	Description
`source`	Yes	File to remove lines from
`destination`	Yes	File to receive the moved lines
`start_line`	Yes	1-indexed start line (inclusive)
`end_line`	Yes	1-indexed end line (inclusive)
`append`	No	If true, append to existing destination content (default false — overwrites)

Single-file equivalent: edit_file({ path, mode:"delete_range", start_line, end_line }).

Usage Examples

Example 1: Simple Batch Write

{
  "tool": "batch_operations",
  "arguments": {
    "request_json": "{\"operations\":[{\"type\":\"write\",\"path\":\"C:\\\\temp\\\\file1.txt\",\"content\":\"Hello\"},{\"type\":\"write\",\"path\":\"C:\\\\temp\\\\file2.txt\",\"content\":\"World\"}],\"atomic\":true,\"create_backup\":true}"
  }
}

Example 2: Refactoring Multiple Files

{
  "operations": [
    {
      "type": "edit",
      "path": "src/utils.js",
      "old_text": "function oldName(",
      "new_text": "function newName("
    },
    {
      "type": "edit",
      "path": "src/index.js",
      "old_text": "oldName()",
      "new_text": "newName()"
    },
    {
      "type": "edit",
      "path": "tests/utils.test.js",
      "old_text": "oldName()",
      "new_text": "newName()"
    }
  ],
  "atomic": true,
  "create_backup": true
}

Example 3: Reorganize Project Structure

{
  "operations": [
    {
      "type": "create_dir",
      "path": "src/components"
    },
    {
      "type": "move",
      "source": "Header.js",
      "destination": "src/components/Header.js"
    },
    {
      "type": "move",
      "source": "Footer.js",
      "destination": "src/components/Footer.js"
    },
    {
      "type": "write",
      "path": "src/components/index.js",
      "content": "export { Header } from './Header';\nexport { Footer } from './Footer';"
    }
  ],
  "atomic": true,
  "create_backup": true
}

Example 4: Validation Only (Dry Run)

{
  "operations": [
    {"type": "delete", "path": "important.txt"},
    {"type": "write", "path": "backup.txt", "content": "backup"}
  ],
  "atomic": true,
  "create_backup": true,
  "validate_only": true
}

Request Parameters

`operations` (required)

Array of operations to execute. Each operation must have a type field and type-specific fields.

`atomic` (optional, default: `true`)

If true, all operations are rolled back if any single operation fails.

`create_backup` (optional, default: `true`)

If true, creates a timestamped backup of all affected files before execution.

`validate_only` (optional, default: `false`)

If true, only validates operations without executing them. Useful for testing.

Response Format

Success Response

✅ Batch Operations Completed Successfully
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary:
  Total operations: 3
  Completed: 3
  Failed: 0
  Execution time: 45.2ms
  Backup created: C:\Temp\mcp-batch-backups\batch-20250124-153045

📋 Operation Details:
  ✓ [0] write: C:\temp\file1.txt (5 B)
  ✓ [1] write: C:\temp\file2.txt (5 B)
  ✓ [2] move: old.txt (1.2 KB)

Failure Response (with Rollback)

❌ Batch Operations Failed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary:
  Total operations: 3
  Completed: 1
  Failed: 1
  Execution time: 23.1ms
  Backup created: C:\Temp\mcp-batch-backups\batch-20250124-153045

⚠️  Rollback performed - all changes reverted

📋 Operation Details:
  ✓ [0] write: C:\temp\file1.txt (5 B)
  ✗ [1] write: C:\temp\readonly.txt - Error: permission denied

❌ Errors:
  • Operation 1 failed, rollback completed: permission denied

Validation-Only Response

✅ Batch Validation Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ All 3 operations validated successfully
✓ Ready to execute

Best Practices

{
  "operations": [...],
  "atomic": true  // ✅ Ensures consistency
}

2. Create Backups for Destructive Operations

{
  "operations": [
    {"type": "delete", "path": "file.txt"}
  ],
  "create_backup": true  // ✅ Safety net
}

3. Validate First for Critical Operations

// Step 1: Validate
{
  "operations": [...],
  "validate_only": true
}

// Step 2: If validation succeeds, execute
{
  "operations": [...],
  "validate_only": false
}

4. Order Operations Carefully

Operations execute in sequence. Ensure dependencies are ordered correctly:

{
  "operations": [
    {"type": "create_dir", "path": "new_folder"},  // ✅ Create folder first
    {"type": "write", "path": "new_folder/file.txt", "content": "..."}  // ✅ Then write file
  ]
}

Error Handling

Validation Errors

If validation fails, you’ll get a detailed error response:

✗ Validation failed
Errors:
  • Op 0: parent directory does not exist: /nonexistent
  • Op 2: file does not exist: /missing.txt

Execution Errors

If execution fails and atomic: true:

All completed operations are automatically rolled back
Original state is restored
Detailed error message is provided

If atomic: false:

Operations continue despite failures
Partial results are returned
No rollback occurs

Use Cases

1. Code Refactoring

Rename functions/variables across multiple files atomically.

2. Project Restructuring

Move files, create directories, update imports - all or nothing.

3. Configuration Updates

Update multiple config files together, rollback if any fails.

4. Database Migrations

Apply schema changes across multiple files atomically.

5. Deployment Preparation

Copy files, update versions, create backups - all in one transaction.

Performance Notes

Validation: ~1-5ms per operation
Backup Creation: Depends on file sizes
Execution: Depends on operation type
Rollback: Usually faster than forward execution

Backup Management

Backups are stored in:

Windows: %TEMP%\mcp-batch-backups\
Linux/Mac: /tmp/mcp-batch-backups/

Backups include:

Timestamped folder (e.g., batch-20250124-153045)
Original files before modification
metadata.json with operation details

Old backups are automatically cleaned, keeping only the last 100 (configurable with --backup-max-count and --backup-max-age).

Other Modes

batch_operations has three input modes. Provide exactly one of:

request_json — atomic multi-file operations (this page)
pipeline_json — multi-step transformation pipelines (see Pipelines)
rename_json — bulk file rename (see Tool Selection Guide)

Limitations

Maximum operations per batch: No hard limit (recommended < 100)
File size limits: Same as individual operations
Nested transactions: Not supported
Concurrent batches: Managed via mutex (one at a time)
Edit operations in batch_operations use simple string replacement (not fuzzy matching)

Example: Complete Workflow

{
  "operations": [
    {
      "type": "create_dir",
      "path": "backup"
    },
    {
      "type": "copy",
      "source": "important.txt",
      "destination": "backup/important.txt"
    },
    {
      "type": "edit",
      "path": "important.txt",
      "old_text": "version: 1.0",
      "new_text": "version: 2.0"
    },
    {
      "type": "write",
      "path": "CHANGELOG.md",
      "content": "## Version 2.0\n- Updated version"
    }
  ],
  "atomic": true,
  "create_backup": true,
  "validate_only": false
}

This will:

Create backup directory
Copy important.txt to backup
Edit version in important.txt
Write changelog

If any step fails, all changes are reverted.