MCP生成器2.0

Name: MCP生成器2.0
Author: quotentiroler

作者：quotentiroler6 星标更新：2025-11-05

安装使用来源：spider==github.com

项目介绍

MCP Generator 2.0

🚀 将 OpenAPI 转换为 FastMCP 2.x 服务器生成器

将任何 OpenAPI 规范转换为企业级认证、模块化架构和全面中间件支持的生产就绪型模型上下文协议（MCP）服务器。

🎯 概述

MCP Generator 2.0 是一个高级代码生成器，它可以从 OpenAPI 3.0.x/3.1.x 规范自动生成 FastMCP 2.x 服务器。通过生成完全功能的 MCP 工具，它可以桥接 REST API 和 AI 代理，使像 Claude、ChatGPT 等 AI 助手能够与您的 API 进行交互。

支持的 OpenAPI 版本

✅ OpenAPI 3.0.x - 完全支持（推荐）
✅ OpenAPI 3.1.x - 完全支持
✅ Swagger 2.0 - 完全支持

注意：支持 JSON 和 YAML 格式。生成器在内部使用 OpenAPI Generator CLI，可以无缝处理这两种格式。

🏆 为什么选择 MCP Generator 2.0？

特性	MCP Generator 2.0	典型生成器
架构	模块化的子服务器	单一文件的单体架构
认证	使用 JWKS 的 JWT 验证，OAuth2 流程	基本令牌传递
中间件系统	完整的 FastMCP 2.x 中间件堆栈	有限或无
可扩展性	每个 API 类一个模块	所有操作在一个文件中
类型安全性	完整的 Pydantic 模型支持	基本验证
测试	自动生成测试套件	手动测试
可观测性	计时、日志、错误处理中间件	基本日志
事件存储	可恢复的 SSE 与事件持久化	简单的 SSE
生产就绪	✅ 是	⚠️ 经常是原型

📦 安装

先决条件

Python 3.11+：需要现代类型提示和特性
uv（推荐）或 pip：用于依赖管理
Node.js & npm：需要 OpenAPI Generator CLI
OpenAPI 规范：您的 API 的 OpenAPI 3.0.x 或 3.1.x 规范文件（JSON 或 YAML）

使用 uv 安装（推荐）

# 克隆仓库
git clone https://github.com/quotentiroler/mcp-generator-2.0.git
cd mcp-generator-2.0

# 安装依赖
uv sync

# 验证安装
uv run generate-mcp --help

使用 pip 安装

# 克隆仓库
git clone https://github.com/quotentiroler/mcp-generator-2.0.git
cd mcp-generator-2.0

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 安装依赖
pip install -e .

# 验证安装
generate-mcp --help

安装 OpenAPI Generator

# 使用 npm（推荐）
npm install -g @openapitools/openapi-generator-cli

# 验证安装
npx @openapitools/openapi-generator-cli version

🚀 快速开始

1. 从 OpenAPI 规范生成 MCP 服务器

# 使用本地文件（默认：./openapi.json）
uv run generate-mcp

# 使用自定义文件
uv run generate-mcp --file ./my-api-spec.yaml

# 从 URL 下载
uv run generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

会发生什么：

✅ 从 OpenAPI 规范生成 Python API 客户端
✅ 创建模块化的 MCP 服务器模块
✅ 生成认证中间件
✅ 创建 OAuth2 提供者
✅ 编写包文件和测试
✅ 输出到 generated_mcp/ 目录

2. 注册您的 MCP 服务器

# 注册生成的服务器
uv run register-mcp ./generated_mcp

# 验证注册
uv run run-mcp --list

这会将您的服务器添加到本地注册表 ~/.mcp-generator/servers.json 中，以便您可以按名称轻松运行它。

3. 运行您的 MCP 服务器

# 选项 1：通过注册表运行（STDIO 模式，适用于本地 AI 客户端）
export BACKEND_API_TOKEN="your-api-token-here"  # 在 Windows 上：set BACKEND_API_TOKEN=...
uv run run-mcp swagger_petstore_openapi

# 选项 2：通过注册表运行（HTTP 模式）
uv run run-mcp swagger_petstore_openapi --mode http --port 8000

# 选项 3：直接使用 Python 运行
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py --transport stdio

# 选项 4：使用 FastMCP CLI 运行
cd generated_mcp
# 注意：使用 :create_server 来正确组合服务器
uv run fastmcp run swagger_petstore_openapi_mcp_generated.py:create_server
# 或使用 fastmcp.json 配置：
uv run fastmcp run fastmcp.json

4. 与 AI 客户端一起使用

Claude Desktop（STDIO 模式）

