@zzp123/mcp-zentao 1.7.4 → 1.8.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.8.0] - 2025-11-06
+
+### Changed
+- **重构需求变更接口命名**
+  - 将 `updateStory` 工具重命名为 `changeStory`，更准确地反映其功能
+  - 将 `UpdateStoryRequest` 类型重命名为 `ChangeStoryRequest`
+  - 将 `updateStory` API方法重命名为 `changeStory`
+  - 使用功能完整的"修改需求其他字段"接口替代功能有限的"变更需求"接口
+
+### Added
+- 向后兼容的类型别名：`UpdateStoryRequest` 作为 `ChangeStoryRequest` 的别名
+
+### Technical
+- 统一需求变更相关的命名规范
+- 保持向后兼容性，旧的类型名称仍然可用
+- 所有测试通过，确保重构不影响现有功能
+
 ## [1.7.4] - 2025-11-06
 
 ### Fixed

package/dist/api/zentaoApi.d.ts

@@ -1,4 +1,4 @@
-import { AssignFeedbackRequest, Bug, BugStatus, Build, CloseFeedbackRequest, CreateBuildRequest, CreateBugRequest, CreateExecutionRequest, CreateFeedbackRequest, CreatePlanRequest, CreateProductRequest, CreateProgramRequest, CreateProjectRequest, CreateStoryRequest, CreateTaskRequest, CreateTestCaseRequest, CreateTicketRequest, CreateUserRequest, Execution, Feedback, FileUploadResponse, ModulesResponse, ModuleType, Plan, Product, Program, Project, Release, ResolveBugRequest, Story, Task, TaskStatus, TaskUpdate, TestCase, Ticket, UpdateBuildRequest, UpdateBugRequest, UpdateExecutionRequest, UpdateFeedbackRequest, UpdatePlanRequest, UpdateProductRequest, UpdateProgramRequest, UpdateProjectRequest, UpdateStoryRequest, UpdateTestCaseRequest, UpdateTicketRequest, UpdateUserRequest, UploadFileRequest, UserDetail, ZentaoConfig } from '../types/zentao';
+import { AssignFeedbackRequest, Bug, BugStatus, Build, CloseFeedbackRequest, CreateBuildRequest, CreateBugRequest, CreateExecutionRequest, CreateFeedbackRequest, CreatePlanRequest, CreateProductRequest, CreateProgramRequest, CreateProjectRequest, CreateStoryRequest, CreateTaskRequest, CreateTestCaseRequest, CreateTicketRequest, CreateUserRequest, Execution, Feedback, FileUploadResponse, ModulesResponse, ModuleType, Plan, Product, Program, Project, Release, ResolveBugRequest, Story, Task, TaskStatus, TaskUpdate, TestCase, Ticket, UpdateBuildRequest, UpdateBugRequest, UpdateExecutionRequest, UpdateFeedbackRequest, UpdatePlanRequest, UpdateProductRequest, UpdateProgramRequest, UpdateProjectRequest, ChangeStoryRequest, UpdateTestCaseRequest, UpdateTicketRequest, UpdateUserRequest, UploadFileRequest, UserDetail, ZentaoConfig } from '../types/zentao';
 export declare class ZentaoAPI {
     private config;
     private client;
@@ -9,8 +9,19 @@ export declare class ZentaoAPI {
     getMyTasks(status?: TaskStatus): Promise<Task[]>;
     getTaskDetail(taskId: number): Promise<Task>;
     getProducts(): Promise<Product[]>;
-    getMyBugs(status?: BugStatus, productId?: number): Promise<Bug[]>;
-    getBugDetail(bugId: number): Promise<Bug>;
+    getMyBugs(status?: BugStatus, productId?: number, page?: number, limit?: number): Promise<{
+        page: number;
+        total: number;
+        limit: number;
+        bugs: Bug[];
+    }>;
+    getProductBugs(productId: number, page?: number, limit?: number, status?: BugStatus): Promise<{
+        page: number;
+        total: number;
+        limit: number;
+        bugs: Bug[];
+    }>;
+    getBugDetail(bugId: number, fields?: 'basic' | 'detail' | 'full'): Promise<any>;
     resolveBug(bugId: number, resolution: ResolveBugRequest): Promise<Bug>;
     updateTask(taskId: number, update: TaskUpdate): Promise<Task>;
     finishTask(taskId: number, update?: TaskUpdate): Promise<Task>;
@@ -28,16 +39,21 @@ export declare class ZentaoAPI {
     linkBugsToPlan(planId: number, bugIds: number[]): Promise<Plan>;
     unlinkBugsFromPlan(planId: number, bugIds: number[]): Promise<Plan>;
     getProjectReleases(projectId: number): Promise<Release[]>;
-    getStoryDetail(storyId: number): Promise<Story>;
+    getStoryDetail(storyId: number, fields?: 'basic' | 'detail' | 'full'): Promise<any>;
     createBug(productId: number, bug: CreateBugRequest): Promise<Bug>;
     getProjectExecutions(projectId: number): Promise<Execution[]>;
     createPlan(productId: number, plan: CreatePlanRequest): Promise<Plan>;
     getProjects(page?: number, limit?: number): Promise<Project[]>;
-    updateStory(storyId: number, update: UpdateStoryRequest): Promise<Story>;
+    changeStory(storyId: number, update: ChangeStoryRequest): Promise<Story>;
     deleteTask(taskId: number): Promise<{
         message: string;
     }>;
-    getProductStories(productId: number): Promise<Story[]>;
+    getProductStories(productId: number, page?: number, limit?: number): Promise<{
+        page: number;
+        total: number;
+        limit: number;
+        stories: Story[];
+    }>;
     getProgramDetail(programId: number): Promise<Program>;
     createProgram(program: CreateProgramRequest): Promise<Program>;
     updateProgram(programId: number, update: UpdateProgramRequest): Promise<Program>;

package/dist/api/zentaoApi.js

@@ -111,7 +111,7 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async getMyBugs(status, productId) {
+    async getMyBugs(status, productId, page, limit) {
         if (!productId) {
             // 如果没有提供产品ID，获取第一个可用的产品
             const products = await this.getProducts();
@@ -121,20 +121,36 @@ export class ZentaoAPI {
             productId = products[0].id;
             console.log(`使用第一个可用的产品ID: ${productId}`);
         }
+        // 默认每页20条，最多100条
+        const finalLimit = limit ? Math.min(limit, 100) : 20;
+        const finalPage = page || 1;
         const params = {
             assignedTo: this.config.username,
             status: status || 'all',
-            product: productId
+            product: productId,
+            page: finalPage,
+            limit: finalLimit
         };
         try {
-            console.log('正在获取Bug列表，参数:', params);
+            console.log(`正在获取Bug列表 (page=${finalPage}, limit=${finalLimit})，参数:`, params);
             const response = await this.request('GET', '/bugs', params);
-            console.log('Bug列表响应:', response);
+            console.log(`Bug列表响应: 获取到 ${response.bugs?.length || 0} 条数据`);
             if (Array.isArray(response)) {
-                return response;
+                // 如果返回的是数组，转换为标准格式
+                return {
+                    page: finalPage,
+                    total: response.length,
+                    limit: finalLimit,
+                    bugs: response
+                };
             }
             else if (response && typeof response === 'object' && Array.isArray(response.bugs)) {
-                return response.bugs;
+                return {
+                    page: response.page || finalPage,
+                    total: response.total || response.bugs.length,
+                    limit: response.limit || finalLimit,
+                    bugs: response.bugs
+                };
             }
             throw new Error(`获取Bug列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
         }
@@ -146,12 +162,80 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async getBugDetail(bugId) {
+    async getProductBugs(productId, page, limit, status) {
+        try {
+            // 默认每页20条，最多100条
+            const finalLimit = limit ? Math.min(limit, 100) : 20;
+            const finalPage = page || 1;
+            console.log(`正在获取产品 ${productId} 的Bug列表 (page=${finalPage}, limit=${finalLimit})...`);
+            // 构建查询参数
+            const queryParams = new URLSearchParams();
+            queryParams.append('page', finalPage.toString());
+            queryParams.append('limit', finalLimit.toString());
+            if (status && status !== 'all') {
+                queryParams.append('status', status);
+            }
+            const response = await this.request('GET', `/products/${productId}/bugs?${queryParams.toString()}`);
+            console.log(`产品Bug列表响应: 获取到 ${response.bugs?.length || 0} 条数据`);
+            if (Array.isArray(response)) {
+                // 如果返回的是数组，转换为标准格式
+                return {
+                    page: finalPage,
+                    total: response.length,
+                    limit: finalLimit,
+                    bugs: response
+                };
+            }
+            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
+                    };
+                }
+            }
+            throw new Error(`获取产品Bug列表失败: 响应格式不正确 ${JSON.stringify(response)}`);
+        }
+        catch (error) {
+            console.error('获取产品Bug列表失败:', error);
+            throw error;
+        }
+    }
+    async getBugDetail(bugId, fields) {
         try {
-            console.log(`正在获取Bug ${bugId} 的详情...`);
+            console.log(`正在获取Bug ${bugId} 的详情 (fields=${fields || 'full'})...`);
             const response = await this.request('GET', `/bugs/${bugId}`);
             console.log('Bug详情响应:', response);
-            return response;
+            // 根据 fields 参数过滤返回的字段
+            const fieldLevel = fields || 'full';
+            if (fieldLevel === 'basic') {
+                // 基本信息：只返回核心字段
+                return {
+                    id: response.id,
+                    title: response.title,
+                    product: response.product,
+                    module: response.module,
+                    status: response.status,
+                    severity: response.severity,
+                    pri: response.pri,
+                    type: response.type,
+                    assignedTo: response.assignedTo,
+                    openedBy: response.openedBy,
+                    openedDate: response.openedDate,
+                    deadline: response.deadline
+                };
+            }
+            else if (fieldLevel === 'detail') {
+                // 详细信息：包含步骤描述，但排除不常用字段
+                const { files, cases, linkBugs, ...detailData } = response;
+                return detailData;
+            }
+            else {
+                // 完整信息：返回所有字段
+                return response;
+            }
         }
         catch (error) {
             console.error('获取Bug详情失败:', error);
@@ -414,12 +498,39 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async getStoryDetail(storyId) {
+    async getStoryDetail(storyId, fields) {
         try {
-            console.log(`正在获取需求 ${storyId} 的详情...`);
+            console.log(`正在获取需求 ${storyId} 的详情 (fields=${fields || 'full'})...`);
             const response = await this.request('GET', `/stories/${storyId}`);
             console.log('需求详情响应:', response);
-            return response;
+            // 根据 fields 参数过滤返回的字段
+            const fieldLevel = fields || 'full';
+            if (fieldLevel === 'basic') {
+                // 基本信息：只返回核心字段
+                return {
+                    id: response.id,
+                    title: response.title,
+                    product: response.product,
+                    module: response.module,
+                    status: response.status,
+                    stage: response.stage,
+                    pri: response.pri,
+                    category: response.category,
+                    estimate: response.estimate,
+                    assignedTo: response.assignedTo,
+                    openedBy: response.openedBy,
+                    openedDate: response.openedDate
+                };
+            }
+            else if (fieldLevel === 'detail') {
+                // 详细信息：包含描述和验收标准，但不包含关联数据
+                const { executions, tasks, stages, children, ...detailData } = response;
+                return detailData;
+            }
+            else {
+                // 完整信息：返回所有字段
+                return response;
+            }
         }
         catch (error) {
             console.error('获取需求详情失败:', error);
@@ -495,9 +606,9 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async updateStory(storyId, update) {
+    async changeStory(storyId, update) {
         try {
-            console.log(`正在更新需求 ${storyId}...`);
+            console.log(`正在变更需求 ${storyId}...`);
             // 自动处理评审人问题
             const updateData = { ...update };
             // 如果用户没有设置评审人，也没有指定无需评审，则自动跳过评审
@@ -506,11 +617,11 @@ export class ZentaoAPI {
                 console.log('自动设置needNotReview=true以跳过评审要求');
             }
             const response = await this.request('PUT', `/stories/${storyId}`, undefined, updateData);
-            console.log('更新需求响应:', response);
+            console.log('变更需求响应:', response);
             return response;
         }
         catch (error) {
-            console.error('更新需求失败:', error);
+            console.error('变更需求失败:', error);
             throw error;
         }
     }
@@ -526,17 +637,35 @@ export class ZentaoAPI {
             throw error;
         }
     }
-    async getProductStories(productId) {
+    async getProductStories(productId, page, limit) {
         try {
-            console.log(`正在获取产品 ${productId} 的需求列表...`);
-            const response = await this.request('GET', `/products/${productId}/stories`);
-            console.log('产品需求列表响应:', response);
+            // 默认每页20条，最多100条
+            const finalLimit = limit ? Math.min(limit, 100) : 20;
+            const finalPage = page || 1;
+            console.log(`正在获取产品 ${productId} 的需求列表 (page=${finalPage}, limit=${finalLimit})...`);
+            // 构建查询参数
+            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} 条数据`);
             if (Array.isArray(response)) {
-                return response;
+                // 如果返回的是数组，转换为标准格式
+                return {
+                    page: finalPage,
+                    total: response.length,
+                    limit: finalLimit,
+                    stories: response
+                };
             }
             else if (response && typeof response === 'object') {
                 if (Array.isArray(response.stories)) {
-                    return response.stories;
+                    return {
+                        page: response.page || finalPage,
+                        total: response.total || response.stories.length,
+                        limit: response.limit || finalLimit,
+                        stories: response.stories
+                    };
                 }
             }
             throw new Error(`获取产品需求列表失败: 响应格式不正确 ${JSON.stringify(response)}`);

package/dist/index.js

@@ -89,24 +89,80 @@ server.tool("getProducts", {}, async () => {
 // Add getMyBugs tool
 server.tool("getMyBugs", {
     status: z.enum(['active', 'resolved', 'closed', 'all']).optional(),
-    productId: z.number().optional()
-}, async ({ status, productId }) => {
-    if (!zentaoApi)
-        throw new Error("Please initialize Zentao API first");
-    const bugs = await zentaoApi.getMyBugs(status, productId);
+    productId: z.number().optional(),
+    page: z.number().optional().describe("页码，从1开始，默认为1"),
+    limit: z.number().optional().describe("每页数量，默认20，最大100")
+}, async ({ status, productId, page, limit }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const result = await zentaoApi.getMyBugs(status, productId, page, limit);
+    // 返回分页信息和数据
+    const summary = {
+        summary: `当前第 ${result.page} 页，共 ${result.total} 个Bug，本页显示 ${result.bugs.length} 个`,
+        pagination: {
+            page: result.page,
+            limit: result.limit,
+            total: result.total,
+            totalPages: Math.ceil(result.total / result.limit)
+        },
+        bugs: result.bugs
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
+    };
+});
+// Add getProductBugs tool
+server.tool("getProductBugs", {
+    productId: z.number(),
+    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);
+    // 返回分页信息和数据
+    const summary = {
+        summary: `当前第 ${result.page} 页，共 ${result.total} 个Bug，本页显示 ${result.bugs.length} 个`,
+        pagination: {
+            page: result.page,
+            limit: result.limit,
+            total: result.total,
+            totalPages: Math.ceil(result.total / result.limit)
+        },
+        bugs: result.bugs
+    };
     return {
-        content: [{ type: "text", text: JSON.stringify(bugs, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
     };
 });
 // Add getBugDetail tool
 server.tool("getBugDetail", {
-    bugId: z.number()
-}, async ({ bugId }) => {
-    if (!zentaoApi)
-        throw new Error("Please initialize Zentao API first");
-    const bug = await zentaoApi.getBugDetail(bugId);
+    bugId: z.number(),
+    fields: z.enum(['basic', 'detail', 'full']).optional().describe(`
+字段级别：
+- basic: 基本信息（id, title, status, severity, pri等核心字段）
+- detail: 详细信息（包含steps步骤，但不包含files/cases/linkBugs等关联数据）
+- full: 完整信息（包含所有字段，默认值）
+        `.trim())
+}, async ({ bugId, fields }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const bug = await zentaoApi.getBugDetail(bugId, fields);
+    // 添加说明信息
+    const result = {
+        fieldLevel: fields || 'full',
+        bug: bug
+    };
+    // 根据字段级别添加提示
+    if (fields === 'basic') {
+        result.note = '仅显示基本信息，如需完整内容请使用 fields=detail 或 fields=full';
+    }
+    else if (fields === 'detail') {
+        result.note = '显示详细信息但不包含关联数据（files/cases/linkBugs），如需完整内容请使用 fields=full';
+    }
     return {
-        content: [{ type: "text", text: JSON.stringify(bug, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
     };
 });
 // Add resolveBug tool
@@ -360,13 +416,31 @@ server.tool("getProjectReleases", {
 });
 // Add getStoryDetail tool
 server.tool("getStoryDetail", {
-    storyId: z.number()
-}, async ({ storyId }) => {
-    if (!zentaoApi)
-        throw new Error("Please initialize Zentao API first");
-    const story = await zentaoApi.getStoryDetail(storyId);
+    storyId: z.number(),
+    fields: z.enum(['basic', 'detail', 'full']).optional().describe(`
+字段级别：
+- basic: 基本信息（id, title, status, stage, pri等核心字段）
+- detail: 详细信息（包含spec和verify，但不包含executions/tasks/stages/children等关联数据）
+- full: 完整信息（包含所有字段，默认值）
+        `.trim())
+}, async ({ storyId, fields }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const story = await zentaoApi.getStoryDetail(storyId, fields);
+    // 添加说明信息
+    const result = {
+        fieldLevel: fields || 'full',
+        story: story
+    };
+    // 根据字段级别添加提示
+    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(story, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
     };
 });
 // Add createBug tool
@@ -460,8 +534,8 @@ server.tool("getProjects", {
         content: [{ type: "text", text: JSON.stringify(projects, null, 2) }]
     };
 });
-// Add updateStory tool
-server.tool("updateStory", {
+// Add changeStory tool
+server.tool("changeStory", {
     storyId: z.number(),
     update: z.union([
         z.object({
@@ -507,7 +581,7 @@ server.tool("updateStory", {
             comment: z.string().optional()
         }),
         z.string()
-    ]).describe("需求更新字段 - 支持对象或JSON字符串格式")
+    ]).describe("需求变更字段 - 支持对象或JSON字符串格式")
 }, async ({ storyId, update }) => {
     if (!zentaoApi)
         throw new Error("Please initialize Zentao API first");
@@ -524,7 +598,7 @@ server.tool("updateStory", {
     else {
         updateData = update;
     }
-    const story = await zentaoApi.updateStory(storyId, updateData);
+    const story = await zentaoApi.changeStory(storyId, updateData);
     return {
         content: [{ type: "text", text: JSON.stringify(story, null, 2) }]
     };
@@ -542,13 +616,26 @@ server.tool("deleteTask", {
 });
 // Add getProductStories tool
 server.tool("getProductStories", {
-    productId: z.number()
-}, async ({ productId }) => {
-    if (!zentaoApi)
-        throw new Error("Please initialize Zentao API first");
-    const stories = await zentaoApi.getProductStories(productId);
+    productId: z.number(),
+    page: z.number().optional().describe("页码，从1开始，默认为1"),
+    limit: z.number().optional().describe("每页数量，默认20，最大100")
+}, async ({ productId, page, limit }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const result = await zentaoApi.getProductStories(productId, page, limit);
+    // 返回分页信息和数据
+    const summary = {
+        summary: `当前第 ${result.page} 页，共 ${result.total} 条需求，本页显示 ${result.stories.length} 条`,
+        pagination: {
+            page: result.page,
+            limit: result.limit,
+            total: result.total,
+            totalPages: Math.ceil(result.total / result.limit)
+        },
+        stories: result.stories
+    };
     return {
-        content: [{ type: "text", text: JSON.stringify(stories, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(summary, null, 2) }]
     };
 });
 // Program tools

package/dist/services/bugService.js

@@ -5,8 +5,8 @@ export class BugService {
         this.api = api;
     }
     async getMyBugs(status) {
-        const bugs = await this.api.getMyBugs(status);
-        return bugs.map(bug => this.enrichBugData(bug));
+        const result = await this.api.getMyBugs(status);
+        return result.bugs.map((bug) => this.enrichBugData(bug));
     }
     async getBugDetail(bugId) {
         const bug = await this.api.getBugDetail(bugId);

package/dist/types/zentao.d.ts

@@ -256,7 +256,7 @@ export interface Project {
     PM: string | User;
     progress: number;
 }
-export interface UpdateStoryRequest {
+export interface ChangeStoryRequest {
     title?: string;
     product?: number;
     parent?: number;
@@ -287,6 +287,7 @@ export interface UpdateStoryRequest {
     verify?: string;
     comment?: string;
 }
+export type UpdateStoryRequest = ChangeStoryRequest;
 export interface CreateProgramRequest {
     name?: string;
     parent?: string;

package/package.json

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