@dyno181cm.nexsoft/zentao_mcp 1.2.17 → 1.3.0

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,44 @@
+import { htmlToMarkdown, parseFiles, formatUser } from "../utils/markdownUtils.js";
+import { localizeImages } from "./imageLocalizer.js";
+import { renderAttachments } from "./attachmentRenderer.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);
+    return [
+        `# Bug #${rawBug.id}: ${rawBug.title}`,
+        '',
+        ...meta.map((m) => `- ${m}`),
+        '',
+        '## Repro Steps',
+        steps || '*No steps provided.*',
+        attachments,
+    ].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,47 @@
+import { htmlToMarkdown, parseFiles, formatUser } from "../utils/markdownUtils.js";
+import { localizeImages } from "./imageLocalizer.js";
+import { renderAttachments } from "./attachmentRenderer.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);
+    return [
+        `# Task #${rawTask.id}: ${rawTask.name}`,
+        '',
+        ...meta.map((m) => `- ${m}`),
+        '',
+        '## Description',
+        desc || '*No description provided.*',
+        attachments,
+    ].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/downloadTool.js

@@ -0,0 +1,56 @@
+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

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

package/build/tools.js

@@ -1,284 +1,47 @@
-import { z } from "zod";
-import * as os from "os";
-import * as path from "path";
-import fs from "fs";
-import { ZentaoClient } from "./zentaoClient.js";
-import TurndownService from "turndown";
-// ─── Module-level singletons ────────────────────────────────────────────────
-const client = new ZentaoClient();
-const activeDownloads = new Map();
-const turndownService = new TurndownService();
-// ─── Internal helpers (Single Responsibility) ────────────────────────────────
-/** Convert HTML to Markdown for better AI readability. */
-function htmlToMarkdown(html) {
-    if (!html)
-        return '';
-    return turndownService.turndown(html);
-}
-/** Normalize the ZenTao `files` field (can be an array or object) into a flat array. */
-function parseFiles(files) {
-    if (!files)
-        return [];
-    const mapper = (f) => ({
-        id: f.id,
-        title: f.title || f.name,
-        extension: f.extension,
-        size: f.size,
-    });
-    if (Array.isArray(files))
-        return files.map(mapper);
-    if (typeof files === 'object')
-        return Object.values(files).map(mapper);
-    return [];
-}
-/** Format a ZenTao user field (object or string) into a human-readable string. */
-function formatUser(user) {
-    if (!user)
-        return '';
-    if (typeof user === 'object') {
-        const name = user.realname || user.account || '';
-        const account = user.account ? ` (${user.account})` : '';
-        return `${name}${account}`;
-    }
-    return String(user);
-}
-/** Convert a local absolute path to a valid file:// URL. */
-function toFileUrl(filePath) {
-    const normalized = filePath.replace(/\\/g, '/');
-    if (/^[a-zA-Z]:\//.test(normalized)) {
-        return `file:///${normalized}`;
-    }
-    if (normalized.startsWith('/')) {
-        return `file://${normalized}`;
-    }
-    return `file:///${normalized}`;
-}
-/**
- * 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.
- * This saves AI tokens (no huge Base64 data) and avoids local file load errors in UI.
- */
-async function localizeImages(html) {
-    if (!html)
-        return html;
-    const imgTagRegex = /<img[^>]+src=["']([^"']+)["'][^>]*>/gi;
-    const matches = [...html.matchAll(imgTagRegex)];
-    if (matches.length === 0)
-        return html;
-    let result = html;
-    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 {
-            if (!fs.existsSync(localPath)) {
-                await client.downloadImageToLocal(remoteUrl, localPath);
-            }
-            const fileUrl = toFileUrl(localPath);
-            // Replace img tag with a standard hyperlink (no inline rendering, saves tokens)
-            const linkTag = `<a href="${fileUrl}">${linkText}</a>`;
-            result = result.split(fullTag).join(linkTag);
-        }
-        catch {
-            // Keep original tag if download fails
-        }
-    }));
-    return result;
-}
-/** Format a file size in bytes to a human-readable string (B / KB / MB). */
-function formatSize(bytes) {
-    if (bytes === undefined || bytes === null || bytes === '')
-        return 'unknown size';
-    const numBytes = typeof bytes === 'string' ? parseInt(bytes, 10) : bytes;
-    if (isNaN(numBytes))
-        return 'unknown size';
-    if (numBytes < 1024)
-        return `${numBytes} B`;
-    if (numBytes < 1024 * 1024)
-        return `${(numBytes / 1024).toFixed(2)} KB`;
-    return `${(numBytes / (1024 * 1024)).toFixed(2)} MB`;
-}
-/** Build a standard MCP text content response. */
-function mcpText(text) {
-    return { content: [{ type: "text", text }] };
-}
-/** Download all attachments to local tmp dir and render them as a Markdown section. */
-async function renderAttachments(files) {
-    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);
-        }
-        catch { /* keep null, show 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`;
-}
-// ─── Public formatters ───────────────────────────────────────────────────────
 /**
- * Format a raw ZenTao task object into a human-readable Markdown document.
- */
-export async function taskToMarkdown(rawTask) {
-    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);
-    const desc = htmlToMarkdown(localizedDesc);
-    const attachments = await renderAttachments(parseFiles(rawTask.files));
-    const metaList = meta.map(m => `- ${m}`).join('\n');
-    return [
-        `# Task #${rawTask.id}: ${rawTask.name}`,
-        '',
-        metaList,
-        '',
-        '## Description',
-        desc || '*No description provided.*',
-        attachments,
-    ].join('\n');
-}
-/**
- * Format a raw ZenTao bug object into a human-readable Markdown document.
- */
-export async function bugToMarkdown(rawBug) {
-    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);
-    const steps = htmlToMarkdown(localizedSteps);
-    const attachments = await renderAttachments(parseFiles(rawBug.files));
-    return [
-        `# Bug #${rawBug.id}: ${rawBug.title}`,
-        '',
-        ...meta.map(m => `- ${m}`),
-        '',
-        '## Repro Steps',
-        steps || '*No steps provided.*',
-        attachments,
-    ].join('\n');
-}
-// ─── Download handler (extracted for Single Responsibility) ──────────────────
-/**
- * Download a ZenTao attachment to a local path.
- * Deduplicates concurrent requests for the same file.
+ * tools.ts — Public surface of the Zentao MCP tool layer.
+ *
+ * This file is intentionally thin. It:
+ *   1. Creates the shared ZentaoClient singleton.
+ *   2. Re-exports formatter functions (bound to the shared client) so
+ *      external callers keep the original 2-argument API without changes.
+ *   3. Delegates tool registration to focused per-tool modules.
+ *
+ * To add a new tool: create `src/tools/<name>Tool.ts` and call its
+ * register function here — no existing files need to be modified.
  */
