星战科技xingzhan.cloud
返回市场
开放API-MCP生成器

开放API-MCP生成器

作者：harsha-iiiv466 星标更新：2025-10-01
安装使用来源：spider==github.com

项目介绍

OpenAPI到MCP生成器（openapi-mcp-generator）

npm版本 许可证：MIT GitHub仓库

从OpenAPI规范生成模型上下文协议（MCP）服务器。

此CLI工具自动化生成与MCP兼容的服务器，这些服务器代理请求到现有的REST API——使AI代理和其他MCP客户端能够无缝地使用您选择的传输方法与您的API进行交互。

✨ 特性

  • 🔧 支持OpenAPI 3.0：将任何OpenAPI 3.0+规范转换为与MCP兼容的服务器。
  • 🔁 代理行为：在验证请求结构和安全性的同时，将调用代理到原始REST API。
  • 🔐 身份验证支持：通过环境变量支持API密钥、Bearer令牌、基本认证和OAuth2。
  • 🧪 Zod验证：自动从OpenAPI定义生成Zod模式以进行运行时输入验证。
  • ⚙️ 类型化服务器：完全类型化的可维护TypeScript代码输出。
  • 🔌 多种传输方式：通过stdio、Hono的SSE或StreamableHTTP进行通信。
  • 🧰 项目框架：生成一个完整的Node.js项目，包括tsconfig.json、package.json和入口点。
  • 🧪 内置HTML测试客户端：在浏览器中可视化测试API交互（适用于基于Web的传输）。

🚀 安装

npm install -g openapi-mcp-generator

您也可以使用yarn global add openapi-mcp-generator或pnpm add -g openapi-mcp-generator

🛠 使用

# 生成MCP服务器（stdio）
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir

# 生成具有SSE的MCP Web服务器
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000

# 生成MCP StreamableHTTP服务器
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=streamable-http --port=3000

CLI选项

选项别名描述默认值
--input-iOpenAPI规范（YAML或JSON）的路径或URL必需
--output-o输出生成的MCP项目的目录必需
--server-name-nMCP服务器名称（package.json:name）OpenAPI标题或mcp-api-server
--server-version-vMCP服务器版本（package.json:version）OpenAPI版本或1.0.0
--base-url-bAPI请求的基础URL。如果OpenAPI中的servers缺失或不明确，则需要指定。如果可能则自动检测
--transport-t传输模式："stdio"（默认）、"web"或"streamable-http""stdio"
--port-p基于Web的传输端口3000
--default-include对于x-mcp过滤，默认行为。接受true或false（大小写不敏感）。true = 默认包含，false = 默认排除。true
--force在没有确认的情况下覆盖输出目录中的现有文件false

📦 程序化API

您还可以在Node.js应用程序中程序化地使用此包：

import { getToolsFromOpenApi } from 'openapi-mcp-generator';

// 从OpenAPI规范提取MCP工具定义
const tools = await getToolsFromOpenApi('./petstore.json');

// 带有选项
const filteredTools = await getToolsFromOpenApi('https://example.com/api-spec.json', {
  baseUrl: 'https://api.example.com',
  dereference: true,
  excludeOperationIds: ['deletePet'],
  filterFn: (tool) => tool.method.toLowerCase() === 'get',
});

有关程序化API的完整文档，请参阅PROGRAMMATIC_API.md。

🧱 项目结构

生成的项目包括：

<output_directory>/
├── .gitignore
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│   ├── index.ts
│   └── [transport-specific-files]
└── public/          # 用于基于Web的传输
    └── index.html   # 测试客户端

核心依赖项：

  • @modelcontextprotocol/sdk - MCP协议实现
  • axios - API请求的HTTP客户端
  • zod - 运行时验证
  • json-schema-to-zod - 将JSON Schema转换为Zod
  • 传输特定依赖项（Hono、uuid等）

📡 传输模式

Stdio（默认）

通过标准输入/输出与MCP客户端通信。适合本地开发或与LLM工具集成。

带SSE的Web服务器

