@chenyingxian/zentao-mcp 0.1.0

package/.env.example

@@ -0,0 +1,6 @@
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_ACCOUNT=admin
+ZENTAO_PASSWORD=change-me
+# Optional: use a pre-issued V1 token instead of logging in with account/password.
+ZENTAO_TOKEN=
+ZENTAO_TIMEOUT_MS=15000

package/CONFIG.md

@@ -0,0 +1,77 @@
+# Configuration
+
+This MCP server is configured with environment variables. It does not read a required config file by default, which makes it suitable for local MCP clients and `npx` usage.
+
+## Required Variables
+
+Use account/password login:
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_ACCOUNT=your-account
+ZENTAO_PASSWORD=your-password
+```
+
+Or use a pre-issued RESTful API v1 token:
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_TOKEN=your-token
+```
+
+## Optional Variables
+
+```bash
+ZENTAO_TIMEOUT_MS=15000
+```
+
+`ZENTAO_TIMEOUT_MS` controls the HTTP request timeout in milliseconds.
+
+## MCP Client Example
+
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "npx",
+      "args": ["zentao-mcp"],
+      "env": {
+        "ZENTAO_BASE_URL": "https://zentao.example.com",
+        "ZENTAO_ACCOUNT": "your-account",
+        "ZENTAO_PASSWORD": "your-password",
+        "ZENTAO_TIMEOUT_MS": "15000"
+      }
+    }
+  }
+}
+```
+
+## Token Helper
+
+After global installation:
+
+```bash
+zentao-mcp-get-token --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+From a source checkout:
+
+```bash
+./scripts/get-token.sh --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+The helper prints only the token when login succeeds.
+
+## Compatibility Notes
+
+- ZenTao installations can differ by edition, version, and customization.
+- RESTful API v1 is used for standard resources such as tasks, stories, builds, and test tasks.
+- Some "My" pages and build linking flows use legacy JSON or form routes because older ZenTao versions do not expose every operation through RESTful API v1.
+- If your ZenTao instance uses a path prefix, include it in `ZENTAO_BASE_URL`, for example `https://zentao.example.com/zentao`.
+
+## Security Notes
+
+- Do not commit real `.env` files.
+- Do not publish accounts, passwords, tokens, internal URLs, task IDs, story IDs, build IDs, or business data in public examples.
+- Prefer MCP client environment variables or a local secret manager for credentials.
+

package/CONFIG.zh-CN.md

@@ -0,0 +1,77 @@
+# 配置说明
+
+本 MCP Server 通过环境变量配置，默认不强制读取配置文件，方便在本地 MCP 客户端或 `npx` 中使用。
+
+## 必填变量
+
+使用账号密码登录：
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_ACCOUNT=your-account
+ZENTAO_PASSWORD=your-password
+```
+
+或者直接使用已签发的 RESTful API v1 token：
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_TOKEN=your-token
+```
+
+## 可选变量
+
+```bash
+ZENTAO_TIMEOUT_MS=15000
+```
+
+`ZENTAO_TIMEOUT_MS` 用于控制 HTTP 请求超时时间，单位为毫秒。
+
+## MCP 客户端示例
+
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "npx",
+      "args": ["zentao-mcp"],
+      "env": {
+        "ZENTAO_BASE_URL": "https://zentao.example.com",
+        "ZENTAO_ACCOUNT": "your-account",
+        "ZENTAO_PASSWORD": "your-password",
+        "ZENTAO_TIMEOUT_MS": "15000"
+      }
+    }
+  }
+}
+```
+
+## Token 辅助脚本
+
+全局安装后：
+
+```bash
+zentao-mcp-get-token --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+源码目录中：
+
+```bash
+./scripts/get-token.sh --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+登录成功时，脚本只输出 token。
+
+## 兼容性说明
+
+- 禅道不同版本、版本类型和二开环境的路由可能不同。
+- 标准资源优先使用 RESTful API v1，例如任务、需求、构建、测试单。
+- 部分“我的”页面和构建关联需求流程使用旧版 JSON / 表单路由，因为旧版本禅道不一定为所有操作提供 RESTful API v1。
+- 如果禅道部署在子路径下，请把路径写入 `ZENTAO_BASE_URL`，例如 `https://zentao.example.com/zentao`。
+
+## 安全说明
+
+- 不要提交真实 `.env` 文件。
+- 不要在公开示例中暴露账号、密码、token、内部地址、任务 ID、需求 ID、构建 ID 或业务数据。
+- 建议通过 MCP 客户端环境变量或本地密钥管理方式提供凭据。
+

