openapi-to -converter

This MCP server converter takes an OpenAPI 3.0 specification and generates an MCP server instance that can be exposed via various transports. It is TypeScript-based and emphasizes type safety, allowing you to rely on strong typings for request and response shapes when mapping OpenAPI operations to MCP tool calls. Typical usage involves loading an OpenAPI document, creating an OpenApiMCPSeverConverter, and obtaining an MCP server from it to connect to a transport like stdio, SSE, or HTTP.

Key capabilities include:

• Automated conversion of OpenAPI operations into MCP endpoints with parameter and response mapping aligned to the OpenAPI spec.
• Type-safe generation of server interfaces so tool calls, parameters, and results are validated at compile time.
• Built-in proxies for request/response handling, mapping OpenAPI request bodies, query parameters, and path parameters to the MCP tool call interface. To use it in your project, import OpenApiMCPSeverConverter, provide the OpenAPI document and options (e.g., timeout and security settings), then obtain the generated server and connect it to a transport (stdio, SSE, or HTTP) to start handling MCP sessions.

Prerequisites:

• Node.js 18+
• npm (comes with Node.js)

1. Install the converter package from npm:

   npm install openapi-mcp-converter

2. Prepare your OpenAPI document (openapi.json) and place it in a known location.

3. Build or run the TypeScript source if you are developing the converter locally:

   npm run build

4. Run a small example script that loads the OpenAPI document, creates the converter, and starts a local MCP server transport (example usage will depend on how you expose the server in your project).

Note: Since the converter is provided as a library, you typically integrate it into your own server entry point rather than starting a standalone executable. The steps above guide you from installation to starting a server via your own startup script.

Tips and common considerations:

• Ensure your OpenAPI document is valid OpenAPI 3.0 to maximize automatic mapping accuracy.
• Leverage the TypeScript types produced by the converter to catch mismatches between API operations and MCP tool calls at compile time.
• When running in production, provide a secure transport layer (HTTPS, authenticated endpoints) for any HTTP-based MCP transports.
• If you need to customize parameter mappings or security, adjust the converter options (e.g., timeout, security key) accordingly.
• Common issues include mismatched parameter names between OpenAPI and MCP tool calls; use the generated types to verify consistency.
• The documentation assumes a local development setup; adapt the openapi.json path and environment variables to match your deployment environment.