Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/cases/create-case.js:100-229 (handler)

  Core handler for 'create_case' tool execution. Validates inputs, performs proactive and reactive field discovery, executes Pega API call via pegaClient.createCase, and provides detailed guidance on failures.
  async execute(params) { const { caseTypeID, parentCaseID, content, pageInstructions, attachments, viewType, pageName } = 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, ['caseTypeID']); if (requiredValidation) { return requiredValidation; } // Validate enum parameters using base class const enumValidation = this.validateEnumParams(params, { viewType: ['none', 'form', 'page'] }); if (enumValidation) { return enumValidation; } // Validate pageName usage if (pageName && viewType !== 'page') { return { error: 'pageName parameter can only be used when viewType is set to "page".' }; } // Validate parentCaseID format if provided if (parentCaseID && (typeof parentCaseID !== 'string' || parentCaseID.trim() === '')) { return { error: 'Invalid parentCaseID parameter. Parent case ID must be a non-empty string if provided.' }; } // PROACTIVE: Auto-discover when no content provided // Try creation with empty content first for both V1 and V2 (many case types accept empty content) if (!content || Object.keys(content).length === 0) { const apiVersion = this.pegaClient.getApiVersion(); // Try creation with empty content first (works for many case types) const emptyResult = await this.executeWithErrorHandling( `Case Creation: ${caseTypeID}`, async () => await this.pegaClient.createCase({ caseTypeID: caseTypeID.trim(), parentCaseID: parentCaseID?.trim(), content: {}, pageInstructions, attachments, viewType, pageName }), { caseTypeID, viewType, pageName, sessionInfo } ); // If empty content worked, return success if (emptyResult.content && emptyResult.content[0].text.includes('✅')) { return emptyResult; } // If it failed, provide version-specific guidance if (apiVersion === 'v1') { // V1: Field discovery not supported, provide manual guidance return { content: [{ type: 'text', text: `## V1 Case Creation Failed ${emptyResult.content?.[0]?.text || 'Case creation with empty content failed.'} **Note**: Traditional DX API (V1) does not support automatic field discovery. ### To create a case with V1 API: Provide the content object with your case fields directly: \`\`\`json { "caseTypeID": "${caseTypeID}", "content": { "YourField1": "value1", "YourField2": "value2" } } \`\`\` **Tip**: Consult your Pega application's case type configuration to determine which fields are required.` }] }; } // V2: Perform automatic field discovery to help user return await this.discoverFieldsAndGuide(caseTypeID, { message: this.extractErrorMessage(emptyResult) }); } // NORMAL: Try creation with provided content const result = await this.executeWithErrorHandling( `Case Creation: ${caseTypeID}`, async () => await this.pegaClient.createCase({ caseTypeID: caseTypeID.trim(), parentCaseID: parentCaseID?.trim(), content, pageInstructions, attachments, viewType, pageName }), { caseTypeID, viewType, pageName, sessionInfo } ); // REACTIVE: If the result contains a field-related error, auto-discover and guide if (this.isFieldRelatedErrorInResult(result)) { return await this.discoverFieldsAndGuide(caseTypeID, { message: this.extractErrorMessage(result) }, content); } return result; } catch (error) { return { content: [{ type: 'text', text: `## Error: Create Case **Unexpected Error**: ${error.message} ${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*` }] }; } }
