Goctl MCP

Goctl-mcp: OpenAPI 3.0 Generator MCP Server

🚀 Automatically convert natural language API descriptions to the standard OpenAPI 3.0 specification, simplifying the code generation process of the go zero gotl framework.

  

📋 catalogue

• background
• Features
• install
• Quick Start
• MCP Tool Description
• Usage example
• Integrate with goctl
• development

background

When using the goctl tool of go zero, developers need to manually write specification files that comply with the OpenAPI 3.0 standard, which is cumbersome and prone to errors. This project provides intelligent API description conversion services through MCP (Model Context Protocol), enabling AI assistants to understand the API requirements of natural language and automatically generate standard OpenAPI specifications.

Features

✨ Intelligent AnalysisAutomatically identify HTTP methods, paths, parameters, etc. from natural language descriptions 📝 Complete specificationsGenerate a complete specification that complies with OpenAPI 3.0.3 standard 🔧 Flexible toolsProvide multiple MCP tools to meet different scenarios 🎯 template generationQuickly generate standard REST API templates ✅ Standardized verificationBuilt in OpenAPI specification verification function 🔄 format conversionSupport YAML/JSON format conversion

install

Pre requirements

• Python 3.10+
• pip

Installation steps

1. Clone repository:

git clone 
cd goctl-mcp

1. Create a virtual environment (recommended):

python -m venv venv
# Windows
.\venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

1. Installation dependencies:

pip install -r requirements.txt

Quick Start

Run MCP server

python -m src.server

Configure Claude Desktop

Add:

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"
    }
  }
}

After restarting Claude Desktop, it can be used.

MCP Tool Description

This MCP server provides the following tools:

one create_openapi_spec

Create OpenAPI specification from scratch

parameter:

• title (Required): API Title
• versionAPI version (default: "1.0.0")
• descriptionAPI Description
• api_descriptionsAPI Description List

example:

创建一个名为 "User Service" 的 API,包含以下接口:
- GET /users 获取所有用户
- POST /users 创建用户,需要 name 和 email
- GET /users/{id} 获取特定用户

two add_api_endpoint

Add new endpoints to existing OpenAPI specifications

parameter:

• existing_spec_yaml: Existing OpenAPI YAML
• api_descriptionDescription of the new endpoint
• summary: Optional brief summary
• tags: Optional label list

three generate_from_template

Quickly generate a complete REST API using templates

parameter:

• titleAPI Title
• resource_name: Resource name (such as "user", "product")
• include_crudDoes it include CRUD operations (default: true)
• include_listDoes it include list operations (default: true)
• versionAPI version

example:

为 "Product" 资源生成完整的 REST API

four batch_create_apis

Batch create multiple API endpoints

parameter:

• titleAPI Title
• api_listAPI Description List
• versionAPI version
• descriptionAPI Description

five convert_to_json

Convert YAML format to JSON

six validate_openapi_spec

Verify the correctness of OpenAPI specification

Usage example

Example 1: Creating a User Management API

Enter in 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} - 删除用户

Example 2: Quickly generate using templates

使用模板为 "Order" 资源生成完整的 REST API,版本 2.0.0

Example 3: Adding a new endpoint

在现有的 API 规范中添加一个新端点:
GET /users/{id}/orders 获取用户的所有订单

Integrate with goctl

After generating the OpenAPI specification, it can be directly used for gotl:

# 1. 使用 MCP 生成 OpenAPI 规范并保存为 openapi.yaml

# 2. 使用 goctl 生成 go-zero 代码
goctl api go -api openapi.yaml -dir ./output

Complete workflow

自然语言 API 需求
    ↓
goctl-mcp MCP 服务器 (本项目)
    ↓
OpenAPI 3.0 规范 (YAML/JSON)
    ↓
goctl 工具 (已改造支持 OpenAPI 3.0)
    ↓
go-zero 微服务代码

development

project structure

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              # 本文件

Running example

# 运行基本使用示例
python examples/basic_usage.py

# 运行 MCP 工具使用示例
python examples/mcp_tools_usage.py

Run the test

pytest tests/

code formatting

black src/
ruff check src/

tech stack

• FastMCPLightweight MCP Framework
• Pydantic: Data validation and serialization
• YamlYAML processing
• Python 3.10+Core Language

API Description Grammar Guide

HTTP method recognition

The system will automatically recognize the following keywords:

• 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

path parameter

use {参数名} Format:

GET /users/{id}
GET /orders/{orderId}/items/{itemId}

query parameters

Use keywords with, by, filter, where:

GET /users with name and email filters
GET /products filter by category

request body

Use 'with', 'including', 'contacts' in POST/PUT/PATCH:

POST /users with name, email and phone
PUT /products including title and price

Frequently Asked Questions

Q: How to handle complex request body structures?

A: For complex structures, it is recommended to describe them step by step or use more detailed natural language descriptions. The system will try its best to infer the structure.

Q: Can the generated specifications be modified?

A: Okay! The generated file is standard YAML, which can be manually edited or used add_api_endpoint Tool addition.

Q: Do you support OpenAPI 2.0 (Swagger)?

A: Currently, only OpenAPI 3.0.3 is supported. If conversion is required, third-party tools can be used.

contribution

Welcome to contribute! Please follow the following steps:

1. Fork's own warehouse
2. Create feature branch（git checkout -b feature/AmazingFeature)
3. Submit changes（git commit -m 'Add some AmazingFeature')
4. Push to branch（git push origin feature/AmazingFeature)
5. Open Pull Request

license

MIT License

Contact Information

If you have any questions or suggestions, please submit an issue.

______________________________________________________________________

Enjoy an automated API specification generation experience! 🚀