@chenyingxian/zentao-mcp 0.1.0

package/README.zh-CN.md

@@ -0,0 +1,79 @@
+# zentao-mcp
+
+禅道 MCP Server，面向禅道 RESTful API v1 和部分旧版 JSON / 表单路由。
+
+适用于自托管禅道环境。当前主要覆盖个人任务、任务详情、工时日志、周总结、构建、测试单和发版任务预览等常用流程。
+
+## 安装
+
+```bash
+npm install -g zentao-mcp
+```
+
+也可以不全局安装，直接通过 `npx` 运行：
+
+```bash
+npx zentao-mcp
+```
+
+## 文档
+
+- [配置说明](./CONFIG.zh-CN.md)
+- [工具说明](./MCP_TOOLS.zh-CN.md)
+- [English README](./README.md)
+
+## 快速配置
+
+在 MCP 客户端中配置环境变量：
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_ACCOUNT=your-account
+ZENTAO_PASSWORD=your-password
+```
+
+也可以直接使用已签发的 v1 token：
+
+```bash
+ZENTAO_BASE_URL=https://zentao.example.com
+ZENTAO_TOKEN=your-token
+```
+
+## MCP 客户端示例
+
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "npx",
+      "args": ["zentao-mcp"],
+      "env": {
+        "ZENTAO_BASE_URL": "https://zentao.example.com",
+        "ZENTAO_ACCOUNT": "your-account",
+        "ZENTAO_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+## 获取 Token
+
+全局安装后可以使用：
+
+```bash
+zentao-mcp-get-token --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+源码目录中可以使用：
+
+```bash
+./scripts/get-token.sh --base-url "https://zentao.example.com" --account "your-account" --password "your-password"
+```
+
+## 注意事项
+
+- 支持禅道 RESTful API v1；部分能力会使用禅道旧版 JSON / 表单路由。
+- 创建构建、创建测试单等写操作默认 `dry_run=true`，需要显式传 `false` 才会真实创建。
+- 不要提交或发布真实 `.env`、账号、密码、token、内网域名或业务数据。
+

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@chenyingxian/zentao-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ZenTao RESTful API v1 and legacy JSON routes.",
+  "type": "module",
+  "bin": {
+    "zentao-mcp": "./src/index.js",
+    "zentao-mcp-get-token": "./scripts/get-token.sh"
+  },
+  "scripts": {
+    "start": "node ./src/index.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "mcp",
+    "zentao",
+    "chandao",
+    "project-management",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "zod": "^3.25.76"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "README.md",
+    "README.zh-CN.md",
+    "CONFIG.md",
+    "CONFIG.zh-CN.md",
+    "MCP_TOOLS.md",
+    "MCP_TOOLS.zh-CN.md",
+    ".env.example"
+  ],
+  "license": "MIT"
+}

