# API Testing MCP

一个基于 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 的 **API 自动化测试服务器**。

提供从 API 规范解析、测试场景生成、测试代码生成、测试数据构造、测试执行到 AI 智能审核的**全流程 API 测试能力**，可被 Claude Desktop、Cursor、Cline 等任何 MCP 客户端直接调用。

---

## 功能概览

```
                         ┌──────────────────────────────────────┐
  OpenAPI 3.x ──┐       │          API Testing MCP             │
  Swagger 2.0 ──┤       │                                      │
  Postman      ──┼──────>│  解析 → 生成场景 → 生成代码/数据     │──────> 可执行测试代码
  HAR          ──┘       │           ↓                          │──────> 测试数据集
                         │       执行测试 → AI 审核 → 自动修复   │──────> 测试报告
                         └──────────────────────────────────────┘
```

### 8 个 MCP 工具

| # | 工具 | 功能 |
|---|------|------|
| 1 | `tool_parse_api_spec` | 解析 API 规范 (OpenAPI 3.x / Swagger 2.0 / Postman / HAR) |
| 2 | `tool_generate_test_scenarios` | 生成全面测试场景 (8 大类别，每端点最多 50 个) |
| 3 | `tool_generate_test_code` | 生成可执行测试代码 (Python / JavaScript / TypeScript / cURL) |
| 4 | `tool_generate_test_data` | 用 11 种策略生成测试数据 |
| 5 | `tool_execute_api_test` | 执行单个 API 测试并验证响应 |
| 6 | `tool_run_test_suite` | 批量运行测试套件 (支持并发) |
| 7 | `tool_ai_review` | AI 智能审核 + 自动修复 |
| 8 | `tool_configure` | 配置 AI 模型提供商 / 查看当前配置 |

---

## 快速开始

### 安装

```bash
# 克隆仓库
git clone https://github.com/amyzlp/API-Testing-MCP.git
cd API-Testing-MCP

# 安装 (推荐使用 editable 模式)
pip install -e .

# 如需使用 Anthropic Claude 作为 AI 审核模型
pip install -e ".[anthropic]"
```

### 运行

```bash
# 启动 MCP 服务器
api-testing-mcp

# 或者
python -m api_testing_mcp.server
```

### 在 MCP 客户端中配置

<details>
<summary><b>Claude Desktop</b></summary>

