@zzp123/mcp-zentao 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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.11.0] - 2025-11-07
+
+### Added
+- **完整的 Bug 状态筛选支持** ✨
+  - 扩展 `BugStatus` 类型，新增 16 种状态筛选类型
+  - 支持所有禅道官方 API 的状态筛选：assigntome、openedbyme、resolvedbyme、assignedbyme、assigntonull、unconfirmed、unclosed、unresolved、toclosed、postponedbugs、longlifebugs、overduebugs、review、feedback、needconfirm、bysearch
+  - MCP 工具现在提供完整的 20 种状态选项供选择
+
+- **分支筛选功能** 🌿
+  - 为 `getMyBugs` 和 `getProductBugs` 添加 `branch` 参数
+  - 支持 'all'(所有分支)、'0'(主干分支)、分支ID
+  - 默认值为 'all'，符合禅道官方 API 规范
+
+### Changed
+- **重构 Bug 列表 API 参数** 🔄
+  - 移除 `onlyAssignedToMe` 参数，改用更灵活的 `status='assigntome'`
+  - 调整参数顺序：`status, productId, page, limit, branch, order`
+  - 优化参数构建逻辑，确保与禅道官方 API 完全一致
+
+### Improved
+- **API 文档完善**
+  - 为 `getMyBugs` 和 `getProductBugs` 添加详细的 JSDoc 注释
+  - 更新工具描述，明确说明支持的状态筛选类型
+  - 参数说明更加清晰，包含默认值和示例
+
+- **更好的用户体验**
+  - MCP 工具提供完整的状态枚举，IDE 可以自动补全
+  - 所有状态选项都有中文注释说明
+  - 更符合禅道用户的使用习惯
+
+### Technical
+- 完全符合禅道官方 Bug 列表 API 文档规范
+- 支持所有官方 API 参数：branch、status、order、limit、page
+- 默认值与官方 API 保持一致
+
+## [1.10.0] - 2025-11-07
+
+### Fixed
+- **修复 Bug 获取工具的 API 端点和参数问题** 🔧
+  - 从错误的 `/bugs` 端点改为正确的 `/products/{productId}/bugs` 端点
+  - 移除了低效的客户端过滤逻辑，改用服务器端原生支持的 `assigntome` 状态
+  - 修复了 `onlyAssignedToMe` 参数无法正确工作的问题
+
+### Added
+- **添加排序参数支持** ✨
+  - 为 `getMyBugs` 和 `getProductBugs` 工具添加 `order` 参数
+  - 支持多种排序方式：`id_desc`(ID降序)、`id_asc`(ID升序)、`pri_desc`(优先级降序)等
+  - 默认使用 `id_desc` 排序，确保最新的 Bug 显示在前面
+  - 与禅道官方 API 完全一致的参数格式
+
+### Improved
+- **性能优化**
+  - 使用服务器端过滤替代客户端过滤，显著提升查询效率
+  - 减少不必要的数据传输，降低网络开销
+  - 更准确的分页信息和总数统计
+
+### Changed
+- 更新了 `getMyBugs` 方法签名，添加 `order` 参数
+- 更新了 `getProductBugs` 方法签名，添加 `order` 参数
+- 优化了查询参数的构建方式，使用 URLSearchParams 确保参数正确编码
+
 ## [1.9.0] - 2025-11-06
 
 ### Fixed

package/README.md

@@ -15,17 +15,17 @@ npm install @zzp123/mcp-zentao -g
 
 查看完整的版本更新历史，请访问 [CHANGELOG.md](./CHANGELOG.md)
 
-**最新版本**: v1.6.1
-- 修复 Windows 剪贴板图片读取问题
-- 使用新的 PowerShell 脚本确保正确读取剪贴板图片
-- 改进错误处理和日志输出
-
-**主要版本**:
-- v1.4.1 - 修复 uploadImageFromClipboard 返回值问题
+**最新版本**: v1.9.0
+- ✅ 修复 getMyBugs 工具的过滤逻辑问题
+- ✅ 改为客户端过滤，正确获取当前用户的bug
+- ✅ 支持 assignedTo 的对象和字符串两种格式
+
+**近期版本**:
+- v1.8.9 - 修复 resolveBug 工具自动设置默认 resolvedBuild
+- v1.8.8 - 修复 getMyBugs 工具返回Bug数量为0的问题
+- v1.6.1 - 修复 Windows 剪贴板图片读取问题
 - v1.4.0 - 新增解决Bug接口
