Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/database-simple-tools.ts:369-440 (handler)

  Primary handler for 'db_export_status' tool. Validates parameters, handles waitBeforeCheck, calls internal status check, adds monitoring/auto-download logic, and structures response.

  static async handleCheckExportStatus(args: CheckExportStatusArgs): Promise<any> {
      if (!args.apiKey || !args.apiSecret || !args.projectId) {
          return ResponseBuilder.invalidParams('Missing required parameters: apiKey, apiSecret, projectId');
      }
  
      // DXP-81: Support new 'database' parameter
      const databaseName = args.database || args.databaseName;
  
      // If waitBeforeCheck is specified, implement transparent wait-then-check pattern
      if (args.waitBeforeCheck && args.waitBeforeCheck > 0) {
          const waitMinutes = Math.floor(args.waitBeforeCheck / 60);
          const waitSeconds = args.waitBeforeCheck % 60;
          const waitDisplay = waitMinutes > 0 ?
              `${waitMinutes} minute${waitMinutes > 1 ? 's' : ''}${waitSeconds > 0 ? ` ${waitSeconds} second${waitSeconds > 1 ? 's' : ''}` : ''}` :
              `${waitSeconds} second${waitSeconds > 1 ? 's' : ''}`;
  
          OutputLogger.info(`⏳ Waiting ${waitDisplay} before checking export status...`);
          await new Promise(resolve => setTimeout(resolve, args.waitBeforeCheck! * 1000));
          OutputLogger.success(`✅ Wait complete. Checking export status now...`);
      }
  
      try {
          const result = await this.internalCheckExportStatus(args);
  
          // Check if result is structured response
          if (result && typeof result === 'object' && 'data' in result && 'message' in result) {
              // If monitor mode is enabled and export is still in progress, add monitoring instructions
              if (args.monitor && result.data && result.data.status) {
                  const monitoringInstructions = this.generateMonitoringInstructions(
                      result.data.exportId || args.exportId || 'unknown',
                      result.data.status,
                      args
                  );
                  result.message = result.message + '\\n\\n' + monitoringInstructions;
              }
  
              // If autoDownload is enabled and export is complete with download URL
              if (args.autoDownload && result.data && result.data.status === 'Succeeded' && result.data.downloadUrl) {
                  // DXP-184: Use background download to avoid MCP timeout
                  OutputLogger.info('🔄 Auto-download enabled. Starting background download...');
                  const downloadId = await this.startBackgroundDatabaseDownload(
                      result.data.downloadUrl,
                      args.downloadPath,
                      args.projectName,
                      result.data.environment || args.environment,
                      result.data.databaseName || databaseName
                  );
  
                  const fileSize = await this.getRemoteFileSize(result.data.downloadUrl).catch(() => 0);
                  const estimatedTime = this.estimateDownloadTime(fileSize);
  
                  const downloadMessage = `\n\n📥 **Background Download Started**\n` +
                                        `• Download ID: \`${downloadId}\`\n` +
                                        `• Size: ${this.formatBytes(fileSize)}\n` +
                                        `• Estimated Time: ${estimatedTime}\n\n` +
                                        `**Monitor Progress:**\n` +
                                        `Use \`download_list()\` to check status.\n` +
                                        `Use \`download_status({ downloadId: "${downloadId}", monitor: true })\` for live updates.`;
  
                  // Append download info to message
                  result.message = result.message + downloadMessage;
              }
  
              return ResponseBuilder.successWithStructuredData(result.data, result.message);
          }
  
          return ResponseBuilder.success(result);
      } catch (error: any) {
          console.error('Check export status error:', error);
          return ResponseBuilder.internalError('Failed to check export status', error.message);
      }
  }

• lib/tools/database-simple-tools.ts:47-66 (schema)

  Type definition for input parameters of the db_export_status tool, including optional fields for authentication, export identification, monitoring, and pagination.

  interface CheckExportStatusArgs {
      apiKey?: string;
      apiSecret?: string;
      projectId?: string;
      projectName?: string;
      environment?: string;
      exportId?: string;
      databaseName?: string;
      database?: string;
      latest?: boolean;
      monitor?: boolean;
      autoDownload?: boolean;
      downloadPath?: string;
      waitBeforeCheck?: number;
      incremental?: boolean;
      limit?: number;
      offset?: number;
      status?: string;
      format?: 'concise' | 'detailed';
  }

