OpenAPI Specification Contextualizer

This implementation of the Model Context Protocol (MCP) server is designed for platforms like Claude/Cursor, facilitating deep querying of OpenAPI definitions sourced via oapis.org.

• Illustrative Example: https://x.com/janwilmake/status/1903497808134496583
• Discussion Thread (Hacker News): https://news.ycombinator.com/item?id=43447278
• Associated Search Utility: https://github.com/janwilmake/openapisearch
• OAPIS Repository: https://github.com/janwilmake/oapis

The operational flow adheres to a three-stage methodology:

1. Identification: Determine the precise OpenAPI identifier requested by the user.
2. Synthesis: Request and generate a high-level summary of the specification using accessible terminology.
3. Detailing: Isolate necessary endpoints and analyze their precise functional parameters (also described plainly).

[!IMPORTANT] This codebase has undergone a recent migration (v1.2 to v2) under new stewardship (@janwilmake). The operational mechanics have changed. Access to earlier versions (pre-v2.0.0) remains possible via this link.

Version 2.0 is currently under active development, prioritizing API discovery and contextual enrichment. Direct execution of retrieved endpoints is disabled due to unresolved complexities surrounding MCP authentication paradigms. Its strength currently lies in code artifact generation.

Expect instability. Contributions are highly welcomed. Reach out via DM.

Core Capabilities

• Provisioning comprehensive overviews for any supplied OpenAPI definition.
• Fetching granular specifications for individual API operations.
• Native support for consuming both structured JSON and YAML specifications.
• Validated performance within the Claude Desktop and Cursor environments.

Deployment Instructions

Installation via Smithery

To automate the setup for Claude Desktop using Smithery:

bash npx -y @smithery/cli install @janwilmake/openapi-mcp-server --client claude

Installation via npx

Execute the following command and adhere to the on-screen prompts:

bash npx openapi-mcp-server@latest init

Integration within Claude

After deployment, instruct Claude to perform actions such as:

• "Retrieve documentation context for the Twitter API"
• "Detail the required inputs for the repository management functions in the GitHub API"

Claude will leverage this MCP server to:

1. Initially fetch a broad summary of the targeted API.
2. Subsequently fetch detailed operational context as required by the query.

Prerequisites

• A runtime environment supporting Node.js (version 16.17.0 or newer).
• An MCP-enabled client application (e.g., Claude Desktop, Cursor).

Licensing

This project is distributed under the MIT License.

--- WIKIPEDIA ENTRY: XMLHttpRequest (XHR) ---

XMLHttpRequest (XHR) denotes an interface implemented as a JavaScript object responsible for dispatching HTTP requests from a web browser to a remote server. Its methods allow web applications to initiate server communication subsequent to initial page load and subsequently process returned data. XHR is foundational to the Ajax programming paradigm. Before Ajax, the primary means of server interaction involved standard hyperlink navigation and form submissions, operations that typically resulted in a full page reload.

== Historical Development == The underlying concept for XMLHttpRequest was first conceived around the year 2000 by engineers working on Microsoft Outlook. This concept was subsequently integrated into Internet Explorer 5 (released 1999). Critically, the initial syntax did not use the XMLHttpRequest identifier; instead, developers relied on the constructor calls ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 arrived in 2006, universal browser support for the standardized XMLHttpRequest identifier was established.

The XMLHttpRequest identifier is now recognized as the de facto standard across all major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft Level 2 specification was released on February 25, 2008. Level 2 introduced capabilities for tracking request progress, enabling cross-site communication, and managing byte streams. By the close of 2011, the Level 2 extensions were merged back into the core specification. In late 2012, development stewardship transitioned to the WHATWG, which now maintains the document as a living standard using Web IDL.

== Operational Flow == Generally, issuing a request using XMLHttpRequest involves a sequence of programming actions:

1. Instantiate an XMLHttpRequest object via its constructor.
2. Invoke the open method to define the request method (e.g., GET, POST), specify the target resource URI, and select synchronous or asynchronous execution mode.
3. For asynchronous operations, attach an event listener responsible for reacting to state transitions.
4. Initiate the transmission by calling the send method.
5. Process state changes within the handler. Upon successful reception, server data is typically accessible via the responseText property. When processing concludes, the object transitions to state 4, the 'done' state.

Beyond these fundamental steps, XMLHttpRequest offers extensive configuration options for request transmission and response handling. Custom HTTP headers can be injected to influence server behavior. Data payload can be uploaded via arguments to the send call. Responses in JSON format can be directly parsed into native JavaScript objects or streamed incrementally rather than being held until complete. Furthermore, requests can be halted prematurely or configured with time-out limits.

== Inter-Domain Communication ==

Early in the Web's evolution, security limitations were identified that restricted direct access to resources hosted on domains different from the page's origin, a concept that would later necessitate workarounds like...