Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/cases/change-to-stage.js:55-143 (handler)

  Main handler function for the 'change_to_stage' tool. Validates inputs, auto-fetches eTag if missing using getCaseAction, initializes session if provided, and executes the stage change via pegaClient.
  async execute(params) { console.log(`[DEBUG] change_to_stage execute called with params:`, JSON.stringify(params, null, 2)); const { caseID, stageID, eTag, viewType, cleanupProcesses } = 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', 'stageID']); if (requiredValidation) { return requiredValidation; } // Validate enum parameters using base class const enumValidation = this.validateEnumParams(params, { viewType: ['none', 'form', 'page'] }); if (enumValidation) { return enumValidation; } // Auto-fetch eTag if not provided let finalETag = eTag; let autoFetchedETag = false; if (!finalETag) { console.log(`[DEBUG] Starting auto-fetch for case ${caseID}`); try { console.log(`Auto-fetching latest eTag for stage change on case ${caseID}...`); const caseActionResponse = await this.pegaClient.getCaseAction(caseID.trim(), 'pyChangeStage', { viewType: 'form', // getCaseAction only accepts 'form' or 'page', not 'none' excludeAdditionalActions: true }); console.log(`[DEBUG] getCaseAction response:`, JSON.stringify(caseActionResponse, null, 2)); if (!caseActionResponse || !caseActionResponse.success) { const errorMsg = `Failed to auto-fetch eTag: ${caseActionResponse?.error?.message || 'Unknown error'}`; console.log(`[DEBUG] Auto-fetch failed: ${errorMsg}`); return { error: errorMsg }; } finalETag = caseActionResponse.eTag; autoFetchedETag = true; console.log(`Successfully auto-fetched eTag: ${finalETag}`); if (!finalETag) { const errorMsg = 'Auto-fetch succeeded but no eTag was returned from get_case_action. This may indicate a server issue.'; console.log(`[DEBUG] ${errorMsg}`); return { error: errorMsg }; } } catch (error) { const errorMsg = `Failed to auto-fetch eTag: ${error.message}`; console.log(`[DEBUG] Exception during auto-fetch: ${errorMsg}`); console.log(`[DEBUG] Stack trace:`, error.stack); return { error: errorMsg }; } } // Validate eTag format (should be a timestamp-like string) if (typeof finalETag !== 'string' || finalETag.trim().length === 0) { return { error: 'Invalid eTag parameter. a non-empty string representing case save date time.' }; } // Execute with standardized error handling return await this.executeWithErrorHandling( `Change to Stage: ${caseID} -> ${stageID}${autoFetchedETag ? ' (auto-fetched eTag)' : ''}`, async () => await this.pegaClient.changeToStage(caseID.trim(), stageID.trim(), finalETag.trim(), { viewType, cleanupProcesses }), { viewType, cleanupProcesses, autoFetchedETag, sessionInfo } ); } catch (error) { return { content: [{ type: 'text', text: `## Error: Change to Stage\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/change-to-stage.js:15-50 (schema)

  Tool schema definition including name, description, and input schema specifying required caseID/stageID and optional parameters like eTag, viewType, sessionCredentials.
  static getDefinition() { return { name: 'change_to_stage', description: 'Change to a specified stage of a case based on stageID passed. Allows navigation to any valid stage (primary, alternate) within a case workflow. If no eTag is provided, automatically fetches the latest eTag from the case action for seamless operation.', inputSchema: { type: 'object', properties: { caseID: { type: 'string', description: 'Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces.' }, stageID: { type: 'string', description: 'Stage ID to navigate to (Example: "PRIM1", "ALT1"). a valid stage identifier for the case type.' }, eTag: { type: 'string', description: 'Optional. Auto-fetched if omitted. For faster execution, use eTag from previous response.' }, viewType: { type: 'string', enum: ['none', 'form', 'page'], description: 'UI resources to return. "none" returns no UI resources (default), "form" returns form UI metadata in read-only review mode, "page" returns full page UI metadata in read-only review mode.', default: 'none' }, cleanupProcesses: { type: 'boolean', description: 'Whether to clean up the processes, including assignments, of the stage being switched away from. Default is true. Set to false to opt out of this cleanup feature.', default: true }, sessionCredentials: getSessionCredentialsSchema() }, required: ['caseID', 'stageID'] } }; }
• src/api/pega-client.js:344-349 (helper)

  PegaClient wrapper method that delegates the changeToStage call to the appropriate V1/V2 client after feature availability check.
  async changeToStage(caseID, stageID, eTag, options = {}) { if (!this.isFeatureAvailable('stageNavigation')) { this.throwUnsupportedFeatureError('stageNavigation', 'changeToStage'); } return this.client.changeToStage(caseID, stageID, eTag, options); }