Backups and Recovery

Introduction

The MCP Filesystem Ultra backup system protects your code against accidental loss. Every destructive operation (edit, delete) automatically creates a persistent backup that you can easily recover.

Key Benefits

• Automatic backups - Created automatically, no action required
• Intelligent validation - Warns you before risky changes
• Quick recovery - One command to restore lost code
• Complete audit trail - History of all changes

---

Automatic Backups

When Are Backups Created?

Backups are created automatically before:

1. File edits (edit_file)
2. Deletions (delete_file)
3. Batch operations (batch_operations with create_backup: true)

Backup Location

By default, backups are stored in:

%TEMP%\mcp-batch-backups\

Each backup has its own directory with a unique ID:

20241203-153045-abc123\
├── metadata.json       # Backup information
└── files\              # Backed up files
    └── your_file.go

Configuration

Customize backup behavior in claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem-ultra": {
      "args": [
        "--backup-dir", "C:\\Backups\\MCP",
        "--backup-max-age", "14",
        "--backup-max-count", "200",
        "C:\\your\\project\\",
        "C:\\Backups\\MCP"
      ]
    }
  }
}

Important: The backup directory MUST be in allowed paths.

---

Risk Validation

What Is Risk Validation?

Before editing a file, the system analyzes the impact of the change:

• Percentage of the file that will change
• Number of occurrences to replace
• Specific risk factors

Risk Levels

Level	Conditions	Behavior
LOW	Less than 20% change, fewer than 50 occurrences	Proceeds silently
MEDIUM	20-74% change, or 50-100 occurrences	Auto-backup + proceed + risk notice
HIGH	75-89% change, or more than 100 occurrences	Auto-backup + proceed + prominent warning
CRITICAL	90% or more change	Auto-backup + block (requires force: true)

