@dyno181cm.nexsoft/zentao_mcp 1.0.2 → 1.2.0

package/README.md

@@ -6,9 +6,9 @@ A Model Context Protocol (MCP) server for integrating with the Zentao API. This
 
 - **Authentication**: Automatically handles login and token management for Zentao.
 - **MCP Tools**:
-  - `zentao_get_execution_tasks`: Retrieve tasks in an execution (sprint), with optional filtering by module ID.
-  - `zentao_get_product_bugs`: Fetch a list of bugs associated with a specific product.
+  - `zentao_get_task_details`: Get detailed information about a specific task by ID.
   - `zentao_get_bug_details`: Get detailed information about a specific bug.
+  - `zentao_download_attachment`: Download file attachments from ZenTao (e.g., bug/task images or videos).
 
 ## Requirements
 
@@ -44,11 +44,7 @@ This server communicates via standard input/output (`stdio`), making it compatib
 
 ### Integrating with MCP Clients (Claude Desktop, Cursor, etc.)
 
-Once published to npm or GitHub, users can integrate this server into their MCP clients easily.
-
-#### Option 1: Running via `npx` (Recommended if published to NPM)
-
-Add the following to your MCP client configuration (e.g., `claude_desktop_config.json`):
+Once published to npm or GitHub, users can integrate this server into their MCP clients easily. Add the following to your MCP client configuration (e.g., `claude_desktop_config.json`):
 
 ```json
 {
@@ -69,39 +65,17 @@ Add the following to your MCP client configuration (e.g., `claude_desktop_config
 }
 ```
 
-#### Option 2: Running from a Local Clone
-
-If a user clones the repository locally, they can configure their client to run it directly:
-
-```json
-{
-  "mcpServers": {
-    "zentao": {
-      "command": "node",
-      "args": ["/absolute/path/to/zentao_mcp/build/index.js"],
-      "env": {
-        "ZENTAO_BASE_URL": "https://your-zentao-url.com/api.php/v1",
-        "ZENTAO_ACCOUNT": "your_username",
-        "ZENTAO_PASSWORD": "your_password"
-      }
-    }
-  }
-}
-```
-
 ### Available Tools
 
-- **`zentao_get_execution_tasks`**
-  - **Inputs:**
-    - `executionId` (string | number) - Required. Execution ID.
-    - `page` (number) - Optional. Current page (default 1).
-    - `limit` (number) - Optional. Items per page (default 500).
-    - `moduleId` (string | number) - Optional. Filter by module ID.
-
-- **`zentao_get_product_bugs`**
+- **`zentao_get_task_details`**
   - **Inputs:**
-    - `productId` (string | number) - Required. Product ID.
+    - `taskId` (string | number) - Required. Task ID.
 
 - **`zentao_get_bug_details`**
   - **Inputs:**
     - `bugId` (string | number) - Required. Bug ID.
+
+- **`zentao_download_attachment`**
+  - **Inputs:**
+    - `fileId` (string | number) - Required. File ID to download.
+    - `extension` (string) - Optional. File extension (e.g., mp4, png).

package/build/index.js

@@ -3,17 +3,26 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerTools } from "./tools.js";
 import * as dotenv from "dotenv";
+// Initialize environment variables from .env file
 dotenv.config();
+// Create the MCP server instance
 const server = new McpServer({
     name: "Zentao MCP Server",
-    version: "1.0.0"
+    version: "1.2.0"
 });
+// Register all Zentao-specific tools onto the server
 registerTools(server);
+/**
+ * Main entrypoint of the Zentao MCP Server.
+ * Connects the server to a standard input/output (stdio) transport
+ * so that MCP clients can communicate with it.
+ */
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Zentao MCP Server started via stdio.");
 }
+// Start the server and handle any initialization errors
 main().catch(error => {
     console.error("Fatal error starting server:", error);
     process.exit(1);

package/build/tools.js

@@ -1,28 +1,26 @@
 import { z } from "zod";
+import * as os from "os";
+import * as path from "path";
 import { ZentaoClient } from "./zentaoClient.js";
 const client = new ZentaoClient();
+/**
+ * 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.
+ */
 export function registerTools(server) {
-    server.registerTool("zentao_get_execution_tasks", {
-        description: "Get a list of tasks in an execution (sprint), optionally filtered by moduleID",
+    server.registerTool("zentao_get_task_details", {
+        description: "Get detailed information of a task",
         inputSchema: {
-            executionId: z.union([z.string(), z.number()]).describe("Execution ID"),
-            page: z.number().optional().describe("Current page (default 1)"),
-            limit: z.number().optional().describe("Number of items per page (default 500)"),
-            moduleId: z.union([z.string(), z.number()]).optional().describe("Filter by module ID"),
+            taskId: z.union([z.string(), z.number()]).describe("Task ID"),
         }
-    }, async ({ executionId, page = 1, limit = 500, moduleId }) => {
-        const data = await client.getExecutionTasks(executionId, page, limit, moduleId);
-        return {
-            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-        };
-    });
-    server.registerTool("zentao_get_product_bugs", {
-        description: "Get a list of bugs for a product",
-        inputSchema: {
-            productId: z.union([z.string(), z.number()]).describe("Product ID"),
-        }
-    }, async ({ productId }) => {
-        const data = await client.getProductBugs(productId);
+    }, async ({ taskId }) => {
+        const data = await client.getTaskDetails(taskId);
         return {
             content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
         };
@@ -38,4 +36,25 @@ export function registerTools(server) {
             content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
         };
     });
+    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 savedPath = await client.downloadFile(fileId, targetPath);
+            return {
+                content: [{ type: "text", text: `File downloaded successfully to: ${savedPath}` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: `Failed to download file: ${error.message}` }],
+            };
+        }
+    });
 }

package/build/zentaoClient.js

@@ -1,12 +1,22 @@
 import axios from 'axios';
 import * as dotenv from 'dotenv';
+import * as fs from 'fs';
 dotenv.config();
+/**
+ * Client for communicating with the Zentao API.
+ * Handles authentication, automatic token injection, session expiration retries,
+ * and standard API requests for projects, executions, tasks, bugs, and attachments.
+ */
 export class ZentaoClient {
     client;
     token = null;
     account = process.env.ZENTAO_ACCOUNT || '';
     password = process.env.ZENTAO_PASSWORD || '';
     baseUrl = process.env.ZENTAO_BASE_URL || '';
+    /**
+     * Initializes the Axios client with base configurations and registers interceptors
+     * to automatically inject token headers and handle token expiration (401 errors).
+     */
     constructor() {
         this.client = axios.create({
             baseURL: this.baseUrl,
@@ -41,6 +51,12 @@ export class ZentaoClient {
             return Promise.reject(error);
         });
     }
+    /**
+     * Performs authentication request to Zentao API to obtain a token.
+     * Updates the internal token state upon successful login.
+     *
+     * @throws {Error} If account/password env vars are missing or if the API request fails.
+     */
     async login() {
         try {
             if (!this.account || !this.password) {
@@ -62,40 +78,51 @@ export class ZentaoClient {
             throw error;
         }
     }
-    async getUsers(page = 1, limit = 100) {
-        const res = await this.client.get(`/users?page=${page}&limit=${limit}`);
-        return res.data;
-    }
-    async getProjects() {
-        const res = await this.client.get('/projects');
-        return res.data;
-    }
-    async getProjectExecutions(projectId) {
-        const res = await this.client.get(`/projects/${projectId}/executions`);
-        return res.data;
-    }
-    async getExecutionDetails(executionId) {
-        const res = await this.client.get(`/executions/${executionId}`);
-        return res.data;
-    }
-    async getExecutionTasks(executionId, page = 1, limit = 500, moduleId) {
-        let url = `/executions/${executionId}/tasks?page=${page}&limit=${limit}`;
-        if (moduleId) {
-            url += `&moduleID=${moduleId}`;
-        }
-        const res = await this.client.get(url);
-        return res.data;
-    }
-    async getTaskModules(executionId) {
-        const res = await this.client.get(`/modules?type=task&id=${executionId}`);
-        return res.data;
-    }
-    async getProductBugs(productId) {
-        const res = await this.client.get(`/products/${productId}/bugs`);
+    /**
+     * Retrieves details of a specific task.
+     *
+     * @param taskId The ID of the task.
+     * @returns Resolves with the task details.
+     */
+    async getTaskDetails(taskId) {
+        const res = await this.client.get(`/tasks/${taskId}`);
         return res.data;
     }
+    /**
+     * Retrieves details of a specific bug.
+     *
+     * @param bugId The ID of the bug.
+     * @returns Resolves with the bug details.
+     */
     async getBugDetails(bugId) {
         const res = await this.client.get(`/bugs/${bugId}`);
         return res.data;
     }
+    /**
+     * Downloads a file from Zentao API and pipes it to a local file path.
+     *
+     * @param fileId The ID of the file to download.
+     * @param targetPath The local file path where the file should be saved.
+     * @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();
+                reject(err);
+            });
+            writer.on('close', () => {
+                if (!error) {
+                    resolve(targetPath);
+                }
+            });
+        });
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dyno181cm.nexsoft/zentao_mcp",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Zentao MCP Server",
   "main": "build/index.js",
   "bin": {