编辑 `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "api-testing": {
      "command": "api-testing-mcp",
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>

在 Settings → MCP Servers 中添加:

```json
{
  "api-testing": {
    "command": "api-testing-mcp",
    "env": {
      "DEEPSEEK_API_KEY": "sk-your-key"
    }
  }
}
```
</details>

<details>
<summary><b>Cline (VS Code)</b></summary>

在 Cline MCP 设置中添加:

```json
{
  "mcpServers": {
    "api-testing": {
      "command": "api-testing-mcp",
      "env": {
        "DEEPSEEK_API_KEY": "sk-your-key"
      }
    }
  }
}
```
</details>

---

## 工具详解

### 1. `tool_parse_api_spec` — 解析 API 规范

支持 4 种格式的 API 规范，解析为统一的结构化数据:

| 格式 | 支持版本 |
|------|---------|
| OpenAPI | 3.0.x, 3.1.x |
| Swagger | 2.0 |
| Postman Collection | v2.x |
| HAR (HTTP Archive) | 1.2 |

**参数:**
- `spec_content` — API 规范的 JSON 或 YAML 字符串

**返回:** 结构化的 API 信息，包含端点、参数、请求体、响应、安全方案等。

---

### 2. `tool_generate_test_scenarios` — 生成测试场景

根据 API 规范自动生成覆盖全面的测试场景:

| 类别 | 说明 |
|------|------|
| `happy_path` | 正常流程 — 必填参数、全部参数、示例值 |
| `input_validation` | 输入验证 — 缺少必填字段、类型错误、无效枚举 |
| `boundary` | 边界值 — 最小值/最大值/溢出/空字符串 |
| `error_handling` | 错误处理 — 404 资源不存在、405 方法错误、415 类型错误 |
| `security` | 安全测试 — SQL 注入、XSS、路径穿越、命令注入、SSRF |
| `authentication` | 认证测试 — 无凭证、无效 Token、过期 Token |
| `edge_case` | 边缘用例 — 特殊字符、未知参数、Unicode |
| `idempotency` | 幂等性 — PUT/DELETE 重复请求一致性 |

**参数:**
- `spec_content` — API 规范
- `categories` — 要生成的类别 (逗号分隔，留空为全部)
- `max_per_endpoint` — 每端点最大场景数 (默认 50)
- `endpoint_filter` — 端点路径过滤

---

### 3. `tool_generate_test_code` — 生成测试代码

将测试场景转换为可直接运行的测试代码:

| 语言 | 框架 | 运行方式 |
|------|------|---------|
| Python | pytest + requests | `pytest test_api.py -v` |
| JavaScript | Node.js + fetch | `node test_api.js` |
| TypeScript | vitest + fetch | `npx vitest run test_api.ts` |
| cURL | Bash 脚本 | `bash test_api.sh` |

**参数:**
- `spec_content` — API 规范
- `language` — 目标语言 (`python` / `javascript` / `typescript` / `curl`)
- `auth_type` — 认证类型 (`bearer` / `basic` / `api_key`)
- `auth_token` — 认证令牌

---

### 4. `tool_generate_test_data` — 生成测试数据

用 11 种策略自动生成测试数据集:

| 策略 | 说明 |
|------|------|
| `valid` | 有效数据 — 符合类型和约束 |
| `boundary` | 边界值 — 最小/最大/临界值 |
| `invalid` | 无效数据 — 类型错误的值 |
| `random` | 随机数据 — 随机生成 |
| `realistic` | 仿真数据 — 类似真实生产数据 |
| `sql_injection` | SQL 注入载荷 |
| `xss` | XSS 攻击载荷 |
| `empty` | 空值 — 空字符串/零/空数组 |
| `null` | Null 值 |
| `overflow` | 溢出值 — 超大字符串/极限数字 |
| `unicode` | Unicode — 中日韩文字/Emoji/零宽字符 |

---

### 5. `tool_execute_api_test` — 执行单个测试

发送 HTTP 请求并验证响应:

- 支持所有 HTTP 方法 (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS)
- 支持 Bearer / Basic / API Key 认证
- 自动断言: 状态码、响应体内容、响应时间
- 返回完整的请求/响应详情和断言结果

---

### 6. `tool_run_test_suite` — 运行测试套件

一键解析规范 → 生成场景 → 批量执行:

- 支持并发请求 (默认 5 并发)
- 按类别/优先级分组统计
- 输出通过率、响应时间、详细断言结果

---

### 7. `tool_ai_review` — AI 智能审核

**双层审核机制:**

```
┌─────────────────────────────────────────┐
│  第一层: 程序化检查 (始终运行)             │
│  ├── 覆盖率分析 (缺失分类检测)            │
│  ├── 一致性验证 (状态码逻辑检查)           │
│  ├── 安全检测 (凭证泄露/硬编码检查)        │
│  ├── 类型检查 (参数类型匹配验证)           │
│  └── 代码质量 (断言完整性/错误处理)        │
├─────────────────────────────────────────┤
│  第二层: AI 深度审查 (可选，需配置模型)     │
│  ├── 遗漏测试用例识别                     │
│  ├── 不合理参数值检测                     │
│  ├── 冗余/重复场景发现                    │
│  └── 安全测试完整性评估                   │
├─────────────────────────────────────────┤
│  自动修复: 最小化调整                      │
│  ├── 修正不一致的状态码                    │
│  ├── 替换硬编码凭证为环境变量              │
│  ├── 修正类型不匹配的参数                  │
│  └── 替换疑似真实密钥为占位符              │
└─────────────────────────────────────────┘
```

**审核对象:**
- `scenario` — 测试场景
- `test_code` — 测试代码
- `test_data` — 测试数据
- `parameter` — 请求参数

**返回:** 评分 (0-100)、问题列表、修复建议、自动修复后的内容。

---

### 8. `tool_configure` — 配置管理

运行时查看和修改 AI 模型配置:

```
# 查看当前配置
tool_configure(action="show")

