@dyno181cm.nexsoft/zentao_mcp 1.5.0 → 1.7.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-13%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.
@@ -17,20 +18,22 @@ Fetch task details, bug reports, and attachments — all directly inside your AI
 
 | 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_details` | Fetch full details of a task or bug by ID |
 | `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 |
+| `zentao_get_assigned_to_me` | Get tasks and bugs currently assigned to you (configured via `ZENTAO_ACCOUNT`) |
 
 
 **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`
 
 ---
 
@@ -100,35 +103,30 @@ Add to your MCP client config (e.g. `claude_desktop_config.json`):
 
 ## 🛠️ Available Tools
 
-### `zentao_get_task_details`
-Get full details of a ZenTao task.
+### `zentao_get_details`
+Get full details of a ZenTao task or bug, including repro steps (for bugs), inline images, attachments, history, and comments.
 
 | 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 |
+| `type` | `"task" \| "bug"` | ✅ | Type of the object |
+| `id` | `string \| number` | ✅ | Task or Bug ID |
 
-### `zentao_download_attachment`
-Download a ZenTao file attachment to local disk.
+### `zentao_get_comments`
+Get only the history and comments timeline of a task or bug.
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `fileId` | `string \| number` | ✅ | File ID to download |
-| `extension` | `string` | ❌ | File extension hint (e.g. `mp4`, `png`) |
+| `type` | `"task" \| "bug"` | ✅ | Type of the object |
+| `id` | `string \| number` | ✅ | Task or Bug ID |
 
-### `zentao_get_comments`
-Get only the history and comments timeline of a task or bug.
+### `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.
@@ -158,6 +156,9 @@ Update a bug's status with optional comments and resolutions.
 | `assignedTo` | `string` | ❌ | Optional user account to assign to next |
 | `openedBuild` | `string` | ❌ | Optional build ID where bug was found (for `activate`) |
 
+### `zentao_get_assigned_to_me`
+Get tasks and bugs currently assigned to the configured user account. Takes no arguments.
+
 ---
 
 ## 🧑‍💻 Development
@@ -174,24 +175,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)
+│   ├── bugFormatter.ts       # bugToMarkdown (includes comments)
+│   └── myWorkFormatter.ts    # myWorkToMarkdown (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
+    ├── detailTool.ts         # zentao_get_details
+    ├── commentTool.ts        # zentao_get_comments · zentao_add_comment
+    ├── statusTool.ts         # zentao_update_task_status · zentao_update_bug_status
+    └── myWorkTool.ts         # zentao_get_assigned_to_me
+```
+
+### Running tests
+
+```bash
+npm test           # Unit tests — 13 tests across ZentaoClient
+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/detailTool.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { taskToMarkdown } from "../formatters/taskFormatter.js";
+import { bugToMarkdown } from "../formatters/bugFormatter.js";
+import { buildMcpResponse } from "../utils/mcpResponse.js";
+/**
+ * Register the `zentao_get_details` MCP tool on the given server.
+ *
+ * @param server The MCP Server instance.
+ * @param client Authenticated ZentaoClient used to fetch and process data.
+ */
+export function registerDetailTool(server, client) {
+    server.registerTool("zentao_get_details", {
+        description: "Get detailed information 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;
+        let markdown;
+        const downloadedImages = [];
+        if (type === "task") {
+            data = await client.getTaskDetails(id);
+            markdown = await taskToMarkdown(data, client, downloadedImages);
+        }
+        else {
+            data = await client.getBugDetails(id);
+            markdown = await bugToMarkdown(data, client, downloadedImages);
+        }
+        return await buildMcpResponse(markdown, downloadedImages);
+    });
+}

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

@@ -13,11 +13,10 @@
 import { ZentaoClient } from "./zentaoClient.js";
 import { taskToMarkdown as _taskToMarkdown, } from "./formatters/taskFormatter.js";
 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 { registerDetailTool } from "./tools/detailTool.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 ──────────────────────────────────────────
