# zentao-rest-v1-mcp

面向禅道开源版的 MCP 服务。优先使用 REST v1，只有明确的 REST v1 路由不兼容时才回退 Legacy Session API。

## 特性

- 支持禅道 REST v1 Token 认证。
- 支持任务、Bug、需求、测试用例和测试单的查询与操作。
- 支持创建任务、更新任务、开始任务、完成任务、关闭任务和解决 Bug。
- 写入操作遵循“写入一次、写后回读”，避免重复提交。
- 读取接口在明确不兼容时回退 Legacy；认证失败、参数错误和写入结果不明时不自动切换通道。
- 支持 `ZENTAO_TIMEOUT_MS` 和 `ZENTAO_SESSION_TTL_MS` 配置。

## 系统要求

- Node.js `>=18.0.0`
- 禅道开源版实例，已启用对应 REST API 能力

## 安装

```bash
npm install -g zentao-rest-v1-mcp
```

## MCP 配置

```json
{
  "mcpServers": {
    "zentao-rest-v1": {
      "command": "zentao-rest-v1-mcp",
      "args": [],
      "env": {
        "ZENTAO_URL": "https://your-zentao.example/zentao",
        "ZENTAO_USERNAME": "your-account",
        "ZENTAO_PASSWORD": "your-password",
        "ZENTAO_TIMEOUT_MS": "30000",
        "ZENTAO_SESSION_TTL_MS": "3000000"
      }
    }
  }
}
```

也可以直接运行本地构建产物：

```bash
node dist/index.js
```

## 核心工具

- 读取：`getBugDetail`、`getTaskDetail`、`getMyBugs`、`getMyTasks`、`getStoryDetail`
- 任务：`createTask`、`updateTask`、`startTask`、`finishTask`、`closeTask`
- Bug：`updateBug`、`resolveBug`
- 测试：`createTestCase`、`runTestCase`

任务完成流程必须遵循：

```text
wait → startTask → doing → finishTask → done → closeTask → closed
```

完成任务时必须提交实际开始时间 `realStarted` 和不早于它的实际完成时间 `finishedDate`，不能只提交日期。

## 本地开发

```bash
pnpm install --frozen-lockfile
pnpm run build
pnpm run test:smoke
```

## 配置说明

- `ZENTAO_URL`：禅道站点地址，通常包含 `/zentao` 部署路径。
- `ZENTAO_USERNAME`：禅道账号。
- `ZENTAO_PASSWORD`：禅道密码，仅通过环境变量传入，不写入源码和日志。
- `ZENTAO_TIMEOUT_MS`：请求超时时间，默认 `30000` 毫秒。
- `ZENTAO_SESSION_TTL_MS`：Token 本地缓存时间，默认 `3000000` 毫秒。

## 许可证

MIT。原始 Legacy MCP 实现及其许可证声明保留在本包中。

## 相关链接

- [禅道开源版](https://github.com/easysoft/zentaopms)
- [本项目仓库](https://github.com/cwj9195/zentao-rest-v1-mcp)