@dyno181cm.nexsoft/zentao_mcp 1.3.0 → 1.4.1

package/README.md

@@ -1,62 +1,93 @@
 # Zentao MCP Server
 
-A Model Context Protocol (MCP) server for integrating with the Zentao API. This server provides tools to access project management data from Zentao directly through MCP-compatible interfaces.
+[![npm version](https://img.shields.io/npm/v/@dyno181cm.nexsoft/zentao_mcp?style=flat-square&color=CB3837&logo=npm)](https://www.npmjs.com/package/@dyno181cm.nexsoft/zentao_mcp)
+[![npm downloads](https://img.shields.io/npm/dm/@dyno181cm.nexsoft/zentao_mcp?style=flat-square&color=CB3837&logo=npm)](https://www.npmjs.com/package/@dyno181cm.nexsoft/zentao_mcp)
+[![GitHub release](https://img.shields.io/github/v/tag/dyno-nexsoft/zentao_mcp?style=flat-square&label=release&color=2ea44f&logo=github)](https://github.com/dyno-nexsoft/zentao_mcp/releases)
+[![License](https://img.shields.io/github/license/dyno-nexsoft/zentao_mcp?style=flat-square)](https://github.com/dyno-nexsoft/zentao_mcp/blob/master/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square&logo=node.js)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript)](https://www.typescriptlang.org)
+[![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square)](https://modelcontextprotocol.io)
 
-## Features
+A **Model Context Protocol (MCP)** server for integrating AI assistants (Claude, Cursor, etc.) with the [ZenTao](https://www.zentao.net) project management API.  
+Fetch task details, bug reports, and attachments — all directly inside your AI chat.
 
-- **Authentication**: Automatically handles login and token management for Zentao.
-- **MCP Tools**:
-  - `zentao_get_task_details`: Get detailed information about a specific task by ID.
-  - `zentao_get_bug_details`: Get detailed information about a specific bug.
-  - `zentao_download_attachment`: Download file attachments from ZenTao (e.g., bug/task images or videos).
+---
 
-## Requirements
+## ✨ Features
 
-- Node.js (v18 or higher recommended)
-- A Zentao instance accessible via API
+| Tool | Description |
+|---|---|
+| `zentao_get_task_details` | Fetch full details of a task by ID (status, assignee, description, history & comments, attachments) |
+| `zentao_get_bug_details` | Fetch full details of a bug by ID (severity, repro steps, history & comments, inline images, attachments) |
+| `zentao_download_attachment` | Download any ZenTao file attachment to local disk |
+| `zentao_get_comments` | Fetch only the history and comments timeline of a task or bug |
+| `zentao_update_task_status` | Update task status (start, finish, close, pause, cancel, restart) and add optional comments/hours |
+| `zentao_update_bug_status` | Update bug status (resolve, close, activate) and add optional comments/resolutions |
 
-## Installation
 
-1. Clone the repository:
+**Under the hood:**
+- 🔐 Auto login & token refresh — no manual auth needed
+- 📦 In-memory cache (2 min TTL) + in-flight request dedup — avoids redundant API calls
+- 🖼️ Inline HTML images are automatically downloaded and served as local `file://` links
+- 📎 Attachments are downloaded and embedded as clickable local links
+- 🛡️ Corrupt partial downloads are auto-cleaned on error
 
-   ```bash
-   git clone https://github.com/dyno-nexsoft/zentao_mcp.git
-   cd zentao_mcp
-   ```
+---
 
-2. Install dependencies:
+## 📦 Installation
 
-   ```bash
-   npm install
-   ```
+### Option 1 — `npx` (recommended, no install required)
 
-3. Configure environment variables:
-   Create a `.env` file in the root directory and add the following configurations:
-   ```env
-   ZENTAO_BASE_URL=https://your-zentao-url.com/api.php/v1
-   ZENTAO_ACCOUNT=your_username
-   ZENTAO_PASSWORD=your_password
-   ```
+```bash
+npx @dyno181cm.nexsoft/zentao_mcp
+```
+
+### Option 2 — Global install
+
+```bash
+npm install -g @dyno181cm.nexsoft/zentao_mcp
+zentao_mcp
+```
+
+### Option 3 — Clone & build
+
+```bash
+git clone https://github.com/dyno-nexsoft/zentao_mcp.git
+cd zentao_mcp
+npm install
+npm run build
+```
+
+---
+
+## ⚙️ Configuration
 
-## Usage
+Create a `.env` file in the project root (or pass via MCP client `env` block):
 
-This server communicates via standard input/output (`stdio`), making it compatible with any MCP client that supports stdio transport.
+```env
+ZENTAO_BASE_URL=https://your-zentao-url.com/zentao/api.php/v1
+ZENTAO_ACCOUNT=your_username
+ZENTAO_PASSWORD=your_password
+```
+
+---
+
+## 🔌 MCP Client Integration
 
-### Integrating with MCP Clients (Claude Desktop, Cursor, etc.)
+This server communicates via **stdio transport** — compatible with any MCP client.
 
-Once published to npm or GitHub, users can integrate this server into their MCP clients easily. Add the following to your MCP client configuration (e.g., `claude_desktop_config.json`):
+### Claude Desktop / Cursor / Windsurf
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "zentao": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@dyno181cm.nexsoft/zentao_mcp"
-      ],
+      "args": ["-y", "@dyno181cm.nexsoft/zentao_mcp"],
       "env": {
-        "ZENTAO_BASE_URL": "https://your-zentao-url.com/api.php/v1",
+        "ZENTAO_BASE_URL": "https://your-zentao-url.com/zentao/api.php/v1",
         "ZENTAO_ACCOUNT": "your_username",
         "ZENTAO_PASSWORD": "your_password"
       }
@@ -65,17 +96,106 @@ Once published to npm or GitHub, users can integrate this server into their MCP
 }
 ```
 
-### Available Tools
+---
+
+## 🛠️ Available Tools
+
+### `zentao_get_task_details`
+Get full details of a ZenTao task.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `taskId` | `string \| number` | ✅ | Task ID |
+
+### `zentao_get_bug_details`
+Get full details of a ZenTao bug, including repro steps and inline images.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `bugId` | `string \| number` | ✅ | Bug ID |
+
+### `zentao_download_attachment`
+Download a ZenTao file attachment to local disk.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `fileId` | `string \| number` | ✅ | File ID to download |
+| `extension` | `string` | ❌ | File extension hint (e.g. `mp4`, `png`) |
+
+### `zentao_get_comments`
+Get only the history and comments timeline of a task or bug.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `type` | `"task" \| "bug"` | ✅ | Type of the object |
+| `id` | `string \| number` | ✅ | Task or Bug ID |
+
+### `zentao_update_task_status`
+Update a task's status with optional comments, actual start/finish dates, and consumed hours.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `taskId` | `string \| number` | ✅ | Task ID |
+| `action` | `"start" \| "finish" \| "close" \| "pause" \| "cancel" \| "restart"` | ✅ | Status transition action |
+| `comment` | `string` | ❌ | Optional comment to attach |
+| `consumed` | `number` | ❌ | Optional hours consumed |
+| `finishedDate` | `string` | ❌ | Optional actual finish date (YYYY-MM-DD) |
+| `realStarted` | `string` | ❌ | Optional actual start date (YYYY-MM-DD) |
+| `assignedTo` | `string` | ❌ | Optional user account to assign to next |
+| `left` | `number` | ❌ | Optional left hours (for `restart`) |
+
+### `zentao_update_bug_status`
+Update a bug's status with optional comments and resolutions.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `bugId` | `string \| number` | ✅ | Bug ID |
+| `action` | `"resolve" \| "close" \| "activate"` | ✅ | Status transition action |
+| `comment` | `string` | ❌ | Optional comment to attach |
+| `resolution` | `"fixed" \| "bydesign" \| "postponed" \| "external" \| "notrepro" \| "willnotfix"` | ❌ | Optional resolution type |
+| `resolvedBuild` | `string` | ❌ | Optional build ID where bug was resolved |
+| `resolvedDate` | `string` | ❌ | Optional resolution date (YYYY-MM-DD) |
+| `assignedTo` | `string` | ❌ | Optional user account to assign to next |
+| `openedBuild` | `string` | ❌ | Optional build ID where bug was found (for `activate`) |
+
+---
+
+## 🧑‍💻 Development
+
+```bash
+npm run build      # Compile TypeScript
+npm run dev        # Watch mode
+npm test           # Unit tests (Jest)
+npm run test:api   # Live API integration test
+```
+
+### Project structure
+
+```
+src/
+├── index.ts                  # MCP server entry point
+├── zentaoClient.ts           # Axios client: auth, cache, dedup, status updates
+├── tools.ts                  # Thin orchestrator + backward-compat exports
+├── utils/
+│   ├── fileUtils.ts          # toFileUrl · getMimeType · formatSize
+│   ├── markdownUtils.ts      # htmlToMarkdown · parseFiles · formatUser
+│   └── mcpResponse.ts        # mcpText · buildMcpResponse
+├── formatters/
+│   ├── imageLocalizer.ts     # Inline <img> → local file:// link
+│   ├── attachmentRenderer.ts # Attachments → Markdown ## Files section
+│   ├── actionFormatter.ts    # renderHistoryAndComments
+│   ├── taskFormatter.ts      # taskToMarkdown (includes comments)
+│   └── bugFormatter.ts       # bugToMarkdown (includes comments)
+└── tools/
+    ├── taskTool.ts           # zentao_get_task_details registration
+    ├── bugTool.ts            # zentao_get_bug_details registration
+    ├── downloadTool.ts       # zentao_download_attachment registration
+    ├── commentTool.ts        # zentao_get_comments registration
+    └── statusTool.ts         # status update tools registration
+```
 
-- **`zentao_get_task_details`**
-  - **Inputs:**
-    - `taskId` (string | number) - Required. Task ID.
+---
 
-- **`zentao_get_bug_details`**
-  - **Inputs:**
-    - `bugId` (string | number) - Required. Bug ID.
+## 📄 License
 
-- **`zentao_download_attachment`**
-  - **Inputs:**
-    - `fileId` (string | number) - Required. File ID to download.
-    - `extension` (string) - Optional. File extension (e.g., mp4, png).
+[MIT](./LICENSE) © [dyno-nexsoft](https://github.com/dyno-nexsoft)

package/build/formatters/actionFormatter.js

@@ -0,0 +1,94 @@
+import { htmlToMarkdown, parseFiles } from "../utils/markdownUtils.js";
+import { localizeImages } from "./imageLocalizer.js";
+import { toFileUrl, formatSize } from "../utils/fileUtils.js";
+import * as path from "path";
+import * as os from "os";
+import fs from "fs";
+/**
+ * Normalizes and formats the history/comments/actions list into a clean Markdown block.
+ *
+ * @param actions          The raw actions array from Zentao task or bug response.
+ * @param client           Authenticated ZentaoClient used for image/attachment downloads.
+ * @param downloadedImages Optional collector for local image paths.
+ */
+export async function renderHistoryAndComments(actions, client, downloadedImages) {
+    if (!actions || !Array.isArray(actions) || actions.length === 0) {
+        return "";
+    }
+    const lines = [];
+    for (const act of actions) {
+        // 1. Localize and convert the action description (desc)
+        let desc = "";
+        if (act.desc) {
+            const localizedDesc = await localizeImages(act.desc, client, downloadedImages);
+            desc = htmlToMarkdown(localizedDesc).trim();
+            // Remove date prefix from desc if it exists to avoid redundancy
+            if (act.date) {
+                const prefixes = [act.date + ",", act.date + " "];
+                for (const prefix of prefixes) {
+                    if (desc.startsWith(prefix)) {
+                        desc = desc.substring(prefix.length).trim();
+                        break;
+                    }
+                }
+            }
+        }
+        // Fallback if description is empty
+        if (!desc) {
+            desc = `${act.actor || "User"} did action "${act.action || "unknown"}"`;
+        }
+        // 2. Format comment if present
+        let commentStr = "";
+        if (act.comment) {
+            const localizedComment = await localizeImages(act.comment, client, downloadedImages);
+            const commentMd = htmlToMarkdown(localizedComment).trim();
+            if (commentMd) {
+                // Blockquote the comment
+                commentStr = `\n  > ${commentMd.replace(/\n/g, '\n  > ')}`;
+            }
+        }
+        // 3. Format files if present in action
+        let filesStr = "";
+        if (act.files && Array.isArray(act.files) && act.files.length > 0) {
+            const parsedFiles = parseFiles(act.files);
+            if (parsedFiles.length > 0) {
+                const fileLinks = [];
+                for (const f of parsedFiles) {
+                    const ext = (f.extension || '').toLowerCase();
+                    const targetPath = path.join(os.tmpdir(), `zentao_file_${f.id}.${ext}`);
+                    let localPath = null;
+                    try {
+                        localPath = fs.existsSync(targetPath)
+                            ? targetPath
+                            : await client.downloadFile(f.id, targetPath);
+                        if (localPath && downloadedImages && !downloadedImages.includes(localPath)) {
+                            downloadedImages.push(localPath);
+                        }
+                    }
+                    catch {
+                        // ignore download error
+                    }
+                    if (localPath) {
+                        fileLinks.push(`[${f.title}](${toFileUrl(localPath)}) *(Size: ${formatSize(f.size)})*`);
+                    }
+                    else {
+                        fileLinks.push(`[${f.title}] *(download failed)*`);
+                    }
+                }
+                if (fileLinks.length > 0) {
+                    filesStr = `\n  - *Attachments:* ${fileLinks.join(", ")}`;
+                }
+            }
+        }
+        // 4. Combine into a timeline item
+        lines.push(`- **[${act.date || "N/A"}]** ${desc}${commentStr}${filesStr}`);
+    }
+    if (lines.length === 0)
+        return "";
+    return [
+        "",
+        "## History & Comments",
+        "",
+        ...lines,
+    ].join("\n");
+}

package/build/formatters/bugFormatter.js

@@ -1,6 +1,7 @@
 import { htmlToMarkdown, parseFiles, formatUser } from "../utils/markdownUtils.js";
 import { localizeImages } from "./imageLocalizer.js";
 import { renderAttachments } from "./attachmentRenderer.js";
+import { renderHistoryAndComments } from "./actionFormatter.js";
 /**
  * Format a raw ZenTao bug object into a human-readable Markdown document.
  *
@@ -32,13 +33,20 @@ export async function bugToMarkdown(rawBug, client, downloadedImages) {
     const localizedSteps = await localizeImages(rawBug.steps, client, downloadedImages);
     const steps = htmlToMarkdown(localizedSteps);
     const attachments = await renderAttachments(parseFiles(rawBug.files), client, downloadedImages);
-    return [
+    const historySection = await renderHistoryAndComments(rawBug.actions, client, downloadedImages);
+    const parts = [
         `# Bug #${rawBug.id}: ${rawBug.title}`,
         '',
         ...meta.map((m) => `- ${m}`),
         '',
         '## Repro Steps',
         steps || '*No steps provided.*',
-        attachments,
-    ].join('\n');
+    ];
+    if (attachments) {
+        parts.push(attachments);
+    }
+    if (historySection) {
+        parts.push(historySection);
+    }
+    return parts.join('\n');
 }

package/build/formatters/taskFormatter.js

@@ -1,6 +1,7 @@
 import { htmlToMarkdown, parseFiles, formatUser } from "../utils/markdownUtils.js";
 import { localizeImages } from "./imageLocalizer.js";
 import { renderAttachments } from "./attachmentRenderer.js";
+import { renderHistoryAndComments } from "./actionFormatter.js";
 /**
  * Format a raw ZenTao task object into a human-readable Markdown document.
  *
@@ -35,13 +36,20 @@ export async function taskToMarkdown(rawTask, client, downloadedImages) {
     const localizedDesc = await localizeImages(rawTask.desc, client, downloadedImages);
     const desc = htmlToMarkdown(localizedDesc);
     const attachments = await renderAttachments(parseFiles(rawTask.files), client, downloadedImages);
-    return [
+    const historySection = await renderHistoryAndComments(rawTask.actions, client, downloadedImages);
+    const parts = [
         `# Task #${rawTask.id}: ${rawTask.name}`,
         '',
         ...meta.map((m) => `- ${m}`),
         '',
         '## Description',
         desc || '*No description provided.*',
-        attachments,
-    ].join('\n');
+    ];
+    if (attachments) {
+        parts.push(attachments);
+    }
+    if (historySection) {
+        parts.push(historySection);
+    }
+    return parts.join('\n');
 }

package/build/tools/commentTool.js

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { renderHistoryAndComments } from "../formatters/actionFormatter.js";
+import { buildMcpResponse } from "../utils/mcpResponse.js";
+/**
+ * Register the `zentao_get_comments` MCP tool on the given server.
+ *
+ * @param server The MCP Server instance.
+ * @param client Authenticated ZentaoClient used to fetch and process data.
+ */
+export function registerCommentTool(server, client) {
+    server.registerTool("zentao_get_comments", {
+        description: "Get only the history and comments timeline of a task or a bug",
+        inputSchema: {
+            type: z.enum(["task", "bug"]).describe("Type of the object ('task' or 'bug')"),
+            id: z.union([z.string(), z.number()]).describe("Task or Bug ID"),
+        },
+    }, async ({ type, id }) => {
+        let data;
+        if (type === "task") {
+            data = await client.getTaskDetails(id);
+        }
+        else {
+            data = await client.getBugDetails(id);
+        }
+        const downloadedImages = [];
+        const markdown = await renderHistoryAndComments(data.actions, client, downloadedImages);
+        const title = type === "task" ? `Task #${data.id || id}: ${data.name || ""}` : `Bug #${data.id || id}: ${data.title || ""}`;
+        const output = [
+            `# History & Comments for ${title}`,
+            markdown.trim() || "*No history or comments found.*"
+        ].join("\n\n");
+        return buildMcpResponse(output, downloadedImages);
+    });
+}

package/build/tools/statusTool.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { taskToMarkdown } from "../formatters/taskFormatter.js";
+import { bugToMarkdown } from "../formatters/bugFormatter.js";
+import { buildMcpResponse } from "../utils/mcpResponse.js";
+/**
+ * Register the task and bug status update MCP tools on the given server.
+ *
+ * @param server The MCP Server instance.
+ * @param client Authenticated ZentaoClient used to update data.
+ */
+export function registerStatusTools(server, client) {
+    // ─── Task Status Update Tool ───────────────────────────────────────────────
+    server.registerTool("zentao_update_task_status", {
+        description: "Update the status of a task and optionally add a comment/remark",
+        inputSchema: {
+            taskId: z.union([z.string(), z.number()]).describe("Task ID"),
+            action: z.enum(["start", "finish", "close", "pause", "cancel", "restart"]).describe("Status transition action"),
+            comment: z.string().optional().describe("Optional comment/remark to attach to this action"),
+            consumed: z.number().optional().describe("Optional hours consumed (used for 'start' or 'finish')"),
+            finishedDate: z.string().optional().describe("Optional actual finish date YYYY-MM-DD (used for 'finish', defaults to today)"),
+            realStarted: z.string().optional().describe("Optional actual start date YYYY-MM-DD (used for 'start' or 'finish')"),
+            assignedTo: z.string().optional().describe("Optional user account to assign to next (used for 'finish' or 'restart')"),
+            left: z.number().optional().describe("Optional left hours (used for 'restart')"),
+        },
+    }, async ({ taskId, action, comment, consumed, finishedDate, realStarted, assignedTo, left }) => {
+        const payload = {};
+        if (comment !== undefined)
+            payload.comment = comment;
+        if (action === "finish") {
+            // Fetch task details to get realStarted / estStarted if not provided (Zentao requires them)
+            const task = await client.getTaskDetails(taskId);
+            payload.realStarted = realStarted || task.realStarted || task.estStarted || new Date().toISOString().split("T")[0];
+            payload.finishedDate = finishedDate || new Date().toISOString().split("T")[0];
+            payload.consumed = consumed !== undefined ? consumed : (task.consumed || 0);
+            if (assignedTo)
+                payload.assignedTo = assignedTo;
+        }
+        else if (action === "start") {
+            payload.realStarted = realStarted || new Date().toISOString().split("T")[0];
+            if (consumed !== undefined)
+                payload.consumed = consumed;
+        }
+        else if (action === "restart") {
+            if (assignedTo)
+                payload.assignedTo = assignedTo;
+            if (left !== undefined)
+                payload.left = left;
+        }
+        const updatedTask = await client.updateTaskStatus(taskId, action, payload);
+        const downloadedImages = [];
+        const markdown = await taskToMarkdown(updatedTask, client, downloadedImages);
+        const output = `### Successfully updated task status to '${updatedTask.status || "updated"}'!\n\n${markdown}`;
+        return buildMcpResponse(output, downloadedImages);
+    });
+    // ─── Bug Status Update Tool ────────────────────────────────────────────────
+    server.registerTool("zentao_update_bug_status", {
+        description: "Update the status of a bug and optionally add a comment/remark",
+        inputSchema: {
+            bugId: z.union([z.string(), z.number()]).describe("Bug ID"),
+            action: z.enum(["resolve", "close", "activate"]).describe("Status transition action"),
+            comment: z.string().optional().describe("Optional comment/remark to attach to this action"),
+            resolution: z.enum(["fixed", "bydesign", "postponed", "external", "notrepro", "willnotfix"]).optional().describe("Resolution type (required for 'resolve', defaults to 'fixed')"),
+            resolvedBuild: z.string().optional().describe("Build ID/name in which the bug was resolved (used for 'resolve', defaults to 'trunk')"),
+            resolvedDate: z.string().optional().describe("Optional date of resolution YYYY-MM-DD (used for 'resolve', defaults to today)"),
+            assignedTo: z.string().optional().describe("Optional user account to assign to next (used for 'resolve' or 'activate')"),
+            openedBuild: z.string().optional().describe("Optional build ID/name where bug was found (used for 'activate')"),
+        },
+    }, async ({ bugId, action, comment, resolution, resolvedBuild, resolvedDate, assignedTo, openedBuild }) => {
+        const payload = {};
+        if (comment !== undefined)
+            payload.comment = comment;
+        if (action === "resolve") {
+            payload.resolution = resolution || "fixed";
+            payload.resolvedBuild = resolvedBuild || "trunk";
+            payload.resolvedDate = resolvedDate || new Date().toISOString().split("T")[0];
+            if (assignedTo)
+                payload.assignedTo = assignedTo;
+        }
+        else if (action === "activate") {
+            if (assignedTo)
+                payload.assignedTo = assignedTo;
+            if (openedBuild)
+                payload.openedBuild = openedBuild;
+        }
+        const updatedBug = await client.updateBugStatus(bugId, action, payload);
+        const downloadedImages = [];
+        const markdown = await bugToMarkdown(updatedBug, client, downloadedImages);
+        const output = `### Successfully updated bug status to '${updatedBug.status || "updated"}'!\n\n${markdown}`;
+        return buildMcpResponse(output, downloadedImages);
+    });
+}

package/build/tools.js

@@ -16,6 +16,8 @@ import { bugToMarkdown as _bugToMarkdown, } from "./formatters/bugFormatter.js";
 import { registerTaskTool } from "./tools/taskTool.js";
 import { registerBugTool } from "./tools/bugTool.js";
 import { registerDownloadTool } from "./tools/downloadTool.js";
+import { registerCommentTool } from "./tools/commentTool.js";
+import { registerStatusTools } from "./tools/statusTool.js";
 // ─── Shared singleton ────────────────────────────────────────────────────────
 const client = new ZentaoClient();
 // ─── Backward-compatible re-exports ──────────────────────────────────────────
@@ -37,6 +39,9 @@ export function bugToMarkdown(rawBug, downloadedImages) {
  * - `zentao_get_task_details`     — Fetch full details of a task by ID.
  * - `zentao_get_bug_details`      — Fetch full details of a bug by ID.
  * - `zentao_download_attachment`  — Download an attachment and save locally.
+ * - `zentao_get_comments`         — Fetch history and comments timeline for task/bug.
+ * - `zentao_update_task_status`   — Update a task's status with comments.
+ * - `zentao_update_bug_status`    — Update a bug's status with comments.
  *
  * @param server The MCP Server instance where the tools will be registered.
  */
@@ -44,4 +49,6 @@ export function registerTools(server) {
     registerTaskTool(server, client);
     registerBugTool(server, client);
     registerDownloadTool(server, client);
+    registerCommentTool(server, client);
+    registerStatusTools(server, client);
 }

package/build/zentaoClient.js

@@ -113,25 +113,175 @@ export class ZentaoClient {
             throw new Error('Login failed: Token not found in response');
         }
     }
+    /**
+     * Helper to generate standard action descriptions when they are not present in classic API.
+     */
+    generateActionDesc(act, userMap) {
+        const actorName = userMap[act.actor] || act.actor || 'User';
+        let extraName = act.extra || '';
+        if (userMap[extraName]) {
+            extraName = userMap[extraName];
+        }
+        else {
+            const resMap = {
+                'fixed': '已解决',
+                'design': '设计如此',
+                'duplicate': '重复Bug',
+                'external': '外部原因',
+                'notrepro': '无法重现',
+                'postponed': '延期处理',
+                'willnotfix': '不予解决',
+                'tostory': '转为需求',
+            };
+            if (resMap[extraName]) {
+                extraName = resMap[extraName];
+            }
+        }
+        switch (act.action) {
+            case 'opened':
+                return `由 <strong>${actorName}</strong> 创建。`;
+            case 'assigned':
+                return `由 <strong>${actorName}</strong> 指派给 <strong>${extraName}</strong>。`;
+            case 'started':
+                if (act.extra === 'autobychild') {
+                    return `由 <strong>${actorName}</strong> 启动子任务，该任务自动启动。`;
+                }
+                return `由 <strong>${actorName}</strong> 启动。`;
+            case 'finished':
+                return `由 <strong>${actorName}</strong> 完成。`;
+            case 'resolved':
+                return `由 <strong>${actorName}</strong> 解决，方案为 <strong>${extraName}</strong>。`;
+            case 'closed':
+                return `由 <strong>${actorName}</strong> 关闭。`;
+            case 'edited':
+                return `由 <strong>${actorName}</strong> 编辑。`;
+            case 'bugconfirmed':
+            case 'confirmed':
+                return `由 <strong>${actorName}</strong> 确认Bug。`;
+            case 'activated':
+                return `由 <strong>${actorName}</strong> 激活。`;
+            case 'commented':
+                return `由 <strong>${actorName}</strong> 备注。`;
+            case 'createchildren':
+                return `由 <strong>${actorName}</strong> 创建子任务 ${act.extra || ''}。`;
+            default:
+                if (act.action && act.action.startsWith('subtask')) {
+                    return `由 <strong>${actorName}</strong> ${act.action}。`;
+                }
+                return `由 <strong>${actorName}</strong> 执行了 <strong>${act.action || '未知'}</strong> 操作。`;
+        }
+    }
+    /**
+     * Fetches classic JSON API fallback data when REST API returns empty/errors.
+     */
+    async getFallbackClassicData(type, id) {
+        const webBaseUrl = this.baseUrl.split('/api.php/v1')[0];
+        const url = `${webBaseUrl}/${type}-view-${id}.json`;
+        const res = await this.client.get(url, {
+            baseURL: '', // override baseURL
+        });
+        const responseData = typeof res.data === 'string' ? JSON.parse(res.data) : res.data;
+        if (responseData && responseData.status === 'success') {
+            const detailData = typeof responseData.data === 'string' ? JSON.parse(responseData.data) : responseData.data;
+            if (detailData) {
+                const entity = detailData[type];
+                if (entity) {
+                    const userMap = detailData.users || {};
+                    // Normalize user fields
+                    const userFields = ['openedBy', 'assignedTo', 'resolvedBy', 'closedBy', 'finishedBy', 'canceledBy', 'lastEditedBy'];
+                    for (const field of userFields) {
+                        const val = entity[field];
+                        if (val && typeof val === 'string') {
+                            entity[field] = {
+                                account: val,
+                                realname: userMap[val] || val
+                            };
+                        }
+                    }
+                    if (entity.assignedTo?.account === 'closed') {
+                        entity.assignedTo = null;
+                    }
+                    // Normalize actions list to sorted array
+                    let actionsArray = [];
+                    if (detailData.actions) {
+                        if (Array.isArray(detailData.actions)) {
+                            actionsArray = detailData.actions;
+                        }
+                        else if (typeof detailData.actions === 'object') {
+                            actionsArray = Object.values(detailData.actions);
+                            actionsArray.sort((a, b) => (Number(a.id) || 0) - (Number(b.id) || 0));
+                        }
+                    }
+                    // Generate descriptions if missing
+                    for (const act of actionsArray) {
+                        if (!act.desc) {
+                            act.desc = `${act.date || ''}, ` + this.generateActionDesc(act, userMap);
+                        }
+                    }
+                    entity.actions = actionsArray;
+                    return entity;
+                }
+            }
+        }
+        throw new Error(`Failed to fetch ${type} details from classic fallback API for ID ${id}`);
+    }
     /**
      * Retrieves details of a specific task.
      * Checks the cache first, otherwise fetches from API.
+     * Falls back to classic JSON API if REST API returns empty/invalid response.
      *
      * @param taskId The ID of the task.
      * @returns Resolves with the task details.
      */
     async getTaskDetails(taskId) {
-        return this.get(`/tasks/${taskId}`);
+        try {
+            const task = await this.get(`/tasks/${taskId}`);
+            if (!task || task === "") {
+                const fallbackTask = await this.getFallbackClassicData('task', taskId);
+                this.getCache.set(`/tasks/${taskId}`, { data: fallbackTask, timestamp: Date.now() });
+                return fallbackTask;
+            }
+            return task;
+        }
+        catch (error) {
+            try {
+                const fallbackTask = await this.getFallbackClassicData('task', taskId);
+                this.getCache.set(`/tasks/${taskId}`, { data: fallbackTask, timestamp: Date.now() });
+                return fallbackTask;
+            }
+            catch (fallbackError) {
+                throw error; // throw original error if fallback also fails
+            }
+        }
     }
     /**
      * Retrieves details of a specific bug.
      * Checks the cache first, otherwise fetches from API.
+     * Falls back to classic JSON API if REST API returns empty/invalid response.
      *
      * @param bugId The ID of the bug.
      * @returns Resolves with the bug details.
      */
     async getBugDetails(bugId) {
-        return this.get(`/bugs/${bugId}`);
+        try {
+            const bug = await this.get(`/bugs/${bugId}`);
+            if (!bug || bug === "") {
+                const fallbackBug = await this.getFallbackClassicData('bug', bugId);
+                this.getCache.set(`/bugs/${bugId}`, { data: fallbackBug, timestamp: Date.now() });
+                return fallbackBug;
+            }
+            return bug;
+        }
+        catch (error) {
+            try {
+                const fallbackBug = await this.getFallbackClassicData('bug', bugId);
+                this.getCache.set(`/bugs/${bugId}`, { data: fallbackBug, timestamp: Date.now() });
+                return fallbackBug;
+            }
+            catch (fallbackError) {
+                throw error; // throw original error if fallback also fails
+            }
+        }
     }
     /**
      * Downloads a file from Zentao API and pipes it to a local file path.
@@ -191,4 +341,37 @@ export class ZentaoClient {
             });
         });
     }
+    /**
+     * Helper method to perform POST requests.
+     * Clears the cache to ensure subsequent GET requests fetch the updated state.
+     *
+     * @param url The API endpoint path.
+     * @param data The payload data.
+     * @returns The response data.
+     */
+    async post(url, data) {
+        this.clearCache();
+        const res = await this.client.post(url, data);
+        return res.data;
+    }
+    /**
+     * Updates task status by calling the action endpoint.
+     *
+     * @param taskId The ID of the task.
+     * @param action The status transition action (e.g. 'start', 'finish', 'close', 'pause', 'cancel').
+     * @param payload The request body payload.
+     */
+    async updateTaskStatus(taskId, action, payload) {
+        return this.post(`/tasks/${taskId}/${action}`, payload);
+    }
+    /**
+     * Updates bug status by calling the action endpoint.
+     *
+     * @param bugId The ID of the bug.
+     * @param action The status transition action (e.g. 'resolve', 'close', 'activate').
+     * @param payload The request body payload.
+     */
+    async updateBugStatus(bugId, action, payload) {
+        return this.post(`/bugs/${bugId}/${action}`, payload);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dyno181cm.nexsoft/zentao_mcp",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Zentao MCP Server",
   "repository": {
     "type": "git",