apifable

Instructions

Implementation Reference

• src/tools/get-endpoint.ts:13-120 (handler)

  Main handler function that executes the get_endpoint tool logic. Validates input parameters (either method+path or operationId), looks up the endpoint in the OpenAPI spec, resolves $refs in parameters/requestBody/responses, and returns the full endpoint details including method, path, operationId, summary, description, tags, parameters, requestBody, responses, and security requirements.

  export function getEndpoint(spec: ParsedSpec, input: GetEndpointInput) {
    const hasMethod = input.method !== undefined
    const hasPath = input.path !== undefined
    const hasOperationId = input.operationId !== undefined
  
    const modeCount = (hasMethod || hasPath ? 1 : 0) + (hasOperationId ? 1 : 0)
  
    if (modeCount === 0) {
      return {
        isError: true,
        message: 'Provide either "method" + "path" or "operationId".',
      }
    }
  
    if (modeCount > 1) {
      return {
        isError: true,
        message: 'Provide either "method" + "path" or "operationId", not both.',
      }
    }
  
    if (hasMethod !== hasPath) {
      return {
        isError: true,
        message: 'Both "method" and "path" are required for endpoint mode.',
      }
    }
  
    let normalizedMethod: HttpMethod
    let path: string
    let operation: OperationObject
  
    if (hasOperationId) {
      if (input.operationId!.trim() === '') {
        return {
          isError: true,
          message: 'operationId must not be an empty string.',
        }
      }
  
      const found = findOperationByOperationId(spec, input.operationId!)
      if (!found) {
        const suggestions = findSimilarNames(
          input.operationId!,
          spec.endpointIndex.map(entry => entry.operationId).filter(Boolean),
        )
  
        return {
          isError: true,
          message: buildNotFoundMessage(`Operation '${input.operationId}' not found in spec.`, suggestions),
        }
      }
  
      normalizedMethod = found.method
      path = found.path
      operation = found.operation
    } else {
      const method = input.method!.toLowerCase()
      if (!isValidHttpMethod(method)) {
        return {
          isError: true,
          message: `Invalid HTTP method '${input.method}'. Use one of: ${HTTP_METHODS.join(', ')}.`,
        }
      }
  
      normalizedMethod = method
      path = input.path!
  
      const pathItem = spec.rawSpec.paths?.[path]
      if (!pathItem) {
        const suggestions = findSimilarNames(path, Object.keys(spec.rawSpec.paths ?? {}))
  
        return {
          isError: true,
          message: buildNotFoundMessage(`Path '${path}' not found in spec.`, suggestions),
        }
      }
  
      const op = pathItem[normalizedMethod]
      if (!op) {
        return {
          isError: true,
          message: `Method '${input.method!.toUpperCase()}' not found for path '${path}'.`,
        }
      }
      operation = op
    }
  
    const result: Record<string, unknown> = {
      method: normalizedMethod,
      path,
      operationId: operation.operationId ?? '',
      summary: operation.summary ?? '',
      description: operation.description ?? '',
      tags: operation.tags ?? [],
      parameters: resolveRefs(operation.parameters, spec.rawSpec),
      requestBody: resolveRefs(operation.requestBody, spec.rawSpec),
      responses: resolveRefs(operation.responses, spec.rawSpec),
    }
  
    if (operation.security !== undefined) {
      result.security = operation.security
    } else if (spec.rawSpec.security !== undefined) {
      result.security = spec.rawSpec.security
    }
  
    return result
  }

• src/tools/get-endpoint.ts:7-11 (schema)

  TypeScript interface defining the input schema for the get_endpoint tool. Accepts optional 'method', 'path', and 'operationId' parameters - either method+path OR operationId must be provided.

  interface GetEndpointInput {
    method?: string
    path?: string
    operationId?: string
  }

• src/index.ts:133-151 (registration)

  Registration of the get_endpoint tool with the MCP server. Defines the tool name, description, Zod inputSchema for validation, and the handler function that calls getEndpoint() and formats the response.

  server.registerTool(
    'get_endpoint',
    {
      description: 'Get full details of a specific endpoint including parameters, request body, responses, and security requirements. Supported internal component $refs are resolved inline. Provide either "method" + "path" or "operationId". Use get_types to get TypeScript type declarations for the endpoint.',
      inputSchema: {
        method: z.string().optional().describe('HTTP method (e.g. get, post, put, delete)'),
        path: z.string().optional().describe('Endpoint path (e.g. /users/{id})'),
        operationId: z.string().optional().describe('Operation ID to look up (e.g. listUsers)'),
      },
    },
    ({ method, path, operationId }) => {
      const result = getEndpoint(spec, { method, path, operationId })
      const isError = 'isError' in result && result.isError === true
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
        isError,
      }
    },
  )

• src/spec/ref-resolver.ts:3-5 (helper)

  Helper function that resolves internal component $ref references in OpenAPI specs. Used by get_endpoint to resolve $refs in parameters, requestBody, and responses, making the endpoint details self-contained.

  export function resolveRefs(value: unknown, rawSpec: OpenAPIObject, visited: Set<string> = new Set()): unknown {
    return resolveRefsInternal(value, rawSpec, visited, false)
  }

• src/tools/find-operation.ts:10-28 (helper)

  Helper function that searches the OpenAPI spec to find an operation by its operationId. Iterates through all paths and HTTP methods to locate the matching operation, returning the method, path, and operation object.

  export function findOperationByOperationId(
    spec: ParsedSpec,
    operationId: string,
  ): FoundOperation | undefined {
    const paths = spec.rawSpec.paths
    if (!paths) return undefined
  
    for (const [path, pathItem] of Object.entries(paths)) {
      if (!pathItem) continue
      for (const method of HTTP_METHODS) {
        const operation = pathItem[method]
        if (operation?.operationId && operation.operationId === operationId) {
          return { method, path, operation }
        }
      }
    }
  
    return undefined
  }