@dyno181cm.nexsoft/zentao_mcp 1.4.4 → 1.6.0

package/README.md

@@ -7,6 +7,7 @@
 [![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)
+[![Tests](https://img.shields.io/badge/tests-26%20passed-brightgreen?style=flat-square&logo=jest)](https://github.com/dyno-nexsoft/zentao_mcp/tree/master/tests)
 
 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.
@@ -21,6 +22,7 @@ Fetch task details, bug reports, and attachments — all directly inside your AI
 | `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_add_comment` | Add a comment/remark to 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 |
 
@@ -28,9 +30,11 @@ Fetch task details, bug reports, and attachments — all directly inside your AI
 **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
+- 🔁 Classic JSON API fallback — seamlessly retries via the web API when the REST endpoint returns empty or errors
 - 🖼️ 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
+- ⚡ Non-blocking async image I/O — base64 encoding uses `fs.promises` + `Promise.all`
 
 ---
 
@@ -130,6 +134,15 @@ Get only the history and comments timeline of a task or bug.
 | `type` | `"task" \| "bug"` | ✅ | Type of the object |
 | `id` | `string \| number` | ✅ | Task or Bug ID |
 
+### `zentao_add_comment`
+Add a comment/remark to a task or bug.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `type` | `"task" \| "bug"` | ✅ | Type of the object |
+| `id` | `string \| number` | ✅ | Task or Bug ID |
+| `comment` | `string` | ✅ | Comment content |
+
 ### `zentao_update_task_status`
 Update a task's status with optional comments, actual start/finish dates, and consumed hours.
 
@@ -174,24 +187,31 @@ npm run test:api   # Live API integration test
 ```
 src/
 ├── index.ts                  # MCP server entry point
-├── zentaoClient.ts           # Axios client: auth, cache, dedup, status updates
+├── zentaoClient.ts           # Axios client: auth, cache, dedup, fallback, stream helpers
 ├── tools.ts                  # Thin orchestrator + backward-compat exports
 ├── utils/
 │   ├── fileUtils.ts          # toFileUrl · getMimeType · formatSize
 │   ├── markdownUtils.ts      # htmlToMarkdown · parseFiles · formatUser
-│   └── mcpResponse.ts        # mcpText · buildMcpResponse
+│   └── mcpResponse.ts        # mcpText · buildMcpResponse (async)
 ├── formatters/
-│   ├── imageLocalizer.ts     # Inline <img> → local file:// link
+│   ├── imageLocalizer.ts     # Inline <img> → local file:// link (deduped, concurrent)
 │   ├── 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
+    ├── taskTool.ts           # zentao_get_task_details
+    ├── bugTool.ts            # zentao_get_bug_details
+    ├── downloadTool.ts       # zentao_download_attachment
+    ├── commentTool.ts        # zentao_get_comments · zentao_add_comment
+    └── statusTool.ts         # zentao_update_task_status · zentao_update_bug_status
+```
+
+### Running tests
+
+```bash
+npm test           # Unit tests — 26 tests across ZentaoClient + formatters
+npm run test:api   # Live API integration test (requires .env)
 ```
 
 ---

package/build/formatters/actionFormatter.js

@@ -1,9 +1,6 @@
 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";
+import { renderAttachments } from "./attachmentRenderer.js";
 /**
  * Normalizes and formats the history/comments/actions list into a clean Markdown block.
  *
@@ -47,36 +44,22 @@ export async function renderHistoryAndComments(actions, client, downloadedImages
                 commentStr = `\n  > ${commentMd.replace(/\n/g, '\n  > ')}`;
             }
         }
-        // 3. Format files if present in action
+        // 3. Format files if present in action — delegated to renderAttachments
         let filesStr = "";
         if (act.files) {
             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);
-                        }
+                // renderAttachments returns a full "## Files\n..." block; for inline action
+                // files we extract only the list items to keep the timeline compact.
+                const attachmentBlock = await renderAttachments(parsedFiles, client, downloadedImages);
+                if (attachmentBlock) {
+                    // Strip the section header and trim, then indent as a sub-item.
+                    const listContent = attachmentBlock
+                        .replace(/^\s*## Files\s*\n/, '')
+                        .trim();
+                    if (listContent) {
+                        filesStr = `\n  - *Attachments:* ${listContent.replace(/^- /gm, '').replace(/\n- /g, ', ')}`;
                     }
-                    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(", ")}`;
                 }
             }
         }

package/build/formatters/imageLocalizer.js

@@ -71,6 +71,8 @@ export async function localizeImages(html, client, downloadedImages) {
         }
         catch {
             // Keep original tag if download fails.
+            // Ensure in-flight entry is cleared even on unexpected errors.
+            inFlightImageDownloads.delete(remoteUrl);
         }
     }));
     // Phase 2: Apply all replacements sequentially on the original string.

package/build/formatters/myWorkFormatter.js

@@ -0,0 +1,55 @@
+/**
+ * Format a raw ZenTao "my work" response object into a human-readable Markdown document.
+ *
+ * @param myWork           The raw "my work" object containing profile, task, and bug lists.
+ * @param client           Authenticated ZentaoClient to get baseUrl for linking.
+ */
+export function myWorkToMarkdown(myWork, client) {
+    if (!myWork)
+        return "No work items found.";
+    const profile = myWork.profile || {};
+    const taskData = myWork.task || { total: 0, tasks: [] };
+    const bugData = myWork.bug || { total: 0, bugs: [] };
+    const webUrl = client.webUrl || "";
+    const header = [
+        `# Work Items Assigned to ${profile.realname || profile.account || "Me"}`,
+        `- **Account:** ${profile.account || "N/A"}`,
+        `- **Role:** ${profile.role?.name || "N/A"}`,
+        `- **Total Tasks:** ${taskData.total}`,
+        `- **Total Bugs:** ${bugData.total}`,
+        ""
+    ];
+    const sections = [...header];
+    // ── Tasks Section ──
+    sections.push("## Tasks Assigned to Me");
+    if (taskData.total === 0 || !taskData.tasks || taskData.tasks.length === 0) {
+        sections.push("*No tasks assigned to you.*", "");
+    }
+    else {
+        sections.push("| ID | Task Name | Pri | Status | Execution | Deadline | Progress |", "| :--- | :--- | :---: | :---: | :--- | :---: | :---: |");
+        for (const t of taskData.tasks) {
+            const taskLink = webUrl ? `[${t.id}](${webUrl}/task-view-${t.id}.html)` : `${t.id}`;
+            const execution = t.executionName || "N/A";
+            const prog = t.progress ?? 0;
+            const deadline = t.deadline || "N/A";
+            sections.push(`| ${taskLink} | ${t.name} | ${t.pri} | ${t.status} | ${execution} | ${deadline} | ${prog}% |`);
+        }
+        sections.push("");
+    }
+    // ── Bugs Section ──
+    sections.push("## Bugs Assigned to Me");
+    if (bugData.total === 0 || !bugData.bugs || bugData.bugs.length === 0) {
+        sections.push("*No bugs assigned to you.*", "");
+    }
+    else {
+        sections.push("| ID | Bug Title | Pri | Status | Product | Deadline |", "| :--- | :--- | :---: | :---: | :--- | :---: |");
+        for (const b of bugData.bugs) {
+            const bugLink = webUrl ? `[${b.id}](${webUrl}/bug-view-${b.id}.html)` : `${b.id}`;
+            const product = b.productName || "N/A";
+            const deadline = b.deadline || "N/A";
+            sections.push(`| ${bugLink} | ${b.title} | ${b.pri} | ${b.status} | ${product} | ${deadline} |`);
+        }
+        sections.push("");
+    }
+    return sections.join("\n");
+}

package/build/tools/bugTool.js

@@ -17,6 +17,6 @@ export function registerBugTool(server, client) {
         const data = await client.getBugDetails(bugId);
         const downloadedImages = [];
         const markdown = await bugToMarkdown(data, client, downloadedImages);
-        return buildMcpResponse(markdown, downloadedImages);
+        return await buildMcpResponse(markdown, downloadedImages);
     });
 }

package/build/tools/commentTool.js

@@ -29,7 +29,7 @@ export function registerCommentTool(server, client) {
             `# History & Comments for ${title}`,
             markdown.trim() || "*No history or comments found.*"
         ].join("\n\n");
-        return buildMcpResponse(output, downloadedImages);
+        return await buildMcpResponse(output, downloadedImages);
     });
     server.registerTool("zentao_add_comment", {
         description: "Add a comment/remark to a task or a bug",

package/build/tools/myWorkTool.js

@@ -0,0 +1,18 @@
+import { myWorkToMarkdown } from "../formatters/myWorkFormatter.js";
+import { mcpText } from "../utils/mcpResponse.js";
+/**
+ * Register the `zentao_get_assigned_to_me` MCP tool on the given server.
+ *
+ * @param server The MCP Server instance.
+ * @param client Authenticated ZentaoClient used to fetch and process data.
+ */
+export function registerMyWorkTool(server, client) {
+    server.registerTool("zentao_get_assigned_to_me", {
+        description: "Get tasks and bugs assigned to the current user (configured in environment variables)",
+        inputSchema: {},
+    }, async () => {
+        const data = await client.getMyWork();
+        const markdown = myWorkToMarkdown(data, client);
+        return mcpText(markdown);
+    });
+}

package/build/tools/statusTool.js

@@ -54,7 +54,7 @@ export function registerStatusTools(server, client) {
         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);
+        return await buildMcpResponse(output, downloadedImages);
     });
     // ─── Bug Status Update Tool ────────────────────────────────────────────────
     server.registerTool("zentao_update_bug_status", {
@@ -90,6 +90,6 @@ export function registerStatusTools(server, client) {
         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);
+        return await buildMcpResponse(output, downloadedImages);
     });
 }

