MCP Multi Edit

Editing Files

When making multiple edits to the same file or across multiple files, prefer using the multi_edit and multi_edit_files MCP tools over the built-in Edit tool. These batch edits atomically in a single call.

That's all—Claude will now use `multi_edit` whenever it's the appropriate tool.

> **Display name**: Claude Code uses the key name in `mcpServers` as the server's display name. You can modify the key to any name you prefer.

**Alternative**: One - liner via CLI:
```bash
claude mcp add --transport stdio multi-edit -- npx -y @essentialai/mcp-multi-edit

Note: The CLI only accepts simple names (letters, numbers, hyphens, underscores). For the full branded display name, use the .mcp.json approach above.

Claude Desktop

Add the following to your config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "Multi Edit from Essential AI Solutions (essentialai.uk)": {
      "command": "npx",
      "args": ["-y", "@essentialai/mcp-multi-edit"]
    }
  }
}

Restart Claude Desktop.

Full installation guide: docs/installation.md

✨ Features

• Atomic operations: All edits succeed or none apply, preventing partial states.
• Multi - file rollback: If any file edit fails, all previously modified files are restored.
• Dry - run preview: Preview changes before committing.
• Automatic backups: .bak files are created before each edit (disable with backup: false).
• Structured errors: Machine - readable error codes with recovery hints for automatic retry.
• Conflict detection: Warns when old_string matches multiple locations.
• Path validation: Enforces absolute paths, resolves symlinks, and checks file existence.

📦 Installation

Requirements

• Node.js 20 or later
• Claude Code or Claude Desktop

Steps

npm install           # Install dependencies
npm run build         # Compile TypeScript
npm test              # Run 264 tests
npm run test:coverage # Coverage report (90%+)
npm run benchmark     # Run benchmark suite
npm run dev           # Watch mode

💻 Usage Examples

multi_edit -- Single file, multiple edits

Batch multiple find - and - replace operations on one file. Edits are applied sequentially and atomically.

{
  "file_path": "/project/src/app.ts",
  "edits": [
    { "old_string": "const oldName = getValue()", "new_string": "const newName = getValue()" },
    { "old_string": "console.log", "new_string": "logger.info", "replace_all": true }
  ]
}

multi_edit_files -- Multiple files, one atomic operation

Coordinate edits across multiple files. If any file fails, all files are rolled back automatically.

{
  "files": [
    {
      "file_path": "/project/src/types.ts",
      "edits": [
        { "old_string": "interface UserData {", "new_string": "interface UserProfile {" }
      ]
    },
    {
      "file_path": "/project/src/api.ts",
      "edits": [
        { "old_string": "UserData", "new_string": "UserProfile", "replace_all": true }
      ]
    }
  ]
}

Full usage guide with examples: docs/usage.md

🔧 Technical Details

Project Structure

src/
  index.ts              # MCP server entry (stdio transport)
  server.ts             # Server factory and tool registration
  tools/
    multi-edit.ts       # multi_edit tool handler
    multi-edit-files.ts # multi_edit_files tool handler
  core/
    editor.ts           # File editing engine (atomic read-modify-write)
    validator.ts        # Zod input validation schemas
    reporter.ts         # Result formatting and diff generation
    errors.ts           # Error classification and envelope creation
  types/
    index.ts            # TypeScript type definitions