# 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. 安装

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

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

# 安装依赖
uv pip install -e .
```

### 2. 运行 MCP 服务器

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

# 启动服务器
python3 mcp_swagger_cli.py
```

### 3. 配置到 MCP 客户端

#### Trae 配置示例

```json
{
  "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 配置示例

```json
{
  "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` |

### 鉴权方式配置示例

**无鉴权:**
```json
{
  "SWAGGER_URL": "http://localhost:8080/swagger-ui.html",
  "SWAGGER_NAME": "Dev API",
  "SWAGGER_AUTH_TYPE": "none"
}
```

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

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

**Cookie:**
```json
{
  "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许可证
```

---

## 测试

```bash
# 运行测试
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