Swagger/OpenAPI MCP Server

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; }