Swagger/OpenAPI MCP Server

Implementation Reference

• src/index.ts:338-394 (handler)

  Handler function that implements the search_endpoints tool logic: retrieves the API spec, searches endpoints by matching pattern against path, summary, or description, and returns matching endpoints as JSON.

    async ({ apiId, pattern }) => {
      try {
        const api = this.apis.get(apiId);
        if (!api) {
          return {
            content: [{
              type: "text",
              text: `API with ID '${apiId}' not found`
            }],
            isError: true
          };
        }
  
        const matchingEndpoints: Array<{method: string, path: string, summary?: string, description?: string}> = [];
        const searchPattern = pattern.toLowerCase();
  
        Object.entries(api.spec.paths || {}).forEach(([path, pathItem]) => {
          if (!pathItem) return;
          
          ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].forEach(method => {
            const operation = (pathItem as any)[method] as OpenAPIV3.OperationObject;
            if (operation) {
              const matchesPath = path.toLowerCase().includes(searchPattern);
              const matchesSummary = operation.summary?.toLowerCase().includes(searchPattern);
              const matchesDescription = operation.description?.toLowerCase().includes(searchPattern);
              
              if (matchesPath || matchesSummary || matchesDescription) {
                matchingEndpoints.push({
                  method: method.toUpperCase(),
                  path,
                  summary: operation.summary,
                  description: operation.description
                });
              }
            }
          });
        });
  
        return {
          content: [{
            type: "text",
            text: matchingEndpoints.length > 0
              ? JSON.stringify(matchingEndpoints, null, 2)
              : `No endpoints found matching pattern: ${pattern}`
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error searching endpoints: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    }
  );

• src/index.ts:335-337 (schema)

  Input schema for the search_endpoints tool using Zod validation: requires apiId and pattern.

    apiId: z.string().describe("ID of the loaded API"),
    pattern: z.string().describe("Search pattern for endpoint paths or descriptions")
  },

• src/index.ts:333-395 (registration)

  Registration of the search_endpoints tool on the MCP server, associating name, input schema, and handler function.

      "search_endpoints",
      {
        apiId: z.string().describe("ID of the loaded API"),
        pattern: z.string().describe("Search pattern for endpoint paths or descriptions")
      },
      async ({ apiId, pattern }) => {
        try {
          const api = this.apis.get(apiId);
          if (!api) {
            return {
              content: [{
                type: "text",
                text: `API with ID '${apiId}' not found`
              }],
              isError: true
            };
          }
  
          const matchingEndpoints: Array<{method: string, path: string, summary?: string, description?: string}> = [];
          const searchPattern = pattern.toLowerCase();
  
          Object.entries(api.spec.paths || {}).forEach(([path, pathItem]) => {
            if (!pathItem) return;
            
            ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].forEach(method => {
              const operation = (pathItem as any)[method] as OpenAPIV3.OperationObject;
              if (operation) {
                const matchesPath = path.toLowerCase().includes(searchPattern);
                const matchesSummary = operation.summary?.toLowerCase().includes(searchPattern);
                const matchesDescription = operation.description?.toLowerCase().includes(searchPattern);
                
                if (matchesPath || matchesSummary || matchesDescription) {
                  matchingEndpoints.push({
                    method: method.toUpperCase(),
                    path,
                    summary: operation.summary,
                    description: operation.description
                  });
                }
              }
            });
          });
  
          return {
            content: [{
              type: "text",
              text: matchingEndpoints.length > 0
                ? JSON.stringify(matchingEndpoints, null, 2)
                : `No endpoints found matching pattern: ${pattern}`
            }]
          };
        } catch (error) {
          return {
            content: [{
              type: "text",
              text: `Error searching endpoints: ${error instanceof Error ? error.message : String(error)}`
            }],
            isError: true
          };
        }
      }
    );
  }