@leeguoo/zentao-mcp 0.2.1 → 0.3.0

package/README.md

@@ -2,9 +2,38 @@
 
 MCP server for ZenTao RESTful APIs (products + bugs).
 
-## Quick Start (npx)
+## Quick Start
 
-Use this MCP server config in your client:
+### Cursor IDE
+
+1. Open Cursor Settings (⌘, on Mac or Ctrl+, on Windows/Linux)
+2. Navigate to **Features** → **Model Context Protocol**
+3. Click **Edit Config** to open `~/.cursor/mcp.json` (or create it)
+4. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "zentao-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@leeguoo/zentao-mcp",
+        "--zentao-url=https://zentao.example.com/zentao",
+        "--zentao-account=leo",
+        "--zentao-password=***",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+5. Restart Cursor IDE
+
+### Other MCP Clients (Claude Desktop, etc.)
+
+For clients using TOML configuration (e.g., Claude Desktop), add to your MCP config file:
 
 ```toml
 [mcp_servers."zentao-mcp"]
@@ -12,30 +41,103 @@ command = "npx"
 args = [
   "-y",
   "@leeguoo/zentao-mcp",
-  "--stdio",
   "--zentao-url=https://zentao.example.com/zentao",
   "--zentao-account=leo",
-  "--zentao-password=***"
+  "--zentao-password=***",
+  "--stdio"
 ]
 ```
 
+**Config file locations:**
+- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.toml` (Mac) or `%APPDATA%\Claude\claude_desktop_config.toml` (Windows)
+- Cursor: `~/.cursor/mcp.json` (JSON format)
+
 ## Configuration
 
-Required:
-- `--zentao-url` / `ZENTAO_URL` (e.g. `https://zentao.example.com/zentao`)
-- `--zentao-account` / `ZENTAO_ACCOUNT`
-- `--zentao-password` / `ZENTAO_PASSWORD`
+### Required Parameters
+
+You can configure the server using CLI arguments or environment variables:
 
-Tip: `ZENTAO_URL` should include the ZenTao base path (often `/zentao`).
+**CLI Arguments:**
+- `--zentao-url` (e.g. `https://zentao.example.com/zentao`)
+- `--zentao-account`
+- `--zentao-password`
+
+**Environment Variables:**
+- `ZENTAO_URL` (e.g. `https://zentao.example.com/zentao`)
+- `ZENTAO_ACCOUNT`
+- `ZENTAO_PASSWORD`
+
+### Using Environment Variables in Cursor
+
+If you prefer to use environment variables instead of CLI args, you can configure them in Cursor:
+
+```json
+{
+  "mcpServers": {
+    "zentao-mcp": {
+      "command": "npx",
+      "args": ["-y", "@leeguoo/zentao-mcp", "--stdio"],
+      "env": {
+        "ZENTAO_URL": "https://zentao.example.com/zentao",
+        "ZENTAO_ACCOUNT": "leo",
+        "ZENTAO_PASSWORD": "***"
+      }
+    }
+  }
+}
+```
+
+**Tip:** `ZENTAO_URL` should include the ZenTao base path (often `/zentao`).
 
 ## Tools
 
-- `zentao_products_list` (page, limit)
-- `zentao_bugs_list` (product, page, limit)
-- `zentao_bugs_stats` (includeZero, limit)
+The MCP server provides four tools that can be triggered by natural language in Cursor:
+
+- **`zentao_products_list`** - List all products
+- **`zentao_bugs_list`** - List bugs for a specific product
+- **`zentao_bugs_stats`** - Get bug statistics across products
+- **`zentao_bugs_mine`** - List my bugs by assignment or creator
 
-Example tool input:
+### Usage Examples
 
+After configuring the MCP server in Cursor, you can use natural language to interact with ZenTao:
+
+**English:**
+- "Show me all products"
+- "List bugs for product 1"
+- "Show me bugs"
+- "What's the bug statistics?"
+- "Show my bugs"
+- "List bugs assigned to me"
+- "View bugs in product 2"
+
+**Chinese (中文):**
+- "看bug" / "查看bug" / "显示bug"
+- "产品1的bug列表"
+- "bug统计"
+- "显示所有产品"
+- "查看产品2的问题"
+- "我的bug"
+- "分配给我的bug"
+
+The AI will automatically:
+1. Use `zentao_products_list` to get product IDs when needed
+2. Use `zentao_bugs_list` when you ask to see bugs
+3. Use `zentao_bugs_stats` when you ask for statistics or overview
+4. Use `zentao_bugs_mine` when you ask for your own bugs
+
+### Tool Parameters
+
+**zentao_products_list:**
+```json
+{
+  "page": 1,
+  "limit": 1000
+}
+```
+
+**zentao_bugs_list:**
 ```json
 {
   "product": 1,
@@ -44,6 +146,24 @@ Example tool input:
 }
 ```
 
