Edit MCP

Overview Schema Source Related Servers Discussions Admin

backup_and_edit

Destructive

Create backups of files before editing them to prevent data loss. Specify files and edit operations to safely modify content.

Instructions

Create backups of files before editing them

Input Schema

TableJSON Schema

Name	Required	Description	Default
`files`	Yes	List of files to backup and edit
`operation`	Yes	The edit operation to perform

Implementation Reference

src/router/operation-router.ts:551-579 (handler)

Main execution logic for the 'backup_and_edit' tool. Backs up files using FileSystemManager, delegates editing to EditInstanceManager via executeWithEdit, includes backup info in response, and restores files from backups if editing fails.

case 'backup_and_edit':
  // Create backups with file system
  const backups = await Promise.all(
    operation.affectedFiles.map(file =>
      this.fileSystemManager.createBackup(file)
    )
  );
  
  try {
    // Use Edit for the edits
    const result = await this.executeWithEdit({
      ...operation,
      type: operation.params.operation.type
    });
    
    return {
      ...result,
      backups
    };
  } catch (error) {
    // If edits fail, restore backups
    await Promise.all(
      operation.affectedFiles.map((file, index) =>
        this.fileSystemManager.restoreBackup(backups[index], file)
      )
    );
    
    throw error;
  }

src/index.ts:365-388 (registration)

Registers the 'backup_and_edit' tool with the MCP server in the registerHybridTools function, defining its name, description, input schema, and operational annotations.

mcpServer.registerTool({
  name: 'backup_and_edit',
  description: 'Create backups of files before editing them',
  inputSchema: {
    type: 'object',
    properties: {
      files: {
        type: 'array',
        description: 'List of files to backup and edit'
      },
      operation: {
        type: 'object',
        description: 'The edit operation to perform'
      }
    },
    required: ['files', 'operation']
  },
  annotations: {
    readOnlyHint: false,
    destructiveHint: true,
    idempotentHint: false,
    openWorldHint: false
  }
});

src/index.ts:368-388 (schema)

Input schema definition for the 'backup_and_edit' tool, specifying required 'files' array and 'operation' object.

  inputSchema: {
    type: 'object',
    properties: {
      files: {
        type: 'array',
        description: 'List of files to backup and edit'
      },
      operation: {
        type: 'object',
        description: 'The edit operation to perform'
      }
    },
    required: ['files', 'operation']
  },
  annotations: {
    readOnlyHint: false,
    destructiveHint: true,
    idempotentHint: false,
    openWorldHint: false
  }
});

Schema Changelog

Changes observed during successful MCP inspections.

First observedAug 21, 2025

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true, readOnlyHint=false, etc., so the agent knows this is a non-idempotent, destructive write operation. The description adds value by specifying that backups are created before editing, which clarifies the safety mechanism beyond the annotations. However, it doesn't detail behavioral traits like error handling, backup location, or rollback options, which would be useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that efficiently conveys the core functionality without unnecessary words. It's front-loaded with the main action, making it easy for an agent to quickly understand the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (destructive operation with backups) and lack of output schema, the description is minimally adequate. Annotations cover safety aspects, but the description could better explain the backup process or return values. It meets basic needs but leaves gaps in understanding the full workflow, such as how backups are managed or what happens on failure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters ('files' and 'operation'). The description implies that 'files' are backed up and edited, and 'operation' is performed, but doesn't add meaning beyond what the schema provides, such as examples of operations or file format constraints. Baseline 3 is appropriate when the schema handles most documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Create backups') and resource ('files'), and distinguishes it from siblings like 'write_file' or 'interactive_edit_session' by emphasizing the backup aspect. However, it doesn't explicitly differentiate from 'smart_refactor' or 'complex_find_replace', which might also involve editing with safety measures.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing write permissions, or compare it to siblings like 'write_file' (which might not create backups) or 'interactive_edit_session' (which might offer more control). This leaves the agent with minimal context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server