@zzp123/mcp-zentao 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -5,6 +5,63 @@ 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.15.0] - 2025-11-07
+
+### Added
+- **评论功能完整支持** 💬
+  - 新增 `addComment` 通用评论工具，支持9种对象类型
+  - 新增专用评论工具：
+    - `addStoryComment`: 为需求添加评论（自动识别story/requirement）
+    - `addTaskComment`: 为任务添加评论
+    - `addBugComment`: 为Bug添加评论
+  - 支持的对象类型：
+    - story（软件需求）
+    - requirement（用户需求）
+    - task（任务）
+    - bug（Bug）
+    - testcase（测试用例）
+    - testtask（测试单）
+    - todo（待办）
+    - doc（文档）
+    - doctemplate（文档模板）
+
+### Changed
+- **评论内容格式**
+  - 支持纯文本评论
+  - 支持HTML格式的富文本评论
+  - 自动处理评论提交的响应格式
+
+### Technical
+- 添加 `CommentObjectType` 类型定义
+- 添加 `AddCommentRequest` 和 `CommentResponse` 接口
+- 实现混合接口调用（使用HTML接口但保持REST API认证）
+
+## [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

package/dist/api/zentaoApi.d.ts

@@ -239,5 +239,6 @@ export declare class ZentaoAPI {
     getModules(type: ModuleType, id: number, fields?: string): Promise<ModulesResponse>;
     uploadFile(uploadRequest: UploadFileRequest): Promise<FileUploadResponse>;
     downloadFile(fileId: number): Promise<Buffer>;
+    addComment(objectType: string, objectID: number, comment: string): Promise<any>;
     getConfig(): ZentaoConfig;
 }

package/dist/api/zentaoApi.js

@@ -1534,6 +1534,63 @@ export class ZentaoAPI {
             throw error;
         }
     }
