HaloPSA MCP Server

Instructions

Implementation Reference

• src/halopsa-client.ts:247-341 (handler)

  Main handler function implementing the tool logic: loads swagger.json, filters endpoints by pathPattern, applies options for detail level (summary/schemas/examples), limits results, and structures response.

  async getApiEndpointDetails(
    pathPattern: string,
    summaryOnly: boolean = false,
    includeSchemas: boolean = true,
    maxEndpoints: number = 10,
    includeExamples: boolean = false
  ): Promise<any> {
    try {
      // Import the swagger.json directly
      const swaggerModule = await import('./swagger.json');
      const schema = swaggerModule.default || swaggerModule;
  
      const matchingPaths: any = {};
      const pathEntries = Object.entries(schema.paths || {});
      let matchCount = 0;
      
      // Find matching paths and limit results
      for (const [path, pathObj] of pathEntries) {
        if (matchCount >= Math.min(maxEndpoints, 50)) break; // Cap at 50 max
        
        if (path.toLowerCase().includes(pathPattern.toLowerCase())) {
          if (summaryOnly) {
            // Return only basic info for summary mode
            const methods: string[] = [];
            let summary = '';
            
            if (pathObj && typeof pathObj === 'object') {
              Object.entries(pathObj).forEach(([method, methodObj]: [string, any]) => {
                methods.push(method.toUpperCase());
                if (!summary && methodObj?.summary) {
                  summary = methodObj.summary;
                }
              });
            }
            
            matchingPaths[path] = { methods, summary };
          } else {
            // Filter the path object based on options
            const filteredPathObj: any = {};
            
            if (pathObj && typeof pathObj === 'object') {
              Object.entries(pathObj).forEach(([method, methodObj]: [string, any]) => {
                const filteredMethodObj: any = {
                  summary: methodObj?.summary,
                  description: methodObj?.description,
                  operationId: methodObj?.operationId,
                  tags: methodObj?.tags
                };
                
                if (includeSchemas) {
                  filteredMethodObj.parameters = methodObj?.parameters;
                  filteredMethodObj.requestBody = methodObj?.requestBody;
                  filteredMethodObj.responses = methodObj?.responses;
                }
                
                if (includeExamples && methodObj?.examples) {
                  filteredMethodObj.examples = methodObj.examples;
                }
                
                filteredPathObj[method] = filteredMethodObj;
              });
            }
            
            matchingPaths[path] = filteredPathObj;
          }
          matchCount++;
        }
      }
  
      const result: any = {
        pathPattern,
        matchingPaths,
        matchCount,
        totalMatches: pathEntries.filter(([path]) => 
          path.toLowerCase().includes(pathPattern.toLowerCase())
        ).length,
        limited: matchCount >= Math.min(maxEndpoints, 50)
      };
  
      // Only include components if schemas are requested and not in summary mode
      if (includeSchemas && !summaryOnly && matchCount > 0) {
        // Include only referenced components to reduce size
        result.components = {
          schemas: schema.components?.schemas ? 
            Object.fromEntries(
              Object.entries(schema.components.schemas).slice(0, 20)
            ) : undefined
        };
      }
  
      return result;
    } catch (error) {
      throw new Error(`Failed to fetch HaloPSA API endpoint details: ${error}`);
    }
  }

• src/index.ts:161-194 (schema)

  Tool schema definition: name, description, and detailed inputSchema for parameters with descriptions, defaults, and requirements.

  {
    name: 'halopsa_get_api_endpoint_details',
    description: 'Get complete details for specific API endpoints including parameters, request/response schemas, and examples. Use after finding endpoints with halopsa_list_api_endpoints.',
    inputSchema: {
      type: 'object',
      properties: {
        pathPattern: {
          type: 'string',
          description: 'Path pattern to match endpoints (e.g., "ticket", "action", "client", "agent")'
        },
        summaryOnly: {
          type: 'boolean',
          description: 'Return only basic endpoint information (path, methods, summary) without detailed schemas - ideal for quick API exploration',
          default: false
        },
        includeSchemas: {
          type: 'boolean',
          description: 'Include detailed request/response schemas (default: true, set to false to significantly reduce response size)',
          default: true
        },
        maxEndpoints: {
          type: 'number',
          description: 'Maximum number of endpoints to return (default: 10, max: 50) - helps manage response size',
          default: 10
        },
        includeExamples: {
          type: 'boolean',
          description: 'Include request/response examples (default: false to keep responses smaller)',
          default: false
        }
      },
      required: ['pathPattern']
    }
  },

• src/index.ts:527-546 (registration)

  MCP tool dispatch/registration in switch statement: extracts arguments, validates pathPattern, calls client handler, formats response.

  case 'halopsa_get_api_endpoint_details': {
    const { pathPattern, summaryOnly, includeSchemas, maxEndpoints, includeExamples } = args as any;
    if (!pathPattern) {
      throw new Error('Path pattern is required');
    }
    
    result = await haloPSAClient.getApiEndpointDetails(
      pathPattern,
      summaryOnly,
      includeSchemas,
      maxEndpoints,
      includeExamples
    );
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }