使用说明

OpenAPI到MCP转换器

通过人工智能增强和验证，将您的OpenAPI规范转换为生产就绪的模型上下文协议（MCP）服务器

OpenAPI到MCP 是一个强大的工具，可以自动将OpenAPI/Swagger规范转换为功能齐全的MCP服务器。它利用大型语言模型（LLM）从现有的API文档中分析、增强和生成MCP兼容的服务器实现。

[！小心] 本存储库中提供的示例仅用于实验和教育目的。它们展示了概念和技术，但不打算直接用于生产环境。确保亚马逊基岩护栏到位，以防止提示注入.

新增功能

v0.1.0

具有核心功能的初始版本
支持OpenAPI 3.0和Swagger 2.0规范
基于人工智能的评估和增强
自动生成MCP服务器和客户端
支持亚马逊基岩和人类学克劳德
具有使用跟踪功能的综合评估报告

为什么选择此解决方案

随着企业向人工智能就绪过渡，一个关键的难题是确保他们的API也为人工智能做好准备。为人类消费而编写的API规范通常缺乏大型语言模型可靠操作所需的详细程度。虽然人类开发人员可以依靠领域专业知识和部落知识来填补文档空白，但LLM可能会产生缺失信息的幻觉，导致AI代理无法在正确的时间可靠地调用正确的工具。

以人为导向的API文档中影响人工智能准备的常见问题包括：

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

当这些不完整的API规范被直接转换为MCP服务器时，生成的工具规范继承了相同的缺陷。这会导致不可预测的行为，充其量可能是次优的，最坏的情况是完全崩溃。OpenAPI到MCP转换器通过在生成MCP服务器之前使用人工智能分析、评估和增强API规范来解决这一差距，确保它们符合可靠的人工智能代理操作所需的质量标准。

建筑

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

关键组件

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

特性

核心功能

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

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

评估能力

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

人工智能准备情况评估尤其有价值，可以确定您的API与人工智能代理和自动化工具的工作效率。内置的linting可以识别规范问题和违反OpenAPI最佳实践的行为，而操作分析则提供了对每个端点的详细审查，包括参数文档、响应模式和错误处理。

发电特性

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

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

示例结果和输出指南

想看看转换器产生了什么吗？查看我们预先生成的示例结果和全面的输出指南：

探索示例结果 -查看真实评估报告、生成的MCP服务器，以及我们的API示例太空任务中的更多内容

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

这些资源准确地向您展示了转换过程的预期，并帮助您解释评估分数和生成的代码。

先决条件

Python 3.12或更高版本
紫外线包管理器
所选LLM提供商的有效API凭据：
- 亚马逊基岩证书（适用于Claude via Bedrock）
- Anthropic API密钥（用于直接访问Claude）

安装

安装uv

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

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Or using pip
pip install uv

快速安装

克隆存储库：

git clone https://github.com/agentic-community/openapi-to-mcp.git
cd openapi-to-mcp

创建并激活虚拟环境：

# Create virtual environment
uv venv

# Activate on macOS/Linux
source .venv/bin/activate

# Activate on Windows
.venv\Scripts\activate

使用uv安装依赖项：

uv pip install -e .

设置环境变量：

cp env.example .env
# Edit .env with your API credentials

开发安装

使用其他工具进行开发：

uv pip install -e ".[dev]"

用法

基本用法

评估并转换本地OpenAPI规范：

# For a simple example
openapi-to-mcp examples/hello.yaml

# For a more complex example
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]

Arguments:
  FILENAME              OpenAPI specification file (YAML or JSON)

Options:
  --url URL            URL to fetch OpenAPI specification from
  --output FILE        Output file for results (default: auto-generated)
  --eval-only         Only run evaluation, skip MCP generation
  --verbose           Enable verbose logging
  --show-env          Show environment configuration

环境变量

通过环境变量配置LLM提供者凭据：

对于亚马逊基岩：

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

对于Anthropic Direct：

export ANTHROPIC_API_KEY=your-api-key

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

例子

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

# Evaluate the simple hello API example
openapi-to-mcp examples/hello.yaml

# Check the generated output
ls output/results_*_hello/

示例2：评估复杂的API

# Evaluate the more complex sample API with multiple endpoints
openapi-to-mcp examples/sample_api.yaml

# This example includes operations for users, products, and more

示例3：从URL进行评估

# Evaluate directly from a URL
openapi-to-mcp --url https://raw.githubusercontent.com/agentic-community/openapi-to-mcp/refs/heads/main/examples/hello.yaml

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

# Just evaluate without generating MCP server
openapi-to-mcp examples/sample_api.yaml --eval-only

示例5：自定义输出位置

# Specify custom output file
openapi-to-mcp examples/hello.yaml --output results/my-api-evaluation.json

使用Stub服务器进行测试

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

为了便于在没有真正后端的情况下进行测试，我们提供：

存根服务器(examples/stub_server.py)用模拟响应实现后端API
预先生成的MCP服务器和客户端代码，用于即时测试
一个完整的工作流程，用于测试从API规范到工作MCP工具的整个链条

预先生成的结果

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

examples/results/anthropic/sample_api/

此目录包含评估报告、增强的规范和可运行的MCP服务器。看结果_ GUIDE.md 有关这些文件的详细信息。

运行端到端演示

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

步骤1：启动Stub服务器

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

# Start stub server on port 9002
uv run examples/stub_server.py --port 9002

这创建了一个模拟后端，用模拟数据响应API请求。

步骤2：设置身份验证令牌

