zhice-mcp

智测（产品代码 zhice，编号 4800）MCP stdio 服务，供 Cursor / AI Agent 通过 MCP 协议调用测试闭环能力。

本服务通过 stdio 与 MCP 客户端通信，将工具调用转发至 zhice-server 的内网 MCP API（/internal/mcp/v1/*）。

前置条件

1. 已启动 zhice-server（本地 dev profile，端口 4802；测试 test profile，端口 4812）
2. Node.js 18+（需支持原生 fetch）

安装与构建

cd zhice-mcp
npm install
npm run build              # 烘焙三套地址，默认环境 development
npm run build:test         # 同上，默认环境 test
npm run build:production   # 同上，默认环境 production（npm publish 自动执行）

构建会把 .env.development / .env.test / .env.production 三套 BIGAPP_API_BASE 全部写入产物；构建命令只决定「未设置运行时环境变量时」的默认环境。运行时可用 BIGAPP_ENV 切换，无需重新打包。

构建产物位于 dist/index.js。

环境文件

| 文件 | 对应环境 | 说明 | |------|----------|------| | .env.development | development | 本地 dev，后端 4802 | | .env.test | test | 测试环境 | | .env.production | production | 生产环境 |

各文件中的 BIGAPP_API_BASE 为智测 MCP 内网 API 根地址（不含 /internal/mcp/v1 后缀）：

| 环境 | 示例值 | 说明 | |------|--------|------| | 本地 dev | http://127.0.0.1:4802 | 直连 zhice-server，无 /api 前缀 | | 测试 | https://zhice.test.atbigapp.com/api | 经 nginx 同域代理，须带 /api | | 生产 | https://zhice.atbigapp.com/api | 经 nginx 同域代理，须带 /api |

代码会在公网域名未写 /api 时自动补全（兼容旧配置）；直连 4802/4812/4822 端口不会追加。

运行时环境变量（Cursor MCP 配置）

与智忆 MCP 命名一致：

| 变量 | 说明 | 是否必填 | |------|------|----------| | BIGAPP_API_KEY | 工作空间签发的 Agent 密钥 | 必填 | | BIGAPP_ENV | 运行环境：development / test / production（别名 dev/local/prod/pro）；也兼容 ENV | 一般不需要 | | BIGAPP_API_BASE | 显式覆盖后端地址（优先级最高） | 一般不需要 |

地址解析优先级：BIGAPP_API_BASE → BIGAPP_ENV/ENV → 构建默认环境（本地 build 为 development，npm 包为 production）。

能力清单

| MCP Tool | 说明 | |----------|------| | listProjects | 列出工作空间内业务项目，供选用 projectId | | getCurrentProject | 查询未传 projectId 时的回退项目（默认/最近） | | createProject | 新建业务项目（无匹配工程名时使用） | | createTask | 创建测试任务 | | createTestCase | 批量创建用例（source=ai） | | queryTask | 查询任务列表/详情 | | queryCase | 查询用例列表/详情 | | queryResult | 查询测试结果（默认 fail） | | queryIssue | 查询缺陷列表/详情 | | submitFix | 提交修复记录（缺陷进入修复中） | | markMerged | 标记修复已合并（缺陷进入待复测） | | runCase | 单用例创建执行记录（复测请带 issueId） | | runTask | 任务下批量创建执行记录 | | submitResult | 提交执行结果（pass 可关闭待复测缺陷） | | recallMemory | 召回智忆历史失败模式与修复方案（Test Memory） | | submitMemoryFeedback | 对 Recall 结果提交 Feedback |

业务工具均支持可选入参 projectId（智测业务项目 ID）。

写任务推荐流程： 先 listProjects → 用被测工程/仓库目录名与 name/code 忽略大小写匹配 → 无匹配则 createProject（名称尽量与工程名一致；code 冲突则改短码重试）→ 后续 createTask / createTestCase 等显式传入 projectId。勿因存在「默认项目」(code=default) 就直接写入其中。

查询类工具不传 projectId 时的回退（对齐 gonline MCP 用 Key 认人）：主站鉴权返回 Key 的 creatorId → 映射本地 sys_user → 读 last_project_id；映射失败（签发者从未登录智测 / 开发兜底 Token）则回退 code=default 默认项目。

createTestCase 的 stepsJson 须为标准 JSON 数组字符串，每步仅含 step（操作描述，必填）与 expected（本步预期，可选）：

[
  {"step": "打开登录页", "expected": "展示账号密码输入框"},
  {"step": "输入正确账号密码并提交", "expected": "跳转至工作台首页"}
]

禁止使用 action、order 等其它字段名。

安全护栏

• MCP 通过 gonline 工作空间签发的 Agent API Key 访问后端内网 API，服务端从 Key 解析工作空间
• 不提供众包领取、验收、结算等工具（产品护栏）

Cursor 配置

在 Cursor 的 MCP 配置（.cursor/mcp.json 或全局设置）中添加：

{
  "mcpServers": {
    "zhice": {
      "command": "npx",
      "args": ["-y", "zhice-mcp"],
      "env": {
        "BIGAPP_API_KEY": "粘贴工作空间签发的 Agent 密钥"
      }
    }
  }
}

推荐通过 npm 包启动（首次会自动下载，默认连生产）。本地源码调试：node + 本机 dist/index.js，先执行 npm run build（默认连 4802）；若 dist 曾按 production 构建，可在 env 加 "BIGAPP_ENV": "development"。

测试环境示例：

{
  "mcpServers": {
    "zhice": {
      "command": "npx",
      "args": ["-y", "zhice-mcp"],
      "env": {
        "BIGAPP_API_KEY": "粘贴工作空间签发的 Agent 密钥",
        "BIGAPP_ENV": "test"
      }
    }
  }
}

Agent 密钥

在 gonline 工作空间设置中签发 Agent API Key（格式 bigapp_...），与智忆 MCP 共用同一套密钥体系。

开发环境兜底：application-dev.yml 可配置 fallback-token + fallback-workspace-id 用于本地联调（非 bigapp_ 格式）。

验收路径

1. 启动 zhice-server（dev 4802）
2. 执行 npm run build 并配置 Cursor MCP，重启 Cursor
3. 在 Cursor 中调用 createTask 创建任务
4. 调用 queryResult 查看 Fail 结果
5. 调用 submitFix 提交修复 → markMerged 标记合并 → runCase + submitResult 复测

项目结构

zhice-mcp/
├── src/
│   ├── index.ts              # MCP Server 入口
│   ├── apiBase.ts            # BIGAPP_API_BASE 解析
│   └── config.generated.ts   # 构建时注入的后端地址
├── scripts/
│   └── build-env.mjs         # 读取 .env.* 生成 config.generated.ts
├── package.json
├── tsconfig.json
└── dist/                     # 构建输出（npm run build 后生成）