MCP API Specification Resolver

This utility functions as an MCP (Model Context Protocol) gateway, providing structured, granular access to API documentation described in OpenAPI (version 3.0) or Swagger (version 2.0) formats, exposed through dedicated MCP Resources.

Core Objective

The fundamental purpose of this server is to enable MCP-aware applications (like Cline or Claude Desktop) to investigate the intricate structure of potentially massive API schema files without overwhelming the Language Model's input buffer. It achieves this by parceling out specification segments via Resource endpoints, which are optimized for read-only data retrieval.

This resolver supports ingestion of specifications originating from local filesystem paths or accessible via remote HTTP/HTTPS endpoints. Swagger v2.0 documents undergo automatic normalization into the OpenAPI v3.0 structure upon loading.

Rationale for MCP Resources vs. Tools

The Model Context Protocol framework delineates between Resources (data access) and Tools (executable actions).

• Resources: Intended for exposing static or dynamic data sets—analogous to reading files or API query results. This server leverages Resources because API schema exploration is inherently a read-only data navigation task, perfectly suited for browsing within client UIs.
• Tools: Reserved for invoking functions or carrying out operations.

While other MCP services might surface OpenAPI data via Tools, this specific implementation prioritizes the Resource paradigm for seamless, interactive exploration within MCP client environments.

For deeper insight into MCP client capabilities, consult the MCP Client Documentation.

Deployment Instructions

For the preferred execution modes (npx or Docker, detailed below), no prerequisite manual installation is necessary. The consumer MCP client handles the package retrieval or container image pull automatically based on the configuration provided.

If explicit local setup is required:

1. Global NPM Installation: Install the package globally into your system's environment:

   bash npm install -g mcp-openapi-schema-explorer

   Refer to Method 3 for client configuration using a globally installed binary.

2. Local Repository Build: For development or running a specific local branch: bash git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git cd mcp-openapi-schema-explorer npm install npm run build

   See Method 4 for configuring the client to execute this local build via node.

Integrating the Resolver into an MCP Client

This service is intended to be initiated and managed by MCP clients (such as Windsurf, Cline, or other supporting applications). Integration involves adding an execution definition to the client's configuration manifest (typically a JSON file). This definition dictates the command line invocation (e.g., via npx, docker, or node). The server itself only requires command-line arguments specifying the target schema.

Below are the standard configuration approaches for client setup:

Method 1: npx Execution (Recommended)

Using npx is favored because it bypasses reliance on global state or local installs, ensuring the client always launches the most current published version.

Configuration Snippet (npx):

Inject the subsequent JSON block into the mcpServers section of your client's settings file:

{ "mcpServers": { "My API Spec (npx) ": { "command": "npx", "args": [ "-y", "mcp-openapi-schema-explorer@latest", "", "--output-format", "yaml" ], "env": {} } } }

Usage Notes:

• Customize "My API Spec (npx)" to create a unique identifier for this specific configuration instance.
• Substitute <path-or-url-to-spec> with the absolute file path or the complete remote URL pointing to the specification.
• The --output-format flag is optional; valid options are json (default), yaml, or json-minified.
• To handle distinct APIs, provision separate entries within the mcpServers map, each unique in name and pointing to its respective specification.

Method 2: Docker Containerization

Leverage the official Docker image (kadykov/mcp-openapi-schema-explorer) to execute the resolver.

Configuration Snippets (Docker):

Add one of the following definitions to the mcpServers map. These configure the client to execute docker run:

• For Remote URLs:

{ "mcpServers": { "My API Spec (Docker Remote)": { "command": "docker", "args": [ "run", "--rm", "-i", "kadykov/mcp-openapi-schema-explorer:latest", "" ], "env": {} } } }

• For Local Files (Requires Volume Mounting):

