Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/attachments/add-case-attachments.js:70-103 (handler)

  Main handler function that orchestrates the tool execution: parameter validation, session initialization, API call to pegaClient.addCaseAttachments, and error handling with custom formatted responses.

  async execute(params) {
    const { caseID, attachments } = params;
  
    let sessionInfo = null;
    try {
      sessionInfo = this.initializeSessionConfig(params);
  
      // Basic parameter validation using base class
      const requiredValidation = this.validateRequiredParams(params, ['caseID', 'attachments']);
      if (requiredValidation) {
        return this.createErrorResponse(`Add Attachments to Case: ${caseID || 'UNKNOWN'}`, { message: requiredValidation.error }, { caseID, attachments });
      }
  
      // Additional comprehensive parameter validation for complex logic
      const validationResult = this.validateParameters(caseID, attachments);
      if (!validationResult.valid) {
        return this.createErrorResponse(`Add Attachments to Case: ${caseID}`, { message: validationResult.error }, { caseID, attachments });
      }
  
      // Execute with standardized error handling
      return await this.executeWithErrorHandling(
        `Add Attachments to Case: ${caseID}`,
        async () => await this.pegaClient.addCaseAttachments(caseID, attachments),
        { caseID, attachments, sessionInfo }
      );
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `## Error: Add Attachments to Case\n\n**Unexpected Error**: ${error.message}\n\n${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
        }]
      };
    }
  }

• src/tools/attachments/add-case-attachments.js:15-65 (schema)

  Static method providing the tool's MCP definition: name, description, and detailed input schema specifying caseID and attachments (array of File or URL objects).

  static getDefinition() {
    return {
      name: 'add_case_attachments',
      description: 'Attach files and/or URLs to a Pega case regardless of the context or stage of the case lifecycle. Can attach temporary uploaded files using their IDs (from upload_attachment tool), or add URL/link attachments directly. Supports multiple attachments in a single atomic operation - if any attachment fails, no attachments are added to the case.',
      inputSchema: {
        type: 'object',
        properties: {
          caseID: {
            type: 'string',
            description: 'Case ID. Example: "MYORG-APP-WORK C-1001". Complete identifier including spaces."OSIEO3-DOCSAPP-WORK T-561003". a complete case identifier including spaces and special characters.'
          },
          attachments: {
            type: 'array',
            description: 'Array of attachment objects to add to the case. Can contain file attachments (using temporary attachment IDs from upload_attachment tool) and/or URL attachments. All attachments must be successfully processed or none will be attached (atomic operation).',
            items: {
              type: 'object',
              properties: {
                type: {
                  type: 'string',
                  enum: ['File', 'URL'],
                  description: 'Attachment type. "File" for file attachments or "URL" for URL/link attachments.'
                },
                category: {
                  type: 'string',
                  enum: ['File', 'URL'],
                  description: 'Attachment category. Must match the type ("File" or "URL").'
                },
                ID: {
                  type: 'string',
                  description: 'Temporary attachment ID returned from upload_attachment tool (required for File type). Example: "450b7275-8868-43ca-9827-bcfd9ec1b54b". Note: Temporary attachments expire after 2 hours if not linked to a case.'
                },
                url: {
                  type: 'string',
                  description: 'URL/link to attach to the case (required for URL type). Example: "https://www.google.com". a valid URL format.'
                },
                name: {
                  type: 'string',
                  description: 'Display name for the URL attachment (required for URL type). Example: "google". This will be shown as the attachment name in the case.'
                }
              },
              required: ['type', 'category']
            },
            minItems: 1,
            maxItems: 50
          },
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: ['caseID', 'attachments']
      }
    };
  }

• src/tools/attachments/add-case-attachments.js:108-149 (helper)

  Comprehensive validation helper for caseID and attachments: checks format, array length (1-50), and delegates to validateAttachmentObject for each item.

  validateParameters(caseID, attachments) {
    // Validate caseID
    if (!caseID || typeof caseID !== 'string' || caseID.trim() === '') {
      return {
        valid: false,
        error: 'Invalid caseID parameter. Case ID must be a non-empty string containing the full case handle.'
      };
    }
  
    // Validate attachments array
    if (!attachments || !Array.isArray(attachments)) {
      return {
        valid: false,
        error: 'Invalid attachments parameter. Attachments must be a non-empty array of attachment objects.'
      };
    }
  
    if (attachments.length === 0) {
      return {
        valid: false,
        error: 'Attachments array cannot be empty. Please provide at least one attachment to add to the case.'
      };
    }
  
    if (attachments.length > 50) {
      return {
        valid: false,
        error: 'Too many attachments provided. Maximum of 50 attachments can be added in a single operation.'
      };
    }
  
    // Validate each attachment object
    for (let i = 0; i < attachments.length; i++) {
      const attachment = attachments[i];
      const attachmentValidation = this.validateAttachmentObject(attachment, i);
      if (!attachmentValidation.valid) {
        return attachmentValidation;
      }
    }
  
    return { valid: true };
  }

• src/tools/attachments/add-case-attachments.js:154-261 (helper)

  Validates individual attachment objects: ensures type/category match ('File'/'URL'), required fields (ID for File, url/name for URL), URL format, no extra properties.

  validateAttachmentObject(attachment, index) {
    if (!attachment || typeof attachment !== 'object') {
      return {
        valid: false,
        error: `Invalid attachment at index ${index}. Each attachment must be an object with required properties.`
      };
    }
  
    const { type, category } = attachment;
  
    // Validate required type field
    if (!type || typeof type !== 'string') {
      return {
        valid: false,
        error: `Missing or invalid 'type' field in attachment at index ${index}. Type must be either "File" or "URL".`
      };
    }
  
    // Validate required category field
    if (!category || typeof category !== 'string') {
      return {
        valid: false,
        error: `Missing or invalid 'category' field in attachment at index ${index}. Category must match the type ("File" or "URL").`
      };
    }
  
    // Validate File attachment
    if (type === 'File') {
      if (category !== 'File') {
        return {
          valid: false,
          error: `Invalid category for File attachment at index ${index}. Category must be "File" when type is "File".`
        };
      }
  
      const { ID } = attachment;
      if (!ID || typeof ID !== 'string' || ID.trim() === '') {
        return {
          valid: false,
          error: `Missing or invalid 'ID' field in File attachment at index ${index}. ID must be a non-empty string containing the temporary attachment ID from upload_attachment tool.`
        };
      }
  
      // Check for unexpected properties
      const allowedProps = ['type', 'category', 'ID'];
      const extraProps = Object.keys(attachment).filter(prop => !allowedProps.includes(prop));
      if (extraProps.length > 0) {
        return {
          valid: false,
          error: `Unexpected properties in File attachment at index ${index}: ${extraProps.join(', ')}. File attachments only support: type, category, ID.`
        };
      }
    }
    // Validate URL attachment
    else if (type === 'URL') {
      if (category !== 'URL') {
        return {
          valid: false,
          error: `Invalid category for URL attachment at index ${index}. Category must be "URL" when type is "URL".`
        };
      }
  
      const { url, name } = attachment;
      
      if (!url || typeof url !== 'string' || url.trim() === '') {
        return {
          valid: false,
          error: `Missing or invalid 'url' field in URL attachment at index ${index}. URL must be a non-empty string containing a valid URL.`
        };
      }
  
      // Basic URL format validation
      try {
        new URL(url.trim());
      } catch (urlError) {
        return {
          valid: false,
          error: `Invalid URL format in URL attachment at index ${index}: "${url}". Please provide a valid URL (Example: "https://www.example.com").`
        };
      }
  
      if (!name || typeof name !== 'string' || name.trim() === '') {
        return {
          valid: false,
          error: `Missing or invalid 'name' field in URL attachment at index ${index}. Name must be a non-empty string for the display name of the URL attachment.`
        };
      }
  
      // Check for unexpected properties
      const allowedProps = ['type', 'category', 'url', 'name'];
      const extraProps = Object.keys(attachment).filter(prop => !allowedProps.includes(prop));
      if (extraProps.length > 0) {
        return {
          valid: false,
          error: `Unexpected properties in URL attachment at index ${index}: ${extraProps.join(', ')}. URL attachments only support: type, category, url, name.`
        };
      }
    }
    // Invalid type
    else {
      return {
        valid: false,
        error: `Invalid attachment type "${type}" at index ${index}. Type must be either "File" or "URL".`
      };
    }
  
    return { valid: true };
  }

• src/api/pega-client.js:587-588 (helper)

  PegaClient wrapper method called by the tool handler to perform the actual API call to add attachments to a case.

  async addCaseAttachments(caseID, attachments) {
    return this.client.addCaseAttachments(caseID, attachments);