What is Openapi Mcp Converter

openapi-mcp-converter is a tool designed to automatically convert OpenAPI specifications into a Model Context Protocol (MCP) server instance, facilitating the integration of APIs with MCP.

Use cases

Use cases include converting existing OpenAPI specifications to run as MCP servers, facilitating API testing and development, and enabling seamless communication between different services in a microservices architecture.

How to use

To use openapi-mcp-converter, first install the package via npm. Then, import the converter in your TypeScript code, load your OpenAPI document, and run the server using the provided transport method.

Key features

Key features include automated conversion of OpenAPI 3.0 specifications, strong type safety through TypeScript, and automatic handling of request parameter mapping.

Where to use

openapi-mcp-converter can be used in various fields such as API development, microservices architecture, and any environment where OpenAPI specifications need to be integrated with MCP.

OpenAPI to MCP Server Converter

A tool for automatically converting OpenAPI specifications into Model Context Protocol (MCP) server instance

Features

• 🚀 Automated Conversion: Auto-parses OpenAPI 3.0 specifications
• 🛠 Type Safety: TypeScript-based strong type validation
• 🔄 Request Proxy: Automatically handles tool call parameter mapping

Quick Start

Prerequisites

• Node.js 18+
• TypeScript 5.x

Basic Usage

Install the package:

npm install openapi-mcp-converter

Create a server instance:

import fs from 'fs';
import { OpenApiMCPSeverConverter } from '../index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import path from 'path';
import { fileURLToPath } from 'url';

const openApiDoc = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), 'openapi.json'), 'utf8'));

const converter = new OpenApiMCPSeverConverter(openApiDoc, { timeout: 100000, security: { apiKey: 'my-api-key' } });
const server = converter.getServer();

Run a local stdio MCP server:

async function runServer() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.log("GitHub MCP Server running on stdio");
}

runServer().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

Run a local SSE Server:

const app = express();
let transport = null;

app.get("/sse", async (req, res) => {
  console.log("SSE connection opened");
  console.log("Request Headers:", req?.headers);
  console.log("Request Query:", req?.query);
  server.onclose = async () => {
    await server.close();
  };
  transport = new SSEServerTransport("/messages", res);
  await server.connect(transport);
  return;
});

app.post("/messages", async (req, res) => {
  const sessionId = req.query.sessionId as string;
  if (!sessionId) {
      throw new Error("sessionId query parameter is required");
  }
  await transport.handlePostMessage(req, res);
  return;
});

app.listen(8080, () => {
  console.log('MCP Server running on port 8080');
});

Run a local Streamable HTTP Server:

const app = express();
app.use(express.json());

const transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};

app.post('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  let transport: StreamableHTTPServerTransport;

  if (sessionId && transports[sessionId]) {
    transport = transports[sessionId];
  } else if (!sessionId && isInitializeRequest(req.body)) {
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (sessionId) => {
        transports[sessionId] = transport;
      }
    });
    transport.onclose = () => {
      if (transport.sessionId) {
        delete transports[transport.sessionId];
      }
    };
    await server.connect(transport);
  } else {
    res.status(400).json({
      jsonrpc: '2.0',
      error: {
        code: -32000,
        message: 'Bad Request: No valid session ID provided',
      },
      id: null,
    });
    return;
  }

  await transport.handleRequest(req, res, req.body);
});

const handleSessionRequest = async (req: express.Request, res: express.Response) => {
  const sessionId = req.headers['mcp-session-id'] as string | undefined;
  if (!sessionId || !transports[sessionId]) {
    res.status(400).send('Invalid or missing session ID');
    return;
  }
  
  const transport = transports[sessionId];
  await transport.handleRequest(req, res);
};

app.get('/mcp', handleSessionRequest);

app.delete('/mcp', handleSessionRequest);

app.listen(3000);

Run Examples

npm run test  # Execute sample test cases

Development Guide

Project Structure

/openapi-to-mcp
├── dist/            # Compiled output
├── src/             # Source code
│   ├── example/     # Example configurations
│   └── index.ts     # Core implementation
├── package.json
└── tsconfig.json

Build Commands

npm run build    # Production build
npm run watch    # Development mode watch