Changed in v3.15.1 (Bug #16): Previously, MEDIUM and HIGH risk edits were blocked and required force: true. Now only CRITICAL (>=90%) blocks. MEDIUM and HIGH auto-proceed with an automatic backup and a risk notice appended to the response. This eliminates wasteful retry round-trips in agentic workflows.

Example: MEDIUM/HIGH Risk (Auto-Proceeds)

When editing a significant portion of a file:

edit_file({
  path: "main.go",
  old_text: "// old implementation block...",
  new_text: "// new implementation block..."
})

Response (edit succeeds immediately):

Replaced 1 occurrence(s). Characters changed: ~400
Backup: 20260302-143022-abc123

Risk notice [medium]
  40.0% of file changed (1 occurrence(s), ~400 chars)
  Auto-backup: 20260302-143022-abc123
  Restore with: backup({ action:"restore", backup_id })

Example: CRITICAL Risk (Blocked)

When attempting to rewrite nearly the entire file:

edit_file({
  path: "main.go",
  old_text: "func",
  new_text: "function"
  // This replaces 95% of the file
})

Response:

OPERATION BLOCKED - CRITICAL risk
  Almost complete file rewrite (95.3%)
  Backup created: 20260302-143022-def456

Use 'analyze_operation' to preview, then add force: true to confirm.

Recommended Workflow

For CRITICAL risk changes (>=90% of file):

1. Preview first with analyze_operation:

   analyze_operation({
     operation: "edit",
     path: "main.go",
     old_text: "func",
     new_text: "function"
   })

2. Review the changes that will be shown

3. Confirm with force if everything looks correct:

   edit_file({
     path: "main.go",
     old_text: "func",
     new_text: "function",
     force: true
   })

For MEDIUM/HIGH risk changes: No special workflow needed. The edit proceeds automatically with a backup. If something goes wrong, use backup({ action:"restore", backup_id }) with the ID from the response.

---

Backup Management

1. List Available Backups

backup({
  action: "list",
  limit: 20,                    // Maximum to show
  filter_operation: "edit",     // edit, delete, batch, all
  filter_path: "main.go",       // Filter by file
  newer_than_hours: 24          // Only last 24 hours
})

Response:

Available Backups (3)

20241203-153045-abc123
   Time: 2024-12-03 15:30:45 (2 hours ago)
   Operation: edit_file
   Files: 1 (12.1KB)
   Context: Edit: 12 occurrences, 35.2% change

20241203-140230-def456
   Time: 2024-12-03 14:02:30 (3 hours ago)
   Operation: batch_operations
   Files: 47 (2.3MB)
   Context: Batch rename: 47 files

Use backup({ action:"restore", backup_id }) to restore files

2. Get Detailed Information

backup({
  action: "info",
  backup_id: "20241203-153045-abc123"
})

Response:

Backup Details: 20241203-153045-abc123

Timestamp: 2024-12-03 15:30:45 (2 hours ago)
Operation: edit_file
Context: Edit: 12 occurrences, 35.2% change
Total Size: 12.1KB
Files: 1

Files in backup:
   - C:\project\main.go (12.1KB)

Backup Location: C:\Users\...\mcp-batch-backups\20241203-153045-abc123

3. Compare with Current State

Before restoring, see what changed:

backup({
  action: "compare",
  backup_id: "20241203-153045-abc123",
  file_path: "C:\\project\\main.go"
})

Response:

=== Comparison for C:\project\main.go ===
Backup lines: 245
Current lines: 268
Difference: +23 lines

First differences:
Line 12:
  - BACKUP:  func oldName() {
  + CURRENT: func newName() {

Line 45:
  - BACKUP:  // TODO: implement
  + CURRENT: // DONE: implemented

---

File Recovery

Preview Mode (Recommended)

First, use preview mode to see what will be restored:

backup({
  action: "restore",
  backup_id: "20241203-153045-abc123",
  file_path: "C:\\project\\main.go",
  preview: true
})

Response:

Preview Mode - Changes to be restored:

=== Comparison for C:\project\main.go ===
[shows the diff]

Actual Restoration

If the preview looks correct, proceed with restoration:

backup({
  action: "restore",
  backup_id: "20241203-153045-abc123",
  file_path: "C:\\project\\main.go"
})

Response:

Restore completed successfully

Restored 1 file(s):
   - C:\project\main.go

A backup of the current state was created before restoring

Note: A backup of the current state is created before restoring, giving you double protection.

Restore All Files

Omit file_path to restore everything:

backup({
  action: "restore",
  backup_id: "20241203-140230-def456"  // Backup with 47 files
})

---

Backup Cleanup

Why Clean Up?

Backups take disk space. Regularly clean up old ones.

Dry Run (Recommended)

First, see what would be deleted:

backup({
  action: "cleanup",
  older_than_days: 7,
  dry_run: true
})

Response:

Dry Run Mode - Preview of cleanup operation

Would delete: 45 backup(s)
Would free: 120.5MB

Run with dry_run: false to actually delete backups

Execute Cleanup

If you agree, execute the cleanup:

backup({
  action: "cleanup",
  older_than_days: 7,
  dry_run: false
})

Response:

Cleanup completed

Deleted: 45 backup(s)
Freed: 120.5MB

Automatic Cleanup

The system automatically cleans up when:

• backup_max_count is exceeded (default: 100)
• Oldest backups are deleted first

---

Common Use Cases

Case 1: Safe Massive Edit

Situation: You need to change “func” to “function” throughout the file.

// 1. Analyze the impact
analyze_operation({
  operation: "edit",
  path: "main.go",
  old_text: "func",
  new_text: "function"
})

// 2. If safe, proceed
edit_file({
  path: "main.go",
  old_text: "func",
  new_text: "function",
  force: true  // If risky
})

// 3. If something went wrong, restore
backup({
  action: "restore",
  backup_id: "20241203-153045-abc123",
  file_path: "main.go"
})

Case 2: Emergency Recovery

Situation: You accidentally overwrote an important file.

// 1. List recent backups
backup({
  action: "list",
  newer_than_hours: 2,
  filter_path: "important.go"
})

// 2. Find the correct backup
backup({
  action: "info",
  backup_id: "20241203-140230-def456"
})

// 3. Compare to be sure
backup({
  action: "compare",
  backup_id: "20241203-140230-def456",
  file_path: "important.go"
})

// 4. Restore
backup({
  action: "restore",
  backup_id: "20241203-140230-def456",
  file_path: "important.go"
})

Case 3: Safe Batch Operations

Situation: You need to rename 50 files.

// 1. Batch with automatic backup
batch_operations({
  operations: [
    {type: "edit", path: "file1.go", old_text: "old", new_text: "new"},
    // ... 49 more
  ],
  atomic: true,
  create_backup: true,
  force: true  // If analysis requires it
})

// 2. If something fails, rollback is automatic
// Or you can restore manually if needed

Case 4: Change Audit

Situation: You want to see what changes were made today.

// List all backups from today
backup({
  action: "list",
  newer_than_hours: 24,
  limit: 100
})

// Review each one
backup({
  action: "info",
  backup_id: "20241203-XXXXXX-XXXXXX"
})

// Compare with current state
backup({
  action: "compare",
  backup_id: "20241203-XXXXXX-XXXXXX",
  file_path: "file.go"
})

---

Advanced Configuration

Custom Risk Thresholds

Adjust risk validation sensitivity:

{
  "args": [
    "--risk-threshold-medium", "40.0",
    "--risk-threshold-high", "60.0",
    "--risk-occurrences-medium", "75",
    "--risk-occurrences-high", "150"
  ]
}

Defaults:

• MEDIUM: 20% change or 50 occurrences
• HIGH: 75% change or 100 occurrences

Backup Retention

Control how many backups to keep:

{
  "args": [
    "--backup-max-age", "14",
    "--backup-max-count", "200"
  ]
}

Defaults:

• Max age: 7 days
• Max count: 100 backups

---

Security and Reliability

Data Integrity

• SHA256 hash of each file
• Integrity verification on restore
• JSON metadata for audit

Error Handling

• Rollback if backup creation fails
• Backup of current state before restoring
• Descriptive error messages

Performance

• Minimal overhead: approximately 5-10ms per small file
• Intelligent cache: Metadata in memory (refresh every 5 min)
• Non-blocking: Operations do not block the system

---

Tips and Best Practices

1. Always Use Preview

Before restoring, use preview mode:

backup({ action:"restore", backup_id: "...", file_path: "...", preview: true })

2. Clean Up Regularly

Establish a weekly routine:

backup({ action:"cleanup", older_than_days: 7, dry_run: false })

3. Validate Large Changes

For massive edits, always use analyze_operation first.

4. Keep Backup Directory Accessible

Ensure it is in allowed paths for full access.

---

FAQ

Are backups automatically deleted?

Not after success, but yes when:

• You exceed backup_max_count
• You run backup({ action:"cleanup" })

Can I access backups manually?

Yes, they are in the normal filesystem. You can copy, move them, etc.

What happens if I edit a file without backup?

The system always creates a backup before editing. It is automatic.

Can I disable backups?

Not directly, but you can use --backup-max-age=0 to delete them immediately.

Do backups include binary content?

Yes, any file type is backed up.

What if I run out of disk space?

The system will warn you, but it is better to clean up regularly with backup({ action:"cleanup" }).

---

Last updated: March 2026 Version: 4.0.0