@aipper/zentao-mcp-server 0.1.10 → 0.1.12

package/.env.example

@@ -1,5 +1,5 @@
 # 禅道基础地址（不要带末尾 /）
-ZENTAO_BASE_URL=http://zentao.example.com
+ZENTAO_BASE_URL=https://zentao.example.com
 
 # 必填：账号密码（MCP 启动后自动获取并缓存 Token）
 ZENTAO_ACCOUNT=your_account
@@ -32,8 +32,8 @@ ZENTAO_TOKEN_TTL_MS=3000000
 # 可选：超时（毫秒）
 ZENTAO_HTTP_TIMEOUT_MS=30000
 
-# 可选：是否在 get_token 工具里回显完整 token（默认 false）
-ZENTAO_EXPOSE_TOKEN=false
+# 可选：仅在临时调试老旧内网实例时允许 HTTP（强烈不推荐）
+# ZENTAO_ALLOW_INSECURE_HTTP=true
 
 # 可选：启用调试日志（输出到 stderr）
 # ZENTAO_DEBUG=true

package/README.md

@@ -2,11 +2,12 @@
 
 ## 目标
 - 提供一个可运行的 MCP Server（stdio），连接你的禅道 RESTful API v1。
-- 最小功能：自动获取/缓存 Token + 通用 `call` 工具 + 少量便捷工具示例。
+- 最小功能：自动获取/缓存 Token + 常用 bug 工具。
 
 ## 非目标
 - 不在仓库内存任何密钥/Token。
-- 不保证覆盖你禅道的全部 API；优先把“通用 call”跑通，再按你的流程补工具。
+- 不暴露无边界的通用 REST 写接口。
+- 不保证覆盖你禅道的全部 API；优先支持高频 bug 流程，再按你的流程补工具。
 
 ## 依赖
 - Node.js 18+（需要内置 `fetch`）
@@ -28,6 +29,8 @@ MIT - 详见 [LICENSE](./LICENSE) 文件
 > 注意：不同禅道版本/部署方式的 token 端点与返回结构可能不同；可通过 `ZENTAO_TOKEN_PATH`/`ZENTAO_API_PREFIX` 调整。
 >
 > 默认情况下不需要配置 `ZENTAO_API_PREFIX`（默认值是 `/api.php/v1`）。
