OpenAPI Specification Orchestrator (OSO)

This server component processes and disseminates OpenAPI/Swagger schemas via the Model Context Protocol (MCP) framework.

Core Capabilities

• Manages loading and serving of OpenAPI/Swagger definitions.
• Comprehensive support for diverse credentialing mechanisms:
• Basic Authorization schema
• Bearer Credential validation
• API Key injection (via HTTP header or query parameter)
• OAuth2 token handling
• Automatic synthesis of MCP tooling interfaces directly from discovered API routes.
• Integration of SSE functionality for continuous, push-based updates.
• Native TypeScript compatibility.

Security Posture

Crucial Notice: This is intended strictly for internal or personal use! Under no circumstances should this orchestrator be directly exposed to the public internet. If the targeted backend service necessitates authentication, public exposure of this MCP gateway is strongly discouraged.

Development Roadmap (Future Enhancements)

• Secret Management: Implement functionality for the orchestrator to securely utilize user-provided secrets for authenticating outgoing requests to the target API.
• Test Coverage: Develop a thorough and extensive testing suite.

Prerequisites for Deployment

• Runtime Environment: Node.js (version 18 or newer is required)
• Package Manager: Yarn
• Language Support: TypeScript

Setup Procedure

1. Obtain the source code repository: bash git clone https://github.com/dcolley/swagger-mcp.git cd swagger-mcp

2. Install necessary project dependencies: bash yarn install

3. Initialize configuration by copying the example environment file: bash cp .env.example .env

4. Configure the OpenAPI/Swagger artifact path:

5. Store your specification file locally (e.g., named swagger.json)

6. Alternatively, specify a reachable URI pointing to the definition.

7. Adjust server parameters within config.json:

{ "server": { "host": "localhost", "port": 3000 }, "swagger": { "url": "url-or-path/to/your/swagger.json", "apiBaseUrl": "https://api.example.com", // Used if base URL is missing from spec "defaultAuth": { // Used as fallback authentication configuration "type": "apiKey", "apiKey": "your-api-key", "apiKeyName": "api_key", "apiKeyIn": "header" } } }

Note on Precedence: The information contained within the loaded Swagger document takes precedence over settings defined in the configuration file: - If the servers array is present in the schema, its initial entry dictates the operational base URL. - Security definitions within the schema govern authentication protocols. - Configuration file entries act solely as the default fallback mechanism.

Execution Instructions

1. Initiate the development iteration environment: bash yarn dev

2. Compile artifacts for a production deployment: bash yarn build

3. Launch the optimized production instance: bash yarn start

Exposed Service Interfaces

• GET /health: Verifies the operational status of the orchestrator.
• GET /sse: Establishes a persistent Server-Sent Events channel.
• POST /messages: Transmits data payloads intended for the MCP server interface.

Validation

Execute the integrated test suite: bash

Run all tests once

yarn test

Run tests reactively upon code changes

yarn test:watch

Generate and view test coverage metrics

yarn test:coverage

Credential Handling

The system supports multiple means of authenticating requests against the target API. These methods are configured in config.json to serve as defaults when not explicitly defined within the OpenAPI schema:

Basic Authentication

{ "defaultAuth": { "type": "basic", "username": "your-username", "password": "your-password" } }

Bearer Token Flow

{ "defaultAuth": { "type": "bearer", "token": "your-bearer-token" } }

API Key Strategy

{ "defaultAuth": { "type": "apiKey", "apiKey": "your-api-key", "apiKeyName": "X-API-Key", "apiKeyIn": "header" } }

OAuth2 Protocol

{ "defaultAuth": { "type": "oauth2", "token": "your-oauth-token" } }

Development Workflow

1. Initiate the development lifecycle server: bash yarn dev

Licensing Information

This software is distributed under the terms of the Apache License, Version 2.0.

Environment Parameters

• PORT: Specifies the network listening port (default value is 3000)
• API_USERNAME: User credential for API interaction (fallback source)
• API_PASSWORD: Secret password for API interaction (fallback source)
• API_TOKEN: Authentication credential string for API calls (fallback source)
• DEFAULT_API_BASE_URL: The default root URL for routing requests to the backend API
• DEFAULT_SWAGGER_URL: The default location or URI for loading the OpenAPI schema

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface standardized as a JavaScript object. Its member functions are utilized to dispatch HTTP requests from a web browser to a remote web server. These functions enable browser-based applications to submit inquiries to the server post-initial page load and subsequently retrieve ensuing data. XMLHttpRequest is foundational to the Ajax paradigm. Before Ajax gained traction, the dominant methods for server interaction involved traditional hyperlink traversal and form submissions, procedures which typically resulted in a full page replacement.

== Chronology == The fundamental concept underpinning XMLHttpRequest was first conceived in the year 2000 by the engineering staff responsible for Microsoft Outlook development. This concept was subsequently integrated into Internet Explorer version 5 (released in 1999). However, the initial implementation did not utilize the standardized XMLHttpRequest identifier. Instead, developers relied on instantiating COM objects via ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), universal recognition of the XMLHttpRequest identifier has been achieved across all major browser platforms. The XMLHttpRequest identifier has since evolved into the recognized cross-browser convention, supported by engines such as Mozilla's Gecko (since 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Specification Evolution === The World Wide Web Consortium (W3C) formally issued a Working Draft specification detailing the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft, designated Level 2, was released by the W3C on February 25, 2008. Level 2 introduced crucial enhancements, including mechanisms for progress monitoring, support for cross-origin data retrieval, and improved handling of raw byte sequences. By the conclusion of 2011, the features defined in the Level 2 specification were merged back into the core specification document. In late 2012, stewardship of the document transitioned to the WHATWG, which currently maintains the standard as a living document specified using Web IDL.

== Operational Steps == Generally, dispatching a network transaction using XMLHttpRequest necessitates adherence to several sequential programming operations.

Instantiate an XMLHttpRequest object instance via its constructor call: Invoke the open() method to define the request methodology (e.g., GET, POST), designate the target resource URI, and stipulate whether the execution should be synchronous or asynchronous: If an asynchronous transaction is chosen, establish a handler function that will be triggered whenever the request's status transitions: Commence the transmission by calling the send() method, optionally supplying data payload: Process state changes within the registered event handler. If the remote server returns data, this content is, by default, stored within the responseText attribute. When the object finalizes response processing, its state transitions to 4, signifying the 'complete' status. Beyond these fundamental stages, XMLHttpRequest offers extensive control over transmission parameters and response ingestion. Custom header fields can be prepended to the outbound request to instruct the server on preferred handling, and application data can be forwarded to the server as an argument within the send() invocation. The received response can be programmatically parsed from JSON format into a natively usable JavaScript entity, or streamed incrementally rather than awaiting total receipt. The transaction can also be terminated prematurely or configured with a timeout limit.

== Requests Across Domain Boundaries ==

Early in the evolution of the World Wide Web architecture, it was identified that circumventing security restrictions that preven