MCP server by mcy1475369
goctl-mcp: OpenAPI 3.0 生成器 MCP 服务器
🚀 自动将自然语言 API 描述转换为标准的 OpenAPI 3.0 规范，简化 go-zero goctl 框架代码生成流程。
📋 目录
背景
在使用 go-zero 的 goctl 工具时,开发人员需要手动编写符合 OpenAPI 3.0 标准的规范文件,这个过程繁琐且容易出错。本项目通过 MCP (Model Context Protocol) 提供智能化的 API 描述转换服务,让 AI 助手能够理解自然语言的 API 需求并自动生成标准的 OpenAPI 规范。
功能特性
✨ 智能解析: 从自然语言描述中自动识别 HTTP 方法、路径、参数等 📝 完整规范: 生成符合 OpenAPI 3.0.3 标准的完整规范 🔧 灵活工具: 提供多个 MCP 工具满足不同场景 🎯 模板生成: 快速生成标准 REST API 模板 ✅ 规范验证: 内置 OpenAPI 规范验证功能 🔄 格式转换: 支持 YAML/JSON 格式互转
安装
前置要求
- Python 3.10+
- pip
安装步骤
- 克隆仓库:
git clone <repository-url>
cd goctl-mcp
- 创建虚拟环境 (推荐):
python -m venv venv
# Windows
.\venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
- 安装依赖:
pip install -r requirements.txt
快速开始
运行 MCP 服务器
python -m src.server
配置 Claude Desktop
在 Claude Desktop 配置文件中添加:
Windows: %APPDATA%\Claude\claude_desktop_config.json
Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"goctl-openapi": {
"command": "python",
"args": ["-m", "src.server"],
"cwd": "d:\\project\\goctl-mcp"
}
}
}
重启 Claude Desktop 后即可使用。
MCP 工具说明
本 MCP 服务器提供以下工具:
1. create_openapi_spec
从零创建 OpenAPI 规范
参数:
title(必需): API 标题version: API 版本 (默认: "1.0.0")description: API 描述api_descriptions: API 描述列表
示例:
创建一个名为 "User Service" 的 API,包含以下接口:
- GET /users 获取所有用户
- POST /users 创建用户,需要 name 和 email
- GET /users/{id} 获取特定用户
2. add_api_endpoint
向现有 OpenAPI 规范添加新端点
参数:
existing_spec_yaml: 现有的 OpenAPI YAMLapi_description: 新端点的描述summary: 可选的简短摘要tags: 可选的标签列表
3. generate_from_template
使用模板快速生成完整 REST API
参数:
title: API 标题resource_name: 资源名称 (如 "user", "product")include_crud: 是否包含 CRUD 操作 (默认: true)include_list: 是否包含列表操作 (默认: true)version: API 版本
示例:
为 "Product" 资源生成完整的 REST API
4. batch_create_apis
批量创建多个 API 端点
参数:
title: API 标题api_list: API 描述列表version: API 版本description: API 描述
5. convert_to_json
将 YAML 格式转换为 JSON
6. validate_openapi_spec
验证 OpenAPI 规范的正确性
使用示例
示例 1: 创建用户管理 API
在 Claude Desktop 中输入:
使用 goctl-openapi MCP 工具创建一个用户管理 API,包含:
1. GET /users - 获取所有用户,支持 name 过滤
2. GET /users/{id} - 根据 ID 获取用户
3. POST /users - 创建用户,需要 name, email, phone
4. PUT /users/{id} - 更新用户信息
5. DELETE /users/{id} - 删除用户
示例 2: 使用模板快速生成
使用模板为 "Order" 资源生成完整的 REST API,版本 2.0.0
示例 3: 添加新端点
在现有的 API 规范中添加一个新端点:
GET /users/{id}/orders 获取用户的所有订单
与 goctl 集成
生成 OpenAPI 规范后,可以直接用于 goctl:
# 1. 使用 MCP 生成 OpenAPI 规范并保存为 openapi.yaml
# 2. 使用 goctl 生成 go-zero 代码
goctl api go -api openapi.yaml -dir ./output
完整工作流程
自然语言 API 需求
↓
goctl-mcp MCP 服务器 (本项目)
↓
OpenAPI 3.0 规范 (YAML/JSON)
↓
goctl 工具 (已改造支持 OpenAPI 3.0)
↓
go-zero 微服务代码
开发
项目结构
goctl-mcp/
├── src/
│ ├── __init__.py
│ ├── server.py # MCP 服务器主文件
│ ├── converter.py # API 描述解析和转换
│ └── openapi_models.py # OpenAPI 3.0 Pydantic 模型
├── tests/ # 测试文件 (待添加)
├── examples/ # 示例文件
├── requirements.txt # 依赖
├── pyproject.toml # 项目配置
└── README.md # 本文件
运行示例
# 运行基本使用示例
python examples/basic_usage.py
# 运行 MCP 工具使用示例
python examples/mcp_tools_usage.py
运行测试
pytest tests/
代码格式化
black src/
ruff check src/
技术栈
- FastMCP: 轻量级 MCP 框架
- Pydantic: 数据验证和序列化
- PyYAML: YAML 处理
- Python 3.10+: 核心语言
API 描述语法指南
HTTP 方法识别
系统会自动识别以下关键词:
- GET: get, fetch, retrieve, query, list, search
- POST: post, create, add, submit, register
- PUT: put, update, replace, modify
- DELETE: delete, remove
- PATCH: patch, partially update
路径参数
使用 {参数名} 格式:
GET /users/{id}
GET /orders/{orderId}/items/{itemId}
查询参数
使用关键词 with, by, filter, where:
GET /users with name and email filters
GET /products filter by category
请求体
在 POST/PUT/PATCH 中使用 with, including, contains:
POST /users with name, email and phone
PUT /products including title and price
常见问题
Q: 如何处理复杂的请求体结构?
A: 对于复杂结构,建议分步骤描述或使用更详细的自然语言描述。系统会尽力推断结构。
Q: 生成的规范可以修改吗?
A: 可以!生成的是标准 YAML,可以手动编辑或使用 add_api_endpoint 工具添加。
Q: 支持 OpenAPI 2.0 (Swagger) 吗?
A: 目前只支持 OpenAPI 3.0.3。如需转换,可使用第三方工具。
贡献
欢迎贡献!请遵循以下步骤:
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
许可证
联系方式
如有问题或建议,请提交 Issue。
享受自动化的 API 规范生成体验! 🚀