Optimizely DXP MCP Server

Instructions

Implementation Reference

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

  Entry point handler for the list_deployments tool. Validates inputs, handles self-hosted restrictions, calls core listDeployments method, and formats response.

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

• lib/tools/deployment/deployment-list.ts:14-28 (schema)

  TypeScript interface defining input parameters for list_deployments tool.

  interface ListDeploymentsArgs {
      apiKey?: string;
      apiSecret?: string;
      projectId?: string;
      projectName?: string;
      limit?: number;
      offset?: number;
      activeOnly?: boolean;
      status?: string;
      environmentSlot?: string;
      format?: 'concise' | 'detailed';
      isSelfHosted?: boolean;
      connectionString?: string;
      apiUrl?: string;
  }

• lib/tools/deployment/deployment-list.ts:93-183 (helper)

  Core implementation: Fetches deployments via DXPRestClient.getDeployments, filters by activeOnly/status/environmentSlot, supports concise/detailed format, handles errors.

  static async listDeployments(args: ListDeploymentsArgs): Promise<any> {
      const { apiKey, apiSecret, projectId, limit, activeOnly = false, status, environmentSlot, format = 'detailed' } = args;
  
      // DXP-101: Use REST API instead of PowerShell (3-10x faster, no PowerShell dependency)
      try {
          // Get deployments directly from REST API
          const deployments: DeploymentResponse | DeploymentResponse[] = await DXPRestClient.getDeployments(
              projectId!,
              apiKey!,
              apiSecret!,
              null, // No specific deployment ID - get all
              { apiUrl: args.apiUrl } // Support custom API URLs for Optimizely internal team
          );
  
          // Ensure we have an array
          let deploymentList: DeploymentResponse[] = Array.isArray(deployments) ? deployments : [deployments];
  
          // DXP-103: Filter to active deployments only if requested
          if (activeOnly) {
              const activeStatuses = ['InProgress', 'AwaitingVerification', 'Resetting', 'Completing'];
              deploymentList = deploymentList.filter(dep =>
                  dep.Status && activeStatuses.includes(dep.Status)
              );
          }
  
          // DXP-76-1: Filter by specific status
          if (status) {
              deploymentList = deploymentList.filter(dep => dep.Status === status);
          }
  
          // DXP-76-1: Filter by environment slot
          if (environmentSlot) {
              deploymentList = deploymentList.filter(dep =>
                  (dep as any).parameters?.environmentSlot === environmentSlot ||
                  (dep as any).TargetEnvironment === environmentSlot
              );
          }
  
          // DXP-76-1: Format response based on format parameter
          if (format === 'concise') {
              // Concise format - return minimal fields for token efficiency
              const conciseList = deploymentList.map(dep => ({
                  id: (dep as any).Id || (dep as any).id,
                  status: dep.Status,
                  environment: (dep as any).parameters?.environmentSlot || (dep as any).TargetEnvironment,
                  startTime: (dep as any).StartTime || (dep as any).Created,
                  percentComplete: dep.PercentComplete || 0
              }));
  
              // Apply limit if specified
              const limited = limit ? conciseList.slice(0, limit) : conciseList;
  
              return {
                  data: { deployments: limited, count: limited.length },
                  message: ResponseBuilder.addFooter(`Found ${limited.length} deployment(s)`)
              };
          }
  
          // Detailed format - use existing formatter
          if (deploymentList.length > 0) {
              return DeploymentFormatters.formatDeploymentList(deploymentList as any, projectId!, limit, args.projectName);
          }
  
          return ResponseBuilder.addFooter(activeOnly ? 'No active deployments found' : 'No deployments found');
  
      } catch (error: any) {
          // Handle REST API errors
          const errorDetails = {
              operation: 'List Deployments',
              projectId,
              projectName: args.projectName,
              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:13-15 (handler)

  DeploymentTools wrapper handler that delegates to DeploymentListOperations.handleListDeployments.

  static async handleListDeployments(args: any): Promise<any> {
      return DeploymentListOperations.handleListDeployments(args);
  }

• lib/utils/tool-availability-matrix.ts:141-145 (helper)

  Tool metadata/availability definition for list_deployments, including hosting restrictions and description.

  'list_deployments': {
      hostingTypes: ['dxp-paas'],
      category: 'Deployments',
      description: 'List recent deployments',
      restrictedMessage: 'Deployment history is only available for DXP PaaS hosting.'