OpenAPI到MCP生成器（OpenAPI-MCP生成器）
生成 模型上下文协议（MCP） OpenAPI规范的服务器。
此CLI工具自动生成与MCP兼容的服务器，这些服务器将请求代理到现有的REST API，使AI代理和其他MCP客户端能够使用您选择的传输方法与您的API无缝交互。
______________________________________________________________________
✨ 特性
- 🔧 OpenAPI 3.0支持：将任何OpenAPI 3.0+规范转换为MCP兼容服务器。
- 🔁 代理行为：在验证请求结构和安全性时代理对原始REST API的调用。
- 🔐 身份验证支持：通过环境变量支持API密钥、承载令牌、基本身份验证和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
______________________________________________________________________
🛠 用法
# Generate an MCP server (stdio)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir
# Generate an MCP web server with SSE
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000
# Generate an MCP StreamableHTTP server
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=streamable-http --port=3000CLI选项
| 选项 | 别名 | 描述 | 默认值 |
|---|---|---|---|
--input | -i | OpenAPI规范的路径或URL（YAML或JSON） | 必需 |
--output | -o | 输出生成的MCP项目的目录 | 必需 |
--server-name | -n | MCP服务器的名称(package.json:name) | OpenAPI标题或 mcp-api-server |
--server-version | -v | MCP服务器的版本(package.json:version) | OpenAPI版本或 1.0.0 |
--base-url | -b | API请求的基本URL。如果OpenAPI需要 servers 缺失或含糊不清。 | 如果可能，自动检测 |
--transport | -t | 运输方式： "stdio" （默认）， "web"，或 "streamable-http" | "stdio" |
--port | -p | 基于网络的传输端口 | 3000 |
--default-include | x-mcp筛选的默认行为。接受 true 或 false 不区分大小写 true =默认情况下包含， false =默认情况下排除。 | true | |
--force | 未经确认覆盖输出目录中的现有文件 | false |
📦 程序化API
您还可以在Node.js应用程序中以编程方式使用此包：
import { getToolsFromOpenApi } from 'openapi-mcp-generator';
// Extract MCP tool definitions from an OpenAPI spec
const tools = await getToolsFromOpenApi('./petstore.json');
// With options
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的完整文档，请参阅 编程\_ API.md.
______________________________________________________________________
🧱 项目结构
生成的项目包括：
/
├── .gitignore
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│ ├── index.ts
│ └── [transport-specific-files]
└── public/ # For web-based transports
└── index.html # Test client核心依赖关系：
@modelcontextprotocol/sdk-MCP协议实现axios-API请求的HTTP客户端zod-运行时验证json-schema-to-zod-将JSON模式转换为Zod- 特定运输部门（Hono、uuid等）
______________________________________________________________________
📡 运输方式
标准（默认）
通过标准输入/输出与MCP客户端通信。非常适合本地开发或与LLM工具集成。
带SSE的Web服务器
启动一个功能齐全的HTTP服务器，包括：
- 用于双向消息传递的服务器发送事件（SSE）
- 客户端的REST端点→ 服务器通信
- 浏览器内测试客户端UI
- 多连接支持
- 采用轻量级Hono框架构建
流式HTTP
实现MCP StreamableHTTP传输，该传输提供：
- 基于HTTP POST请求的有状态JSON-RPC
- 使用HTTP标头的会话管理
- 正确的HTTP响应状态代码
- 内置错误处理
- 与MCP StreamableHTTPClientTransport的兼容性
- 浏览器内测试客户端UI
- 采用轻量级Hono框架构建
运输比较
| 功能 | stdio | web（SSE） | 可流式传输http |
|---|---|---|---|
| 协议 | stdio上的JSON-RPC | SSE上的JSON-RTC | HTTP上的JSON-RSC |
| 连接 | 持久 | 持久 | 请求/响应 |
| 双向 | 是 | 是 | 有（有状态） |
| 多个客户端 | 否 | 是 | 是 |
| 浏览器兼容 | 否 | 是 | 是 |
| 防火墙友好 | 否 | 是 | 是 |
| 负载平衡 | 否 | 有限 | 是 |
| 状态代码 | 否 | 有限 | 完整HTTP代码 |
| 标头 | 否 | 有限 | 完整HTTP标头 |
| 测试客户端 | 否 | 是 | 是 |
______________________________________________________________________
🔐 身份验证的环境变量
在您的环境中配置身份验证凭据：
| 身份验证类型 | 变量格式 |
|---|---|
| API密钥 | API_KEY_ |
| 持票人 | BEARER_TOKEN_ |
| 基本身份验证 | BASIC_USERNAME_, BASIC_PASSWORD_ |
| OAuth2 | OAUTH_CLIENT_ID_, OAUTH_CLIENT_SECRET_, OAUTH_SCOPES_ |
______________________________________________________________________
🔎 使用OpenAPI扩展过滤端点
您可以使用供应商扩展标志控制哪些操作作为MCP工具公开 x-mcp。此扩展在根、路径和操作级别都受支持。默认情况下，除非明确排除，否则将包括端点。
- 扩展名：
x-mcp: true | false - 违约：
true（默认包含） - 优先级：操作>路径>根（第一个未定义的获胜）
- CLI选项：
--default-include false将默认值更改为默认排除
示例：
# Optional root-level default
x-mcp: true
paths:
/pets:
x-mcp: false # exclude all ops under /pets
get:
x-mcp: true # include this operation anyway
/users/{id}:
get:
# no x-mcp -> included by default这使用了标准的OpenAPI扩展（x-…字段）。请参阅 OpenAPI扩展指南 了解详情。
注： x-mcp 必须是布尔值或字符串 "true"/"false" 不区分大小写其他值会被忽略，以支持更高的优先级或默认行为。
______________________________________________________________________
▶️ 运行生成的服务器
cd path/to/output/dir
npm install
# Run in stdio mode
npm start
# Run in web server mode
npm run start:web
# Run in StreamableHTTP mode
npm run start:http测试基于Web的服务器
对于web和StreamableHTTP传输，会自动生成基于浏览器的测试客户端：
- 使用适当的命令启动服务器
- 打开浏览器 `http://localhost:
`
- 使用测试客户端与MCP服务器交互
______________________________________________________________________
⚠️ 需求
- Node.js v20或更高版本
______________________________________________________________________
明星历史
🤝 贡献
欢迎投稿！
- 分叉回购
- 创建要素分支：
git checkout -b feature/amazing-feature - 跑
npm run format.write格式化代码 - 提交您的更改：
git commit -m "Add amazing feature" - 推送并打开PR
📌 存储库：
______________________________________________________________________
📄 许可证
MIT许可证——见 许可证 了解全部细节。