HaloPSA MCP Server

Instructions

Implementation Reference

• src/halopsa-client.ts:346-406 (handler)

  The primary handler function that loads the swagger.json schema, filters endpoints by optional category, extracts path/method/summary/category, sorts, paginates, and returns structured results with metadata.

  async listApiEndpoints(category?: string, limit: number = 100, skip: number = 0): Promise<any> {
    try {
      // Import the swagger.json directly
      const swaggerModule = await import('./swagger.json');
      const schema = swaggerModule.default || swaggerModule;
      
      const allMatchingEndpoints: any[] = [];
      
      if ((schema as any).paths) {
        Object.entries((schema as any).paths).forEach(([path, pathObj]: [string, any]) => {
          // Filter by category if provided
          if (category) {
            const pathCategory = this.categorizeApiPath(path);
            if (pathCategory.toLowerCase() !== category.toLowerCase()) {
              return;
            }
          }
          
          if (pathObj && typeof pathObj === 'object') {
            const methods: string[] = [];
            let primarySummary = '';
            
            Object.entries(pathObj).forEach(([method, methodObj]: [string, any]) => {
              methods.push(method.toUpperCase());
              if (!primarySummary && methodObj?.summary) {
                primarySummary = methodObj.summary;
              }
            });
            
            allMatchingEndpoints.push({
              path,
              methods,
              summary: primarySummary,
              category: this.categorizeApiPath(path)
            });
          }
        });
      }
      
      // Sort endpoints by path
      allMatchingEndpoints.sort((a, b) => a.path.localeCompare(b.path));
      
      // Apply pagination
      const paginatedEndpoints = allMatchingEndpoints.slice(skip, skip + limit);
      
      return {
        totalEndpoints: allMatchingEndpoints.length,
        endpoints: paginatedEndpoints,
        returnedCount: paginatedEndpoints.length,
        skipped: skip,
        limited: paginatedEndpoints.length >= limit,
        hasMore: skip + paginatedEndpoints.length < allMatchingEndpoints.length,
        categories: [...new Set(allMatchingEndpoints.map(e => e.category))].sort(),
        message: category ? 
          `Showing ${paginatedEndpoints.length} of ${allMatchingEndpoints.length} endpoints in category "${category}"` :
          `Showing ${paginatedEndpoints.length} endpoints starting from position ${skip}. Total: ${allMatchingEndpoints.length}.`
      };
    } catch (error) {
      throw new Error(`Failed to list API endpoints: ${error}`);
    }
  }

• src/index.ts:138-160 (schema)

  Tool schema definition: name, description, and inputSchema specifying optional category filter, limit (default 100), and skip (default 0) parameters.

  {
    name: 'halopsa_list_api_endpoints',
    description: 'List all API endpoints with their paths, methods, and summaries. Use this first to discover available endpoints, then use halopsa_get_api_endpoint_details for full details. Supports pagination.',
    inputSchema: {
      type: 'object',
      properties: {
        category: {
          type: 'string',
          description: 'Optional category filter (e.g., "Tickets", "Actions", "Clients", "Sites")'
        },
        limit: {
          type: 'number',
          description: 'Maximum number of endpoints to return (default: 100)',
          default: 100
        },
        skip: {
          type: 'number',
          description: 'Number of endpoints to skip for pagination (default: 0)',
          default: 0
        }
      }
    }
  },

• src/index.ts:516-525 (registration)

  MCP server tool registration: switch case handler that extracts parameters from request and delegates execution to HaloPSAClient.listApiEndpoints method.

  case 'halopsa_list_api_endpoints': {
    const { category, limit, skip } = args as any;
    result = await haloPSAClient.listApiEndpoints(category, limit, skip);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }

• src/halopsa-client.ts:539-563 (helper)

  Supporting utility that categorizes API endpoint paths into logical groups (e.g., 'Tickets', 'Actions') for filtering and display purposes.

  private categorizeApiPath(path: string): string {
    const lowerPath = path.toLowerCase();
    
    if (lowerPath.includes('/actions')) return 'Actions';
    if (lowerPath.includes('/ticket')) return 'Tickets';
    if (lowerPath.includes('/agent')) return 'Agents';
    if (lowerPath.includes('/client')) return 'Clients';
    if (lowerPath.includes('/site')) return 'Sites';
    if (lowerPath.includes('/user')) return 'Users';
    if (lowerPath.includes('/asset')) return 'Assets';
    if (lowerPath.includes('/invoice')) return 'Invoicing';
    if (lowerPath.includes('/report')) return 'Reports';
    if (lowerPath.includes('/address')) return 'Addresses';
    if (lowerPath.includes('/appointment')) return 'Appointments';
    if (lowerPath.includes('/project')) return 'Projects';
    if (lowerPath.includes('/contract')) return 'Contracts';
    if (lowerPath.includes('/supplier')) return 'Suppliers';
    if (lowerPath.includes('/product')) return 'Products';
    if (lowerPath.includes('/kb') || lowerPath.includes('/knowledge')) return 'Knowledge Base';
    if (lowerPath.includes('/integration')) return 'Integrations';
    if (lowerPath.includes('/webhook')) return 'Webhooks';
    if (lowerPath.includes('/api')) return 'API Management';
    
    return 'Other';
  }