@dyno181cm.nexsoft/zentao_mcp 1.4.3 → 1.5.0

package/build/formatters/actionFormatter.js

@@ -1,9 +1,6 @@
 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";
+import { renderAttachments } from "./attachmentRenderer.js";
 /**
  * Normalizes and formats the history/comments/actions list into a clean Markdown block.
  *
@@ -47,36 +44,22 @@ export async function renderHistoryAndComments(actions, client, downloadedImages
                 commentStr = `\n  > ${commentMd.replace(/\n/g, '\n  > ')}`;
             }
         }
-        // 3. Format files if present in action
+        // 3. Format files if present in action — delegated to renderAttachments
         let filesStr = "";
-        if (act.files && Array.isArray(act.files) && act.files.length > 0) {
+        if (act.files) {
             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);
-                        }
+                // renderAttachments returns a full "## Files\n..." block; for inline action
+                // files we extract only the list items to keep the timeline compact.
+                const attachmentBlock = await renderAttachments(parsedFiles, client, downloadedImages);
+                if (attachmentBlock) {
+                    // Strip the section header and trim, then indent as a sub-item.
+                    const listContent = attachmentBlock
+                        .replace(/^\s*## Files\s*\n/, '')
+                        .trim();
+                    if (listContent) {
+                        filesStr = `\n  - *Attachments:* ${listContent.replace(/^- /gm, '').replace(/\n- /g, ', ')}`;
                     }
-                    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(", ")}`;
                 }
             }
         }

package/build/formatters/imageLocalizer.js

@@ -71,6 +71,8 @@ export async function localizeImages(html, client, downloadedImages) {
         }
         catch {
             // Keep original tag if download fails.
+            // Ensure in-flight entry is cleared even on unexpected errors.
+            inFlightImageDownloads.delete(remoteUrl);
         }
     }));
     // Phase 2: Apply all replacements sequentially on the original string.

package/build/tools/bugTool.js

@@ -17,6 +17,6 @@ export function registerBugTool(server, client) {
         const data = await client.getBugDetails(bugId);
         const downloadedImages = [];
         const markdown = await bugToMarkdown(data, client, downloadedImages);
-        return buildMcpResponse(markdown, downloadedImages);
+        return await buildMcpResponse(markdown, downloadedImages);
     });
 }

package/build/tools/commentTool.js

@@ -29,7 +29,7 @@ export function registerCommentTool(server, client) {
             `# History & Comments for ${title}`,
             markdown.trim() || "*No history or comments found.*"
         ].join("\n\n");
-        return buildMcpResponse(output, downloadedImages);
+        return await buildMcpResponse(output, downloadedImages);
     });
     server.registerTool("zentao_add_comment", {
         description: "Add a comment/remark to a task or a bug",

package/build/tools/statusTool.js

@@ -54,7 +54,7 @@ export function registerStatusTools(server, client) {
         const downloadedImages = [];
         const markdown = await taskToMarkdown(updatedTask, client, downloadedImages);
         const output = `### Successfully updated task status to '${updatedTask.status || "updated"}'!\n\n${markdown}`;
-        return buildMcpResponse(output, downloadedImages);
+        return await buildMcpResponse(output, downloadedImages);
     });
     // ─── Bug Status Update Tool ────────────────────────────────────────────────
     server.registerTool("zentao_update_bug_status", {
@@ -90,6 +90,6 @@ export function registerStatusTools(server, client) {
         const downloadedImages = [];
         const markdown = await bugToMarkdown(updatedBug, client, downloadedImages);
         const output = `### Successfully updated bug status to '${updatedBug.status || "updated"}'!\n\n${markdown}`;
-        return buildMcpResponse(output, downloadedImages);
+        return await buildMcpResponse(output, downloadedImages);
     });
 }

package/build/tools/taskTool.js

@@ -17,6 +17,6 @@ export function registerTaskTool(server, client) {
         const data = await client.getTaskDetails(taskId);
         const downloadedImages = [];
         const markdown = await taskToMarkdown(data, client, downloadedImages);
-        return buildMcpResponse(markdown, downloadedImages);
+        return await buildMcpResponse(markdown, downloadedImages);
     });
 }

package/build/utils/markdownUtils.js

@@ -1,5 +1,9 @@
 import TurndownService from "turndown";
-const turndownService = new TurndownService();
+const turndownService = new TurndownService({
+    headingStyle: 'atx', // Use `#` headings instead of underline style
+    bulletListMarker: '-', // Consistent `-` for unordered lists
+    codeBlockStyle: 'fenced', // Use ``` for code blocks
+});
 /** Convert HTML to Markdown for better AI readability. */
 export function htmlToMarkdown(html) {
     if (!html)
@@ -19,7 +23,7 @@ export function parseFiles(files) {
         size: f.size,
     });
     if (Array.isArray(files)) {
-        return files.filter(Boolean).map(mapper); // Fix #8: filter null/undefined items
+        return files.filter(Boolean).map(mapper); // filter null/undefined items
     }
     if (typeof files === "object") {
         return Object.values(files).filter(Boolean).map(mapper);

package/build/utils/mcpResponse.js

@@ -10,28 +10,29 @@ export function mcpText(text) {
  *
  * Images are deduplicated and limited to the first 5 to stay within
  * JSON-RPC / token limits. Individual images larger than 2 MB are skipped.
+ *
+ * Uses async file I/O (`fs.promises`) to avoid blocking the event loop
+ * while reading image data.
  */
-export function buildMcpResponse(markdown, imagePaths) {
+export async 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) {
+    await Promise.all(uniquePaths.map(async (imgPath) => {
         try {
-            if (!fs.existsSync(imgPath))
-                continue;
             const mimeType = getMimeType(imgPath);
             if (!mimeType)
-                continue;
-            const stats = fs.statSync(imgPath);
+                return;
+            const stats = await fs.promises.stat(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 });
+                return;
+            const buffer = await fs.promises.readFile(imgPath);
+            content.push({ type: "image", data: buffer.toString("base64"), mimeType });
         }
         catch {
             // Ignore read errors for individual images
         }
-    }
+    }));
     return { content };
 }

