@dyno181cm.nexsoft/zentao_mcp 1.2.8 → 1.2.10

package/build/tools.js

@@ -4,19 +4,18 @@ 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();
-/**
- * Registers Zentao-specific tools to the Model Context Protocol (MCP) server.
- *
- * 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 (e.g. bug reproduction videos/images) and save locally.
- *
- * @param server The MCP Server instance where the tools will be registered.
- */
+// ─── 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 [];
@@ -24,89 +23,58 @@ function parseFiles(files) {
         id: f.id,
         title: f.title || f.name,
         extension: f.extension,
-        size: f.size
+        size: f.size,
     });
-    if (Array.isArray(files)) {
+    if (Array.isArray(files))
         return files.map(mapper);
-    }
-    if (typeof files === 'object') {
+    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);
+}
 /**
- * Simple utility to convert basic HTML to Markdown for better readability by the AI.
+ * Find all <img src="..."> URLs in an HTML string, download each image
+ * to the local tmp directory using the authenticated ZenTao client,
+ * and replace the remote src with the local file path.
+ * Images already cached on disk are not re-downloaded.
  */
-function htmlToMarkdown(html) {
+async function localizeImages(html) {
     if (!html)
-        return '';
-    return turndownService.turndown(html);
-}
-export function cleanTask(task) {
-    if (!task)
-        return null;
-    return {
-        id: task.id,
-        name: task.name,
-        status: task.status,
-        pri: task.pri,
-        desc: htmlToMarkdown(task.desc),
-        estimate: task.estimate,
-        consumed: task.consumed,
-        left: task.left,
-        progress: task.progress,
-        openedBy: task.openedBy ? {
-            account: task.openedBy.account,
-            realname: task.openedBy.realname
-        } : undefined,
-        assignedTo: task.assignedTo ? {
-            account: task.assignedTo.account,
-            realname: task.assignedTo.realname
-        } : undefined,
-        finishedBy: task.finishedBy ? {
-            account: task.finishedBy.account,
-            realname: task.finishedBy.realname
-        } : undefined,
-        closedBy: task.closedBy ? {
-            account: task.closedBy.account,
-            realname: task.closedBy.realname
-        } : undefined,
-        closedReason: task.closedReason,
-        files: parseFiles(task.files)
-    };
-}
-export function cleanBug(bug) {
-    if (!bug)
-        return null;
-    return {
-        id: bug.id,
-        title: bug.title,
-        status: bug.status,
-        severity: bug.severity,
-        pri: bug.pri,
-        type: bug.type,
-        steps: htmlToMarkdown(bug.steps),
-        openedBy: bug.openedBy ? {
-            account: bug.openedBy.account,
-            realname: bug.openedBy.realname
-        } : undefined,
-        assignedTo: bug.assignedTo ? {
-            account: bug.assignedTo.account,
-            realname: bug.assignedTo.realname
-        } : undefined,
-        resolvedBy: bug.resolvedBy ? {
-            account: bug.resolvedBy.account,
-            realname: bug.resolvedBy.realname
-        } : undefined,
-        resolution: bug.resolution,
-        closedBy: bug.closedBy ? {
-            account: bug.closedBy.account,
-            realname: bug.closedBy.realname
-        } : undefined,
-        files: parseFiles(bug.files)
-    };
+        return html;
+    const imgRegex = /<img[^>]+src=["']([^"']+)["']/gi;
+    const matches = [...html.matchAll(imgRegex)];
+    if (matches.length === 0)
+        return html;
+    let result = html;
+    await Promise.all(matches.map(async (match) => {
+        const remoteUrl = match[1];
+        // Derive a stable local filename from the last path segment of the URL
+        const filename = `zentao_img_${path.basename(remoteUrl.split('?')[0])}`;
+        const localPath = path.join(os.tmpdir(), filename);
+        try {
+            if (!fs.existsSync(localPath)) {
+                await client.downloadImageToLocal(remoteUrl, localPath);
+            }
+            result = result.split(remoteUrl).join(localPath);
+        }
+        catch {
+            // If download fails, keep the original remote URL
+        }
+    }));
+    return result;
 }
-export function formatSize(bytes) {
+/** 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;
@@ -118,132 +86,191 @@ export function formatSize(bytes) {
         return `${(numBytes / 1024).toFixed(2)} KB`;
     return `${(numBytes / (1024 * 1024)).toFixed(2)} MB`;
 }
-export function taskToMarkdown(task) {
-    if (!task)
+/** 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 with AI hints. */
+async function renderAttachments(files) {
+    if (!files || files.length === 0)
+        return '';
+    const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'svg']);
+    const VIDEO_EXTS = new Set(['mp4', 'mov', 'avi', 'mkv', 'webm']);
+    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 };
+    }));
+    // Build section header hint based on media types present
+    const hasImage = enriched.some(f => f.localPath && IMAGE_EXTS.has(f.ext));
+    const hasVideo = enriched.some(f => f.localPath && VIDEO_EXTS.has(f.ext));
+    let headerHint = '';
+    if (hasImage && hasVideo)
+        headerHint = ' *(AI: Please view the images and videos below)*';
+    else if (hasImage)
+        headerHint = ' *(AI: Please view the images below)*';
+    else if (hasVideo)
+        headerHint = ' *(AI: Please view the videos below)*';
+    const lines = enriched.map((f) => {
+        if (!f.localPath)
+            return `- 📎 ${f.title} — *(download failed, Size: ${formatSize(f.size)})*`;
+        if (IMAGE_EXTS.has(f.ext))
+            return `- 📎 ![${f.title}](${f.localPath}) *(Size: ${formatSize(f.size)})*`;
+        return `- 📎 [${f.title}](${f.localPath}) *(Size: ${formatSize(f.size)})*`;
+    });
+    return `\n## Files 📎${headerHint}\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.";
-    let md = `# Task #${task.id}: ${task.name}\n\n`;
-    md += `- **Status**: ${task.status || 'N/A'}\n`;
-    md += `- **Priority**: ${task.pri || 'N/A'}\n`;
-    const est = task.estimate ?? 0;
-    const cons = task.consumed ?? 0;
-    const left = task.left ?? 0;
-    const prog = task.progress ?? 0;
-    md += `- **Estimate / Consumed / Left**: ${est}h / ${cons}h / ${left}h (${prog}%)\n`;
-    if (task.openedBy)
-        md += `- **Opened By**: ${task.openedBy.realname} (${task.openedBy.account})\n`;
-    if (task.assignedTo)
-        md += `- **Assigned To**: ${task.assignedTo.realname} (${task.assignedTo.account})\n`;
-    if (task.finishedBy)
-        md += `- **Finished By**: ${task.finishedBy.realname} (${task.finishedBy.account})\n`;
-    if (task.closedBy) {
-        md += `- **Closed By**: ${task.closedBy.realname} (${task.closedBy.account})`;
-        if (task.closedReason)
-            md += ` (Reason: ${task.closedReason})`;
-        md += `\n`;
-    }
-    md += `\n## Description\n${task.desc || '*No description provided.*'}\n`;
-    if (task.files && task.files.length > 0) {
-        md += `\n## Attachments\n`;
-        task.files.forEach((f) => {
-            md += `- 📎 **${f.title}** (ID: ${f.id}, Extension: ${f.extension}, Size: ${formatSize(f.size)})\n`;
-        });
+    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}`);
     }
-    return md;
+    const localizedDesc = await localizeImages(rawTask.desc);
+    const desc = htmlToMarkdown(localizedDesc);
+    const attachments = await renderAttachments(parseFiles(rawTask.files));
+    return [
+        `# Task #${rawTask.id}: ${rawTask.name}`,
+        '',
+        meta.join(' | '),
+        '',
+        '## Description',
+        desc || '*No description provided.*',
+        attachments,
+    ].join('\n');
 }
