halopsa_get_api_endpoint_details
Retrieve detailed API endpoint specifications including parameters, request/response schemas, and examples to understand how to interact with HaloPSA's API after identifying relevant endpoints.
Instructions
Get complete details for specific API endpoints including parameters, request/response schemas, and examples. Use after finding endpoints with halopsa_list_api_endpoints.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pathPattern | Yes | Path pattern to match endpoints (e.g., "ticket", "action", "client", "agent") | |
| summaryOnly | No | Return only basic endpoint information (path, methods, summary) without detailed schemas - ideal for quick API exploration | |
| includeSchemas | No | Include detailed request/response schemas (default: true, set to false to significantly reduce response size) | |
| maxEndpoints | No | Maximum number of endpoints to return (default: 10, max: 50) - helps manage response size | |
| includeExamples | No | Include request/response examples (default: false to keep responses smaller) |
Input Schema (JSON Schema)
{
"properties": {
"includeExamples": {
"default": false,
"description": "Include request/response examples (default: false to keep responses smaller)",
"type": "boolean"
},
"includeSchemas": {
"default": true,
"description": "Include detailed request/response schemas (default: true, set to false to significantly reduce response size)",
"type": "boolean"
},
"maxEndpoints": {
"default": 10,
"description": "Maximum number of endpoints to return (default: 10, max: 50) - helps manage response size",
"type": "number"
},
"pathPattern": {
"description": "Path pattern to match endpoints (e.g., \"ticket\", \"action\", \"client\", \"agent\")",
"type": "string"
},
"summaryOnly": {
"default": false,
"description": "Return only basic endpoint information (path, methods, summary) without detailed schemas - ideal for quick API exploration",
"type": "boolean"
}
},
"required": [
"pathPattern"
],
"type": "object"
}
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) }] }; }