Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/attachments/get-attachment.js:36-77 (handler)

  The main execute method implementing the get_attachment tool. Validates attachmentID, initializes session, and calls pegaClient.getAttachmentContent(attachmentID) with error handling.

  async execute(params) {
    const { attachmentID } = params;
  
    let sessionInfo = null;
    try {
      sessionInfo = this.initializeSessionConfig(params);
  
      // Basic parameter validation using base class
      const requiredValidation = this.validateRequiredParams(params, ['attachmentID']);
      if (requiredValidation) {
        return requiredValidation;
      }
  
      // Additional comprehensive parameter validation for complex logic
      const validationResult = this.validateParameters(attachmentID);
      if (!validationResult.valid) {
        // Return proper MCP error response format
        return {
          content: [
            {
              type: 'text',
              text: `## Parameter Validation Error\n\n**Error**: ${validationResult.error}\n\n**Solution**: Please provide a valid Link-Attachment instance pzInsKey and try again.`
            }
          ]
        };
      }
  
      // Execute with standardized error handling
      return await this.executeWithErrorHandling(
        `Attachment Content: ${attachmentID}`,
        async () => await this.pegaClient.getAttachmentContent(attachmentID),
        { attachmentID, sessionInfo }
      );
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `## Error: Attachment Content\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/get-attachment.js:15-31 (schema)

  Static getDefinition method providing the tool name, description, and inputSchema for MCP protocol validation.

  static getDefinition() {
    return {
      name: 'get_attachment',
      description: 'Get the attachment content based on the attachmentID. Returns different content types: Base64 data for file type attachments, URL for URL type attachments, and HTML data for correspondence type attachments. The API validates the attachmentID and checks if the user has access to view the attachment before returning the content.',
      inputSchema: {
        type: 'object',
        properties: {
          attachmentID: {
            type: 'string',
            description: 'Link-Attachment instance pzInsKey (attachment ID) to retrieve content for. Format example: "LINK-ATTACHMENT MYCO-PAC-WORK E-47009!20231016T062800.275 GMT". This is the complete instance handle key that uniquely identifies the attachment in the Pega system. The attachment must exist and be accessible to the current user.'
          },
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: ['attachmentID']
      }
    };
  }

• src/tools/attachments/get-attachment.js:82-100 (helper)

  validateParameters helper method for comprehensive attachmentID validation including format checks.

  validateParameters(attachmentID) {
    // Validate attachmentID
    if (!attachmentID || typeof attachmentID !== 'string' || attachmentID.trim() === '') {
      return {
        valid: false,
        error: 'Invalid attachmentID parameter. Attachment ID must be a non-empty string containing the full Link-Attachment instance handle (Example: "LINK-ATTACHMENT MYCO-PAC-WORK E-47009!20231016T062800.275 GMT").'
      };
    }
  
    // Basic format validation for Link-Attachment instance key
    if (!attachmentID.includes('LINK-ATTACHMENT')) {
      return {
        valid: false,
        error: 'Invalid attachmentID format. Expected Link-Attachment instance pzInsKey format (Example: "LINK-ATTACHMENT MYCO-PAC-WORK E-47009!20231016T062800.275 GMT").'
      };
    }
  
    return { valid: true };
  }

• src/registry/tool-loader.js:111-134 (registration)

  Dynamic registration in ToolLoader: finds GetAttachmentTool class, validates, instantiates, and registers by name 'get_attachment' in loadedTools map.

    const ToolClass = this.findToolClass(module);
    if (!ToolClass) {
      console.warn(`No valid tool class found in ${filename}`);
      return null;
    }
    
    // Validate tool class
    if (!this.validateToolClass(ToolClass, category, filename)) {
      return null;
    }
    
    // Create and register tool instance
    const toolInstance = new ToolClass();
    const toolName = ToolClass.getDefinition().name;
    
    this.loadedTools.set(toolName, {
      instance: toolInstance,
      class: ToolClass,
      category: category,
      filename: filename
    });
    
    return toolInstance;
  } catch (error) {

• src/api/pega-client.js:606-616 (helper)

  PegaClient.getAttachmentContent method called by the tool handler to fetch attachment content from Pega API.

  async getAttachmentContent(attachmentID) {
    return this.client.getAttachmentContent(attachmentID);
  }
  
  /**
   * Delete attachment
   * @param {string} attachmentID - Attachment ID
   * @returns {Promise<Object>} Deletion result
   */
  async deleteAttachment(attachmentID) {
    return this.client.deleteAttachment(attachmentID);