+>
+> 安全约束：`ZENTAO_API_PREFIX` / `ZENTAO_TOKEN_PATH` 只支持相对路径；默认要求 `ZENTAO_BASE_URL` 使用 HTTPS。`ZENTAO_BASE_URL` 可为根路径或子目录部署地址（如 `https://zentao.example.com/zentao`）。
 
 ## 安装与运行
 ```bash
@@ -94,42 +97,51 @@ npm run smoke
 ## 常见错误（`-32000`）
 `-32000` 通常是客户端侧“通用 MCP 调用失败”映射码，优先检查：
 - `env` 是否完整传入（尤其是 `ZENTAO_BASE_URL`/`ZENTAO_ACCOUNT`/`ZENTAO_PASSWORD`）。
+- 默认要求 HTTPS；如果你的实例只能走 HTTP，必须显式设置 `ZENTAO_ALLOW_INSECURE_HTTP=true`，且只建议临时内网调试使用。
 - 若报 `Need product id`，请设置 `ZENTAO_PRODUCT_ID`，或在 `get_my_bugs` 传 `productId`。
 - 若你的 bug 在“项目集/我的视角”而非产品，建议设置 `ZENTAO_PROJECT_SET_ID`，并配置 `ZENTAO_MY_BUGS_PATH=/my/bug`。
+- 项目集场景下，优先直接调用 `get_my_bugs` 并传 `projectSetId`，必要时再显式传 `path="/my/bug"`；不要先依赖 `list_my_projects` 找项目。
+- 有些项目集本身没有创建实际项目，但仍然存在“我的 bug”；这类数据可能不会出现在 `list_my_projects` 结果里。
 - `get_my_bugs` 会按候选路径回退（包含项目集路径）；即使首个路径返回空列表也会继续尝试，并会把多端点结果合并去重。
+- `get_my_bugs.total` 表示最终“我的 bug”总数；若需排查底层一共扫描了多少条，可看 `raw.scannedTotal`。
 - 排查时看工具返回里的 `raw.triedPaths` / `raw.paths`，可确认每条路径的返回码与命中数量。
-- `ZENTAO_API_PREFIX`/`ZENTAO_TOKEN_PATH` 是否和你的禅道实例一致。
+- `ZENTAO_API_PREFIX`/`ZENTAO_TOKEN_PATH` 是否和你的禅道实例一致，且使用相对路径。
 - MCP 客户端是否真的在执行 `npx -y @aipper/zentao-mcp-server`（而不是旧的本地命令）。
 - 客户端日志中是否有启动报错（如找不到命令、401、超时）。
 
 ## 已实现工具
-- `get_token`：获取/刷新 token（默认不回显完整 token）
-- `call`：调用任意相对 API 路径（自动带 Token 头）
-- `list_my_projects`：示例：列出“我参与的项目”（字段匹配基于常见返回结构，可能需按你的实例微调）
-- `get_my_bugs`：获取“指派给我”的 bug（支持 `status`/`keyword`/`limit`/`page`/`productId`/`projectSetId`，默认路径 `/bugs`）
-- `get_bug_detail`：按 `id` 获取 bug 详情（默认路径模板 `/bugs/{id}`，返回详情与图片链接；会提取富文本 `<img>`、Markdown 图片、附件图片并归一化为可访问 URL）
+- `get_token`：获取/刷新 token（始终只回显脱敏后的 token 摘要）
+- `list_my_projects`：示例：列出“我参与的项目”（字段匹配基于常见返回结构，可能需按你的实例微调；不适合作为项目集 bug 的唯一发现入口）
+- `get_my_bugs`：获取“指派给我”的 bug（支持 `status`/`keyword`/`limit`/`page`/`productId`/`projectSetId`，默认路径 `/bugs`；`path` 仅允许 `/bugs`、`/my/bug`、`/my/bugs`）
+- `get_bug_detail`：按 `id` 获取 bug 详情（固定读取 `/bugs/{id}`；返回安全裁剪后的 bug 摘要与同源图片链接，不直接透传外部图片地址或原始附件外链）
 - `resolve_bug`：按 `id` 处理单个 bug 状态（默认 `resolution=fixed`，支持 `solution` 解决说明）
-- `batch_resolve_my_bugs`：批量处理“我的 bug”（默认筛选 `status=active`，支持 `productId`/`projectSetId`）
+- `batch_resolve_my_bugs`：批量处理“我的 bug”（默认筛选 `status=active`，支持 `productId`/`projectSetId`，默认遇错即停，`maxItems` 上限 100）
 - `close_bug`：按 `id` 关闭 bug
 - `verify_bug`：验证结果处理（`pass`=关闭，`fail`=激活）
-- `comment_bug`：按 `id` 添加备注（默认路径 `/bugs/{id}/comment`）
+- `comment_bug`：按 `id` 添加备注
 
 示例参数：
-- `resolve_bug`：`{"id":123,"resolution":"fixed","comment":"已修复并自测"}`
-- `resolve_bug`（建议）：`{"id":123,"resolution":"fixed","solution":"修复空指针并补充参数校验"}`
-- `batch_resolve_my_bugs`：`{"status":"active","maxItems":20,"comment":"批量修复"}`
-- `batch_resolve_my_bugs`（建议）：`{"status":"active","maxItems":20,"solution":"统一修复分页参数为空导致的报错"}`
-- `get_my_bugs`（按产品）：`{"status":"active","productId":1,"limit":50}`
+- `resolve_bug`：`{"id":123,"resolution":"fixed","comment":"根因已定位，已按最新字段映射调整处理逻辑"}`
+- `resolve_bug`（建议）：`{"id":123,"resolution":"fixed","solution":"补齐分页参数为空时的默认值分支，避免空值继续进入查询构造；同时收敛异常提示，防止前端重复触发提交"}`
+- `batch_resolve_my_bugs`：`{"status":"active","maxItems":20,"comment":"统一补充非空校验并收敛异常分支"}`
+- `batch_resolve_my_bugs`（建议）：`{"status":"active","maxItems":20,"solution":"统一修正状态切换时的判空与分支顺序，避免旧数据触发空指针；保存前增加兜底校验，异常场景改为明确提示"}`
 - `get_my_bugs`（项目集）：`{"status":"active","projectSetId":1001,"limit":50}`
 - `get_my_bugs`（我的）：`{"status":"active","path":"/my/bug","limit":50}`
+- `get_my_bugs`（项目集 + 我的）：`{"status":"active","projectSetId":1001,"path":"/my/bug","limit":50}`
+- `get_my_bugs`（按产品）：`{"status":"active","productId":1,"limit":50}`
 - `close_bug`：`{"id":123,"comment":"验证通过，关闭"}`
 - `verify_bug`：`{"id":123,"result":"pass","comment":"验证通过"}`
 - `comment_bug`：`{"id":123,"comment":"已复现，正在定位根因"}`
 
+`solution` / `comment` 建议直接写“根因 + 修复思路 + 改动逻辑 + 影响范围”，不要默认写 `Evidence:`、`Verify:`、文件路径、编译命令或“已修复并自测”这类无法说明改动内容的表述。
+
+使用建议：如果用户提到“项目集”“我的 bug”“项目列表里找不到但禅道里能看到 bug”，优先走项目集视角的 `get_my_bugs`，不要先让用户证明项目已创建。
+
 ## 安全建议
-- **强烈建议使用 HTTPS**：HTTP 会明文传输账号密码和数据，存在安全风险。
+- **默认要求使用 HTTPS**：HTTP 会明文传输账号密码和数据，存在安全风险；如确需兼容老旧实例，需显式设置 `ZENTAO_ALLOW_INSECURE_HTTP=true`。
 - 使用最小权限账号（仅需要的项目权限），避免使用管理员账号。
-- 默认 `get_token` 不回显完整 token；如确需调试，可设 `ZENTAO_EXPOSE_TOKEN=true`。
+- `get_token` 不再支持回显完整 token。
+- 调试日志会自动脱敏 `query`、`body`、`comment`、`solution` 等敏感字段，但仍建议仅在排查问题时临时开启。
 
 ## 调试
 如需查看详细日志，可设置环境变量：

package/package.json

@@ -1,14 +1,23 @@
 {
   "name": "@aipper/zentao-mcp-server",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "private": false,
   "type": "module",
-  "description": "A minimal MCP server for ZenTao (token + generic REST call + a few helper tools).",
+  "description": "A minimal MCP server for ZenTao (token + focused bug workflow tools).",
   "license": "MIT",
   "main": "src/index.js",
   "bin": {
     "zentao-mcp-server": "bin/zentao-mcp-server.js"
   },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/smoke.mjs",
+    ".env.example",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=18.0.0"
   },

package/scripts/smoke.mjs

@@ -12,11 +12,12 @@ function getConfigFromEnv() {
   const tokenPath = process.env.ZENTAO_TOKEN_PATH || `${apiPrefix}/tokens`;
   const tokenTtlMs = Number(process.env.ZENTAO_TOKEN_TTL_MS || "3000000");
   const timeoutMs = Number(process.env.ZENTAO_HTTP_TIMEOUT_MS || "30000");
+  const allowInsecureHttp = String(process.env.ZENTAO_ALLOW_INSECURE_HTTP || "false").toLowerCase() === "true";
 
   const account = requireEnv("ZENTAO_ACCOUNT");
   const password = requireEnv("ZENTAO_PASSWORD");
 
-  return { baseUrl, apiPrefix, tokenPath, tokenTtlMs, timeoutMs, auth: { account, password } };
+  return { baseUrl, apiPrefix, tokenPath, tokenTtlMs, timeoutMs, allowInsecureHttp, auth: { account, password } };
 }
 
 async function main() {

package/src/index.js

@@ -15,6 +15,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"));
 
 const DEBUG = process.env.ZENTAO_DEBUG === "true";
+const ALLOW_INSECURE_HTTP = String(process.env.ZENTAO_ALLOW_INSECURE_HTTP || "false").toLowerCase() === "true";
 
 function log(...args) {
   if (DEBUG) {
@@ -22,9 +23,26 @@ function log(...args) {
   }
 }
 
+function sanitizeToolArgs(toolName, args) {
+  if (!args || typeof args !== "object") return {};
+  const redactedKeys = new Set(["body", "query", "comment", "solution", "password", "token"]);
+  const sanitized = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (redactedKeys.has(key)) {
+      sanitized[key] = "<redacted>";
+      continue;
+    }
+    if (toolName === "get_token" && key === "force") {
+      sanitized[key] = Boolean(value);
+      continue;
+    }
+    sanitized[key] = value;
+  }
+  return sanitized;
+}
+
 const KNOWN_TOOL_NAMES = new Set([
   "get_token",
-  "call",
   "list_my_projects",
   "get_my_bugs",
   "get_bug_detail",
@@ -37,29 +55,20 @@ const KNOWN_TOOL_NAMES = new Set([
 
 function normalizeToolName(rawName) {
   if (!rawName || typeof rawName !== "string") return rawName;
-  if (KNOWN_TOOL_NAMES.has(rawName)) return rawName;
-
-  if (rawName.includes("_")) {
-    const withoutPrefix = rawName.replace(/^[^_]+_/, "");
-    if (KNOWN_TOOL_NAMES.has(withoutPrefix)) return withoutPrefix;
-  }
-
-  for (const name of KNOWN_TOOL_NAMES) {
-    if (rawName.endsWith(name)) return name;
-  }
-  return rawName;
+  return KNOWN_TOOL_NAMES.has(rawName) ? rawName : rawName;
 }
 
 function requireEnv(name) {
   const value = process.env[name];
   if (!value) throw new Error(`Missing required env: ${name}`);
 
-  // Security check: warn if using HTTP instead of HTTPS
   if (name === "ZENTAO_BASE_URL" && value.startsWith("http://")) {
-    process.stderr.write(
-      "⚠️  WARNING: Using HTTP instead of HTTPS is insecure! " +
-      "Your credentials and data will be transmitted in plain text.\n"
-    );
+    if (!ALLOW_INSECURE_HTTP) {
+      throw new Error("ZENTAO_BASE_URL must use HTTPS unless ZENTAO_ALLOW_INSECURE_HTTP=true");
+    }
+  }
+  if (name === "ZENTAO_BASE_URL" && !/^https?:\/\//i.test(value)) {
+    throw new Error("ZENTAO_BASE_URL must start with http:// or https://");
   }
 
   return value;
@@ -71,7 +80,6 @@ function getConfigFromEnv() {
   const tokenPath = process.env.ZENTAO_TOKEN_PATH || `${apiPrefix}/tokens`;
   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 defaultProjectSetId = Number(process.env.ZENTAO_PROJECT_SET_ID || "0") || null;
   const myBugsPath = String(process.env.ZENTAO_MY_BUGS_PATH || "").trim();
@@ -93,7 +101,7 @@ function getConfigFromEnv() {
     tokenPath,
     tokenTtlMs,
     timeoutMs,
-    exposeToken,
+    allowInsecureHttp: ALLOW_INSECURE_HTTP,
     defaultProductId,
     defaultProjectSetId,
     myBugsPath,
@@ -107,13 +115,7 @@ async function main() {
   log("Starting zentao-mcp-server version", pkg.version);
 
   const config = getConfigFromEnv();
-  log("Config loaded:", {
-    baseUrl: config.baseUrl,
-    apiPrefix: config.apiPrefix,
-    account: config.auth.account,
-    productId: config.defaultProductId,
-    projectSetId: config.defaultProjectSetId,
-  });
+  log("Config loaded");
 
   const zentao = createZenTaoClient(config);
 
@@ -133,7 +135,7 @@ async function main() {
     const toolName = normalizeToolName(rawToolName);
     const args = req.params?.arguments || {};
 
-    log(`Tool call: ${toolName}`, JSON.stringify(args));
+    log(`Tool call: ${toolName}`, JSON.stringify(sanitizeToolArgs(toolName, args)));
 
     try {
       assertToolArgs(toolName, args);
@@ -141,21 +143,13 @@ async function main() {
       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)}` : "",
