@dyno181cm.nexsoft/zentao_mcp 1.2.8 → 1.2.9

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,88 +23,26 @@ 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 [];
 }
-/**
- * Simple utility to convert basic HTML to Markdown for better readability by the AI.
- */
-function htmlToMarkdown(html) {
-    if (!html)
+/** Format a ZenTao user field (object or string) into a human-readable string. */
+function formatUser(user) {
+    if (!user)
         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)
-    };
+    if (typeof user === 'object') {
+        const name = user.realname || user.account || '';
+        const account = user.account ? ` (${user.account})` : '';
+        return `${name}${account}`;
+    }
+    return String(user);
 }
+/** Format a file size in bytes to a human-readable string (B / KB / MB). */
 export function formatSize(bytes) {
     if (bytes === undefined || bytes === null || bytes === '')
         return 'unknown size';
@@ -118,132 +55,147 @@ 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 }] };
+}
+/** Render a list of file attachments as a Markdown section. Returns empty string if none. */
+function renderAttachments(files) {
+    if (!files || files.length === 0)
+        return '';
+    const lines = files.map((f) => `- 📎 **${f.title}** (ID: ${f.id}, Extension: ${f.extension}, Size: ${formatSize(f.size)})`);
+    return `\n## Attachments\n${lines.join('\n')}\n`;
+}
+// ─── Public formatters ───────────────────────────────────────────────────────
+/**
+ * Format a raw ZenTao task object into a human-readable Markdown document.
+ */
+export 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`;
+    const est = rawTask.estimate ?? 0;
+    const cons = rawTask.consumed ?? 0;
+    const left = rawTask.left ?? 0;
+    const prog = rawTask.progress ?? 0;
+    const lines = [
+        `# Task #${rawTask.id}: ${rawTask.name}`,
+        '',
+        `- **Status**: ${rawTask.status || 'N/A'}`,
+        `- **Priority**: ${rawTask.pri || 'N/A'}`,
+        `- **Estimate / Consumed / Left**: ${est}h / ${cons}h / ${left}h (${prog}%)`,
+    ];
+    if (rawTask.openedBy)
+        lines.push(`- **Opened By**: ${formatUser(rawTask.openedBy)}`);
+    if (rawTask.assignedTo)
+        lines.push(`- **Assigned To**: ${formatUser(rawTask.assignedTo)}`);
+    if (rawTask.finishedBy)
+        lines.push(`- **Finished By**: ${formatUser(rawTask.finishedBy)}`);
+    if (rawTask.closedBy) {
+        const reason = rawTask.closedReason ? ` (Reason: ${rawTask.closedReason})` : '';
+        lines.push(`- **Closed By**: ${formatUser(rawTask.closedBy)}${reason}`);
     }
-    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`;
-        });
-    }
-    return md;
+    const desc = htmlToMarkdown(rawTask.desc);
+    lines.push(`\n## Description\n${desc || '*No description provided.*'}`);
+    lines.push(renderAttachments(parseFiles(rawTask.files)));
+    return lines.join('\n');
 }
-export function bugToMarkdown(bug) {
-    if (!bug)
+/**
+ * Format a raw ZenTao bug object into a human-readable Markdown document.
+ */
+export 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`;
+    const lines = [
+        `# Bug #${rawBug.id}: ${rawBug.title}`,
+        '',
+        `- **Status**: ${rawBug.status || 'N/A'}`,
+        `- **Severity**: ${rawBug.severity || 'N/A'}`,
+        `- **Priority**: ${rawBug.pri || 'N/A'}`,
+        `- **Type**: ${rawBug.type || 'N/A'}`,
+    ];
+    if (rawBug.openedBy)
+        lines.push(`- **Opened By**: ${formatUser(rawBug.openedBy)}`);
+    if (rawBug.assignedTo)
+        lines.push(`- **Assigned To**: ${formatUser(rawBug.assignedTo)}`);
+    if (rawBug.resolvedBy) {
+        const resolution = rawBug.resolution ? ` (Resolution: ${rawBug.resolution})` : '';
+        lines.push(`- **Resolved By**: ${formatUser(rawBug.resolvedBy)}${resolution}`);
+    }
+    if (rawBug.closedBy)
+        lines.push(`- **Closed By**: ${formatUser(rawBug.closedBy)}`);
+    const steps = htmlToMarkdown(rawBug.steps);
+    lines.push(`\n## Steps to Reproduce\n${steps || '*No steps provided.*'}`);
+    lines.push(renderAttachments(parseFiles(rawBug.files)));
+    return lines.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}`;
     }
-    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`;
-        });
+    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(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(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/package.json

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