get_endpoint_details

Instructions

Implementation Reference

• src/index.ts:333-420 (handler)

  The getEndpointDetails private method implements the core logic for the get_endpoint_details tool. It finds an endpoint by path/method from pre-loaded endpoints, then generates a detailed Markdown documentation string with parameters, request body schema, response schema, and implementation notes.

    private getEndpointDetails(args: ToolCallArguments): any {
      const path = args.path as string;
      const method = (args.method as string).toUpperCase();
  
      const endpoint = this.endpoints.find(
        e => e.path === path && e.method === method
      );
  
      if (!endpoint) {
        return {
          content: [
            {
              type: 'text',
              text: `Endpoint not found: ${method} ${path}\n\nTip: Use search_endpoints or list_all_endpoints to find the correct path.`,
            },
          ],
          isError: true,
        };
      }
  
      // Separate required and optional parameters
      const pathParams = endpoint.parameters.filter(p => p.in === 'path');
      const queryParams = endpoint.parameters.filter(p => p.in === 'query');
      const requiredParams = endpoint.parameters.filter(p => p.required);
      const optionalParams = endpoint.parameters.filter(p => !p.required);
  
      const markdown = `# ${endpoint.method} ${endpoint.path}
  
  ## Overview
  - **Operation ID**: ${endpoint.operationId}
  - **Summary**: ${endpoint.summary || 'N/A'}
  - **Resource Tags**: ${endpoint.tags?.join(', ') || 'N/A'}
  
  ## Description
  ${endpoint.description || 'No detailed description available.'}
  
  ## Parameters
  
  ${pathParams.length > 0 ? `### Path Parameters (Required)
  ${pathParams.map(p => `- **${p.name}** (${p.schema?.type || 'unknown'})
    - ${p.description || 'No description'}
    - ${p.schema?.pattern ? `Pattern: \`${p.schema.pattern}\`` : ''}
    - ${p.schema?.enum ? `Allowed values: ${p.schema.enum.join(', ')}` : ''}`).join('\n\n')}
  ` : '### Path Parameters\nNone\n'}
  
  ${queryParams.length > 0 ? `### Query Parameters
  ${queryParams.map(p => `- **${p.name}** (${p.schema?.type || 'unknown'})${p.required ? ' *REQUIRED*' : ' *optional*'}
    - ${p.description || 'No description'}
    - ${p.schema?.enum ? `Allowed values: ${p.schema.enum.join(', ')}` : ''}
    - ${p.schema?.minimum !== undefined ? `Min: ${p.schema.minimum}` : ''}
    - ${p.schema?.maximum !== undefined ? `Max: ${p.schema.maximum}` : ''}`).join('\n\n')}
  ` : '### Query Parameters\nNone\n'}
  
  ${endpoint.requestBodySchema ? `## Request Body
  Required for ${endpoint.method} requests.
  
  \`\`\`json
  ${JSON.stringify(endpoint.requestBodySchema, null, 2)}
  \`\`\`
  ` : '## Request Body\nNot applicable for this endpoint.\n'}
  
  ${endpoint.responseSchema ? `## Response Schema
  \`\`\`json
  ${JSON.stringify(endpoint.responseSchema, null, 2)}
  \`\`\`
  ` : '## Response\nResponse schema not documented in OpenAPI spec.\n'}
  
  ## Quick Reference
  - **Base URL**: https://api.fortnox.se
  - **Full URL**: https://api.fortnox.se${endpoint.path}
  - **Required Parameters**: ${requiredParams.length > 0 ? requiredParams.map(p => p.name).join(', ') : 'None'}
  - **Optional Parameters**: ${optionalParams.length > 0 ? optionalParams.map(p => p.name).join(', ') : 'None'}
  
  ## Notes for Implementation
  1. Authentication: Include 'Access-Token' header
  2. Rate Limit: 25 requests per 5 seconds
  3. Content-Type: application/json
  `;
  
      return {
        content: [
          {
            type: 'text',
            text: markdown,
          },
        ],
      };
    }

• src/index.ts:89-106 (schema)

  The tool definition with inputSchema for get_endpoint_details. It declares the tool name, description, and input schema requiring 'path' (string) and 'method' (enum of HTTP methods) as required parameters.

  {
    name: 'get_endpoint_details',
    description: 'Get complete documentation for a specific endpoint including: description, parameters (path/query), request body schema, response schema, required vs optional fields. Essential for understanding how to use an endpoint.',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'The API endpoint path exactly as shown in list_all_endpoints (e.g., /3/customers, /3/invoices/{DocumentNumber})',
        },
        method: {
          type: 'string',
          description: 'The HTTP method (must match exactly)',
          enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
        },
      },
      required: ['path', 'method'],
    },

• src/index.ts:175-176 (registration)

  The tool registration in the handleToolCall switch-case. When the tool name 'get_endpoint_details' is received, it dispatches to the getEndpointDetails method with the provided arguments.

  case 'get_endpoint_details':
    return this.getEndpointDetails(args);

• src/index.ts:89-90 (registration)

  The tool is registered as part of the tools array in generateTools(), which is sent to MCP via ListToolsRequestSchema handler.

  {
    name: 'get_endpoint_details',

• src/openapi-parser.ts:202-213 (helper)

  The getOpenAPIParser function that creates the OpenAPIParser singleton. The parser's getAllEndpoints() method is called in the constructor to load endpoints, which are later queried by getEndpointDetails.

  export function getOpenAPIParser(): OpenAPIParser {
    if (!parser) {
      // Get the directory where this module is located
      const __filename = fileURLToPath(import.meta.url);
      const __dirname = dirname(__filename);
      
      // Load the OpenAPI spec from the project root (one level up from dist/)
      const specPath = join(__dirname, '..', 'openapi.json');
      parser = new OpenAPIParser(specPath);
    }
    return parser;
  }