Openapi To MCP Demo

OpenAPI到MCP转换器

将OpenAPI规范转换为具备AI增强功能的运行中的MCP（模型上下文协议）服务器。

概述

这个工具展示了如何快速将现有的API转变为一个可与Claude和其他AI助手协同工作的功能性MCP服务器。它结合了：

• OpenAPI 解析自动提取端点、参数和模式
• 大语言模型（LLM）增强/丰富使用Claude生成更优质的描述和商业背景信息
• 工具生成以JSON格式创建声明式的MCP工具定义
• 服务器生成使用通用运行时生成一个完整且可立即运行的MCP服务器
• 复合工具将多个API端点组合成单一、强大的工具

项目结构

openapi-to-mcp/
├── api/                    # FastAPI backend (converter service)
│   ├── app/
│   │   ├── api/            # API routes
│   │   ├── services/       # Core services (parser, enricher, generators)
│   │   ├── models/         # Pydantic schemas
│   │   └── templates/      # Template files for MCP server generation
│   ├── pyproject.toml      # Python dependencies (uv-compatible)
│   └── requirements.txt    # Alternative pip requirements
├── ui/                     # Vue 3 frontend
│   ├── src/
│   │   ├── components/     # Vue components
│   │   ├── stores/         # Pinia state management
│   │   └── views/          # Vue views
│   ├── package.json        # Node.js dependencies
│   └── vite.config.js      # Vite configuration
├── crm/                    # Example CRM API (for testing)
│   ├── main.py             # FastAPI CRM implementation
│   ├── docs/
│   │   └── crm_openapi.yaml  # OpenAPI spec for CRM
│   ├── pyproject.toml      # CRM API dependencies
│   └── seed_data.py        # Sample data generator
└── generated-servers/      # Output directory for generated MCP servers

先决条件

• Python 3.11及以上版本
• Node.js 18及以上版本
• Anthropic API密钥

快速入门

1. 后端设置（转换器API）

使用紫外线（推荐）

cd api

# Install uv if you haven't already
# curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies (creates .venv automatically)
uv sync

# Configure environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Start backend server
uv run uvicorn app.main:app --reload --port 8000

使用 pip（另一种方法）

cd api

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Start backend server
uvicorn app.main:app --reload --port 8000

后端将在 http://localhost:8000

2. 前端设置

cd ui

# Install dependencies
npm install

# Start development server
npm run dev

前端将在以下地址可用 http://localhost:5173

3. 示例CRM API（可选）

使用真实API测试转换器：

cd crm

# Using uv (recommended)
uv sync
uv run uvicorn main:app --reload --port 8001

# OR using pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8001

客户关系管理（CRM）API将提供于 http://localhost:8001 提供OpenAPI文档，位于 http://localhost:8001/docs

使用工作流程

步骤1：上传OpenAPI规范

1. 在浏览器中打开以下网址的网页界面： http://localhost:5173
2. 上传您的OpenAPI规范（YAML或JSON）
3. 该系统将解析并提取所有终端节点

步骤2：丰富终端节点

1. 审查提取的端点
2. 对于缺少描述的端点，添加业务上下文
3. 点击“使用AI增强”以利用Claude生成更完善的描述
4. 大型语言模型（LLM）将提供：

- 终端功能的技术描述 - 商业背景说明何时/为何使用它

第三步：生成工具

1. 配置您的API详细信息（名称和基础URL）
2. 点击“生成工具定义”
3. 审查生成的MCP工具及其输入模式
4. 每个工具都映射到一个带有适当参数定义的API端点

步骤4：生成服务器

1. 为您的MCP服务器提供一个名称
2. 点击“生成服务器”
3. 下载完整的服务器包，格式为ZIP文件

步骤5：使用您的MCP服务器

1. 解压下载的ZIP文件
2. 导航到服务器目录
3. 安装依赖项：

   pip install -e .

1. 在“中”配置您的API密钥 .env
2. 添加到Claude桌面配置中：

   {
     "mcpServers": {
       "your-server-name": {
         "command": "python",
         "args": ["/path/to/server/server.py"],
         "env": {
           "API_KEY": "your-api-key-here"
         }
       }
     }
   }