# 列出所有支持的提供商
tool_configure(action="providers")

# 设置提供商
tool_configure(action="set", provider="deepseek", api_key="sk-xxx")
```

---

## AI 模型配置

AI 审核功能支持 **17 个模型提供商**，涵盖国际模型、国内大模型和本地部署:

### 支持的提供商

| 分类 | 提供商 | 标识 | 环境变量 | 默认模型 |
|------|--------|------|---------|---------|
| 国际 | OpenAI | `openai` | `OPENAI_API_KEY` | gpt-4o |
| 国际 | Anthropic | `anthropic` | `ANTHROPIC_API_KEY` | claude-sonnet-4-20250514 |
| 国内 | 通义千问/Qwen | `qwen` | `DASHSCOPE_API_KEY` | qwen-plus |
| 国内 | 智谱 AI/GLM | `zhipu` | `ZHIPU_API_KEY` | glm-4-plus |
| 国内 | DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | deepseek-chat |
| 国内 | Moonshot/Kimi | `moonshot` | `MOONSHOT_API_KEY` | moonshot-v1-8k |
| 国内 | 零一万物/Yi | `yi` | `YI_API_KEY` | yi-large |
| 国内 | 百川/Baichuan | `baichuan` | `BAICHUAN_API_KEY` | Baichuan4 |
| 国内 | 文心一言/ERNIE | `ernie` | `ERNIE_API_KEY` | ernie-4.0-8k |
| 国内 | 豆包/Doubao | `doubao` | `DOUBAO_API_KEY` | doubao-pro-32k |
| 国内 | MiniMax | `minimax` | `MINIMAX_API_KEY` | abab6.5s-chat |
| 国内 | 阶跃星辰 | `stepfun` | `STEPFUN_API_KEY` | step-2-16k |
| 本地 | Ollama | `ollama` | 不需要 | llama3.1 |
| 本地 | LM Studio | `lmstudio` | 不需要 | local-model |
| 本地 | vLLM | `vllm` | 不需要 | default |
| 本地 | LocalAI | `localai` | 不需要 | gpt-4 |
| 本地 | llama.cpp | `llamacpp` | 不需要 | default |

> 所有国内模型均通过 **OpenAI 兼容 API** 接入，无需额外适配。

### 配置方式

#### 方式一: 环境变量 (推荐)

只需设置一个提供商的 API Key，系统自动识别:

```bash
# 使用 DeepSeek (推荐，性价比高)
export DEEPSEEK_API_KEY=sk-xxx

# 使用通义千问
export DASHSCOPE_API_KEY=sk-xxx

# 使用 OpenAI
export OPENAI_API_KEY=sk-xxx
```

如需指定模型:

```bash
export AI_PROVIDER=deepseek
export AI_MODEL=deepseek-chat
export DEEPSEEK_API_KEY=sk-xxx
```

#### 方式二: 本地模型 (不需要 API Key)

```bash
# Ollama
export AI_PROVIDER=ollama
export AI_MODEL=qwen2.5    # 或 llama3.1, deepseek-v2, etc.

# LM Studio
export AI_PROVIDER=lmstudio