package/MCP_TOOLS.md

@@ -0,0 +1,154 @@
+# MCP Tools
+
+All tools return JSON text so the caller can inspect the original ZenTao fields and pass IDs into later tools.
+
+## `zentao_get_my_tasks`
+
+Reads pending tasks assigned to the current user.
+
+Parameters:
+
+- `order_by`: Sort field. Default: `id_desc`.
+- `rec_per_page`: Page size. Default: `100`, max: `1000`.
+- `page_id`: Page number. Default: `1`.
+
+Typical use:
+
+```json
+{
+  "order_by": "id_desc",
+  "rec_per_page": 100,
+  "page_id": 1
+}
+```
+
+## `zentao_get_finished_tasks`
+
+Reads tasks finished by the current user.
+
+Parameters:
+
+- `rec_per_page`: Return count. Default: `20`, max: `20`.
+- `page_id`: Local page number. Default: `1`.
+
+This tool follows the legacy "My contributed tasks" route and keeps the response compact.
+
+## `zentao_get_task`
+
+Reads one task by ID.
+
+Parameters:
+
+- `task_id`: ZenTao task ID.
+
+The response keeps the original `desc` HTML and adds `descText` plain text.
+
+## `zentao_create_build`
+
+Creates a build from a development task and links the related story after build creation.
+
+Parameters:
+
+- `task_id`: Development task ID.
+- `dry_run`: Preview only. Default: `true`. Pass `false` to create the build.
+
+The tool resolves:
+
+- development task
+- story
+- product
+- project
+- execution
+- matching test task and assignee when available
+
+When created successfully, the response includes the new build ID and related product information.
+
+## `zentao_create_testtask`
+
+Creates a test task from a development task and build.
+
+Parameters:
+
+- `task_id`: Development task ID.
+- `build_id`: Build ID.
+- `dry_run`: Preview only. Default: `true`. Pass `false` to create the test task.
+- `owner`: Optional owner account. If omitted, the matched test task assignee is used.
+- `begin`: Start date in `yyyy-mm-dd`. Defaults to today.
+- `end`: End date in `yyyy-mm-dd`. Defaults to four days after `begin`.
+- `attachment_paths`: Optional local file paths to upload, such as `.jmx` and `.md` files.
+
+The tool uses the task priority as the test task priority.
+
+## `zentao_create_release_task`
+
+Generates release task data from a list of development tasks.
+
+Parameters:
+
+- `task_ids`: Development task IDs included in the release.
+- `system`: System or module name.
+- `story_id`: Optional main story ID. If omitted, the first related story is used.
+- `release_scope`: Release scope. Default: `生产环境`.
+- `gray_tag`: Optional gray/canary tag for production release notes.
+- `branch`: Git branch. If omitted, the tool tries to parse it from task descriptions.
+- `release_content`: Release content lines. If omitted, related story titles are used.
+- `database`: Database changes. Empty means `无`.
+- `env`: Environment variable changes. Empty means `无`.
+- `cron`: Scheduled job changes. Empty means `无`.
+- `dependencies`: Dependency package changes. Empty means `无`.
+- `other`: Other notes. Empty means `无`.
+- `risk`: Risks. Empty means `无`.
+- `dry_run`: Preview only. Current implementation supports preview mode only.
+
+Generated task name:
+
+```text
+发布-{system} xxxxxx {release_scope}
+```
+
+The generated description contains these sections:
+
+```text
+一.更新范围
+二.代码
+三.数据库
+四.环境变量
+五.计划任务
+六.依赖包
+七.其它
+八.对外说明发布的内容
+九.风险
+```
+
+For people in the release content section, the tool resolves main development and test tasks, includes child tasks, removes task creators from contributor candidates, and sorts development contributors before test contributors.
+
+## `zentao_get_effort_logs`
+
+Reads effort logs from `effort-calendar` and "My Effort" routes.
+
+Parameters:
+
+- `type`: Effort type. Default: `all`.
+- `order_by`: Sort field. Default: `date_desc`.
+- `rec_per_page`: Page size. Default: `100`, max: `1000`.
+- `page_id`: Page number. Default: `1`.
+
+## `zentao_generate_weekly_summary`
+
+Generates a weekly summary from effort logs.
+
+Parameters:
+
+- `start_date`: Start date in `yyyy-mm-dd`. Defaults to Monday of the current week.
+- `end_date`: End date in `yyyy-mm-dd`. Defaults to Sunday of the current week.
+- `rec_per_page`: Page size. Default: `100`, max: `1000`.
+- `max_pages`: Max pages to read. Default: `10`, max: `50`.
+
+Output style:
+
+```text
+1、Item A。2、Item B。共计X小时。
+```
+
+The summary removes duplicate work items and excludes existing weekly-summary-like effort entries.
+