示例

一个示例CRM API已包含在内 crm/ 包含其OpenAPI规范的目录位于 crm/docs/crm_openapi.yaml这提供了：

• 一个可运行的FastAPI实现用于测试
• 用于转换测试的完整OpenAPI规范
• 产品、客户和订单的示例端点

您可以使用CRM API的OpenAPI规范来测试整个转换工作流程。

主要特点

智能解析

• 自动识别需要更好描述的终端节点
• 提取参数、请求体和响应模式
• 保留原始API元数据

AI赋能的丰富化（或增强功能）

• 使用Claude生成清晰、技术性的描述
• 添加业务上下文，帮助AI助手了解何时使用每种工具
• 将用户领域知识与大型语言模型（LLM）推理相结合

复合工具

• 将多个API端点组合成单一、强大的工具
• 创建如“搜索并购买”或“创建客户并下单”等工作流
• 人工智能辅助建议：有用的复合工具组合

完整服务器生成

• 使用声明式工具定义创建可运行的Python MCP服务器
• 包括适当的错误处理和HTTP方法支持
• 生成README文件、pyproject.toml文件以及安装说明
• 输出已保存至 generated-servers/ 目录

建筑学

后端服务

• OpenAPIParser 翻译为中文是“OpenAPI解析器”解析YAML/JSON规范并提取端点数据
• LLMEnricher（可译为“大型语言模型增强器”或根据具体上下文意译为更贴切的名称，如“模型丰富工具”等）使用Claude API来增强端点描述
• 工具生成器将端点转换为MCP工具定义
• 服务器生成器创建完整的MCP服务器包

前端组件（ui/）

• SpecUploader（可译为“规格上传器”或根据具体上下文调整为更贴切的名称）带有拖放功能的文件上传界面
• 终端点列表交互式终端点审查与丰富化
• 工具预览显示生成的工具定义
• 服务器生成器处理服务器创建和下载
• 复合工具创建器从多个端点创建组合工具

API 端点

• POST /api/upload-spec上传并解析OpenAPI规范
• POST /api/enrich-endpoint利用大型语言模型（LLM）丰富终端功能
• POST /api/suggest-tools获取大型语言模型（LLM）对工具的建议
• POST /api/generate-tools生成MCP工具定义
• POST /api/generate-server创建完整的MCP服务器
• GET /api/download-server/{name}下载服务器包

发展

运行测试

# Backend tests
cd api
pytest

# Frontend tests
cd ui
npm run test

代码风格

项目内容如下：

• Python：使用 Black 格式化遵循 PEP 8 规范
• JavaScript：ESLint + Prettier

演讲技巧

用于演示/展示目的：

1. 提前准备准备好你的OpenAPI规范和丰富上下文，以便复制粘贴
2. 使用截图如果现场演示失败，截取关键屏幕作为备份
3. 选择简单的API电子商务或客户关系管理（CRM）的例子易于观众理解
4. 预填充上下文准备好业务用例以便快速粘贴补充
5. 显示输出结果显示生成的服务器代码以证明其完整性

核心信息

• 这是 不难也不神奇 - 任何人都可以建造这个
• 它是 不是万能良药 我们将人类的专业知识与大型语言模型（LLM）的能力相结合
• 使用 现有工具 (OpenAPI) + 轻量级编码 = 快速成果
• 非常适合 加速发展 内部工具和客户解决方案两者

局限性

• 内存存储（尚不适用于生产环境）
• 无需身份验证/授权
• 对格式错误的规范处理有限
• 生成的服务器使用基本的HTTP客户端（无重试逻辑、速率限制等）

未来改进方向

• 数据库持久性
• 用户身份验证
• 支持更多API规范（GraphQL、gRPC）
• 高级服务器功能（缓存、速率限制）
• 批量端点富集
• 自定义工具模板

许可证

MIT 许可证 - 可自由用于演示、展示和学习。

做出贡献

这是一个用于教育目的的演示项目。请随意进行分支并根据您的需求进行调整。

支持

如有疑问或问题，请参阅项目文档或在仓库中创建一个问题。