@dyno181cm.nexsoft/zentao_mcp 1.2.17 → 1.4.0

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/attachmentRenderer.js

@@ -0,0 +1,45 @@
+import * as os from "os";
+import * as path from "path";
+import fs from "fs";
+import { toFileUrl, getMimeType, formatSize } from "../utils/fileUtils.js";
+/**
+ * Download all attachments in `files` to the local tmp directory and
+ * render them as a Markdown `## Files` section.
+ *
+ * @param files            Array of normalised file descriptors.
+ * @param client           Authenticated ZentaoClient used for downloads.
+ * @param downloadedImages Optional collector – successfully downloaded image
+ *                         paths are pushed here for later MCP embedding.
+ * @returns A Markdown string starting with `\n## Files\n`, or `''` when
+ *          there are no files.
+ */
+export async function renderAttachments(files, client, downloadedImages) {
+    if (!files || files.length === 0)
+        return '';
+    const enriched = await Promise.all(files.map(async (f) => {
+        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);
+            // Fix #5: only push each path once to avoid duplicates in the MCP response.
+            if (localPath && downloadedImages && getMimeType(targetPath) && !downloadedImages.includes(localPath)) {
+                downloadedImages.push(localPath);
+            }
+        }
+        catch {
+            /* keep null — shown as download-failed below */
+        }
+        return { title: f.title, size: f.size, localPath, ext };
+    }));
+    const lines = enriched.map((f) => {
+        if (!f.localPath) {
+            return `- ${f.title} — *(download failed, Size: ${formatSize(f.size)})*`;
+        }
+        const fileUrl = toFileUrl(f.localPath);
+        return `- [${f.title}](${fileUrl}) *(Size: ${formatSize(f.size)})*`;
+    });
+    return `\n## Files\n${lines.join('\n')}\n`;
+}

package/build/formatters/bugFormatter.js

@@ -0,0 +1,52 @@
+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.
+ *
+ * @param rawBug           The raw bug object returned by the Zentao API.
+ * @param client           Authenticated ZentaoClient used for image/attachment downloads.
+ * @param downloadedImages Optional collector for locally saved image paths
+ *                         (used by the MCP response builder to embed images).
+ */
+export async function bugToMarkdown(rawBug, client, downloadedImages) {
+    if (!rawBug)
+        return "Bug not found.";
+    // ── Compact metadata row ──
+    const meta = [
+        `**Status:** ${rawBug.status || 'N/A'}`,
+        `**Severity:** ${rawBug.severity || 'N/A'}`,
+        `**Priority:** ${rawBug.pri || 'N/A'}`,
+        `**Type:** ${rawBug.type || 'N/A'}`,
+    ];
+    if (rawBug.openedBy)
+        meta.push(`**Opened by:** ${formatUser(rawBug.openedBy)}`);
+    if (rawBug.assignedTo)
+        meta.push(`**Assigned to:** ${formatUser(rawBug.assignedTo)}`);
+    if (rawBug.resolvedBy) {
+        const resolution = rawBug.resolution ? ` (${rawBug.resolution})` : '';
+        meta.push(`**Resolved by:** ${formatUser(rawBug.resolvedBy)}${resolution}`);
+    }
+    if (rawBug.closedBy)
+        meta.push(`**Closed by:** ${formatUser(rawBug.closedBy)}`);
+    const localizedSteps = await localizeImages(rawBug.steps, client, downloadedImages);
+    const steps = htmlToMarkdown(localizedSteps);
+    const attachments = await renderAttachments(parseFiles(rawBug.files), client, downloadedImages);
+    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.*',
+    ];
+    if (attachments) {
+        parts.push(attachments);
+    }
+    if (historySection) {
+        parts.push(historySection);
+    }
+    return parts.join('\n');
+}

package/build/formatters/imageLocalizer.js

