OpenAPI to MCP

Converts an OpenAPI specification file into an MCP server that can be used to interact with existing web APIs described by OpenAPI specifications.

This allows AI agents or other clients that understand MCP to interact with existing web APIs described by OpenAPI specifications.

Features

• Automatic conversion of OpenAPI operations to MCP tools
• Support for both modern Streamable HTTP and legacy SSE transports
• Automatic API base URL detection from OpenAPI specs
• Support for OpenAPI/Swagger 2.0 and OpenAPI 3.x
• Binary response handling
• Graceful shutdown handling
• Detailed logging for debugging

Prerequisites

• Node.js (v16 or later recommended)

Installation

1. Clone the repository (or ensure you have the `openapi-to-mcp` directory).

2. Navigate to the `openapi-to-mcp` directory:

cd openapi-to-mcp

3. Install dependencies:

npm install

Build

Compile the TypeScript code to JavaScript:

npm run build

This will create a `dist` directory with the compiled JavaScript files.

Usage

Start the server using the `start` script, providing the path to your OpenAPI specification file using the `-f` or `--file` option:

# Example using a local petstore.yaml file
npm start -- serve -f ./path/to/your/openapi.json

# Example with different port and host
npm start -- serve --file ./specs/petstore.json --port 9090 --host 0.0.0.0

• Replace `./path/to/your/openapi.json` with the actual path to your OpenAPI file.
• The server will parse the file, adapt the API operations to MCP functions, and start listening.
• It will print the available endpoints for both modern and legacy MCP connections.

Connecting as an MCP Client

Modern Connection (Recommended)

The server provides a modern Streamable HTTP transport managed by the MCP SDK. This is the recommended way to connect to the server.

Legacy SSE Connection

For backwards compatibility, the server also supports SSE connections:

1. Connect to the SSE endpoint (e.g., `http://localhost:8080/sse`).

2. You will receive an `mcp-hello` event upon connection.

3. To call a function, send an MCP `function_call` message via a POST request to the `/messages` endpoint with a `sessionId` query parameter matching your SSE connection ID.

Example POST to `/messages?sessionId=`:

Headers:

Content-Type: application/json

Body:

{
     "type": "function_call",
     "id": "call-123",
     "function_name": "get_pets_by_status",
     "parameters": {
       "status": "available"
     }
   }

4. The server will execute the corresponding API call and send back a `function_return` or `error` event over the established SSE connection.

Development

Run in development mode with auto-recompilation:

# Make sure to provide the OpenAPI file path
npm run dev -- -f ./path/to/your/openapi.yaml

Current Limitations

• Authentication: Not implemented
• Schema Validation: While basic schema validation is in place, some complex OpenAPI schema features (discriminators, complex compositions) might not be fully supported.
• Testing: No automated tests are currently included.
• Documentation: Individual tool documentation could be improved with more examples and parameter descriptions.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.