@zzp123/mcp-zentao 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.14.0] - 2025-11-07
+
+### Added
+- **完整的用户需求(Requirement)支持** 🎯
+  - 扩展 Story API，统一支持软件需求(story)和用户需求(requirement)
+  - 所有现有 story 工具现已支持两种需求类型，自动识别
+  - 新增4个专用的 requirement 工具：
+    - `createRequirement`: 创建用户需求
+    - `getRequirementDetail`: 获取用户需求详情
+    - `changeRequirement`: 修改用户需求
+    - `deleteRequirement`: 删除用户需求
+  - `createStory` 工具新增 `type` 参数，可选择创建 story 或 requirement
+
+### Changed
+- **更新现有需求工具描述**
+  - `getStoryDetail`: 现支持 story 和 requirement 两种类型，自动识别
+  - `changeStory`: 现支持 story 和 requirement 两种类型，自动识别
+  - `deleteStory`: 现支持 story 和 requirement 两种类型，自动识别
+  - `getProductStories`: 返回的列表可能包含两种类型的需求
+
+### Improved
+- **更好的语义化**
+  - 专用的 requirement 工具提供更清晰的意图表达
+  - 统一接口底层实现，减少代码重复
+  - 符合禅道 API v2.0 的最新扩展
+
+## [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) }]
     };
@@ -333,10 +335,11 @@ server.tool("createTask", {
     };
 });
 // Add createStory tool
