星战科技xingzhan.cloud
返回市场
开放API到MCP

开放API到MCP

作者：agentic-community7 星标更新：2025-07-21
安装使用来源：spider==github.com

项目介绍

OpenAPI 转 MCP 转换器

License Python MCP Code style: black

将您的 OpenAPI 规范转换为生产就绪的 Model Context Protocol (MCP) 服务器，并通过 AI 增强和验证

OpenAPI 转 MCP 是一个强大的工具，可以自动将 OpenAPI/Swagger 规范转换为完全功能的 MCP 服务器。它利用大型语言模型（LLMs）来分析、增强并生成与 MCP 兼容的服务器实现，基于您现有的 API 文档。

[!CAUTION] 本仓库提供的示例仅用于实验和教育目的。它们展示了概念和技术，但不建议直接在生产环境中使用。确保有 Amazon Bedrock 安全措施以防止 提示注入。

目录

新特性

v0.1.0

  • 初始发布，包含核心功能
  • 支持 OpenAPI 3.0 和 Swagger 2.0 规范
  • AI 驱动的评估和增强
  • 自动 MCP 服务器和客户端生成
  • 支持 Amazon Bedrock 和 Anthropic Claude
  • 包含使用跟踪的全面评估报告

为什么选择此解决方案

随着企业向 AI 就绪转型，确保其 API 也具备 AI 就绪性是关键的一环。为人类消费编写的 API 规范往往缺乏大型语言模型运行所需的细节水平。虽然人类开发者可以依赖领域专业知识和部落知识来填补文档中的空白，但 LLM 可能会幻想缺失的信息，导致 AI 代理无法可靠地在正确的时间调用正确的工具。

影响 AI 就绪性的常见问题包括：

  • 缺少或模糊的描述：缺乏详细解释其目的和行为的端点和参数
  • 未定义的参数约束：没有明确定义范围、格式或验证规则的参数
  • 不完整的错误处理：缺少错误响应和边缘情况的文档
  • 不清楚的数据关系：缺乏关于不同 API 资源如何相互关联的明确文档
  • 缺少分页细节：处理大量数据集的 API 但没有清楚地记录分页机制
  • 模糊的过滤选项：缺乏全面文档的查询参数用于过滤
  • 隐含的业务逻辑：关于工作流和使用模式的假设没有明确记录

当这些不完整的 API 规范直接转换为 MCP 服务器时，生成的工具规范也会继承同样的缺陷。这会导致不可预测的行为，最坏的情况可能是完全失效。OpenAPI 转 MCP 转换器通过使用 AI 分析、评估和增强您的 API 规范，然后生成 MCP 服务器，解决了这一差距，确保它们符合可靠的 AI 代理操作所需的质量标准。

架构

OpenAPI 转 MCP 转换器遵循多阶段管道架构：

graph TD
    A[OpenAPI Spec] --> B[Specification Loader]
    B --> C[AI-Powered Evaluator]
    C --> D{Quality Check}
    D -->|Pass| E[MCP Generator]
    D -->|Fail| F[Enhancement Suggestions]
    E --> G[MCP Server]
    E --> H[MCP Client]
    F --> I[Enhanced Spec]
    
    J[LLM Provider] --> C
    J --> E
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#9f9,stroke:#333,stroke-width:2px
    style H fill:#9f9,stroke:#333,stroke-width:2px

关键组件

  1. 规范加载器：从文件或 URL 加载和验证 OpenAPI/Swagger 规范
  2. AI 驱动的评估器：使用 LLM 分析 API 的质量、完整性和 AI 就绪性
  3. 增强引擎：提供可操作的建议以改进您的 API 规范
  4. MCP 生成器：创建生产就绪的 MCP 服务器和客户端实现
  5. 输出管理器：以结构化格式组织所有生成的文件和报告

特性

核心特性

OpenAPI 转 MCP 转换器提供了现有 API 文档与 Model Context Protocol 生态系统之间的无缝桥梁。只需一个命令，即可将任何 OpenAPI 或 Swagger 规范转换为生产就绪的 MCP 服务器。该工具利用先进的大型语言模型不仅进行转换，还分析和增强您的 API 规范，确保它们达到最高标准的 AI 集成。

每次转换都包括全面的评估报告，对您的 API 在多个维度上的评分，包括完整性、安全性以及 AI 就绪性。内置的质量阈值确保只有符合您标准的规范才会进入 MCP 生成，而详细的使用跟踪帮助您监控 LLM 令牌消耗及相关成本的所有操作。

评估能力

评估引擎对您的 OpenAPI 规范进行深入分析，跨多个维度检查。它通过识别可能影响可用性的缺失描述、示例和模式来检查 API 的完整性。安全性分析评估您的身份验证和授权方案，确保它们符合现代安全标准。

