@aipper/zentao-mcp-server 0.1.6 → 0.1.7

package/.env.example

@@ -8,6 +8,9 @@ ZENTAO_PASSWORD=your_password
 # 可选：API 前缀（默认 /api.php/v1）
 # ZENTAO_API_PREFIX=/api.php/v1
 
+# 可选：默认产品 ID（当实例请求 bug 列表需要 product id 时使用）
+# ZENTAO_PRODUCT_ID=1
+
 # 获取 Token 的路径（相对 ZENTAO_BASE_URL；通常为 /api.php/v1/tokens）
 ZENTAO_TOKEN_PATH=/api.php/v1/tokens
 

package/README.md

@@ -16,6 +16,7 @@
 - `ZENTAO_BASE_URL`
 - `ZENTAO_ACCOUNT`
 - `ZENTAO_PASSWORD`
+- （可选）`ZENTAO_PRODUCT_ID`：你的禅道实例若报 `Need product id` 时设置
 
 > 注意：不同禅道版本/部署方式的 token 端点与返回结构可能不同；可通过 `ZENTAO_TOKEN_PATH`/`ZENTAO_API_PREFIX` 调整。
 >
@@ -86,6 +87,7 @@ npm run smoke
 ## 常见错误（`-32000`）
 `-32000` 通常是客户端侧“通用 MCP 调用失败”映射码，优先检查：
 - `env` 是否完整传入（尤其是 `ZENTAO_BASE_URL`/`ZENTAO_ACCOUNT`/`ZENTAO_PASSWORD`）。
+- 若报 `Need product id`，请设置 `ZENTAO_PRODUCT_ID`，或在 `get_my_bugs` 传 `productId`。
 - `ZENTAO_API_PREFIX`/`ZENTAO_TOKEN_PATH` 是否和你的禅道实例一致。
 - MCP 客户端是否真的在执行 `npx -y @aipper/zentao-mcp-server`（而不是旧的本地命令）。
 - 客户端日志中是否有启动报错（如找不到命令、401、超时）。
@@ -94,16 +96,17 @@ npm run smoke
 - `get_token`：获取/刷新 token（默认不回显完整 token）
 - `call`：调用任意相对 API 路径（自动带 Token 头）
 - `list_my_projects`：示例：列出“我参与的项目”（字段匹配基于常见返回结构，可能需按你的实例微调）
-- `get_my_bugs`：获取“指派给我”的 bug（支持 `status`/`keyword`/`limit`/`page`，默认路径 `/bugs`）
+- `get_my_bugs`：获取“指派给我”的 bug（支持 `status`/`keyword`/`limit`/`page`/`productId`，默认路径 `/bugs`）
 - `get_bug_detail`：按 `id` 获取 bug 详情（默认路径模板 `/bugs/{id}`，返回详情与图片链接）
 - `resolve_bug`：按 `id` 处理单个 bug 状态（默认 `resolution=fixed`）
-- `batch_resolve_my_bugs`：批量处理“我的 bug”（默认筛选 `status=active`）
+- `batch_resolve_my_bugs`：批量处理“我的 bug”（默认筛选 `status=active`，支持 `productId`）
 - `close_bug`：按 `id` 关闭 bug
 - `verify_bug`：验证结果处理（`pass`=关闭，`fail`=激活）
 
 示例参数：
 - `resolve_bug`：`{"id":123,"resolution":"fixed","comment":"已修复并自测"}`
 - `batch_resolve_my_bugs`：`{"status":"active","maxItems":20,"comment":"批量修复"}`
+- `get_my_bugs`（按产品）：`{"status":"active","productId":1,"limit":50}`
 - `close_bug`：`{"id":123,"comment":"验证通过，关闭"}`
 - `verify_bug`：`{"id":123,"result":"pass","comment":"验证通过"}`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/zentao-mcp-server",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "description": "A minimal MCP server for ZenTao (token + generic REST call + a few helper tools).",

package/src/index.js

@@ -48,6 +48,7 @@ function getConfigFromEnv() {
   const tokenTtlMs = Number(process.env.ZENTAO_TOKEN_TTL_MS || "3000000");
   const timeoutMs = Number(process.env.ZENTAO_HTTP_TIMEOUT_MS || "30000");
   const exposeToken = String(process.env.ZENTAO_EXPOSE_TOKEN || "false").toLowerCase() === "true";
+  const defaultProductId = Number(process.env.ZENTAO_PRODUCT_ID || "0") || null;
 
   const account = requireEnv("ZENTAO_ACCOUNT");
   const password = requireEnv("ZENTAO_PASSWORD");
@@ -59,6 +60,7 @@ function getConfigFromEnv() {
     tokenTtlMs,
     timeoutMs,
     exposeToken,
+    defaultProductId,
     auth: { account, password },
   };
 }