在 ~/.claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["/path/to/generated_mcp/swagger_petstore_openapi_mcp_generated.py"],
      "env": {
        "BACKEND_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

🔍 使用 MCP Inspector 测试

MCP Inspector 是 MCP 服务器的官方调试工具。它提供了视觉 UI 和 CLI 模式来测试您的生成服务器。

快速开始使用 Inspector

# 首先生成您的 MCP 服务器
uv run generate-mcp --file ./openapi.json

# 使用 Inspector 测试（推荐使用 FastMCP）
cd generated_mcp
uv run fastmcp dev swagger_petstore_openapi_mcp_generated.py:create_server

# 或直接使用 Python 测试
npx @modelcontextprotocol/inspector python swagger_petstore_openapi_mcp_generated.py

# 或使用环境变量
npx @modelcontextprotocol/inspector -e BACKEND_API_TOKEN=your-token python swagger_petstore_openapi_mcp_generated.py

注意：当使用 fastmcp dev 或 fastmcp run 时，始终包括 :create_server 来正确组合模块化服务器架构。

Inspector 将：

🚀 启动您的 MCP 服务器
🌐 在 http://localhost:6274 打开浏览器 UI
🔗 通过代理连接到 http://localhost:6277
🔑 生成安全会话令牌

Inspector 功能针对您的生成服务器

🛠️ 工具测试

列出从您的 OpenAPI 规范生成的所有可用工具
交互式表单参数输入
实时响应可视化，带有 JSON 格式化
测试 OAuth2 认证流程

📦 资源探索

层次浏览 API 资源
查看资源元数据和内容
测试资源订阅

💬 提示测试

交互式提示采样
流式响应可视化
比较多个提示变体

📊 调试

请求/响应历史记录
可视化错误消息
实时服务器通知
网络计时信息

CLI 模式用于自动化

适合 CI/CD 和快速开发周期：

# 列出可用工具
npx @modelcontextprotocol/inspector --cli python swagger_petstore_openapi_mcp_generated.py --method tools/list

# 调用特定工具
npx @modelcontextprotocol/inspector --cli python swagger_petstore_openapi_mcp_generated.py \
  --method tools/call \
  --tool-name create_pet \
  --tool-arg 'name=Fluffy' \
  --tool-arg 'status=available'

# 使用环境变量测试
npx @modelcontextprotocol/inspector --cli \
  -e BACKEND_API_TOKEN=your-token \
  python swagger_petstore_openapi_mcp_generated.py \
  --method tools/list

测试 HTTP/SSE 传输

如果您的生成服务器以 HTTP 模式运行：

# 以 HTTP 模式启动服务器
cd generated_mcp
python swagger_petstore_openapi_mcp_generated.py --transport http --port 8000

# 连接到运行中的服务器（SSE 传输）
npx @modelcontextprotocol/inspector http://localhost:8000/sse

# 或使用可流式传输的 HTTP 传输
npx @modelcontextprotocol/inspector http://localhost:8000/mcp --transport http

导出配置

Inspector 可以导出您的服务器配置，用于 Claude Desktop 或其他 MCP 客户端：

服务器条目按钮 - 复制单个服务器配置到剪贴板
服务器文件按钮 - 复制完整的 mcp.json 结构

示例导出配置：

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["swagger_petstore_openapi_mcp_generated.py"],
      "env": {
        "BACKEND_API_TOKEN": "your-token"
      }
    }
  }
}

开发工作流

将 Inspector 整合到您的开发周期中：

# 1. 从 OpenAPI 规范生成服务器
uv run generate-mcp --file ./openapi.yaml

# 2. 使用 Inspector UI 测试（交互式开发）
cd generated_mcp
npx @modelcontextprotocol/inspector -e BACKEND_API_TOKEN=test python *_mcp_generated.py

# 3. 自动化测试（CI/CD）
npx @modelcontextprotocol/inspector --cli \
  -e BACKEND_API_TOKEN=test \
  python *_mcp_generated.py \
  --method tools/list > tools.json

# 4. 测试特定工具
npx @modelcontextprotocol/inspector --cli \
  -e BACKEND_API_TOKEN=test \
  python *_mcp_generated.py \
  --method tools/call \
  --tool-name get_user \
  --tool-arg 'user_id=123'

测试生成服务器的技巧

JWT 验证：使用 Inspector 测试 JWT 认证流程，使用 --validate-tokens
OAuth2 流程：Inspector 支持 bearer token 认证，用于测试 OAuth2
作用域测试：验证您的 OAuth2 配置中的作用域强制执行
错误处理：Inspector 可视化错误响应和堆栈跟踪
性能：使用 Inspector 的计时指标识别慢操作

更多详情，请参阅 Inspector 文档。

