@leeguoo/zentao-mcp 0.4.1 → 0.5.0

package/README.md

@@ -1,177 +1,107 @@
 # zentao-mcp
 
-MCP server for ZenTao RESTful APIs (products + bugs).
-
-## Quick Start
-
-### 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"
-      ]
-    }
-  }
-}
-```
+ZenTao CLI for products + bugs.
 
-5. Restart Cursor IDE
+## Installation
 
-### Other MCP Clients (Claude Desktop, etc.)
+Global install:
 
-For clients using TOML configuration (e.g., Claude Desktop), add to your MCP config file:
+```bash
+npm i -g @leeguoo/zentao-mcp
+```
 
-```toml
-[mcp_servers."zentao-mcp"]
-command = "npx"
-args = [
-  "-y",
-  "@leeguoo/zentao-mcp",
-  "--zentao-url=https://zentao.example.com/zentao",
-  "--zentao-account=leo",
-  "--zentao-password=***",
-  "--stdio"
-]
+Or use without installing:
+
+```bash
+npx -y @leeguoo/zentao-mcp --help
 ```
 
-**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)
+This installs the `zentao` command (and keeps `zentao-mcp` as a compatibility alias).
 
 ## Configuration
 
 ### Required Parameters
 
-You can configure the server using CLI arguments or environment variables:
+You can configure the CLI using CLI arguments or environment variables:
+
+CLI arguments:
 
-**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`)
+Environment variables:
+
+- `ZENTAO_URL`
 - `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`).
+
+## Commands
+
+List products:
+
+```bash
+zentao products list
 ```
 
-**Tip:** `ZENTAO_URL` should include the ZenTao base path (often `/zentao`).
-
-## Tools
-
-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_bug_get`** - Get bug details by ID
-- **`zentao_bugs_mine`** - List my bugs by assignment or creator (status filter supported)
-
-### 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 bug 123"
-- "Show me bugs"
-- "Show my bugs"
-- "List bugs assigned to me"
-- "View bugs in product 2"
-
-**Chinese (中文):**
-- "看bug" / "查看bug" / "显示bug"
-- "产品1的bug列表"
-- "查看bug 123"
-- "显示所有产品"
-- "查看产品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_bug_get` when you ask for bug details
-4. Use `zentao_bugs_mine` when you ask for your own bugs
-
-### Tool Parameters
-
-**zentao_products_list:**
-```json
-{
-  "page": 1,
-  "limit": 1000
-}
+List bugs for a product:
+
+```bash
+zentao bugs list --product 1
 ```
 
-**zentao_bugs_list:**
-```json
-{
-  "product": 1,
-  "page": 1,
-  "limit": 20
-}
+Get bug details:
+
+```bash
+zentao bug get --id 123
 ```
 
-**zentao_bug_get:**
-```json
-{
-  "id": 123
-}
+List my bugs:
+
+```bash
+zentao bugs mine --scope assigned --status active
 ```
 
-**zentao_bugs_mine:**
-```json
-{
-  "status": "active",
-  "scope": "assigned",
-  "includeZero": false,
-  "includeDetails": true,
-  "maxItems": 50
-}
+Self test:
+
+```bash
+zentao self-test
+```
+
+## Login
+
+Save credentials locally (stored as plaintext TOML under your user config directory):
+
+```bash
+zentao login --zentao-url=https://zentao.example.com/zentao --zentao-account=leo --zentao-password=***
+```
+
+Config file:
+
+- `~/.config/zentao/config.toml` (or `$XDG_CONFIG_HOME/zentao/config.toml`)
+
+Then commands can omit auth flags:
+
+```bash
+zentao whoami
+zentao products list
+```
+
+## Release (maintainers)
+
+Requires `git`, `npm`, and `gh`.
+
+```bash
+zentao release patch --dry-run
 ```
 
 ## Local Development
 
 ```bash
 pnpm install
-ZENTAO_URL=https://zentao.example.com/zentao \\
-ZENTAO_ACCOUNT=leo \\
-ZENTAO_PASSWORD=*** \\
-pnpm start
+pnpm test
 ```
 
 ## Security

package/package.json

