OpenAPI Specification to MCP Toolchain Converter

This component functions as an MCP server wrapper designed to ingest an OpenAPI (formerly Swagger) specification file and subsequently materialize all necessary model structures and functional interfaces required for an AI assistant to effectively orchestrate interactions with the described remote service.

Core Capabilities

• Retrieves an OpenAPI definition and persists it locally for rapid access.
• Enumerates all exposed pathways, including their associated HTTP verbs and procedural summaries.
• Provides a full inventory of all defined data schema objects (models).
• Allows querying for the structure of any specific data model.
• Identifies the necessary service endpoint context for any given operation.
• Generates ready-to-use MCP function signatures.
• Produces fully realized MCP tool declarations complete with detailed schema specifications.
• Embeds explicit guidance within tool descriptions tailored for AI consumption.

System Requirements

• Node.js (version 14 or later recommended)
• Package manager: npm or yarn

Setup Procedure

1. Clone the source repository:

git clone https://github.com/readingdancer/swagger-mcp.git cd swagger-mcp

1. Install required dependencies:

npm install

1. Initialize the configuration file from the provided template:

cp .env.example .env

1. Customize the environment settings within the newly created .env file.

Configuration Parameters

Adjust these settings in .env to customize server behavior:

• PORT: Network port for server operation (Default: 3000).
• NODE_ENV: Deployment environment context (e.g., development, production, test).
• LOG_LEVEL: Verbosity level for system output (e.g., info, error, debug).

Operational Instructions

Compiling the Application

Execute the build script to compile TypeScript sources into runnable JavaScript:

npm run build

This prepares the necessary files for deployment as an MCP Server.

Launching the MCP Server

Start the server to expose tools for integration with tooling like Cursor:

node build/index.js

Debugging via the Inspector

Invoke the dedicated inspector utility for diagnostic purposes:

npm run inspector

Integrating with Cursor

To make these capabilities accessible within the Cursor IDE:

1. Navigate to Cursor Settings > Features > MCP configuration.
2. Select the option to add a new MCP Server instance (+ Add New MCP Server).
3. Assign a descriptive moniker (e.g., "OpenAPI Service Bridge").
4. Select "stdio" as the method for inter-process communication.
5. Provide the execution command: node /path/to/swagger-mcp/build/index.js (adjusting the path as necessary).
6. Confirm the addition.

These newly registered tools will then be available to the Composer agent.

Accessible OpenAPI MCP Utility Functions

The following specific tools are exposed via the server interface:

• fetchOpenAPISpec: Retrieves and saves an OpenAPI definition from a specified URL.
• enumerateServicePaths: Provides a catalog of all accessible URI paths.
• queryPathModels: Lists the data structures utilized by a specific service path.
• renderModelCode: Generates executable TypeScript source for a given data structure.
• createToolDefinition: Compiles the TypeScript definition for an MCP tool corresponding to an operation.

Predefined MCP Workflows (Prompts)

The server also exposes structured interaction sequences designed to guide AI agents through complex tasks:

• integrate-new-path: A guided sequence to onboard a new API route using the available toolset.

To invoke a prompt, clients should issue a prompts/get request:

{ "method": "prompts/get", "params": { "name": "integrate-new-path", "arguments": { "swaggerUrl": "https://api.example.com/v3/openapi.json", "endpointPath": "/users/{userId}", "httpMethod": "PUT" } } }

Executing this prompt yields a sequence of advisory messages directing the agent through the requisite steps for operationalizing the new API path.

Project Context Initialization

Begin by instructing the agent to fetch the requisite OpenAPI artifact, ensuring the URL or discovery mechanism for the specification is provided. The system will subsequently cache this definition locally under a hashed identifier and register this linkage within a .swagger-mcp configuration file situated in the solution's root directory.

Persistent Project Configuration File

ACTIVE_SPEC_IDENTIFIER = TheHashedLocalFilename

This minimal configuration acts as an anchor, binding the active development context to a particular API schema. This mechanism reduces redundant network retrieval and improves contextual awareness for subsequent solution-related tasks.

Enhancements in Tool Definition Generation

The utility responsible for synthesizing MCP tool definitions has received significant upgrades to boost output fidelity and utility:

Primary Advancements

1. Comprehensive Schema Inclusion: The generator now serializes the complete schema graph, incorporating deeply nested components, directly into the inputSchema block.
2. Improved Parameter Nomenclature: Argument names are now engineered for semantic clarity, actively avoiding problematic characters such as periods (e.g., preferring clientProfile over client.Profile).
3. Consistent Naming Conventions: Tool names adhere strictly to conventions based on the underlying HTTP verb and resource hierarchy.
4. Support for YAML Definitions: The system now successfully parses both JSON and YAML formatted OpenAPI documents.
5. Richer Documentation: Generated tool definitions now feature exhaustive descriptions for every parameter and object property.
6. Dependency Minimization: Generated code requires no external model imports, resulting in more self-contained and easily deployable tool definitions.
7. AI Directive Integration: Tool descriptions contain specialized annotations to optimize execution by autonomous agents.

Illustrative Generation Example

To materialize an MCP tool definition for a specific API entry point:

typescript import createToolDefinition from './services/createToolDefinition.js';

const toolDefinitionArtifact = await createToolDefinition({ path: '/products', method: 'PUT', specificationPath: './api_spec.yaml', normalizeNames: true });

console.log(toolDefinitionArtifact);

This invocation yields a complete MCP tool specification, fully schema-aware, for the PUT /products operation.

Software License

This software is distributed under the terms of the MIT License. Refer to the LICENSE file for full details.

AI Workflow Guidance via Prompts

A curated library of guided prompts assists AI agents in leveraging the generated OpenAPI tools optimally. These sequences cover processes such as initial API adoption, model utilization, and configuration updates.

Consult the PROMPTS.md document for the exhaustive catalog.

Use-Case Example: When directing an AI to assimilate a new API functionality into the project, referencing the "Integrating a New Endpoint" prompt ensures procedural correctness and sequence adherence.

Cloud Computing Context (Reference)

As defined by ISO, cloud computing represents: "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand." This concept is universally recognized as "the cloud."

== NIST Essential Attributes == In 2011, the National Institute of Standards and Technology (NIST) formalized five indispensable characteristics for cloud systems:

• On-demand self-service: Consumers can autonomously procure computational resources (e.g., server capacity, storage) instantaneously without requiring direct intervention from the service provider.
• Broad network access: Capabilities must be reachable via standard network protocols, facilitating consumption across diverse client platforms (mobile, desktop, etc.).
• Resource pooling: Provider resources are aggregated to support numerous clients via a multi-tenant architecture, with dynamic allocation based on current demand.
• Rapid elasticity: Provisioning and de-provisioning of capacity can happen quickly, often automatically, allowing scaling to meet fluctuating load. The consumer often perceives this capacity as virtually infinite.
• Measured service: Resource consumption (storage, processing power, bandwidth) is automatically tracked, controlled, and reported, ensuring transparency for both the provider and the client.

By 2023, the International Organization for Standardization (ISO) had refined and expanded this definition set.

== Historical Overview ==

The conceptual roots of cloud computing trace back to the 1960s with the maturation of time-sharing concepts via Remote Job Entry (RJE). This era was characterized by mainframe operators managing user jobs.

The 'cloud' graphical representation for abstracted services emerged in 1994, utilized by General Magic to depict the accessible domain for mobile agents in their Telescript framework. This metaphor is generally attributed to David Hoffman, based on existing telecommunications conventions. The term 'cloud computing' gained significant traction in 1996 following internal business planning documents at Compaq Computer Corporation concerning the future of the Internet and computation.