HaloPSA MCP Server

Instructions

Implementation Reference

• src/halopsa-client.ts:464-534 (handler)

  Core handler implementation that loads the OpenAPI swagger.json, extracts components.schemas, applies filtering by schemaPattern, pagination with limit/skip, and returns structured schema data with metadata.

  async getApiSchemas(
    schemaPattern?: string, 
    limit: number = 50, 
    skip: number = 0,
    listNames: boolean = false
  ): Promise<any> {
    try {
      // Import the swagger.json directly
      const swaggerModule = await import('./swagger.json');
      const schema = swaggerModule.default || swaggerModule;
      
      const schemas: any = {};
      const matchingSchemaNames: string[] = [];
      let schemaCount = 0;
      let skippedCount = 0;
      
      if ((schema as any).components?.schemas) {
        const allSchemas = (schema as any).components.schemas;
        
        Object.entries(allSchemas).forEach(([name, schemaObj]: [string, any]) => {
          // Filter by pattern if provided
          if (schemaPattern && !name.toLowerCase().includes(schemaPattern.toLowerCase())) {
            return;
          }
          
          matchingSchemaNames.push(name);
          
          // Skip logic
          if (skippedCount < skip) {
            skippedCount++;
            return;
          }
          
          if (schemaCount >= limit) {
            return;
          }
          
          schemas[name] = schemaObj;
          schemaCount++;
        });
      }
      
      // Get total count of all schemas
      const totalSchemaCount = (schema as any).components?.schemas ? 
        Object.keys((schema as any).components.schemas).length : 0;
      
      const result: any = {
        schemas,
        returnedCount: schemaCount,
        matchingCount: matchingSchemaNames.length,
        totalSchemasInAPI: totalSchemaCount,
        skipped: skip,
        limited: schemaCount >= limit,
        hasMore: skip + schemaCount < matchingSchemaNames.length,
        message: schemaPattern ? 
          `Showing ${schemaCount} of ${matchingSchemaNames.length} schemas matching "${schemaPattern}" (skipped ${skip})` : 
          `Showing ${schemaCount} schemas starting from position ${skip}. Total: ${totalSchemaCount}.`
      };
      
      // Only include schema names if requested or if there are few enough
      if (listNames || matchingSchemaNames.length <= 20) {
        result.schemaNames = matchingSchemaNames.sort();
      } else {
        result.hint = `${matchingSchemaNames.length} schemas match. Set listNames=true to see all names.`;
      }
      
      return result;
    } catch (error) {
      throw new Error(`Failed to get API schemas: ${error}`);
    }
  }

• src/index.ts:219-246 (registration)

  MCP tool registration defining the name, description, and input schema validation for halopsa_get_api_schemas.

  {
    name: 'halopsa_get_api_schemas',
    description: 'Get API schemas/models from the swagger definition. Shows the structure of request/response objects used by the API endpoints. Supports pagination.',
    inputSchema: {
      type: 'object',
      properties: {
        schemaPattern: {
          type: 'string',
          description: 'Optional pattern to filter schemas by name (e.g., "Ticket", "Action", "Client")'
        },
        limit: {
          type: 'number',
          description: 'Maximum number of schemas to return (default: 50)',
          default: 50
        },
        skip: {
          type: 'number',
          description: 'Number of matching schemas to skip for pagination (default: 0)',
          default: 0
        },
        listNames: {
          type: 'boolean',
          description: 'Include list of all matching schema names (default: false, auto-included if ≤20 matches)',
          default: false
        }
      }
    }
  },

• src/index.ts:563-572 (handler)

  MCP server request handler switch case that parses tool arguments and delegates to HaloPSAClient.getApiSchemas method.

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

• src/index.ts:222-244 (schema)

  Input schema definition for validating tool parameters: schemaPattern, limit, skip, listNames.

  inputSchema: {
    type: 'object',
    properties: {
      schemaPattern: {
        type: 'string',
        description: 'Optional pattern to filter schemas by name (e.g., "Ticket", "Action", "Client")'
      },
      limit: {
        type: 'number',
        description: 'Maximum number of schemas to return (default: 50)',
        default: 50
      },
      skip: {
        type: 'number',
        description: 'Number of matching schemas to skip for pagination (default: 0)',
        default: 0
      },
      listNames: {
        type: 'boolean',
        description: 'Include list of all matching schema names (default: false, auto-included if ≤20 matches)',
        default: false
      }
    }