package/build/zentaoClient.js

@@ -2,6 +2,29 @@ import axios from 'axios';
 import * as dotenv from 'dotenv';
 import * as fs from 'fs';
 dotenv.config();
+/**
+ * Resolution label map for bug actions.
+ * Defined at module level to avoid re-allocating the object on every call to
+ * `generateActionDesc`.
+ */
+const RESOLUTION_LABEL_MAP = {
+    fixed: '已解决',
+    design: '设计如此',
+    duplicate: '重复Bug',
+    external: '外部原因',
+    notrepro: '无法重现',
+    postponed: '延期处理',
+    willnotfix: '不予解决',
+    tostory: '转为需求',
+};
+/**
+ * User fields that may be stored as a plain account string in the classic API
+ * and need to be normalised to `{ account, realname }` objects.
+ */
+const USER_FIELDS = [
+    'openedBy', 'assignedTo', 'resolvedBy',
+    'closedBy', 'finishedBy', 'canceledBy', 'lastEditedBy',
+];
 /**
  * Client for communicating with the Zentao API.
  * Handles authentication, automatic token injection, session expiration retries,
@@ -15,8 +38,21 @@ 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. */
+    /** In-flight request map prevents cache stampede under concurrent calls. */
     inFlightRequests = new Map();
+    // ─── Computed properties ─────────────────────────────────────────────────────
+    /**
+     * Returns the web base URL (without the API path suffix).
+     * Used by both `getFallbackClassicData` and `addComment` to avoid duplicating
+     * the same string-split logic in two places.
+     */
+    get webBaseUrl() {
+        if (this.baseUrl.includes('/api.php/v1')) {
+            return this.baseUrl.split('/api.php/v1')[0];
+        }
+        return this.baseUrl.split('/api/v1')[0];
+    }
+    // ─── Cache helpers ────────────────────────────────────────────────────────────
     /**
      * Clears the in-memory cache for GET requests. Helpful for testing.
      */
