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); } }