• src/tools/cases/create-case.js:15-95 (schema)

  Defines the MCP tool schema for 'create_case' including input parameters like caseTypeID (required), content, pageInstructions for embedded pages, attachments, viewType, and session credentials.
  static getDefinition() { return { name: 'create_case', description: 'Create a new Pega case with specified case type and optional content. If no content is provided, the tool will automatically discover available fields and provide guidance. If case creation fails due to field issues, field discovery will be performed automatically.', inputSchema: { type: 'object', properties: { caseTypeID: { type: 'string', description: 'The class of the case being created (required)' }, parentCaseID: { type: 'string', description: 'The ID of the case serving as the parent case (optional)' }, content: { type: 'object', description: 'A map of scalar properties and embedded page properties to be set upon case creation (optional). If not provided, the tool will discover available fields and return guidance with examples.' }, pageInstructions: { type: 'array', items: { type: 'object', properties: { instruction: { type: 'string', enum: ['UPDATE', 'REPLACE', 'DELETE', 'APPEND', 'INSERT', 'MOVE'], description: 'The type of page instruction: UPDATE (add fields to page), REPLACE (replace entire page), DELETE (remove page), APPEND (add item to page list), INSERT (insert item in page list), MOVE (reorder page list items)' }, target: { type: 'string', description: 'The target embedded page name (e.g., "Collection", "Datasource")' }, content: { type: 'object', description: 'Content to set on the embedded page (required for UPDATE and REPLACE)' } }, required: ['instruction', 'target'], description: 'Page operation for embedded pages. IMPORTANT: Use REPLACE instruction to set embedded page references like Collection or Datasource with full object including pzInsKey. Example: {"instruction": "REPLACE", "target": "Collection", "content": {"CollectionName": "knowledge", "pyID": "DC-1", "pzInsKey": "PEGAFW-QNA-WORK DC-1"}}' }, description: 'Optional list of page-related operations for embedded pages, page lists, or page groups. Required for setting embedded page references (e.g., Collection, Datasource). See Pega DX API documentation on page instructions for embedded pages.' }, attachments: { type: 'array', items: { type: 'object', properties: { fileName: { type: 'string', description: 'Name of the attachment file' }, fileContent: { type: 'string', description: 'Base64 encoded file content' }, mimeType: { type: 'string', description: 'MIME type of the attachment' } }, description: 'Attachment object with file details and metadata' }, description: 'A list of attachments to be added to specific attachment fields (optional)' }, viewType: { type: 'string', enum: ['none', 'form', 'page'], description: 'Type of view data to return. "none" returns no UI resources, "form" returns form UI metadata, "page" returns full page UI metadata', default: 'none' }, pageName: { type: 'string', description: 'If provided, view metadata for specific page name will be returned (only used when viewType is "page")' }, sessionCredentials: getSessionCredentialsSchema() }, required: ['caseTypeID'] } }; }
• src/tools/cases/create-case.js:234-289 (helper)

  Key helper method for automatic field discovery. Retrieves case data objects, data view metadata, processes fields (filtering OOTB), and formats guidance with examples for users when content is missing or invalid.
  async discoverFieldsAndGuide(caseTypeID, originalError = null, attemptedContent = null) { try { // Step 1: Get case data objects to find the default list data view const dataObjectsResponse = await this.pegaClient.getDataObjects({ type: 'case' }); if (!dataObjectsResponse.success) { throw new Error(`Failed to retrieve case data objects: ${dataObjectsResponse.error?.message || 'Unknown error'}`); } // Step 2: Find the matching case type in the data objects const dataObjects = dataObjectsResponse.data?.dataObjects || dataObjectsResponse.data; const caseTypeData = this.findCaseTypeInDataObjects(dataObjects, caseTypeID); if (!caseTypeData) { throw new Error(`Case type "${caseTypeID}" not found in available data objects`); } if (!caseTypeData.defaultListDataView) { throw new Error(`No default list data view found for case type "${caseTypeID}"`); } // Step 3: Get field metadata from the data view const fieldMetadataResponse = await this.pegaClient.getDataViewMetadata(caseTypeData.defaultListDataView); if (!fieldMetadataResponse.success) { throw new Error(`Failed to retrieve field metadata for data view "${caseTypeData.defaultListDataView}": ${fieldMetadataResponse.error?.message || 'Unknown error'}`); } // Step 4: Process field metadata and filter out OOTB fields const processedFields = this.processDataViewFields(fieldMetadataResponse.data); // Format and return field discovery guidance return { content: [ { type: "text", text: this.formatFieldDiscoveryGuidanceFromDataView(caseTypeID, processedFields, caseTypeData, originalError, attemptedContent) } ] }; } catch (discoveryError) { // If field discovery fails, return a helpful fallback message let errorMessage = `Unable to discover fields for case type "${caseTypeID}".`; if (originalError) { errorMessage += `\n\nOriginal creation error: ${originalError.message}`; } errorMessage += `\n\nField discovery error: ${discoveryError.message}`; errorMessage += `\n\nPlease verify the case type ID is correct and accessible.`; return { error: errorMessage }; } }
• src/api/pega-client.js:166-167 (helper)

  Underlying Pega client method delegated to by the CreateCaseTool handler for performing the actual case creation API call.
  async createCase(options) { return this.client.createCase(options);