@@ -1,14 +1,10 @@
 {
   "name": "@leeguoo/zentao-mcp",
-  "version": "0.4.1",
-  "description": "MCP server for ZenTao RESTful APIs",
+  "version": "0.5.0",
+  "description": "ZenTao CLI for products + bugs",
   "keywords": [
     "zentao",
     "chandao",
-    "mcp",
-    "modelcontextprotocol",
-    "llm",
-    "ai",
     "api",
     "rest",
     "bug-tracker",
@@ -20,10 +16,12 @@
   ],
   "type": "module",
   "bin": {
+    "zentao": "src/index.js",
     "zentao-mcp": "src/index.js"
   },
   "files": [
     "src",
+    "skills",
     "README.md"
   ],
   "publishConfig": {
@@ -31,13 +29,15 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "self-test": "node scripts/self-test.mjs",
-    "release": "./scripts/release.sh",
-    "release:patch": "./scripts/release.sh patch",
-    "release:minor": "./scripts/release.sh minor",
-    "release:major": "./scripts/release.sh major"
+    "self-test": "node src/index.js self-test",
+    "release": "node src/index.js release",
+    "release:patch": "node src/index.js release patch",
+    "release:minor": "node src/index.js release minor",
+    "release:major": "node src/index.js release major",
+    "test": "node --test"
   },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.1"
+  "dependencies": {},
+  "engines": {
+    "node": ">=18"
   }
 }

package/skills/zentao-cli.md

@@ -0,0 +1,106 @@
+# zentao (ZenTao CLI)
+
+This package provides a CLI for ZenTao REST API (products + bugs).
+
+## Installation
+
+Global install:
+
+```bash
+npm i -g @leeguoo/zentao-mcp
+```
+
+Or use without installing:
+
+```bash
+npx -y @leeguoo/zentao-mcp --help
+```
+
+This installs the `zentao` command (and keeps `zentao-mcp` as a compatibility alias).
+
+## Authentication
+
+You can pass credentials via environment variables:
+
+```bash
+export ZENTAO_URL="https://zentao.example.com/zentao"
+export ZENTAO_ACCOUNT="leo"
+export ZENTAO_PASSWORD="***"
+```
+
+Or via CLI flags:
+
+- `--zentao-url`
+- `--zentao-account`
+- `--zentao-password`
+
+## Commands
+
+### List products
+
+```bash
+zentao products list
+```
+
+### List bugs for a product
+
+```bash
+zentao bugs list --product 1
+```
+
+### Get bug details
+
+```bash
+zentao bug get --id 123
+```
+
+### List my bugs
+
+```bash
+zentao bugs mine --scope assigned --status active
+```
+
+Common options:
+
+- `--scope`: `assigned|opened|resolved|all`
+- `--status`: `active|resolved|closed|all` (supports `,` or `|` separated)
+- `--include-details`: include bug list in response
+- `--product-ids`: limit scan to specific products, e.g. `--product-ids=1,2,3`
+
+### Self test
+
+```bash
+zentao self-test
+```
+
+Use `--expected N` to make it CI-friendly (exit code 2 when mismatch):
+
+```bash
+zentao self-test --expected 0
+```
+
+## Login / Whoami
+
+Save credentials locally:
+
+```bash
+zentao login --zentao-url=https://zentao.example.com/zentao --zentao-account=leo --zentao-password=***
+```
+
+Config file:
+
+- `~/.config/zentao/config.toml` (or `$XDG_CONFIG_HOME/zentao/config.toml`)
+
+Then:
+
+```bash
+zentao whoami
+```
+
+### Release (maintainers)
+
+Requires `git`, `npm`, and `gh`.
+
+```bash
+zentao release patch --dry-run
+```

package/src/cli/args.js

