Pega DX MCP Server

Instructions

Implementation Reference

• src/tools/cases/get-cases.js:48-97 (handler)

  Core handler logic for the get_cases tool: initializes session configuration, enforces V1 API requirement, calls pegaClient.getAllCases(), and provides standardized error handling.

    async execute(params) {
      let sessionInfo = null;
  
      try {
        // Initialize session configuration if provided
        sessionInfo = this.initializeSessionConfig(params);
  
        // Check API version
        const apiVersion = this.pegaClient.getApiVersion();
        if (apiVersion !== 'v1') {
          return {
            content: [{
              type: 'text',
              text: `## Error: Get Cases (V1 Exclusive)
  
  **Version Mismatch**: This endpoint is only available in Traditional DX API (V1).
  
  **Current API Version**: ${apiVersion.toUpperCase()}
  
  **Solution**: Set \`PEGA_API_VERSION=v1\` environment variable to use this endpoint.
  
  **V2 Alternative**: Use Data Views to query cases:
  - Tool: \`get_list_data_view\`
  - Data View: \`D_MyCaseList\` or similar case list data view
  - Filter by: \`pyCreatedBy\` = current user
  
  ${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
            }]
          };
        }
  
        // Execute with standardized error handling
        return await this.executeWithErrorHandling(
          'Get All Cases (V1)',
          async () => await this.pegaClient.getAllCases(),
          { sessionInfo }
        );
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: `## Error: Get Cases
  
  **Unexpected Error**: ${error.message}
  
  ${sessionInfo ? `**Session**: ${sessionInfo.sessionId} (${sessionInfo.authMode} mode)\n` : ''}*Error occurred at: ${new Date().toISOString()}*`
          }]
        };
      }
    }

• src/tools/cases/get-cases.js:31-42 (schema)

  Tool schema definition for MCP protocol, specifying name 'get_cases', detailed description, and optional sessionCredentials input schema.

  static getDefinition() {
    return {
      name: 'get_cases',
      description: 'Get all cases created by authenticated user (V1 EXCLUSIVE - max 500 cases, oldest to newest). V2 users should use Data Views instead. Requires pxGetCases privilege.',
      inputSchema: {
        type: 'object',
        properties: {
          sessionCredentials: getSessionCredentialsSchema()
        },
        required: []
      }
    };

• src/tools/cases/get-cases.js:102-187 (helper)

  Custom response formatter for get_cases results: displays metadata, groups cases by status, details first 10 cases, warns on truncation, includes V1-specific notes.

  formatSuccessResponse(operation, data, options = {}) {
    const { sessionInfo } = options;
  
    let response = `## ${operation}\n\n`;
    response += `*Operation completed at: ${new Date().toISOString()}*\n\n`;
  
    // Session Information (if applicable)
    if (sessionInfo) {
      response += `### Session Information\n`;
      response += `- **Session ID**: ${sessionInfo.sessionId}\n`;
      response += `- **Authentication Mode**: ${sessionInfo.authMode.toUpperCase()}\n`;
      response += `- **Configuration Source**: ${sessionInfo.configSource}\n\n`;
    }
  
    // Display metadata prominently
    if (data.metadata) {
      response += '### 📊 Results Metadata\n';
      response += `- **Total Cases Retrieved**: ${data.metadata.count}\n`;
      response += `- **Maximum Records**: ${data.metadata.maxRecords} (pyMaxRecords DSS)\n`;
      response += `- **API Version**: ${data.metadata.apiVersion.toUpperCase()}\n`;
      response += `- **Order**: Oldest to Newest\n\n`;
  
      if (data.metadata.count === data.metadata.maxRecords) {
        response += `⚠️  **Warning**: Result set may be truncated at ${data.metadata.maxRecords} records.\n\n`;
      }
    }
  
    // Cases section header
    response += '### 📋 Cases\n\n';
  
    // Display cases summary
    if (data.data && data.data.cases && data.data.cases.length > 0) {
      response += `**Found ${data.data.cases.length} cases**\n\n`;
  
      // Group cases by status for better overview
      const casesByStatus = {};
      data.data.cases.forEach(c => {
        const status = c.status || 'Unknown';
        if (!casesByStatus[status]) {
          casesByStatus[status] = [];
        }
        casesByStatus[status].push(c);
      });
  
      response += '#### Status Summary\n';
      Object.keys(casesByStatus).forEach(status => {
        response += `- **${status}**: ${casesByStatus[status].length} cases\n`;
      });
      response += '\n';
  
      // Display first 10 cases in detail
      response += '#### Case Details (First 10)\n\n';
      const casesToShow = data.data.cases.slice(0, 10);
      casesToShow.forEach((caseObj, index) => {
        response += `##### ${index + 1}. ${caseObj.ID}\n`;
        response += `- **Case Type**: ${caseObj.caseTypeID || 'N/A'}\n`;
        response += `- **Name**: ${caseObj.name || 'N/A'}\n`;
        response += `- **Status**: ${caseObj.status || 'N/A'}\n`;
        response += `- **Stage**: ${caseObj.stage || 'N/A'}\n`;
        response += `- **Urgency**: ${caseObj.urgency || 0}\n`;
        response += `- **Created**: ${caseObj.createTime || 'N/A'} by ${caseObj.createdBy || 'N/A'}\n`;
        response += `- **Last Updated**: ${caseObj.lastUpdateTime || 'N/A'} by ${caseObj.lastUpdatedBy || 'N/A'}\n`;
        if (caseObj.parentCaseID) {
          response += `- **Parent Case**: ${caseObj.parentCaseID}\n`;
        }
        response += '\n';
      });
  
      if (data.data.cases.length > 10) {
        response += `*... and ${data.data.cases.length - 10} more cases*\n\n`;
      }
    } else {
      response += 'No cases found for the authenticated user.\n\n';
    }
  
    // Add V1 notes
    response += '### 📝 V1 API Notes\n';
    response += '- This endpoint is V1 EXCLUSIVE (not available in V2)\n';
    response += '- Returns cases from user\'s default work pool only\n';
    response += '- Maximum 500 cases (controlled by pyMaxRecords DSS)\n';
    response += '- No pagination or filtering options\n';
    response += '- Cases ordered from oldest to newest\n';
    response += '- Requires pxGetCases privilege\n\n';
  
    return response;
  }

• src/api/v1/client-v1.js:247-285 (helper)

  Low-level HTTP implementation of getAllCases for V1 API: GET /prweb/api/v1/cases, transforms flat V1 response to standardized structure with metadata (max 500 cases).

  async getAllCases() {
    const url = `${this.getApiBaseUrl()}/cases`;
  
    const response = await this.makeRequest(url, {
      method: 'GET',
      headers: {
        'x-origin-channel': 'Web'
      }
    });
  
    if (!response.success) {
      return response;
    }
  
    // Transform response for consistency
    return {
      success: true,
      data: {
        cases: response.data.cases.map(c => ({
          ID: c.ID,
          parentCaseID: c.parentCaseID,
          caseTypeID: c.caseTypeID,
          name: c.name,
          stage: c.stage,
          status: c.status,
          urgency: parseInt(c.urgency) || 0,
          createTime: c.createTime,
          createdBy: c.createdBy,
          lastUpdateTime: c.lastUpdateTime,
          lastUpdatedBy: c.lastUpdatedBy
        }))
      },
      metadata: {
        count: response.data.cases.length,
        maxRecords: 500, // From pyMaxRecords DSS
        apiVersion: 'v1'
      }
    };
  }

• src/tools/cases/get-cases.js:24-26 (registration)

  Static method returning tool category 'cases', used by tool loader for automatic discovery and categorization in src/registry/tool-loader.js.

  static getCategory() {
    return 'cases';
  }