🧰 CLI 参考

此项目安装了三个 CLI 命令。这里是一个快速备忘单。

generate-mcp

描述：从 OpenAPI 3.0.x/3.1.x 规范生成 FastMCP 2.x 服务器。
选项：
- --file <path> 规范文件路径（默认：./openapi.json）
- --url <url> 从 URL 下载规范（覆盖 --file）
示例：

# 使用本地文件（默认）
uv run generate-mcp

# 自定义文件
uv run generate-mcp --file ./my-api.yaml

# 从 URL
uv run generate-mcp --url https://petstore3.swagger.io/api/v3/openapi.json

register-mcp

描述：管理位于 ~/.mcp-generator/servers.json 的本地注册表
子命令：
- add <path> 注册生成的服务器（默认情况下传递路径）
- list 显示所有已注册的服务器
  - --json 作为 JSON 输出（用于脚本/自动化）
- remove <name> 通过名称取消注册服务器
- export <name> 导出服务器元数据作为 server.json 用于 MCP 注册表发布
  - -o, --output <file> 写入文件（默认：标准输出）
示例：

# 添加（显式）
uv run register-mcp add ./generated_mcp

# 添加（隐式）
uv run register-mcp ./generated_mcp

# 列出已注册的服务器
uv run register-mcp list

# 列出为 JSON
uv run register-mcp list --json

# 通过名称删除
uv run register-mcp remove swagger_petstore_openapi

# 导出服务器元数据用于发布
uv run register-mcp export swagger_petstore_openapi -o server.json

run-mcp

描述：通过名称运行已注册的服务器。
标志：
- --list 列出已注册的服务器并退出
- --mode/--transport stdio | http（默认：stdio）
- --host HTTP 主机（默认：0.0.0.0）
- --port HTTP 端口（默认：8000）
- --validate-tokens 启用 JWT 验证（HTTP 模式）
示例：

# 列出服务器
uv run run-mcp --list

# 通过 STDIO 运行（Linux/macOS）
export BACKEND_API_TOKEN="your-api-token" && uv run run-mcp swagger_petstore_openapi

# 通过 STDIO 运行（Windows PowerShell）
powershell
$env:BACKEND_API_TOKEN = "your-api-token"
uv run run-mcp swagger_petstore_openapi

# 通过 HTTP 运行
uv run run-mcp swagger_petstore_openapi --mode http --port 8000

# HTTP 带 JWT 验证
uv run run-mcp swagger_petstore_openapi --mode http --port  8000 --validate-tokens

注意事项：

注册表文件位于 ~/.mcp-generator/servers.json
run-mcp 将这些标志转发给生成服务器的入口点。
您也可以直接运行生成的脚本：python <name>_mcp_generated.py

内部注册表（本地）

使用 register-mcp 快速创建您生成的 MCP 服务器的本地内部注册表。条目位于 ~/.mcp-generator/servers.json；几秒钟内即可添加/列出/移除，并且 run-mcp 让您可以通过名称启动服务器。您可以并排运行多个服务器（例如，不同的 HTTP 端口），以实现平滑的开发工作流。

发布到自托管的 MCP 注册表

您可以运行自己的 MCP 注册表（开源）并将生成的服务器发布到其中：

在您的基础设施上部署官方注册服务（Docker Compose/Kubernetes）。配置 TLS、数据库（PostgreSQL）和公共基础 URL。
配置身份验证/所有权验证：在注册表中设置 GitHub OAuth/OIDC，或使用 DNS/HTTP 挑战证明您的命名空间的所有权。
让您的 MCP 服务器可通过 HTTP 访问，并提供有效的服务器元数据（server.json），符合注册表模式。
使用发布者 CLI 指向您的注册表的基础 URL，进行身份验证并发布您的服务器。经过验证后，它可以通过您的注册表的 API/UI 发现。

注意：此项目尚未自动发布。本地每个用户的注册表（~/.mcp-generator/servers.json）是为了方便开发；发布到中央目录是一个可选的单独步骤。

OAuth2 支持

当 OpenAPI 规范包含 OAuth2 安全方案时，会自动生成 OAuth2 提供者。

支持的流程：

隐式流程
授权码流程
客户端凭证流程
密码流程

功能：

范围提取和验证
令牌检查
基于 JWKS 的 JWT 验证
范围强制执行中间件

JWT 验证

当启用 --validate-tokens 时：

令牌提取：从 Authorization 头中提取 JWT
JWKS 发现：自动发现 JWKS 端点来自 OpenAPI 规范或使用标准的 well-known 路径
签名验证：使用公钥验证 JWT 签名
声明验证：检查过期时间、发行人、受众
**