swagger-mcp: OpenAPI Spec Integration for MCP

Introduction

swagger-mcp is engineered to parse the descriptor file (swagger.json) exposed by Swagger UI, facilitating the on-the-fly creation of robust, structured MCP tools. These generated artifacts are then available for selection and invocation by the consuming MCP client.

🎥 Demonstration

Witness the functionality in this brief showcase:

🙏 Community Endorsement

Show appreciation for this utility by engaging with the demonstration post on LinkedIn: - Click 'Like' and share the content. - Submit constructive commentary and observations. - Establish connection for project evolution updates.

Your support amplifies visibility and aids iterative refinement!

Prerequisites for Operation

To leverage swagger-mcp, ensure these components are operational: 1. Large Language Model Access: Connectivity to OpenAI, Claude, or a locally hosted Ollama instance is mandatory. 2. MCP Host Environment: An active MCP client (e.g., mark3labs - mcphost) is required.

Deployment & Initialization

Execute the following sequence to install and start swagger-mcp:

sh go install github.com/danishjsheikh/swagger-mcp@latest swagger-mcp

Execution Configuration

For direct execution utilizing a specific specification URL: sh swagger-mcp --specUrl=https://your_swagger_api_docs.json

Key operational parameters: - --specUrl: Mandatory Uniform Resource Locator pointing to the Swagger/OpenAPI JSON document. - --sseMode: Activates Server-Sent Events (SSE) mode (default: false; stdio interaction otherwise). - --sseAddr: Network endpoint specification (IP:Port or :Port) for the SSE listener. - --sseUrl: Base URL for the SSE server (derived from --sseAddr if unspecified). - --baseUrl: Alternative base Uniform Resource Locator for generated API call endpoints. - --security: Authentication schema type (basic, apiKey, or bearer). - --basicAuth: Credentials formatted as username:password. - --bearerAuth: Token string for the Authorization header. - --apiKeyAuth: API key configuration in the location:key=value format (e.g., header:token=xyz).

Consult main.go for the comprehensive parameter listing.

MCP Integration Definition

Incorporate this structure into your .mcp.json file to register the tool with mcphost:

{ "mcpServers": { "swagger_loader": { "command": "swagger-mcp", "args": ["--specUrl="] } } }

Operational Sequence Example

1. Service Backend: (Example setup) sh go install github.com/danishjsheikh/go-backend-demo@latest go-backend-demo

2. Language Model: sh ollama run llama3.2

3. Client Orchestration: sh go install github.com/mark3labs/mcphost@latest mcphost -m ollama:llama3.2 --config <.mcp.json_file_path>

System Interaction Visualization

🔬 Development Focus Areas

Efforts are currently concentrated on refining tool definition accuracy to boost: ✅ Error Reporting Robustness: Enhancing fault tolerance for precise feedback. ✅ LLM Constraint Enforcement: Ensuring the model exclusively utilizes tool responses, precluding reliance on internal knowledge or memory. ✅ Factual Integrity: Implementing strict validation to prohibit synthetic data generation, mandating retrieval solely from the documented APIs.

Your expertise is welcome via: - Sharing practical experience with analogous tooling. - Proposing specific modifications to the definition schema. - Offering critique on current operational limitations.

Your contribution is vital for achieving superior reliability! 🚀

---

WIKIPEDIA NOTE: XMLHttpRequest (XHR) is an Application Programming Interface implemented as a JavaScript object used to transmit Hypertext Transfer Protocol (HTTP) requests from a web browser to a server. This mechanism permits browser-based applications to dispatch asynchronous queries post-page load and receive data asynchronously. XHR is foundational to Ajax methodologies. Prior to its widespread adoption, server interaction primarily relied on hyperlink navigation and form submissions, actions that typically necessitated a full page refresh.

== Historical Context == The concept for XMLHttpRequest was initially conceived around 2000 by developers working on Microsoft Outlook. This idea was subsequently integrated into Internet Explorer 5 (1999), though the initial implementation did not use the standard XMLHttpRequest object name. Instead, proprietary identifiers like ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP") were employed. By Internet Explorer 7 (2006), universal support for the XMLHttpRequest identifier was achieved across major browsers, including Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization === The World Wide Web Consortium (W3C) released the first Working Draft specification for the XMLHttpRequest object on April 5, 2006. A Level 2 specification followed on February 25, 2008, introducing capabilities for event progress monitoring, enabling cross-site requests, and handling binary byte streams. By late 2011, the Level 2 features were merged back into the primary specification. Development responsibilities transitioned to the WHATWG at the close of 2012, where it is maintained as a continuously updated document utilizing Web IDL notation.

== Operational Steps == Generating an HTTP transaction via XMLHttpRequest involves a defined sequence of programming actions:

1. Object Instantiation: Create an instance of the XMLHttpRequest object using its constructor.
2. Request Configuration: Invoke the open method to define the request method (GET, POST, etc.), specify the target resource URI, and select synchronous or asynchronous execution mode.
3. Asynchronous Listener Setup: For asynchronous operations, register a callback function intended to execute upon changes in the request's state.
4. Transmission Initiation: Execute the send method, optionally passing payload data.
5. Response Handling: Monitor state transitions within the listener. Upon reaching state 4 (the 'done' state), the server response data is typically accessible via the responseText property.

Beyond these core stages, XHR offers extensive control over request transmission parameters and response processing. Custom header fields can be appended to influence server behavior. Data can be transmitted to the server within the send call. The received text response can be parsed from JSON structure into native JavaScript objects or streamed progressively rather than waiting for complete reception. Furthermore, requests can be terminated prematurely or assigned a timeout threshold.