• lib/tools/database-simple-tools.ts:772-881 (handler)

  Core internal handler performing the actual API call to retrieve database export status, parses response, emits resource events, and formats output.

  static async internalCheckExportStatus(args: CheckExportStatusArgs): Promise<StatusResult> {
      const databaseName = args.database || args.databaseName || 'epicms';
      let exportId = args.exportId;
  
      const projectConfig: ProjectConfig = {
          name: args.projectName || 'Unknown',
          projectId: args.projectId!,
          apiKey: args.apiKey!,
          apiSecret: args.apiSecret!
      };
  
      // DXP-76-2: List mode - when limit/offset is specified, list all exports
      if ((args.limit !== undefined || args.offset !== undefined) && !exportId && !args.latest) {
          return await this.listAllExports(args, projectConfig, databaseName);
      }
  
      // If 'latest' is specified or no exportId provided, try to get from saved state
      if (args.latest || !exportId) {
          const savedState = await this.loadCurrentExportState();
          if (savedState && savedState.exportId) {
              exportId = savedState.exportId;
              OutputLogger.info(`Using latest export ID: ${exportId}`);
          } else {
              throw new Error('No export ID specified and no saved export state found. Please provide exportId or start a new export.');
          }
      }
  
      try {
          // Check export status via REST API (DXP-101: No PowerShell)
          const result = await DXPRestClient.getDatabaseExportStatus(
              projectConfig.projectId,
              projectConfig.apiKey!,
              projectConfig.apiSecret!,
              args.environment || 'Production',
              databaseName,
              exportId!
          );
  
          const parsedStatus = this.parseExportStatus(result);
  
          // DXP-155: Emit export events based on status
          try {
              if (parsedStatus.status === 'InProgress') {
                  ExportResourceHandler.emitInProgress(exportId!, {
                      status: parsedStatus.status,
                      percentComplete: parsedStatus.percentComplete || 0
                  });
              } else if (parsedStatus.status === 'Succeeded') {
                  ExportResourceHandler.emitSucceeded(exportId!, {
                      downloadUrl: parsedStatus.downloadUrl,
                      environment: args.environment || 'Production',
                      databaseName
                  });
              } else if (parsedStatus.status === 'Failed') {
                  ExportResourceHandler.emitFailed(exportId!, {
                      error: (parsedStatus as any).errorMessage || 'Export failed',
                      environment: args.environment || 'Production',
                      databaseName
                  });
              }
          } catch (eventError: any) {
              console.error(`Failed to emit export event: ${eventError.message}`);
              // Don't fail the operation if event emission fails
          }
  
          // Update saved state if we have one
          const savedState = await this.loadCurrentExportState();
          if (savedState && savedState.exportId === exportId) {
              savedState.status = parsedStatus.status;
              if (parsedStatus.downloadUrl) {
                  savedState.downloadUrl = parsedStatus.downloadUrl;
              }
              if (parsedStatus.status === 'Succeeded' || parsedStatus.status === 'Failed') {
                  savedState.completedAt = new Date().toISOString();
              }
              await this.saveCurrentExportState(savedState);
          }
  
          let message = `Export Status: ${parsedStatus.status}\\n`;
          message += `Export ID: ${exportId}\\n`;
  
          if (parsedStatus.percentComplete !== undefined) {
              message += `Progress: ${parsedStatus.percentComplete}%\\n`;
          }
  
          if (parsedStatus.status === 'Succeeded' && parsedStatus.downloadUrl) {
              message += `\\n✅ Export completed successfully!\\n`;
              message += `Download URL available (valid for 24 hours)\\n\\n`;
              message += `Use download_database_export to download the backup.`;
          } else if (parsedStatus.status === 'Failed') {
              message += `\\n❌ Export failed. Check DXP portal for details.`;
          } else {
              message += `\\n⏳ Export in progress. Check again in 30 seconds.`;
          }
  
          return {
              data: {
                  status: parsedStatus.status,
                  exportId: exportId!,
                  downloadUrl: parsedStatus.downloadUrl,
                  environment: args.environment || 'Production',
                  databaseName,
                  percentComplete: parsedStatus.percentComplete
              },
              message
          };
      } catch (error: any) {
          throw new Error(`Failed to check export status: ${error.message}`);
      }
  }

• lib/utils/tool-availability-matrix.ts:205-209 (registration)

  Tool registration/availability definition in the central tool matrix, specifying hosting restrictions, category, and description for db_export_status.

  'db_export_status': {
      hostingTypes: ['dxp-paas'],
      category: 'Database',
      description: 'Check export status with optional monitoring and download',
      restrictedMessage: 'Database export status is only available for DXP PaaS hosting.'

• lib/resources/export-resource.ts:86-105 (helper)

  Helper functions that emit export progress/success events tagged with operation 'db_export_status' for resource updates and notifications.

  static emitInProgress(exportId: string, details: ExportDetails = {}): DXPEvent {
      const emitter = getGlobalEmitter();
      const event = createEvent(
          EVENT_TYPES.EXPORT_IN_PROGRESS,
          exportId,
          {
              exportId,
              status: 'InProgress',
              progress: details.progress || 50,
              ...details
          },
          {
              operation: 'db_export_status',
              user: 'system'
          }
      );
  
      emitter.emitEvent(event);
      return event;
  }