@@ -80,99 +82,114 @@ async function main() {
     const rawToolName = req.params?.name;
     const toolName = normalizeToolName(rawToolName);
     const args = req.params?.arguments || {};
-    assertToolArgs(toolName, args);
-
-    if (toolName === "get_token") {
-      const force = Boolean(args.force);
-      const result = await zentao.getToken({ force });
-      const output = config.exposeToken
-        ? result
-        : {
-            ...result,
-            token: result.token ? `${result.token.slice(0, 6)}…${result.token.slice(-4)}` : "",
-          };
-      return toMcpTextResult(JSON.stringify(output, null, 2));
-    }
-
-    if (toolName === "call") {
-      const { path, method, query, body } = args;
-      const resp = await zentao.call({ path, method, query, body });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
-    }
-
-    if (toolName === "list_my_projects") {
-      const resp = await zentao.listMyProjects({ keyword: args.keyword || "" });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
-    }
-
-    if (toolName === "get_my_bugs") {
-      const resp = await zentao.getMyBugs({
-        status: args.status || "",
-        keyword: args.keyword || "",
-        limit: args.limit,
-        page: args.page,
-        path: args.path || "/bugs",
-        assignedTo: args.assignedTo || "",
-      });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
-    }
-
-    if (toolName === "get_bug_detail") {
-      const resp = await zentao.getBugDetail({
-        id: args.id,
-        path: args.path || "/bugs/{id}",
-      });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
-    }
-
-    if (toolName === "resolve_bug") {
-      const resp = await zentao.resolveBug({
-        id: args.id,
-        resolution: args.resolution || "fixed",
-        comment: args.comment || "",
-        path: args.path || "/bugs/{id}/resolve",
-      });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
-    }
-
-    if (toolName === "batch_resolve_my_bugs") {
-      const resp = await zentao.batchResolveMyBugs({
-        status: args.status || "active",
-        keyword: args.keyword || "",
-        limit: args.limit,
-        page: args.page,
-        maxItems: args.maxItems,
-        assignedTo: args.assignedTo || "",
-        resolution: args.resolution || "fixed",
-        comment: args.comment || "",
-        listPath: args.listPath || "/bugs",
-        resolvePath: args.resolvePath || "/bugs/{id}/resolve",
-        stopOnError: Boolean(args.stopOnError),
-      });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
-    }
-
-    if (toolName === "close_bug") {
-      const resp = await zentao.closeBug({
-        id: args.id,
-        comment: args.comment || "",
-        path: args.path || "/bugs/{id}/close",
-      });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
-    }
 
-    if (toolName === "verify_bug") {
-      const resp = await zentao.verifyBug({
-        id: args.id,
-        result: args.result || "pass",
-        comment: args.comment || "",
-        closePath: args.closePath || "/bugs/{id}/close",
-        activatePath: args.activatePath || "/bugs/{id}/activate",
-      });
-      return toMcpTextResult(JSON.stringify(resp, null, 2));
+    try {
+      assertToolArgs(toolName, args);
+
+      if (toolName === "get_token") {
+        const force = Boolean(args.force);
+        const result = await zentao.getToken({ force });
+        const output = config.exposeToken
+          ? result
+          : {
+              ...result,
+              token: result.token ? `${result.token.slice(0, 6)}…${result.token.slice(-4)}` : "",
+            };
+        return toMcpTextResult(JSON.stringify(output, null, 2));
+      }
+
+      if (toolName === "call") {
+        const { path, method, query, body } = args;
+        const resp = await zentao.call({ path, method, query, body });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      if (toolName === "list_my_projects") {
+        const resp = await zentao.listMyProjects({ keyword: args.keyword || "" });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      if (toolName === "get_my_bugs") {
+        const resp = await zentao.getMyBugs({
+          status: args.status || "",
+          keyword: args.keyword || "",
+          limit: args.limit,
+          page: args.page,
+          productId: args.productId,
+          path: args.path || "/bugs",
+          assignedTo: args.assignedTo || "",
+        });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      if (toolName === "get_bug_detail") {
+        const resp = await zentao.getBugDetail({
+          id: args.id,
+          path: args.path || "/bugs/{id}",
+        });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      if (toolName === "resolve_bug") {
+        const resp = await zentao.resolveBug({
+          id: args.id,
+          resolution: args.resolution || "fixed",
+          comment: args.comment || "",
+          path: args.path || "/bugs/{id}/resolve",
+        });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      if (toolName === "batch_resolve_my_bugs") {
+        const resp = await zentao.batchResolveMyBugs({
+          status: args.status || "active",
+          keyword: args.keyword || "",
+          limit: args.limit,
+          page: args.page,
+          productId: args.productId,
+          maxItems: args.maxItems,
+          assignedTo: args.assignedTo || "",
+          resolution: args.resolution || "fixed",
+          comment: args.comment || "",
+          listPath: args.listPath || "/bugs",
+          resolvePath: args.resolvePath || "/bugs/{id}/resolve",
+          stopOnError: Boolean(args.stopOnError),
+        });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      if (toolName === "close_bug") {
+        const resp = await zentao.closeBug({
+          id: args.id,
+          comment: args.comment || "",
+          path: args.path || "/bugs/{id}/close",
+        });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      if (toolName === "verify_bug") {
+        const resp = await zentao.verifyBug({
+          id: args.id,
+          result: args.result || "pass",
+          comment: args.comment || "",
+          closePath: args.closePath || "/bugs/{id}/close",
+          activatePath: args.activatePath || "/bugs/{id}/activate",
+        });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
+      throw new Error(`Unknown tool: ${rawToolName}`);
+    } catch (err) {
+      const errorPayload = {
+        ok: false,
+        tool: rawToolName,
+        message: String(err?.message || err),
+        status: err?.status ?? null,
+        data: err?.data ?? null,
+        hint: "If you see 'Need product id', set env ZENTAO_PRODUCT_ID or pass productId in get_my_bugs.",
+      };
+      return toMcpTextResult(JSON.stringify(errorPayload, null, 2), { isError: true });
     }
-
-    throw new Error(`Unknown tool: ${rawToolName}`);
   });
 
   const transport = new StdioServerTransport();

package/src/tools.js

@@ -1,7 +1,10 @@
-export function toMcpTextResult(text) {
+export function toMcpTextResult(text, options = {}) {
+  const { isError = false } = options;
   return {
     content: [{ type: "text", text }],
     structuredContent: { output: text },
+    output: text,
+    ...(isError ? { isError: true } : {}),
   };
 }
 
@@ -49,6 +52,7 @@ export const TOOLS = [
         keyword: { type: "string", description: "Optional keyword in title/steps/severity/pri" },
         limit: { type: "number", minimum: 1, maximum: 200, description: "Default 20, max 200" },
         page: { type: "number", minimum: 1, description: "Default 1" },
+        productId: { type: "number", minimum: 1, description: "Optional product id (for instances requiring product scope)" },
         path: { type: "string", description: "Optional bugs endpoint override, default /bugs" },
         assignedTo: { type: "string", description: "Optional assignee override, default current account" },
       },
@@ -93,6 +97,7 @@ export const TOOLS = [
         keyword: { type: "string", description: "Optional keyword filter before resolve" },
         limit: { type: "number", minimum: 1, maximum: 200, description: "List page size, default 50" },
         page: { type: "number", minimum: 1, description: "Default 1" },
+        productId: { type: "number", minimum: 1, description: "Optional product id (for instances requiring product scope)" },
         maxItems: { type: "number", minimum: 1, maximum: 500, description: "Max resolve count, default 50" },
         assignedTo: { type: "string", description: "Optional assignee override" },
         resolution: { type: "string", description: "Default fixed" },
@@ -152,6 +157,9 @@ export function assertToolArgs(name, args) {
     if (args.path !== undefined && typeof args.path !== "string") {
       throw new Error("get_my_bugs.path must be a string");
     }
+    if (args.productId !== undefined && (!Number.isFinite(args.productId) || args.productId < 1)) {
+      throw new Error("get_my_bugs.productId must be a number >= 1");
+    }
   }
   if (name === "get_bug_detail") {
     if (!Number.isFinite(args.id) || Number(args.id) < 1) {
@@ -179,6 +187,9 @@ export function assertToolArgs(name, args) {
     if (args.maxItems !== undefined && (!Number.isFinite(args.maxItems) || args.maxItems < 1 || args.maxItems > 500)) {
       throw new Error("batch_resolve_my_bugs.maxItems must be a number between 1 and 500");
     }
+    if (args.productId !== undefined && (!Number.isFinite(args.productId) || args.productId < 1)) {
+      throw new Error("batch_resolve_my_bugs.productId must be a number >= 1");
+    }
     if (args.listPath !== undefined && typeof args.listPath !== "string") {
       throw new Error("batch_resolve_my_bugs.listPath must be a string");
     }

package/src/zentao.js

@@ -31,7 +31,7 @@ function createAbortSignal(timeoutMs) {
 }
 
 export function createZenTaoClient(config) {
-  const { baseUrl, apiPrefix, tokenPath, tokenTtlMs, timeoutMs, auth } = config;
+  const { baseUrl, apiPrefix, tokenPath, tokenTtlMs, timeoutMs, defaultProductId, auth } = config;
 
   let cachedToken = "";
   let cachedAt = 0;
@@ -174,6 +174,30 @@ export function createZenTaoClient(config) {
     return String(value || "").trim().toLowerCase();
   }
 
+  function normalizePositiveInt(value) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : null;
+  }
+
+  function buildProductScopedBugsPath({ productId, path }) {
+    const pid = normalizePositiveInt(productId);
+    if (!pid) return path || "/bugs";
+
+    const basePath = path || "/bugs";
+    if (basePath.includes("{productId}")) {
+      return basePath.replaceAll("{productId}", String(pid));
+    }
+    if (basePath === "/bugs") {
+      return `/products/${pid}/bugs`;
+    }
+    return basePath;
+  }
+
+  function isNeedProductIdError(err) {
+    const merged = `${String(err?.message || "")} ${JSON.stringify(err?.data || "")}`.toLowerCase();
+    return merged.includes("need product id");
+  }
+
   function getBugAssignee(bug) {
     return (
       bug?.assignedTo ||
@@ -275,19 +299,45 @@ export function createZenTaoClient(config) {
     return Array.from(images);
   }
 
-  async function getMyBugs({ status, keyword, limit = 20, page = 1, path = "/bugs", assignedTo } = {}) {
+  async function getMyBugs({
+    status,
+    keyword,
+    limit = 20,
+    page = 1,
+    productId,
+    path = "/bugs",
+    assignedTo,
+  } = {}) {
     const safeLimit = Math.max(1, Math.min(Number(limit) || 20, 200));
     const safePage = Math.max(1, Number(page) || 1);
     const assignee = normalizeString(assignedTo) || normalizeString(auth.account);
+    const effectiveProductId = normalizePositiveInt(productId) || normalizePositiveInt(defaultProductId);
+    const primaryPath = buildProductScopedBugsPath({ productId: effectiveProductId, path });
 
     const query = {
       limit: safeLimit,
       page: safePage,
       assignedTo: assignee || undefined,
       status: status || undefined,
+      product: effectiveProductId || undefined,
     };
-    const resp = await call({ path, method: "GET", query });
-    const bugs = parseBugsFromResponse(resp.data);
+    let resp;
+    try {
+      resp = await call({ path: primaryPath, method: "GET", query });
+    } catch (err) {
+      const fallbackPath = effectiveProductId ? `/products/${effectiveProductId}/bugs` : null;
+      if (
+        fallbackPath &&
+        primaryPath !== fallbackPath &&
+        isNeedProductIdError(err)
+      ) {
+        resp = await call({ path: fallbackPath, method: "GET", query: { limit: safeLimit, page: safePage } });
+      } else {
+        throw err;
+      }
+    }
+
+    const bugs = parseBugsFromResponse(resp?.data);
     const filtered = bugs.filter((bug) => matchesBugFilters(bug, { status, keyword, assignee }));
 
     return {
@@ -295,9 +345,10 @@ export function createZenTaoClient(config) {
       matched: filtered.length,
       page: safePage,
       limit: safeLimit,
+      productId: effectiveProductId,
       assignedTo: assignee,
       bugs: filtered,
-      raw: { status: resp.status },
+      raw: { status: resp?.status, path: primaryPath },
     };
   }
 
@@ -421,6 +472,7 @@ export function createZenTaoClient(config) {
     keyword = "",
     limit = 50,
     page = 1,
+    productId,
     maxItems = 50,
     assignedTo = "",
     resolution = "fixed",
@@ -435,6 +487,7 @@ export function createZenTaoClient(config) {
       keyword,
       limit,
       page,
+      productId,
       path: listPath,
       assignedTo,
     });