{ "mcpServers": { "My API Spec (Docker Local)": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/full/host/path/to/spec.yaml:/spec/api.yaml", "kadykov/mcp-openapi-schema-explorer:latest", "/spec/api.yaml", "--output-format", "yaml" ], "env": {} } } }

Crucial Note: Replace /full/host/path/to/spec.yaml with the actual absolute path on your host system. The internal container path /spec/api.yaml must match the argument passed to the containerized process.

Method 3: Global NPM Installation (Alternative)

This method is applicable if you have executed npm install -g mcp-openapi-schema-explorer.

bash

Execution step (done once in the shell)

pm install -g mcp-openapi-schema-explorer

Configuration Snippet (Global Install):

This assumes the mcp-openapi-schema-explorer executable is discoverable within the PATH environment accessible by the MCP client.

{ "mcpServers": { "My API Spec (Global)": { "command": "mcp-openapi-schema-explorer", "args": ["", "--output-format", "yaml"], "env": {} } } }

• Verification is required to ensure the command binary is present in the client's execution context PATH.

Method 4: Local Development Runtime

This approach is suitable for testing locally cloned or modified source code.

Prerequisites (One-time setup in terminal):

1. Clone: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. Navigate: cd mcp-openapi-schema-explorer
3. Install: npm install
4. Compile: npm run build

Configuration Snippet (Local Build):

This configuration instructs the client to invoke the compiled JavaScript output using the Node runtime.

{ "mcpServers": { "My API Spec (Local Dev)": { "command": "node", "args": [ "/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js", "", "--output-format", "yaml" ],

  "env": {}
}

} }

Requirement: Update the path argument in args to point precisely to the generated file: /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js.

Key Capabilities

• MCP Resource Mapping: Browse OpenAPI constructs via standardized URIs (e.g., openapi://info, openapi://paths/..., openapi://components/...).
• Format Versatility: Handles both OpenAPI v3.0 and auto-converts Swagger v2.0.
• Input Flexibility: Accepts specifications from the local disk or external web locations (HTTP/HTTPS).
• Context Optimization: Engineered to conserve LLM context tokens by serving targeted specification segments.
• Data Serialization Control: Allows output to be rendered in JSON (default), YAML, or compacted JSON (--output-format).
• Dynamic Labeling: The server's identity presented to MCP clients dynamically adopts the info.title field from the loaded schema.
• Internal Link Resolution: Internal $ref pointers (like #/components/...) are automatically translated into navigable MCP Resource URIs.

Accessible MCP Resources

This service registers the following resource definitions for schema traversal.

Handling of Multi-Value Parameters (*)

Resource paths featuring a parameter suffixed with an asterisk (*), such as {method*} or {name*}, signify acceptance of a comma-delimited list of values. For instance, querying both GET and POST operations for a path is achieved via a URI like openapi://paths/users/get,post. This supports batch retrieval of related elements in a single request.

Resource Endpoints:

• openapi://{field}
• Function: Retrieves top-level document sections (info, servers, tags) or enumerates the contents of collection fields (paths, components). The exact fields listed are contingent on the loaded specification.
• Example: openapi://info
• MIME Type: text/plain list for collections; configured format for named fields.

• Completions: Context-aware suggestions based on the spec's actual top-level keys.

• openapi://paths/{path}

• Function: Lists the HTTP verbs (operations) defined for a specific API endpoint path.
• Parameter: {path} - The path segment. Must undergo URL encoding (e.g., /users/{id} becomes users%2F%7Bid%7D).
• Example: openapi://paths/users%2F%7Bid%7D
• MIME Type: text/plain list of methods.

• Completions: Dynamic suggestions for {path}, using URL-encoded paths from the specification.

• openapi://paths/{path}/{method*}

• Function: Fetches the detailed definition for one or more specified HTTP operations located at a given path.
• Parameters:
  • {path} - URL-encoded API path string.
  • {method*} - One or more HTTP verbs (e.g., get, post, specified as get,post). Case-insensitive.
• Example (Multiple): openapi://paths/users%2F%7Bid%7D/get,post
• MIME Type: Configured format (JSON/YAML/minified JSON).

• Completions: Suggestions for {path} provided dynamically. Static suggestions for common HTTP verbs are provided for {method*}.

• openapi://components/{type}

• Function: Lists the names and brief descriptions of all components belonging to a specified category (e.g., schemas, responses).
• Example: openapi://components/schemas
• MIME Type: text/plain list including descriptions.

• Completions: Dynamic suggestions for {type} based on component categories present in the spec.

• openapi://components/{type}/{name*}

• Function: Retrieves the complete definition for one or more components identified by name within a specified category.
• Parameters:
  • {type} - The component category.
  • {name*} - One or more component identifiers (e.g., User,Order). Case-sensitive.
• Example (Single): openapi://components/schemas/User
• MIME Type: Configured format (JSON/YAML/minified JSON).
• Completions: Dynamic suggestions for {type}. Note on {name*} completions: Due to limitations in scoping completions across disparate component types within the current MCP SDK context, name suggestions are only reliably provided if the specification contains only a single defined component type globally (e.g., only schemas exist).

Contribution Guidelines

We welcome all constructive contributions. Refer to the CONTRIBUTING.md file for detailed instructions on environment setup, testing procedures, and submission protocols.

Versioning and Releases

This repository utilizes semantic-release to automate version numbering and package publishing, adhering strictly to the Conventional Commits specification.

Prospective Enhancements

(Future development directions will be articulated here.)

WIKIPEDIA: XMLHttpRequest (XHR) is an application programming interface integrated into web browsers via a JavaScript object. Its methods facilitate the transmission of HTTP requests from the browser environment to a web server. This capability allows browser-based applications to initiate server communication post-page load and subsequently receive data back. XMLHttpRequest is a fundamental component of the Ajax programming paradigm. Before Ajax gained prominence, page navigation was dominated by link clicks and form submissions, actions that typically resulted in a full page refresh.