package/build/tools/taskTool.js

@@ -17,6 +17,6 @@ export function registerTaskTool(server, client) {
         const data = await client.getTaskDetails(taskId);
         const downloadedImages = [];
         const markdown = await taskToMarkdown(data, client, downloadedImages);
-        return buildMcpResponse(markdown, downloadedImages);
+        return await buildMcpResponse(markdown, downloadedImages);
     });
 }

package/build/tools.js

@@ -18,6 +18,7 @@ import { registerBugTool } from "./tools/bugTool.js";
 import { registerDownloadTool } from "./tools/downloadTool.js";
 import { registerCommentTool } from "./tools/commentTool.js";
 import { registerStatusTools } from "./tools/statusTool.js";
+import { registerMyWorkTool } from "./tools/myWorkTool.js";
 // ─── Shared singleton ────────────────────────────────────────────────────────
 const client = new ZentaoClient();
 // ─── Backward-compatible re-exports ──────────────────────────────────────────
@@ -51,4 +52,5 @@ export function registerTools(server) {
     registerDownloadTool(server, client);
     registerCommentTool(server, client);
     registerStatusTools(server, client);
+    registerMyWorkTool(server, client);
 }

package/build/utils/markdownUtils.js

@@ -1,5 +1,9 @@
 import TurndownService from "turndown";