+**zentao_bugs_stats:**
+```json
+{
+  "includeZero": false,
+  "limit": 1000
+}
+```
+
+**zentao_bugs_mine:**
+```json
+{
+  "scope": "assigned",
+  "includeZero": false,
+  "includeDetails": true,
+  "maxItems": 50
+}
+```
+
 ## Local Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeguoo/zentao-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP server for ZenTao RESTful APIs",
   "keywords": [
     "zentao",
@@ -26,6 +26,9 @@
     "src",
     "README.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "start": "node src/index.js",
     "release": "./scripts/release.sh",

package/src/index.js

@@ -50,6 +50,10 @@ function normalizeError(message, payload) {
   return { status: 0, msg: message || "error", result: payload ?? [] };
 }
 
+function normalizeAccount(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
 class ZentaoClient {
   constructor({ baseUrl, account, password }) {
     this.baseUrl = normalizeBaseUrl(baseUrl);
@@ -156,6 +160,49 @@ class ZentaoClient {
     return normalizeResult(payload);
   }
 
+  async fetchAllBugsForProduct({ product, perPage, maxItems }) {
+    const bugs = [];
+    let page = 1;
+    let total = null;
+    const pageSize = toInt(perPage, 100);
+    const cap = toInt(maxItems, 0);
+
+    while (true) {
+      const payload = await this.request({
+        method: "GET",
+        path: "/api.php/v1/bugs",
+        query: {
+          product,
+          page,
+          limit: pageSize,
+        },
+      });
+
+      if (payload.error) {
+        throw new Error(payload.error);
+      }
+
+      const pageBugs = Array.isArray(payload.bugs) ? payload.bugs : [];
+      total = payload.total ?? total;
+      for (const bug of pageBugs) {
+        bugs.push(bug);
+        if (cap > 0 && bugs.length >= cap) {
+          return { bugs, total };
+        }
+      }
+
+      if (total !== null && payload.limit) {
+        if (page * payload.limit >= total) break;
+      } else if (pageBugs.length < pageSize) {
+        break;
+      }
+
+      page += 1;
+    }
+
+    return { bugs, total };
+  }
+
   async bugStats({ includeZero, limit }) {
     const productsResponse = await this.listProducts({ page: 1, limit: toInt(limit, 1000) });
     if (productsResponse.status !== 1) return productsResponse;
@@ -183,6 +230,90 @@ class ZentaoClient {
       products: rows,
     });
   }
+
+  async bugsMine({
+    account,
+    scope,
+    productIds,
+    includeZero,
+    perPage,
+    maxItems,
+    includeDetails,
+  }) {
+    const matchAccount = normalizeAccount(account || this.account);
+    const targetScope = (scope || "assigned").toLowerCase();
+
+    const productsResponse = await this.listProducts({ page: 1, limit: 1000 });
+    if (productsResponse.status !== 1) return productsResponse;
+    const products = productsResponse.result.products || [];
+
+    const productSet = Array.isArray(productIds) && productIds.length
+      ? new Set(productIds.map((id) => Number(id)))
+      : null;
+
+    const rows = [];
+    const bugs = [];
+    let totalMatches = 0;
+    const maxCollect = toInt(maxItems, 200);
+
+    for (const product of products) {
+      if (productSet && !productSet.has(Number(product.id))) continue;
+      const { bugs: productBugs } = await this.fetchAllBugsForProduct({
+        product: product.id,
+        perPage,
+      });
+
+      const matches = productBugs.filter((bug) => {
+        const assigned = normalizeAccount(bug.assignedTo);
+        const opened = normalizeAccount(bug.openedBy);
+        const resolved = normalizeAccount(bug.resolvedBy);
+        if (targetScope === "assigned") return assigned === matchAccount;
+        if (targetScope === "opened") return opened === matchAccount;
+        if (targetScope === "resolved") return resolved === matchAccount;
+        return (
+          assigned === matchAccount ||
+          opened === matchAccount ||
+          resolved === matchAccount
+        );
+      });
+
+      if (!includeZero && matches.length === 0) continue;
+      totalMatches += matches.length;
+
+      rows.push({
+        id: product.id,
+        name: product.name,
+        totalBugs: toInt(product.totalBugs, 0),
+        myBugs: matches.length,
+      });
+
+      if (includeDetails && bugs.length < maxCollect) {
+        for (const bug of matches) {
+          if (bugs.length >= maxCollect) break;
+          bugs.push({
+            id: bug.id,
+            title: bug.title,
+            product: bug.product,
+            status: bug.status,
+            pri: bug.pri,
+            severity: bug.severity,
+            assignedTo: bug.assignedTo,
+            openedBy: bug.openedBy,
+            resolvedBy: bug.resolvedBy,
+            openedDate: bug.openedDate,
+          });
+        }
+      }
+    }
+
+    return normalizeResult({
+      account: matchAccount,
+      scope: targetScope,
+      total: totalMatches,
+      products: rows,
+      bugs: includeDetails ? bugs : [],
+    });
+  }
 }
 
 function createClient() {
@@ -206,7 +337,7 @@ function getClient() {
 const server = new Server(
   {
     name: "zentao-mcp",
-    version: "0.2.0",
+    version: "0.2.2",
   },
   {
     capabilities: {
@@ -218,7 +349,7 @@ const server = new Server(
 const tools = [
   {
     name: "zentao_products_list",
-    description: "List products (RESTful API).",
+    description: "List all products from ZenTao. Use this to get product IDs before querying bugs. Returns product information including ID, name, and bug counts.",
     inputSchema: {
       type: "object",
       properties: {
@@ -230,11 +361,11 @@ const tools = [
   },
   {
     name: "zentao_bugs_list",
-    description: "List bugs for a product (RESTful API).",
+    description: "List bugs (缺陷/问题) for a specific product in ZenTao. Use this when user asks to 'see bugs', 'view bugs', 'show bugs', '看bug', '查看bug', '显示bug', or wants to check issues for a product. Requires product ID which can be obtained from zentao_products_list.",
     inputSchema: {
       type: "object",
       properties: {
-        product: { type: "integer", description: "Product ID." },
+        product: { type: "integer", description: "Product ID (required). Get this from zentao_products_list first." },
         page: { type: "integer", description: "Page number (default 1)." },
         limit: { type: "integer", description: "Page size (default 20)." },
       },
@@ -244,16 +375,40 @@ const tools = [
   },
   {
     name: "zentao_bugs_stats",
-    description: "Aggregate bug totals across products.",
+    description: "Get bug statistics (bug统计) across all products. Shows total bugs, unresolved bugs, closed bugs, and fixed bugs per product. Use when user asks for bug summary, statistics, overview, or 'bug统计'.",
     inputSchema: {
       type: "object",
       properties: {
-        includeZero: { type: "boolean", description: "Include products with zero bugs." },
+        includeZero: { type: "boolean", description: "Include products with zero bugs (default false)." },
         limit: { type: "integer", description: "Max products to fetch (default 1000)." },
       },
       additionalProperties: false,
     },
   },
+  {
+    name: "zentao_bugs_mine",
+    description: "List my bugs (我的Bug) by assignment or creator. Default scope is assigned. Use when user asks for 'my bugs', '我的bug', '分配给我', or personal bug list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        account: { type: "string", description: "Account to match (default: login account)." },
+        scope: {
+          type: "string",
+          description: "Filter scope: assigned|opened|resolved|all (default assigned).",
+        },
+        productIds: {
+          type: "array",
+          items: { type: "integer" },
+          description: "Optional product IDs to limit search.",
+        },
+        includeZero: { type: "boolean", description: "Include products with zero matches (default false)." },
+        perPage: { type: "integer", description: "Page size when scanning products (default 100)." },
+        maxItems: { type: "integer", description: "Max bug items to return (default 200)." },
+        includeDetails: { type: "boolean", description: "Include bug details list (default false)." },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -273,6 +428,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "zentao_bugs_stats":
         result = await api.bugStats(args);
         break;
+      case "zentao_bugs_mine":
+        result = await api.bugsMine(args);
+        break;
       default:
         return {
           isError: true,