# Spring Boot Test MCP Server

一个 MCP (Model Context Protocol) 服务器，为 Claude Code 提供 Spring Boot REST API 的**功能测试**和**性能测试**能力。

## 核心功能

### 🧪 功能测试
- **call_api** — 调用 REST API，获取完整响应
- **assert_response** — 多维度断言（状态码、JSON 字段、响应时间等）
- **run_functional_tests** — 批量执行测试用例，支持 setup/teardown SQL
- **query_database** — 查询 Oracle 数据库验证数据正确性
- **execute_dml** — 准备/清理测试数据

### 🔥 性能测试
- **run_perf_test** — 可配置并发数和时长的负载测试
- **run_stress_test** — 逐步增加压力的阶梯压测，定位性能拐点

### 📋 辅助工具
- **discover_api_endpoints** — 自动发现 Spring Boot API 端点（Actuator 或源码扫描）
- **get_test_report** — 获取测试报告
- **check_config** — 检查配置和连接状态
- **reset_test_session** — 重置测试会话

## 快速开始

### 1. 安装依赖

```bash
cd springboot-test-mcp
pip install -e .
```

或直接安装：
```bash
pip install httpx "mcp[cli]>=1.6.0" oracledb python-dotenv jmespath
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env`，填入你的配置：

```env
TARGET_BASE_URL=http://localhost:8080
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SERVICE=ORCL
ORACLE_USER=your_user
ORACLE_PASSWORD=your_password
```

### 3. 配置 Claude Code

在项目根目录创建 `.claude/settings.json`：

```json
{
  "mcpServers": {
    "springboot-test": {
      "command": "python",
      "args": ["/absolute/path/to/springboot-test-mcp/main.py"]
    }
  }
}
```

或在 Claude Code 中运行：
```bash
claude mcp add springboot-test -- python /absolute/path/to/springboot-test-mcp/main.py
```

### 4. 启动被测服务后使用

在 Claude Code 中：

```
# 检查配置
> check_config

# 发现 API
> discover_api_endpoints

# 功能测试
> call_api(method="GET", path="/api/users")
> run_functional_tests(test_cases=[{
    "name": "创建用户",
    "method": "POST",
    "path": "/api/users",
    "body": {"name": "Alice", "email": "alice@test.com"},
    "assertions": [
      {"target": "status_code", "operator": "eq", "expected": 201},
      {"target": "json_path", "json_path": "name", "operator": "eq", "expected": "Alice"}
    ]
  }])

# 性能测试
> run_perf_test(name="用户列表压测", method="GET", path="/api/users",
                concurrency=50, duration_seconds=30)

# 阶梯压测
> run_stress_test(name="用户API压测", method="GET", path="/api/users",
                  max_concurrency=200, step_size=50, step_duration_seconds=30)

# 数据库验证
> query_database(sql="SELECT * FROM users WHERE name='Alice'")
```

## 项目结构

```
springboot-test-mcp/
├── main.py                  # 入口
├── server.py                # MCP Tool 定义（所有工具）
├── config.py                # 配置管理
├── core/
│   ├── __init__.py          # HTTP 客户端（httpx）
│   ├── assertion_engine.py  # 断言引擎
│   ├── test_runner.py       # 功能测试执行器
│   └── perf_engine.py       # 性能测试引擎（asyncio 并发）
├── db/
│   ├── __init__.py          # Oracle 连接器（oracledb thin mode）
│   └── oracle_connector.py  # 别名
├── discovery/
│   └── __init__.py          # API 发现（Actuator + 源码扫描）
├── models/
│   └── __init__.py          # 数据模型
├── .env.example             # 环境变量模板
└── claude_desktop_config.json  # Claude 配置参考
```

## 支持的断言

| target | 说明 | 示例 |
|--------|------|------|
| status_code | HTTP 状态码 | `{"target": "status_code", "operator": "eq", "expected": 200}` |
| json_path | JSON 字段（JMESPath） | `{"target": "json_path", "json_path": "data.name", "operator": "eq", "expected": "Alice"}` |
| response_time | 响应时间(ms) | `{"target": "response_time", "operator": "lt", "expected": 500}` |
| body | 完整响应体 | `{"target": "body", "operator": "contains", "expected": "success"}` |
| header | 响应头 | `{"target": "header", "operator": "contains", "expected": "application/json"}` |

| operator | 说明 |
|----------|------|
| eq / neq | 等于 / 不等于 |
| gt / lt / gte / lte | 大于 / 小于 / 大于等于 / 小于等于 |
| contains / not_contains | 包含 / 不包含 |
| matches | 正则匹配 |
| exists / not_exists | 存在 / 不存在 |

## 性能测试指标

- 总请求数、成功/失败数
- 错误率 (%)
- 吞吐量 (req/s)
- 延迟分布：Avg / Min / Max / Median / P90 / P95 / P99
- 状态码分布
- 阶梯压测自动识别性能拐点

## 技术栈

- **MCP SDK**: `mcp[cli]` (Python FastMCP)
- **HTTP Client**: httpx (异步)
- **Oracle**: oracledb (thin mode，无需 Oracle Client)
- **JSON Path**: jmespath
- **并发**: asyncio (性能测试)