package/scripts/get-token.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_URL="${ZENTAO_BASE_URL:-}"
+ACCOUNT="${ZENTAO_ACCOUNT:-}"
+PASSWORD="${ZENTAO_PASSWORD:-}"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --base-url)
+      BASE_URL="${2:-}"
+      shift 2
+      ;;
+    --account)
+      ACCOUNT="${2:-}"
+      shift 2
+      ;;
+    --password)
+      PASSWORD="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: $0 --base-url URL --account ACCOUNT --password PASSWORD"
+      echo "Or set ZENTAO_BASE_URL, ZENTAO_ACCOUNT and ZENTAO_PASSWORD."
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$BASE_URL" ]; then
+  echo "BASE_URL is required. Pass --base-url or set ZENTAO_BASE_URL." >&2
+  exit 1
+fi
+if [ -z "$ACCOUNT" ]; then
+  echo "ACCOUNT is required. Pass --account or set ZENTAO_ACCOUNT." >&2
+  exit 1
+fi
+if [ -z "$PASSWORD" ]; then
+  echo "PASSWORD is required. Pass --password or set ZENTAO_PASSWORD." >&2
+  exit 1
+fi
+
+# Build the ZenTao RESTful API v1 token URL.
+BASE_URL="${BASE_URL%/}"
+if [[ "$BASE_URL" == */api.php/v1 ]]; then
+  LOGIN_URL="$BASE_URL/tokens"
+elif [[ "$BASE_URL" == */api.php ]]; then
+  LOGIN_URL="$BASE_URL/v1/tokens"
+elif [[ "$BASE_URL" == */api.php/v2 ]]; then
+  LOGIN_URL="${BASE_URL%/v2}/v1/tokens"
+else
+  LOGIN_URL="$BASE_URL/api.php/v1/tokens"
+fi
+
+# Escape JSON string content before building the request body.
+json_escape() {
+  printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'
+}
+
+BODY=$(printf '{"account":"%s","password":"%s"}' "$(json_escape "$ACCOUNT")" "$(json_escape "$PASSWORD")")
+RESPONSE_FILE=$(mktemp)
+trap 'rm -f "$RESPONSE_FILE"' EXIT
+
+HTTP_STATUS=$(curl -sS -o "$RESPONSE_FILE" -w "%{http_code}" -X POST "$LOGIN_URL" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json" \
+  -d "$BODY")
+
+RESPONSE=$(cat "$RESPONSE_FILE")
+TOKEN=$(node -e 'const fs=require("fs"); const file=process.argv[1]; const text=fs.readFileSync(file,"utf8"); try { const data=JSON.parse(text); const token=data.token || data?.data?.token || data?.data?.user?.token || ""; if (token) process.stdout.write(String(token)); } catch (_) {}' "$RESPONSE_FILE")
+if [ -z "$TOKEN" ]; then
+  TOKEN=$(printf '%s' "$RESPONSE" | sed -n 's/.*"token"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p')
+fi
+if [ -z "$TOKEN" ]; then
+  echo "Login URL: $LOGIN_URL" >&2
+  echo "HTTP status: $HTTP_STATUS" >&2
+  echo "$RESPONSE" >&2
+  echo "ZenTao login failed or token is empty." >&2
+  exit 1
+fi
+
+printf '%s\n' "$TOKEN"

package/src/index.js

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createClientFromEnv } from "./zentao-client.js";
+
+const server = new McpServer({
+  name: "zentao-mcp",
+  version: "0.1.0"
+});
+
+server.tool(
+  "zentao_get_my_tasks",
+  "查询禅道待处理下指派给当前登录用户的任务。",
+  {
+    order_by: z.string().optional().default("id_desc").describe("排序字段，例如 id_desc。"),
+    rec_per_page: z.number().int().positive().max(1000).optional().default(100).describe("每页数量，最大 1000。"),
+    page_id: z.number().int().positive().optional().default(1).describe("页码，从 1 开始。")
+  },
+  handleGetMyTasks
+);
+
+server.tool(
+  "zentao_get_finished_tasks",
+  "查询禅道由当前登录用户完成的任务。",
+  {
+    rec_per_page: z.number().int().positive().max(20).optional().default(20).describe("返回数量，默认 20，最大 20。"),
+    page_id: z.number().int().positive().optional().default(1).describe("本地分页页码，从 1 开始。")
+  },
+  handleGetFinishedTasks
+);
+
+server.tool(
+  "zentao_get_task",
+  "按任务 ID 读取禅道任务详情。",
+  {
+    task_id: z.union([z.number().int().positive(), z.string().min(1)]).describe("禅道任务 ID。")
+  },
+  handleGetTask
+);
+
+server.tool(
+  "zentao_create_build",
+  "按开发任务 ID 创建禅道构建，并在创建后自动关联该任务对应的需求。",
+  {
+    task_id: z.union([z.number().int().positive(), z.string().min(1)]).describe("禅道开发任务 ID。"),
+    dry_run: z.boolean().optional().default(true).describe("是否只预览不创建，默认 true；传 false 才会真实创建构建并关联需求。")
+  },
+  handleCreateBuild
+);
+
+server.tool(
+  "zentao_create_testtask",
+  "按开发任务 ID 和构建 ID 创建禅道测试单。",
+  {
+    task_id: z.union([z.number().int().positive(), z.string().min(1)]).describe("禅道开发任务 ID。"),
+    build_id: z.union([z.number().int().positive(), z.string().min(1)]).describe("禅道构建 ID。"),
+    dry_run: z.boolean().optional().default(true).describe("是否只预览不创建，默认 true；传 false 才会真实创建测试单。"),
+    owner: z.string().optional().describe("测试单负责人账号；不传则使用对应测试任务的第一个指派人。"),
+    begin: z.string().optional().describe("开始日期，格式 yyyy-mm-dd；不传则使用今天。"),
+    end: z.string().optional().describe("结束日期，格式 yyyy-mm-dd；不传则使用开始日期后第 4 天。"),
+    attachment_paths: z.array(z.string().min(1)).optional().default([]).describe("要随测试单上传的本地附件路径，例如 JMeter 脚本 .jmx 和测试内容 .md。")
+  },
+  handleCreateTestTask
+);
+
+server.tool(
+  "zentao_create_release_task",
+  "根据开发任务列表生成发版任务信息；默认只预览，不实际创建。",
+  {
+    task_ids: z.array(z.union([z.number().int().positive(), z.string().min(1)])).min(1).describe("本次发版包含的禅道开发任务 ID 列表。"),
+    system: z.string().min(1).describe("系统或模块名，例如 WebApp。"),
+    story_id: z.union([z.number().int().positive(), z.string().min(1)]).optional().describe("发版任务要关联的主需求 ID；不传则使用第一个任务的需求。"),
+    release_scope: z.string().optional().default("生产环境").describe("发布范围，例如 生产环境、灰度环境。"),
+    gray_tag: z.string().optional().describe("生产发布时对应的灰度 tag。"),
+    branch: z.string().optional().describe("git 分支；不传则尝试从开发任务描述中解析。"),
+    release_content: z.array(z.string()).optional().default([]).describe("对外说明发布的内容；不传则使用关联需求标题。"),
+    database: z.string().optional().describe("数据库变更，没有可不传。"),
+    env: z.string().optional().describe("环境变量变更，没有可不传。"),
+    cron: z.string().optional().describe("计划任务变更，没有可不传。"),
+    dependencies: z.string().optional().describe("依赖包变更，没有可不传。"),
+    other: z.string().optional().describe("其它事项，没有可不传。"),
+    risk: z.string().optional().describe("风险，没有可不传。"),
+    dry_run: z.boolean().optional().default(true).describe("是否只预览不创建；当前只支持 true。")
+  },
+  handleCreateReleaseTask
+);
+
+server.tool(
+  "zentao_get_effort_logs",
+  "读取禅道 effort-calendar / 我的日志工时记录。",
+  {
+    type: z.string().optional().default("all").describe("日志类型，默认 all。"),
+    order_by: z.string().optional().default("date_desc").describe("排序字段，默认 date_desc。"),
+    rec_per_page: z.number().int().positive().max(1000).optional().default(100).describe("每页数量，最大 1000。"),
+    page_id: z.number().int().positive().optional().default(1).describe("页码，从 1 开始。")
+  },
+  handleGetEffortLogs
+);
+
+server.tool(
+  "zentao_generate_weekly_summary",
+  "根据本周工时日志生成周总结文本。",
+  {
+    start_date: z.string().optional().describe("开始日期，格式 yyyy-mm-dd；不传则使用本周一。"),
+    end_date: z.string().optional().describe("结束日期，格式 yyyy-mm-dd；不传则使用本周日。"),
+    rec_per_page: z.number().int().positive().max(1000).optional().default(100).describe("每页读取日志数量，默认 100。"),
+    max_pages: z.number().int().positive().max(50).optional().default(10).describe("最多读取页数，默认 10。")
+  },
+  handleGenerateWeeklySummary
+);
+
+/**
+ * Handle the MCP tool call for assigned ZenTao tasks.
+ * @param {{rec_per_page?: number, page_id?: number}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleGetMyTasks(args) {
+  const client = createClientFromEnv();
+  // Keep the API result intact so later tools can reuse raw ZenTao fields.
+  const result = await client.getMyTasks({ orderBy: args.order_by, recPerPage: args.rec_per_page, pageId: args.page_id });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Handle the MCP tool call for tasks finished by current user.
+ * @param {{order_by?: string, rec_per_page?: number, page_id?: number}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleGetFinishedTasks(args) {
+  const client = createClientFromEnv();
+  const result = await client.getFinishedTasks({ recPerPage: args.rec_per_page, pageId: args.page_id });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Handle the MCP tool call for one ZenTao task detail.
+ * @param {{task_id: number|string}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleGetTask(args) {
+  const client = createClientFromEnv();
+  const result = await client.getTask(args.task_id);
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Handle the MCP tool call for creating a ZenTao build.
+ * @param {{task_id: number|string, dry_run?: boolean}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleCreateBuild(args) {
+  const client = createClientFromEnv();
+  const result = await client.createBuildForTask(args.task_id, { dryRun: args.dry_run });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Handle the MCP tool call for creating a ZenTao test task.
+ * @param {{task_id: number|string, build_id: number|string, dry_run?: boolean, owner?: string, begin?: string, end?: string, attachment_paths?: string[]}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleCreateTestTask(args) {
+  const client = createClientFromEnv();
+  const result = await client.createTestTaskForTask(args.task_id, args.build_id, { dryRun: args.dry_run, owner: args.owner, begin: args.begin, end: args.end, attachmentPaths: args.attachment_paths });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Handle the MCP tool call for preparing a ZenTao release task.
+ * @param {{task_ids: Array<number|string>, system: string, story_id?: number|string, release_scope?: string, gray_tag?: string, branch?: string, release_content?: string[], database?: string, env?: string, cron?: string, dependencies?: string, other?: string, risk?: string, dry_run?: boolean}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleCreateReleaseTask(args) {
+  const client = createClientFromEnv();
+  const result = await client.createReleaseTask({ taskIds: args.task_ids, system: args.system, storyId: args.story_id, releaseScope: args.release_scope, grayTag: args.gray_tag, branch: args.branch, releaseContent: args.release_content, database: args.database, env: args.env, cron: args.cron, dependencies: args.dependencies, other: args.other, risk: args.risk, dryRun: args.dry_run });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Handle the MCP tool call for effort logs.
+ * @param {{type?: string, order_by?: string, rec_per_page?: number, page_id?: number}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleGetEffortLogs(args) {
+  const client = createClientFromEnv();
+  const result = await client.getEffortLogs({ type: args.type, orderBy: args.order_by, recPerPage: args.rec_per_page, pageId: args.page_id });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Handle the MCP tool call for weekly summary generation.
+ * @param {{start_date?: string, end_date?: string, rec_per_page?: number, max_pages?: number}} args Tool arguments.
+ * @returns {Promise<{content: Array<{type: "text", text: string}>}>} MCP response.
+ */
+async function handleGenerateWeeklySummary(args) {
+  const client = createClientFromEnv();
+  const result = await client.generateWeeklySummary({ startDate: args.start_date, endDate: args.end_date, recPerPage: args.rec_per_page, maxPages: args.max_pages });
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2)
+      }
+    ]
+  };
+}
+
+/**
+ * Start the MCP stdio server.
+ * @returns {Promise<void>} Resolves when transport is connected.
+ */
+async function main() {
+  // Stdio transport is the standard integration mode for local MCP clients.
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});