@aipper/zentao-mcp-server 0.1.4

package/.env.example

@@ -0,0 +1,21 @@
+# 禅道基础地址（不要带末尾 /）
+ZENTAO_BASE_URL=http://zentao.example.com
+
+# 必填：账号密码（MCP 启动后自动获取并缓存 Token）
+ZENTAO_ACCOUNT=your_account
+ZENTAO_PASSWORD=your_password
+
+# API 前缀（多数禅道为 /api.php/v1）
+ZENTAO_API_PREFIX=/api.php/v1
+
+# 获取 Token 的路径（相对 ZENTAO_BASE_URL；通常为 /api.php/v1/tokens）
+ZENTAO_TOKEN_PATH=/api.php/v1/tokens
+
+# Token 缓存时间（毫秒）。不知道服务端过期时间时，先保守设置 30~50 分钟
+ZENTAO_TOKEN_TTL_MS=3000000
+
+# 可选：超时（毫秒）
+ZENTAO_HTTP_TIMEOUT_MS=30000
+
+# 可选：是否在 get_token 工具里回显完整 token（默认 false）
+ZENTAO_EXPOSE_TOKEN=false

package/README.md

@@ -0,0 +1,92 @@
+# zentao-mcp-server（自建）
+
+## 目标
+- 提供一个可运行的 MCP Server（stdio），连接你的禅道 RESTful API v1。
+- 最小功能：自动获取/缓存 Token + 通用 `call` 工具 + 少量便捷工具示例。
+
+## 非目标
+- 不在仓库内存任何密钥/Token。
+- 不保证覆盖你禅道的全部 API；优先把“通用 call”跑通，再按你的流程补工具。
+
+## 依赖
+- Node.js 18+（需要内置 `fetch`）
+
+## 配置
+复制 `.env.example` 为 `.env` 并填写：
+- `ZENTAO_BASE_URL`
+- `ZENTAO_ACCOUNT`
+- `ZENTAO_PASSWORD`
+
+> 注意：不同禅道版本/部署方式的 token 端点与返回结构可能不同；可通过 `ZENTAO_TOKEN_PATH`/`ZENTAO_API_PREFIX` 调整。
+
+## 安装与运行
+```bash
+npm i
+cp .env.example .env
+npm start
+```
+
+## 验证（不依赖 MCP 客户端）
+```bash
+npm i
+cp .env.example .env
+set -a; source .env; set +a
+npm run smoke
+```
+期望结果：
+- 输出一行 `token: xxxx…yyyy source: ...`
+- 输出 `GET /projects status: 200`（或你的禅道实际返回码）
+
+## Claude Desktop / Cursor 示例（stdio）
+把启动命令指向 `node src/index.js`（或 `npm start`）。
+
+示例（Claude Desktop 的 `mcpServers` 风格，按你的客户端实际字段为准）：
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "node",
+      "args": ["src/index.js"],
+      "cwd": "/ABS/PATH/TO/zentao",
+      "env": {
+        "ZENTAO_BASE_URL": "https://zentao.example.com",
+        "ZENTAO_API_PREFIX": "/api.php/v1",
+        "ZENTAO_ACCOUNT": "your_account",
+        "ZENTAO_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+## 已实现工具
+- `get_token`：获取/刷新 token（默认不回显完整 token）
+- `call`：调用任意相对 API 路径（自动带 Token 头）
+- `list_my_projects`：示例：列出“我参与的项目”（字段匹配基于常见返回结构，可能需按你的实例微调）
+
+## 安全建议
+- 使用最小权限账号（仅需要的项目权限），避免使用管理员账号。
+- 默认 `get_token` 不回显完整 token；如确需调试，可设 `ZENTAO_EXPOSE_TOKEN=true`。
+
+## 发布到 npm
+脚本：`scripts/release-npm.sh`（参考 `aiws` 的发布流程，默认 dry-run）。
+
+常用命令：
+```bash
+# dry-run：只检查 + npm pack --dry-run，不会发布
+npm run release:npm
+
+# 自动递增版本（patch/minor/major）+ commit + tag（不发布）
+npm run release:npm -- --bump patch
+
+# 发布（会二次确认；默认自动 patch 递增）
+npm run release:npm -- --publish
+
+# 版本对齐 + commit + tag（不发布）
+npm run release:npm -- --release v0.1.0
+```
+
+注意：
+- 若 `package.json` 为 `private: true`，发布前请改成 `false` 并确认包名可用。
+- 可加 `--require-tag` 要求 HEAD 上有匹配版本的 tag。
+- 若发布时报 `403`，通常是包名归属问题；建议改为 scoped 包名（如 `@yourname/zentao-mcp-server`）。

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@aipper/zentao-mcp-server",
+  "version": "0.1.4",
+  "private": false,
+  "type": "module",
+  "description": "A minimal MCP server for ZenTao (token + generic REST call + a few helper tools).",
+  "license": "UNLICENSED",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js",
+    "lint": "node -c src/index.js && node -c src/zentao.js && node -c src/tools.js && node -c scripts/smoke.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "release:npm": "bash scripts/release-npm.sh"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest"
+  }
+}

