Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/simple-tools.ts:344-467 (handler)

  Core handler for the 'quick' MCP tool. Performs a super-fast status check: fetches the 3 most recent deployments, provides self-hosted guidance, handles limited access gracefully, and returns an ultra-condensed summary.

  static async handleQuick(args: QuickArgs): Promise<any> {
      try {
          const { project } = args;
  
          // Get project configuration
          const projectConfig = await this.getProjectConfig(project);
  
          // Check if this is a self-hosted project
          if (projectConfig.isSelfHosted || projectConfig.connectionString) {
              // Provide useful info for self-hosted projects
              let response = `🏢 **Self-Hosted Project: ${projectConfig.name || 'OCA'}**\n\n`;
              response += `✅ **Connection Status:** Active\n`;
  
              // Parse connection string to get storage account name
              if (projectConfig.connectionString) {
                  const accountMatch = projectConfig.connectionString.match(/AccountName=([^;]+)/);
                  if (accountMatch) {
                      response += `📦 **Storage Account:** ${accountMatch[1]}\n`;
                  }
              }
  
              response += `\n**Available Operations:**\n`;
              response += `• Download logs (application, web, insights)\n`;
              response += `• Download blobs/media files\n`;
              response += `• Export database backups\n`;
              response += `• List storage containers\n`;
              response += `\n**Quick Commands:**\n`;
              response += `• \`list_storage_containers\` - View all containers\n`;
              response += `• \`download_logs logType: "application"\` - Get app logs\n`;
              response += `• \`download_blobs containerName: "mysitemedia"\` - Download media\n`;
              response += `• \`db_export\` - Export database backup\n`;
  
              return ResponseBuilder.success(response);
          }
  
          // Get only the most recent deployments with retry
          const deploymentsResult = await this.executeWithRetry(
              () => DeploymentTools.handleListDeployments({
                  projectId: projectConfig.projectId,
                  projectName: projectConfig.name,
                  apiKey: projectConfig.apiKey,
                  apiSecret: projectConfig.apiSecret,
                  limit: 3
              }),
              `quick status check`,
              1 // single retry for quick 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;
          }
  
          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 = [];
          }
  
          // Ultra-condensed status
          const summary = this.createQuickSummary(deployments);
  
          return ResponseBuilder.successWithVersionCheck(summary, true);
  
      } catch (error: any) {
          return ErrorHandler.handleError(error, 'quick', args as any);
      }
  }

• lib/tools/simple-tools.ts:35-37 (schema)

  TypeScript interface defining the input schema for the 'quick' tool: optional project name.

  interface QuickArgs {
      project?: string;
  }

• lib/nlp-parser.ts:162-162 (registration)

  NLP pattern registration that maps natural language inputs starting with 'quick', 'fast', or 'rapid' to the 'quick' tool.

  { pattern: /^(quick|fast|rapid)/i, tool: 'quick', category: 'monitoring' },

• lib/utils/tool-availability-matrix.ts:76-81 (registration)

  Tool availability registration for 'quick' tool, restricting it to DXP PaaS hosting with descriptive metadata.

  'quick': {
      hostingTypes: ['dxp-paas'],
      category: 'Simple Commands',
      description: 'Quick deployment operations',
      restrictedMessage: 'Quick deployments are only available for DXP PaaS hosting.'
  },

• lib/tools/simple-tools.ts:783-793 (helper)

  Helper method used by 'quick' handler to generate the ultra-condensed status summary from deployment data.

  static createQuickSummary(deployments: Deployment[]): string {
      if (!deployments || deployments.length === 0) {
          return "🔍 No recent deployments found";
      }
  
      const latest = deployments[0];
      const status = this.getEnvironmentStatusIcon(latest);
      const timeAgo = this.getTimeAgo(latest.startTime);
  
      return `${status} ${latest.targetEnvironment}: ${latest.status} ${timeAgo}`;
  }