🚀 OpenAPI to MCP Server Code Generator

🚀 OpenAPI 到 MCP 服务代码生成器

概述

此工具可根据 OpenAPI 规范生成 Model Context Protocol（MCP）服务，创建可供 AI 助手与 API 交互的 Python 包。其核心架构会将 OpenAPI 规范转换为包含工具、模型和客户端代码的结构化 MCP 服务。

快速开始

• 安装 uv
• 生成服务（以及可选的 Agent/评估）：

  uvx --from git+https://github.com/cnoe-io/openapi-mcp-codegen.git openapi_mcp_codegen \
    --spec-file examples/petstore/openapi_petstore.json \
    --output-dir examples/petstore \
    --generate-agent \
    --generate-eval
  

✨ 功能

• ⚡ 根据 OpenAPI 规范自动生成 MCP 服务
• 📝 支持 JSON 和 YAML 格式
• 🛠️ 为每个 API 端点生成工具模块
• 🤖 生成 API 客户端代码
• 📋 设置日志记录和错误处理
• ⚙️ 配置文件（pyproject.toml、.env.example）
• 📚 生成全面的文档
• 🚀 --generate-agent 标志 – 另外生成一个 LangGraph React Agent（包含 A2A 服务、Makefile、README 和 .env.example）， 与生成的 MCP 服务一同提供
• 📊 --generate-eval：添加交互式评估模式和自动化评估套件
• 🧠 --generate-system-prompt：使用已配置的大模型为 Agent 生成 SYSTEM 提示词
• 🔌 可选支持 SLIM 传输（请参阅实验部分）

工作原理

• 提供 OpenAPI 规范（JSON 或 YAML）。
• 生成器会解析路径、操作和架构，然后将 Jinja2 模板渲染为结构化的 Python MCP 服务。
• 还可选择生成配套的 LangGraph Agent 和 A2A 服务封装，使其能够调用生成的 MCP 工具。
• 还支持使用 LangFuse 进行追踪和评估。

开发

本地开发命令

# Setup venv
uv venv && source .venv/bin/activate

# Initial setup (requires uv CLI)
uv sync

CLI 选项

• --generate-agent
  • 生成一个封装所生成 MCP 服务的 LangGraph React Agent
  • 包含 A2A 服务、Makefile、README 和 .env.example
• --generate-eval
  • 添加：
    • eval_mode.py（交互式数据集构建器，将追踪记录保存到 eval/dataset.yaml）
    • eval/evaluate_agent.py（由 LangFuse 驱动的评估，使用正确性、幻觉和轨迹准确度指标）
• --generate-system-prompt
  • 使用已配置的大模型创建适用于所生成工具的 SYSTEM 提示词
• --enhance-docstring-with-llm
  • 可选择使用大模型改写工具文档字符串
• --enable-slim
  • 通过 AgntcyFactory 将生成的 A2A Starlette 应用桥接到 SLIM，并生成用于启动服务的 docker-compose 文件

生成的架构

🏗️ 架构

flowchart TD
  subgraph Client Layer
    A[User Client A2A]
  end
  subgraph Agent Transport Layer
    B[Google A2A]
  end
  subgraph Agent Framework Layer
    C[LangGraph ReAct Agent]
  end
  subgraph Tools/MCP Layer
    D[Petstore MCP Server]
    E[Petstore API Server]
  end
  A --> B
  B --> C
  C -.-> D
  D -.-> C
  D -.-> E
  E -.-> D

生成的架构包含一个 STDIO 模式的 MCP 服务和两个内置实用工具：get_current_time 和 iso8601_to_unix。

示例：Petstore A2A LangGraph Agent + MCP 服务

1. 生成 Agent 和评估用例

uvx --from git+https://github.com/cnoe-io/openapi-mcp-codegen.git openapi_mcp_codegen \
  --spec-file examples/petstore/openapi_petstore.json \
  --output-dir examples/petstore \
  --generate-agent \
  --generate-eval

2. 配置 Agent 和大模型（参见 大模型提供商文档），以及 Langfuse 的 使用 docker-compose 部署和创建 API 密钥文档。

cat > .env << 'EOF'
# Petstore API
PETSTORE_API_URL=http://0.0.0.0:10000
PETSTORE_TOKEN=foo

# LLM provider (configure per your provider)
LLM_PROVIDER=openai
OPENAI_API_KEY=<your-openai-api-key>
OPENAI_ENDPOINT=https://api.openai.com/v1
OPENAI_MODEL_NAME=gpt-5

# Langfuse (optional)
LANGFUSE_HOST=http://localhost:3000
LANGFUSE_PUBLIC_KEY=<your-langfuse-public-key>
LANGFUSE_SECRET_KEY=<your-langfuse-secret-key>
EOF

还要将这些变量导出到 shell 中：

# Exports each line of the .env ignoring lines starting with #
export $(grep -v '^#' .env | xargs)

3. 进入 Agent 目录并运行模拟服务：

cd examples/petstore
uv run python petstore_mock_server.py

4. 在 Git 仓库根目录的新终端中：

cd examples/petstore
make run-a2a

5. 在 Git 仓库根目录的新终端中（先安装 Docker）：

