@dyno181cm.nexsoft/zentao_mcp 1.5.0 → 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/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/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.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/zentaoClient.js

@@ -52,6 +52,12 @@ export class ZentaoClient {
         }
         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.
@@ -304,6 +310,14 @@ export class ZentaoClient {
         });
     }
     // ─── 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.

package/package.json

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