What is Openapi To Mcp Converter

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

Use cases

Use cases include converting existing OpenAPI specifications into MCP servers for better API management, rapid prototyping of services, and facilitating communication between different services in a microservices architecture.

How to use

To use openapi-to-mcp-converter, first install the package using npm. Then, import the converter in your TypeScript code, load your OpenAPI document, and create an MCP server instance. Finally, connect the server to a transport layer and run it.

Key features

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

Where to use

openapi-to-mcp-converter can be used in software development environments where API specifications need to be integrated into applications using the Model Context Protocol, particularly in microservices and cloud-native architectures.

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