HaloPSA MCP Server

Instructions

Implementation Reference

• src/halopsa-client.ts:411-459 (handler)

  Exact implementation of the tool logic: searches HaloPSA OpenAPI swagger.json paths for endpoints matching the query in path, method summary, description, or tags. Returns paginated results with details.

  async searchApiEndpoints(query: string, limit: number = 50, skip: number = 0): Promise<any> {
    try {
      // Import the swagger.json directly
      const swaggerModule = await import('./swagger.json');
      const schema = swaggerModule.default || swaggerModule;
      const matchingEndpoints: any[] = [];
      
      if ((schema as any).paths) {
        Object.entries((schema as any).paths).forEach(([path, pathObj]: [string, any]) => {
          if (pathObj && typeof pathObj === 'object') {
            Object.entries(pathObj).forEach(([method, methodObj]: [string, any]) => {
              // Search in path, summary, description, and tags
              const searchableText = [
                path,
                methodObj?.summary || '',
                methodObj?.description || '',
                ...(methodObj?.tags || [])
              ].join(' ').toLowerCase();
              
              if (searchableText.includes(query.toLowerCase())) {
                matchingEndpoints.push({
                  path,
                  method: method.toUpperCase(),
                  summary: methodObj?.summary,
                  description: methodObj?.description,
                  tags: methodObj?.tags
                });
              }
            });
          }
        });
      }
      
      // Apply pagination
      const paginatedResults = matchingEndpoints.slice(skip, skip + limit);
      
      return {
        query,
        results: paginatedResults,
        returnedCount: paginatedResults.length,
        totalResults: matchingEndpoints.length,
        skipped: skip,
        hasMore: skip + paginatedResults.length < matchingEndpoints.length,
        message: `Found ${matchingEndpoints.length} endpoints matching "${query}". Showing ${paginatedResults.length} starting from position ${skip}.`
      };
    } catch (error) {
      throw new Error(`Failed to search API endpoints: ${error}`);
    }
  }

• src/index.ts:548-561 (handler)

  MCP CallToolRequest handler switch case for halopsa_search_api_endpoints: validates input, calls client method, formats response as MCP content.

  case 'halopsa_search_api_endpoints': {
    const { query, limit, skip } = args as any;
    if (!query) {
      throw new Error('Search query is required');
    }
    
    result = await haloPSAClient.searchApiEndpoints(query, limit, skip);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }

• src/index.ts:195-218 (schema)

  Tool registration and input schema definition: defines name, description, and JSON schema for parameters (query required, limit/skip optional).

  {
    name: 'halopsa_search_api_endpoints',
    description: 'Search for API endpoints by keywords. Returns matching endpoints with basic info. Use halopsa_get_api_endpoint_details for full details of specific endpoints. Supports pagination.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query to find endpoints (searches in paths, summaries, descriptions, and tags)'
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return (default: 50)',
          default: 50
        },
        skip: {
          type: 'number',
          description: 'Number of results to skip for pagination (default: 0)',
          default: 0
        }
      },
      required: ['query']
    }
  },

• src/index.ts:279-281 (registration)

  Registration of all tools list handler, which exposes the halopsa_search_api_endpoints tool via MCP ListToolsRequest.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools };
  });