@dyno181cm.nexsoft/zentao_mcp 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# Zentao MCP Server
+
+A Model Context Protocol (MCP) server for integrating with the Zentao API. This server provides tools to access project management data from Zentao directly through MCP-compatible interfaces.
+
+## Features
+
+- **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_bug_details`: Get detailed information about a specific bug.
+
+## Requirements
+
+- Node.js (v18 or higher recommended)
+- A Zentao instance accessible via API
+
+## Installation
+
+1. Clone the repository:
+
+   ```bash
+   git clone <repository-url>
+   cd zentao_mcp
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Configure environment variables:
+   Create a `.env` file in the root directory and add the following configurations:
+   ```env
+   ZENTAO_BASE_URL=https://your-zentao-url.com/api.php/v1
+   ZENTAO_ACCOUNT=your_username
+   ZENTAO_PASSWORD=your_password
+   ```
+
+## Usage
+
+This server communicates via standard input/output (`stdio`), making it compatible with any MCP client that supports stdio transport.
+
+### 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`):
+
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@dyno181cm.nexsoft/zentao_mcp"
+      ],
+      "env": {
+        "ZENTAO_BASE_URL": "https://your-zentao-url.com/api.php/v1",
+        "ZENTAO_ACCOUNT": "your_username",
+        "ZENTAO_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+#### 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`**
+  - **Inputs:**
+    - `productId` (string | number) - Required. Product ID.
+
+- **`zentao_get_bug_details`**
+  - **Inputs:**
+    - `bugId` (string | number) - Required. Bug ID.

package/build/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+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";
+dotenv.config();
+const server = new McpServer({
+    name: "Zentao MCP Server",
+    version: "1.0.0"
+});
+registerTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Zentao MCP Server started via stdio.");
+}
+main().catch(error => {
+    console.error("Fatal error starting server:", error);
+    process.exit(1);
+});

package/build/testApi.js

@@ -0,0 +1,31 @@
+import { ZentaoClient } from './zentaoClient.js';
+import * as dotenv from 'dotenv';
+dotenv.config();
+async function main() {
+    try {
+        const client = new ZentaoClient();
+        console.log('Logging in to Zentao...');
+        await client.login();
+        console.log('Successfully logged in.');
+        console.log('\n--- Fetching execution tasks (Execution ID: 2) ---');
+        try {
+            const tasks = await client.getExecutionTasks(2, 1, 5);
+            console.log('Tasks result:', JSON.stringify(tasks, null, 2));
+        }
+        catch (e) {
+            console.error('Error fetching tasks:', e.response?.data || e.message);
+        }
+        console.log('\n--- Fetching bug details (Bug ID: 2) ---');
+        try {
+            const bug = await client.getBugDetails(2);
+            console.log('Bug details:', JSON.stringify(bug, null, 2));
+        }
+        catch (e) {
+            console.error('Error fetching bug:', e.response?.data || e.message);
+        }
+    }
+    catch (error) {
+        console.error('Fatal Error:', error.message || error);
+    }
+}
+main();

package/build/tools.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+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) }],
+        };
+    });
+    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);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+    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);
+        return {
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        };
+    });
+}

package/build/zentaoClient.js

@@ -0,0 +1,101 @@
+import axios from 'axios';
+import * as dotenv from 'dotenv';
+dotenv.config();
+export class ZentaoClient {
+    client;
+    token = null;
+    account = process.env.ZENTAO_ACCOUNT || '';
+    password = process.env.ZENTAO_PASSWORD || '';
+    baseUrl = process.env.ZENTAO_BASE_URL || '';
+    constructor() {
+        this.client = axios.create({
+            baseURL: this.baseUrl,
+            headers: {
+                'Content-Type': 'application/json',
+            },
+        });
+        // Add a request interceptor to automatically add the token and handle retries
+        this.client.interceptors.request.use(async (config) => {
+            // Don't add token if we are requesting a token
+            if (config.url === '/tokens')
+                return config;
+            if (!this.token) {
+                await this.login();
+            }
+            if (this.token) {
+                config.headers['Token'] = this.token;
+            }
+            return config;
+        });
+        // Add response interceptor to handle 401 Unauthorized (token expiry)
+        this.client.interceptors.response.use((response) => response, async (error) => {
+            const originalRequest = error.config;
+            if (error.response?.status === 401 && !originalRequest._retry && originalRequest.url !== '/tokens') {
+                originalRequest._retry = true;
+                await this.login();
+                if (this.token) {
+                    originalRequest.headers['Token'] = this.token;
+                    return this.client(originalRequest);
+                }
+            }
+            return Promise.reject(error);
+        });
+    }
+    async login() {
+        try {
+            if (!this.account || !this.password) {
+                throw new Error('ZENTAO_ACCOUNT or ZENTAO_PASSWORD is not set in environment variables');
+            }
+            const response = await this.client.post('/tokens', {
+                account: this.account,
+                password: this.password,
+            });
+            if (response.data && response.data.token) {
+                this.token = response.data.token;
+            }
+            else {
+                throw new Error('Login failed: Token not found in response');
+            }
+        }
+        catch (error) {
+            console.error('Failed to login to Zentao:', error.message);
+            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`);
+        return res.data;
+    }
+    async getBugDetails(bugId) {
+        const res = await this.client.get(`/bugs/${bugId}`);
+        return res.data;
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dyno181cm.nexsoft/zentao_mcp",
+  "version": "1.0.0",
+  "description": "Zentao MCP Server",
+  "main": "build/index.js",
+  "bin": {
+    "zentao_mcp": "build/index.js"
+  },
+  "type": "module",
+  "files": [
+    "build"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsc --watch",
+    "test:api": "tsx tests/testApi.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.1.0",
+    "axios": "^1.7.9",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "tsx": "^4.23.0",
+    "typescript": "^5.7.2"
+  }
+}