@dyno181cm.nexsoft/zentao_mcp 1.1.0 → 1.2.1

package/README.md

@@ -6,8 +6,7 @@ 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).
 
@@ -45,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
 {
@@ -70,38 +65,11 @@ 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:**

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.1"
 });
+// 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

@@ -3,30 +3,108 @@ import * as os from "os";
 import * as path from "path";
 import { ZentaoClient } from "./zentaoClient.js";
 const client = new ZentaoClient();
-export function registerTools(server) {
-    server.registerTool("zentao_get_execution_tasks", {
-        description: "Get a list of tasks in an execution (sprint), optionally filtered by moduleID",
-        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"),
-        }
-    }, 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) }],
-        };
+/**
+ * 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.
+ */
+function parseFiles(files) {
+    if (!files)
+        return [];
+    const mapper = (f) => ({
+        id: f.id,
+        title: f.title || f.name,
+        extension: f.extension,
+        size: f.size
     });
-    server.registerTool("zentao_get_product_bugs", {
-        description: "Get a list of bugs for a product",
+    if (Array.isArray(files)) {
+        return files.map(mapper);
+    }
+    if (typeof files === 'object') {
+        return Object.values(files).map(mapper);
+    }
+    return [];
+}
+function cleanTask(task) {
+    if (!task)
+        return null;
+    return {
+        id: task.id,
+        name: task.name,
+        status: task.status,
+        pri: task.pri,
+        desc: 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)
+    };
+}
+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: 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)
+    };
+}
+export function registerTools(server) {
+    server.registerTool("zentao_get_task_details", {
+        description: "Get detailed information of a task",
         inputSchema: {
-            productId: z.union([z.string(), z.number()]).describe("Product ID"),
+            taskId: z.union([z.string(), z.number()]).describe("Task ID"),
         }
-    }, async ({ productId }) => {
-        const data = await client.getProductBugs(productId);
+    }, async ({ taskId }) => {
+        const data = await client.getTaskDetails(taskId);
+        const cleaned = cleanTask(data);
         return {
-            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(cleaned, null, 2) }],
         };
     });
     server.registerTool("zentao_get_bug_details", {
@@ -36,8 +114,9 @@ export function registerTools(server) {
         }
     }, async ({ bugId }) => {
         const data = await client.getBugDetails(bugId);
+        const cleaned = cleanBug(data);
         return {
-            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            content: [{ type: "text", text: JSON.stringify(cleaned, null, 2) }],
         };
     });
     server.registerTool("zentao_download_attachment", {

package/build/zentaoClient.js

@@ -2,12 +2,21 @@ 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,
@@ -42,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) {
@@ -63,42 +78,33 @@ 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}`, {

package/package.json

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