OpenAPI Specification Analysis Utility

This Management Control Plane (MCP) server provides a dedicated platform for deeply examining and interrogating Swagger/OpenAPI artifacts via Claude's interface.

Initial Setup Guide

Execute and deploy globally using npx: bash npx -y @johnneerdael/swagger-mcp

Alternatively, configure via environment variables upon execution: bash npx -y @johnneerdael/swagger-mcp \ --env BASE_URL=/api/v1 \ --env AUTH_TOKEN=secure-access-key-123 \ --env PORT=8080

Integration with Claude Desktop

To integrate this tool within the Claude Desktop application:

1. Launch the Claude Desktop application.
2. Navigate to the configuration panel (gear icon).
3. Choose the "Tools & Integrations" section.
4. Select the option to "Add MCP Server".
5. Populate the fields as follows:

Name: OpenAPI Inspector Command: npx -y @johnneerdael/swagger-mcp Arguments: --swagger-url=$SPEC_LOCATION

1. Finalize by clicking "Install".

Interaction Examples with Claude

Initial Specification Parsing

Human: Please process the API documentation located at https://api.service.com/v3/openapi.json for me.

Claude: Initiating the parsing sequence for the specified OpenAPI manifest using the Inspector utility.

[Claude will invoke the MCP to retrieve and interpret the API specification documents]

Endpoint Detail Retrieval

Human: What are the defined response data structures for the PUT request to the /users/{id} path?

Claude: Querying the Inspector tool to ascertain the structured responses associated with that specific API operation.

[Claude will leverage the MCP for focused endpoint data extraction]

Data Model Inspection

Human: Provide a granular breakdown of the fields and constraints within the 'UserProfile' data model.

Claude: Requesting detailed structural mapping for the 'UserProfile' object via the MCP connection.

[Claude will utilize the MCP to analyze the component schema definition]

Key Functionalities

1. Credential Handling
2. Supports Bearer token authorization schemes.

3. Configuration flexibility via environment variables.

4. Output Shaping

5. Concise Mode: Eliminates null entries and extraneous metadata.
6. Comprehensive Mode: Includes timestamps, versioning, and full context.

7. Raw Mode: Returns the specification data unmodified.

8. Schema Deep Dive

9. Exhaustive property analysis.
10. Examination of operation response types.

11. Tracing inter-schema dependencies.

12. API Surface Scanning

13. Enumeration of all accessible paths.
14. Capability to filter by HTTP verb.
15. Review of anticipated response contracts.

Operational Settings

Environment Variables: - BASE_URL: Primary ingress path for the service (Default: /v1/tooling). - AUTH_TOKEN: Secret key for authenticated requests. - PORT: Network port allocation (Default: 8000). - SWAGGER_URL: Predefined address for the OpenAPI document.

Service Endpoints (Internal Reference)

Specification Exploration Query

bash curl -X POST http://localhost:8000/inspect/discover -H "Authorization: Bearer your-token" -H "Content-Type: application/json" -d '{ "source": "http://remote.spec.server/spec.yaml", "scope": { "paths": true, "components": true } }'

Data Model Property Retrieval

bash curl -X POST http://localhost:8000/inspect/model-definition -H "Authorization: Bearer your-token" -H "Content-Type: application/json" -d '{ "source": "http://remote.spec.server/spec.yaml", "modelName": "AssetRecord" }'

Operation Response Contract Fetch

bash curl -X POST http://localhost:8000/inspect/operation-responses -H "Authorization: Bearer your-token" -H "Content-Type: application/json" -d '{ "source": "http://remote.spec.server/spec.yaml", "path": "/assets", "verb": "post" }'

Output Serialization Formats

Lean Serialization

