# ZenTao MCP

English | [中文](#chinese)

<a id="english"></a>

An MCP service for ZenTao development workflows. It covers requirement breakdown, execution planning, and workload-allocation suggestions for leads, plus task and bug workflows for developers.

## Current status

Phase 1 provides connection diagnostics and read-only query tools:

- `diagnose_connection`
- `list_projects`
- `list_executions`
- `list_products`
- `list_stories`
- `list_tasks`
- `list_execution_tasks`
- `list_my_tasks`
- `list_user_tasks`
- `list_bugs`
- `list_my_bugs`
- `list_user_bugs`
- `list_users`
- `get_task`
- `get_story`
- `get_bug`

`list_stories` and `list_bugs` require a ZenTao product ID. An agent can call `list_users` first, then pass the returned `account` to `list_user_tasks` or `list_user_bugs`, so the user does not need to enter a username manually.

Write tools generate a plan by default and do not send a request unless `confirm: true` is explicitly supplied:

- `create_task`
- `assign_task`
- `start_task`
- `finish_task`
- `complete_task` (suited to natural-language requests such as “mark 1554 as completed”)
- `resolve_bug`

Do not use `confirm: true` in tests or ordinary calls.

## Local development

```powershell
Copy-Item .env.example .env
npm install
npm run check
npm test
npm run build
npm start
```

The default ZenTao connection file is `~/.zentao-mcp/config.json` (`%USERPROFILE%\\.zentao-mcp\\config.json` on Windows):

```json
{
  "baseUrl": "https://your-zentao.example.com",
  "apiPath": "/zentao/api.php/v1",
  "token": "your-token",
  "timeoutMs": 10000
}
```

Use `ZENTAO_CONFIG_FILE` to select another config file. `ZENTAO_*` variables are advanced overrides or supplements. Never commit real credentials.

---

<a id="chinese"></a>

[English](#english) | 中文

面向禅道研发协作的 MCP 服务，覆盖总监视角的需求拆解、执行计划和工作量分配建议，以及开发人员视角的任务与 Bug 工作流。

## 当前状态

当前为 Phase 1 开发阶段，已提供连接诊断和只读查询工具：

- `diagnose_connection`
- `list_projects`
- `list_executions`
- `list_products`
- `list_stories`
- `list_tasks`
- `list_execution_tasks`
- `list_my_tasks`
- `list_user_tasks`
- `list_bugs`
- `list_my_bugs`
- `list_user_bugs`
- `list_users`
- `get_task`
- `get_story`
- `get_bug`

`list_stories` 和 `list_bugs` 需要提供禅道产品 ID，分别访问产品下的需求和 Bug。Agent 可以先调用 `list_users`，再使用返回的 `account` 调用 `list_user_tasks` 或 `list_user_bugs`，不需要用户手工输入用户名。

写入工具当前默认只生成方案，不执行请求。只有显式传入 `confirm: true` 才会发送写入请求：

- `create_task`
- `assign_task`
- `start_task`
- `finish_task`
- `complete_task`（适合“将 1554 标记为已完成”这类自然语言指令）
- `resolve_bug`

测试和普通调用不得使用 `confirm: true`。

## 本地运行

```powershell
Copy-Item .env.example .env
npm install
npm run check
npm test
npm run build
npm start
```

默认通过用户目录配置禅道连接：`~/.zentao-mcp/config.json`（Windows 为 `%USERPROFILE%\\.zentao-mcp\\config.json`）。示例：

```json
{
  "baseUrl": "https://your-zentao.example.com",
  "apiPath": "/zentao/api.php/v1",
  "token": "your-token",
  "timeoutMs": 10000
}
```

环境变量 `ZENTAO_CONFIG_FILE` 可指定配置文件路径；`ZENTAO_*` 变量仅作为高级覆盖/补充方式。不要将真实凭证写入仓库。