Swagger/OpenAPI MCP Server

Implementation Reference

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

  The handler function that executes the get_endpoint_details tool: validates inputs, retrieves the API spec, finds the operation, formats details, and returns JSON or natural 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:237-241 (schema)

  Zod input schema defining parameters: apiId, method, path, and optional natural flag.
  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:234-305 (registration)

  Registration of the get_endpoint_details tool on the MCP server using this.server.tool(name, schema, handler).
  this.server.tool( "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 method to format endpoint details 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 method to generate a human-readable natural language summary of the endpoint details when 'natural' flag is 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; }