-async function downloadAttachment(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);
-    }
-}
-// ─── Tool registration (Open/Closed: add tools without touching existing ones) ─
+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";
+// ─── Shared singleton ────────────────────────────────────────────────────────
+const client = new ZentaoClient();
+// ─── Backward-compatible re-exports ──────────────────────────────────────────
+// The formatter modules now accept `client` as an explicit parameter (DI).
+// These wrappers preserve the original 2-arg signature for any existing callers.
+/** @see formatters/taskFormatter.ts */
+export function taskToMarkdown(rawTask, downloadedImages) {
+    return _taskToMarkdown(rawTask, client, downloadedImages);
+}
+/** @see formatters/bugFormatter.ts */
+export function bugToMarkdown(rawBug, downloadedImages) {
+    return _bugToMarkdown(rawBug, client, downloadedImages);
+}
+// ─── Tool registration ────────────────────────────────────────────────────────
 /**
- * Registers Zentao-specific tools to the Model Context Protocol (MCP) server.
+ * Registers all Zentao MCP tools on the provided server instance.
  *
- * Available Tools:
- * - `zentao_get_task_details`: Fetch full details of a specific task by ID.
- * - `zentao_get_bug_details`: Fetch full details of a specific bug by ID.
- * - `zentao_download_attachment`: Download attachments and save locally.
+ * 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.
  *
  * @param server The MCP Server instance where the tools will be registered.
  */
 export function registerTools(server) {
-    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);
-        return mcpText(await taskToMarkdown(data));
-    });
-    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);
-        return mcpText(await bugToMarkdown(data));
-    });
-    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(fileId, targetPath);
-            return mcpText(message);
-        }
-        catch (error) {
-            return mcpText(`Failed to download file: ${error.message}`);
-        }
-    });
+    registerTaskTool(server, client);
+    registerBugTool(server, client);
+    registerDownloadTool(server, client);
 }

package/build/utils/fileUtils.js

