🚀 OpenAPI Spec Master MCP Server 🚀

Welcome to the OpenAPI Spec Master MCP Server! This server provides a powerful set of tools to work with your OpenAPI specifications, all accessible through the Model Context Protocol (MCP).

⚡ Quick Start ⚡

Get up and running in a flash with npx:

npx @ryancardin/openapi-spec-master-mcp@latest

This command fires up the MCP server using the STDIO transport by default. This is ideal for local development and integration with tools that use standard input/output.

For remote access or use cases requiring an HTTP interface, you can start the server in HTTP mode:

npx @ryancardin/openapi-spec-master-mcp@latest http

The HTTP server exposes all 16 tools — both through a modern MCP Streamable HTTP transport at /mcp and through the legacy REST helper routes used by the web app and VS Code extension.

⚙️ Configuration ⚙️

You can configure the server using command-line arguments and environment variables:

• Transport (Command-Line Argument):
  • (default): Starts the server with stdio transport.
  • http [port]: Starts an HTTP server. An optional positional port argument takes precedence over the PORT env var.
• PORT (Environment Variable): Set the port for the HTTP server (defaults to 3001). Ignored if a port is passed as the second CLI argument.

Examples

Running with STDIO (default):

npx @ryancardin/openapi-spec-master-mcp@latest

Running with HTTP:

npx @ryancardin/openapi-spec-master-mcp@latest http

Running with a specific port for HTTP:

# via positional argument
node dist/index.js http 8080

# or via environment variable
PORT=8080 npx @ryancardin/openapi-spec-master-mcp@latest http

🌐 HTTP Transport & the Streamable /mcp Endpoint 🌐

When started in http mode the server mounts the SDK's Streamable HTTP transport at /mcp, so any modern MCP client can connect over HTTP with full protocol support (initialize, tools/list, tools/call, server→client streaming and session teardown):

| Method | Path | Purpose | | --- | --- | --- | | POST | /mcp | Initialize a session and send JSON-RPC requests. The response carries an Mcp-Session-Id header. | | GET | /mcp | Open the server→client SSE stream for an established session (Mcp-Session-Id header required). | | DELETE | /mcp | Terminate a session. |

Sessions are stateful: the first initialize POST mints a session id (returned via the Mcp-Session-Id header) which subsequent requests reuse. Every session shares the same in-memory spec state as the legacy REST routes — a spec loaded via POST /api/sync (or the load_openapi_spec tool) is immediately visible to Streamable HTTP clients and vice-versa, and tool-driven spec loads still broadcast over the GET /mcp/stream SSE channel.

Connecting a modern MCP client

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('http://localhost:3001/mcp'));
const client = new Client({ name: 'my-client', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();          // all 16 tools
await client.callTool({ name: 'get_api_overview', arguments: {} });

await transport.close();

Legacy REST helper routes

These remain available for the web app and VS Code extension:

GET /health · POST /mcp/tools/list · POST /mcp/tools/call · POST /mcp/execute · GET /mcp/stream (SSE spec updates) · POST /api/sync · POST /api/proxy · GET /api/info · GET /api/endpoints · GET /docs

🧪 Testing 🧪

The project ships with a Vitest suite covering the OpenAPI parser, all 16 tool handlers, and the HTTP server (including a real Streamable HTTP client handshake):

npm run build   # type-check + compile to dist/
npm test        # vitest run

🛠️ Tools 🛠️

This server exposes a rich set of tools for deep interaction with OpenAPI specifications. Once the server is running, your AI assistant can leverage the following capabilities:

| Tool Name | Description | | --- | --- | | load_openapi_spec | Load and parse an OpenAPI specification from text, URL, or file content. | | get_api_overview | Get a comprehensive overview of the loaded API including basic info, statistics, and analytics. | | search_endpoints | Search and filter API endpoints with advanced criteria. | | get_endpoint_details | Get detailed information about a specific endpoint. | | generate_code_examples| Generate code examples for specific endpoints in various languages. | | get_api_analytics | Get comprehensive analytics and insights about the API. | | validate_api_design | Analyze the API design and provide recommendations for improvements. | | export_documentation | Export API documentation in various formats. | | search_request_body_properties | Deep search through request body schemas to find specific properties, types, or patterns. | | generate_typescript_types | Generate TypeScript interfaces and types from OpenAPI schemas. | | find_schema_dependencies | Trace and analyze schema references and dependencies throughout the API. | | validate_request_examples | Validate that request/response examples match their schemas. | | extract_auth_patterns | Analyze and extract authentication and authorization patterns across the API. | | generate_mock_data | Generate realistic mock data based on OpenAPI schemas. | | find_unused_schemas | Identify schemas that are defined but never referenced in the API. | | analyze_schema_evolution | Analyze how schemas might evolve and suggest versioning strategies. |

Example Workflow

1. Use load_openapi_spec with the content of your OpenAPI file.
2. Use search_endpoints to find endpoints related to "users".
3. Use get_endpoint_details on a specific user endpoint.
4. Use generate_code_examples to get a Python snippet for that endpoint.