OpenAPI Specification Processor for MCP Agents

This specialized MCP server component interfaces directly with OpenAPI definitions (previously known as Swagger) to bootstrap the creation of necessary models and associated MCP service definitions for autonomous agents.

Core Functionality

• Locally caches downloaded OpenAPI documents for enhanced retrieval speed.
• Enumerates all accessible service endpoints, including their HTTP verbs and descriptive annotations.
• Provides a complete roster of defined data schemas (models).
• Retrieves the full definition for any specified data model.
• Identifies the underlying service path associated with a given operation.
• Outputs ready-to-use MCP function definitions.
• Constructs complete, fully annotated MCP tool manifests, incorporating granular schema details.
• Embeds specific operational directives within tool metadata tailored for AI consumption.

Dependencies

Requires the execution environment to have:

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

Deployment Sequence

1. Source Code Retrieval: bash git clone https://github.com/readingdancer/swagger-mcp.git cd swagger-mcp

2. Dependency Resolution: bash npm install

3. Environment File Initialization: bash cp .env.example .env

4. Parameter Customization: Adjust variables within the newly created .env file.

Operational Setup

Configure the server via the .env file:

• PORT: Network listener designation (Default: 3000).
• NODE_ENV: Operational context (e.g., 'development', 'production').
• LOG_LEVEL: Verbosity setting for system output (e.g., 'info', 'debug').

Execution Procedures

Compilation Step

Compile the source TypeScript into executable JavaScript: bash npm run build

Launching the MCP Backend

Start the server to expose tools for integration environments like Cursor: bash node build/index.js

Debugging Utility

Execute the MCP diagnostic utility: bash npm run inspector

Integration into Cursor/Agent Environments

To make these capabilities available to an agent: 1. Navigate to Cursor Preferences > Features > MCP (Machine Control Protocol). 2. Initiate the addition of a new server instance (+ Add New MCP Server). 3. Assign a recognizable label (e.g., "OpenAPI Tool Provider"). 4. Specify the communication modality as "stdio". 5. Input the execution command: node /path/to/swagger-mcp/build/index.js (including any necessary startup arguments). 6. Finalize the setup.

These newly defined instruments will then populate the Composer's toolkit for the AI agent.

Exposed MCP Utility Set

The server makes the following primary tools available:

• fetchOpenAPIDefinition: Retrieves and caches the specification from a provided URL.
• enumerateEndpoints: Lists all defined service access points.
• queryEndpointModels: Details the data structures utilized by a particular operation.
• renderModelTypeDefinition: Outputs canonical type code for a specified schema.
• renderOperationToolManifest: Generates the complete MCP tool definition for a specific API method.

Agent Workflow Prompts

In addition to direct tools, pre-defined guidance sequences expedite complex tasks:

• integrate-new-operation: A structured sequence guiding the agent through defining an operation based on the specification.

Agents can invoke these via a prompts/get mechanism. For instance, to initiate the integration of a specific path:

{ "method": "prompts/get", "params": { "name": "integrate-new-operation", "arguments": { "swaggerUrl": "https://api.example.com/v3/openapi.json", "targetPath": "/user/profile/{id}", "operationVerb": "GET" } } }

This prompt sequence directs the AI through the precise steps necessary for integrating the target operation.

Local Configuration Persistence

Upon initial retrieval, the OpenAPI artifact is saved locally using a content-derived identifier. This identifier is recorded in a project-root configuration file named .swagger-mcp-context.

ACTIVE_SPEC_FILE_ID = [HashBasedFileName]

This file establishes a persistent link between the working directory and the associated API contract, optimizing subsequent data access and reducing redundant external requests.

Advanced Tool Manifest Generation

The code generation engine has undergone significant refinement to yield superior, production-ready tool specifications:

Enhancement Summary

1. Comprehensive Data Typing: Generation incorporates the entirety of model structures, including deeply nested object references, directly within the inputSchema specification.

2. Improved Naming Conventions: Input parameter names are now contextually meaningful, systematically eliminating ambiguous characters (e.g., favoring userCredentials over user.Credentials).

3. Methodical Naming: Tool identifiers now adhere strictly to conventions derived from the associated HTTP action and resource hierarchy.

4. Format Versatility: Expanded capability to process both JSON and YAML representations of the OpenAPI specification.

5. Enhanced Metadata: Generated tool descriptors now feature exhaustive documentation for every input parameter and output field.

6. Self-Contained Output: Artifacts do not impose external file dependencies, promoting easier integration and portability.

7. Agent Directives: Tool descriptions now contain explicit instructions designed to optimize the AI's invocation strategy.

Generation Example

To create a manifest for the POST /resources operation:

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

const toolManifest = await renderOperationToolManifest({ apiPath: '/resources', verb: 'POST', specLocation: './api_contract.yaml', normalizeNames: true });

console.log(toolManifest);

This operation yields a fully structured MCP manifest tailored for the specified API interaction.

Legal Notice

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

Guided AI Operations

A curated set of procedural prompts supports agents utilizing the OpenAPI Transformation tools for routine activities such as dependency integration and schema manipulation.

Consult the PROMPTS.md documentation for the complete catalog of available workflows.

Example Scenario: When tasked with integrating a new service capability, referencing the "Operation Integration" prompt ensures adherence to best practices.