swagger-mcp

Parses OpenAPI 3.0 and Swagger 2.0 specifications from URLs or local files and automatically registers each API endpoint as an MCP tool. Uses schema introspection to extract operation metadata (parameters, request/response types, authentication requirements) and generates tool definitions compatible with the Model Context Protocol specification, enabling LLM clients to discover and invoke REST APIs without manual tool definition.

Constructs HTTP requests from MCP tool invocations by mapping tool parameters to OpenAPI operation definitions (path parameters, query strings, request bodies, headers). Executes requests against the target API using the HTTP method and endpoint specified in the schema, handling content negotiation (JSON, form-encoded, XML) and returning raw or parsed responses. Implements retry logic and timeout handling for resilient API calls.

Manages API authentication credentials (API keys, basic auth, bearer tokens) and injects them into HTTP request headers according to the OpenAPI security scheme definitions. Supports multiple authentication methods per API and selects the appropriate credentials based on the operation's security requirements. Stores credentials securely (environment variables or encrypted config) and applies them transparently to all tool invocations.

Validates MCP tool parameters against OpenAPI schema constraints (required fields, type validation, enum constraints, min/max values, pattern matching) before constructing HTTP requests. Coerces parameter types (string to number, boolean parsing) based on the schema definition and rejects invalid inputs with detailed error messages. Implements JSON Schema validation using a schema validator library to ensure type safety and catch errors early.

Parses HTTP responses from REST APIs and extracts structured data based on OpenAPI response schema definitions. Handles multiple content types (JSON, XML, plain text) and deserializes responses into typed objects matching the schema. Implements error handling for malformed responses and provides fallback parsing strategies. Optionally filters or transforms responses to extract only relevant fields defined in the schema.

Implements the MCP server protocol lifecycle (initialization, tool discovery, tool invocation) and exposes registered tools through the MCP interface. Handles MCP client requests for tool listing, tool metadata retrieval, and tool execution. Manages server state (loaded specs, registered tools, authentication context) and provides introspection endpoints for clients to discover available tools and their schemas. Implements graceful shutdown and resource cleanup.

Loads and manages multiple OpenAPI specifications simultaneously, registering tools from each spec and aggregating them into a single tool namespace. Handles spec conflicts (duplicate operation IDs, overlapping paths) by namespacing or renaming tools. Supports dynamic spec loading (adding/removing specs at runtime) and maintains a registry of all loaded specs and their associated tools. Enables LLM clients to interact with multiple APIs through a single MCP server instance.