OpenAPI Specification Utility for MCP Tool Generation

This specialized MCP server component interfaces directly with an OpenAPI specification to facilitate the automatic creation of necessary data structures and operational methods required to build a robust MCP service layer for any compliant API.

Core Capabilities

• Retrieves and persists local copies of OpenAPI documents to optimize subsequent access latency.
• Provides granular introspection capabilities for all defined service entry points, including their associated HTTP verbs and functional descriptions.
• Exposes a catalog of all data models referenced within the specification.
• Allows retrieval of specific, detailed model definitions.
• Identifies the underlying target service URL associated with any given endpoint.
• Offers utility functions to synthesize appropriate MCP function signatures.
• Engineers complete, fully specified MCP tool manifests incorporating exhaustive schema details.
• Embeds specialized contextual directives within tool descriptions tailored for advanced AI reasoning engines.

Prerequisites for Operation

• Runtime environment: Node.js, version 14 or newer.
• Package manager: npm or yarn.

Setup Procedure

1. Source Code Acquisition:

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

1. Dependency Installation:

bash npm install

1. Environment Variable Initialization:

bash cp .env.example .env

1. Configuration Refinement:

Modify the newly created .env file to align with deployment requirements.

Configuration Parameters

• PORT: Network listener port (Default: 3000).
• NODE_ENV: Operational context (e.g., 'development', 'production').
• LOG_LEVEL: Verbosity setting for internal logging (e.g., 'info', 'error', 'debug').

Execution Instructions

Application Compilation

Prepare the TypeScript sources for runtime execution:

bash npm run build

This command compiles the source code into executable JavaScript artifacts.

Launching the MCP Service Host

Execute the server instance intended for integration with intelligent agents like Cursor:

bash node build/index.js

Debugging with the MCP Inspector

To utilize the built-in diagnostic utility:

bash npm run inspector

Integration with Cursor IDE

To enable this functionality within the Cursor IDE environment:

1. Navigate to Cursor Settings -> Features -> MCP.
2. Select the option to "+ Add New MCP Server".
3. Assign a descriptive label (e.g., "OpenAPI Transformer").
4. Select "stdio" as the communication transport mechanism.
5. Input the server execution command: node path/to/swagger-mcp/build/index.js along with any necessary command-line flags.
6. Finalize the addition by clicking "Add".

This action makes the associated tools accessible to the Cursor Agent within its compositional workflow environment.

Exposed MCP Utilities

The following discrete tools are surfaced by this service endpoint:

• getSwaggerDefinition: Fetches and caches an OpenAPI definition from a specified URI.
• listEndpoints: Enumerates all accessible paths and their associated methods from the loaded specification.
• listEndpointModels: Details the data schemas utilized by a particular service route.
• generateModelCode: Produces source code representations (e.g., TypeScript interfaces) for a given model.
• generateEndpointToolCode: Renders a complete MCP tool definition based on an endpoint's signature.

Available MCP Instructional Prompts

The server also hosts curated MCP instructional sequences designed to guide AI assistants through complex procedures:

• add-endpoint: A structured workflow to incorporate a new API interaction point using the generated tools.

Clients can invoke these structured guides via a prompts/get request:

{ "method": "prompts/get", "params": { "name": "add-endpoint", "arguments": { "swaggerUrl": "https://petstore.swagger.io/v2/swagger.json", "endpointPath": "/pets/{id}", "httpMethod": "GET" } } }

This prompt yields a sequence of conversational steps for the AI to follow, ensuring precise execution of the endpoint addition process.

Project Initialization Workflow

Initially, instruct the assistant to fetch the necessary OpenAPI document, providing either the direct URL or sufficient metadata for its location. The system will download the definition, save it under a cryptographically hashed filename, and record this file reference in a local .swagger-mcp configuration file located in the current solution root.

Persisted Configuration File (.swagger-mcp)

SWAGGER_FILENAME = [TheHashedNameOfTheStoredFile]

This minimal configuration binds the current development workspace to a specific API specification. Future operations will reference this local cache, minimizing redundant network calls for project-related API interactions.

Advanced Tool Definition Compilation

The utility responsible for generating MCP tool code has undergone significant enhancement to yield superior, production-ready definitions:

Key Enhancements

1. Comprehensive Schema Fidelity: The generator now incorporates the complete hierarchical schema for all related data models directly within the inputSchema block.

2. Semantic Parameter Labeling: Input parameters are now assigned more intuitive and robust names, systematically avoiding characters that cause parsing issues (e.g., using serviceRequest instead of service.Request).

3. Consistent Naming Conventions: Tool identifiers now adhere to standardized formats derived logically from the HTTP method and the associated resource path.

4. Multi-Format Support: The utility now successfully processes both JSON and YAML serialized OpenAPI definition files.

5. Rich Documentation Inclusion: Generated tool specifications feature thorough descriptions for every parameter and data field.

6. Self-Contained Output: The generated code is dependency-free regarding external model files, improving portability and ease of direct integration.

7. AI Optimization Directives: Tool descriptions contain specific guidance annotations to optimize their invocation by autonomous agents.

Example Code Generation Invocation

To produce the MCP tool specification for a specific API route:

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

const toolCode = await generateEndpointToolCode({ path: '/pets', method: 'POST', swaggerFilePath: './petstore.json', singularizeResourceNames: true });

console.log(toolCode);

This execution yields a complete MCP tool definition, fully parameterized with detailed schema metadata for the POST operation targeting /pets.

Licensing

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

Agent Guidance Prompts

To maximize the efficacy of AI assistants when interacting with the OpenAPI-derived tools, a suite of prescriptive prompts has been curated. These guide agents through typical activities such as onboarding new endpoints or leveraging generated data structures.

Review the PROMPTS.md document for the complete catalog.

Example Scenario: If an assistant is tasked with extending project capabilities by adding a new API endpoint, referencing the "Adding a New Endpoint" prompt ensures adherence to the established, correct sequence of tool operations.