Swagger/OpenAPI MCP Server

Implementation Reference

• src/index.ts:199-230 (handler)

  The handler function that loads and parses the OpenAPI/Swagger specification from the provided source URL or path, caches it using SwaggerParser, calculates paths and endpoints count, and returns a success or error message.

  async ({ apiId, source }) => {
    try {
      console.error(`Loading API from: ${source}`);
      
      const parser = new SwaggerParser();
      const spec = await parser.dereference(source) as OpenAPIV3.Document;
      
      this.apis.set(apiId, { spec, parser });
      
      const pathCount = Object.keys(spec.paths || {}).length;
      const endpointCount = Object.values(spec.paths || {}).reduce((count, pathItem) => {
        if (!pathItem) return count;
        return count + ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace']
          .filter(method => (pathItem as any)[method]).length;
      }, 0);
  
      return {
        content: [{
          type: "text",
          text: `Successfully loaded API '${spec.info?.title || apiId}' (v${spec.info?.version || 'unknown'}) with ${pathCount} paths and ${endpointCount} endpoints.`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Failed to load API: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  }

• src/index.ts:195-198 (schema)

  Zod input schema defining the required parameters: apiId (string) and source (string).

  {
    apiId: z.string().describe("Unique identifier for this API"),
    source: z.string().describe("URL or file path to the OpenAPI/Swagger specification")
  },

• src/index.ts:193-231 (registration)

  Registration of the load_api tool on the MCP server, specifying the name, input schema, and handler function.

  this.server.tool(
    "load_api",
    {
      apiId: z.string().describe("Unique identifier for this API"),
      source: z.string().describe("URL or file path to the OpenAPI/Swagger specification")
    },
    async ({ apiId, source }) => {
      try {
        console.error(`Loading API from: ${source}`);
        
        const parser = new SwaggerParser();
        const spec = await parser.dereference(source) as OpenAPIV3.Document;
        
        this.apis.set(apiId, { spec, parser });
        
        const pathCount = Object.keys(spec.paths || {}).length;
        const endpointCount = Object.values(spec.paths || {}).reduce((count, pathItem) => {
          if (!pathItem) return count;
          return count + ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace']
            .filter(method => (pathItem as any)[method]).length;
        }, 0);
  
        return {
          content: [{
            type: "text",
            text: `Successfully loaded API '${spec.info?.title || apiId}' (v${spec.info?.version || 'unknown'}) with ${pathCount} paths and ${endpointCount} endpoints.`
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Failed to load API: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    }
  );