@@ -0,0 +1,99 @@
+export function parseCliArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    if (!raw.startsWith("--")) continue;
+    const [flag, inlineValue] = raw.split("=", 2);
+    const key = flag.replace(/^--/, "");
+    if (inlineValue !== undefined) {
+      args[key] = inlineValue;
+      continue;
+    }
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      args[key] = next;
+      i += 1;
+      continue;
+    }
+    args[key] = true;
+  }
+  return args;
+}
+
+export function hasHelpFlag(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+
+export function getOption(cliArgs, env, envName, cliName) {
+  if (cliArgs[cliName]) return cliArgs[cliName];
+  const envValue = env[envName];
+  if (envValue) return envValue;
+  return null;
+}
+
+function isFlagToken(raw) {
+  return raw.startsWith("-") && raw !== "-";
+}
+
+export function splitSubcommand(argv) {
+  // Goal: find the first positional argument that isn't a flag or a flag value.
+  // This allows: `zentao-mcp self-test --foo=bar`.
+  // It also avoids treating `--zentao-url https://...` value as a subcommand.
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+
+    if (raw === "--") {
+      return { command: null, commandArgv: argv };
+    }
+
+    if (raw.startsWith("--")) {
+      const hasInlineValue = raw.includes("=");
+      if (hasInlineValue) continue;
+      const next = argv[i + 1];
+      if (next && !isFlagToken(next)) {
+        i += 1;
+      }
+      continue;
+    }
+
+    if (raw === "-h") continue;
+    if (raw === "-v") continue;
+    if (raw.startsWith("-")) continue;
+
+    return { command: raw, commandArgv: argv.slice(i + 1) };
+  }
+
+  return { command: null, commandArgv: argv };
+}
+
+function findFirstPositional(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const raw = argv[i];
+    if (raw === "--") continue;
+
+    if (raw.startsWith("--")) {
+      const hasInlineValue = raw.includes("=");
+      if (hasInlineValue) continue;
+      const next = argv[i + 1];
+      if (next && !isFlagToken(next)) {
+        i += 1;
+      }
+      continue;
+    }
+
+    if (raw === "-h") continue;
+    if (raw === "-v") continue;
+    if (raw.startsWith("-")) continue;
+
+    return { index: i, value: raw };
+  }
+
+  return { index: -1, value: null };
+}
+
+export function extractCommand(argv) {
+  const { index, value } = findFirstPositional(argv);
+  if (!value) return { command: null, argv };
+  const nextArgv = argv.slice(0, index).concat(argv.slice(index + 1));
+  return { command: value, argv: nextArgv };
+}

package/src/cli/help.js

@@ -0,0 +1,49 @@
+export function printRootHelp() {
+  // Keep this plain text: many users run via npx and paste output.
+  process.stdout.write(`zentao - ZenTao CLI\n\n`);
+  process.stdout.write(`Usage:\n`);
+  process.stdout.write(`  zentao login [--zentao-url ... --zentao-account ... --zentao-password ...] [--yes]\n`);
+  process.stdout.write(`  zentao whoami\n`);
+  process.stdout.write(`  zentao products list [--page N] [--limit N]\n`);
+  process.stdout.write(`  zentao bugs list --product <id> [--page N] [--limit N]\n`);
+  process.stdout.write(`  zentao bug get --id <bugId>\n`);
+  process.stdout.write(`  zentao bugs mine [--scope ...] [--status ...] [--include-details]\n`);
+  process.stdout.write(`  zentao self-test [--expected N]\n`);
+  process.stdout.write(`  zentao release [patch|minor|major] [--dry-run] [--yes]\n\n`);
+  process.stdout.write(`Auth options:\n`);
+  process.stdout.write(`  --zentao-url        or env ZENTAO_URL\n`);
+  process.stdout.write(`  --zentao-account    or env ZENTAO_ACCOUNT\n`);
+  process.stdout.write(`  --zentao-password   or env ZENTAO_PASSWORD\n`);
+  process.stdout.write(`  --help, -h          show help\n\n`);
+  process.stdout.write(`Subcommands:\n`);
+  process.stdout.write(`  login               save credentials locally\n`);
+  process.stdout.write(`  whoami              show current account\n`);
+  process.stdout.write(`  products            ZenTao products\n`);
+  process.stdout.write(`  bugs                ZenTao bugs\n`);
+  process.stdout.write(`  bug                 ZenTao bug\n`);
+  process.stdout.write(`  self-test           run a basic API roundtrip\n`);
+  process.stdout.write(`  release             version bump + tag + gh release + npm publish\n`);
+}
+
+export function printSelfTestHelp() {
+  process.stdout.write(`zentao self-test - verify API access\n\n`);
+  process.stdout.write(`Usage:\n`);
+  process.stdout.write(`  zentao self-test --zentao-url=... --zentao-account=... --zentao-password=...\n`);
+  process.stdout.write(`  ZENTAO_URL=... ZENTAO_ACCOUNT=... ZENTAO_PASSWORD=... zentao self-test\n\n`);
+  process.stdout.write(`Options:\n`);
+  process.stdout.write(`  --expected N         exit 2 if total != N\n`);
+  process.stdout.write(`  --help, -h           show help\n`);
+}
+
+export function printReleaseHelp() {
+  process.stdout.write(`zentao release - create a new release\n\n`);
+  process.stdout.write(`Usage:\n`);
+  process.stdout.write(`  zentao release [patch|minor|major] [--dry-run] [--yes]\n\n`);
+  process.stdout.write(`Options:\n`);
+  process.stdout.write(`  --dry-run            print planned commands, do not run\n`);
+  process.stdout.write(`  --yes                auto-confirm prompts (dirty git, npm login)\n`);
+  process.stdout.write(`  --skip-push           do not push commits/tags\n`);
+  process.stdout.write(`  --skip-github-release do not create GitHub release\n`);
+  process.stdout.write(`  --skip-publish        do not npm publish\n`);
+  process.stdout.write(`  --help, -h            show help\n`);
+}

