Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/deployment/deployment-actions.ts:669-870 (handler)

  Primary handler function for the 'complete_deployment' tool. Validates args, checks deployment state, calls DXP REST API to complete deployment, emits events, starts monitoring, and formats response.
  static async handleCompleteDeployment(args: CompleteDeploymentArgs): Promise<any> { // Check if this is a self-hosted project if (args.isSelfHosted || args.connectionString) { return ResponseBuilder.invalidParams('Deployment completion is not available for self-hosted projects. Self-hosted projects can only download existing backups and blobs.'); } if (!args.apiKey || !args.apiSecret || !args.projectId || !args.deploymentId) { return ResponseBuilder.invalidParams('Missing required parameters'); } try { const result = await this.completeDeployment(args); // Check if result is already a structured response with data and message if (result && typeof result === 'object' && 'data' in result && 'message' in result) { // DXP-68: If result contains an error field, return as error response if (result.data.error) { return { error: result.message, data: result.data }; } return ResponseBuilder.successWithStructuredData(result.data, result.message); } // Fallback for legacy string responses return ResponseBuilder.success(result); } catch (error: any) { console.error('Complete deployment error:', error); return ResponseBuilder.internalError('Failed to complete deployment', error.message); } } static async completeDeployment(args: CompleteDeploymentArgs): Promise<any> { const { apiKey, apiSecret, projectId, deploymentId } = args; console.error(`Completing deployment ${deploymentId} for project ${projectId}`); // DXP-68: Validate deployment state before attempting completion console.error('Checking deployment state before completion...'); const DeploymentListOperations = require('./deployment-list'); try { const statusResult = await DeploymentListOperations.getDeploymentStatus({ apiKey, apiSecret, projectId, deploymentId }); // Extract current status from the response let currentStatus = 'Unknown'; // Check if this is a structured response (new format from DXP-66) if (statusResult && typeof statusResult === 'object' && 'data' in statusResult && 'message' in statusResult) { currentStatus = statusResult.data.status || 'Unknown'; } else if (typeof statusResult === 'string' && statusResult.includes('Status:')) { const statusMatch = statusResult.match(/Status:\s*\*\*([^*]+)\*\*/); if (statusMatch) { currentStatus = statusMatch[1].trim(); } } console.error(`Current deployment status: ${currentStatus}`); // Check if deployment is in the correct state for completion (DXP-69: Use status constants) if (!isAwaitingVerification(currentStatus)) { // Return structured error response const errorMessage = `❌ **Cannot Complete Deployment**\n\n` + `Deployment must be in **${DEPLOYMENT_STATUS.AWAITING_VERIFICATION}** state to complete.\n\n` + `**Current State**: ${currentStatus}\n` + `**Deployment ID**: ${deploymentId}\n\n` + `**Next Steps:**\n` + (isInProgress(currentStatus) ? `• Wait for deployment to reach verification state\n` + `• Use \`get_deployment_status\` to check progress\n` + `• Use \`monitor_deployment\` for continuous updates` : isSucceeded(currentStatus) ? `• Deployment is already completed - no action needed` : isFailed(currentStatus) ? `• Deployment has failed - use \`reset_deployment\` to rollback` : `• Check deployment status with \`get_deployment_status\`` ); return { data: { error: 'INVALID_STATE', deploymentId: deploymentId, currentStatus: currentStatus, requiredStatus: DEPLOYMENT_STATUS.AWAITING_VERIFICATION, canComplete: false }, message: ResponseBuilder.addFooter(errorMessage) }; } console.error('✓ Deployment is in valid state for completion'); } catch (statusError: any) { console.error('Warning: Could not check deployment status before completion:', statusError.message); // Continue with completion attempt even if status check fails // The REST API itself will fail if state is wrong } // DXP-101: Use REST API instead of PowerShell (3-10x faster, no PowerShell dependency) try { const result: DeploymentResult = await DXPRestClient.completeDeployment( projectId!, apiKey!, apiSecret!, deploymentId!, { apiUrl: args.apiUrl } // Support custom API URLs ); // DXP-47: The completion API returns immediately with status "Completing" (transitional), // not "Succeeded" (final). Format the response with the ACTUAL current status. if (result) { // DXP-136: Emit deployment completing event try { if (result.status === 'Completing') { DeploymentResourceHandler.emitCompleting(deploymentId!, { project: args.projectName, status: result.status, slotUrl: result.deploymentSlotUrl || result.DeploymentSlotUrl }); } else if (result.status === 'Succeeded') { DeploymentResourceHandler.emitSucceeded(deploymentId!, { project: args.projectName, status: result.status, slotUrl: result.deploymentSlotUrl || result.DeploymentSlotUrl }); } } catch (eventError: any) { console.error(`Failed to emit deployment completion event: ${eventError.message}`); // Don't fail the operation if event emission fails } // DXP-121: Auto-start background monitoring if enabled (default true) if (args.monitor !== false && result && result.id) { try { const monitor = getGlobalMonitor(); monitor.startMonitoring({ deploymentId: result.id || deploymentId!, projectId: args.projectId!, apiKey: args.apiKey!, apiSecret: args.apiSecret!, interval: 30 * 1000 // 30 seconds (faster polling for completion phase) }); const logger = new StructuredLogger({ context: { tool: 'complete_deployment', deployment_id: result.id || deploymentId! } }); logger.info('Auto-monitoring started for deployment completion', { deployment_id: result.id || deploymentId!, interval_ms: 30 * 1000 }); console.log('🔄 Auto-monitoring started for deployment completion'); } catch (monitorError: any) { console.error(`Failed to start monitoring: ${monitorError.message}`); // Don't fail the operation if monitoring fails } } return DeploymentFormatters.formatDeploymentCompleted(result, args.projectName, projectId); } else { // Fallback if no result returned return { data: { deploymentId: deploymentId, status: 'Unknown' }, message: ResponseBuilder.addFooter('Deployment completion initiated but status unavailable') }; } } catch (error: any) { // Handle REST API errors const errorDetails = { operation: 'Complete Deployment', projectId, projectName: args.projectName, deploymentId, apiKey }; // Check if this is an access denied error if (error.statusCode === 401 || error.statusCode === 403) { return ErrorHandler.formatError({ type: 'ACCESS_DENIED', message: 'Access denied to deployment API', statusCode: error.statusCode } as any, errorDetails); } // Generic error handling return ErrorHandler.formatError({ type: 'API_ERROR', message: error.message, statusCode: error.statusCode } as any, errorDetails); } }
• lib/tools/deployment/index.ts:26-37 (handler)

  DeploymentTools aggregator entry point that delegates 'complete_deployment' handling to DeploymentActionOperations.
  static async handleCompleteDeployment(args: any): Promise<any> { return DeploymentActionOperations.handleCompleteDeployment(args); } static async handleResetDeployment(args: any): Promise<any> { return DeploymentActionOperations.handleResetDeployment(args); } static async handleMonitorDeployment(args: any): Promise<any> { return DeploymentActionOperations.handleMonitorDeployment(args); } }
• lib/dxp-rest-client.ts:564-573 (helper)

  Low-level REST API client method that performs the actual POST request to complete the deployment via Optimizely DXP API.
  static async completeDeployment( projectId: string, clientKey: string, clientSecret: string, deploymentId: string, options: RequestOptions = {} ): Promise<any> { const uriEnding = `projects/${projectId}/deployments/${deploymentId}/complete`; return await this.makeRequest(clientKey, clientSecret, uriEnding, 'POST', {}, options); }
• lib/utils/tool-availability-matrix.ts:129-133 (registration)

  Tool registration/definition in availability matrix, specifying it's for DXP PaaS, category, description, and restriction message.
  'complete_deployment': { hostingTypes: ['dxp-paas'], category: 'Deployments', description: 'Complete an in-progress deployment', restrictedMessage: 'Completing deployments is only available for DXP PaaS hosting.'