AI 就绪性评估特别有价值，确定您的 API 与 AI 代理和自动化工具的有效工作程度。内置的代码检查器识别规范问题和违反 OpenAPI 最佳实践，而操作分析提供每个端点的详细审查，包括参数文档、响应模式和错误处理。

生成特性

当您的规范满足质量阈值时，工具会生成一个完整的 MCP 实现包。这包括一个完全功能的基于 Python 的 MCP 服务器，实现了您的所有 API 操作作为 MCP 工具，以及一个用于测试实现的现成客户端。

生成的包包括所有必要的依赖文件、带有使用说明的综合文档以及详细的操作规范，描述了每项操作的 MCP 格式。一切都组织在一个干净的目录结构中，准备好部署或进一步定制。

示例结果及输出指南

想看看转换器生成的内容吗？查看我们的预生成示例结果和综合输出指南：

探索示例结果 - 查看我们样本太空任务 API 的真实评估报告、生成的 MCP 服务器等内容

阅读结果指南 - 了解转换器生成的每个文件，附带实际示例链接

这些资源展示了您从转换过程中可以期待的结果，并帮助您解读评估分数和生成的代码。

前提条件

  • Python 3.12 或更高版本
  • uv 包管理器
  • 有效 API 凭证，用于您选择的 LLM 提供商：
    • Amazon Bedrock 凭证（通过 Bedrock 访问 Claude）
    • Anthropic API 密钥（直接访问 Claude）

安装

安装 uv

首先，如果您还没有安装，请安装 uv 包管理器：

# 在 macOS 和 Linux 上
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows 上
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或者使用 pip
pip install uv

快速安装

  1. 克隆仓库：
git clone https://github.com/agentic-community/openapi-to-mcp.git
cd openapi-to-mcp
  1. 创建并激活虚拟环境：
# 创建虚拟环境
uv venv

# 激活在 macOS/Linux 上
source .venv/bin/activate

# 激活在 Windows 上
.venv\Scripts\activate
  1. 使用 uv 安装依赖：
uv pip install -e .
  1. 设置环境变量：
cp env.example .env
# 编辑 .env 文件，添加您的 API 凭证

开发安装

对于带有额外工具的开发：

uv pip install -e ".[dev]"

使用方法

基本用法

评估并转换本地 OpenAPI 规范：

# 对于简单示例
openapi-to-mcp examples/hello.yaml

# 对于更复杂的示例
openapi-to-mcp examples/sample_api.yaml

从 URL 评估规范：

openapi-to-mcp --url https://raw.githubusercontent.com/agentic-community/openapi-to-mcp/refs/heads/main/examples/hello.yaml

命令行选项

openapi-to-mcp [OPTIONS] [FILENAME]

参数：
  FILENAME              OpenAPI 规范文件（YAML 或 JSON）

选项：
  --url URL            从 URL 获取 OpenAPI 规范
  --output FILE        结果输出文件（默认：自动生成）
  --eval-only         仅运行评估，跳过 MCP 生成
  --verbose           启用详细日志
  --show-env          显示环境配置

环境变量

通过环境变量配置您的 LLM 提供商凭证：

对于 Amazon Bedrock：

export AWS_PROFILE=your-profile-name
export AWS_REGION=us-east-1

对于 Anthropic 直接访问：

export ANTHROPIC_API_KEY=your-api-key

注意：模型选择配置在 config/config.yml 中，而不是通过环境变量。

示例

示例 1：评估一个简单的 API

# 评估简单的 hello API 示例
openapi-to-mcp examples/hello.yaml

# 检查生成的输出
ls output/results_*_hello/

示例 2：评估一个复杂的 API

# 评估具有多个端点的更复杂示例 API
openapi-to-mcp examples/sample_api.yaml

# 此示例包括用户、产品等操作

示例 3：从 URL 评估

# 直接从 URL 评估
openapi-to-mcp --url https://raw.githubusercontent.com/agentic-community/openapi-to-mcp/refs/heads/main/examples/hello.yaml

示例 4：仅评估（不生成）

# 仅评估而不生成 MCP 服务器
openapi-to-mcp examples/sample_api.yaml --eval-only

示例 5：自定义输出位置

# 指定自定义输出文件
openapi-to-mcp examples/hello.yaml --output results/my-api-evaluation.json

使用存根服务器测试

此仓库包含使用 examples/sample_api.yaml 规范的完整端到端演示。示例 API 表示一个虚构的太空任务控制系统，具有飞船遥测、机组人员管理、任务操作和科学实验的端点。

为了便于测试而无需真实的后端，我们提供了：

  • 存根服务器 (examples/stub_server.py)，模拟后端 API 并返回模拟响应
  • 预生成的 MCP 服务器和客户端代码，立即可用于测试
  • 从 API 规范到工作的 MCP 工具的完整工作流程

预生成的结果

为了方便起见，我们在以下位置包含了评估 sample_api.yaml 的预生成结果：

examples/results/anthropic/sample_api/

