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. 安装依赖

cd springboot-test-mcp
pip install -e .

或直接安装：

pip install httpx "mcp[cli]>=1.6.0" oracledb python-dotenv jmespath

2. 配置环境变量

复制 .env.example 为 .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：

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

或在 Claude Code 中运行：

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 (性能测试)