package/MCP_TOOLS.zh-CN.md

@@ -0,0 +1,154 @@
+# MCP 工具说明
+
+所有工具都返回 JSON 文本，调用方可以查看禅道原始字段，也可以把返回的 ID 继续传给后续工具。
+
+## `zentao_get_my_tasks`
+
+查询待处理下指派给当前用户的任务。
+
+参数：
+
+- `order_by`：排序字段，默认 `id_desc`。
+- `rec_per_page`：每页数量，默认 `100`，最大 `1000`。
+- `page_id`：页码，默认 `1`。
+
+示例：
+
+```json
+{
+  "order_by": "id_desc",
+  "rec_per_page": 100,
+  "page_id": 1
+}
+```
+
+## `zentao_get_finished_tasks`
+
+查询由当前用户完成的任务。
+
+参数：
+
+- `rec_per_page`：返回数量，默认 `20`，最大 `20`。
+- `page_id`：本地分页页码，默认 `1`。
+
+该工具使用“我的贡献任务”旧版路由，并尽量保持返回结果简洁。
+
+## `zentao_get_task`
+
+按任务 ID 查询任务详情。
+
+参数：
+
+- `task_id`：禅道任务 ID。
+
+返回结果会保留原始 `desc` HTML，并额外提供纯文本 `descText`。
+
+## `zentao_create_build`
+
+按开发任务创建构建，并在创建后自动关联该任务对应的需求。
+
+参数：
+
+- `task_id`：开发任务 ID。
+- `dry_run`：是否只预览，默认 `true`。传 `false` 才会真实创建。
+
+工具会解析：
+
+- 开发任务
+- 需求
+- 产品
+- 项目
+- 执行
+- 可匹配的测试任务和测试负责人
+
+创建成功后，返回结果会包含新构建 ID 和关联产品信息。
+
+## `zentao_create_testtask`
+
+按开发任务和构建创建测试单。
+
+参数：
+
+- `task_id`：开发任务 ID。
+- `build_id`：构建 ID。
+- `dry_run`：是否只预览，默认 `true`。传 `false` 才会真实创建。
+- `owner`：测试单负责人账号。不传时使用匹配到的测试任务指派人。
+- `begin`：开始日期，格式 `yyyy-mm-dd`，默认今天。
+- `end`：结束日期，格式 `yyyy-mm-dd`，默认开始日期后第 4 天。
+- `attachment_paths`：可选附件本地路径，例如 `.jmx` 和 `.md` 文件。
+
+测试单优先级会按开发任务优先级填写。
+
+## `zentao_create_release_task`
+
+根据开发任务列表生成发版任务信息。
+
+参数：
+
+- `task_ids`：本次发版包含的开发任务 ID 列表。
+- `system`：系统或模块名。
+- `story_id`：可选主需求 ID。不传时使用第一个关联需求。
+- `release_scope`：发布范围，默认 `生产环境`。
+- `gray_tag`：生产发布时可填写对应灰度 tag。
+- `branch`：Git 分支。不传时尝试从任务描述中解析。
+- `release_content`：发布内容。不传时使用关联需求标题。
+- `database`：数据库变更，空值按 `无`。
+- `env`：环境变量变更，空值按 `无`。
+- `cron`：计划任务变更，空值按 `无`。
+- `dependencies`：依赖包变更，空值按 `无`。
+- `other`：其它事项，空值按 `无`。
+- `risk`：风险，空值按 `无`。
+- `dry_run`：是否只预览。当前实现仅支持预览。
+
+生成的任务名称：
+
+```text
+发布-{system} xxxxxx {release_scope}
+```
+
+生成的描述包含以下大项：
+
+```text
+一.更新范围
+二.代码
+三.数据库
+四.环境变量
+五.计划任务
+六.依赖包
+七.其它
+八.对外说明发布的内容
+九.风险
+```
+
+对外说明中的人员信息会查找主开发任务和主测试任务，并包含对应子任务；候选人员会剔除任务创建者，避免完成后回指给创建人时被误加入；排序按开发人员字典序 + 测试人员字典序。
+
+## `zentao_get_effort_logs`
+
+读取 `effort-calendar` 和“我的日志”工时记录。
+
+参数：
+
+- `type`：日志类型，默认 `all`。
+- `order_by`：排序字段，默认 `date_desc`。
+- `rec_per_page`：每页数量，默认 `100`，最大 `1000`。
+- `page_id`：页码，默认 `1`。
+
+## `zentao_generate_weekly_summary`
+
+根据工时日志生成周总结文本。
+
+参数：
+
+- `start_date`：开始日期，格式 `yyyy-mm-dd`，默认本周一。
+- `end_date`：结束日期，格式 `yyyy-mm-dd`，默认本周日。
+- `rec_per_page`：每页读取数量，默认 `100`，最大 `1000`。
+- `max_pages`：最多读取页数，默认 `10`，最大 `50`。
+
+输出格式：
+
+```text
+1、事项 A。2、事项 B。共计X小时。
+```
+
+生成时会去除重复事项，并排除已有周总结风格的日志。
+