此目录包含评估报告、增强规范和一个可运行的 MCP 服务器。参阅 RESULTS_GUIDE.md 以获取有关这些文件的详细信息。

运行端到端演示

按照以下步骤测试完整集成：

第一步：启动存根服务器

首先，运行模拟您的 API 后端的存根服务器：

# 在端口 9002 启动存根服务器
uv run examples/stub_server.py --port 9002

这创建了一个模拟后端，对 API 请求返回模拟数据。

第二步：设置认证令牌

导出 MCP 服务器所需的认证令牌：

export AUTH_TOKEN="your-secret-token"

第三步：启动 MCP 服务器

在新的终端中，导航到生成的 MCP 服务器目录并启动它：

# 导航到生成的服务器目录
cd examples/results/anthropic/sample_api/mcpserver/

# 在端口 9001 启动 MCP 服务器，指向端口 9002 的存根服务器
python server.py --port 9001 --base-url http://localhost:9002

第四步：使用 MCP 客户端测试

在另一个终端中，运行 MCP 客户端以与您的服务器交互：

# 从相同的 mcpserver 目录
python client.py --server-url http://localhost:9001/mcp

客户端将连接到 MCP 服务器并允许您测试所有可用工具。

示例工作流程

# 终端 1：启动存根服务器
uv run examples/stub_server.py --port 9002

# 终端 2：设置认证并启动 MCP 服务器
export AUTH_TOKEN="my-secret-token"
cd examples/results/anthropic/sample_api/mcpserver/
python server.py --port 9001 --base-url http://localhost:9002

# 终端 3：运行客户端
cd examples/results/anthropic/sample_api/mcpserver/
python client.py --server-url http://localhost:9001/mcp

配置

配置文件

该工具使用 config/config.yml 进行所有设置，包括模型选择：

# 模型配置 - 在这里指定您的模型
model: bedrock/us.anthropic.claude-3-5-sonnet-20241022-v2:0
# 或对于 Anthropic 直接访问：
# model: anthropic/claude-3-5-sonnet-20241022

# 模型参数
max_tokens: 8192
temperature: 0.0
timeout_seconds: 300

# 评估阈值
good_evaluation_threshold: 3.0
generate_mcp_threshold: 3.0

# 功能标志
debug: false

质量阈值

  • good_evaluation_threshold：良好评估的最低分数（默认：3/5）
  • generate_mcp_threshold：生成 MCP 服务器的最低分数（默认：3/5）

完整性和 AI 就绪性评分必须同时达到阈值才能生成 MCP 服务器。

输出结构

运行工具后，您会找到以下结构：

output/
└── results_YYYYMMDD_HHMMSS_<spec-name>_<provider>/
    ├── evaluation_YYYYMMDD_HHMMSS.json      # 详细的评估结果
    ├── summary_YYYYMMDD_HHMMSS.md           # 人类可读的摘要
    ├── usage_YYYYMMDD_HHMMSS.json           # 令牌使用和成本
    ├── enhanced_spec_YYYYMMDD_HHMMSS.yaml   # 增强的规范
    ├── original_spec_YYYYMMDD_HHMMSS.yaml   # 原始规范
    └── mcpserver/                            # 生成的 MCP 服务器（如果符合条件）
        ├── server.py                         # MCP 服务器实现
        ├── client.py                         # 测试用的 MCP 客户端
        ├── requirements.txt                  # Python 依赖
        ├── README.md                         # 使用文档
        └── tool_spec.txt                     # 工具规范

理解结果

OpenAPI 转 MCP 转换器生成全面的评估报告和 MCP 实现。为了帮助您理解和使用这些输出：

查看结果指南

此指南解释：

  • 每个生成文件包含的内容及其用途
  • 如何解读评估分数和质量指标
  • 理解分页和过滤支持指示符
  • 使用生成的 MCP 服务器和客户端代码
  • 链接到我们预生成样本 API 结果中的示例文件

examples/results/anthropic/sample_api/ 中的预生成结果作为参考实现，展示了高质量转换的样子。

AI 提供商

支持的提供商

  1. Amazon Bedrock

    • 模型：Claude 3.5 Sonnet、Claude 4 Sonnet
    • 地区支持：所有支持 Bedrock 的 AWS 地区
    • 定价：按令牌付费通过 AWS

  2. Anthropic（直接访问）

    • 模型：所有 Claude 模型
    • 全球可用
    • 定价：按令牌付费通过 Anthropic

提供商选择

此解决方案使用 LiteLLM 进行 LLM 提供商管理。根据 MODEL 环境变量中的前缀自动检测提供商：

  • 以 bedrock/ 前缀的模型使用 Amazon Bedrock
  • 以 anthropic/ 前缀的模型直接使用 Anthropic
  • 没有前缀，默认使用 Anthropic

尽管 LiteLLM 支持许多提供商，但此工具已专门针对通过 Amazon Bedrock 和 Anthropic 的 Claude 模型系列进行了测试和优化。

贡献