MCP Swagger Tools

<p align="center"> <img src="https://img.shields.io/badge/MCP-Swagger%20Tools-green" alt="MCP"> <img src="https://img.shields.io/badge/Python-3.10+-blue" alt="Python"> <img src="https://img.shields.io/badge/License-MIT-yellow" alt="License"> </p>

🤖 MCP (Model Context Protocol) 工具 - 自动解析 Swagger/OpenAPI 文档，生成前端代码，测试 API 接口

功能特性

🔧 配置管理

• 支持配置多个 Swagger 地址
• 支持多种鉴权方式：Basic Auth、Bearer Token、Cookie
• 自动校验配置有效性

📡 接口解析

• 自动解析 Swagger 2.0 / OpenAPI 3.0 文档
• 按模块/标签分组展示接口
• 支持搜索和筛选接口
• 解析结果缓存，避免重复请求

💬 对话式指令

• 自然语言理解指令
• 核心指令支持：
  • "列出所有接口"
  • "获取xxx接口"
  • "封装xxx接口为Vue3代码"
  • "生成xxx列表页"
  • "测试xxx接口"

🎨 前端代码生成

• 支持 Vue3 (Composition API)、React、原生 JavaScript
• 自动生成 TypeScript 类型
• 包含请求拦截器和错误处理
• 可复制的代码片段

📄 页面生成

• 自动生成列表页、详情页、表单页
• 适配 Element Plus、Ant Design
• 包含搜索、分页、CRUD 操作

🧪 接口测试

• 在线测试解析后的接口
• 支持自定义参数和请求体
• 实时查看响应结果

---

快速开始

1. 安装

# 克隆项目
cd /path/to/workspace

# 创建虚拟环境
uv venv
source .venv/bin/activate

# 安装依赖
uv pip install -e .

2. 运行 MCP 服务器

# 激活虚拟环境
source .venv/bin/activate

# 启动服务器
python3 mcp_swagger_cli.py

3. 配置到 MCP 客户端

Trae 配置示例

{
  "mcpServers": {
    "swagger-tools": {
      "command": "python3",
      "args": ["/path/to/mcp-swagger-tools/mcp_swagger_cli.py"],
      "env": {
        "SWAGGER_URL": "https://petstore.swagger.io/v2/swagger.json",
        "SWAGGER_NAME": "PetStore",
        "SWAGGER_AUTH_TYPE": "none"
      },
      "cwd": "/path/to/mcp-swagger-tools"
    }
  }
}

Cursor 配置示例

{
  "mcpServers": {
    "swagger-tools": {
      "command": "python3",
      "args": ["/path/to/mcp-swagger-tools/mcp_swagger_cli.py"],
      "env": {
        "SWAGGER_URL": "http://your-api.com/swagger-ui.html",
        "SWAGGER_NAME": "My API",
        "SWAGGER_AUTH_TYPE": "bearer",
        "SWAGGER_TOKEN": "your-token-here"
      },
      "cwd": "/path/to/mcp-swagger-tools"
    }
  }
}

---

环境变量配置

变量	说明	必填	示例
SWAGGER_URL	Swagger 文档地址	✅	http://localhost:8080/swagger-ui.html
SWAGGER_NAME	配置名称	❌	My API
SWAGGER_AUTH_TYPE	鉴权方式	❌	none, basic, bearer, cookie
SWAGGER_USERNAME	用户名 (basic auth)	❌	admin
SWAGGER_PASSWORD	密码 (basic auth)	❌	123456
SWAGGER_TOKEN	Token (bearer auth)	❌	eyJhbGciOiJIUzI1NiIs...
SWAGGER_COOKIE	Cookie (cookie auth)	❌	SESSION=abc123

鉴权方式配置示例

无鉴权:

{
  "SWAGGER_URL": "http://localhost:8080/swagger-ui.html",
  "SWAGGER_NAME": "Dev API",
  "SWAGGER_AUTH_TYPE": "none"
}