@@ -0,0 +1,49 @@
+import * as path from "path";
+const KB = 1024;
+const MB = 1024 * KB;
+/**
+ * Convert a local absolute path to a valid file:// URL.
+ * Handles Windows drive-letter paths (e.g. C:/...) and Unix-style paths.
+ */
+export function toFileUrl(filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    if (/^[a-zA-Z]:\//.test(normalized)) {
+        return `file:///${normalized}`;
+    }
+    if (normalized.startsWith("/")) {
+        return `file://${normalized}`;
+    }
+    return `file:///${normalized}`;
+}
+/**
+ * Determine the MIME type of a file based on its extension.
+ * Returns `null` for unrecognised or non-image extensions.
+ */
+export function getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    switch (ext) {
+        case ".png": return "image/png";
+        case ".jpg":
+        case ".jpeg": return "image/jpeg";
+        case ".gif": return "image/gif";
+        case ".webp": return "image/webp";
+        case ".bmp": return "image/bmp";
+        case ".svg": return "image/svg+xml";
+        default: return null;
+    }
+}
+/**
+ * Format a file size (bytes) to a human-readable string (B / KB / MB).
+ */
+export function formatSize(bytes) {
+    if (bytes === undefined || bytes === null || bytes === "")
+        return "unknown size";
+    const numBytes = typeof bytes === "string" ? parseInt(bytes, 10) : bytes;
+    if (isNaN(numBytes))
+        return "unknown size";
+    if (numBytes < KB)
+        return `${numBytes} B`;
+    if (numBytes < MB)
+        return `${(numBytes / KB).toFixed(2)} KB`;
+    return `${(numBytes / MB).toFixed(2)} MB`;
+}

package/build/utils/markdownUtils.js

@@ -0,0 +1,39 @@
+import TurndownService from "turndown";
+const turndownService = new TurndownService();
+/** Convert HTML to Markdown for better AI readability. */
+export function htmlToMarkdown(html) {
+    if (!html)
+        return "";
+    return turndownService.turndown(html);
+}
+/** Normalize the ZenTao `files` field (array or keyed object) into a flat array.
+ *  Null/undefined items in the source are filtered out defensively.
+ */
+export function parseFiles(files) {
+    if (!files)
+        return [];
+    const mapper = (f) => ({
+        id: f.id,
+        title: f.title || f.name,
+        extension: f.extension,
+        size: f.size,
+    });
+    if (Array.isArray(files)) {
+        return files.filter(Boolean).map(mapper); // Fix #8: filter null/undefined items
+    }
+    if (typeof files === "object") {
+        return Object.values(files).filter(Boolean).map(mapper);
+    }
+    return [];
+}
+/** Format a ZenTao user field (object or string) into a human-readable string. */
+export function formatUser(user) {
+    if (!user)
+        return "";
+    if (typeof user === "object") {
+        const name = user.realname || user.account || "";
+        const account = user.account ? ` (${user.account})` : "";
+        return `${name}${account}`;
+    }
+    return String(user);
+}

package/build/utils/mcpResponse.js

@@ -0,0 +1,37 @@
+import fs from "fs";
+import { getMimeType } from "./fileUtils.js";
+/** Build a standard MCP text-only content response. */
+export function mcpText(text) {
+    return { content: [{ type: "text", text }] };
+}
+/**
+ * Build an MCP response containing a Markdown text block followed by
+ * inline base64 image blocks for each discovered local image path.
+ *
+ * Images are deduplicated and limited to the first 5 to stay within
+ * JSON-RPC / token limits. Individual images larger than 2 MB are skipped.
+ */
+export 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) {
+        try {
+            if (!fs.existsSync(imgPath))
+                continue;
+            const mimeType = getMimeType(imgPath);
+            if (!mimeType)
+                continue;
+            const stats = fs.statSync(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 });
+        }
+        catch {
+            // Ignore read errors for individual images
+        }
+    }
+    return { content };
+}

package/build/zentaoClient.js

@@ -15,6 +15,8 @@ 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. */
+    inFlightRequests = new Map();
     /**
      * Clears the in-memory cache for GET requests. Helpful for testing.
      */
@@ -30,12 +32,25 @@ export class ZentaoClient {
     async get(url) {
         const cached = this.getCache.get(url);
         const now = Date.now();
-        if (cached && (now - cached.timestamp < this.cacheTtlMs)) {
+        if (cached && now - cached.timestamp < this.cacheTtlMs) {
             return cached.data;
         }
-        const res = await this.client.get(url);
-        this.getCache.set(url, { data: res.data, timestamp: now });
-        return res.data;
+        // Fix #3: 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);
+        }
+        const requestPromise = this.client
+            .get(url)
+            .then((res) => {
+            this.getCache.set(url, { data: res.data, timestamp: Date.now() });
+            return res.data;
+        })
+            .finally(() => {
+            this.inFlightRequests.delete(url);
+        });
+        this.inFlightRequests.set(url, requestPromise);
+        return requestPromise;
     }
     /**
      * Initializes the Axios client with base configurations and registers interceptors
@@ -133,15 +148,16 @@ export class ZentaoClient {
         return new Promise((resolve, reject) => {
             res.data.pipe(writer);
             let error = null;
-            writer.on('error', err => {
+            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) {
+                if (!error)
                     resolve(targetPath);
-                }
             });
         });
     }
@@ -162,9 +178,11 @@ export class ZentaoClient {
         return new Promise((resolve, reject) => {
             res.data.pipe(writer);
             let error = null;
-            writer.on('error', err => {
+            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', () => {

package/package.json

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