Agent Skill 核验档案

Openapi To MCP

openapi-to-mcp 是一套使用 mcp-use TypeScript SDK 将 OpenAPI 3.x 或 Swagger 2.0 REST API 文档转换为 MCP 服务器的流程。它将文档中的每个操作映射为可供大模型调用的 MCP 工具。

适用任务

将本地文件、URL 或聊天中粘贴的 OpenAPI/Swagger 文档获取并解引用为单个 JSON 文件
按全部操作、标签或指定操作筛选端点，并将每个操作注册为一个 MCP 工具
从 OpenAPI 参数与请求体生成 Zod 模式，并为工具接入 API Key、Bearer、Basic 或 OAuth Bearer 认证
启动开发服务器后，用 mcp-use client 列出、描述和调用工具，并在 Inspector 聊天中验证工具发现与调用

输入

OpenAPI 3.x 文档或 Swagger 2.0 文档
文档文件路径、URL，或粘贴到聊天中的文档内容
API 服务器基础 URL
文档声明的认证方案及对应环境变量名称
待暴露的全部操作、指定标签或手选操作列表

输出

使用 mcp-use TypeScript SDK 构建的 MCP 服务器
由 API 操作映射得到的 MCP 工具
与 OpenAPI 参数和请求体对应的 Zod 工具模式
解引用后的 OpenAPI JSON 文件
用于说明所需环境变量的 .env.example 文件

限制与检查

仅支持流式 HTTP 传输，不应改用 stdio。
认证密钥应来自环境变量；文档只声明认证方案，不包含密钥。
当解引用后仍存在循环引用的 `$ref` 时，应将其作为 Zod 中的不透明对象类型处理。
大型文档应先确认暴露范围；来源建议操作数超过约 30 个时询问筛选方式。
检查解引用后的文件不含 `$ref`；如仍存在，确认其是否为循环引用并按不透明对象处理。
运行开发服务器后，使用 `mcp-use client` 连接 MCP 端点，并确认 `tools list` 能列出预期工具。
对至少一个工具执行 `tools describe` 和 `tools call`，确认其模式、参数传递与响应处理正确。
在 Inspector 聊天中分别测试明确指定工具的调用和自然语言发现工具的调用。

项目详情

0