get_endpoint_details

Retrieve detailed information about a specific API endpoint from a loaded OpenAPI/Swagger specification, including parameters, responses, and a human-readable summary when requested.

Input Schema

TableJSON Schema

Name	Required	Description
`apiId`	Yes	ID of the loaded API
`method`	Yes	HTTP method (GET, POST, etc.)
`path`	Yes	API endpoint path
`natural`	No	If true, returns a human-readable summary

Implementation Reference

src/index.ts:242-304 (handler)

The handler function for the 'get_endpoint_details' tool. It retrieves the API spec by apiId, looks up the operation for the given method and path, formats the details using formatEndpointDetails, and returns JSON or natural language summary if requested.

async ({ apiId, method, path, natural = false }) => {
  try {
    const api = this.apis.get(apiId);
    if (!api) {
      return {
        content: [{
          type: "text",
          text: `API with ID '${apiId}' not found. Use load_api tool first.`
        }],
        isError: true
      };
    }

    const pathItem = api.spec.paths?.[path];
    if (!pathItem) {
      return {
        content: [{
          type: "text",
          text: `Path '${path}' not found in API`
        }],
        isError: true
      };
    }

    const operation = (pathItem as any)[method.toLowerCase()] as OpenAPIV3.OperationObject;
    if (!operation) {
      return {
        content: [{
          type: "text",
          text: `Method '${method}' not found for path '${path}'`
        }],
        isError: true
      };
    }

    const endpointDetails = this.formatEndpointDetails(operation, path, method.toUpperCase());

    if (natural) {
      const summary = this.generateNaturalSummary(endpointDetails, path, method);
      return {
        content: [{
          type: "text",
          text: summary
        }]
      };
    }

    return {
      content: [{
        type: "text",
        text: JSON.stringify(endpointDetails, null, 2)
      }]
    };
  } catch (error) {
    return {
      content: [{
        type: "text",
        text: `Error getting endpoint details: ${error instanceof Error ? error.message : String(error)}`
      }],
      isError: true
    };
  }
}

src/index.ts:236-240 (schema)

Zod input schema for the get_endpoint_details tool defining parameters: apiId (string), method (string), path (string), natural (optional boolean).

{
  apiId: z.string().describe("ID of the loaded API"),
  method: z.string().describe("HTTP method (GET, POST, etc.)"),
  path: z.string().describe("API endpoint path"),
  natural: z.boolean().optional().describe("If true, returns a human-readable summary")

src/index.ts:235-305 (registration)

Registration of the 'get_endpoint_details' tool on the MCP server using this.server.tool, including name, schema, and handler.

  "get_endpoint_details",
  {
    apiId: z.string().describe("ID of the loaded API"),
    method: z.string().describe("HTTP method (GET, POST, etc.)"),
    path: z.string().describe("API endpoint path"),
    natural: z.boolean().optional().describe("If true, returns a human-readable summary")
  },
  async ({ apiId, method, path, natural = false }) => {
    try {
      const api = this.apis.get(apiId);
      if (!api) {
        return {
          content: [{
            type: "text",
            text: `API with ID '${apiId}' not found. Use load_api tool first.`
          }],
          isError: true
        };
      }

      const pathItem = api.spec.paths?.[path];
      if (!pathItem) {
        return {
          content: [{
            type: "text",
            text: `Path '${path}' not found in API`
          }],
          isError: true
        };
      }

      const operation = (pathItem as any)[method.toLowerCase()] as OpenAPIV3.OperationObject;
      if (!operation) {
        return {
          content: [{
            type: "text",
            text: `Method '${method}' not found for path '${path}'`
          }],
          isError: true
        };
      }

      const endpointDetails = this.formatEndpointDetails(operation, path, method.toUpperCase());

      if (natural) {
        const summary = this.generateNaturalSummary(endpointDetails, path, method);
        return {
          content: [{
            type: "text",
            text: summary
          }]
        };
      }

      return {
        content: [{
          type: "text",
          text: JSON.stringify(endpointDetails, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error getting endpoint details: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  }
);

src/index.ts:397-446 (helper)

Helper function formatEndpointDetails that structures the endpoint information including parameters, requestBody, and responses from the OpenAPI operation.

private formatEndpointDetails(operation: OpenAPIV3.OperationObject, path: string, method: string) {
  const details: any = {
    method,
    path,
    summary: operation.summary,
    description: operation.description,
    operationId: operation.operationId,
    tags: operation.tags,
    parameters: [],
    requestBody: null,
    responses: {}
  };

  // Process parameters
  if (operation.parameters) {
    details.parameters = operation.parameters.map((param: any) => ({
      name: param.name,
      in: param.in,
      required: param.required || false,
      description: param.description,
      schema: param.schema,
      example: param.example
    }));
  }

  // Process request body
  if (operation.requestBody) {
    const requestBody = operation.requestBody as OpenAPIV3.RequestBodyObject;
    details.requestBody = {
      description: requestBody.description,
      required: requestBody.required || false,
      content: requestBody.content
    };
  }

  // Process responses
  if (operation.responses) {
    Object.entries(operation.responses).forEach(([code, response]) => {
      if (response && typeof response === 'object' && 'description' in response) {
        details.responses[code] = {
          description: response.description,
          content: (response as OpenAPIV3.ResponseObject).content,
          headers: (response as OpenAPIV3.ResponseObject).headers
        };
      }
    });
  }

  return details;
}

src/index.ts:448-493 (helper)

Helper function generateNaturalSummary that creates a human-readable description of the endpoint, used when natural=true.

private generateNaturalSummary(endpointDetails: any, path: string, method: string): string {
  const { summary, description, parameters, requestBody, responses } = endpointDetails;
  
  let naturalSummary = `The ${method} ${path} endpoint`;
  
  if (summary) {
    naturalSummary += ` ${summary.toLowerCase()}`;
  } else if (description) {
    naturalSummary += ` ${description.toLowerCase()}`;
  }
  
  // Add parameter information
  if (parameters && parameters.length > 0) {
    const requiredParams = parameters.filter((p: any) => p.required);
    const optionalParams = parameters.filter((p: any) => !p.required);
    
    if (requiredParams.length > 0) {
      naturalSummary += `. It requires ${requiredParams.map((p: any) => `${p.name} (${p.in})`).join(', ')}`;
    }
    
    if (optionalParams.length > 0) {
      naturalSummary += `. Optional parameters include ${optionalParams.map((p: any) => `${p.name} (${p.in})`).join(', ')}`;
    }
  }
  
  // Add request body information
  if (requestBody) {
    naturalSummary += `. It accepts a request body`;
    if (requestBody.required) {
      naturalSummary += ' (required)';
    }
  }
  
  // Add response information
  const responseKeys = Object.keys(responses || {});
  if (responseKeys.length > 0) {
    const successCodes = responseKeys.filter(code => code.startsWith('2'));
    if (successCodes.length > 0) {
      naturalSummary += `. Success responses include ${successCodes.join(', ')}`;
    }
  }
  
  naturalSummary += '.';
  
  return naturalSummary;
}

Swagger/OpenAPI MCP Server