cd examples/petstore
make run-a2a-client

现在，Agent 和客户端都已部署，例如可以询问 List my available pets。如果启用了跟踪，可以在 LangFuse（http://localhost:3000）中查看。按照以下步骤评估 Agent：

6. 在新终端中以评估模式启动 Agent。这将输出工具列表，并提示你评估每个工具并在 eval/dataset.yaml 中构建数据集。

make run-a2a-eval-mode

7. 完成数据集构建后，启动评估：

make eval

这会在 LangFuse 中创建一个新数据集，并触发一次评估运行。

扩展：SLIM

本节要求可以访问 host.docker.internal。如果遇到问题，请参阅此 GitHub issue。

8. 如果使用 --enable-slim 生成，还可以通过 SLIM 运行 A2A 服务，并通过 docker-compose 自动启动本地 SLIM 数据平面：

export PETSTORE_API_URL=http://host.docker.internal:10000  # Needed so that the MCP server can talk to the mock API server running on the host
make run-a2a-and-slim

此 docker-compose：

• 运行两个容器：一个通过 HTTP 运行 A2A，另一个将 A2A 桥接到 SLIM，
• 启动 slim-config.yaml 中定义的 slim-dataplane 服务，
• 将 Langfuse 接入两个容器（假设可以访问 host.docker.internal；或者将 langfuse 组件添加到生成的 docker-compose 文件中，并将 LANGFUSE_HOST 环境变量更新为 http://langfuse-web:3000）。

9. 要从客户端连接到桥接至 SLIM 的 Agent，请在新终端中运行：

make run-slim-client

A2A Inspector 工具

A2A Inspector 是用于检查和调试 A2A 服务的实用工具。它提供可视化界面，用于浏览 Agent 卡片并调用 Agent。按照项目页面上的说明构建并运行 Inspector，之后应可通过 localhost:8080 访问。然后即可连接到运行于 localhost:8000/.well-known/agent.json 的 Agent。

项目特定约定

配置文件

• 每个示例都需要 config.yaml，其中包含授权标头等元数据
• 生成的 pyproject.toml 包含 Agent 专属依赖项
• .env.example 模板包含 Agent 专属环境变量

代码生成模式

• 操作 ID 会转换为 Python 函数名（转换为 snake_case）
• OpenAPI 参数会映射为带类型提示的函数参数
• 生成的工具遵循以下模式：async def operation_id(params) -> Any
• API 客户端使用 httpx，并支持配置基础 URL 和标头

集成点

外部依赖项

• MCP 协议：使用 mcp>=1.9.0 实现 FastMCP 服务
• uv 包管理器：依赖管理和执行所必需
• Jinja2：用于代码生成的模板引擎
• Ruff：代码格式化和 lint（自动应用于生成的代码）

了解项目的关键文件

• openapi_mcp_codegen/mcp_codegen.py：核心生成逻辑和模板渲染
• openapi_mcp_codegen/templates/：模板结构与输出结构相对应
• examples/petstore/：包含 OpenAPI 规范和配置的完整可运行示例
• tests/test_mcp_codegen.py：展示预期生成流程的集成测试

实验性

SLIM 支持

使用 --enable-slim 构建可通过 SLIM 传输运行 A2A 服务的 Agent。

• 使用 --enable-slim 生成时，docker-compose 还会启动 slim-dataplane 服务，并通过 SLIM 连接 Agent。
• Agent 的 A2A 服务通过 AgntcyFactory 在 SLIM 上运行。
• 使用 make run-a2a-and-slim 启动 HTTP A2A 和 SLIM 桥接堆栈，其中包括 slim-dataplane。
• 要从客户端连接到经 SLIM 桥接的 Agent：

  make run-slim-client
  

• 参考：
  • SLIM Core：https://docs.agntcy.org/messaging/slim-core/

A2A 代理

--with-a2a-proxy 标志

• 生成一个精简的 WebSocket 上游服务，用于部署在外部 a2a-proxy 后面。
• 单独部署外部 a2a-proxy，并将其配置为连接到 WS 上游（ws://host:port）。该代理会向客户端提供 A2A HTTP API（例如 /a2a/v1）。
• 与 --generate-agent 配合使用时，可能会提供一个 Makefile 目标（例如 make run-with-proxy），用于在本地启动 WS 上游服务。
• 该方式仍处于实验阶段，可能会有变更。仅用于评估和原型开发。

常见调试模式

• 生成的代码通过 Python 的 logging 模块提供了详尽的日志记录
• 可通过 render_template() 中的 Jinja2 上下文访问模板变量
• 使用 --dry-run 标志预览生成结果，而不写入文件

---

🎯 使用 OpenAPI Overlay 增强文档

概述

此工具现在支持使用 OpenAPI Overlay Specification 1.0.0 增强文档。生成对 AI 友好的 MCP 服务，并优化文档字符串，帮助 Agent 更好地理解内容。

快速开始：增强生成

# One-command enhanced MCP server generation
python -m openapi_mcp_codegen.enhance_and_generate \
    examples/argo-workflows/openapi_argo_workflows.json \
    examples/argo-workflows/mcp_server \
    examples/argo-workflows/config.yaml \
    --save-overlay overlay.yaml \
    --save-enhanced-spec enhanced_openapi.json

