Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/cases/create-case.js:112-248 (handler)

  Main handler function that executes the create_case tool. Handles input validation, session management, proactive field discovery with empty content, error handling, and calls pegaClient.createCase. Includes smart field discovery and guidance for missing fields.

    async execute(params) {
      const { caseTypeID, parentCaseID, processID, 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(),
            processID: processID?.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: Check if error is truly field-related before doing field discovery
        if (this.isFieldRelatedErrorInResult(emptyResult)) {
          return await this.discoverFieldsAndGuide(caseTypeID, { message: this.extractErrorMessage(emptyResult) });
        }
  
        // Not field-related, return the actual error
        return 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(),
          processID: processID?.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:23-107 (schema)

  Static method providing the tool definition for MCP protocol, including name 'create_case', detailed description, and comprehensive inputSchema defining parameters like caseTypeID, content, pageInstructions, attachments, etc.

  static getDefinition() {
    return {
      name: 'create_case',
      description: 'Create a new Pega case. This is the FIRST step in case workflows. Automatically creates the initial assignment (returned in nextAssignmentInfo). Many case types accept empty content {}. If fields required, automatic field discovery provides guidance. Returns: caseID, assignmentID (in nextAssignmentInfo.ID), eTag. Next steps: use get_assignment with assignmentID to view form fields.',
      inputSchema: {
        type: 'object',
        properties: {
          caseTypeID: {
            type: 'string',
            description: 'Case type ID (Example: "Org-App-Work-CaseType"). Use get_case_types to discover available types.'
          },
          parentCaseID: {
            type: 'string',
            description: 'Parent case ID for child case creation'
          },
          processID: {
            type: 'string',
            description: 'Starting process ID to use for case creation (Example: "pyStartCase"). Optional parameter that specifies which flow to use when creating the case. Some case types may require this to bypass initial validation.'
          },
          content: {
            type: 'object',
            description: 'Field values for case creation (optional). Empty {} often works. If fields required, automatic discovery provides guidance. For embedded pages use pageInstructions.'
          },
          pageInstructions: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                instruction: {
                  type: 'string',
                  enum: ['UPDATE', 'REPLACE', 'DELETE', 'APPEND', 'INSERT', 'MOVE'],
                  description: 'Page instruction type. 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: 'Target embedded page name (Example: "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 (Example: 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: 'UI resources 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:16-18 (registration)

  Static getCategory() method returning 'cases', used by the dynamic tool loader (src/registry/tool-loader.js) to categorize and auto-register this tool during discovery.

  static getCategory() {
    return 'cases';
  }

• src/tools/cases/create-case.js:254-291 (helper)

  Helper method for proactive field discovery using Case Type Action 'Create'. Extracts relevant fields from UI resources, groups by required/optional, and generates guidance for users when case creation fails due to missing fields.

  async discoverFieldsAndGuide(caseTypeID, originalError = null, attemptedContent = null) {
    try {
      // Use Case Type Action "Create" to get accurate creation form fields
      // This returns ~28 fields instead of 500+ from Data Views
      const actionResponse = await this.pegaClient.getCaseTypeAction(caseTypeID, 'Create');
  
      if (!actionResponse.success) {
        throw new Error(`Failed to retrieve case type action: ${actionResponse.error?.message || 'Unknown error'}`);
      }
  
      // Extract fields from UI resources
      const processedFields = this.processCaseTypeActionFields(actionResponse.data);
  
      // Format and return field discovery guidance
      return {
        content: [
          {
            type: "text",
            text: this.formatFieldDiscoveryGuidanceFromCaseTypeAction(caseTypeID, processedFields, 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-200 (helper)

  Underlying API method pegaClient.createCase(options) called by the tool handler to perform the actual case creation via Pega DX API. Handles both V1 and V2 API versions transparently.

  async createCase(options) {
    return this.client.createCase(options);
  }
  
  /**
   * Get case by ID
   * @param {string} caseID - Case ID
   * @param {Object} options - Optional parameters
   * @returns {Promise<Object>} Case details
   */
  async getCase(caseID, options = {}) {
    return this.client.getCase(caseID, options);
  }
  
  /**
   * Update case
   * V1 EXCLUSIVE - Use case actions in V2
   * @param {string} caseID - Case ID
   * @param {Object} content - Updated content
   * @returns {Promise<Object>} Updated case details
   */
  async updateCase(caseID, content) {
    if (!this.isFeatureAvailable('updateCase')) {
      this.throwUnsupportedFeatureError('updateCase', 'updateCase');
    }
    return this.client.updateCase(caseID, content);
  }
  
  /**
   * Delete case (only works for cases in create stage)
   * @param {string} caseID - Case ID
   * @returns {Promise<Object>} Deletion result
   */
  async deleteCase(caseID) {
    return this.client.deleteCase(caseID);