Basic Auth:

{
  "SWAGGER_URL": "http://localhost:8080/swagger-ui.html",
  "SWAGGER_NAME": "Dev API",
  "SWAGGER_AUTH_TYPE": "basic",
  "SWAGGER_USERNAME": "admin",
  "SWAGGER_PASSWORD": "admin123"
}

Bearer Token:

{
  "SWAGGER_URL": "http://api.example.com/v3/api-docs",
  "SWAGGER_NAME": "Production API",
  "SWAGGER_AUTH_TYPE": "bearer",
  "SWAGGER_TOKEN": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Cookie:

{
  "SWAGGER_URL": "http://api.example.com/swagger-ui.html",
  "SWAGGER_NAME": "Internal API",
  "SWAGGER_AUTH_TYPE": "cookie",
  "SWAGGER_COOKIE": "JSESSIONID=abc123; UserID=admin"
}

---

MCP 工具列表

工具	说明	示例
list_configs	列出所有配置	list_configs
add_config	添加新配置	add_config(url="...")
delete_config	删除配置	delete_config(config_id=0)
parse_swagger	解析接口文档	parse_swagger()
search_endpoints	搜索接口	search_endpoints(query="user")
generate_api_code	生成 API 代码	generate_api_code(endpoint_path="/api/users", method="get", framework="vue3")
generate_page	生成页面代码	generate_page(endpoint_path="/api/users", method="get", page_type="list")
test_endpoint	测试接口	test_endpoint(endpoint_path="/api/users", method="get")
execute_command	执行自然语言指令	execute_command(command="列出所有接口")

---

使用示例

列出所有接口

用户: 列出所有接口
助手: 📚 Swagger Petstore v1.0.7
     🔗 https://petstore.swagger.io/v2
     
     ### pet (9 endpoints)
       POST   /pet/{petId}/uploadImage - uploads an image
       POST   /pet - Add a new pet to the store
       PUT    /pet - Update an existing pet
       GET    /pet/findByStatus - Finds Pets by status
       ...

生成前端代码

用户: 封装findByStatus接口为vue3代码
助手: ```typescript
     // Swagger Petstore - API
     // Generated by MCP Swagger Tools
     
     import { ref } from 'vue'
     import axios from 'axios'
     
     const apiClient = axios.create({
       baseURL: 'https://petstore.swagger.io/v2',
       timeout: 30000,
       ...
     ```

生成页面

用户: 生成宠物列表页
助手: ```vue
     <template>
       <div class="findByStatus-page">
         <!-- Table -->
         <el-table :data="tableData" v-loading="loading" border>
           ...
     ```

测试接口

用户: 测试findByStatus接口
助手: ✅ Success (200, 1939ms)
     ```json
     [
       {"id": 1, "name": "doggie", "status": "available"},
       {"id": 2, "name": "doggie 2", "status": "available"},
       ...
     ]
     ```

---

依赖

• Python >= 3.10
• mcp >= 1.0.0
• httpx >= 0.27.0
• openapi-spec-validator >= 0.7.0
• pyyaml >= 6.0
• jinja2 >= 3.1.0

---

项目结构

mcp-swagger-tools/
├── mcp_swagger/
│   ├── __init__.py       # 包入口
│   ├── config.py         # 配置管理
│   ├── parser.py         # Swagger解析
│   ├── generator.py      # 代码生成
│   ├── executor.py       # API执行
│   ├── commands.py      # 指令解析
│   └── server.py        # MCP服务器
├── tests/               # 测试
├── pyproject.toml       # 项目配置
├── README.md           # 文档
└── LICENSE             # MIT许可证

---

测试

# 运行测试
python3 -m pytest tests/ -v

# 运行特定测试
python3 -m pytest tests/test_core.py::TestCodeGenerator -v

---

License

MIT License - see LICENSE file for details

---

🤖 Generated by MCP Swagger Tools