# fe-testgen-mcp

基于 MCP 协议的前端单元测试生成服务，专注于 AI 分析和代码生成能力。通过 HTTP Streaming 暴露 MCP 工具，可与 n8n、Cursor、Claude 等客户端集成。

## 核心能力

- **测试矩阵分析**：分析代码变更，生成功能清单和测试场景
- **测试代码生成**：基于矩阵生成完整的单元测试代码
- **多框架支持**：支持 Vitest 和 Jest
- **多场景覆盖**：happy-path、edge-case、error-path、state-change

## 快速开始

```bash
# 安装依赖
pnpm install

# 构建
pnpm build

# 启动服务
pnpm start
```

服务默认监听 `http://localhost:3000/mcp`

## 环境配置

复制 `env.example` 为 `.env` 并填写必要配置：

```bash
# 必需：OpenAI API 密钥
OPENAI_API_KEY=your_api_key

# 可选：自定义模型
OPENAI_MODEL=gpt-4

# 可选：服务配置
HTTP_PORT=3000
HTTP_HOST=0.0.0.0  # 允许外部访问
```

## MCP 工具

### analyze-test-matrix

分析代码变更，生成测试矩阵。

**参数**：
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| rawDiff | string | ✅ | Unified diff 格式文本 |
| identifier | string | | 唯一标识符（MR ID、commit hash） |
| rules | string | | test-strategy.md 内容 |
| framework | string | | 测试框架（vitest/jest） |

**返回**：功能清单、测试场景、统计信息

### generate-tests

生成单元测试代码。

**参数**：
| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| rawDiff | string | ✅ | Unified diff 格式文本 |
| identifier | string | | 唯一标识符 |
| rules | string | | test-strategy.md 内容 |
| framework | string | | 测试框架 |
| scenarios | string[] | | 指定场景类型 |
| maxTests | number | | 最大测试数量 |

**返回**：测试用例数组（包含文件路径、代码、场景类型）

## n8n 集成

### 工作流示例

```
GitLab/Phabricator Webhook
    │
    ▼
读取 diff + rules 文件
    │
    ▼
调用 MCP generate-tests
    │
    ▼
写入测试文件 + 创建 MR
    │
    ▼
发送通知（企微/飞书）
```

### HTTP 调用示例

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "generate-tests",
      "arguments": {
        "rawDiff": "diff --git a/src/utils.ts ...",
        "framework": "vitest"
      }
    }
  }'
```

## rules 文件格式

在项目中创建 `.cursor/rules/test-strategy.md`：

```markdown
# 测试生成规则

## 测试框架配置
- **测试框架**：vitest
- **测试文件模式**：**/*.{test,spec}.{ts,tsx}

## Mock 策略
- 使用 vi.fn() 进行函数 mock
- HTTP 请求优先 mock fetch/axios
```

n8n 读取此文件内容，作为 `rules` 参数传给 MCP。

## Docker 部署

```bash
docker build -t fe-testgen-mcp .
docker run -d -p 3000:3000 \
  -e OPENAI_API_KEY=xxx \
  fe-testgen-mcp
```

## 常见问题

**Q: 如何提高生成结果的一致性？**

A: 服务默认使用 `temperature=0` 和固定 `seed=42`，同时启用响应缓存。

**Q: 如何指定测试框架？**

A: 优先级：`framework` 参数 > `rules` 中解析 > 默认 vitest

**Q: 需要 Node.js 版本？**

A: Node.js 18+（推荐 20+）