package/scripts/release-npm.sh

@@ -0,0 +1,481 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+release-npm.sh (zentao-mcp-server)
+
+Default mode is dry-run: run checks + npm pack --dry-run, no npm publish.
+
+Usage:
+  bash scripts/release-npm.sh
+  bash scripts/release-npm.sh --publish
+
+Options:
+  --release <tag>        Set package version from tag (vX.Y.Z), then commit + tag
+  --bump <level>         Auto bump version: patch | minor | major, then commit + tag
+  --publish              Run npm publish after checks (defaults to --bump patch)
+  --yes                  Skip interactive confirmation
+  --require-tag          Require a semver git tag on HEAD matching package version
+  --skip-secrets-scan    Skip ripgrep-based secrets scan
+  --skip-whoami          Skip npm whoami check
+  --no-git-clean-check   Skip clean-worktree check (not recommended)
+  -h, --help             Show help
+
+Environment:
+  ZENTAO_NPM_CACHE_DIR   Override npm cache dir used by this script
+EOF
+}
+
+PUBLISH=0
+YES=0
+REQUIRE_TAG=0
+RELEASE_TAG=""
+BUMP_LEVEL=""
+SKIP_SECRETS_SCAN=0
+SKIP_WHOAMI=0
+SKIP_GIT_CLEAN_CHECK=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --release)
+      shift
+      if [[ $# -lt 1 ]]; then
+        echo "error: --release requires <tag> (e.g. v0.1.0)" >&2
+        usage
+        exit 2
+      fi
+      RELEASE_TAG="$1"
+      ;;
+    --bump)
+      shift
+      if [[ $# -lt 1 ]]; then
+        echo "error: --bump requires <level> (patch|minor|major)" >&2
+        usage
+        exit 2
+      fi
+      BUMP_LEVEL="$1"
+      ;;
+    --publish) PUBLISH=1 ;;
+    --yes) YES=1 ;;
+    --require-tag) REQUIRE_TAG=1 ;;
+    --skip-secrets-scan) SKIP_SECRETS_SCAN=1 ;;
+    --skip-whoami) SKIP_WHOAMI=1 ;;
+    --no-git-clean-check) SKIP_GIT_CLEAN_CHECK=1 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "error: unknown arg: $1" >&2; usage; exit 2 ;;
+  esac
+  shift
+done
+
+log() { echo "info: $*"; }
+warn() { echo "warn: $*" >&2; }
+die() { echo "error: $*" >&2; exit 2; }
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repo_root"
+
+command -v node >/dev/null 2>&1 || die "node is required"
+command -v npm >/dev/null 2>&1 || die "npm is required"
+
+DEFAULT_NPM_CACHE_DIR="${ZENTAO_NPM_CACHE_DIR:-/tmp/zentao-npm-cache}"
+
+maybe_use_safe_npm_cache() {
+  if [[ -z "${npm_config_cache:-}" && -z "${NPM_CONFIG_CACHE:-}" ]]; then
+    export npm_config_cache="$DEFAULT_NPM_CACHE_DIR"
+  fi
+  local cache_dir="${npm_config_cache:-${NPM_CONFIG_CACHE:-}}"
+  if [[ -n "${cache_dir:-}" ]]; then
+    mkdir -p "$cache_dir" 2>/dev/null || true
+    log "npm_cache=$cache_dir"
+  fi
+}
+
+maybe_use_safe_npm_cache
+
+pkg_name=""
+pkg_version=""
+pkg_private=""
+release_version=""
+release_tag_name=""
+release_tmpdir=""
+release_restore_on_exit=0
+
+cleanup_release() {
+  if [[ "${release_restore_on_exit:-0}" == "1" && -n "${release_tmpdir:-}" ]]; then
+    cp "$release_tmpdir/package.json" package.json 2>/dev/null || true
+  fi
+  if [[ -n "${release_tmpdir:-}" ]]; then
+    rm -rf "$release_tmpdir" 2>/dev/null || true
+  fi
+}
+trap cleanup_release EXIT
+
+is_semver() {
+  printf '%s' "$1" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([-.+].+)?$'
+}
+
+normalize_release_tag() {
+  local input="$1"
+  if [[ "$input" == v* ]]; then
+    release_tag_name="$input"
+    release_version="${input#v}"
+  else
+    release_tag_name="v$input"
+    release_version="$input"
+  fi
+  if ! is_semver "$release_version"; then
+    die "--release requires semver tag (vX.Y.Z); got: $input"
+  fi
+}
+
+calc_bumped_version() {
+  local current="$1"
+  local level="$2"
+  ZENTAO_CURRENT_VERSION="$current" ZENTAO_BUMP_LEVEL="$level" node - <<'NODE'
+const current = process.env.ZENTAO_CURRENT_VERSION || "";
+const level = process.env.ZENTAO_BUMP_LEVEL || "";
+const m = current.match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+if (!m) {
+  console.error(`error: current version is not semver-like: ${current}`);
+  process.exit(2);
+}
+let major = Number(m[1]);
+let minor = Number(m[2]);
+let patch = Number(m[3]);
+if (level === "patch") {
+  patch += 1;
+} else if (level === "minor") {
+  minor += 1;
+  patch = 0;
+} else if (level === "major") {
+  major += 1;
+  minor = 0;
+  patch = 0;
+} else {
+  console.error(`error: unsupported bump level: ${level} (expected patch|minor|major)`);
+  process.exit(2);
+}
+process.stdout.write(`${major}.${minor}.${patch}`);
+NODE
+}
+
+read_pkg() {
+  pkg_name="$(node -p "require('./package.json').name")"
+  pkg_version="$(node -p "require('./package.json').version")"
+  pkg_private="$(node -p "Boolean(require('./package.json').private)")"
+}
+
+write_version() {
+  local v="$1"
+  ZENTAO_RELEASE_VERSION="$v" node - <<'NODE'
+const fs = require("node:fs");
+const file = "package.json";
+const v = process.env.ZENTAO_RELEASE_VERSION;
+if (!v) {
+  console.error("missing ZENTAO_RELEASE_VERSION");
+  process.exit(2);
+}
+const src = fs.readFileSync(file, "utf8");
+const pkg = JSON.parse(src);
+pkg.version = v;
+fs.writeFileSync(file, JSON.stringify(pkg, null, 2) + "\n");
+NODE
+}
+
+backup_package_for_restore() {
+  release_tmpdir="$(mktemp -d)"
+  cp package.json "$release_tmpdir/package.json"
+  release_restore_on_exit=1
+}
+
+check_publish_ownership() {
+  local npm_user="$1"
+  local package_name="$2"
+
+  local view_out=""
+  local view_code=0
+  set +e
+  view_out="$(npm view "$package_name" name 2>&1)"
+  view_code=$?
+  set -e
+
+  if [[ "$view_code" != "0" ]]; then
+    if echo "$view_out" | grep -Eqi "(E404|404|not found|not in this registry)"; then
+      log "publish ownership precheck: package not found on registry ($package_name), treated as first publish"
+      return 0
+    fi
+    warn "publish ownership precheck skipped: cannot query package metadata"
+    return 0
+  fi
+
+  local owners_out=""
+  local owners_code=0
+  set +e
+  owners_out="$(npm owner ls "$package_name" 2>&1)"
+  owners_code=$?
+  set -e
+
+  if [[ "$owners_code" != "0" ]]; then
+    warn "publish ownership precheck skipped: cannot query package owners"
+    return 0
+  fi
+
+  if echo "$owners_out" | grep -Eiq "^${npm_user}[[:space:]]"; then
+    log "publish ownership precheck: ok ($npm_user owns $package_name)"
+    return 0
+  fi
+
+  die "npm user '$npm_user' is not an owner of '$package_name' (likely 403). Use a scoped name like '@$npm_user/zentao-mcp-server' or ask current owner to add you."
+}
+
+read_pkg
+
+# Default behavior: publishing without explicit release/bump will auto-bump patch.
+if [[ "$PUBLISH" == "1" && -z "${RELEASE_TAG:-}" && -z "${BUMP_LEVEL:-}" ]]; then
+  BUMP_LEVEL="patch"
+  log "publish requested without version args; defaulting to --bump patch"
+fi
+
+log "repo_root=$repo_root"
+log "package=$pkg_name"
+log "version=$pkg_version"
+log "mode=$(
+  if [[ "$PUBLISH" == "1" ]]; then
+    echo publish
+  elif [[ -n "${RELEASE_TAG:-}" || -n "${BUMP_LEVEL:-}" ]]; then
+    echo prepare
+  else
+    echo dry-run
+  fi
+)"
+
+if [[ -n "${RELEASE_TAG:-}" && -n "${BUMP_LEVEL:-}" ]]; then
+  die "cannot combine --release and --bump"
+fi
+
+VERSION_UPDATE=0
+if [[ -n "${RELEASE_TAG:-}" ]]; then
+  normalize_release_tag "$RELEASE_TAG"
+  VERSION_UPDATE=1
+fi
+if [[ -n "${BUMP_LEVEL:-}" ]]; then
+  release_version="$(calc_bumped_version "$pkg_version" "$BUMP_LEVEL")"
+  release_tag_name="v$release_version"
+  VERSION_UPDATE=1
+  log "bump_level=$BUMP_LEVEL"
+fi
+
+if [[ "$VERSION_UPDATE" == "1" && "$REQUIRE_TAG" == "1" ]]; then
+  die "cannot combine --release/--bump with --require-tag (release flow creates a tag)"
+fi
+
+if [[ "$VERSION_UPDATE" == "1" ]]; then
+  command -v git >/dev/null 2>&1 || die "--release/--bump requires git"
+  log "release_tag=$release_tag_name"
+  log "release_version=$release_version"
+
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    die "--release requires running inside a git repository"
+  fi
+
+  if git rev-parse -q --verify "refs/tags/$release_tag_name" >/dev/null 2>&1; then
+    die "--release tag already exists: $release_tag_name"
+  fi
+
+  if [[ "$SKIP_GIT_CLEAN_CHECK" != "1" ]]; then
+    dirty="$(git status --porcelain || true)"
+    if [[ -n "${dirty:-}" ]]; then
+      die "--release requires a clean git working tree; commit or stash changes first"
+    fi
+  fi
+
+  backup_package_for_restore
+  write_version "$release_version"
+  read_pkg
+  log "(after release) version=$pkg_version"
+fi
+
+if [[ "$REQUIRE_TAG" == "1" ]]; then
+  if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    die "--require-tag requires running inside a git repository"
+  fi
+  git_tag="$(git describe --tags --exact-match 2>/dev/null || true)"
+  if [[ -z "${git_tag:-}" ]]; then
+    die "--require-tag expected a semver tag on HEAD (e.g. v$pkg_version); found none"
+  fi
+  tag_version="${git_tag#v}"
+  if ! is_semver "$tag_version"; then
+    die "--require-tag expected tag in vX.Y.Z (or X.Y.Z) form; got: $git_tag"
+  fi
+  if [[ "$tag_version" != "$pkg_version" ]]; then
+    die "--require-tag tag version mismatch: tag=$git_tag (=> $tag_version) but package version=$pkg_version"
+  fi
+  log "git_tag=$git_tag"
+fi
+
+if [[ "$PUBLISH" == "1" && "$pkg_version" == "0.0.0" ]]; then
+  die "refusing to publish version 0.0.0; bump version first"
+fi
+
+if [[ "$VERSION_UPDATE" != "1" ]]; then
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    if [[ "$SKIP_GIT_CLEAN_CHECK" != "1" ]]; then
+      dirty="$(git status --porcelain || true)"
+      if [[ -n "${dirty:-}" ]]; then
+        if [[ "$PUBLISH" == "1" ]]; then
+          die "git working tree is not clean; commit or stash changes before publishing"
+        fi
+        warn "git working tree is not clean (ok for dry-run):"
+        echo "$dirty" | sed -n '1,20p'
+        if [[ "$(echo "$dirty" | wc -l | tr -d ' ')" -gt 20 ]]; then
+          warn "(truncated)"
+        fi
+      fi
+    fi
+  else
+    warn "not a git repository; skip git clean check"
+  fi
+fi
+
+if [[ "$SKIP_SECRETS_SCAN" != "1" ]]; then
+  if command -v rg >/dev/null 2>&1; then
+    log "secrets scan (filenames only):"
+    secret_re='(_authToken\\s*=\\s*[^\\s#]{16,}|sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}|npm_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|AIzaSy[A-Za-z0-9_-]{35}|-----BEGIN [A-Z ]*PRIVATE KEY-----|Authorization:\\s*Bearer\\s+[^\\s<]{20,}|Bearer\\s+[A-Za-z0-9._-]{20,}|(api[_-]?key|token|password|secret)\\s*[:=]\\s*[\\x27\\\"][^\\x27\\\"<]{12,}[\\x27\\\"])'
+    matches="$(rg -i -l "$secret_re" . --glob '!node_modules/**' --glob '!.git/**' --glob '!dist/**' --glob '!.env' --glob '!.env.*' || true)"
+    if [[ -n "${matches:-}" ]]; then
+      if [[ "$PUBLISH" == "1" ]]; then
+        echo "$matches"
+        die "potential secret-like patterns found; inspect files above before publishing"
+      fi
+      warn "potential secret-like patterns found (dry-run continues):"
+      echo "$matches"
+    else
+      log "secrets scan: ok"
+    fi
+  else
+    warn "rg not found; skip secrets scan"
+  fi
+fi
+
+if [[ "$SKIP_WHOAMI" == "1" ]]; then
+  warn "npm whoami skipped (--skip-whoami)"
+else
+  set +e
+  whoami_out="$(npm whoami 2>&1)"
+  whoami_code=$?
+  set -e
+  if [[ "$whoami_code" == "0" ]]; then
+    npm_user="$(printf '%s' "$whoami_out" | tr -d '\r\n')"
+    log "npm whoami: ok ($npm_user)"
+  else
+    warn "npm whoami failed:"
+    echo "$whoami_out" >&2
+    if [[ "$PUBLISH" == "1" ]]; then
+      warn "continue publish flow despite whoami failure; final publish result will be authoritative"
+    fi
+  fi
+fi
+
+if [[ "$PUBLISH" == "1" ]]; then
+  if [[ "$SKIP_WHOAMI" == "1" ]]; then
+    warn "publish ownership precheck skipped because --skip-whoami is enabled"
+  else
+    if [[ -z "${npm_user:-}" ]]; then
+      warn "publish ownership precheck skipped: npm username unavailable"
+    else
+      check_publish_ownership "$npm_user" "$pkg_name"
+    fi
+  fi
+fi
+
+log "pack preview: npm pack --dry-run"
+pack_out=""
+set +e
+pack_out="$(npm pack --dry-run 2>&1)"
+pack_code=$?
+set -e
+if [[ "$pack_code" != "0" ]]; then
+  if echo "$pack_out" | grep -Eqi "(EPERM|EACCES)" && [[ "${npm_config_cache:-${NPM_CONFIG_CACHE:-}}" != "$DEFAULT_NPM_CACHE_DIR" ]]; then
+    warn "npm pack failed with EPERM/EACCES; retry with npm_config_cache=$DEFAULT_NPM_CACHE_DIR"
+    export npm_config_cache="$DEFAULT_NPM_CACHE_DIR"
+    mkdir -p "$DEFAULT_NPM_CACHE_DIR" 2>/dev/null || true
+    npm pack --dry-run >/dev/null
+  else
+    echo "$pack_out" >&2
+    exit "$pack_code"
+  fi
+fi
+log "pack preview: ok"
+
+publish_cmd=(npm publish)
+if [[ "$pkg_name" == @*/* ]]; then
+  publish_cmd=(npm publish --access public)
+fi
+log "publish command: ${publish_cmd[*]}"
+
+if [[ "$PUBLISH" != "1" ]]; then
+  if [[ "$VERSION_UPDATE" == "1" ]]; then
+    if [[ "$YES" != "1" ]]; then
+      echo ""
+      echo "About to prepare git release:"
+      echo "  - set version to $release_version"
+      echo "  - git commit: chore(release): $release_tag_name"
+      echo "  - git tag: $release_tag_name"
+      echo ""
+      read -r -p "Type 'release' to continue: " confirm_release
+      if [[ "${confirm_release:-}" != "release" ]]; then
+        die "aborted"
+      fi
+    fi
+    if ! git diff --quiet -- package.json; then
+      git add package.json
+      git commit -m "chore(release): $release_tag_name"
+    else
+      log "release: no version changes to commit"
+    fi
+    git tag "$release_tag_name"
+    log "release: created git tag $release_tag_name"
+    release_restore_on_exit=0
+    log "prepare complete (no npm publish performed)"
+    exit 0
+  fi
+  log "dry-run complete (no publish performed)"
+  exit 0
+fi
+
+if [[ "$pkg_private" == "true" ]]; then
+  die "package.json has private=true; set private=false before publishing"
+fi
+
+if [[ "$YES" != "1" ]]; then
+  echo ""
+  echo "About to publish to npm:"
+  echo "  - $pkg_name@$pkg_version"
+  if [[ "$VERSION_UPDATE" == "1" ]]; then
+    echo ""
+    echo "And prepare git release:"
+    echo "  - git commit: chore(release): $release_tag_name"
+    echo "  - git tag: $release_tag_name"
+  fi
+  echo ""
+  read -r -p "Type 'publish' to continue: " confirm_publish
+  if [[ "${confirm_publish:-}" != "publish" ]]; then
+    die "aborted"
+  fi
+fi
+
+if [[ "$VERSION_UPDATE" == "1" ]]; then
+  if ! git diff --quiet -- package.json; then
+    git add package.json
+    git commit -m "chore(release): $release_tag_name"
+  else
+    log "release: no version changes to commit"
+  fi
+  git tag "$release_tag_name"
+  log "release: created git tag $release_tag_name"
+  release_restore_on_exit=0
+fi
+
+"${publish_cmd[@]}"
+log "publish complete"

package/scripts/smoke.mjs

@@ -0,0 +1,37 @@
+import { createZenTaoClient } from "../src/zentao.js";
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required env: ${name}`);
+  return value;
+}
+
+function getConfigFromEnv() {
+  const baseUrl = requireEnv("ZENTAO_BASE_URL").replace(/\/+$/, "");
+  const apiPrefix = (process.env.ZENTAO_API_PREFIX || "/api.php/v1").replace(/\/+$/, "");
+  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 account = requireEnv("ZENTAO_ACCOUNT");
+  const password = requireEnv("ZENTAO_PASSWORD");
+
+  return { baseUrl, apiPrefix, tokenPath, tokenTtlMs, timeoutMs, auth: { account, password } };
+}
+
+async function main() {
+  const zentao = createZenTaoClient(getConfigFromEnv());
+
+  const token = await zentao.getToken({ force: false });
+  console.log("token:", token.token ? `${token.token.slice(0, 6)}…${token.token.slice(-4)}` : "", "source:", token.source);
+
+  // 尝试拉一个最常用的列表接口，验证 apiPrefix/path 是否正确
+  const projects = await zentao.call({ path: "/projects", method: "GET" });
+  console.log("GET /projects status:", projects.status);
+  console.log("projects keys:", projects.data && typeof projects.data === "object" ? Object.keys(projects.data) : typeof projects.data);
+}
+
+main().catch((err) => {
+  console.error(String(err?.stack || err));
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,91 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  TOOLS,
+  assertToolArgs,
+  toMcpTextResult,
+} from "./tools.js";
+import { createZenTaoClient } from "./zentao.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) throw new Error(`Missing required env: ${name}`);
+  return value;
+}
+
+function getConfigFromEnv() {
+  const baseUrl = requireEnv("ZENTAO_BASE_URL").replace(/\/+$/, "");
+  const apiPrefix = (process.env.ZENTAO_API_PREFIX || "/api.php/v1").replace(/\/+$/, "");
+  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 account = requireEnv("ZENTAO_ACCOUNT");
+  const password = requireEnv("ZENTAO_PASSWORD");
+
+  return {
+    baseUrl,
+    apiPrefix,
+    tokenPath,
+    tokenTtlMs,
+    timeoutMs,
+    exposeToken,
+    auth: { account, password },
+  };
+}
+
+async function main() {
+  const config = getConfigFromEnv();
+  const zentao = createZenTaoClient(config);
+
+  const server = new Server(
+    { name: "zentao-mcp-server", version: "0.1.0" },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const toolName = req.params?.name;
+    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));
+    }
+
+    throw new Error(`Unknown tool: ${toolName}`);
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  // stderr 方便客户端看到启动失败原因
+  process.stderr.write(String(err?.stack || err) + "\n");
+  process.exit(1);
+});

package/src/tools.js

@@ -0,0 +1,47 @@
+export function toMcpTextResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+export const TOOLS = [
+  {
+    name: "get_token",
+    description: "Get or refresh ZenTao API token (cached).",
+    inputSchema: {
+      type: "object",
+      properties: { force: { type: "boolean" } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "call",
+    description: "Call ZenTao REST API v1 path with Token header.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", minLength: 1, description: "API path, e.g. /projects or bugs/123" },
+        method: { type: "string", description: "GET/POST/PUT/DELETE..." },
+        query: { type: "object", additionalProperties: true },
+        body: {},
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "list_my_projects",
+    description: "List projects I participate in (heuristic filtering).",
+    inputSchema: {
+      type: "object",
+      properties: { keyword: { type: "string" } },
+      additionalProperties: false,
+    },
+  },
+];
+
+export function assertToolArgs(name, args) {
+  if (args == null) return;
+  if (typeof args !== "object") throw new Error(`Invalid arguments for ${name}: expected object`);
+  if (name === "call" && typeof args.path !== "string") {
+    throw new Error("call.path must be a string");
+  }
+}

package/src/zentao.js

@@ -0,0 +1,173 @@
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+function isProbablyAbsoluteUrl(value) {
+  return /^https?:\/\//i.test(value);
+}
+
+function buildUrl({ baseUrl, apiPrefix, path, query }) {
+  if (!path) throw new Error("path is required");
+  if (isProbablyAbsoluteUrl(path)) {
+    throw new Error("path must be relative (absolute URL is not allowed)");
+  }
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const prefix = apiPrefix.startsWith("/") ? apiPrefix : `/${apiPrefix}`;
+  const url = new URL(`${baseUrl}${prefix}${normalizedPath}`);
+
+  if (query && typeof query === "object") {
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null) continue;
+      url.searchParams.set(k, String(v));
+    }
+  }
+  return url;
+}
+
+function createAbortSignal(timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error("Request timeout")), timeoutMs);
+  return { signal: controller.signal, cleanup: () => clearTimeout(timer) };
+}
+
+export function createZenTaoClient(config) {
+  const { baseUrl, apiPrefix, tokenPath, tokenTtlMs, timeoutMs, auth } = config;
+
+  let cachedToken = "";
+  let cachedAt = 0;
+
+  async function fetchJson(url, { method, headers, body }) {
+    const { signal, cleanup } = createAbortSignal(timeoutMs);
+    try {
+      const resp = await fetch(url, { method, headers, body, signal });
+      const text = await resp.text();
+      const contentType = resp.headers.get("content-type") || "";
+      const data = contentType.includes("application/json") ? safeJsonParse(text) : text;
+      if (!resp.ok) {
+        const err = new Error(`Request failed ${resp.status}: ${truncate(String(text), 2000)}`);
+        err.status = resp.status;
+        err.data = data;
+        throw err;
+      }
+      return { status: resp.status, headers: Object.fromEntries(resp.headers.entries()), data };
+    } finally {
+      cleanup();
+    }
+  }
+
+  function safeJsonParse(text) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  function truncate(s, max) {
+    if (s.length <= max) return s;
+    return s.slice(0, max) + "...(truncated)";
+  }
+
+  function tokenExpired() {
+    if (!cachedToken) return true;
+    if (!cachedAt) return true;
+    return Date.now() - cachedAt > tokenTtlMs;
+  }
+
+  async function getToken({ force } = {}) {
+    if (!force && !tokenExpired()) {
+      return { token: cachedToken, source: "cache" };
+    }
+    if (!auth.account || !auth.password) {
+      throw new Error("Need ZENTAO_ACCOUNT and ZENTAO_PASSWORD");
+    }
+
+    // 兼容性：不同禅道版本 token 接口可能不同；先按常见 v1 约定尝试
+    const url = new URL(tokenPath, baseUrl);
+    const payload = { account: auth.account, password: auth.password };
+    const resp = await fetchJson(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    const token =
+      resp?.data?.token ||
+      resp?.data?.data?.token ||
+      resp?.data?.data?.session?.token ||
+      "";
+
+    if (!token) {
+      throw new Error(
+        "Token response does not contain token field; adjust parsing in src/zentao.js#getToken()"
+      );
+    }
+    cachedToken = token;
+    cachedAt = Date.now();
+    return { token: cachedToken, source: "login" };
+  }
+
+  async function call({ path, method = "GET", query, body } = {}) {
+    const tokenInfo = await getToken();
+    const url = buildUrl({ baseUrl, apiPrefix, path, query });
+
+    const headers = { Token: tokenInfo.token };
+    let payload;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+
+    return fetchJson(url, { method: method.toUpperCase(), headers, body: payload });
+  }
+
+  function looksLikeMyProject(p, keyword) {
+    if (!p || typeof p !== "object") return false;
+    const k = (keyword || "").trim().toLowerCase();
+    const fields = [
+      p.name,
+      p.code,
+      p.desc,
+      p.pm,
+      p.po,
+      p.qd,
+      p.rd,
+      p.status,
+    ]
+      .filter(Boolean)
+      .map((x) => String(x).toLowerCase());
+    if (k && !fields.some((x) => x.includes(k))) return false;
+    return true;
+  }
+
+  async function listMyProjects({ keyword } = {}) {
+    // 这里的路径可能需要按你的禅道实例调整：如 /projects 或 /projects?limit=...
+    const resp = await call({ path: "/projects", method: "GET" });
+    const list = Array.isArray(resp?.data?.projects)
+      ? resp.data.projects
+      : Array.isArray(resp?.data?.data)
+        ? resp.data.data
+        : Array.isArray(resp?.data)
+          ? resp.data
+          : [];
+    const filtered = list.filter((p) => looksLikeMyProject(p, keyword));
+    return { total: list.length, matched: filtered.length, projects: filtered };
+  }
+
+  // 轻量重试：禅道偶发 502/网关问题时可用；默认不用，保留扩展点
+  async function callWithRetry(args, { retries = 0, backoffMs = 200 } = {}) {
+    let lastErr;
+    for (let i = 0; i <= retries; i++) {
+      try {
+        return await call(args);
+      } catch (e) {
+        lastErr = e;
+        if (i === retries) break;
+        await sleep(backoffMs * (i + 1));
+      }
+    }
+    throw lastErr;
+  }
+
+  return { getToken, call, callWithRetry, listMyProjects };
+}