Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/database-simple-tools.ts:275-364 (handler)

  Main handler function for the export_database tool. Handles preview, validation, existing backups, monitoring, and calls internal export logic.
  static async handleExportDatabase(args: ExportDatabaseArgs): Promise<any> { // DXP-81: Support new 'database' parameter (replaces 'databaseName') const databaseName = args.database || args.databaseName; if (!args.apiKey || !args.apiSecret || !args.projectId) { return ResponseBuilder.invalidParams('Missing required parameters: apiKey, apiSecret, projectId'); } // DXP-81: Preview mode with capability check if (args.previewOnly) { return this.handleCheckCapabilities(args); } const projectConfig: ProjectConfig = { name: args.projectName || 'Unknown', projectId: args.projectId, apiKey: args.apiKey, apiSecret: args.apiSecret }; try { // DXP-183 Bug #3: Check for existing backups if useExisting is true // Track if we checked for existing backups but found none let useExistingChecked = false; let useExistingSearchPath = ''; if (args.useExisting) { // Use provided downloadPath or default to current directory const searchPath = args.downloadPath || process.cwd(); useExistingSearchPath = searchPath; useExistingChecked = true; const existingBackups = await this.checkForExistingBackups( searchPath, projectConfig.name, args.environment || 'Production', databaseName || 'epicms' ); if (existingBackups.length > 0) { const backup = existingBackups[0]; // Most recent return ResponseBuilder.success( `✅ Found existing backup (useExisting=true):\\n\\n` + `📦 **File**: ${backup.fileName}\\n` + `📍 **Location**: ${backup.filePath}\\n` + `📊 **Size**: ${this.formatBytes(backup.fileSize)}\\n` + `⏱️ **Age**: ${backup.formattedAge}\\n\\n` + `💡 Use this file path for database restore operations.` ); } else { // No existing backup found - will inform user in response OutputLogger.info(`⚠️ No existing backup found in ${searchPath}. Starting new export...`); } } // Start export const result = await this.internalStartExport(args); // Check if result is structured response if (result && typeof result === 'object' && 'data' in result && 'message' in result) { // DXP-183 Bug #3: Add useExisting feedback to message if (useExistingChecked) { const useExistingNote = `\\n\\n📋 **Note**: useExisting=true was specified but no local backup was found in \`${useExistingSearchPath}\`.\\n` + `Starting new export. Future calls with useExisting=true will find this backup after download completes.`; result.message = result.message + useExistingNote; } // If autoMonitor is enabled, start background monitoring if (args.autoMonitor && result.data && result.data.exportId) { this.startBackgroundMonitoring( result.data.exportId, projectConfig, result.data.environment || args.environment || 'Production', result.data.databaseName || databaseName || 'epicms', args.downloadPath ); // Update message to indicate monitoring started result.message = result.message + '\\n\\n✅ Background monitoring started. Use check_export_status to view progress.'; } return ResponseBuilder.successWithStructuredData(result.data, result.message); } return ResponseBuilder.success(result); } catch (error: any) { console.error('Export database error:', error); return ResponseBuilder.internalError('Failed to export database', error.message); } }
• lib/tools/database-simple-tools.ts:24-42 (schema)

  TypeScript interface defining the input parameters/schema for the export_database tool.
  interface ExportDatabaseArgs { apiKey?: string; apiSecret?: string; projectId?: string; projectName?: string; environment?: string; databaseName?: string; database?: string; // DXP-81: New parameter replacing databaseName downloadPath?: string; retentionHours?: number; useExisting?: boolean; autoMonitor?: boolean; autoDownload?: boolean; skipConfirmation?: boolean; previewOnly?: boolean; waitBeforeCheck?: number; monitor?: boolean; incremental?: boolean; }
• lib/tools/database-simple-tools.ts:580-709 (helper)

  Core helper that performs the actual database export initiation via DXP REST client, handles state management and event emission.
  static async internalStartExport(args: ExportDatabaseArgs): Promise<StatusResult> { const databaseName = args.database || args.databaseName || 'epicms'; const environment = args.environment || 'Production'; const retentionHours = args.retentionHours || 24; const projectConfig: ProjectConfig = { name: args.projectName || 'Unknown', projectId: args.projectId!, apiKey: args.apiKey!, apiSecret: args.apiSecret! }; // Check for active exports that might conflict const activeExport = await this.detectAndOfferRecovery(projectConfig); if (activeExport) { // There's an active export - check if it's for the same database const isSameDatabase = activeExport.environment === environment && activeExport.databaseName === databaseName; if (isSameDatabase) { // Same database - offer to resume monitoring return { data: { status: 'InProgress', exportId: activeExport.exportId, environment: activeExport.environment, databaseName: activeExport.databaseName, message: 'Resuming existing export' }, message: `Found existing export in progress for ${environment} ${databaseName}.\\n` + `Export ID: ${activeExport.exportId}\\n\\n` + `Use check_export_status with this exportId to monitor progress.` }; } else { // Different database - resolve conflict const resolution = await this.resolveExportConflict( environment, databaseName, projectConfig, args.downloadPath ); if (resolution.action === 'queue') { return { data: { status: 'Queued', exportId: resolution.queuedExportId || 'pending', environment, databaseName, message: 'Export queued - will start when current export completes' }, message: resolution.message || 'Export queued behind active export' }; } else if (resolution.action === 'cancel') { return { data: { status: 'Cancelled', environment, databaseName, message: 'Export cancelled by user' }, message: 'Export request cancelled' }; } } } // Start new export via REST API (DXP-101: No PowerShell) try { const result = await DXPRestClient.startDatabaseExport( projectConfig.projectId, projectConfig.apiKey!, projectConfig.apiSecret!, environment, databaseName, retentionHours ); // Parse export ID from result const exportId = this.extractExportId(result); // Save export state const exportInfo: ExportInfo = { exportId, projectId: projectConfig.projectId, projectName: projectConfig.name, environment, databaseName, status: 'InProgress', startedAt: new Date().toISOString(), downloadPath: args.downloadPath, autoMonitor: args.autoMonitor, autoDownload: args.autoDownload, incremental: args.incremental }; await this.saveCurrentExportState(exportInfo); // DXP-155: Emit export started event try { ExportResourceHandler.emitStarted(exportId, { project: projectConfig.name, environment, databaseName, retentionHours }); } catch (eventError: any) { console.error(`Failed to emit export started event: ${eventError.message}`); // Don't fail the operation if event emission fails } return { data: { status: 'InProgress', exportId, environment, databaseName, message: 'Export started successfully' }, message: `Database export started successfully\\n` + `Export ID: ${exportId}\\n` + `Environment: ${environment}\\n` + `Database: ${databaseName}\\n` + `Retention: ${retentionHours} hours\\n\\n` + `Use check_export_status to monitor progress.` }; } catch (error: any) { throw new Error(`Failed to start export: ${error.message}`); } }
• lib/prompts/database-export-prompts.ts:24-82 (helper)

  Prompt definition and workflow guidance for the export-database AI prompt that guides usage of the tool.
  static getPromptDefinitions(): PromptDefinition[] { return [ { name: "export-database", description: "Start database export with preview and monitoring", arguments: [ { name: "environment", description: "Production, Preproduction, Integration", required: false }, { name: "database", description: "epicms or epicommerce", required: false }, { name: "retention", description: "Number between 1-168 hours", required: false }, { name: "monitor", description: "true or false", required: false }, { name: "autoDownload", description: "true or false", required: false } ] }, { name: "database_export_workflow", description: "Guide for exporting and downloading DXP databases", arguments: [ { name: "environment", description: "Target environment (Integration, Preproduction, Production)", required: true } ] } ]; } /** * Get messages for a specific prompt */ static getPromptMessages(name: string, args: DatabaseExportArgs = {}): PromptMessage[] { switch (name) { case "export-database": return this.getCompleteWorkflowMessages(args); case "database_export_workflow": return this.getDatabaseExportWorkflowMessages(args); default: throw new Error(`Unknown prompt: ${name}`); }