导出MCP服务器所需的身份验证令牌：

export AUTH_TOKEN="your-secret-token"

步骤3：启动MCP服务器

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

# Navigate to the generated server directory
cd examples/results/anthropic/sample_api/mcpserver/

# Start the MCP server on port 9001, pointing to stub server on port 9002
python server.py --port 9001 --base-url http://localhost:9002

步骤4：使用MCP客户端进行测试

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

# From the same mcpserver directory
python client.py --server-url http://localhost:9001/mcp

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

工作流示例

# Terminal 1: Start stub server
uv run examples/stub_server.py --port 9002

# Terminal 2: Set auth and start MCP server
export AUTH_TOKEN="my-secret-token"
cd examples/results/anthropic/sample_api/mcpserver/
python server.py --port 9001 --base-url http://localhost:9002

# Terminal 3: Run client
cd examples/results/anthropic/sample_api/mcpserver/
python client.py --server-url http://localhost:9001/mcp

配置

配置文件

该工具使用 config/config.yml 对于包括型号选择在内的所有设置：

# Model configuration - specify your model here
model: bedrock/us.anthropic.claude-3-5-sonnet-20241022-v2:0
# Or for Anthropic direct:
# model: anthropic/claude-3-5-sonnet-20241022

# Model parameters
max_tokens: 8192
temperature: 0.0
timeout_seconds: 300

# Evaluation thresholds
good_evaluation_threshold: 3.0
generate_mcp_threshold: 3.0

# Feature flags
debug: false

质量阈值

良好评价阈值：“良好”评价的最低分数（默认值：3/5）
generate_mcp阈值：生成MCP服务器的最低分数（默认值：3/5）

完整性和AI就绪性得分都必须达到MCP生成的阈值。

输出结构

运行该工具后，您将发现以下结构：

output/
└── results_YYYYMMDD_HHMMSS_<spec-name>_<provider>/
    ├── evaluation_YYYYMMDD_HHMMSS.json      # Detailed evaluation results
    ├── summary_YYYYMMDD_HHMMSS.md           # Human-readable summary
    ├── usage_YYYYMMDD_HHMMSS.json           # Token usage and costs
    ├── enhanced_spec_YYYYMMDD_HHMMSS.yaml   # Enhanced specification
    ├── original_spec_YYYYMMDD_HHMMSS.yaml   # Original specification
    └── mcpserver/                            # Generated MCP server (if criteria met)
        ├── server.py                         # MCP server implementation
        ├── client.py                         # MCP client for testing
        ├── requirements.txt                  # Python dependencies
        ├── README.md                         # Usage documentation
        └── tool_spec.txt                     # Tool specifications

了解结果

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

查看结果指南

本指南解释了：

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

预先生成的结果 examples/results/anthropic/sample_api/ 作为一个参考实现，显示高质量转换是什么样子的。

AI提供商

支持的提供商

亚马逊基岩
- 型号：克劳德3.5十四行，克劳德4十四行
- 区域支持：所有使用Bedrock的AWS区域
- 定价：通过AWS按代币支付
人类学（直接）
- 型号：所有克劳德型号
- 全球可用性
- 定价：通过Anthropic按代币支付

提供者选择

此解决方案使用文学硕士 LLM提供者管理。根据MODEL环境变量中的前缀自动检测提供程序：

型号前缀为 bedrock/ 使用亚马逊基岩
型号前缀为 anthropic/ 直接使用Anthropic
如果没有前缀，模型默认为Anthropic

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

贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

开发设置

分叉存储库
创建要素分支
安装开发依赖项： uv pip install -e ".[dev]"
- 这将安装pytest、black、ruff和其他开发工具
进行更改
运行测试和代码质量检查
提交拉取请求

运行测试

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_spec_loader.py

# Run tests in verbose mode
uv run pytest -v

代码质量工具

黑色（代码格式化）

# Format all Python files in src directory
uv run black src

# Check formatting without making changes
uv run black --check src

# Format specific file
uv run black src/services/spec_loader.py

褶边（棉绒）

# Run linter on src directory
uv run ruff check src

# Fix auto-fixable issues
uv run ruff check --fix src

# Check specific file
uv run ruff check src/services/spec_loader.py

预提交检查

提交前运行所有质量检查：

# Run black formatting
uv run black src

# Run ruff linting
uv run ruff check --fix src

# Run tests
uv run pytest

安全

安全最佳实践

使用此工具时，请遵循以下安全准则：

OpenAPI规范中的敏感数据：在使用基于云的LLM提供商进行测试时，请确保OpenAPI规范不包含真实的API密钥、密码或个人身份信息（PII）等敏感数据。
对敏感数据使用本地模型：如果您的OpenAPI规范包含敏感信息，请考虑使用本地托管的LLM模型而不是第三方模型提供商来维护数据隐私。
生成代码的安全测试：在部署到生产环境之前，始终彻底审查和测试生成的MCP服务器代码是否存在安全漏洞。这包括：
- 输入验证和净化
- 身份验证和授权检查
- 限速和防止滥用
- 安全处理API证书
- 防止常见漏洞（注入攻击、XSS等）
环境变量：从不承诺 .env 文件或公开代码存储库中的API凭据。使用安全的凭据管理实践。

报告安全问题

看贡献有关此项目中报告安全漏洞的信息。

路线图

大型OpenAPI规范支持

实现基于路径的批处理，以处理超过LLM上下文窗口的大型API规范(#1)

许可证

此项目根据Apache-2.0许可证获得许可。看许可证了解详情。