-- v1.3.1 - 修复剪贴板图片上传核心问题
 - v1.3.0 - 添加命令行脚本支持
-- v1.2.0 - 添加文件上传/下载功能
 
 ## 使用方法
 

package/dist/api/zentaoApi.d.ts

@@ -9,13 +9,35 @@ export declare class ZentaoAPI {
     getMyTasks(status?: TaskStatus): Promise<Task[]>;
     getTaskDetail(taskId: number): Promise<Task>;
     getProducts(): Promise<Product[]>;
-    getMyBugs(status?: BugStatus, productId?: number, page?: number, limit?: number, onlyAssignedToMe?: boolean): Promise<{
+    /**
+     * 获取 Bug 列表
+     *
+     * @param status Bug状态筛选（支持多种状态，详见BugStatus类型）
+     * @param productId 产品ID（可选，默认使用第二个产品）
+     * @param page 页码（从1开始，默认1）
+     * @param limit 每页数量（默认20，最大100）
+     * @param branch 分支筛选（'all'所有分支/'0'主干/分支ID，默认'all'）
+     * @param order 排序字段（如：'id_desc'、'pri_desc'等，默认'id_desc'）
+     * @returns Promise<Bug列表及分页信息>
+     */
+    getMyBugs(status?: BugStatus, productId?: number, page?: number, limit?: number, branch?: string, order?: string): Promise<{
         page: number;
         total: number;
         limit: number;
         bugs: Bug[];
     }>;
-    getProductBugs(productId: number, page?: number, limit?: number, status?: BugStatus): Promise<{
+    /**
+     * 获取产品 Bug 列表
+     *
+     * @param productId 产品ID（必填）
+     * @param page 页码（从1开始，默认1）
+     * @param limit 每页数量（默认20，最大100）
+     * @param status Bug状态筛选（支持多种状态，详见BugStatus类型）
+     * @param branch 分支筛选（'all'所有分支/'0'主干/分支ID，默认'all'）
+     * @param order 排序字段（如：'id_desc'、'pri_desc'等，默认'id_desc'）
+     * @returns Promise<Bug列表及分页信息>
+     */
+    getProductBugs(productId: number, page?: number, limit?: number, status?: BugStatus, branch?: string, order?: string): Promise<{
         page: number;
         total: number;
         limit: number;

package/dist/api/zentaoApi.js

@@ -111,7 +111,18 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async getMyBugs(status, productId, page, limit, onlyAssignedToMe = false) {
+    /**
+     * 获取 Bug 列表
+     *
+     * @param status Bug状态筛选（支持多种状态，详见BugStatus类型）
+     * @param productId 产品ID（可选，默认使用第二个产品）
+     * @param page 页码（从1开始，默认1）
+     * @param limit 每页数量（默认20，最大100）
+     * @param branch 分支筛选（'all'所有分支/'0'主干/分支ID，默认'all'）
+     * @param order 排序字段（如：'id_desc'、'pri_desc'等，默认'id_desc'）
+     * @returns Promise<Bug列表及分页信息>
+     */
+    async getMyBugs(status, productId, page, limit, branch, order) {
         if (!productId) {
             // 如果没有提供产品ID，获取第二个可用的产品（索引为1）
             const products = await this.getProducts();
@@ -125,72 +136,74 @@ export class ZentaoAPI {
         // 默认每页20条，最多100条
         const finalLimit = limit ? Math.min(limit, 100) : 20;
         const finalPage = page || 1;
-        // 禅道API的/bugs接口不支持assignedTo参数过滤，需要客户端过滤
-        // 所以获取更多数据以确保有足够的结果
-        const fetchLimit = onlyAssignedToMe ? 100 : finalLimit;
-        const params = {
-            status: status || 'all',
-            product: productId,
-            page: 1,
-            limit: fetchLimit
-        };
-        try {
-            console.log(`正在获取Bug列表，参数:`, params);
-            const response = await this.request('GET', '/bugs', params);
+        const finalBranch = branch || 'all';
+        const finalOrder = order || 'id_desc';
+        // 构建查询参数
+        const queryParams = new URLSearchParams();
+        queryParams.append('branch', finalBranch);
+        queryParams.append('page', finalPage.toString());
+        queryParams.append('limit', finalLimit.toString());
+        queryParams.append('order', finalOrder);
+        // 添加状态筛选
+        if (status && status !== 'all') {
+            queryParams.append('status', status);
+        }
+        try {
+            console.log(`正在获取产品 ${productId} 的Bug列表，参数: status=${status || 'all'}, branch=${finalBranch}, page=${finalPage}, limit=${finalLimit}, order=${finalOrder}`);
+            const response = await this.request('GET', `/products/${productId}/bugs?${queryParams.toString()}`);
             console.log(`Bug列表响应: 获取到 ${response.bugs?.length || 0} 条数据`);
-            let bugs = [];
             if (Array.isArray(response)) {
-                bugs = response;
-            }
-            else if (response && typeof response === 'object' && Array.isArray(response.bugs)) {
-                bugs = response.bugs;
-            }
-            else {
-                throw new Error(`获取Bug列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
+                // 如果返回的是数组，转换为标准格式
+                return {
+                    page: finalPage,
+                    total: response.length,
+                    limit: finalLimit,
+                    bugs: response
+                };
             }
-            // 如果需要过滤分配给当前用户的bug，在客户端进行过滤
-            if (onlyAssignedToMe) {
-                console.log(`客户端过滤：只保留分配给 ${this.config.username} 的Bug`);
-                bugs = bugs.filter(bug => {
-                    // assignedTo可能是对象或字符串
-                    if (typeof bug.assignedTo === 'object' && bug.assignedTo !== null) {
-                        return bug.assignedTo.account === this.config.username;
-                    }
-                    else if (typeof bug.assignedTo === 'string') {
-                        return bug.assignedTo === this.config.username;
-                    }
-                    return false;
-                });
-                console.log(`过滤后剩余 ${bugs.length} 个Bug`);
+            else if (response && typeof response === 'object') {
+                if (Array.isArray(response.bugs)) {
+                    return {
+                        page: response.page || finalPage,
+                        total: response.total || response.bugs.length,
+                        limit: response.limit || finalLimit,
+                        bugs: response.bugs
+                    };
+                }
             }
-            // 应用分页
-            const start = (finalPage - 1) * finalLimit;
-            const paginatedBugs = bugs.slice(start, start + finalLimit);
-            return {
-                page: finalPage,
-                total: bugs.length,
-                limit: finalLimit,
-                bugs: paginatedBugs
-            };
+            throw new Error(`获取Bug列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
         }
         catch (error) {
-            if (error instanceof Error && error.message.includes('Need product id')) {
-                throw new Error('获取Bug列表失败: 请提供产品ID');
-            }
             console.error('获取Bug列表失败:', error);
             throw error;
         }
     }
-    async getProductBugs(productId, page, limit, status) {
+    /**
+     * 获取产品 Bug 列表
+     *
+     * @param productId 产品ID（必填）
+     * @param page 页码（从1开始，默认1）
+     * @param limit 每页数量（默认20，最大100）
+     * @param status Bug状态筛选（支持多种状态，详见BugStatus类型）
+     * @param branch 分支筛选（'all'所有分支/'0'主干/分支ID，默认'all'）
+     * @param order 排序字段（如：'id_desc'、'pri_desc'等，默认'id_desc'）
+     * @returns Promise<Bug列表及分页信息>
+     */
+    async getProductBugs(productId, page, limit, status, branch, order) {
         try {
             // 默认每页20条，最多100条
             const finalLimit = limit ? Math.min(limit, 100) : 20;
             const finalPage = page || 1;
-            console.log(`正在获取产品 ${productId} 的Bug列表 (page=${finalPage}, limit=${finalLimit})...`);
+            const finalBranch = branch || 'all';
+            const finalOrder = order || 'id_desc';
+            console.log(`正在获取产品 ${productId} 的Bug列表 (status=${status || 'all'}, branch=${finalBranch}, page=${finalPage}, limit=${finalLimit}, order=${finalOrder})...`);
             // 构建查询参数
             const queryParams = new URLSearchParams();
+            queryParams.append('branch', finalBranch);
             queryParams.append('page', finalPage.toString());
             queryParams.append('limit', finalLimit.toString());
+            queryParams.append('order', finalOrder);
+            // 添加状态筛选
             if (status && status !== 'all') {
                 queryParams.append('status', status);
             }

package/dist/index.js

@@ -87,16 +87,38 @@ server.tool("getProducts", {}, async () => {
     };
 });
 // Add getMyBugs tool
-server.tool("getMyBugs", "获取Bug列表 - 默认获取所有Bug，可选择只获取分配给我的Bug", {
-    status: z.enum(['active', 'resolved', 'closed', 'all']).optional(),
-    productId: z.number().optional(),
+server.tool("getMyBugs", "获取Bug列表 - 支持多种状态筛选（指派给我、由我创建、未关闭等）和分支筛选", {
+    status: z.enum([
+        'active', // 激活状态
+        'resolved', // 已解决
+        'closed', // 已关闭
+        'all', // 所有状态
+        'assigntome', // 指派给我的
+        'openedbyme', // 由我创建
+        'resolvedbyme', // 由我解决
+        'assignedbyme', // 由我指派
+        'assigntonull', // 未指派
+        'unconfirmed', // 未确认
+        'unclosed', // 未关闭
+        'unresolved', // 未解决(激活状态)
+        'toclosed', // 待关闭(已解决)
+        'postponedbugs', // 延期的Bug
+        'longlifebugs', // 长期未处理的Bug
+        'overduebugs', // 已过期的Bug
+        'review', // 待我审核
+        'feedback', // 用户反馈
+        'needconfirm', // 需求变更需确认
+        'bysearch' // 自定义搜索
+    ]).optional().describe("Bug状态筛选，默认返回所有状态"),
+    productId: z.number().optional().describe("产品ID，默认使用第二个产品"),
     page: z.number().optional().describe("页码，从1开始，默认为1"),
     limit: z.number().optional().describe("每页数量，默认20，最大100"),
-    onlyAssignedToMe: z.boolean().optional().describe("是否只获取分配给我的Bug，默认false（获取所有Bug）")
-}, async ({ status, productId, page, limit, onlyAssignedToMe }) => {
+    branch: z.string().optional().describe("分支筛选：'all'(所有分支,默认)、'0'(主干分支)、分支ID"),
+    order: z.string().optional().describe("排序方式，如 id_desc(ID降序), pri_desc(优先级降序), openedDate_desc(创建时间降序)等，默认id_desc")
+}, async ({ status, productId, page, limit, branch, order }) => {
     if (!zentaoApi)
         throw new Error("Please initialize Zentao API first");
-    const result = await zentaoApi.getMyBugs(status, productId, page, limit, onlyAssignedToMe || false);
+    const result = await zentaoApi.getMyBugs(status, productId, page, limit, branch, order);
     // 返回分页信息和数据
     const summary = {
         summary: `当前第 ${result.page} 页，共 ${result.total} 个Bug，本页显示 ${result.bugs.length} 个`,
@@ -113,15 +135,38 @@ server.tool("getMyBugs", "获取Bug列表 - 默认获取所有Bug，可选择只
     };
 });
 // Add getProductBugs tool
-server.tool("getProductBugs", {
-    productId: z.number(),
+server.tool("getProductBugs", "获取指定产品的Bug列表 - 支持多种状态筛选和分支筛选", {
+    productId: z.number().describe("产品ID（必填）"),
     page: z.number().optional().describe("页码，从1开始，默认为1"),
     limit: z.number().optional().describe("每页数量，默认20，最大100"),
-    status: z.enum(['active', 'resolved', 'closed', 'all']).optional()
-}, async ({ productId, page, limit, status }) => {
-    if (!zentaoApi)
-        throw new Error("Please initialize Zentao API first");
-    const result = await zentaoApi.getProductBugs(productId, page, limit, status);
+    status: z.enum([
+        'active', // 激活状态
+        'resolved', // 已解决
+        'closed', // 已关闭
+        'all', // 所有状态
+        'assigntome', // 指派给我的
+        'openedbyme', // 由我创建
+        'resolvedbyme', // 由我解决
+        'assignedbyme', // 由我指派
+        'assigntonull', // 未指派
+        'unconfirmed', // 未确认
+        'unclosed', // 未关闭
+        'unresolved', // 未解决(激活状态)
+        'toclosed', // 待关闭(已解决)
+        'postponedbugs', // 延期的Bug
+        'longlifebugs', // 长期未处理的Bug
+        'overduebugs', // 已过期的Bug
+        'review', // 待我审核
+        'feedback', // 用户反馈
+        'needconfirm', // 需求变更需确认
+        'bysearch' // 自定义搜索
+    ]).optional().describe("Bug状态筛选，默认返回所有状态"),
+    branch: z.string().optional().describe("分支筛选：'all'(所有分支,默认)、'0'(主干分支)、分支ID"),
+    order: z.string().optional().describe("排序方式，如 id_desc(ID降序), pri_desc(优先级降序), openedDate_desc(创建时间降序)等，默认id_desc")
+}, async ({ productId, page, limit, status, branch, order }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const result = await zentaoApi.getProductBugs(productId, page, limit, status, branch, order);
     // 返回分页信息和数据
     const summary = {
         summary: `当前第 ${result.page} 页，共 ${result.total} 个Bug，本页显示 ${result.bugs.length} 个`,

package/dist/types/zentao.d.ts

@@ -56,7 +56,34 @@ export interface TaskUpdate {
     comment?: string;
 }
 export type TaskStatus = 'wait' | 'doing' | 'done' | 'all';
-export type BugStatus = 'active' | 'resolved' | 'closed' | 'all';
+/**
+ * Bug 状态筛选类型
+ *
+ * 基础状态:
+ * - active: 激活状态
+ * - resolved: 已解决
+ * - closed: 已关闭
+ * - all: 所有状态
+ *
+ * 筛选条件:
+ * - assigntome: 指派给我的
+ * - openedbyme: 由我创建
+ * - resolvedbyme: 由我解决
+ * - assignedbyme: 由我指派
+ * - assigntonull: 未指派
+ * - unconfirmed: 未确认
+ * - unclosed: 未关闭
+ * - unresolved: 未解决(激活状态)
+ * - toclosed: 待关闭(已解决)
+ * - postponedbugs: 延期的Bug
+ * - longlifebugs: 长期未处理的Bug
+ * - overduebugs: 已过期的Bug
+ * - review: 待我审核
+ * - feedback: 用户反馈
+ * - needconfirm: 需求变更需确认
+ * - bysearch: 自定义搜索(需配合queryID使用)
+ */
+export type BugStatus = 'active' | 'resolved' | 'closed' | 'all' | 'assigntome' | 'openedbyme' | 'resolvedbyme' | 'assignedbyme' | 'assigntonull' | 'unconfirmed' | 'unclosed' | 'unresolved' | 'toclosed' | 'postponedbugs' | 'longlifebugs' | 'overduebugs' | 'review' | 'feedback' | 'needconfirm' | 'bysearch';
 export type ResolutionType = 'fixed' | 'bydesign' | 'duplicate' | 'external' | 'notrepro' | 'postponed' | 'willnotfix';
 export interface ResolveBugRequest {
     resolution: ResolutionType;

package/package.json

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