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