@@ -36,9 +35,7 @@ export function bugToMarkdown(rawBug, downloadedImages) {
  * Registers all Zentao MCP tools on the provided server instance.
  *
  * Available tools:
- * - `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_details`          — Fetch full details of a task or a bug by ID.
  * - `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.
@@ -46,9 +43,8 @@ export function bugToMarkdown(rawBug, downloadedImages) {
  * @param server The MCP Server instance where the tools will be registered.
  */
 export function registerTools(server) {
-    registerTaskTool(server, client);
-    registerBugTool(server, client);
-    registerDownloadTool(server, client);
+    registerDetailTool(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.7.0",
   "description": "Zentao MCP Server",
   "repository": {
     "type": "git",

package/build/tools/bugTool.js

@@ -1,22 +0,0 @@
-import { z } from "zod";
-import { bugToMarkdown } from "../formatters/bugFormatter.js";
-import { buildMcpResponse } from "../utils/mcpResponse.js";
-/**
- * Register the `zentao_get_bug_details` MCP tool on the given server.
- *
- * @param server The MCP Server instance.
- * @param client Authenticated ZentaoClient used to fetch and process data.
- */
-export function registerBugTool(server, client) {
-    server.registerTool("zentao_get_bug_details", {
-        description: "Get detailed information of a bug",
-        inputSchema: {
-            bugId: z.union([z.string(), z.number()]).describe("Bug ID"),
-        },
-    }, async ({ bugId }) => {
-        const data = await client.getBugDetails(bugId);
-        const downloadedImages = [];
-        const markdown = await bugToMarkdown(data, client, downloadedImages);
-        return await buildMcpResponse(markdown, downloadedImages);
-    });
-}

package/build/tools/downloadTool.js

@@ -1,56 +0,0 @@
-import { z } from "zod";
-import * as os from "os";
-import * as path from "path";
-import fs from "fs";
-import { mcpText } from "../utils/mcpResponse.js";
-/** Tracks in-flight downloads to deduplicate concurrent requests for the same file. */
-const activeDownloads = new Map();
-/**
- * Download a ZenTao attachment to a local path.
- * Deduplicates concurrent requests for the same target file.
- */
-async function downloadAttachment(client, fileId, targetPath) {
-    if (fs.existsSync(targetPath) && !activeDownloads.has(targetPath)) {
-        return `File already exists locally at: ${targetPath}`;
-    }
-    if (activeDownloads.has(targetPath)) {
-        await activeDownloads.get(targetPath);
-        return `File downloaded successfully to: ${targetPath}`;
-    }
-    const downloadPromise = client.downloadFile(fileId, targetPath);
-    activeDownloads.set(targetPath, downloadPromise);
-    try {
-        const savedPath = await downloadPromise;
-        return `File downloaded successfully to: ${savedPath}`;
-    }
-    finally {
-        activeDownloads.delete(targetPath);
-    }
-}
-/**
- * Register the `zentao_download_attachment` MCP tool on the given server.
- *
- * @param server The MCP Server instance.
- * @param client Authenticated ZentaoClient used for downloading files.
- */
-export function registerDownloadTool(server, client) {
-    server.registerTool("zentao_download_attachment", {
-        description: "Download a file attachment from ZenTao and save it locally",
-        inputSchema: {
-            fileId: z.union([z.string(), z.number()]).describe("File ID to download"),
-            extension: z.string().optional().describe("Optional file extension (e.g., mp4, png)"),
-        },
-    }, async ({ fileId, extension }) => {
-        const ext = extension
-            ? extension.startsWith('.') ? extension : `.${extension}`
-            : '';
-        const targetPath = path.join(os.tmpdir(), `zentao_file_${fileId}${ext}`);
-        try {
-            const message = await downloadAttachment(client, fileId, targetPath);
-            return mcpText(message);
-        }
-        catch (error) {
-            return mcpText(`Failed to download file: ${error.message}`);
-        }
-    });
-}

package/build/tools/taskTool.js

@@ -1,22 +0,0 @@
-import { z } from "zod";
-import { taskToMarkdown } from "../formatters/taskFormatter.js";
-import { buildMcpResponse } from "../utils/mcpResponse.js";
-/**
- * Register the `zentao_get_task_details` MCP tool on the given server.
- *
- * @param server The MCP Server instance.
- * @param client Authenticated ZentaoClient used to fetch and process data.
- */
-export function registerTaskTool(server, client) {
-    server.registerTool("zentao_get_task_details", {
-        description: "Get detailed information of a task",
-        inputSchema: {
-            taskId: z.union([z.string(), z.number()]).describe("Task ID"),
-        },
-    }, async ({ taskId }) => {
-        const data = await client.getTaskDetails(taskId);
-        const downloadedImages = [];
-        const markdown = await taskToMarkdown(data, client, downloadedImages);
-        return await buildMcpResponse(markdown, downloadedImages);
-    });
-}