+    // 评论模块 - 使用 HTML 接口
+    async addComment(objectType, objectID, comment) {
+        try {
+            console.log(`正在为 ${objectType} ${objectID} 添加评论...`);
+            const token = await this.getToken();
+            const htmlUrl = `${this.config.url}/zentao/action-comment-${objectType}-${objectID}.html`;
+            // 使用 form-urlencoded 格式发送数据
+            const formData = new URLSearchParams();
+            formData.append('actioncomment', comment);
+            const response = await axios.post(htmlUrl, formData.toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Token': token
+                },
+                timeout: 10000
+            });
+            console.log('添加评论响应:', response.data);
+            // 返回统一格式
+            if (response.data && typeof response.data === 'object') {
+                // 如果是 JSON 响应（API 模式）
+                if (response.data.status === 'success' || response.data.result === 'success') {
+                    return {
+                        status: 'success',
+                        actionID: response.data.data || response.data.actionID,
+                        message: '评论添加成功'
+                    };
+                }
+                else if (response.data.result === 'fail' || response.data.status === 'fail') {
+                    throw new Error(response.data.message || '评论添加失败');
+                }
+            }
+            // 如果返回的是 HTML 或其他格式，认为成功
+            return {
+                status: 'success',
+                message: '评论添加成功'
+            };
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                console.error('添加评论失败:', {
+                    status: error.response?.status,
+                    data: error.response?.data,
+                    message: error.message
+                });
+                // 尝试解析错误消息
+                if (error.response?.data) {
+                    const errorData = error.response.data;
+                    if (typeof errorData === 'object' && errorData.message) {
+                        throw new Error(`添加评论失败: ${errorData.message}`);
+                    }
+                }
+                throw new Error(`添加评论失败: ${error.message}`);
+            }
+            console.error('添加评论失败:', error);
+            throw error;
+        }
+    }
     // 获取配置信息（用于生成图片 URL）
     getConfig() {
         return this.config;

package/dist/index.js

@@ -335,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(),
@@ -346,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,
@@ -465,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等核心字段）
@@ -585,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({
             // 基本信息
@@ -671,7 +673,7 @@ server.tool("deleteTask", {
     };
 });
 // Add getProductStories tool
-server.tool("getProductStories", "获取产品需求列表 - 默认只返回核心字段（id, 标题, 指派人, 创建人）", {
+server.tool("getProductStories", "获取产品需求列表 - 包含软件需求(story)和用户需求(requirement)，默认只返回核心字段（id, 标题, 指派人, 创建人）", {
     productId: z.number(),
     page: z.number().optional().describe("页码，从1开始，默认为1"),
     limit: z.number().optional().describe("每页数量，默认20，最大100"),
@@ -831,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(),
@@ -1385,6 +1504,95 @@ server.tool("downloadFile", {
     fs.writeFileSync(savePath, fileBuffer);
     return { content: [{ type: "text", text: `文件已下载到: ${savePath}` }] };
 });
+// Comment tools (评论工具)
+server.tool("addComment", "添加评论 - 为需求、任务、Bug等对象添加评论", {
+    objectType: z.enum([
+        'story', // 软件需求
+        'requirement', // 用户需求
+        'task', // 任务
+        'bug', // Bug
+        'testcase', // 测试用例
+        'testtask', // 测试单
+        'todo', // 待办
+        'doc', // 文档
+        'doctemplate' // 文档模板
+    ]).describe("对象类型"),
+    objectID: z.number().describe("对象ID"),
+    comment: z.string().describe("评论内容，支持HTML格式")
+}, async ({ objectType, objectID, comment }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const result = await zentaoApi.addComment(objectType, objectID, comment);
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: result.status,
+                    message: result.message,
+                    actionID: result.actionID,
+                    details: `已为 ${objectType} #${objectID} 添加评论`
+                }, null, 2)
+            }]
+    };
+});
+server.tool("addStoryComment", "为需求添加评论 - 专用工具，支持软件需求(story)和用户需求(requirement)", {
+    storyId: z.number().describe("需求ID"),
+    comment: z.string().describe("评论内容，支持HTML格式")
+}, async ({ storyId, comment }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    // 使用 'story' 类型，API会自动识别是 story 还是 requirement
+    const result = await zentaoApi.addComment('story', storyId, comment);
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: result.status,
+                    message: result.message,
+                    actionID: result.actionID,
+                    details: `已为需求 #${storyId} 添加评论`
+                }, null, 2)
+            }]
+    };
+});
+server.tool("addTaskComment", "为任务添加评论", {
+    taskId: z.number().describe("任务ID"),
+    comment: z.string().describe("评论内容，支持HTML格式")
+}, async ({ taskId, comment }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const result = await zentaoApi.addComment('task', taskId, comment);
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: result.status,
+                    message: result.message,
+                    actionID: result.actionID,
+                    details: `已为任务 #${taskId} 添加评论`
+                }, null, 2)
+            }]
+    };
+});
+server.tool("addBugComment", "为Bug添加评论", {
+    bugId: z.number().describe("Bug ID"),
+    comment: z.string().describe("评论内容，支持HTML格式")
+}, async ({ bugId, comment }) => {
+    if (!zentaoApi)
+        throw new Error("Please initialize Zentao API first");
+    const result = await zentaoApi.addComment('bug', bugId, comment);
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({
+                    status: result.status,
+                    message: result.message,
+                    actionID: result.actionID,
+                    details: `已为Bug #${bugId} 添加评论`
+                }, null, 2)
+            }]
+    };
+});
 // Start receiving messages on stdin and sending messages on stdout
 const transport = new StdioServerTransport();
 await server.connect(transport).catch(console.error);

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;
@@ -716,3 +717,14 @@ export interface UploadFileRequest {
     filename: string;
     uid?: string;
 }
+export type CommentObjectType = 'story' | 'requirement' | 'task' | 'bug' | 'testcase' | 'testtask' | 'todo' | 'doc' | 'doctemplate';
+export interface AddCommentRequest {
+    objectType: CommentObjectType;
+    objectID: number;
+    comment: string;
+}
+export interface CommentResponse {
+    status: string;
+    data?: number;
+    message?: string;
+}

package/package.json

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