🚀 MCP OpenAPI变压器
一种模型上下文协议（MCP）服务器，通过读取OpenAPI规范动态地将REST API端点公开为MCP工具。
📋 特性
- 动态工具生成：从OpenAPI规范端点自动创建MCP工具
- 完全支持OpenAPI：解析路径、参数、请求正文和描述
- HTTP方法支持：处理GET、POST、PUT、DELETE和PATCH操作
- 扁平化参数：请求体属性被扁平化为顶级工具参数，以获得更好的用户体验
- 架构引用解析：处理内联模式和
$ref对组件模式的引用 - 参数处理：支持路径参数、查询参数和扁平化请求正文字段
- 错误处理：针对API调用的全面错误报告
🏗️ 建筑
┌─────────────┐
│ MCP │
│ Client │
└──────┬──────┘
│ MCP Protocol
▼
┌─────────────────────────────┐
│ MCP OpenAPI Transformer │
│ ┌───────────────────────┐ │
│ │ Fetch OpenAPI Spec │ │
│ └───────────┬───────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ Generate MCP Tools │ │
│ └───────────┬───────────┘ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ Execute API Calls │ │
│ └───────────────────────┘ │
└──────────────┬──────────────┘
│ HTTP Requests
▼
┌──────────┐
│ API │
│ Server │
└──────────┘🛠️ 配置
服务器需要两个环境变量：
BASE_URL：要调用的API的基本URL（例如。，https://api.example.com)DOC_URL：OpenAPI规范JSON的URL（例如。，https://api.example.com/openapi.json)
🚀 用法
建筑
unset ARGV0 && cargo build --release跑步
BASE_URL="https://api.example.com" \
DOC_URL="https://api.example.com/openapi.json" \
./target/release/mcp-openapi-transformer公共API示例
以Petstore API为例：
BASE_URL="https://petstore3.swagger.io/api/v3" \
DOC_URL="https://petstore3.swagger.io/api/v3/openapi.json" \
./target/release/mcp-openapi-transformer🔧 运作原理
- 初始化：服务器从以下位置获取并解析OpenAPI规范
DOC_URL - 工具生成OpenAPI规范中的每个端点都成为MCP工具：
- 工具名称格式： {method}_{path} （例如。， get_users_id, post_orders) - 描述：摘自操作总结或描述 - 参数：由路径参数、查询参数和请求体生成
- 执行：当调用工具时：
- 路径参数被替换到URL中 - 查询参数已添加到请求中 - 请求正文（如果存在）以JSON格式发送 - 响应返回给MCP客户端
📝 示例工具
给定此OpenAPI端点：
{
"paths": {
"/users/{id}": {
"get": {
"summary": "Get user by ID",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": { "type": "string" }
}
]
}
}
}
}服务器生成此MCP工具：
- 名字:
get_users_id - 描述：“按ID获取用户”
- 参数:
{
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": ["id"]
}🎯 参数展平
请求正文参数为 自动变平 将其转换为顶级工具参数，以获得更好的用户体验。
之前（包装）
{
"properties": {
"body": {
"type": "object",
"description": "Request body"
}
}
}之后（压扁）✅
{
"properties": {
"name": { "type": "string" },
"photoUrls": { "type": "array" },
"status": { "type": "string" },
"category": { "type": "string" }
},
"required": ["name", "photoUrls"]
}益处
- ✨ 必填字段清晰可见
- ✨ 每个参数的类型信息
- ✨ 更好的IDE自动补全支持
- ✨ 改进了验证和文件编制
服务器自动执行以下操作：
- 解析架构引用(
$ref: "#/components/schemas/...") - 从请求正文架构中提取所有属性
- 将它们添加为具有适当类型的单独参数
- 适当标记必填字段
- 在执行过程中自动重建请求正文
🧪 测试
运行参数压扁试验
使用公共Petstore API进行测试：
python3 test_flattening.py这将：
- ✅ 连接到Petstore API
- ✅ 验证否
bodyPOST端点中的参数 - ✅ 确认参数已正确展平
- ✅ 使用扁平化参数测试真实的API调用
- ✅ 显示详细的测试结果
运行E2E测试
确保API正在上运行 localhost:5000那么：
python3 test.py这将：
- ✅ 启动MCP服务器
- ✅ 初始化MCP会话（通过适当的握手）
- ✅ 列出OpenAPI规范中的所有可用工具
- ✅ 查找与用餐相关的工具
- ✅ 调用工具从昨天开始吃饭
- ✅ 以漂亮的格式显示结果
使用不同的API进行测试
编辑顶部的URL test.py:
BASE_URL = "http://your-api.com/v1"
DOC_URL = "http://your-api.com/openapi.json"手动测试
手动启动服务器：
BASE_URL="http://localhost:5000/api/v1" \
DOC_URL="http://localhost:5000/api-docs.json" \
RUST_LOG="info" \
./target/release/mcp-openapi-transformer然后通过stdin发送JSON-RPC消息：
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_meals","arguments":{"date":"2025-11-21"}}}🔍 日志记录
设置 RUST_LOG 用于控制日志记录的环境变量：
RUST_LOG=info BASE_URL="..." DOC_URL="..." ./target/release/mcp-openapi-transformer水平： trace, debug, info, warn, error
📦 依赖项
- mcp-sdk：Rust的模型上下文协议SDK
- openapiv3：OpenAPI v3规范解析器
- 请求：用于进行API调用的HTTP客户端
- 东京：异步运行时
- Serde/Serde JSON：JSON序列化
- 无论如何：错误处理
- 追踪：日志框架
🤝 贡献
欢迎投稿！这是一个可以扩展的起点：
- \[\]支持身份验证（API密钥、OAuth等）
- \[\]自定义标头配置
- \[\]响应模式验证
- \[\]OpenAPI v2（Swagger）支持
- \[\]文件上传/下载支持
- \[\]Webhook处理
- \[\]速率限制
📄 许可证
MIT许可证-随意使用和修改！
🐛 已知限制
- 目前仅支持JSON格式的OpenAPI v3.x规范
- 参考分辨率(
$ref)有限 - 复杂的参数模式被简化为基本类型
- 还没有身份验证支持（如果需要，手动添加标头）
______________________________________________________________________
内置于🦀 Rust和MCP SDK