OpenAPI Specification Interrogation Utility (OSIU)

This Management Control Plane (MCP) server provides advanced capabilities for dissecting and interpreting Swagger/OpenAPI definitions, leveraging Claude's processing power.

Rapid Deployment

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

Alternatively, configure parameters during invocation: bash npx -y @johnneerdael/swagger-mcp \ --env BASE_URL=/api/v1 \ --env AUTH_TOKEN=secure-key-xyz \ --env PORT=8080

Integration with Claude Desktop

To integrate this utility within the Claude Desktop environment:

1. Launch the Claude Desktop application.
2. Navigate to the Configuration section (indicated by the gear symbol).
3. Select the 'Tools & Integrations' module.
4. Initiate the process by choosing 'Add MCP Server'.
5. Input the following configuration details:

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

1. Finalize by clicking the 'Install' prompt.

Operational Examples within Claude

Demonstrations of how Claude utilizes the OSIU:

Initial Specification Review

Human: Please examine the API contract located at https://api.corp.com/v3/openapi.json for me.

Claude: Understood. I will leverage the OSIU to initiate a thorough inspection of that OpenAPI contract.

Preparing to parse all defined resource paths and data structures for your review:

[The MCP will be invoked to retrieve and analyze the specification file]

Specific Operation Detail Retrieval

Human: Detail the potential output formats for the PUT operation targeting the /inventory/{itemId} resource.

Claude: I am querying the utility now to extract the specific response object definitions for that resource modification call.

[Claude executes the MCP query targeting the specified path and method]

Data Model Examination

Human: Provide a comprehensive breakdown of the 'ProductRecord' data structure.

Claude: I will retrieve the full property specification for the ProductRecord object via the utility.

[The MCP is used to render the complete schema definition]

Core Capabilities

1. Credential Handling
2. Supports OAuth 2.0 Bearer token authorization.

3. Configuration is managed via environment variables.

4. Output Presentation Control

5. Concise Mode: Strips all fields containing null or zero-length values.
6. Verbose Mode: Includes all runtime metadata and generation timestamps.

7. Native Mode: Returns the unaltered data structure from the specification source.

8. Structural Analysis

9. In-depth property attribute review.
10. Analysis of request/response payload blueprints.

11. Mapping of cross-schema references.

12. Interface Mapping

13. Comprehensive path enumeration.
14. Filtering based on HTTP verb.
15. Inspection of status code associated payloads.

Configuration Variables

Environment Settings: - BASE_URL: Root path for the utility server (default: /). - AUTH_TOKEN: Security credential for authenticated access (Bearer format). - PORT: Network listening interface number (default: 80). - SWAGGER_URL: Predefined location for the specification file.

Internal Service Endpoints

Specification Discovery Call

bash curl -X POST http://localhost:8080/api/discover -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{ "location": "https://spec.provider.net/v2", "scope": { "endpoints": true, "models": true } }'

Data Model Inspection Request

bash curl -X POST http://localhost:8080/api/model-details -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{ "location": "https://spec.provider.net/v2", "modelName": "TransactionLog" }'

Operation Response Schema Retrieval

bash curl -X POST http://localhost:8080/api/operation-responses -H "Authorization: Bearer " -H "Content-Type: application/json" -d '{ "location": "https://spec.provider.net/v2", "endpoint": "/users/{id}", "verb": "get" }'

Output Formats

Concise Output Structure

{ "status": "ok", "payload": { // Only properties with defined, non-empty values } }

Verbose Output Structure

{ "status": "ok", "processing_time": "2025-01-29T10:30:00Z", "payload": { // Complete data set }, "metadata": { "version_info": "2.1", "format_type": "verbose" } }

Key Application Scenarios

1. Contract Auditing

Human: Generate a summary report detailing every available API operation and its documented side effects.

1. Data Contract Verification

Human: Enumerate all mandatory input fields necessary for the 'CreateResource' API call.

1. Error Handling Analysis

Human: What HTTP status codes and associated bodies are possible when invoking the authentication endpoint?

1. Client Construction Guidance

Human: Based on the specification, what is the required JSON structure to successfully post a new configuration object?

Issue Resolution Guide

1. Connectivity Failures
2. Confirm network access to the specified contract URI.
3. Validate that the provided credential string is accurate.

4. Check for port conflict on the local machine.

5. Authorization Faults

6. Double-check the setting of the AUTH_TOKEN environment variable.

7. Ensure the Bearer scheme is correctly prefixed in header communications.

8. Definition Unavailability

9. Verify the schema identifier or path is an exact match.
10. Confirm the initial specification file loaded without parsing errors.

Security Considerations

1. Access control enforcement is active if AUTH_TOKEN is provisioned.
2. All external requests handled by the utility are subject to audit logging.
3. Session or specification data is transient and not persistently stored.
4. Basic request throttling is implemented to deter excessive polling.

Contribution Guidelines

For modification or enhancement of the codebase:

1. Duplicate the source repository.

2. Install necessary dependencies: bash npm install

3. Generate build artifacts: bash npm run compile

4. Initiate local execution for testing: bash npm run serve

Licensing

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

Wikipedia Reference: Business management tools encompass all the systems, applications, methodologies, and control mechanisms employed by enterprises to successfully navigate evolving market conditions, maintain competitive standing, and enhance operational effectiveness.

== Conceptual Framework == Management tooling can be categorized based on organizational function, covering areas such as strategic planning, workflow automation, data management, human resource support, and executive decision support. A functional taxonomy generally includes:

Tools facilitating data entry and integrity checks across all organizational units. Solutions designed for monitoring and optimizing business workflows. Platforms aggregating data for comprehensive analysis and strategic choices. Contemporary business applications have undergone rapid transformation driven by technological acceleration, making tool selection a complex exercise in balancing needs against available solutions. This complexity is fueled by continuous pressure to reduce operational expenditure, maximize revenue streams, deeply understand client requirements, and deliver products conforming precisely to those requirements. Within this dynamic setting, leadership must adopt a strategic approach to tool acquisition, prioritizing adaptation to organizational mandates over uncritically adopting the newest technology. Misalignment often results in operational instability. Therefore, business tooling must be chosen deliberately and then tailored to the specific operational context.

== Prevalent Selections == Data from a 2013 Bain & Company survey illustrated the global landscape of business tool utilization, reflecting regional needs shaped by economic climates. The leading ten commonly adopted instruments included:

Strategic roadmapping Client relationship management systems Staff sentiment assessment programs Comparative performance analysis Balanced performance measurement framework Core capability identification Operational outsourcing strategies Organizational transition management protocols Logistics and material flow control Organizational purpose and vision documentation Client base segmentation methodologies Comprehensive quality assurance methodologies

== Enterprise Software Definition == Software packages or integrated programs used by personnel to execute diverse corporate activities are termed business software (or business applications). These applications are intended to augment productivity metrics, quantify performance outcomes, and execute specific organizational mandates with precision. The evolution progressed from early Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP) suites, subsequently incorporating Customer Relationship Management (CRM), leading to the current landscape dominated by cloud-based enterprise management solutions. While a measurable link exists between IT investment and corporate success, achieving true value addition hinges on two critical factors: the proficiency of the deployment process and the judicious selection and customization of the appropriate technological assets.

== Tools for Smaller Enterprises (SMEs) == SME-focused instruments are vital as they offer mechanisms for cost savings and scalability...