@leeguoo/zentao-mcp 0.2.1 → 0.2.2

package/README.md

@@ -2,9 +2,38 @@
 
 MCP server for ZenTao RESTful APIs (products + bugs).
 
-## Quick Start (npx)
+## Quick Start
 
-Use this MCP server config in your client:
+### 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",
+        "--stdio",
+        "--zentao-url=https://zentao.example.com/zentao",
+        "--zentao-account=leo",
+        "--zentao-password=***"
+      ]
+    }
+  }
+}
+```
+
+5. Restart Cursor IDE
+
+### Other MCP Clients (Claude Desktop, etc.)
+
+For clients using TOML configuration (e.g., Claude Desktop), add to your MCP config file:
 
 ```toml
 [mcp_servers."zentao-mcp"]
@@ -19,23 +48,90 @@ args = [
 ]
 ```
 
+**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)
+
 ## Configuration
 
-Required:
-- `--zentao-url` / `ZENTAO_URL` (e.g. `https://zentao.example.com/zentao`)
-- `--zentao-account` / `ZENTAO_ACCOUNT`
-- `--zentao-password` / `ZENTAO_PASSWORD`
+### Required Parameters
 
-Tip: `ZENTAO_URL` should include the ZenTao base path (often `/zentao`).
+You can configure the server using CLI arguments or environment variables:
+
+**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`)
+- `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`).
 
 ## Tools
 
-- `zentao_products_list` (page, limit)
-- `zentao_bugs_list` (product, page, limit)
-- `zentao_bugs_stats` (includeZero, limit)
+The MCP server provides three 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_bugs_stats`** - Get bug statistics across products
+
+### 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 me bugs"
+- "What's the bug statistics?"
+- "View bugs in product 2"
 
-Example tool input:
+**Chinese (中文):**
+- "看bug" / "查看bug" / "显示bug"
+- "产品1的bug列表"
+- "bug统计"
+- "显示所有产品"
+- "查看产品2的问题"
+
+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_bugs_stats` when you ask for statistics or overview
+
+### Tool Parameters
+
+**zentao_products_list:**
+```json
+{
+  "page": 1,
+  "limit": 1000
+}
+```
 
+**zentao_bugs_list:**
 ```json
 {
   "product": 1,
@@ -44,6 +140,14 @@ Example tool input:
 }
 ```
 
+**zentao_bugs_stats:**
+```json
+{
+  "includeZero": false,
+  "limit": 1000
+}
+```
+
 ## Local Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeguoo/zentao-mcp",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "MCP server for ZenTao RESTful APIs",
   "keywords": [
     "zentao",
@@ -26,6 +26,9 @@
     "src",
     "README.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "start": "node src/index.js",
     "release": "./scripts/release.sh",

package/src/index.js

@@ -218,7 +218,7 @@ const server = new Server(
 const tools = [
   {
     name: "zentao_products_list",
-    description: "List products (RESTful API).",
+    description: "List all products from ZenTao. Use this to get product IDs before querying bugs. Returns product information including ID, name, and bug counts.",
     inputSchema: {
       type: "object",
       properties: {
@@ -230,11 +230,11 @@ const tools = [
   },
   {
     name: "zentao_bugs_list",
-    description: "List bugs for a product (RESTful API).",
+    description: "List bugs (缺陷/问题) for a specific product in ZenTao. Use this when user asks to 'see bugs', 'view bugs', 'show bugs', '看bug', '查看bug', '显示bug', or wants to check issues for a product. Requires product ID which can be obtained from zentao_products_list.",
     inputSchema: {
       type: "object",
       properties: {
-        product: { type: "integer", description: "Product ID." },
+        product: { type: "integer", description: "Product ID (required). Get this from zentao_products_list first." },
         page: { type: "integer", description: "Page number (default 1)." },
         limit: { type: "integer", description: "Page size (default 20)." },
       },
@@ -244,11 +244,11 @@ const tools = [
   },
   {
     name: "zentao_bugs_stats",
-    description: "Aggregate bug totals across products.",
+    description: "Get bug statistics (bug统计) across all products. Shows total bugs, unresolved bugs, closed bugs, and fixed bugs per product. Use when user asks for bug summary, statistics, overview, or 'bug统计'.",
     inputSchema: {
       type: "object",
       properties: {
-        includeZero: { type: "boolean", description: "Include products with zero bugs." },
+        includeZero: { type: "boolean", description: "Include products with zero bugs (default false)." },
         limit: { type: "integer", description: "Max products to fetch (default 1000)." },
       },
       additionalProperties: false,