内容
# kiwi-tcms-mcp
一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器，暴露 [Kiwi TCMS](https://kiwitcms.org/) 作为一组 AI 调用工具。它允许 AI 助手（例如 Kiro、Cursor、Claude Desktop）直接从对话中创建和管理测试计划、测试用例、测试运行和执行。
## 功能
服务器注册以下工具：
### 产品和版本
| 工具 | 描述 |
|---|---|
| `kiwi_list_products` | 列出所有产品 |
| `kiwi_list_versions` | 列出某个产品的版本 |
### 测试计划
| 工具 | 描述 |
|---|---|
| `kiwi_list_test_plans` | 列出测试计划，可选按产品过滤 |
| `kiwi_create_test_plan` | 创建新的测试计划 |
| `kiwi_update_test_plan` | 更新计划名称、描述或停用 |
| `kiwi_add_case_to_plan` | 将现有的测试用例添加到计划 |
| `kiwi_remove_case_from_plan` | 从计划中取消链接测试用例 |
### 测试用例
| 工具 | 描述 |
|---|---|
| `kiwi_list_test_cases` | 列出测试计划中的测试用例 |
| `kiwi_get_test_case` | 获取完整的详细信息（步骤、备注、优先级、标签） |
| `kiwi_create_test_case` | 创建具有步骤、导航、角色、优先级和格式的测试用例 |
| `kiwi_update_test_case` | 更新现有的测试用例 |
| `kiwi_disable_test_case` | 禁用不再相关的测试用例 |
### 标签
| 工具 | 描述 |
|---|---|
| `kiwi_add_tag` | 为测试用例添加一个或多个标签 |
| `kiwi_remove_tag` | 从测试用例中删除标签 |
| `kiwi_list_tags` | 列出测试用例上的所有标签 |
### 测试运行和执行
| 工具 | 描述 |
|---|---|
| `kiwi_list_builds` | 列出某个产品版本的构建 |
| `kiwi_create_build` | 为某个版本创建新的构建 |
| `kiwi_create_test_run` | 从测试计划创建测试运行（活动） |
| `kiwi_list_test_runs` | 列出测试运行，可选按计划过滤 |
| `kiwi_list_test_executions` | 列出运行中的执行及其状态 |
| `kiwi_update_test_execution` | 将执行标记为通过、失败、阻塞、豁免、错误或空闲 |
| `kiwi_add_execution_comment` | 为测试执行添加备注 |
## 测试用例格式化
测试用例支持通过 `format` 参数的两种输出格式：
- **`table`** （默认）— HTML 表格，包含步骤编号、操作、预期行为列，以及导航和角色标题
- **`list`** — 粗体标签样式（步骤 1：/ 操作：/ 预期结果：）
附加字段：
- `navigation` — 到达屏幕的路径（例如“登录 → 菜单 → 每日烤箱”）
- `role` — 测试的用户角色（例如“销售经理（SM）”）
- `priority` — P1（最高）到 P4（最低），默认为 P2
- `notes` — 存储在 Kiwi 的专用备注字段中（不嵌入文本正文中）
## 需求
- Node.js 18+
- 运行的 Kiwi TCMS 实例（自托管或云）
## 安装
```bash
npm install
```
这将安装 `@modelcontextprotocol/sdk`、`node-fetch`、`dotenv` 和 `zod`。
## 配置
服务器通过环境变量配置。您可以在命令行设置它们，通过您的 MCP 配置，或在项目根目录中创建 `.env` 文件（通过 [dotenv](https://www.npmjs.com/package/dotenv) 自动加载）：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `KIWI_URL` | （必填） | 您的 Kiwi TCMS 实例的基本 URL |
| `KIWI_USERNAME` | （空） | 登录用户名 |
| `KIWI_PASSWORD` | （空） | 登录密码 |
### 使用 `.env` 文件
在项目根目录中创建 `.env` 文件：
```env
KIWI_URL=https://your-kiwi-instance
KIWI_USERNAME=your_user
KIWI_PASSWORD=your_pass
```
> `.env` 文件默认被 git 忽略。永远不要提交凭证。
> 自签名 TLS 证书将自动接受，这对于自托管实例非常有用。
## 用法
### 直接运行服务器
```bash
npm start
```
或使用命令行环境变量（如果不使用 `.env`）：
```bash
KIWI_URL=https://your-kiwi-instance \
KIWI_USERNAME=your_user \
KIWI_PASSWORD=your_pass \
npm start
```
服务器通过 **stdio** 使用 MCP 协议进行通信。
### Kiro / Cursor / Claude Desktop 集成
将服务器添加到您的 MCP 配置文件（例如 `.kiro/settings/mcp.json`、`~/.cursor/mcp.json` 或 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"kiwi-tcms": {
"command": "node",
"args": ["/absolute/path/to/kiwi-tcms-mcp/src/index.js"],
"env": {
"KIWI_URL": "https://your-kiwi-instance",
"KIWI_USERNAME": "your_user",
"KIWI_PASSWORD": "your_pass"
}
}
}
}
```
配置完成后，您可以要求 AI 用自然语言创建测试计划和用例：
> “为 ADS-1697 生成测试用例，并将它们推送到 Kiwi TCMS 下的 AWA 产品。”
## Cursor AI 技能
`skills/kiwi-tcms-test-generation/SKILL.md` 中包含一个现成的 [Cursor 代理技能](https://docs.cursor.com/context/rules-for-ai)。安装后，您可以要求 Cursor 通过单个提示从功能分支生成并推送完整的测试计划。
### 技能功能
- 读取您的 PRD、设计文档和实施计划
- 提取测试场景（快乐路径、边缘情况、访问控制、回归）
- 通过 MCP 工具将测试用例推送到 Kiwi TCMS
- 支持**新生成**和**文档更改后更新**
### 安装
**1. 将技能复制到 Cursor 全局技能文件夹：**
```bash
mkdir -p ~/.agents/skills/kiwi-tcms-test-generation
cp skills/kiwi-tcms-test-generation/SKILL.md \
~/.agents/skills/kiwi-tcms-test-generation/SKILL.md
```
**2. 编辑复制的文件并替换所有占位符** （搜索 `<REPLACE_`）：
| 占位符 | 描述 | 示例 |
|---|---|---|
| `<REPLACE_KIWI_URL>` | 您的 Kiwi TCMS 实例的基本 URL | `https://tcms.example.com` |
| `<REPLACE_MCP_SERVER_PATH>` | 您机器上 `src/index.js` 的绝对路径 | `/home/alice/kiwi-tcms-mcp/src/index.js` |
**3. 确保 MCP 服务器已在您的 IDE 的 MCP 配置中注册** （参见上面的集成部分）。
**4. 重启您的 IDE** 以获取技能和 MCP 服务器。
### 用法
安装完成后，使用自然语言提示触发它：
> “为 ADS-1234 生成测试并将它们推送到 Kiwi TCMS。”
> “在 ADS-1234 的 PRD 更改后更新 Kiwi 测试。”
## 项目结构
```
src/
index.js # MCP 服务器 — 工具定义和 JSON-RPC 帮助程序
skills/
kiwi-tcms-test-generation/
SKILL.md # AI 技能模板（复制到 ~/.agents/skills/）
package.json
```
## 工作原理
1. 在第一次工具调用时，服务器使用 `Auth.login` 进行身份验证并存储会话 cookie。
2. 之后的每次调用都会重用该会话 — 无需重新登录。
3. 工具通过 Kiwi TCMS [JSON-RPC API](https://kiwitcms.readthedocs.io/en/latest/api/index.html) (`POST /json-rpc/`) 与 Kiwi TCMS 通信。
4. 测试用例内容（步骤、前置条件）存储在 `text` 字段中作为格式化的 HTML（表格或列表格式）。
5. 备注和优先级使用 Kiwi 的专用字段，而不是嵌入在文本正文中。
