@zentao-hub/mcp 0.3.0

package/.env.example

@@ -0,0 +1,13 @@
+# ZenTao instance base URL (no trailing slash). The /api.php/v1 path is appended automatically.
+ZENTAO_URL=https://zentao.example.com
+
+# Account used to authenticate. The MCP server exchanges these for a token at startup
+# and silently re-logs in on 401.
+ZENTAO_USERNAME=your-account
+ZENTAO_PASSWORD=your-password
+
+# Optional: pass a pre-issued token instead of username/password. Takes precedence when set.
+# ZENTAO_TOKEN=
+
+# Optional: HTTP request timeout in milliseconds (default 15000).
+# ZENTAO_TIMEOUT_MS=15000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deven Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# @zentao-hub/mcp
+
+English | [简体中文](README.zh-CN.md)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for **ZenTao 20.x (open source edition)**. Covers the everyday entities of the ZenTao v1 REST API (products, projects, plans, executions, stories, tasks, bugs, test cases, builds, releases, repos, users, docs) plus a generic `zentao_request` escape hatch for endpoints that are not explicitly wrapped.
+
+> Looking for the hub directory, slash commands, and commit-msg hook? See the sister package [`@zentao-hub/cli`](../cli). This package is the MCP server itself, nothing more.
+
+## Tool overview (129 tools)
+
+| Entity              | Tools                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Users / Depts**   | `whoami` · `list_users` · `get_user` · `list_departments` · `list_department_users`                                                                                                                                                                                                                                                                                              |
+| **Products**        | `list_products` · `get_product` · `create_product` · `update_product` · `delete_product` · `list_product_branches` · `list_product_modules` · `list_product_plans` · `list_product_executions`                                                                                                                                                                                   |
+| **Projects**        | `list_projects` · `get_project` · `create_project` · `update_project` · `delete_project` · `list_project_executions` · `list_project_products`                                                                                                                                                                                                                                   |
+| **Programs**        | `list_programs` · `get_program` · `create_program` · `delete_program`                                                                                                                                                                                                                                                                                                            |
+| **Executions**      | `list_executions` · `get_execution` · `create_execution` · `update_execution` · `delete_execution` · `start_execution` · `close_execution` · `list_execution_tasks` · `list_execution_stories` · `list_execution_team`                                                                                                                                                           |
+| **Stories**         | `list_product_stories` · `get_story` · `create_story` · `update_story` · `delete_story` · `change_story` · `review_story` · `close_story` · `activate_story` · `assign_story` · `add_story_comment`                                                                                                                                                                              |
+| **Tasks**           | `get_task` · `list_my_tasks` · `create_task` · `update_task` · `delete_task` · `start_task` · `finish_task` · `pause_task` · `activate_task` · `close_task` · `cancel_task` · `assign_task` · `add_task_comment`                                                                                                                                                                  |
+| **Bugs**            | `list_my_bugs` · `list_product_bugs` · `list_execution_bugs` · `get_bug` · `create_bug` · `update_bug` · `delete_bug` · `resolve_bug` · `close_bug` · `confirm_bug` · `activate_bug` · `assign_bug` · `add_bug_comment` · `get_bug_history` · `download_bug_attachments`                                                                                                          |
+| **Test cases**      | `list_product_cases` · `get_case` · `create_case` · `update_case` · `delete_case` · `create_case_result` · `list_case_results` · `list_product_testsuites` · `list_product_testtasks`                                                                                                                                                                                            |
+| **Test reports**    | `list_product_testreports` · `get_testreport` · `create_testreport` · `delete_testreport`                                                                                                                                                                                                                                                                                        |
+| **Builds**          | `list_product_builds` · `list_execution_builds` · `get_build` · `create_build` · `delete_build`                                                                                                                                                                                                                                                                                  |
+| **Releases**        | `list_product_releases` · `get_release` · `create_release` · `delete_release`                                                                                                                                                                                                                                                                                                    |
+| **Repos**           | `list_repos` · `get_repo` · `list_repo_branches` · `list_repo_commits`                                                                                                                                                                                                                                                                                                           |
+| **Docs**            | `list_doclibs` · `list_doclib_docs` · `get_doc` · `create_doc` · `update_doc` · `delete_doc`                                                                                                                                                                                                                                                                                     |
+| **Effort**          | `log_effort` · `list_efforts` · `update_effort` · `delete_effort`                                                                                                                                                                                                                                                                                                                |
+| **Todos**           | `list_todos` · `get_todo` · `create_todo` · `update_todo` · `finish_todo` · `delete_todo`                                                                                                                                                                                                                                                                                        |
+| **Issues**          | `list_project_issues` · `get_issue` · `create_issue` · `update_issue` · `resolve_issue` · `close_issue` · `delete_issue`                                                                                                                                                                                                                                                         |
+| **Risks**           | `list_project_risks` · `get_risk` · `create_risk` · `update_risk` · `delete_risk`                                                                                                                                                                                                                                                                                                |
+| **Escape hatch**    | `zentao_request` — arbitrary `GET / POST / PUT / DELETE` against `/api.php/v1/...`, for endpoints with no explicit wrapper                                                                                                                                                                                                                                                       |
+
+**On the product scope.** Most ZenTao v1 REST endpoints for bugs / stories / cases / builds / releases are product-scoped. The usual first step is `list_products` to grab a productId.
+
+## Requirements
+
+- Node.js ≥ 18
+- A ZenTao 20.x instance with the v1 REST API enabled, reachable from this machine
+- A developer account (username + password), or a pre-issued token
+
+## Install
+
+```bash
+npm install -g @zentao-hub/mcp
+# Or, inside this monorepo: `pnpm install && pnpm run build` from the repo root.
+```
+
+Executable entry point: `zentao-hub-mcp` (i.e. `dist/index.js`).
+
+## Configuration
+
+The recommended path is to log in once via the sister CLI
+[`@zentao-hub/cli`](../cli) and let the MCP server pick the credentials
+up automatically:
+
+```bash
+npm install -g @zentao-hub/cli @zentao-hub/mcp
+zentao-hub login                          # default profile
+zentao-hub login --profile personal       # additional ZenTao instance
+zentao-hub profiles                       # list and pick a default
+```
+
+The CLI stores the token + URL + username in `~/.zentao-hub/credentials.json`
+(mode 0600) and caches the password in the OS keychain (macOS Keychain /
+libsecret on Linux / Credential Manager on Windows). The MCP server reads
+that file when the env vars below are not set and silently refreshes
+expired tokens using the cached password.
+
+### Environment variables
+
+Env vars take precedence over the credentials file, so CI/CD setups stay
+explicit.
+
+| Env var                 | When to use                                  | Description                                                                  |
+| ----------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
+| `ZENTAO_PROFILE`        | Multiple profiles configured                 | Which profile to use. Defaults to the file's `default`, or to the sole profile if only one is configured. |
+| `ZENTAO_URL`            | Skipping the credentials file                | ZenTao base URL, e.g. `https://zentao.example.com` (no trailing `/`).        |
+| `ZENTAO_TOKEN`          | One of: token, or username+password          | Pre-issued token. Auto-refresh disabled in this mode.                        |
+| `ZENTAO_USERNAME`       | Together with password                       | Account; exchanged for a token at startup, silently re-logged in on 401.     |
+| `ZENTAO_PASSWORD`       | Together with username                       | Password.                                                                    |
+| `ZENTAO_TIMEOUT_MS`     | Optional                                     | Per-request timeout in milliseconds, default `15000`.                        |
+| `ZENTAO_HUB_CREDENTIALS`| Optional                                     | Override credentials file location (default: `~/.zentao-hub/credentials.json`). |
+
+## Wiring it up to an MCP client
+
+`@zentao-hub/mcp` is a vanilla stdio MCP server, so it drops into any
+MCP-capable client. The sister CLI knows the config file format and location
+for the major agents and writes the entry for you:
+
+```bash
+npm install -g @zentao-hub/cli
+zentao-hub login                          # cache credentials once (shared)
+zentao-hub install mcp --agent claude     # claude | copilot | copilot-cli | codex
+```
+
+| `--agent`     | Tool                        | Writes to                                                                                |
+| ------------- | --------------------------- | ---------------------------------------------------------------------------------------- |
+| `claude`      | Claude Code / Desktop       | `~/.claude.json` (user) or `<repo>/.mcp.json` (workspace)                                |
+| `copilot`     | GitHub Copilot (VS Code)    | `User/mcp.json` (user) or `<repo>/.vscode/mcp.json` (workspace)                          |
+| `copilot-cli` | GitHub Copilot CLI          | `~/.copilot/mcp-config.json` (user) or `<repo>/.mcp.json` (workspace, shared with Claude)|
+| `codex`       | OpenAI Codex CLI            | `~/.codex/config.toml` (user-only)                                                       |
+
+For everything else (Cline, Continue, custom clients) hand-edit the config —
+the shape is `command: "zentao-hub-mcp"` with no required args, see the
+Claude Code example below.
+
+### Claude Code / Claude Desktop — using `zentao-hub login`
+
+After `zentao-hub login` the env block can be omitted entirely:
+
+```json
+{
+  "mcpServers": {
+    "zentao-hub": {
+      "command": "zentao-hub-mcp"
+    }
+  }
+}
+```
+
+With multiple profiles, pin one per MCP server entry:
+
+```json
+{
+  "mcpServers": {
+    "zentao-hub":          { "command": "zentao-hub-mcp" },
+    "zentao-hub-personal": { "command": "zentao-hub-mcp", "env": { "ZENTAO_PROFILE": "personal" } }
+  }
+}
+```
+
+### Claude Code / Claude Desktop — env-only (no CLI, e.g. for CI)
+
+```json
+{
+  "mcpServers": {
+    "zentao-hub": {
+      "command": "zentao-hub-mcp",
+      "env": {
+        "ZENTAO_URL": "https://zentao.example.com",
+        "ZENTAO_USERNAME": "your-account",
+        "ZENTAO_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+Claude Code CLI (env-only example):
+
+```bash
+claude mcp add zentao-hub \
+  --env ZENTAO_URL=https://zentao.example.com \
+  --env ZENTAO_USERNAME=your-account \
+  --env ZENTAO_PASSWORD=your-password \
+  -- zentao-hub-mcp
+```
+
+## Usage conventions
+
+- **List tools default to `limit=20`**, max 200. `page` is 1-based.
+- **`list_my_bugs` / `list_my_tasks`** filter on the server side by `assignedTo.account == <current account>`, bypassing ZenTao v1's unreliable query parameters. The scan cap is `maxScan` (default 1000); the result includes a `truncated` flag.
+- **State transitions use dedicated action tools** (`resolve_bug`, `finish_task`, `close_story`, ...) instead of `update_*`. ZenTao relies on `/{entity}/{id}/{action}` endpoints to drive its state machine and history records. `update_*` only changes fields and does not trigger state transitions.
+- **`zentao_request` is the escape hatch.** Any endpoint without a typical wrapper (custom workflows, third-party extensions, endpoints added in newer versions) can be called directly:
+  ```json
+  {"method": "GET", "path": "/products/27/testreports", "query": {"limit": 10}}
+  ```
+
+## Behavior details
+
+- **Automatic token refresh.** Any tool that gets a 401 clears the cached token, re-logs in once, and retries. In `ZENTAO_TOKEN`-only mode (no credentials to refresh with), the 401 is re-thrown as-is.
+- **Compatible list shapes.** List tools auto-adapt to ZenTao's various wrappers (`{bugs:[...]}`, `{products:[...]}`, `{data:[...]}`, `{list:[...]}`, or a bare array) and try to extract `total`.
+- **Summary field trimming.** List tools return only commonly used fields by default (id / title / status / assignedTo / openedDate / ...). Use the corresponding `get_*` for full details.
+- **`download_bug_attachments`** additionally parses `<img src>` tags inside `bug.steps` to download inline screenshots into `destDir/inline/`. A single failure does not abort the rest.
+
+## Development
+
+```bash
+# From the monorepo root (uses pnpm)
+corepack enable
+pnpm install
+pnpm run build         # build everything
+pnpm run dev           # watch everything
+
+# Only this package
+pnpm --filter @zentao-hub/mcp run build
+```
+
+Smoke test (no real ZenTao instance required):
+
+```bash
+ZENTAO_URL=http://example.invalid ZENTAO_TOKEN=fake \
+  node dist/index.js
+# Send JSON-RPC `initialize` + `tools/list` over stdin to verify.
+```
+
+## Source layout
+
+```
+src/
+├── index.ts                    entry point + stdio transport + tool registration
+├── zentao-client.ts            HTTP client: login, token refresh, timeout, download
+└── tools/
+    ├── index.ts                aggregator: buildTools(client)
+    ├── helpers.ts              shared schema fragments, summary-key sets, JSON extraction
+    ├── request.ts              zentao_request escape hatch
+    ├── users.ts                whoami / users / departments
+    ├── products.ts             products / branches / modules / plans
+    ├── projects.ts             projects / project executions / project products
+    ├── programs.ts             programs
+    ├── executions.ts           executions + execution tasks/stories/team
+    ├── stories.ts              stories CRUD + change/review/close/activate/assign/comment
+    ├── tasks.ts                tasks CRUD + start/finish/pause/activate/close/cancel/assign/comment
+    ├── bugs.ts                 bugs CRUD + resolve/close/confirm/activate/assign/comment/history/attachments
+    ├── cases.ts                cases / test results / testsuites / testtasks
+    ├── testreports.ts          test reports
+    ├── builds.ts               product/execution builds
+    ├── releases.ts             product releases
+    ├── repos.ts                code repos + branches + commits
+    ├── docs.ts                 doclibs / docs
+    ├── efforts.ts              effort (work-hour) logs
+    ├── todos.ts                personal todos
+    ├── issues.ts               project issues
+    └── risks.ts                project risks
+```
+
+Adding a new tool: drop a `defineTool({ description, schema, handler })` into the matching entity module — it gets picked up automatically by the `build*Tools(ctx)` calls in `tools/index.ts`.
+
+## License
+
+[MIT](../../LICENSE) © Deven Liu

package/README.zh-CN.md

@@ -0,0 +1,225 @@
+# @zentao-hub/mcp
+
+[English](README.md) | 简体中文
+
+面向 **禅道 20.x 开源版** 的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，覆盖禅道 v1 REST API 的常用实体（产品 / 项目 / 计划 / 迭代 / 需求 / 任务 / Bug / 测试用例 / 构建 / 发布 / 代码库 / 用户 / 文档），加一个通用的 `zentao_request` 逃生口兜底未包装的端点。
+
+> 想要 hub 目录、slash command、commit-msg hook 这些自动化协作工件，看姐妹包 [`@zentao-hub/cli`](../cli)。本包只做 MCP server 本身。
+
+## 工具总览（129 个）
+
+| 实体           | 工具                                                                                                                                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **用户/部门**  | `whoami` · `list_users` · `get_user` · `list_departments` · `list_department_users`                                                                                                                                                                                            |
+| **产品**       | `list_products` · `get_product` · `create_product` · `update_product` · `delete_product` · `list_product_branches` · `list_product_modules` · `list_product_plans` · `list_product_executions`                                                                                 |
+| **项目**       | `list_projects` · `get_project` · `create_project` · `update_project` · `delete_project` · `list_project_executions` · `list_project_products`                                                                                                                                 |
+| **项目集**     | `list_programs` · `get_program` · `create_program` · `delete_program`                                                                                                                                                                                                          |
+| **执行/迭代**  | `list_executions` · `get_execution` · `create_execution` · `update_execution` · `delete_execution` · `start_execution` · `close_execution` · `list_execution_tasks` · `list_execution_stories` · `list_execution_team`                                                         |
+| **需求**       | `list_product_stories` · `get_story` · `create_story` · `update_story` · `delete_story` · `change_story` · `review_story` · `close_story` · `activate_story` · `assign_story` · `add_story_comment`                                                                            |
+| **任务**       | `get_task` · `list_my_tasks` · `create_task` · `update_task` · `delete_task` · `start_task` · `finish_task` · `pause_task` · `activate_task` · `close_task` · `cancel_task` · `assign_task` · `add_task_comment`                                                                |
+| **Bug**        | `list_my_bugs` · `list_product_bugs` · `list_execution_bugs` · `get_bug` · `create_bug` · `update_bug` · `delete_bug` · `resolve_bug` · `close_bug` · `confirm_bug` · `activate_bug` · `assign_bug` · `add_bug_comment` · `get_bug_history` · `download_bug_attachments`        |
+| **测试用例**   | `list_product_cases` · `get_case` · `create_case` · `update_case` · `delete_case` · `create_case_result` · `list_case_results` · `list_product_testsuites` · `list_product_testtasks`                                                                                          |
+| **测试报告**   | `list_product_testreports` · `get_testreport` · `create_testreport` · `delete_testreport`                                                                                                                                                                                      |
+| **构建**       | `list_product_builds` · `list_execution_builds` · `get_build` · `create_build` · `delete_build`                                                                                                                                                                                |
+| **发布**       | `list_product_releases` · `get_release` · `create_release` · `delete_release`                                                                                                                                                                                                  |
+| **代码库**     | `list_repos` · `get_repo` · `list_repo_branches` · `list_repo_commits`                                                                                                                                                                                                         |
+| **文档**       | `list_doclibs` · `list_doclib_docs` · `get_doc` · `create_doc` · `update_doc` · `delete_doc`                                                                                                                                                                                   |
+| **工时(effort)** | `log_effort` · `list_efforts` · `update_effort` · `delete_effort`                                                                                                                                                                                                            |
+| **待办**       | `list_todos` · `get_todo` · `create_todo` · `update_todo` · `finish_todo` · `delete_todo`                                                                                                                                                                                      |
+| **问题**       | `list_project_issues` · `get_issue` · `create_issue` · `update_issue` · `resolve_issue` · `close_issue` · `delete_issue`                                                                                                                                                       |
+| **风险**       | `list_project_risks` · `get_risk` · `create_risk` · `update_risk` · `delete_risk`                                                                                                                                                                                              |
+| **逃生口**     | `zentao_request` — 任意 `GET / POST / PUT / DELETE` 到 `/api.php/v1/...`，覆盖没显式包装的端点                                                                                                                                                                                  |
+
+**关于 product 作用域**：禅道 v1 REST API 大多 bug / story / case / build / release 接口都按产品作用域。第一步通常先 `list_products` 拿 productId。
+
+## 环境要求
+
+- Node.js ≥ 18
+- 一台开启了 v1 REST API 的禅道 20.x 实例，并能从本机访问
+- 一个开发者账号（账号 / 密码），或一个已签发的 token
+
+## 安装
+
+```bash
+npm install -g @zentao-hub/mcp
+# 或在 monorepo 内：从根目录 `pnpm install && pnpm run build`
+```
+
+可执行入口：`zentao-hub-mcp`（即 `dist/index.js`）。
+
+## 配置
+
+推荐做法：通过姊妹 CLI [`@zentao-hub/cli`](../cli) 登录一次，MCP 服务自动读取：
+
+```bash
+npm install -g @zentao-hub/cli @zentao-hub/mcp
+zentao-hub login                          # 默认 profile
+zentao-hub login --profile personal       # 多个禅道实例时再加一个
+zentao-hub profiles                       # 列出并切换默认 profile
+```
+
+CLI 把 URL + 用户名 + token 存到 `~/.zentao-hub/credentials.json`（权限 0600），
+密码缓存在系统 keychain（macOS Keychain / Linux libsecret / Windows
+Credential Manager）。MCP server 在环境变量未设置时自动读取，token 过期时
+用缓存密码静默续期。
+
+### 环境变量
+
+环境变量优先级高于凭据文件，CI/CD 场景仍可显式注入。
+
+| 环境变量                | 何时使用                              | 说明                                                                 |
+| ----------------------- | ------------------------------------- | -------------------------------------------------------------------- |
+| `ZENTAO_PROFILE`        | 配置了多个 profile                    | 选用哪个 profile。默认使用文件中的 `default`，若只有 1 个 profile 直接用它。 |
+| `ZENTAO_URL`            | 不使用凭据文件时                      | 禅道地址，例如 `https://zentao.example.com`（结尾不要 `/`）。        |
+| `ZENTAO_TOKEN`          | 与（用户名+密码）二选一               | 已签发的 token。此模式下自动续期关闭。                               |
+| `ZENTAO_USERNAME`       | 与密码同时提供                        | 账号；启动时换取 token，401 时自动重新登录。                         |
+| `ZENTAO_PASSWORD`       | 与账号同时提供                        | 密码。                                                               |
+| `ZENTAO_TIMEOUT_MS`     | 可选                                  | 单次请求超时，毫秒，默认 `15000`。                                   |
+| `ZENTAO_HUB_CREDENTIALS`| 可选                                  | 覆盖凭据文件路径（默认 `~/.zentao-hub/credentials.json`）。           |
+
+## 接入 MCP 客户端
+
+`@zentao-hub/mcp` 是一个标准的 stdio MCP server，可接入任何 MCP-capable client。
+姊妹 CLI 内置了主流 agent 的配置格式与位置，可一条命令注册：
+
+```bash
+npm install -g @zentao-hub/cli
+zentao-hub login                          # 凭据缓存一次，所有 agent 共用
+zentao-hub install mcp --agent claude     # claude | copilot | copilot-cli | codex
+```
+
+| `--agent`     | 对应工具                  | 写入文件                                                                              |
+| ------------- | ------------------------- | ------------------------------------------------------------------------------------- |
+| `claude`      | Claude Code / Desktop     | `~/.claude.json`（user）或 `<repo>/.mcp.json`（workspace）                            |
+| `copilot`     | GitHub Copilot（VS Code） | `User/mcp.json`（user）或 `<repo>/.vscode/mcp.json`（workspace）                      |
+| `copilot-cli` | GitHub Copilot CLI        | `~/.copilot/mcp-config.json`（user）或 `<repo>/.mcp.json`（workspace，与 Claude 共用）|
+| `codex`       | OpenAI Codex CLI          | `~/.codex/config.toml`（仅 user）                                                     |
+
+其他 client（Cline、Continue、自研客户端等）手工编辑 config 即可——形如
+`command: "zentao-hub-mcp"`，无需必填参数，参考下面的 Claude Code 示例。
+
+### Claude Code / Claude Desktop — 使用 `zentao-hub login`
+
+`zentao-hub login` 完成后 env 块完全可省略：
+
+```json
+{
+  "mcpServers": {
+    "zentao-hub": {
+      "command": "zentao-hub-mcp"
+    }
+  }
+}
+```
+
+配置了多个 profile 时，给每个 MCP server 条目指定一个：
+
+```json
+{
+  "mcpServers": {
+    "zentao-hub":          { "command": "zentao-hub-mcp" },
+    "zentao-hub-personal": { "command": "zentao-hub-mcp", "env": { "ZENTAO_PROFILE": "personal" } }
+  }
+}
+```
+
+### Claude Code / Claude Desktop — 纯环境变量（不依赖 CLI，例如 CI）
+
+```json
+{
+  "mcpServers": {
+    "zentao-hub": {
+      "command": "zentao-hub-mcp",
+      "env": {
+        "ZENTAO_URL": "https://zentao.example.com",
+        "ZENTAO_USERNAME": "你的账号",
+        "ZENTAO_PASSWORD": "你的密码"
+      }
+    }
+  }
+}
+```
+
+Claude Code CLI（纯环境变量示例）：
+
+```bash
+claude mcp add zentao-hub \
+  --env ZENTAO_URL=https://zentao.example.com \
+  --env ZENTAO_USERNAME=你的账号 \
+  --env ZENTAO_PASSWORD=你的密码 \
+  -- zentao-hub-mcp
+```
+
+## 用法约定
+
+- **列表工具默认 `limit=20`**，最大 200。`page` 1-based。
+- **list_my_bugs / list_my_tasks** 在服务端按 `assignedTo.account == <当前账号>` 过滤，绕开禅道 v1 不可靠的查询参数；扫描上限由 `maxScan`（默认 1000）控制，结果中 `truncated` 标记是否截断。
+- **状态转移用专用动作工具**（`resolve_bug`、`finish_task`、`close_story` …），而不是 `update_*` —— 禅道靠 `/{entity}/{id}/{action}` 端点驱动状态机和历史记录。`update_*` 只改字段，不触发状态变更。
+- **`zentao_request` 是逃生口**：任何没典型 wrapper 的端点（自定义工作流、第三方扩展、新版本里新增端点）都可以直接调，例如：
+  ```json
+  {"method": "GET", "path": "/products/27/testreports", "query": {"limit": 10}}
+  ```
+
+## 行为细节
+
+- **Token 自动刷新**：任何工具收到 401 都会清掉缓存 token、重登一次、重试。仅 `ZENTAO_TOKEN` 模式（没账号密码可刷新）下 401 会原样抛回。
+- **列表结构兼容**：list 工具自动适配 `{bugs:[...]}` / `{products:[...]}` / `{data:[...]}` / `{list:[...]}` / 裸数组等多种禅道返回包装，并尽量提取 `total`。
+- **summary 字段裁剪**：list 工具默认只回常用字段（id / title / status / assignedTo / openedDate …）。要全字段就用对应的 `get_*`。
+- **`download_bug_attachments`** 还会解析 bug.steps 里的 `<img src>` 把内联截图也下载到 `destDir/inline/`，单个失败不中断。
+
+## 开发
+
+```bash
+# 在 monorepo 根目录（使用 pnpm）
+corepack enable
+pnpm install
+pnpm run build         # 全部构建
+pnpm run dev           # 全部 watch
+
+# 仅本包
+pnpm --filter @zentao-hub/mcp run build
+```
+
+冒烟测试（不需要真实禅道实例）：
+
+```bash
+ZENTAO_URL=http://example.invalid ZENTAO_TOKEN=fake \
+  node dist/index.js
+# 通过 stdin 发 JSON-RPC `initialize` + `tools/list` 验证。
+```
+
+## 源码组织
+
+```
+src/
+├── index.ts                    入口 + stdio transport + 工具注册
+├── zentao-client.ts            HTTP 客户端：登录、token 刷新、超时、下载
+└── tools/
+    ├── index.ts                聚合 buildTools(client)
+    ├── helpers.ts              共用 schema 片段、summary key 集合、JSON 提取
+    ├── request.ts              zentao_request 逃生口
+    ├── users.ts                whoami / users / departments
+    ├── products.ts             products / branches / modules / plans
+    ├── projects.ts             projects / project executions / project products
+    ├── programs.ts             programs
+    ├── executions.ts           executions + execution tasks/stories/team
+    ├── stories.ts              stories CRUD + change/review/close/activate/assign/comment
+    ├── tasks.ts                tasks CRUD + start/finish/pause/activate/close/cancel/assign/comment
+    ├── bugs.ts                 bugs CRUD + resolve/close/confirm/activate/assign/comment/history/attachments
+    ├── cases.ts                cases / test results / testsuites / testtasks
+    ├── testreports.ts          test reports
+    ├── builds.ts               product/execution builds
+    ├── releases.ts             product releases
+    ├── repos.ts                code repos + branches + commits
+    ├── docs.ts                 doclibs / docs
+    ├── efforts.ts              effort (work-hour) logs
+    ├── todos.ts                personal todos
+    ├── issues.ts               project issues
+    └── risks.ts                project risks
+```
+
+加新工具：在对应实体模块里加一个 `defineTool({ description, schema, handler })`，然后会被 `tools/index.ts` 的 `build*Tools(ctx)` 自动带进来。
+
+## License
+
+[MIT](../../LICENSE) © Deven Liu

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ZentaoApiError, createClientFromConfig, loadZentaoConfig, } from "@zentao-hub/sdk";
+import { buildTools } from "./tools/index.js";
+function toToolResult(value) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+            },
+        ],
+    };
+}
+function toErrorResult(err) {
+    const msg = err instanceof ZentaoApiError
+        ? `${err.message}${err.body ? `\n${JSON.stringify(err.body, null, 2).slice(0, 1000)}` : ""}`
+        : err instanceof Error
+            ? err.message
+            : String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: msg }],
+    };
+}
+async function main() {
+    const config = loadZentaoConfig();
+    const client = createClientFromConfig(config);
+    const tools = buildTools(client);
+    const server = new McpServer({
+        name: "zentao-hub",
+        version: "0.3.0",
+    });
+    for (const [name, def] of Object.entries(tools)) {
+        server.registerTool(name, {
+            description: def.description,
+            inputSchema: def.schema.shape,
+        }, async (args) => {
+            try {
+                const parsed = def.schema.parse(args);
+                // The handler signatures are tied to each tool's own schema; the cast
+                // bridges the heterogeneous union back to the per-tool argument type.
+                const result = await def.handler(parsed);
+                return toToolResult(result);
+            }
+            catch (err) {
+                return toErrorResult(err);
+            }
+        });
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdio transport keeps the process alive via stdin; nothing else to do here.
+}
+main().catch((err) => {
+    // stderr is safe — stdio transport reserves stdout for the JSON-RPC channel.
+    console.error("zentao-hub-mcp failed to start:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/bugs.d.ts

@@ -0,0 +1,2 @@
+import { type ToolDef, type ToolFactoryCtx } from "./helpers.js";
+export declare function buildBugTools(ctx: ToolFactoryCtx): Record<string, ToolDef>;