-server.tool("createStory", {
+server.tool("createStory", "创建需求 - 支持创建软件需求(story)或用户需求(requirement)", {
     title: z.string(),
     product: z.number(),
     pri: z.number(),
+    type: z.enum(['story', 'requirement']).optional().describe("需求类型：story=软件需求，requirement=用户需求，默认为story"),
     category: z.string().optional(),
     spec: z.string().optional(),
     verify: z.string().optional(),
@@ -344,13 +347,14 @@ server.tool("createStory", {
     sourceNote: z.string().optional(),
     estimate: z.number().optional(),
     keywords: z.string().optional()
-}, async ({ title, product, pri, category, spec, verify, source, sourceNote, estimate, keywords }) => {
+}, async ({ title, product, pri, type, category, spec, verify, source, sourceNote, estimate, keywords }) => {
     if (!zentaoApi)
         throw new Error("Please initialize Zentao API first");
     const story = await zentaoApi.createStory({
         title,
         product,
         pri,
+        type,
         category,
         spec,
         verify,
@@ -463,8 +467,8 @@ server.tool("getProjectReleases", {
     };
 });
 // Add getStoryDetail tool
-server.tool("getStoryDetail", {
-    storyId: z.number(),
+server.tool("getStoryDetail", "获取需求详情 - 支持软件需求(story)和用户需求(requirement)，自动识别类型", {
+    storyId: z.number().describe("需求ID（可以是story或requirement类型）"),
     fields: z.enum(['basic', 'detail', 'full']).optional().describe(`
 字段级别：
 - basic: 基本信息（id, title, status, stage, pri等核心字段）
@@ -583,8 +587,8 @@ server.tool("getProjects", {
     };
 });
 // Add changeStory tool
-server.tool("changeStory", "需求变更 - 支持对象或JSON字符串格式", {
-    storyId: z.number().describe("需求ID"),
+server.tool("changeStory", "需求变更 - 支持软件需求(story)和用户需求(requirement)，自动识别类型。支持对象或JSON字符串格式", {
+    storyId: z.number().describe("需求ID（可以是story或requirement类型）"),
     update: z.union([
         z.object({
             // 基本信息
@@ -669,14 +673,15 @@ server.tool("deleteTask", {
     };
 });
 // Add getProductStories tool
-server.tool("getProductStories", {
+server.tool("getProductStories", "获取产品需求列表 - 包含软件需求(story)和用户需求(requirement)，默认只返回核心字段（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} 条`,
@@ -828,11 +833,128 @@ server.tool("deleteExecution", { executionId: z.number() }, async ({ executionId
     return { content: [{ type: "text", text: JSON.stringify(await zentaoApi.deleteExecution(executionId), null, 2) }] };
 });
 // Story tools
-server.tool("deleteStory", { storyId: z.number() }, async ({ storyId }) => {
+server.tool("deleteStory", "删除需求 - 支持软件需求(story)和用户需求(requirement)，自动识别类型", {
+    storyId: z.number().describe("需求ID（可以是story或requirement类型）")
+}, async ({ storyId }) => {
     if (!zentaoApi)
         throw new Error("Please initialize Zentao API first");
     return { content: [{ type: "text", text: JSON.stringify(await zentaoApi.deleteStory(storyId), null, 2) }] };
 });
+// Requirement tools (用户需求专用工具 - 提供更好的语义化)
+server.tool("createRequirement", "创建用户需求(requirement) - 用户需求的专用接口，提供更好的语义化", {
+    title: z.string(),
+    product: z.number(),
+    pri: z.number(),
+    category: z.string().optional(),
+    spec: z.string().optional(),
+    verify: z.string().optional(),
+    source: z.string().optional(),
+    sourceNote: z.string().optional(),
+    estimate: z.number().optional(),
+    keywords: z.string().optional()
+}, async ({ title, product, pri, category, spec, verify, source, sourceNote, estimate, keywords }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    // 调用 createStory 但强制设置 type='requirement'
+    const requirement = await zentaoApi.createStory({
+        title,
+        product,
+        pri,
+        type: 'requirement',
+        category,
+        spec,
+        verify,
+        source,
+        sourceNote,
+        estimate,
+        keywords
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify(requirement, null, 2) }]
+    };
+});
+server.tool("getRequirementDetail", "获取用户需求详情 - 用户需求的专用接口，提供更好的语义化", {
+    requirementId: z.number().describe("用户需求ID"),
+    fields: z.enum(['basic', 'detail', 'full']).optional().describe(`
+字段级别：
+- basic: 基本信息（id, title, status, stage, pri等核心字段）
+- detail: 详细信息（包含spec和verify，但不包含executions/tasks/stages/children等关联数据）
+- full: 完整信息（包含所有字段，默认值）
+        `.trim())
+}, async ({ requirementId, fields }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const requirement = await zentaoApi.getStoryDetail(requirementId, fields);
+    const result = {
+        fieldLevel: fields || 'full',
+        requirement: requirement
+    };
+    if (fields === 'basic') {
+        result.note = '仅显示基本信息，如需完整内容请使用 fields=detail 或 fields=full';
+    }
+    else if (fields === 'detail') {
+        result.note = '显示详细信息但不包含关联数据（executions/tasks/stages/children），如需完整内容请使用 fields=full';
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+});
+server.tool("changeRequirement", "用户需求变更 - 用户需求的专用接口，提供更好的语义化", {
+    requirementId: z.number().describe("用户需求ID"),
+    update: z.union([
+        z.object({
+            title: z.string().optional(),
+            product: z.number().optional(),
+            parent: z.number().optional(),
+            module: z.number().optional(),
+            pri: z.number().optional(),
+            category: z.string().optional(),
+            spec: z.string().optional(),
+            verify: z.string().optional(),
+            source: z.string().optional(),
+            sourceNote: z.string().optional(),
+            estimate: z.number().optional(),
+            keywords: z.string().optional(),
+            assignedTo: z.string().optional(),
+            reviewer: z.array(z.string()).optional(),
+            comment: z.string().optional()
+        }),
+        z.string().describe("JSON字符串格式的更新内容")
+    ]).describe(`
+更新用户需求（使用 PUT /stories/:id 接口）
+
+此工具使用标准的"修改需求其他字段"接口(PUT /stories/:id),支持修改多个字段。
+自动处理评审人问题,无需手动设置 needNotReview。
+
+支持对象或JSON字符串格式。
+        `.trim())
+}, async ({ requirementId, update }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    let updateData;
+    if (typeof update === 'string') {
+        try {
+            updateData = JSON.parse(update);
+        }
+        catch (e) {
+            throw new Error('Invalid JSON string for update parameter');
+        }
+    }
+    else {
+        updateData = update;
+    }
+    const requirement = await zentaoApi.changeStory(requirementId, updateData);
+    return {
+        content: [{ type: "text", text: JSON.stringify(requirement, null, 2) }]
+    };
+});
+server.tool("deleteRequirement", "删除用户需求 - 用户需求的专用接口，提供更好的语义化", {
+    requirementId: z.number().describe("用户需求ID")
+}, async ({ requirementId }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    return { content: [{ type: "text", text: JSON.stringify(await zentaoApi.deleteStory(requirementId), null, 2) }] };
+});
 // Bug tools
 server.tool("updateBug", {
     bugId: z.number(),

package/dist/types/zentao.d.ts

@@ -180,6 +180,7 @@ export interface CreateStoryRequest {
     title: string;
     product: number;
     pri: number;
+    type?: 'story' | 'requirement';
     category?: string;
     spec?: string;
     verify?: string;

package/package.json

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