What is React Openapi Mcp Converter

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

Use cases

Use cases include generating an MCP server from existing OpenAPI specifications, facilitating API testing and development, and enabling seamless integration of APIs into applications using the MCP protocol.

How to use

To use react-openapi-mcp-converter, first install the package via npm. Then, import the OpenApiMCPServerConverter, load your OpenAPI document, and create an MCP server instance. Finally, connect the server using a transport method like StdioServerTransport to 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

react-openapi-mcp-converter can be used in various fields such as web development, API management, and microservices architecture, where integration with the MCP framework is required.

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