Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/participants/create-case-participant.js:87-169 (handler)

  The main execute handler for the 'create_case_participant' tool. Validates inputs, auto-fetches eTag if not provided by calling getCase, then invokes pegaClient.createCaseParticipant with prepared options, and handles errors with detailed logging.

    async execute(params) {
      const { caseID, eTag, content, participantRoleID, viewType, pageInstructions } = params;
      let sessionInfo = null;
  
      try {
        sessionInfo = this.initializeSessionConfig(params);
  
        // Validate required parameters using base class
        const requiredValidation = this.validateRequiredParams(params, ['caseID', 'content', 'participantRoleID']);
        if (requiredValidation) {
          return requiredValidation;
        }
  
        // Validate enum parameters
        const enumValidation = this.validateEnumParams(params, {
          viewType: ['form', 'none']
        });
        if (enumValidation) {
          return enumValidation;
        }
  
        // Auto-fetch eTag if not provided
        let finalETag = eTag;
        let autoFetchedETag = false;
  
        if (!finalETag) {
          try {
            console.log(`Auto-fetching latest eTag for participant operation on ${caseID}...`);
            const caseResponse = await this.pegaClient.getCase(caseID.trim());
  
            if (!caseResponse || !caseResponse.success) {
              const errorMsg = `Failed to auto-fetch eTag: ${caseResponse?.error?.message || 'Unknown error'}`;
              return {
                error: errorMsg
              };
            }
  
            finalETag = caseResponse.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. This may indicate a server issue.';
              return {
                error: errorMsg
              };
            }
          } catch (error) {
            const errorMsg = `Failed to auto-fetch eTag: ${error.message}`;
            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.'
          };
        }
  
        return await this.executeWithErrorHandling(
          `Create Participant: ${caseID}`,
          async () => await this.pegaClient.createCaseParticipant(caseID.trim(), {
            eTag: finalETag,
            content,
            participantRoleID,
            viewType,
            pageInstructions
          }),
          { caseID: caseID.trim(), participantRoleID, sessionInfo }
        );
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: `## Error: Create Participant: ${caseID}\\n\\n**Unexpected Error**: ${error.message}\\n\\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
          }]
        };
      }
    }
  }

• src/tools/participants/create-case-participant.js:15-82 (schema)

  Static method providing the MCP tool definition including name 'create_case_participant', detailed description, and comprehensive inputSchema with properties, types, descriptions, enums, and required fields.

  static getDefinition() {
    return {
      name: 'create_case_participant',
      description: 'Create a new participant in a Pega case with specified role and participant information. If no eTag is provided, automatically fetches the latest eTag from the case for seamless operation. Adds users to case access control with appropriate permissions and role assignments.',
      inputSchema: {
        type: 'object',
        properties: {
          caseID: {
            type: 'string',
            description: 'Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces."ON6E5R-DIYRecipe-Work-RecipeCollection R-1008". a complete case identifier including spaces and special characters.'
          },
          eTag: {
            type: 'string',
            description: 'Optional. Auto-fetched if omitted. For faster execution, use eTag from previous response.'
          },
          content: {
            type: 'object',
            description: 'Participant information object containing user details such as name, email, phone, and other contact information. Structure matches Data-Party schema.',
            properties: {
              pyFirstName: { type: 'string', description: 'First name of the participant' },
              pyLastName: { type: 'string', description: 'Last name of the participant' },
              pyEmail1: { type: 'string', description: 'Email address of the participant' },
              pyPhoneNumber: { type: 'string', description: 'Phone number of the participant' },
              pyWorkPartyUri: { type: 'string', description: 'Unique identifier for the participant' },
              pyFullName: { type: 'string', description: 'Full name of the participant' },
              pyTitle: { type: 'string', description: 'Title of the participant' }
            }
          },
          participantRoleID: {
            type: 'string',
            description: 'Role ID to assign to the participant. This determines the permissions and access level the participant will have for the case.'
          },
          viewType: {
            type: 'string',
            enum: ['form', 'none'],
            description: 'UI resources to return. "form" returns form UI metadata, "none" returns no UI resources (default: "form")',
            default: 'form'
          },
          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'
                },
                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. Use REPLACE instruction to set embedded page references with full object including pzInsKey. Example: {"instruction": "REPLACE", "target": "PageName", "content": {"Property": "value", "pyID": "ID-123", "pzInsKey": "CLASS-NAME ID-123"}}'
            },
            description: 'Optional list of page-related operations for embedded pages, page lists, or page groups. Required for setting embedded page references.'
          },
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: ['caseID', 'content', 'participantRoleID']
      }
    };
  }

• src/api/pega-client.js:836-841 (helper)

  PegaClient wrapper method for creating case participants. Checks feature availability and delegates to the underlying client.createCaseParticipant, which is called by the tool handler.

  async createCaseParticipant(caseID, options = {}) {
    if (!this.isFeatureAvailable('participants')) {
      this.throwUnsupportedFeatureError('participants', 'createCaseParticipant');
    }
    return this.client.createCaseParticipant(caseID, options);
  }