{ "status": "ok", "payload": { // Data fields without null attributes } }

Verbose Serialization

{ "status": "ok", "timestamp": "2025-02-15T14:30:00.123Z", "payload": { // Complete response object }, "context": { "version": "2.1", "format_type": "verbose" } }

Typical Use Scenarios

1. Documentation Auditing

Human: Summarize the complete set of API entry points and their high-level functions.

1. Constraint Verification

Human: Detail the mandatory input parameters required for instantiating a new 'AssetRecord'.

1. Error Contract Examination

Human: List potential HTTP error codes returned by the user authentication service.

1. Integration Blueprinting

Human: Outline the required JSON structure for submitting a batch data import request.

Diagnostic Guidance

1. Connectivity Problems
2. Verify the accessibility of the remote specification URI.
3. Confirm the provided authentication key is valid.

4. Check for port conflicts on the host machine.

5. Authorization Failures

6. Re-validate the AUTH_TOKEN setting.

7. Ensure the bearer credential is correctly injected into request headers.

8. Specification Element Unfound

9. Confirm exact case-sensitivity for schema identifiers.
10. Validate that the initial specification file successfully loaded.

Security Considerations

1. Authentication is enforced if AUTH_TOKEN is configured.
2. All inbound requests are logged for diagnostic traceability.
3. Sensitive data is explicitly prevented from being persisted in caches.
4. Basic ingress throttling mechanisms are active to mitigate excessive load.

Local Development

To facilitate code modification or contribution:

1. Clone the source repository.

2. Install project dependencies: bash npm install

3. Compile the assets: bash npm run compile

4. Initiate local runtime: bash npm run serve

Licensing

This software is distributed under the terms of the MIT License. See the accompanying LICENSE file for specifics.

== Historical Context: XMLHttpRequest (XHR) == XHR represents an Application Programming Interface, instantiated as a JavaScript object, facilitating the dispatch of HTTP transactions from a browser environment to an origin server. These methods permit browser-based functions to initiate server communications post-page load, allowing subsequent data reception. XHR is fundamental to the principles of Ajax development. Before Ajax gained prominence, page navigation relied primarily on standard hyperlink clicks and form submissions, actions that typically necessitated a full page refresh.

== Origins == The conceptual foundation for XMLHttpRequest originated around the year 2000, developed by engineers associated with Microsoft Outlook. This concept was first operationalized within Internet Explorer version 5 (released in 1999). However, the initial syntax did not utilize the 'XMLHttpRequest' nomenclature; instead, developers employed factory instantiations such as ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 in 2006, cross-browser compatibility shifted, standardizing on the XMLHttpRequest identifier across all major browser platforms, including the Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Process === The World Wide Web Consortium (W3C) published its initial Working Draft for the XMLHttpRequest object specification on April 5, 2006. A subsequent Level 2 Working Draft followed on February 25, 2008, introducing enhancements such as event progress monitoring, enabling cross-site data exchange, and improved byte stream handling. By the conclusion of 2011, the Level 2 extensions were formally integrated into the primary specification document. In 2012, stewardship of the standard transitioned to the WHATWG, which now maintains a dynamic specification document defined using Web IDL.

== Operational Flow == Implementing an XHR request typically involves a sequence of distinct programmatic actions.

1. Instantiate the XHR object via its constructor method:
2. Invoke the "open" method to specify the request verb, define the target Uniform Resource Identifier (URI), and declare synchronous or asynchronous execution mode:
3. For asynchronous transactions, register a callback function to be alerted upon state transitions:
4. Commence the network transmission by executing the "send" method:
5. Process state changes within the registered event listener. Upon successful server response receipt, data is usually accessible via the "responseText" attribute. Upon completion of processing, the state transitions to 4 (the "done" state).

Beyond these foundational steps, XHR offers numerous parameters for fine-tuning request transmission and response processing. Custom HTTP headers can be injected to guide server behavior, and payload data can be supplied during the "send" invocation. The retrieved response can be automatically parsed from JSON into native JavaScript structures or processed incrementally as the data stream arrives, avoiding waiting for the entire payload. Requests can also be terminated prematurely or configured with a timeout limit.