MCP Host Configuration Backup System¶

This article is about: - Core backup system architecture and components - Atomic file operations with rollback capabilities - Pydantic data models for validation and type safety - Host-agnostic design patterns for MCP configuration management

Overview¶

The MCP (Model Context Protocol) host configuration backup system provides comprehensive backup and restore functionality for MCP host configuration files. The system ensures data integrity through atomic operations and Pydantic validation while maintaining host-agnostic design principles.

Architecture Components¶

MCPHostConfigBackupManager¶

The central backup management class handles all backup operations:

from hatch.mcp.backup import MCPHostConfigBackupManager

backup_manager = MCPHostConfigBackupManager()
result = backup_manager.create_backup(config_path, "claude-desktop")

Core responsibilities: - Timestamped backup creation with microsecond precision - Backup restoration by hostname and timestamp - Backup listing with Pydantic model validation - Cleanup operations (age-based and count-based)

AtomicFileOperations¶

Provides safe file operations preventing data corruption:

from hatch.mcp.backup import AtomicFileOperations

atomic_ops = AtomicFileOperations(backup_manager)
atomic_ops.atomic_write(target_path, new_content, "vscode", no_backup=False)

Key features: - Temporary file creation with atomic moves - Automatic backup creation before modifications - Rollback capability on operation failure - Cross-platform file permission handling

Pydantic Data Models¶

Type-safe data structures with comprehensive validation:

BackupInfo¶

class BackupInfo(BaseModel):
    hostname: str = Field(..., regex=r'^(claude-desktop|claude-code|vscode|cursor|lmstudio|gemini)$')
    timestamp: datetime
    file_path: Path
    file_size: int = Field(..., ge=0)
    original_config_path: Path

BackupResult¶

class BackupResult(BaseModel):
    success: bool
    backup_path: Optional[Path] = None
    error_message: Optional[str] = None
    original_size: int = Field(default=0, ge=0)
    backup_size: int = Field(default=0, ge=0)

BackupAwareOperation¶

Base class enforcing explicit backup acknowledgment:

class BackupAwareOperation:
    def prepare_backup(self, config_path: Path, hostname: str, no_backup: bool = False) -> Optional[BackupResult]
    def rollback_on_failure(self, backup_result: Optional[BackupResult], config_path: Path, hostname: str) -> bool

Design Patterns¶

Host-Agnostic Architecture¶

The system operates independently of specific host configuration structures:

JSON Format Independence: Works with any valid JSON configuration
Path Agnostic: No assumptions about configuration file locations
Content Neutral: Backup operations preserve exact file content

Explicit API Design¶

Forces consumers to acknowledge backup creation:

# Explicit backup preparation
backup_result = operation.prepare_backup(config_path, "cursor", no_backup=False)

# Operation with rollback capability
try:
    perform_configuration_update()
except Exception:
    operation.rollback_on_failure(backup_result, config_path, "cursor")
    raise

Atomic Operations Pattern¶

Ensures data consistency through atomic file operations:

Temporary File Creation: Write to temporary file first
Validation: Verify content integrity
Atomic Move: Replace original file atomically
Cleanup: Remove temporary files on success/failure

File Organization¶

Backup Directory Structure¶

~/.hatch/mcp_host_config_backups/
├── claude-desktop/
│   ├── mcp.json.claude-desktop.20250921_100000_123456
│   └── mcp.json.claude-desktop.20250921_110000_234567
├── vscode/
│   └── mcp.json.vscode.20250921_100000_345678
└── cursor/
    └── mcp.json.cursor.20250921_100000_456789

Naming Convention¶

Format: mcp.json.<hostname>.<timestamp>
Timestamp: YYYYMMDD_HHMMSS_ffffff (microsecond precision)
Hostname: Exact host identifier from supported types

Supported Host Types¶

The system supports all MCP host platforms:

Host Type	Description
`claude-desktop`	Claude Desktop application
`claude-code`	Claude for VS Code extension
`vscode`	VS Code MCP extension
`cursor`	Cursor IDE MCP integration
`lmstudio`	LM Studio MCP support
`gemini`	Google Gemini MCP integration
`mistral-vibe`	Mistral Vibe CLI coding agent

Performance Characteristics¶

Operation Benchmarks¶

Backup Creation: <2ms for typical 5KB JSON files
Restore Operation: <3ms including verification
List Backups: <1ms for typical backup counts (<100)
Pydantic Validation: <0.5ms for typical models

Storage Requirements¶

Per Backup: 5-10KB (typical MCP configuration)
Annual Storage: <36MB per host (negligible)

Security Model¶

File Permissions¶

Backup Directory: 700 (owner read/write/execute only)
Backup Files: 600 (owner read/write only)

Access Control¶

Backup creation requires write access to backup directory
Backup restoration requires write access to target configuration
No network access or external dependencies

Integration Points¶

Environment Manager Integration¶

The backup system integrates with Hatch's environment management:

# Future integration pattern
from hatch.env import EnvironmentManager

env_manager = EnvironmentManager()
backup_manager = MCPHostConfigBackupManager()

# Backup before environment changes
backup_result = backup_manager.create_backup(env_manager.get_mcp_config_path(), "vscode")

CLI Integration¶

Designed for future CLI command integration:

# Future CLI commands
hatch mcp backup create --host vscode
hatch mcp backup restore --host vscode --timestamp 20250921_100000_123456
hatch mcp backup list --host cursor
hatch mcp backup clean --host claude-desktop --older-than-days 30

Testing Architecture¶

Test Categories¶

Unit Tests: Component isolation and validation
Integration Tests: End-to-end workflow testing
Performance Tests: Large file and concurrent operations

Test Results¶

Total Tests: 31
Success Rate: 100%
Coverage: 95% unit test coverage, 100% integration coverage

Host-Agnostic Testing¶

All tests use generic JSON configurations without host-specific dependencies, ensuring the backup system works with any valid MCP configuration format.

Future Extensions¶

The current implementation provides core backup functionality. Future phases will add:

Host-Specific Configuration Detection: Automatic discovery of host configuration paths
Environment Manager Integration: Deep integration with Hatch's environment management
CLI Command Integration: Full command-line interface for backup operations
Backup Compression: Optional compression for large configuration files
Remote Backup Storage: Cloud storage integration for backup redundancy

Implementation Notes¶

Error Handling Strategy¶

Comprehensive Validation: Pydantic models ensure data integrity
Graceful Degradation: Operations continue when possible
Detailed Error Messages: Clear feedback for troubleshooting
Automatic Cleanup: Temporary files removed on failure

Cross-Platform Compatibility¶

Path Handling: Uses pathlib.Path for cross-platform compatibility
File Operations: Platform-specific permission handling
Timestamp Format: ISO 8601 compatible timestamps

Memory Efficiency¶

Streaming Operations: Large files processed in chunks
Lazy Loading: Backup lists generated on-demand
Resource Cleanup: Automatic cleanup of temporary resources