Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/simple-tools.ts:239-339 (handler)

  Primary handler for the 'status' tool. Fetches recent deployments for the project, handles self-hosted limitations, parses data, and generates a formatted multi-environment status summary with proactive suggestions.

  static async handleStatus(args: StatusArgs): Promise<any> {
      try {
          const { project, environment } = args;
  
          // Get project configuration
          const projectConfig = await this.getProjectConfig(project);
  
          // Check if this is a self-hosted project
          if (projectConfig.isSelfHosted) {
              return ResponseBuilder.invalidParams('Deployment status is not available for self-hosted projects. Self-hosted projects can only download existing backups and blobs.');
          }
  
          // Get deployments with retry
          const deploymentsResult = await this.executeWithRetry(
              () => DeploymentTools.handleListDeployments({
                  projectId: projectConfig.projectId,
                  projectName: projectConfig.name,
                  apiKey: projectConfig.apiKey,
                  apiSecret: projectConfig.apiSecret,
                  limit: 10
              }),
              `status check for ${projectConfig.name}`,
              2 // fewer retries for status checks
          ) as any;
  
          if (!deploymentsResult.isSuccess) {
              // Check if it's a limited access issue
              const errorText = deploymentsResult.content?.[0]?.text || '';
              if (errorText.includes('Environment Access Check') || errorText.includes('403') || errorText.includes('forbidden')) {
                  // This is likely limited environment access - check permissions
                  try {
                      const PermissionChecker = require('./permission-checker');
                      const permissions = await PermissionChecker.checkEnvironmentAccess(projectConfig);
  
                      let response = `ℹ️ **Environment Access for ${projectConfig.name}**\n\n`;
  
                      if (permissions.accessible.length > 0) {
                          response += `Your API key has access to: **${permissions.accessible.join(', ')}**\n\n`;
  
                          if (permissions.accessible.length === 1) {
                              const env = permissions.accessible[0];
                              response += `This configuration is `;
                              response += env === 'Integration' ? 'commonly used for development workflows.\n' :
                                        env === 'Preproduction' ? 'commonly used for staging and testing.\n' :
                                        'commonly used for production monitoring.\n';
                          } else if (permissions.accessible.length === 2) {
                              const envs = permissions.accessible.sort();
  
                              // Provide specific context for each dual-environment combination
                              if (envs.includes('Integration') && envs.includes('Production')) {
                                  response += `This configuration provides direct development-to-production access.\n`;
                                  response += `Commonly used for rapid deployment workflows or emergency fixes.\n`;
                              } else if (envs.includes('Integration') && envs.includes('Preproduction')) {
                                  response += `This configuration provides access to development and preproduction environments.\n`;
                                  response += `Commonly used for development teams with staging responsibilities.\n`;
                              } else if (envs.includes('Preproduction') && envs.includes('Production')) {
                                  response += `This configuration provides access to preproduction and production environments.\n`;
                                  response += `Commonly used for deployment teams and production support.\n`;
                              }
                          } else if (permissions.accessible.length === 3) {
                              response += `This configuration provides full access to all environments.\n`;
                          }
  
                          response += '\nThe MCP will automatically use your accessible environments for all operations.';
                          response += '\n\nWhat would you like to do? Try commands like:\n';
                          response += '• "List deployments" - Shows deployments from your accessible environment(s)\n';
                          response += '• "Export database" - Exports from your highest accessible environment\n';
                          response += '• "Check deployment status" - Monitor deployment progress';
                      } else {
                          response += '❌ No environment access detected. Please check your API credentials.';
                      }
  
                      return ResponseBuilder.success(response);
                  } catch (permError) {
                      // Fall back to original error if permission check fails
                      return deploymentsResult;
                  }
              }
              return deploymentsResult;
          }
  
          // Parse deployment data safely
          let deployments: Deployment[];
          try {
              deployments = JSON.parse(deploymentsResult.content[0].text);
              if (!Array.isArray(deployments)) {
                  deployments = [];
              }
          } catch (parseError: any) {
              OutputLogger.warn(`Failed to parse deployment data: ${parseError.message}`);
              deployments = [];
          }
  
          // Create intelligent status summary
          const statusSummary = this.formatIntelligentStatus(deployments, environment);
          return ResponseBuilder.successWithVersionCheck(statusSummary, true);
  
      } catch (error: any) {
          return ErrorHandler.handleError(error, 'status', args);
      }
  }

• lib/tools/simple-tools.ts:27-30 (schema)

  Input schema defining optional parameters for the status tool: project name and target environment filter.

  interface StatusArgs {
      project?: string;
      environment?: string;
  }

• lib/tools/simple-tools.ts:621-651 (helper)

  Key helper method that intelligently formats deployment status across environments (Production, Preproduction, Integration) with visual icons, time-ago, progress/ETA estimates, and action suggestions.

  static formatIntelligentStatus(deployments: Deployment[], filterEnvironment?: string): string {
      const environments = ['Production', 'Preproduction', 'Integration'];
      let status = "📊 **Current Status**\n\n";
  
      // Group deployments by target environment
      const envDeployments: EnvironmentDeployments = {};
      environments.forEach(env => {
          envDeployments[env] = deployments
              .filter(d => d.targetEnvironment === env)
              .sort((a, b) => new Date(b.startTime).getTime() - new Date(a.startTime).getTime())[0] || null;
      });
  
      // Show status for each environment
      environments.forEach(env => {
          if (filterEnvironment && env !== filterEnvironment) return;
  
          const deployment = envDeployments[env];
          const envStatus = this.getEnvironmentStatusIcon(deployment);
          const envDetails = this.getEnvironmentDetails(deployment);
  
          status += `${envStatus} **${env}**: ${envDetails}\n`;
      });
  
      // Add suggestions
      const suggestions = this.generateSuggestions(envDeployments);
      if (suggestions) {
          status += `\n💡 **Suggestions**\n${suggestions}`;
      }
  
      return status;
  }

• lib/tools/deployment/deployment-list.ts:67-91 (helper)

  Underlying handler called by status tool to fetch raw deployment data from the DXP API, used via DeploymentTools.handleListDeployments.

  static async handleListDeployments(args: ListDeploymentsArgs): Promise<any> {
      // Check if this is a self-hosted project
      if (args.isSelfHosted || args.connectionString) {
          return ResponseBuilder.invalidParams('Deployment listing is not available for self-hosted projects. Self-hosted projects can only download existing backups and blobs.');
      }
  
      if (!args.apiKey || !args.apiSecret || !args.projectId) {
          return ResponseBuilder.invalidParams('Missing required parameters');
      }
  
      try {
          const result = await this.listDeployments(args);
  
          // DXP-66: Check if result is structured response with data and message
          if (result && typeof result === 'object' && 'data' in result && 'message' in result) {
              return ResponseBuilder.successWithStructuredData(result.data, result.message);
          }
  
          // Fallback for legacy string responses
          return ResponseBuilder.success(result);
      } catch (error: any) {
          console.error('List deployments error:', error);
          return ResponseBuilder.internalError('Failed to list deployments', error.message);
      }
  }