-const turndownService = new TurndownService();
+const turndownService = new TurndownService({
+    headingStyle: 'atx', // Use `#` headings instead of underline style
+    bulletListMarker: '-', // Consistent `-` for unordered lists
+    codeBlockStyle: 'fenced', // Use ``` for code blocks
+});
 /** Convert HTML to Markdown for better AI readability. */
 export function htmlToMarkdown(html) {
     if (!html)
@@ -19,7 +23,7 @@ export function parseFiles(files) {
         size: f.size,
     });
     if (Array.isArray(files)) {
-        return files.filter(Boolean).map(mapper); // Fix #8: filter null/undefined items
+        return files.filter(Boolean).map(mapper); // filter null/undefined items
     }
     if (typeof files === "object") {
         return Object.values(files).filter(Boolean).map(mapper);

package/build/utils/mcpResponse.js

@@ -10,28 +10,29 @@ export function mcpText(text) {
  *
  * Images are deduplicated and limited to the first 5 to stay within
  * JSON-RPC / token limits. Individual images larger than 2 MB are skipped.
+ *
+ * Uses async file I/O (`fs.promises`) to avoid blocking the event loop
+ * while reading image data.
  */
-export function buildMcpResponse(markdown, imagePaths) {
+export async function buildMcpResponse(markdown, imagePaths) {
     const content = [{ type: "text", text: markdown }];
     // Deduplicate and cap at 5 images
     const uniquePaths = Array.from(new Set(imagePaths)).slice(0, 5);
-    for (const imgPath of uniquePaths) {
+    await Promise.all(uniquePaths.map(async (imgPath) => {
         try {
-            if (!fs.existsSync(imgPath))
-                continue;
             const mimeType = getMimeType(imgPath);
             if (!mimeType)
-                continue;
-            const stats = fs.statSync(imgPath);
+                return;
+            const stats = await fs.promises.stat(imgPath);
             // Skip images > 2 MB to avoid hitting JSON-RPC / token limits
             if (stats.size > 2 * 1024 * 1024)
-                continue;
-            const data = fs.readFileSync(imgPath).toString("base64");
-            content.push({ type: "image", data, mimeType });
+                return;
+            const buffer = await fs.promises.readFile(imgPath);
+            content.push({ type: "image", data: buffer.toString("base64"), mimeType });
         }
         catch {
             // Ignore read errors for individual images
         }
-    }
+    }));
     return { content };
 }

package/build/zentaoClient.js

@@ -2,6 +2,29 @@ import axios from 'axios';
 import * as dotenv from 'dotenv';
 import * as fs from 'fs';
 dotenv.config();
+/**
+ * Resolution label map for bug actions.
+ * Defined at module level to avoid re-allocating the object on every call to
+ * `generateActionDesc`.
+ */
+const RESOLUTION_LABEL_MAP = {
+    fixed: '已解决',
+    design: '设计如此',
+    duplicate: '重复Bug',
+    external: '外部原因',
+    notrepro: '无法重现',
+    postponed: '延期处理',
+    willnotfix: '不予解决',
+    tostory: '转为需求',
+};
+/**
+ * User fields that may be stored as a plain account string in the classic API
+ * and need to be normalised to `{ account, realname }` objects.
+ */
+const USER_FIELDS = [
+    'openedBy', 'assignedTo', 'resolvedBy',
+    'closedBy', 'finishedBy', 'canceledBy', 'lastEditedBy',
+];
 /**
  * Client for communicating with the Zentao API.
  * Handles authentication, automatic token injection, session expiration retries,
@@ -15,8 +38,27 @@ export class ZentaoClient {
     baseUrl = process.env.ZENTAO_BASE_URL || '';
     getCache = new Map();
     cacheTtlMs = 2 * 60 * 1000; // 2 minutes TTL
-    /** Fix #3: In-flight request map prevents cache stampede under concurrent calls. */
+    /** In-flight request map prevents cache stampede under concurrent calls. */
     inFlightRequests = new Map();
+    // ─── Computed properties ─────────────────────────────────────────────────────
+    /**
+     * Returns the web base URL (without the API path suffix).
+     * Used by both `getFallbackClassicData` and `addComment` to avoid duplicating
+     * the same string-split logic in two places.
+     */
+    get webBaseUrl() {
+        if (this.baseUrl.includes('/api.php/v1')) {
+            return this.baseUrl.split('/api.php/v1')[0];
+        }
+        return this.baseUrl.split('/api/v1')[0];
+    }
+    /**
+     * Public getter exposing the web base URL.
+     */
+    get webUrl() {
+        return this.webBaseUrl;
+    }
+    // ─── Cache helpers ────────────────────────────────────────────────────────────
     /**
      * Clears the in-memory cache for GET requests. Helpful for testing.
      */
@@ -35,7 +77,7 @@ export class ZentaoClient {
         if (cached && now - cached.timestamp < this.cacheTtlMs) {
             return cached.data;
         }
-        // Fix #3: If a request for this URL is already in-flight, reuse its promise
+        // If a request for this URL is already in-flight, reuse its promise
         // instead of firing a duplicate HTTP request (prevents cache stampede).
         if (this.inFlightRequests.has(url)) {
             return this.inFlightRequests.get(url);
@@ -52,6 +94,7 @@ export class ZentaoClient {
         this.inFlightRequests.set(url, requestPromise);
         return requestPromise;
     }
+    // ─── Constructor & interceptors ───────────────────────────────────────────────
     /**
      * Initializes the Axios client with base configurations and registers interceptors
      * to automatically inject token headers and handle token expiration (401 errors).
@@ -92,6 +135,7 @@ export class ZentaoClient {
             return Promise.reject(error);
         });
     }
+    // ─── Authentication ───────────────────────────────────────────────────────────
     /**
      * Performs authentication request to Zentao API to obtain a token.
      * Updates the internal token state upon successful login.
@@ -113,6 +157,7 @@ export class ZentaoClient {
             throw new Error('Login failed: Token not found in response');
         }
     }
+    // ─── Private helpers ──────────────────────────────────────────────────────────
     /**
      * Helper to generate standard action descriptions when they are not present in classic API.
      */
@@ -122,20 +167,8 @@ export class ZentaoClient {
         if (userMap[extraName]) {
             extraName = userMap[extraName];
         }
-        else {
-            const resMap = {
-                'fixed': '已解决',
-                'design': '设计如此',
-                'duplicate': '重复Bug',
-                'external': '外部原因',
-                'notrepro': '无法重现',
-                'postponed': '延期处理',
-                'willnotfix': '不予解决',
-                'tostory': '转为需求',
-            };
-            if (resMap[extraName]) {
-                extraName = resMap[extraName];
-            }
+        else if (RESOLUTION_LABEL_MAP[extraName]) {
+            extraName = RESOLUTION_LABEL_MAP[extraName];
         }
         switch (act.action) {
             case 'opened':
@@ -175,10 +208,7 @@ export class ZentaoClient {
      * Fetches classic JSON API fallback data when REST API returns empty/errors.
      */
     async getFallbackClassicData(type, id) {
-        const webBaseUrl = this.baseUrl.includes('/api.php/v1')
-            ? this.baseUrl.split('/api.php/v1')[0]
-            : this.baseUrl.split('/api/v1')[0];
-        const url = `${webBaseUrl}/${type}-view-${id}.json`;
+        const url = `${this.webBaseUrl}/${type}-view-${id}.json`;
         const res = await this.client.get(url, {
             baseURL: '', // override baseURL
         });
@@ -190,8 +220,7 @@ export class ZentaoClient {
                 if (entity) {
                     const userMap = detailData.users || {};
                     // Normalize user fields
-                    const userFields = ['openedBy', 'assignedTo', 'resolvedBy', 'closedBy', 'finishedBy', 'canceledBy', 'lastEditedBy'];
-                    for (const field of userFields) {
+                    for (const field of USER_FIELDS) {
                         const val = entity[field];
                         if (val && typeof val === 'string') {
                             entity[field] = {
@@ -227,6 +256,68 @@ export class ZentaoClient {
         }
         throw new Error(`Failed to fetch ${type} details from classic fallback API for ID ${id}`);
     }
+    /**
+     * Generic helper that fetches entity details from the REST API and falls back
+     * to the classic JSON API when the REST response is empty or throws an error.
+     * Caches the fallback result under the REST API key so subsequent calls are fast.
+     *
+     * @param restUrl   The REST API path (e.g. `/tasks/1`).
+     * @param type      Entity type passed to `getFallbackClassicData`.
+     * @param id        Entity ID passed to `getFallbackClassicData`.
+     */
+    async getWithFallback(restUrl, type, id) {
+        const runFallback = async () => {
+            const data = await this.getFallbackClassicData(type, id);
+            // Cache the fallback result under the REST key so repeated calls are fast.
+            this.getCache.set(restUrl, { data, timestamp: Date.now() });
+            return data;
+        };
+        try {
+            const data = await this.get(restUrl);
+            if (!data || data === '') {
+                return runFallback();
+            }
+            return data;
+        }
+        catch {
+            return runFallback();
+        }
+    }
+    /**
+     * Shared stream-to-file helper used by `downloadFile` and `downloadImageToLocal`.
+     * Pipes a readable stream to a local file path, removing the partial file on error.
+     *
+     * @param readable    A Node.js Readable stream (axios response body).
+     * @param targetPath  The local file path to write to.
+     * @returns Resolves with `targetPath` on success.
+     */
+    pipeStreamToFile(readable, targetPath) {
+        const writer = fs.createWriteStream(targetPath);
+        return new Promise((resolve, reject) => {
+            readable.pipe(writer);
+            let writeError = null;
+            writer.on('error', (err) => {
+                writeError = err;
+                writer.close();
+                // Remove the partial/corrupt file so future calls don't mistake it for a valid download.
+                fs.unlink(targetPath, () => { });
+                reject(err);
+            });
+            writer.on('close', () => {
+                if (!writeError)
+                    resolve(targetPath);
+            });
+        });
+    }
+    // ─── Public API ───────────────────────────────────────────────────────────────
+    /**
+     * Retrieves tasks and bugs assigned to the current user (my work).
+     *
+     * @returns Resolves with the user's work items (tasks and bugs).
+     */
+    async getMyWork() {
+        return this.get('/user?fields=task,bug&type=assignedTo');
+    }
     /**
      * Retrieves details of a specific task.
      * Checks the cache first, otherwise fetches from API.
@@ -236,25 +327,7 @@ export class ZentaoClient {
      * @returns Resolves with the task details.
      */
     async getTaskDetails(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
-            }
-        }
+        return this.getWithFallback(`/tasks/${taskId}`, 'task', taskId);
     }
     /**
      * Retrieves details of a specific bug.
@@ -265,25 +338,7 @@ export class ZentaoClient {
      * @returns Resolves with the bug details.
      */
     async getBugDetails(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
-            }
-        }
+        return this.getWithFallback(`/bugs/${bugId}`, 'bug', bugId);
     }
     /**
      * Downloads a file from Zentao API and pipes it to a local file path.
@@ -293,25 +348,10 @@ export class ZentaoClient {
      * @returns A promise that resolves to the targetPath upon success, or rejects with an error.
      */
     async downloadFile(fileId, targetPath) {
-        const writer = fs.createWriteStream(targetPath);
         const res = await this.client.get(`/files/${fileId}`, {
             responseType: 'stream',
         });
-        return new Promise((resolve, reject) => {
-            res.data.pipe(writer);
-            let error = null;
-            writer.on('error', (err) => {
-                error = err;
-                writer.close();
-                // Fix #4: remove the partial/corrupt file so future calls don't mistake it for a valid download.
-                fs.unlink(targetPath, () => { });
-                reject(err);
-            });
-            writer.on('close', () => {
-                if (!error)
-                    resolve(targetPath);
-            });
-        });
+        return this.pipeStreamToFile(res.data, targetPath);
     }
     /**
      * Downloads an image from a full authenticated URL and saves it to a local path.
@@ -322,26 +362,11 @@ export class ZentaoClient {
      * @returns A promise that resolves to the targetPath upon success, or rejects with an error.
      */
     async downloadImageToLocal(imageUrl, targetPath) {
-        const writer = fs.createWriteStream(targetPath);
         const res = await this.client.get(imageUrl, {
             baseURL: '', // override baseURL so the full URL is used as-is
             responseType: 'stream',
         });
-        return new Promise((resolve, reject) => {
-            res.data.pipe(writer);
-            let error = null;
-            writer.on('error', (err) => {
-                error = err;
-                writer.close();
-                // Fix #4: remove the partial/corrupt file so future calls don't mistake it for a valid download.
-                fs.unlink(targetPath, () => { });
-                reject(err);
-            });
-            writer.on('close', () => {
-                if (!error)
-                    resolve(targetPath);
-            });
-        });
+        return this.pipeStreamToFile(res.data, targetPath);
     }
     /**
      * Helper method to perform POST requests.
@@ -387,10 +412,7 @@ export class ZentaoClient {
         if (!this.token) {
             await this.login();
         }
-        const webBaseUrl = this.baseUrl.includes('/api.php/v1')
-            ? this.baseUrl.split('/api.php/v1')[0]
-            : this.baseUrl.split('/api/v1')[0];
-        const url = `${webBaseUrl}/action-comment-${type}-${id}.json?zentaosid=${this.token}`;
+        const url = `${this.webBaseUrl}/action-comment-${type}-${id}.json?zentaosid=${this.token}`;
         // Clear the cache so subsequent fetches get the new comment
         this.clearCache();
         const params = new URLSearchParams();

package/package.json

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