Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/deployment/deployment-actions.ts:875-991 (handler)

  Primary handler implementation for the reset_deployment tool. Includes parameter validation, deployment status check, REST API call to reset, event emission, background monitoring, and response formatting.

  static async handleResetDeployment(args: ResetDeploymentArgs): Promise<any> {
      // Check if this is a self-hosted project
      if (args.isSelfHosted || args.connectionString) {
          return ResponseBuilder.invalidParams('Deployment reset 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.resetDeployment(args);
  
          // Check if result is already a 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('Reset deployment error:', error);
          return ResponseBuilder.internalError('Failed to reset deployment', error.message);
      }
  }
  
  static async resetDeployment(args: ResetDeploymentArgs): Promise<any> {
      const { apiKey, apiSecret, projectId, deploymentId, projectName } = args;
  
      console.error(`Resetting deployment ${deploymentId} for project ${projectId}`);
  
      // DXP-101: Get deployment details to determine if DB rollback is needed (using REST API)
      let includeDbRollback = false;
      let deploymentData: DeploymentResult | null = null;
  
      try {
          const statusResult: DeploymentResult = await DXPRestClient.getDeployments(
              projectId!,
              apiKey!,
              apiSecret!,
              deploymentId!,
              { apiUrl: args.apiUrl }
          );
  
          if (statusResult) {
              // Check if this deployment included database changes
              deploymentData = statusResult;
              includeDbRollback = (deploymentData as any).includeDatabase === true;
          }
      } catch (error: any) {
          console.error('Warning: Could not check deployment details before reset:', error.message);
          // Continue with reset even if we can't check details
      }
  
      // DXP-101: Use REST API instead of PowerShell (3-10x faster, no PowerShell dependency)
      let resetData: DeploymentResult = {} as DeploymentResult;
      try {
          const result: DeploymentResult = await DXPRestClient.resetDeployment(
              projectId!,
              apiKey!,
              apiSecret!,
              deploymentId!,
              {}, // No additional reset options needed
              { apiUrl: args.apiUrl } // Support custom API URLs
          );
  
          resetData = result || ({} as DeploymentResult);
  
          // Merge deployment data if available
          if (deploymentData && deploymentData.parameters) {
              resetData.parameters = deploymentData.parameters;
          }
  
          // DXP-136: Emit deployment reset event
          try {
              DeploymentResourceHandler.emitReset(deploymentId!, {
                  project: projectName,
                  includeDbRollback: includeDbRollback
              });
          } catch (eventError: any) {
              console.error(`Failed to emit deployment reset event: ${eventError.message}`);
              // Don't fail the operation if event emission fails
          }
  
          // Start monitoring the reset in the background
          this.monitorResetProgress(deploymentId!, projectId!, apiKey!, apiSecret!, projectName, args.apiUrl);
  
          // Format response
          return DeploymentFormatters.formatDeploymentReset(resetData, includeDbRollback, projectName);
  
      } catch (error: any) {
          // Handle REST API errors
          const errorDetails = {
              operation: 'Reset 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/deployment-actions.ts:57-68 (schema)

  TypeScript interface defining the input parameters/schema for the reset_deployment tool.

   * Reset deployment arguments
   */
  interface ResetDeploymentArgs {
      apiKey?: string;
      apiSecret?: string;
      projectId?: string;
      projectName?: string;
      deploymentId?: string;
      isSelfHosted?: boolean;
      connectionString?: string;
      apiUrl?: string;
  }

• lib/tools/deployment/index.ts:30-32 (handler)

  Thin wrapper handler in DeploymentTools that delegates to the main implementation in deployment-actions.ts.

  static async handleResetDeployment(args: any): Promise<any> {
      return DeploymentActionOperations.handleResetDeployment(args);
  }

• lib/dxp-rest-client.ts:587-597 (helper)

  Core REST API client method that performs the actual HTTP POST request to the Optimizely DXP API endpoint for resetting a deployment.

  static async resetDeployment(
      projectId: string,
      clientKey: string,
      clientSecret: string,
      deploymentId: string,
      resetOptions: ResetOptions = {},
      options: RequestOptions = {}
  ): Promise<any> {
      const uriEnding = `projects/${projectId}/deployments/${deploymentId}/reset`;
      return await this.makeRequest(clientKey, clientSecret, uriEnding, 'POST', resetOptions, options);
  }

• lib/resources/deployment-resource.ts:223-241 (registration)

  Event emission handler that registers the 'reset_deployment' operation for resource notifications and MCP client updates.

  static emitReset(deploymentId: string, details: DeploymentDetails = {}): DXPEvent {
      const emitter = getGlobalEmitter();
      const event = createEvent(
          EVENT_TYPES.DEPLOYMENT_RESET,
          deploymentId,
          {
              deploymentId,
              status: 'Reset',
              ...details
          },
          {
              operation: 'reset_deployment',
              user: 'system'
          }
      );
  
      emitter.emitEvent(event);
      return event;
  }