启动一个完全功能的HTTP服务器，具有：

  • 用于双向消息传递的服务器发送事件（SSE）
  • 客户端→服务器通信的REST端点
  • 浏览器中的测试客户端UI
  • 多连接支持
  • 使用轻量级Hono框架构建

StreamableHTTP

实现MCP StreamableHTTP传输，提供：

  • 使用HTTP POST请求的状态化JSON-RPC
  • 使用HTTP头管理会话
  • 正确的HTTP响应状态码
  • 内置错误处理
  • 与MCP StreamableHTTPClientTransport兼容
  • 浏览器中的测试客户端UI
  • 使用轻量级Hono框架构建

传输比较

功能stdioweb (SSE)streamable-http
协议通过stdio的JSON-RPC通过SSE的JSON-RPC通过HTTP的JSON-RPC
连接持久持久请求/响应
双向通信是是是（状态化）
多个客户端否是是
浏览器兼容性否是是
防火墙友好否是是
负载均衡否有限是
状态码否有限完整HTTP代码
标头否有限完整HTTP标头
测试客户端否是是

🔐 认证的环境变量

在环境中配置认证凭据：

认证类型变量格式
API密钥API_KEY_<SCHEME_NAME>
BearerBEARER_TOKEN_<SCHEME_NAME>
基本认证BASIC_USERNAME_<SCHEME_NAME>, BASIC_PASSWORD_<SCHEME_NAME>
OAuth2OAUTH_CLIENT_ID_<SCHEME_NAME>, OAUTH_CLIENT_SECRET_<SCHEME_NAME>, OAUTH_SCOPES_<SCHEME_NAME>

🔎 使用OpenAPI扩展过滤端点

您可以使用供应商扩展标志x-mcp控制哪些操作作为MCP工具公开。此扩展在根、路径和操作级别受支持。默认情况下，端点被包含，除非显式排除。

  • 扩展：x-mcp: true | false
  • 默认：true（默认包含）
  • 优先级：操作 > 路径 > 根（第一个非未定义的获胜）
  • CLI选项：--default-include false以更改默认设置为默认排除

示例：

# 可选的根级默认
x-mcp: true

paths:
  /pets:
    x-mcp: false # 排除/pets下的所有操作
    get:
      x-mcp: true # 无论如何包含此操作

  /users/{id}:
    get:
      # 没有x-mcp -> 默认包含

这使用标准的OpenAPI扩展（x-...字段）。详情请参阅OpenAPI扩展指南。

注意：x-mcp必须是布尔值或字符串"true"/"false"（大小写不敏感）。其他值将被忽略，以优先级更高或默认行为为准。

▶️ 运行生成的服务器

cd path/to/output/dir
npm install

# 在stdio模式下运行
npm start

# 在Web服务器模式下运行
npm run start:web

# 在StreamableHTTP模式下运行
npm run start:http

测试基于Web的服务器

对于基于Web和StreamableHTTP的传输，会自动生成一个基于浏览器的测试客户端：

  1. 使用适当的命令启动服务器
  2. 在浏览器中打开http://localhost:<port>
  3. 使用测试客户端与您的MCP服务器进行交互

⚠️ 要求

  • Node.js v20或更高版本

Star历史

<a href="https://www.star-history.com/#harsha-iiiv/openapi-mcp-generator&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=harsha--iiiv/openapi-mcp-generator&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=harsha-iiiv/openapi-mcp-generator&type=Date" /> <img alt="Star历史图表" src="https://api.star-history.com/svg?repos=harsha-iiiv/openapi-mcp-generator&type=Date" /> </picture> </a>

🤝 贡献

欢迎贡献！

  1. 分叉仓库
  2. 创建特性分支：git checkout -b feature/amazing-feature
  3. 运行npm run format.write以格式化您的代码
  4. 提交您的更改：git commit -m "添加惊人的功能"
  5. 推送并打开PR

📌 仓库：github.com/harsha-iiiv/openapi-mcp-generator

📄 许可证

MIT许可证——详见LICENSE。