@@ -35,7 +71,7 @@ export class ZentaoClient {
         if (cached && now - cached.timestamp < this.cacheTtlMs) {
             return cached.data;
         }
-        // Fix #3: If a request for this URL is already in-flight, reuse its promise
+        // 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);
@@ -52,6 +88,7 @@ export class ZentaoClient {
         this.inFlightRequests.set(url, requestPromise);
         return requestPromise;
     }
+    // ─── Constructor & interceptors ───────────────────────────────────────────────
     /**
      * Initializes the Axios client with base configurations and registers interceptors
      * to automatically inject token headers and handle token expiration (401 errors).
@@ -92,6 +129,7 @@ export class ZentaoClient {
             return Promise.reject(error);
         });
     }
+    // ─── Authentication ───────────────────────────────────────────────────────────
     /**
      * Performs authentication request to Zentao API to obtain a token.
      * Updates the internal token state upon successful login.
@@ -113,6 +151,7 @@ export class ZentaoClient {
             throw new Error('Login failed: Token not found in response');
         }
     }
+    // ─── Private helpers ──────────────────────────────────────────────────────────
     /**
      * Helper to generate standard action descriptions when they are not present in classic API.
      */
@@ -122,20 +161,8 @@ export class ZentaoClient {
         if (userMap[extraName]) {
             extraName = userMap[extraName];
         }
-        else {
-            const resMap = {
-                'fixed': '已解决',
-                'design': '设计如此',
-                'duplicate': '重复Bug',
-                'external': '外部原因',
-                'notrepro': '无法重现',
-                'postponed': '延期处理',
-                'willnotfix': '不予解决',
-                'tostory': '转为需求',
-            };
-            if (resMap[extraName]) {
-                extraName = resMap[extraName];
-            }
+        else if (RESOLUTION_LABEL_MAP[extraName]) {
+            extraName = RESOLUTION_LABEL_MAP[extraName];
         }
         switch (act.action) {
             case 'opened':
@@ -175,10 +202,7 @@ export class ZentaoClient {
      * Fetches classic JSON API fallback data when REST API returns empty/errors.
      */
     async getFallbackClassicData(type, id) {
-        const webBaseUrl = this.baseUrl.includes('/api.php/v1')
-            ? this.baseUrl.split('/api.php/v1')[0]
-            : this.baseUrl.split('/api/v1')[0];
-        const url = `${webBaseUrl}/${type}-view-${id}.json`;
+        const url = `${this.webBaseUrl}/${type}-view-${id}.json`;
         const res = await this.client.get(url, {
             baseURL: '', // override baseURL
         });
@@ -190,8 +214,7 @@ export class ZentaoClient {
                 if (entity) {
                     const userMap = detailData.users || {};
                     // Normalize user fields
-                    const userFields = ['openedBy', 'assignedTo', 'resolvedBy', 'closedBy', 'finishedBy', 'canceledBy', 'lastEditedBy'];
-                    for (const field of userFields) {
+                    for (const field of USER_FIELDS) {
                         const val = entity[field];
                         if (val && typeof val === 'string') {
                             entity[field] = {
@@ -227,6 +250,60 @@ export class ZentaoClient {
         }
         throw new Error(`Failed to fetch ${type} details from classic fallback API for ID ${id}`);
     }
+    /**
+     * Generic helper that fetches entity details from the REST API and falls back
+     * to the classic JSON API when the REST response is empty or throws an error.
+     * Caches the fallback result under the REST API key so subsequent calls are fast.
+     *
+     * @param restUrl   The REST API path (e.g. `/tasks/1`).
+     * @param type      Entity type passed to `getFallbackClassicData`.
+     * @param id        Entity ID passed to `getFallbackClassicData`.
+     */
+    async getWithFallback(restUrl, type, id) {
+        const runFallback = async () => {
+            const data = await this.getFallbackClassicData(type, id);
+            // Cache the fallback result under the REST key so repeated calls are fast.
+            this.getCache.set(restUrl, { data, timestamp: Date.now() });
+            return data;
+        };
+        try {
+            const data = await this.get(restUrl);
+            if (!data || data === '') {
+                return runFallback();
+            }
+            return data;
+        }
+        catch {
+            return runFallback();
+        }
+    }
+    /**
+     * Shared stream-to-file helper used by `downloadFile` and `downloadImageToLocal`.
+     * Pipes a readable stream to a local file path, removing the partial file on error.
+     *
+     * @param readable    A Node.js Readable stream (axios response body).
+     * @param targetPath  The local file path to write to.
+     * @returns Resolves with `targetPath` on success.
+     */
+    pipeStreamToFile(readable, targetPath) {
+        const writer = fs.createWriteStream(targetPath);
+        return new Promise((resolve, reject) => {
+            readable.pipe(writer);
+            let writeError = null;
+            writer.on('error', (err) => {
+                writeError = err;
+                writer.close();
+                // 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 (!writeError)
+                    resolve(targetPath);
+            });
+        });
+    }
+    // ─── Public API ───────────────────────────────────────────────────────────────
     /**
      * Retrieves details of a specific task.
      * Checks the cache first, otherwise fetches from API.
@@ -236,25 +313,7 @@ export class ZentaoClient {
      * @returns Resolves with the task details.
      */
     async getTaskDetails(taskId) {
-        try {
-            const task = await this.get(`/tasks/${taskId}`);
-            if (!task || task === "") {
-                const fallbackTask = await this.getFallbackClassicData('task', taskId);
-                this.getCache.set(`/tasks/${taskId}`, { data: fallbackTask, timestamp: Date.now() });
-                return fallbackTask;
-            }
-            return task;
-        }
-        catch (error) {
-            try {
-                const fallbackTask = await this.getFallbackClassicData('task', taskId);
-                this.getCache.set(`/tasks/${taskId}`, { data: fallbackTask, timestamp: Date.now() });
-                return fallbackTask;
-            }
-            catch (fallbackError) {
-                throw error; // throw original error if fallback also fails
-            }
-        }
+        return this.getWithFallback(`/tasks/${taskId}`, 'task', taskId);
     }
     /**
      * Retrieves details of a specific bug.
@@ -265,25 +324,7 @@ export class ZentaoClient {
      * @returns Resolves with the bug details.
      */
     async getBugDetails(bugId) {
-        try {
-            const bug = await this.get(`/bugs/${bugId}`);
-            if (!bug || bug === "") {
-                const fallbackBug = await this.getFallbackClassicData('bug', bugId);
-                this.getCache.set(`/bugs/${bugId}`, { data: fallbackBug, timestamp: Date.now() });
-                return fallbackBug;
-            }
-            return bug;
-        }
-        catch (error) {
-            try {
-                const fallbackBug = await this.getFallbackClassicData('bug', bugId);
-                this.getCache.set(`/bugs/${bugId}`, { data: fallbackBug, timestamp: Date.now() });
-                return fallbackBug;
-            }
-            catch (fallbackError) {
-                throw error; // throw original error if fallback also fails
-            }
-        }
+        return this.getWithFallback(`/bugs/${bugId}`, 'bug', bugId);
     }
     /**
      * Downloads a file from Zentao API and pipes it to a local file path.
@@ -293,25 +334,10 @@ export class ZentaoClient {
      * @returns A promise that resolves to the targetPath upon success, or rejects with an error.
      */
     async downloadFile(fileId, targetPath) {
-        const writer = fs.createWriteStream(targetPath);
         const res = await this.client.get(`/files/${fileId}`, {
             responseType: 'stream',
         });
-        return new Promise((resolve, reject) => {
-            res.data.pipe(writer);
-            let error = null;
-            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)
-                    resolve(targetPath);
-            });
-        });
+        return this.pipeStreamToFile(res.data, targetPath);
     }
     /**
      * Downloads an image from a full authenticated URL and saves it to a local path.
@@ -322,26 +348,11 @@ export class ZentaoClient {
      * @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();
-                // 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)
-                    resolve(targetPath);
-            });
-        });
+        return this.pipeStreamToFile(res.data, targetPath);
     }
     /**
      * Helper method to perform POST requests.
@@ -387,10 +398,7 @@ export class ZentaoClient {
         if (!this.token) {
             await this.login();
         }
-        const webBaseUrl = this.baseUrl.includes('/api.php/v1')
-            ? this.baseUrl.split('/api.php/v1')[0]
-            : this.baseUrl.split('/api/v1')[0];
-        const url = `${webBaseUrl}/action-comment-${type}-${id}.json?zentaosid=${this.token}`;
+        const url = `${this.webBaseUrl}/action-comment-${type}-${id}.json?zentaosid=${this.token}`;
         // Clear the cache so subsequent fetches get the new comment
         this.clearCache();
         const params = new URLSearchParams();

package/package.json

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