Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/cases/add-optional-process.js:46-82 (handler)

  The main handler function that executes the tool's core logic: validates inputs, initializes session, and calls the Pega API to add an optional process to a case.

  async execute(params) {
    const { caseID, processID, viewType } = params;
    let sessionInfo = null;
  
    try {
      // Initialize session configuration if provided
      sessionInfo = this.initializeSessionConfig(params);
  
      // Validate required parameters using base class
      const requiredValidation = this.validateRequiredParams(params, ['caseID', 'processID']);
      if (requiredValidation) {
        return requiredValidation;
      }
  
      // Validate enum parameters using base class
      const enumValidation = this.validateEnumParams(params, {
        viewType: ['none', 'form', 'page']
      });
      if (enumValidation) {
        return enumValidation;
      }
  
      // Execute with standardized error handling
      return await this.executeWithErrorHandling(
        `Add Optional Process: ${processID} to case ${caseID}`,
        async () => await this.pegaClient.addOptionalProcess(caseID.trim(), processID.trim(), { viewType }),
        { processID, viewType, sessionInfo }
      );
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `## Error: Add Optional Process\n\n**Unexpected Error**: ${error.message}\n\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
        }]
      };
    }
  }

• src/tools/cases/add-optional-process.js:15-41 (schema)

  Defines the tool schema for MCP, including name, description, input parameters (caseID, processID, optional viewType and sessionCredentials), and validation rules.

  static getDefinition() {
    return {
      name: 'add_optional_process',
      description: 'Add stage or case-wide optional process and return details of the next assignment in the process. The API is invoked when a user tries to initiate an optional action listed under case actions which are configured and designed as a process under case wide actions or stage-only actions.',
      inputSchema: {
        type: 'object',
        properties: {
          caseID: {
            type: 'string',
            description: 'Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces."MYORG-SERVICES-WORK S-293001". a complete case identifier including spaces and special characters.'
          },
          processID: {
            type: 'string',
            description: 'Process ID - Name of the process which is the ID of a flow rule. Example: "UpdateContactDetails". ProcessID can be retrieved with a lookup for ID attribute under availableProcesses node of a DX API response.'
          },
          viewType: {
            type: 'string',
            enum: ['none', 'form', 'page'],
            description: 'UI resources to return. "none" returns no uiResources, data.caseInfo.content contains the fields of the pyDetails view (default), "form" returns the form UI metadata (read-only review mode, without page-specific metadata) in the uiResources object, "page" returns the full page (read-only review mode) UI metadata in the uiResources object.',
            default: 'none'
          },
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: ['caseID', 'processID']
      }
    };
  }

• src/tools/cases/add-optional-process.js:8-10 (registration)

  Static method returning the tool category 'cases', used by the dynamic tool loader for categorization and discovery.

  static getCategory() {
    return 'cases';
  }

• src/api/pega-client.js:359-364 (helper)

  Helper method in PegaClient that routes the addOptionalProcess call to the appropriate API version client (V1/V2), enforcing feature availability checks.

  async addOptionalProcess(caseID, processID, options = {}) {
    if (!this.isFeatureAvailable('stageNavigation')) {
      this.throwUnsupportedFeatureError('stageNavigation', 'addOptionalProcess');
    }
    return this.client.addOptionalProcess(caseID, processID, options);
  }

• src/registry/tool-loader.js:278-279 (helper)

  Dynamic tool loader instance that discovers and registers all tools, including add_optional_process, by scanning directories and using getDefinition().

  export const toolLoader = new ToolLoader();