@zzp123/mcp-zentao 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0] - 2025-11-07
+
+### Added
+- **产品和需求列表字段过滤功能** 📦
+  - 为 `getProducts` 添加 `fields` 参数支持
+  - 为 `getProductStories` 添加 `fields` 参数支持
+  - 支持三种字段级别：
+    - `basic`: 基本信息（产品：id, name, code, status；需求：id, title, assignedTo, openedBy）
+    - `default`: 默认信息（产品：包含 PO/QD/RD 等；需求：包含 status/stage/pri 等，**默认使用**）
+    - `full`: 完整信息（所有字段）
+
+### Changed
+- **优化列表接口默认返回数据**
+  - 产品列表默认使用 `default` 字段级别，返回核心管理信息
+  - 需求列表默认使用 `basic` 字段级别，只返回最基本的4个字段
+  - 显著减少数据传输量，提升列表查询响应速度
+
+### Improved
+- **性能优化**
+  - 列表接口数据量大幅减少，特别适合快速浏览和搜索场景
+  - 减少不必要的字段传输，降低网络开销
+  - 需要详细信息时可按需设置 `fields='full'`
+
 ## [1.12.0] - 2025-11-07
 
 ### Added

package/dist/api/zentaoApi.d.ts

@@ -8,7 +8,24 @@ export declare class ZentaoAPI {
     private request;
     getMyTasks(status?: TaskStatus): Promise<Task[]>;
     getTaskDetail(taskId: number): Promise<Task>;
-    getProducts(): Promise<Product[]>;
+    /**
+     * 过滤产品字段
+     * @param product 原始产品对象
+     * @param fields 字段级别
+     */
+    private filterProductFields;
+    /**
+     * 过滤需求字段
+     * @param story 原始需求对象
+     * @param fields 字段级别
+     */
+    private filterStoryFields;
+    /**
+     * 获取产品列表
+     * @param fields 返回字段级别（'basic'基本/'default'默认/'full'完整，默认'default'）
+     * @returns Promise<产品列表>
+     */
+    getProducts(fields?: 'basic' | 'default' | 'full'): Promise<Product[]>;
     /**
      * 过滤 Bug 字段
      * @param bug 原始 Bug 对象
@@ -88,7 +105,15 @@ export declare class ZentaoAPI {
     deleteTask(taskId: number): Promise<{
         message: string;
     }>;
-    getProductStories(productId: number, page?: number, limit?: number): Promise<{
+    /**
+     * 获取产品需求列表
+     * @param productId 产品ID
+     * @param page 页码（从1开始，默认1）
+     * @param limit 每页数量（默认20，最大100）
+     * @param fields 返回字段级别（'basic'基本/'default'默认/'full'完整，默认'basic'）
+     * @returns Promise<需求列表及分页信息>
+     */
+    getProductStories(productId: number, page?: number, limit?: number, fields?: 'basic' | 'default' | 'full'): Promise<{
         page: number;
         total: number;
         limit: number;

package/dist/api/zentaoApi.js

@@ -91,20 +91,95 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async getProducts() {
+    /**
+     * 过滤产品字段
+     * @param product 原始产品对象
+     * @param fields 字段级别
+     */
+    filterProductFields(product, fields) {
+        if (fields === 'full') {
+            return product;
+        }
+        if (fields === 'basic') {
+            // 基本信息：只返回核心字段
+            return {
+                id: product.id,
+                name: product.name,
+                code: product.code,
+                status: product.status
+            };
+        }
+        // default: 默认字段（id, 名称, 状态, 负责人）
+        return {
+            id: product.id,
+            name: product.name,
+            code: product.code,
+            status: product.status,
+            type: product.type,
+            PO: product.PO,
+            QD: product.QD,
+            RD: product.RD,
+            createdBy: product.createdBy,
+            createdDate: product.createdDate
+        };
+    }
+    /**
+     * 过滤需求字段
+     * @param story 原始需求对象
+     * @param fields 字段级别
+     */
+    filterStoryFields(story, fields) {
+        if (fields === 'full') {
+            return story;
+        }
+        if (fields === 'basic') {
+            // 基本信息：只返回核心字段
+            return {
+                id: story.id,
+                title: story.title,
+                assignedTo: story.assignedTo,
+                openedBy: story.openedBy
+            };
+        }
+        // default: 默认字段（id, 标题, 状态, 指派人, 创建人）
+        return {
+            id: story.id,
+            title: story.title,
+            status: story.status,
+            stage: story.stage,
+            pri: story.pri,
+            assignedTo: story.assignedTo,
+            openedBy: story.openedBy,
+            openedDate: story.openedDate,
+            estimate: story.estimate,
+            product: story.product,
+            plan: story.plan
+        };
+    }
+    /**
+     * 获取产品列表
+     * @param fields 返回字段级别（'basic'基本/'default'默认/'full'完整，默认'default'）
+     * @returns Promise<产品列表>
+     */
+    async getProducts(fields) {
         try {
-            console.log('正在获取产品列表...');
+            const finalFields = fields || 'default';
+            console.log(`正在获取产品列表 (fields=${finalFields})...`);
             const response = await this.request('GET', '/products');
             console.log('产品列表响应:', response);
+            let products = [];
             if (Array.isArray(response)) {
-                return response;
+                products = response;
             }
-            else if (response && typeof response === 'object') {
-                if (Array.isArray(response.products)) {
-                    return response.products;
-                }
+            else if (response && typeof response === 'object' && Array.isArray(response.products)) {
+                products = response.products;
+            }
+            else {
+                throw new Error(`获取产品列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
             }
-            throw new Error(`获取产品列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
+            // 应用字段过滤
+            const filteredProducts = products.map(product => this.filterProductFields(product, finalFields));
+            return filteredProducts;
         }
         catch (error) {
             console.error('获取产品列表失败:', error);
@@ -746,38 +821,55 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async getProductStories(productId, page, limit) {
+    /**
+     * 获取产品需求列表
+     * @param productId 产品ID
+     * @param page 页码（从1开始，默认1）
+     * @param limit 每页数量（默认20，最大100）
+     * @param fields 返回字段级别（'basic'基本/'default'默认/'full'完整，默认'basic'）
+     * @returns Promise<需求列表及分页信息>
+     */
+    async getProductStories(productId, page, limit, fields) {
         try {
             // 默认每页20条，最多100条
             const finalLimit = limit ? Math.min(limit, 100) : 20;
             const finalPage = page || 1;
-            console.log(`正在获取产品 ${productId} 的需求列表 (page=${finalPage}, limit=${finalLimit})...`);
+            const finalFields = fields || 'basic'; // 默认只返回基本字段
+            console.log(`正在获取产品 ${productId} 的需求列表 (page=${finalPage}, limit=${finalLimit}, fields=${finalFields})...`);
             // 构建查询参数
             const queryParams = new URLSearchParams();
             queryParams.append('page', finalPage.toString());
             queryParams.append('limit', finalLimit.toString());
             const response = await this.request('GET', `/products/${productId}/stories?${queryParams.toString()}`);
             console.log(`产品需求列表响应: 获取到 ${response.stories?.length || 0} 条数据`);
+            let stories = [];
+            if (Array.isArray(response)) {
+                stories = response;
+            }
+            else if (response && typeof response === 'object' && Array.isArray(response.stories)) {
+                stories = response.stories;
+            }
+            else {
+                throw new Error(`获取产品需求列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
+            }
+            // 应用字段过滤
+            const filteredStories = stories.map(story => this.filterStoryFields(story, finalFields));
             if (Array.isArray(response)) {
-                // 如果返回的是数组，转换为标准格式
                 return {
                     page: finalPage,
-                    total: response.length,
+                    total: filteredStories.length,
                     limit: finalLimit,
-                    stories: response
+                    stories: filteredStories
                 };
             }
-            else if (response && typeof response === 'object') {
-                if (Array.isArray(response.stories)) {
-                    return {
-                        page: response.page || finalPage,
-                        total: response.total || response.stories.length,
-                        limit: response.limit || finalLimit,
-                        stories: response.stories
-                    };
-                }
+            else {
+                return {
+                    page: response.page || finalPage,
+                    total: response.total || filteredStories.length,
+                    limit: response.limit || finalLimit,
+                    stories: filteredStories
+                };
             }
-            throw new Error(`获取产品需求列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
         }
         catch (error) {
             console.error('获取产品需求列表失败:', error);

package/dist/index.js

@@ -78,10 +78,12 @@ server.tool("getTaskDetail", {
     };
 });
 // Add getProducts tool
-server.tool("getProducts", {}, async () => {
+server.tool("getProducts", "获取产品列表 - 只返回核心字段（id, 名称, 负责人）", {
+    fields: z.enum(['basic', 'default', 'full']).optional().describe("返回字段级别：'basic'(id/名称/状态)、'default'(+负责人/创建人,默认)、'full'(完整字段)")
+}, async ({ fields }) => {
     if (!zentaoApi)
         throw new Error("Please initialize Zentao API first");
-    const products = await zentaoApi.getProducts();
+    const products = await zentaoApi.getProducts(fields);
     return {
         content: [{ type: "text", text: JSON.stringify(products, null, 2) }]
     };
@@ -669,14 +671,15 @@ server.tool("deleteTask", {
     };
 });
 // Add getProductStories tool
-server.tool("getProductStories", {
+server.tool("getProductStories", "获取产品需求列表 - 默认只返回核心字段（id, 标题, 指派人, 创建人）", {
     productId: z.number(),
     page: z.number().optional().describe("页码，从1开始，默认为1"),
-    limit: z.number().optional().describe("每页数量，默认20，最大100")
-}, async ({ productId, page, limit }) => {
+    limit: z.number().optional().describe("每页数量，默认20，最大100"),
+    fields: z.enum(['basic', 'default', 'full']).optional().describe("字段级别:\n- basic: 基本信息(id, title, assignedTo, openedBy)\n- default: 常用信息(包含basic + status, stage, pri等)\n- full: 完整信息(所有字段)")
+}, async ({ productId, page, limit, fields }) => {
     if (!zentaoApi)
         throw new Error("Please initialize Zentao API first");
-    const result = await zentaoApi.getProductStories(productId, page, limit);
+    const result = await zentaoApi.getProductStories(productId, page, limit, fields);
     // 返回分页信息和数据
     const summary = {
         summary: `当前第 ${result.page} 页，共 ${result.total} 条需求，本页显示 ${result.stories.length} 条`,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zzp123/mcp-zentao",
-    "version": "1.12.0",
+    "version": "1.13.0",
     "description": "禅道项目管理系统的高级API集成包，提供任务管理、Bug跟踪等功能的完整封装，专为Cursor IDE设计的MCP扩展",
     "main": "dist/index.js",
     "type": "module",