-export function bugToMarkdown(bug) {
-    if (!bug)
+/**
+ * Format a raw ZenTao bug object into a human-readable Markdown document.
+ */
+export async function bugToMarkdown(rawBug) {
+    if (!rawBug)
         return "Bug not found.";
-    let md = `# Bug #${bug.id}: ${bug.title}\n\n`;
-    md += `- **Status**: ${bug.status || 'N/A'}\n`;
-    md += `- **Severity**: ${bug.severity || 'N/A'}\n`;
-    md += `- **Priority**: ${bug.pri || 'N/A'}\n`;
-    md += `- **Type**: ${bug.type || 'N/A'}\n`;
-    if (bug.openedBy)
-        md += `- **Opened By**: ${bug.openedBy.realname} (${bug.openedBy.account})\n`;
-    if (bug.assignedTo)
-        md += `- **Assigned To**: ${bug.assignedTo.realname} (${bug.assignedTo.account})\n`;
-    if (bug.resolvedBy) {
-        md += `- **Resolved By**: ${bug.resolvedBy.realname} (${bug.resolvedBy.account})`;
-        if (bug.resolution)
-            md += ` (Resolution: ${bug.resolution})`;
-        md += `\n`;
+    // ── 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 (bug.closedBy)
-        md += `- **Closed By**: ${bug.closedBy.realname} (${bug.closedBy.account})\n`;
-    md += `\n## Steps to Reproduce\n${bug.steps || '*No steps provided.*'}\n`;
-    if (bug.files && bug.files.length > 0) {
-        md += `\n## Attachments\n`;
-        bug.files.forEach((f) => {
-            md += `- 📎 **${f.title}** (ID: ${f.id}, Extension: ${f.extension}, Size: ${formatSize(f.size)})\n`;
-        });
+    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.join(' | '),
+        '',
+        '## 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.
+ */
+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);
     }
-    return md;
 }
+// ─── Tool registration (Open/Closed: add tools without touching existing ones) ─
+/**
+ * Registers Zentao-specific tools to the Model Context Protocol (MCP) server.
+ *
+ * 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.
+ *
+ * @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);
-        const cleaned = cleanTask(data);
-        return {
-            content: [{ type: "text", text: taskToMarkdown(cleaned) }],
-        };
+        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);
-        const cleaned = cleanBug(data);
-        return {
-            content: [{ type: "text", text: bugToMarkdown(cleaned) }],
-        };
+        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 {
-            // If it already exists on disk and is not currently being downloaded
-            if (fs.existsSync(targetPath) && !activeDownloads.has(targetPath)) {
-                return {
-                    content: [{ type: "text", text: `File already exists locally at: ${targetPath}` }],
-                };
-            }
-            // If it is currently being downloaded, await the active promise
-            if (activeDownloads.has(targetPath)) {
-                await activeDownloads.get(targetPath);
-                return {
-                    content: [{ type: "text", text: `File downloaded successfully to: ${targetPath}` }],
-                };
-            }
-            // Start new download and track it
-            const downloadPromise = client.downloadFile(fileId, targetPath);
-            activeDownloads.set(targetPath, downloadPromise);
-            try {
-                const savedPath = await downloadPromise;
-                return {
-                    content: [{ type: "text", text: `File downloaded successfully to: ${savedPath}` }],
-                };
-            }
-            finally {
-                activeDownloads.delete(targetPath);
-            }
+            const message = await downloadAttachment(fileId, targetPath);
+            return mcpText(message);
         }
         catch (error) {
-            return {
-                content: [{ type: "text", text: `Failed to download file: ${error.message}` }],
-            };
+            return mcpText(`Failed to download file: ${error.message}`);
         }
     });
 }

package/build/zentaoClient.js

@@ -145,4 +145,32 @@ export class ZentaoClient {
             });
         });
     }
+    /**
+     * Downloads an image from a full authenticated URL and saves it to a local path.
+     * Uses the same authenticated Axios client so ZenTao session token is injected automatically.
+     *
+     * @param imageUrl The full image URL to download (e.g. https://zentao.../file-read-xxx.png).
+     * @param targetPath The local file path where the image should be saved.
+     * @returns A promise that resolves to the targetPath upon success, or rejects with an error.
+     */
+    async downloadImageToLocal(imageUrl, targetPath) {
+        const writer = fs.createWriteStream(targetPath);
+        const res = await this.client.get(imageUrl, {
+            baseURL: '', // override baseURL so the full URL is used as-is
+            responseType: 'stream',
+        });
+        return new Promise((resolve, reject) => {
+            res.data.pipe(writer);
+            let error = null;
+            writer.on('error', err => {
+                error = err;
+                writer.close();
+                reject(err);
+            });
+            writer.on('close', () => {
+                if (!error)
+                    resolve(targetPath);
+            });
+        });
+    }
 }

package/package.json

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