package/src/commands/bug.js

@@ -0,0 +1,27 @@
+import process from "node:process";
+import { extractCommand, hasHelpFlag, parseCliArgs } from "../cli/args.js";
+import { createClientFromCli } from "../zentao/client.js";
+
+function printHelp() {
+  process.stdout.write(`zentao-mcp bug get\n\n`);
+  process.stdout.write(`Usage:\n`);
+  process.stdout.write(`  zentao-mcp bug get --id <bugId>\n`);
+}
+
+export async function runBug({ argv = [], env = process.env } = {}) {
+  if (hasHelpFlag(argv)) {
+    printHelp();
+    return;
+  }
+
+  const { command: sub, argv: argvWithoutSub } = extractCommand(argv);
+  if (sub !== "get") throw new Error(`Unknown bug subcommand: ${sub || "(missing)"}`);
+
+  const cliArgs = parseCliArgs(argvWithoutSub);
+  const id = cliArgs.id;
+  if (!id) throw new Error("Missing --id");
+
+  const api = createClientFromCli({ argv: argvWithoutSub, env });
+  const result = await api.getBug({ id });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}

package/src/commands/bugs.js

@@ -0,0 +1,68 @@
+import process from "node:process";
+import { extractCommand, hasHelpFlag, parseCliArgs } from "../cli/args.js";
+import { createClientFromCli } from "../zentao/client.js";
+
+function parseCsvIntegers(value) {
+  if (value === undefined || value === null || value === "") return null;
+  if (Array.isArray(value)) {
+    const nested = value.flatMap((item) => String(item).split(/[,|]/));
+    const parsed = nested.map((item) => Number(item)).filter((n) => Number.isFinite(n));
+    return parsed.length ? parsed : null;
+  }
+  const tokens = String(value)
+    .split(/[,|]/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+  const parsed = tokens.map((item) => Number(item)).filter((n) => Number.isFinite(n));
+  return parsed.length ? parsed : null;
+}
+
+function printHelp() {
+  process.stdout.write(`zentao-mcp bugs <subcommand>\n\n`);
+  process.stdout.write(`Usage:\n`);
+  process.stdout.write(`  zentao-mcp bugs list --product <id> [--page N] [--limit N]\n`);
+  process.stdout.write(`  zentao-mcp bugs mine [--scope assigned|opened|resolved|all] [--status active|resolved|closed|all] [--include-details]\n`);
+}
+
+export async function runBugs({ argv = [], env = process.env } = {}) {
+  if (hasHelpFlag(argv)) {
+    printHelp();
+    return;
+  }
+
+  const { command: sub, argv: argvWithoutSub } = extractCommand(argv);
+  const cliArgs = parseCliArgs(argvWithoutSub);
+  const api = createClientFromCli({ argv: argvWithoutSub, env });
+
+  if (sub === "list") {
+    const product = cliArgs.product;
+    if (!product) throw new Error("Missing --product");
+    const result = await api.listBugs({
+      product,
+      page: cliArgs.page,
+      limit: cliArgs.limit,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  if (sub === "mine") {
+    const includeDetails = Boolean(cliArgs["include-details"]);
+    const includeZero = Boolean(cliArgs["include-zero"]);
+    const productIds = parseCsvIntegers(cliArgs["product-ids"]);
+    const result = await api.bugsMine({
+      account: cliArgs.account,
+      scope: cliArgs.scope,
+      status: cliArgs.status,
+      productIds,
+      includeZero,
+      perPage: cliArgs["per-page"],
+      maxItems: cliArgs["max-items"],
+      includeDetails,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return;
+  }
+
+  throw new Error(`Unknown bugs subcommand: ${sub || "(missing)"}`);
+}