Swagger MCP

Instructions

Implementation Reference

• src/tools/listEndpoints.ts:26-48 (handler)

  MCP tool handler for 'listEndpoints' that invokes the service function and returns formatted JSON response.

  export async function handleListEndpoints(input: any) {
    logger.info('Calling swaggerService.listEndpoints()');
    logger.info(`Input parameters: ${JSON.stringify(input)}`);
  
    try {
      const endpoints = await swaggerService.listEndpoints(input);
      logger.info(`Endpoints response: ${JSON.stringify(endpoints).substring(0, 200)}...`);
  
      return {
        content: [{
          type: "text",
          text: JSON.stringify(endpoints, null, 2)
        }]
      };
    } catch (error: any) {
      logger.error(`Error in listEndpoints handler: ${error.message}`);
      return {
        content: [{
          type: "text",
          text: `Error retrieving endpoints: ${error.message}`
        }]
      };
    }

• src/tools/listEndpoints.ts:10-23 (schema)

  Tool schema definition for 'listEndpoints', including name, description, and input schema.

  export const listEndpoints = {
    name: "listEndpoints",
    description: "Lists all endpoints from the Swagger definition including their HTTP methods and descriptions. Priority: CLI --swagger-url > swaggerFilePath parameter.",
    inputSchema: {
      type: "object",
      properties: {
        swaggerFilePath: {
          type: "string",
          description: "Optional path to the Swagger file. Used only if --swagger-url is not provided. You can find this path in the .swagger-mcp file in the solution root with the format SWAGGER_FILEPATH=path/to/file.json."
        }
      },
      required: []
    }
  };

• src/services/listEndpoints.ts:25-63 (helper)

  Core helper function that loads Swagger definition and extracts list of endpoints with details.

  async function listEndpoints(params?: { swaggerFilePath?: string }): Promise<Endpoint[]> {
    try {
      // Load Swagger definition (checks CLI arg, then swaggerFilePath, then env var)
      const swaggerJson = await loadSwaggerDefinition(params?.swaggerFilePath);
  
      // Check if it's OpenAPI or Swagger
      const isOpenApi = !!swaggerJson.openapi;
      const paths = swaggerJson.paths || {};
  
      // Extract endpoints
      const endpoints: Endpoint[] = [];
  
      for (const path in paths) {
        const pathItem = paths[path];
  
        for (const method in pathItem) {
          if (['get', 'post', 'put', 'delete', 'patch', 'options', 'head'].includes(method)) {
            const operation = pathItem[method];
  
            endpoints.push({
              path,
              method: method.toUpperCase(),
              summary: operation.summary,
              description: operation.description,
              operationId: operation.operationId,
              tags: operation.tags
            });
          }
        }
      }
  
      return endpoints;
    } catch (error: any) {
      logger.error(`Error listing endpoints: ${error.message}`);
      throw error;
    }
  }
  
  export default listEndpoints; 

• src/services/listEndpoints.ts:10-17 (schema)

  Type definition for Endpoint objects returned by the tool.

  export interface Endpoint {
    path: string;
    method: string;
    summary?: string;
    description?: string;
    operationId?: string;
    tags?: string[];
  }

• src/tools/index.ts:6-29 (registration)

  Registration of the listEndpoints tool in the toolDefinitions array and export of its handler.

  import { getSwaggerDefinition } from './getSwaggerDefinition.js';
  import { listEndpoints } from './listEndpoints.js';
  import { listEndpointModels } from './listEndpointModels.js';
  import { generateModelCode } from './generateModelCode.js';
  import { generateEndpointToolCode } from './generateEndpointToolCode.js';
  import { version } from './version.js';
  
  // Tool definitions array
  export const toolDefinitions = [
    getSwaggerDefinition,
    listEndpoints,
    listEndpointModels,
    generateModelCode,
    generateEndpointToolCode,
    version
  ];
  
  // Export all tool handlers
  export { handleGetSwaggerDefinition } from './getSwaggerDefinition.js';
  export { handleListEndpoints } from './listEndpoints.js';
  export { handleListEndpointModels } from './listEndpointModels.js';
  export { handleGenerateModelCode } from './generateModelCode.js';
  export { handleGenerateEndpointToolCode } from './generateEndpointToolCode.js';
  export { handleVersion } from './version.js';