package/README.md

@@ -0,0 +1,213 @@
+# zentao-mcp
+
+ZenTao MCP server for RESTful API v1 and legacy JSON routes.
+
+This package is intended for self-hosted ZenTao installations where the v1 API is available and some "My" pages still need ZenTao legacy JSON routes.
+
+## Documentation
+
+- [Configuration](./CONFIG.md)
+- [MCP Tools](./MCP_TOOLS.md)
+- [中文文档](./README.zh-CN.md)
+
+## Installation
+
+```bash
+npm install -g zentao-mcp
+```
+
+You can also run it without a global install:
+
+```bash
+npx zentao-mcp
+```
+
+## Configuration
+
+Set the following environment variables in your MCP client:
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_ACCOUNT=your-account
+ZENTAO_PASSWORD=your-password
+```
+
+Alternatively, provide a pre-issued v1 token:
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_TOKEN=your-token
+```
+
+Optional:
+
+```bash
+ZENTAO_TIMEOUT_MS=15000
+```
+
+## MCP Client Example
+
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "npx",
+      "args": ["zentao-mcp"],
+      "env": {
+        "ZENTAO_BASE_URL": "https://zentao.example.com",
+        "ZENTAO_ACCOUNT": "your-account",
+        "ZENTAO_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+## Get a Token
+
+The package includes a helper script:
+
+```bash
+zentao-mcp-get-token --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+If you run from a source checkout:
+
+```bash
+./scripts/get-token.sh --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+## Tools
+
+### `zentao_get_my_tasks`
+
+Read pending tasks assigned to the current user.
+
+Parameters:
+
+- `order_by`: Sort field, default `id_desc`.
+- `rec_per_page`: Page size, default `100`, max `1000`.
+- `page_id`: Page number, default `1`.
+
+Uses:
+
+- `POST /api.php/v1/tokens`
+- `GET /my-work-task-assignedTo-id_desc-0-1-100.json`
+
+### `zentao_get_finished_tasks`
+
+Read tasks finished by the current user.
+
+Parameters:
+
+- `rec_per_page`: Return count, default `20`, max `20`.
+- `page_id`: Local page number, default `1`.
+
+Uses:
+
+- `GET /my-contribute-task-finishedBy.json`
+
+### `zentao_get_task`
+
+Read one task by ID.
+
+Parameters:
+
+- `task_id`: ZenTao task ID.
+
+Uses:
+
+- `GET /api.php/v1/tasks/:taskID`
+
+The response keeps the original ZenTao `desc` HTML and adds `descText` plain text.
+
+### `zentao_create_build`
+
+Create a build from a development task. The tool reads the related story, product, project, and execution, creates a build, and links the story after creation.
+
+Parameters:
+
+- `task_id`: Development task ID.
+- `dry_run`: Preview only by default. Pass `false` to create the build and link the story.
+
+Uses:
+
+- `GET /api.php/v1/tasks/{taskID}`
+- `GET /api.php/v1/executions/{executionID}/builds?limit=20&page=1`
+- `POST /build-create-{executionID}.html?t=json`
+- `POST /build-linkStory-{buildID}--0.html?t=json`
+
+### `zentao_create_testtask`
+
+Create a test task from a development task and build.
+
+Parameters:
+
+- `task_id`: Development task ID.
+- `build_id`: Build ID.
+- `dry_run`: Preview only by default. Pass `false` to create the test task.
+- `owner`: Optional owner account. If omitted, the first matched test task assignee is used.
+- `begin`: Start date in `yyyy-mm-dd`. Defaults to today.
+- `end`: End date in `yyyy-mm-dd`. Defaults to four days after `begin`.
+- `attachment_paths`: Optional local files to upload, such as `.jmx` and `.md` files.
+
+Uses:
+
+- `GET /api.php/v1/tasks/{taskID}`
+- `GET /api.php/v1/stories/{storyID}`
+- `GET /api.php/v1/builds/{buildID}`
+- `GET /api.php/v1/executions/{executionID}/tasks?limit=1000&page=1`
+- `POST /api.php/v1/projects/{projectID}/testtasks`
+
+### `zentao_create_release_task`
+
+Generate release task data from a list of development tasks. This tool currently previews only and does not create the task.
+
+Parameters:
+
+- `task_ids`: Development task IDs included in the release.
+- `system`: System or module name, for example `WebApp`.
+- `story_id`: Optional main story ID. If omitted, the first task story is used.
+- `release_scope`: Release scope, default `生产环境`.
+- `gray_tag`: Optional gray/canary tag for production releases.
+- `branch`: Git branch. If omitted, the tool tries to parse `git分支:` from task descriptions.
+- `release_content`: Release notes. If omitted, related story titles are used.
+- `database` / `env` / `cron` / `dependencies` / `other` / `risk`: Release description sections. Empty values become `无`.
+
+The generated task name is:
+
+```text
+发布-{system} xxxxxx {release_scope}
+```
+
+### `zentao_get_effort_logs`
+
+Read effort logs from `effort-calendar` and "My Effort".
+
+Parameters:
+
+- `type`: Effort type, default `all`.
+- `order_by`: Sort field, default `date_desc`.
+- `rec_per_page`: Page size, default `100`, max `1000`.
+- `page_id`: Page number, default `1`.
+
+### `zentao_generate_weekly_summary`
+
+Generate a weekly summary from effort logs:
+
+```text
+1、Item A。2、Item B。共计X小时。
+```
+
+Parameters:
+
+- `start_date`: Start date in `yyyy-mm-dd`. Defaults to Monday of the current week.
+- `end_date`: End date in `yyyy-mm-dd`. Defaults to Sunday of the current week.
+- `rec_per_page`: Page size, default `100`, max `1000`.
+- `max_pages`: Max pages to read, default `10`, max `50`.
+
+## Notes
+
+- Mutating tools use `dry_run=true` by default where supported.
+- Some ZenTao installations expose different legacy routes depending on version and customization.
+- Do not publish real `.env` files or tokens.