OPNSense MCP Server

Instructions

Implementation Reference

• src/resources/backup/manager.ts:13-18 (schema)

  Input options schema for the createBackup function defining optional backup parameters.

  export interface BackupOptions {
    description?: string;
    compress?: boolean;
    includeRRD?: boolean;
    includeCaptivePortal?: boolean;
  }

• src/resources/backup/manager.ts:32-63 (handler)

  Main handler function that executes the backup creation: generates ID, downloads config from OPNsense, creates metadata, logs, saves metadata and file, returns BackupInfo.

  async createBackup(options: BackupOptions = {}): Promise<BackupInfo> {
    try {
      // Generate backup ID
      const timestamp = new Date();
      const id = `backup-${timestamp.toISOString().replace(/[:.]/g, '-')}`;
      
      // Download configuration
      const config = await this.downloadConfig();
      
      // Create backup info
      const backupInfo: BackupInfo = {
        id,
        filename: `${id}.xml`,
        timestamp,
        description: options.description || `Automated backup before API operation`,
        size: config.length
      };
  
      // Log backup creation
      console.log(`Created backup: ${backupInfo.id}`);
      
      // Store backup metadata (in production, save to database)
      await this.saveBackupMetadata(backupInfo);
      
      // Store backup file (in production, save to TrueNAS or local storage)
      await this.saveBackupFile(backupInfo.filename, config);
      
      return backupInfo;
    } catch (error: any) {
      throw new Error(`Failed to create backup: ${error.message}`);
    }
  }

• src/resources/backup/manager.ts:4-11 (schema)

  Output schema for backup information returned by createBackup.

  export interface BackupInfo {
    id: string;
    filename: string;
    timestamp: Date;
    size?: number;
    description?: string;
    checksum?: string;
  }

• src/resources/backup/manager.ts:179-198 (helper)

  Helper method that creates a backup before executing an operation and returns the backup ID, useful for safe API operations.

  async withBackup<T>(
    operation: () => Promise<T>,
    description?: string
  ): Promise<{ result: T; backupId: string }> {
    // Create backup first
    const backup = await this.createBackup({ description });
    
    try {
      // Execute operation
      const result = await operation();
      
      return {
        result,
        backupId: backup.id
      };
    } catch (error) {
      console.error(`Operation failed. Backup available: ${backup.id}`);
      throw error;
    }
  }