此命令将：

1. 生成 Overlay，添加对 AI 友好的描述（如果可用，则使用大模型）
2. 应用 Overlay，生成增强版 OpenAPI 规范
3. 生成 MCP 服务，并使用优化后的文档字符串

增强流程

flowchart LR
    A[OpenAPI Spec] -->|1. Analyze| B[Overlay Generator]
    B -->|2. LLM Enhance| C[overlay.yaml]
    A -->|3. Apply| D[Overlay Applier]
    C --> D
    D -->|4. Enhanced| E[enhanced_openapi.json]
    E -->|5. Generate| F[MCP Server]
    style B fill:#e1f5ff
    style C fill:#fff4e6
    style E fill:#e8f5e9
    style F fill:#f3e5f5

主要功能

1. 大模型增强描述

• 兼容 OpenAI 的格式（少于 250 个字符）
• 纯文本——不含 Markdown 或特殊格式
• 使用场景上下文——“使用场景：”
• 以操作为导向——以明确的动词开头

2. 智能参数处理

• 自动检测复杂架构
• 字典模式适用于包含超过 10 个嵌套参数的架构
• 简洁的函数签名——不再生成包含 1,000 多个参数的函数
• 结果：复杂操作的代码量减少 98%

3. OpenAPI Overlay 标准

• 行业标准 Overlay Specification 1.0.0
• 可在工具和平台间重复使用
• 版本控制文档增强内容
• 不会破坏原始 OpenAPI 规范

配置

config.yaml 中的 title 字段现在用于控制包名称：

title: argo_workflows              # → mcp_argo_workflows
description: Argo Workflows MCP Server
author: Your Name
email: [email protected]
version: 0.1.0
license: Apache-2.0

headers:
  Authorization: Bearer {token}
  Accept: application/json

Overlay 生成选项

# Generate overlay only (with LLM)
python -m openapi_mcp_codegen.overlay_generator \
    spec.json overlay.yaml --use-llm

# Apply existing overlay
python -m openapi_mcp_codegen.overlay_applier \
    spec.json overlay.yaml enhanced_spec.json

# Full pipeline
python -m openapi_mcp_codegen.enhance_and_generate \
    spec.json output/ config.yaml \
    --save-overlay overlay.yaml \
    --format yaml

示例：增强前后对比

增强前

GET /api/v1/workflows:
  description: "Get workflows"

大模型增强后

GET /api/v1/workflows:
  description: "List all workflows in a namespace. Use when: you need to discover running workflows or check workflow status. Required: namespace"

生成的函数

async def workflow_service_list_workflows(
    path_namespace: str,
    param_listOptions_labelSelector: str = None
) -> Any:
    """
    List all workflows in a namespace

    OpenAPI Description:
        List all workflows in a namespace. Use when: you need to
        discover running workflows or check workflow status.

    Args:
        path_namespace (str): Kubernetes namespace to scope the operation
        param_listOptions_labelSelector (str): Filter by labels
    """

性能影响

指标	增强前	增强后	改进
函数大小（复杂操作）	5,735 行	82 行	减少 98.6%
参数数量	1,000 多个	7 个参数	减少 99.3%
描述长度	300 多个字符	少于 250 个字符	符合 OpenAI 规范 ✅
工具选择准确率	基准值	+35%	Agent 性能更佳

文件管理

纳入版本控制：

• ✅ openapi.json - 原始 OpenAPI 规范
• ✅ config.yaml - 配置
• 🤔 overlay.yaml - 可选（可重新生成，但便于审查和编辑）

自动生成（无需存储）：

• ❌ enhanced_openapi.json - 根据原始规范和 Overlay 派生
• ❌ mcp_server/ - 生成的代码输出

大模型提供商设置

# Set LLM API keys
export OPENAI_API_KEY=your-key
export ANTHROPIC_API_KEY=your-key
export LLM_PROVIDER=openai  # or anthropic

# The overlay generator will automatically use LLM if keys are set
# Falls back to rule-based generation if no LLM available

高级：自定义 Overlay

你可以手动编辑 overlay.yaml，实现精细控制：

overlay: 1.0.0
info:
  title: Custom Enhancements
  version: 1.0.0

actions:
  - target: $.paths['/api/v1/workflows'].get.description
    update: "Your custom description here"

  - target: $.paths['/api/v1/workflows'].get.parameters[0].description
    update: "Custom parameter description"

然后应用并重新生成：

python -m openapi_mcp_codegen.overlay_applier \
    original_spec.json overlay.yaml enhanced_spec.json

python -m openapi_mcp_codegen \
    --spec-file enhanced_spec.json \
    --output-dir mcp_server

---

📚 其他资源

• 架构指南：查看 Architecture.md，了解详细的架构文档和实现指南，其中包含 Argo Workflows 示例
• Overlay 规范：OpenAPI Overlay Specification 1.0.0
• MCP 协议：Model Context Protocol
• 示例：查看 examples/ 目录，了解完整的可运行示例