# vLLM
export AI_PROVIDER=vllm
export AI_BASE_URL=http://localhost:8000/v1
```

#### 方式三: .env 文件

```bash
cp .env.example .env
# 编辑 .env 填入配置
```

#### 方式四: MCP 客户端配置

在 Claude Desktop / Cursor 的 MCP 配置中直接传入:

```json
{
  "mcpServers": {
    "api-testing": {
      "command": "api-testing-mcp",
      "env": {
        "AI_PROVIDER": "deepseek",
        "DEEPSEEK_API_KEY": "sk-xxx"
      }
    }
  }
}
```

#### 方式五: 运行时动态配置

通过 `tool_configure` 工具在对话中直接设置:

```
tool_configure(action="set", provider="qwen", api_key="sk-xxx")
```

> **注意:** 不配置 AI 模型不影响使用。AI 审核为可选功能，未配置时 `tool_ai_review` 仍会执行程序化检查并返回结果。

---

## 项目结构

```
API-Testing-MCP/
├── pyproject.toml                  # 项目配置与依赖
├── .env.example                    # 环境变量配置模板
└── src/api_testing_mcp/
    ├── server.py                   # MCP 服务器入口 (8 个工具注册)
    ├── types.py                    # Pydantic 数据模型 (20+ 类型定义)
    ├── utils.py                    # 工具函数 (值生成/边界计算/安全载荷)
    ├── llm_client.py               # LLM 统一调用层 (17 提供商适配)
    └── tools/
        ├── parse_spec.py           # API 规范解析 (4 种格式)
        ├── generate_scenarios.py   # 测试场景生成 (8 大类别)
        ├── generate_code.py        # 测试代码生成 (4 种语言)
        ├── generate_data.py        # 测试数据生成 (11 种策略)
        ├── execute_test.py         # 测试执行引擎 (异步并发)
        └── review.py               # AI 审核层 (双层检查 + 自动修复)
```

---

## 使用示例

### 示例 1: 从 OpenAPI 规范生成完整测试

```
用户: 解析这个 API 规范，生成测试场景和 Python 测试代码

→ tool_parse_api_spec(spec_content=<OpenAPI YAML>)
→ tool_generate_test_scenarios(spec_content=<spec>, categories="happy_path,security")
→ tool_generate_test_code(spec_content=<spec>, language="python", auth_type="bearer")
→ tool_ai_review(target_type="test_code", content=<生成的代码>)
```

### 示例 2: 生成安全测试数据

```
用户: 给 /api/users POST 端点生成 SQL 注入和 XSS 测试数据

→ tool_generate_test_data(spec_content=<spec>, strategies="sql_injection,xss", endpoint_filter="/users")
→ tool_ai_review(target_type="test_data", content=<生成的数据>)
```

### 示例 3: 直接测试一个 API

```
用户: 测试一下 https://httpbin.org/get 返回 200

→ tool_execute_api_test(url="https://httpbin.org/get", method="GET", expected_status=200)
```

### 示例 4: 运行完整测试套件

```
用户: 对这个 API 规范运行完整测试

→ tool_run_test_suite(spec_content=<spec>, categories="happy_path,error_handling,security")
```

---

## 技术栈

| 组件 | 技术选型 |
|------|---------|
| MCP 框架 | [FastMCP](https://github.com/modelcontextprotocol/python-sdk) |
| 数据模型 | [Pydantic v2](https://docs.pydantic.dev/) |
| HTTP 客户端 | [httpx](https://www.python-httpx.org/) (异步) |
| YAML 解析 | [PyYAML](https://pyyaml.org/) |
| LLM 调用 | [OpenAI SDK](https://github.com/openai/openai-python) (兼容协议) + [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-python) (可选) |
| Python 版本 | >= 3.10 |

---

## 开发

```bash
# 克隆并安装开发环境
git clone https://github.com/amyzlp/API-Testing-MCP.git
cd API-Testing-MCP
pip install -e ".[all]"

# 运行服务器
api-testing-mcp

# 直接测试模块
python -c "
from api_testing_mcp.tools.parse_spec import parse_api_spec
from api_testing_mcp.tools.generate_scenarios import generate_test_scenarios
import json

spec = parse_api_spec(json.dumps({
    'openapi': '3.0.0',
    'info': {'title': 'Demo', 'version': '1.0'},
    'paths': {'/users': {'get': {'responses': {'200': {'description': 'ok'}}}}}
}))
scenarios = generate_test_scenarios(spec)
print(f'生成了 {len(scenarios)} 个测试场景')
"
```

---

## 许可证

MIT