@@ -0,0 +1,84 @@
+import * as os from "os";
+import * as path from "path";
+import fs from "fs";
+import { toFileUrl, getMimeType } from "../utils/fileUtils.js";
+/**
+ * In-flight download deduplication map.
+ * Key: remote URL → Value: Promise resolving to local file path.
+ *
+ * Prevents concurrent coroutines from downloading the same image
+ * simultaneously when the same URL appears multiple times in the HTML.
+ */
+const inFlightImageDownloads = new Map();
+/**
+ * Find all <img src="..."> tags in an HTML string, download each image
+ * to the local tmp directory using the authenticated ZenTao client,
+ * and replace the entire <img> tag with an <a> link pointing to the
+ * local file:// URL.
+ *
+ * Guarantees:
+ * - Each unique URL is downloaded **at most once** even when called concurrently.
+ * - The `result` string is mutated **only after** all downloads finish,
+ *   eliminating the race condition from parallel `Promise.all` writes.
+ *
+ * @param html            The raw HTML string to process.
+ * @param client          Authenticated ZentaoClient used for downloads.
+ * @param downloadedImages Optional collector – successfully downloaded
+ *                         local paths are pushed here for later rendering.
+ */
+export async function localizeImages(html, client, downloadedImages) {
+    if (!html)
+        return html;
+    const imgTagRegex = /<img[^>]+src=["']([^"']+)["'][^>]*>/gi;
+    const matches = [...html.matchAll(imgTagRegex)];
+    if (matches.length === 0)
+        return html;
+    // Phase 1: Download all images in parallel (deduplicated per URL).
+    // Collect replacements as a Map<fullTag, linkTag> — applied in phase 2.
+    const replacements = new Map();
+    await Promise.all(matches.map(async (match) => {
+        const fullTag = match[0];
+        const remoteUrl = match[1];
+        const altMatch = fullTag.match(/alt=["']([^"']+)["']/i);
+        const filename = path.basename(remoteUrl.split("?")[0]);
+        const linkText = altMatch ? altMatch[1] : filename;
+        const localFilename = `zentao_img_${filename}`;
+        const localPath = path.join(os.tmpdir(), localFilename);
+        try {
+            // Deduplicate: reuse an in-flight promise for the same URL.
+            if (!inFlightImageDownloads.has(remoteUrl)) {
+                if (fs.existsSync(localPath)) {
+                    // Already cached on disk — resolve immediately.
+                    inFlightImageDownloads.set(remoteUrl, Promise.resolve(localPath));
+                }
+                else {
+                    const dlPromise = client
+                        .downloadImageToLocal(remoteUrl, localPath)
+                        .finally(() => inFlightImageDownloads.delete(remoteUrl));
+                    inFlightImageDownloads.set(remoteUrl, dlPromise);
+                }
+            }
+            await inFlightImageDownloads.get(remoteUrl);
+            // Only push each local path once to avoid duplicates.
+            if (downloadedImages &&
+                getMimeType(localPath) &&
+                !downloadedImages.includes(localPath)) {
+                downloadedImages.push(localPath);
+            }
+            const fileUrl = toFileUrl(localPath);
+            const linkTag = `<a href="${fileUrl}">${linkText}</a>`;
+            replacements.set(fullTag, linkTag);
+        }
+        catch {
+            // Keep original tag if download fails.
+        }
+    }));
+    // Phase 2: Apply all replacements sequentially on the original string.
+    // This is safe because we only write `result` after all awaits complete.
+    let result = html;
+    for (const [original, replacement] of replacements) {
+        // Use split/join for literal string replacement (no regex special chars risk).
+        result = result.split(original).join(replacement);
+    }
+    return result;
+}

package/build/formatters/taskFormatter.js

@@ -0,0 +1,55 @@
+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.
+ *
+ * @param rawTask          The raw task object returned by the Zentao API.
+ * @param client           Authenticated ZentaoClient used for image/attachment downloads.
+ * @param downloadedImages Optional collector for locally saved image paths
+ *                         (used by the MCP response builder to embed images).
+ */
+export async function taskToMarkdown(rawTask, client, downloadedImages) {
+    if (!rawTask)
+        return "Task not found.";
+    const est = rawTask.estimate ?? 0;
+    const cons = rawTask.consumed ?? 0;
+    const left = rawTask.left ?? 0;
+    const prog = rawTask.progress ?? 0;
+    // ── Compact metadata row ──
+    const meta = [
+        `**Status:** ${rawTask.status || 'N/A'}`,
+        `**Priority:** ${rawTask.pri || 'N/A'}`,
+        `**Estimate/Consumed/Left:** ${est}h / ${cons}h / ${left}h (${prog}%)`,
+    ];
+    if (rawTask.openedBy)
+        meta.push(`**Opened by:** ${formatUser(rawTask.openedBy)}`);
+    if (rawTask.assignedTo)
+        meta.push(`**Assigned to:** ${formatUser(rawTask.assignedTo)}`);
+    if (rawTask.finishedBy)
+        meta.push(`**Finished by:** ${formatUser(rawTask.finishedBy)}`);
+    if (rawTask.closedBy) {
+        const reason = rawTask.closedReason ? ` (${rawTask.closedReason})` : '';
+        meta.push(`**Closed by:** ${formatUser(rawTask.closedBy)}${reason}`);
+    }
+    const localizedDesc = await localizeImages(rawTask.desc, client, downloadedImages);
+    const desc = htmlToMarkdown(localizedDesc);
+    const attachments = await renderAttachments(parseFiles(rawTask.files), client, downloadedImages);
+    const historySection = await renderHistoryAndComments(rawTask.actions, client, downloadedImages);
+    const parts = [
+        `# Task #${rawTask.id}: ${rawTask.name}`,
+        '',
+        ...meta.map((m) => `- ${m}`),
+        '',
+        '## Description',
+        desc || '*No description provided.*',
+    ];
+    if (attachments) {
+        parts.push(attachments);
+    }
+    if (historySection) {
+        parts.push(historySection);
+    }
+    return parts.join('\n');
+}

package/build/tools/bugTool.js

@@ -0,0 +1,22 @@
+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 buildMcpResponse(markdown, downloadedImages);
+    });
+}

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);
+    });
+}