# mcp-zentao

面向禅道 11.3 Legacy Session API 的 Model Context Protocol（MCP）服务器。它让 Codex、Claude Desktop、Cursor 等 MCP 客户端可以读取和操作禅道中的任务、Bug、需求、测试用例和测试单。

本项目是基于 [`MaxenLin/mcp-zentao-11-3@1.0.5`](https://github.com/MaxenLin/mcp-zentao-11-3) 的非官方派生版本，保留原项目 MIT 许可证和版权声明。

## 兼容范围

| 禅道接口/版本 | 支持状态 |
| --- | --- |
| 禅道开源版 11.3 Legacy Session API | 已在真实环境验证 |
| 其他禅道 11.x Legacy Session API | 预期兼容，未逐版本验证 |
| GET 路由 | 支持，默认模式 |
| 自定义 GET 入口 | 支持 |
| PATH_INFO 路由 | 支持 |
| REST API v1/v2 | 不支持 |

本项目不会自动探测路由模式。部分禅道或代理服务会对错误路由返回 HTTP 200 的 HTML 页面，自动探测可能把登录页或错误页误判为可用接口，因此需要显式配置。

## 环境要求

- Node.js 20 或更高版本
- 可访问目标禅道服务的网络环境
- 一个具有所需禅道权限的账号

## 推荐使用方式

客户端通过固定 npm 版本启动，避免 `latest` 更新导致行为变化：

```json
{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "mcp-zentao@1.0.0"],
      "env": {
        "ZENTAO_URL": "https://zentao.example.com",
        "ZENTAO_USERNAME": "your-username",
        "ZENTAO_PASSWORD": "your-password",
        "ZENTAO_REQUEST_TYPE": "GET",
        "ZENTAO_ENTRY": "index.php"
      }
    }
  }
}
```

配置保存位置由 MCP 客户端决定。修改配置后需要重启对应客户端。

也可以全局安装后使用 CLI：

```bash
npm install -g mcp-zentao@1.0.0
```

```json
{
  "mcpServers": {
    "zentao": {
      "command": "mcp-zentao",
      "args": [],
      "env": {
        "ZENTAO_URL": "https://zentao.example.com",
        "ZENTAO_USERNAME": "your-username",
        "ZENTAO_PASSWORD": "your-password",
        "ZENTAO_REQUEST_TYPE": "GET",
        "ZENTAO_ENTRY": "index.php"
      }
    }
  }
}
```

## 配置说明

### `ZENTAO_URL`

填写禅道应用根地址，不要把 API 路径或 `index.php` 写进去。

- 禅道部署在站点根路径：`https://zentao.example.com`
- 禅道确实部署在 `/zentao` 子路径：`https://example.com/zentao`

只有浏览器实际访问地址包含 `/zentao` 时才保留该路径。不要因为项目名称是禅道就手工追加 `/zentao`。

### `ZENTAO_USERNAME` 和 `ZENTAO_PASSWORD`

禅道登录账号和密码。凭证只应保存在本地 MCP 客户端配置或本地配置文件中，不要提交到 Git 仓库。

### `ZENTAO_REQUEST_TYPE`

支持以下值：

- `GET`：默认值，使用具名查询参数访问 Legacy Session API。
- `PATH_INFO`：使用 `module-method-params.json` 形式访问。

### `ZENTAO_ENTRY`

GET 模式的相对入口，默认值为 `index.php`。如果部署通过自定义入口转发，可以填写 `gateway.php` 或 `gateway/index.php`。

`PATH_INFO` 模式不会使用该配置。

### 默认配置

省略路由配置时等价于：

```env
ZENTAO_REQUEST_TYPE=GET
ZENTAO_ENTRY=index.php
```

## 本地配置文件

除了环境变量，也可以使用 `~/.zentao/config.json`：

```json
{
  "url": "https://zentao.example.com",
  "username": "your-username",
  "password": "your-password",
  "apiVersion": "legacy",
  "requestType": "GET",
  "entry": "index.php"
}
```

完整的环境变量连接配置优先于配置文件。使用配置文件时，非空环境变量会按字段覆盖文件内容。

## 功能范围

当前 MCP 注册 48 个工具，主要包括：

- 配置初始化和脱敏后的配置查询
- 我的任务、任务详情、任务更新和完成
- 我的 Bug、Bug 详情、产品 Bug 和 Bug 解决
- 产品、需求、需求搜索和需求详情
- 测试用例、测试单、执行结果和用例执行
- 需求、Bug、任务之间的关联查询
- 批量任务和 Bug 操作
- 统计、开发上下文、Markdown 摘要和数据导出
- 复杂度、优先级、工作量及下一步建议分析
- 代码提示、测试提示和代码审查清单生成

部分工具会修改禅道数据。调用更新、完成、解决、创建或执行类工具前，请检查客户端展示的参数并确认当前账号权限。

## 开发与验证

```bash
npm ci
npm test
```

仅构建：

```bash
npm run build
```

检查 npm 发布内容：

```bash
npm pack --dry-run
```

npm 包只包含 `dist/`、`README.md`、`LICENSE` 和 `package.json`。源码、测试、凭证、本地 MCP 配置和 `node_modules` 不进入发布包。

## 常见问题

### MCP 启动失败并提示找不到 `node` 或 `npx`

确认 Node.js 20+ 已安装，并在启动 MCP 客户端的环境中执行：

```bash
node --version
npx --version
```

Windows 安装 Node.js 后通常需要完全退出并重新打开 MCP 客户端，使新的 PATH 生效。

### GET 模式返回 HTML 或 404

依次确认：

1. `ZENTAO_URL` 是否为真实应用根地址。
2. 是否错误追加或遗漏实际部署的 `/zentao` 子路径。
3. `ZENTAO_ENTRY` 是否与服务入口一致，常见值为 `index.php`。
4. 服务是否确实启用了 GET 路由；如果只支持 PATH_INFO，显式改为 `PATH_INFO`。

### PATH_INFO 模式返回 404

这通常表示服务器、反向代理或当前禅道部署没有启用 PATH_INFO。请改用 `GET`，并设置正确的 `ZENTAO_ENTRY`。

## 升级与回滚

建议在客户端中固定精确版本：

```text
mcp-zentao@1.0.0
```

升级时先修改版本号并重启客户端。如果新版本不适配当前部署，将配置恢复到上一个已验证版本即可。开发环境也可以直接回滚为本地入口：

```text
node <project-directory>/dist/index.js
```

## 项目来源与主要改动

本项目以 `MaxenLin/mcp-zentao-11-3` 的 `1.0.5` 版本为基线，主要增加或完善：

- 禅道 11.3 GET 路由的位置参数到具名参数转换
- `GET`、`PATH_INFO` 和自定义 GET 入口配置
- 路由及配置校验、错误信息和配置脱敏
- 48 个 MCP 工具契约及 Legacy API 回归测试
- 独立 npm 包、GitHub 仓库和版本线

本项目不是禅道官方项目，也不代表原项目作者对该派生版本提供支持或背书。

## 许可证

[MIT](./LICENSE)。原始版权声明保留在 LICENSE 中。

## 相关链接

- [本项目 GitHub 仓库](https://github.com/luffy-mcw/mcp-zentao)
- [上游项目](https://github.com/MaxenLin/mcp-zentao-11-3)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [禅道官网](https://www.zentao.net/)