-            };
+        const output = {
+          ...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));
@@ -170,7 +164,6 @@ async function main() {
           productId: args.productId,
           projectSetId: args.projectSetId,
           path: args.path || "/bugs",
-          assignedTo: args.assignedTo || "",
         });
         return toMcpTextResult(JSON.stringify(resp, null, 2));
       }
@@ -178,7 +171,6 @@ async function main() {
       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));
       }
@@ -189,7 +181,6 @@ async function main() {
           resolution: args.resolution || "fixed",
           solution: args.solution || "",
           comment: args.comment || "",
-          path: args.path || "/bugs/{id}/resolve",
         });
         return toMcpTextResult(JSON.stringify(resp, null, 2));
       }
@@ -203,13 +194,11 @@ async function main() {
           productId: args.productId,
           projectSetId: args.projectSetId,
           maxItems: args.maxItems,
-          assignedTo: args.assignedTo || "",
           resolution: args.resolution || "fixed",
           solution: args.solution || "",
           comment: args.comment || "",
-          listPath: args.listPath || "/bugs",
-          resolvePath: args.resolvePath || "/bugs/{id}/resolve",
-          stopOnError: Boolean(args.stopOnError),
+          path: args.path || "/bugs",
+          stopOnError: args.stopOnError !== undefined ? Boolean(args.stopOnError) : true,
         });
         return toMcpTextResult(JSON.stringify(resp, null, 2));
       }
@@ -218,7 +207,6 @@ async function main() {
         const resp = await zentao.closeBug({
           id: args.id,
           comment: args.comment || "",
-          path: args.path || "/bugs/{id}/close",
         });
         return toMcpTextResult(JSON.stringify(resp, null, 2));
       }
@@ -228,8 +216,6 @@ async function main() {
           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));
       }
@@ -238,7 +224,6 @@ async function main() {
         const resp = await zentao.commentBug({
           id: args.id,
           comment: args.comment || "",
-          path: args.path || "/bugs/{id}/comment",
         });
         return toMcpTextResult(JSON.stringify(resp, null, 2));
       }
@@ -252,9 +237,8 @@ async function main() {
         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.",
-        hint2: "For project-set instances, set ZENTAO_PROJECT_SET_ID or ZENTAO_MY_BUGS_PATH.",
+        hint2: "For project-set instances, prefer get_my_bugs with projectSetId or ZENTAO_MY_BUGS_PATH=/my/bug; list_my_projects may miss project sets without concrete projects.",
       };
       return toMcpTextResult(JSON.stringify(errorPayload, null, 2), { isError: true });
     }