@zzp123/mcp-zentao 1.4.2 → 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,334 @@
+# Changelog
+
+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.5.0] - 2025-11-05
+
+### Added
+- **模块数据简化功能** - 新增 `SimpleModule` 接口，简化模块API返回数据
+  - `getModules` 接口现在只返回核心字段：id、name、parent、grade、children
+  - 移除冗余的字段（type、path、order等），大幅减少数据传输量
+  - 保持树形结构，递归简化所有子模块数据
+
+### Changed
+- 优化 `getModules()` 方法，返回类型从 `Module[]` 改为 `SimpleModule[]`
+- 添加 `simplifyModule()` 私有方法，用于递归转换模块数据结构
+
+### Benefits
+- 减少网络传输数据量，提升API响应速度
+- 简化客户端数据处理逻辑
+- 更清晰的数据结构，只包含必要信息
+
+## [1.4.3] - 2025-11-05
+
+### Fixed
+- 将 `CHANGELOG.md` 添加到 npm 包发布文件列表中
+- 确保用户可以在安装包后查看完整的版本历史
+
+## [1.4.2] - 2025-11-05
+
+### Added
+- 创建 `CHANGELOG.md` - 完整的版本更新历史文档
+- 在 README.md 中添加版本历史章节和最新版本信息
+- 添加 npm 版本徽章和 MIT 许可证徽章
+
+### Changed
+- 更新 README.md 中的包名从 `@bigtian/mcp-zentao` 到 `@zzp123/mcp-zentao`
+- 更新 API 文档示例代码，使用最新的接口签名
+- 添加版本标记到 API 方法说明（如 v1.4.0+, v1.2.0+）
+- 完善类型定义文档，添加 `ResolveBugRequest`、`UploadFileRequest`、`FileUploadResponse` 等新接口
+
+### Documentation
+- 整理所有版本的更新内容到 CHANGELOG
+- 记录从 v1.0.x 到 v1.4.2 的完整演进历史
+- 提供清晰的版本规范说明
+
+## [1.4.1] - 2025-11-05
+
+### Fixed
+- 修复 `uploadImageFromClipboard` 工具上传成功后没有返回内容的问题，该问题导致 AI 一直等待响应而卡住
+- 改进返回数据结构，现在包含 `success` 标志位、文件大小、文件名等详细信息
+- 增强错误处理，为每个平台（Windows/macOS/Linux）提供专门的错误处理和清晰的错误提示
+- 添加完整的执行日志，方便调试和问题排查
+
+### Changed
+- 优化返回格式，统一成功和失败响应的数据结构
+- 改进错误信息，包含堆栈跟踪和解决建议
+
+## [1.4.0] - 2025-11-05
+
+### Added
+- **新增解决Bug接口** `resolveBug` - 根据最新的禅道API文档添加
+  - 接口路径：`POST /bugs/:id/resolve`
+  - 支持7种解决方案：fixed（已解决）、bydesign（设计如此）、duplicate（重复Bug）、external（外部原因）、notrepro（无法重现）、postponed（延期处理）、willnotfix（不予解决）
+  - 自动验证必填字段：fixed 需要 resolvedBuild，duplicate 需要 duplicateBug
+  - 支持备注和指派功能
+- 新增 `ResolutionType` 类型定义
+- 新增 `ResolveBugRequest` 接口定义
+
+### Technical
+- 在 `zentaoApi.ts` 中实现 `resolveBug()` 方法，包含参数验证逻辑
+- 在 `index.ts` 中注册 `resolveBug` MCP 工具
+- 完善类型系统，确保类型安全
+
+## [1.3.2] - 2025-11-05
+
+### Removed
+- 移除 `resolveBug` API 方法（之前的实现与文档不符）
+- 移除 `resolveBug` MCP 工具注册
+- 移除 `BugResolution` 接口类型定义
+
+### Reason
+- 禅道REST API文档中的修改Bug接口（`PUT /bugs/:id`）不支持修改Bug状态
+- 该接口只支持修改基本信息（标题、优先级、严重程度等），不能修改 status、resolution、resolvedBuild 等字段
+- 这些字段只在返回数据中存在，不能作为请求参数
+
+### Note
+- 此版本移除的功能在 v1.4.0 中以正确的实现方式重新添加
+
+## [1.3.1] - 2025-11-05
+
+### Fixed
+- **修复 Claude Code 中剪贴板图片无法上传的核心问题**
+- 修改 `uploadImageFromClipboard` 工具，使其主动读取系统剪贴板，而不是期望 Claude Code 提供 base64Data
+
+### Changed
+- 工具现在直接使用操作系统原生方法读取剪贴板：
+  - Windows: PowerShell 的 `System.Windows.Forms.Clipboard`
+  - macOS: `pngpaste` 命令
+  - Linux: `xclip` 命令
+- 移除 `base64Data` 必填参数，改为可选的 `filename` 和 `uid`
+
+### Technical Details
+- **问题根源**：Claude Code 输入框中粘贴的图片会上传到 Claude 服务器用于视觉分析，MCP 工具运行在本地只能访问系统剪贴板，这是两个完全独立的数据源
+- **解决方案**：工具直接读取系统剪贴板，不依赖 Claude Code 传递图片数据
+
+### Documentation
+- 创建 `为什么读取不到剪贴板图片.md` - 详细解释技术原理
+- 创建 `Claude-Code图片上传指南.md` - 提供正确的使用方法
+- 创建 `scripts/get-clipboard-base64.js` - 辅助脚本
+
+## [1.3.0] - 2025-11-05
+
+### Added
+- **命令行脚本支持** - 添加跨平台的剪贴板图片上传脚本
+  - `scripts/upload-clipboard-image.js` - Node.js 实现（跨平台）
+  - `scripts/upload-clipboard-image.ps1` - PowerShell 脚本（Windows）
+  - `scripts/upload-clipboard-image.py` - Python 实现（跨平台）
+- 添加 npm 脚本命令：
+  - `npm run upload:clipboard` - 运行 Node.js 脚本
+  - `npm run upload:clipboard:py` - 运行 Python 脚本
+- 创建 `upload.bat.example` 配置模板
+
+### Documentation
+- 创建 `scripts/README.md` - 详细的脚本使用文档
+- 创建 `scripts/MCP-INTEGRATION.md` - MCP 集成说明
+- 创建 `上传图片使用说明.md` - 中文快速开始指南
+
+### Changed
+- 更新 package.json，将 scripts 文件夹包含到发布包中
+
+### Features
+- 支持从系统剪贴板直接上传图片到禅道
+- 100% 可靠的命令行方式（不依赖 MCP）
+- 自动保存图片到本地 img 文件夹
+- 返回文件 ID 和访问 URL
+
+## [1.2.2] - 2025-11-05
+
+### Added
+- 创建专门的 `uploadImageFromClipboard` MCP 工具
+- 工具接受 `base64Data`（必填）、`filename`（可选）、`uid`（可选）参数
+
+### Changed
+- 简化剪贴板图片上传流程
+- 使工具更加明确和易用
+
+### Note
+- 此版本的实现在 v1.3.1 中被完全重写，以解决 Claude Code 集成问题
+
+## [1.2.1] - 2025-11-05
+
+### Added
+- `uploadFile` 工具支持 `base64Data` 参数，可以直接上传 base64 编码的图片
+- 自动创建 `img` 文件夹（如果不存在）
+- 智能图片格式检测（从 data URL 中提取）
+- 默认文件名生成（使用时间戳）
+
+### Changed
+- 增强 `uploadFile` 工具，同时支持 `filePath` 和 `base64Data` 两种方式
+- 改进错误处理和参数验证
+
+### Technical
+- 添加 data URL 解析逻辑
+- 支持 png、jpg、jpeg、gif 等常见图片格式
+
+## [1.2.0] - 2025-11-05
+
+### Added
+- **文件上传接口** `uploadFile` - POST `/files`
+  - 支持 multipart/form-data 格式上传
+  - 支持 `uid` 参数（用于富文本编辑器关联）
+  - 支持多种文件格式（文档、图片、媒体、压缩包等）
+- **文件下载接口** `downloadFile` - GET `/files/:id`
+  - 返回文件的二进制数据（Buffer）
+  - 支持将文件保存到指定路径
+
+### Technical
+- 添加 `FileUploadResponse` 接口类型
+- 添加 `UploadFileRequest` 接口类型
+- 实现 `zentaoApi.uploadFile()` 方法，使用 form-data 库
+- 实现 `zentaoApi.downloadFile()` 方法，支持 arraybuffer 响应
+- 安装依赖：`form-data` 和 `@types/form-data`
+
+### MCP Tools
+- 注册 `uploadFile` MCP 工具
+- 注册 `downloadFile` MCP 工具
+
+## [1.1.x] - 早期版本
+
+### Added
+- 模块管理接口 `getModules` - GET `/modules`
+  - 支持按类型和ID获取模块树
+  - 支持需求、任务、Bug、用例、反馈、产品等多种模块类型
+
+## [1.0.x] - 初始版本
+
+### Added
+- **基础功能**
+  - 禅道 API 认证（Token 获取）
+  - 配置管理（本地配置文件）
+  - MCP 服务器初始化
+
+- **任务管理**
+  - `getMyTasks` - 获取我的任务列表
+  - `getTaskDetail` - 获取任务详情
+  - `updateTask` - 更新任务
+  - `finishTask` - 完成任务
+  - `createTask` - 创建任务
+
+- **Bug管理**
+  - `getMyBugs` - 获取我的Bug列表
+  - `getBugDetail` - 获取Bug详情
+  - `createBug` - 创建Bug
+  - `updateBug` - 修改Bug
+  - `deleteBug` - 删除Bug
+
+- **产品管理**
+  - `getProducts` - 获取产品列表
+  - `getProductDetail` - 获取产品详情
+  - `createProduct` - 创建产品
+  - `updateProduct` - 更新产品
+  - `deleteProduct` - 删除产品
+
+- **项目集管理**
+  - `getPrograms` - 获取项目集列表
+  - `getProgramDetail` - 获取项目集详情
+  - `createProgram` - 创建项目集
+  - `updateProgram` - 更新项目集
+  - `deleteProgram` - 删除项目集
+
+- **项目管理**
+  - `getProjects` - 获取项目列表
+  - `getProjectDetail` - 获取项目详情
+  - `createProject` - 创建项目
+  - `updateProject` - 更新项目
+  - `deleteProject` - 删除项目
+
+- **执行管理**
+  - `getExecutions` - 获取执行列表
+  - `getExecutionDetail` - 获取执行详情
+  - `createExecution` - 创建执行
+  - `updateExecution` - 更新执行
+  - `deleteExecution` - 删除执行
+
+- **需求管理**
+  - `getStories` - 获取需求列表
+  - `getStoryDetail` - 获取需求详情
+  - `createStory` - 创建需求
+  - `updateStory` - 更新需求
+  - `deleteStory` - 删除需求
+
+- **产品计划**
+  - `getPlans` - 获取计划列表
+  - `getPlanDetail` - 获取计划详情
+  - `createPlan` - 创建计划
+  - `updatePlan` - 更新计划
+  - `deletePlan` - 删除计划
+  - `linkBugsToPlan` - 关联Bug到计划
+  - `unlinkBugsFromPlan` - 取消关联Bug
+
+- **版本管理**
+  - `getBuilds` - 获取版本列表
+  - `getBuildDetail` - 获取版本详情
+  - `createBuild` - 创建版本
+  - `updateBuild` - 更新版本
+  - `deleteBuild` - 删除版本
+
+- **反馈管理**
+  - `getFeedbacks` - 获取反馈列表
+  - `getFeedbackDetail` - 获取反馈详情
+  - `createFeedback` - 创建反馈
+  - `updateFeedback` - 更新反馈
+  - `deleteFeedback` - 删除反馈
+  - `assignFeedback` - 指派反馈
+  - `closeFeedback` - 关闭反馈
+
+- **测试用例**
+  - `getTestCases` - 获取用例列表
+  - `getTestCaseDetail` - 获取用例详情
+  - `createTestCase` - 创建用例
+  - `updateTestCase` - 更新用例
+  - `deleteTestCase` - 删除用例
+
+- **工单管理**
+  - `getTickets` - 获取工单列表
+  - `getTicketDetail` - 获取工单详情
+  - `createTicket` - 创建工单
+  - `updateTicket` - 更新工单
+  - `deleteTicket` - 删除工单
+
+- **用户管理**
+  - `getMyProfile` - 获取我的信息
+  - `getUsers` - 获取用户列表
+  - `getUserDetail` - 获取用户详情
+  - `createUser` - 创建用户
+  - `updateUser` - 更新用户
+  - `deleteUser` - 删除用户
+
+- **发布管理**
+  - `getReleases` - 获取发布列表
+  - `getReleaseDetail` - 获取发布详情
+
+### Technical
+- TypeScript 实现，提供完整的类型定义
+- 基于 Axios 的 HTTP 客户端
+- MD5 密码加密
+- 自动 Token 管理和刷新
+- 配置文件支持（~/.zentao/config.json）
+- MCP (Model Context Protocol) 集成
+- Zod schema 验证
+
+### Documentation
+- README.md - 项目说明
+- 禅道API文档.md - 完整的 API 文档
+
+---
+
+## 版本规范
+
+- **主版本号 (Major)**: 不兼容的 API 变更
+- **次版本号 (Minor)**: 向下兼容的功能新增
+- **修订号 (Patch)**: 向下兼容的问题修正
+
+## 链接
+
+- [npm 包地址](https://www.npmjs.com/package/@zzp123/mcp-zentao)
+- [GitHub 仓库](https://github.com/yourusername/mcp-zentao)（待更新）
+
+## 贡献者
+
+- [@zzp123](https://github.com/zzp123) - 项目维护者

package/README.md

@@ -15,10 +15,10 @@ npm install @zzp123/mcp-zentao -g
 
 查看完整的版本更新历史，请访问 [CHANGELOG.md](./CHANGELOG.md)
 
-**最新版本**: v1.4.2
-- 创建完整的版本更新历史文档（CHANGELOG.md）
-- 更新所有文档和示例代码
-- 修正包名和API签名
+**最新版本**: v1.5.0
+- 模块数据简化功能 - getModules接口现在只返回核心字段
+- 大幅减少数据传输量，提升API响应速度
+- 新增 SimpleModule 接口，优化数据结构
 
 **主要版本**:
 - v1.4.1 - 修复 uploadImageFromClipboard 返回值问题

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, Module, 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, ModuleType, Plan, Product, Program, Project, Release, ResolveBugRequest, SimpleModule, Story, Task, TaskStatus, TaskUpdate, TestCase, Ticket, UpdateBuildRequest, UpdateBugRequest, UpdateExecutionRequest, UpdateFeedbackRequest, UpdatePlanRequest, UpdateProductRequest, UpdateProgramRequest, UpdateProjectRequest, UpdateStoryRequest, UpdateTestCaseRequest, UpdateTicketRequest, UpdateUserRequest, UploadFileRequest, UserDetail, ZentaoConfig } from '../types/zentao';
 export declare class ZentaoAPI {
     private config;
     private client;
@@ -148,7 +148,14 @@ export declare class ZentaoAPI {
     deleteTicket(ticketId: number): Promise<{
         message: string;
     }>;
-    getModules(type: ModuleType, id: number): Promise<Module[]>;
+    /**
+     * 将完整的Module对象转换为简化的SimpleModule对象
+     */
+    private simplifyModule;
+    /**
+     * 获取模块列表（返回简化数据）
+     */
+    getModules(type: ModuleType, id: number): Promise<SimpleModule[]>;
     uploadFile(uploadRequest: UploadFileRequest): Promise<FileUploadResponse>;
     downloadFile(fileId: number): Promise<Buffer>;
 }

package/dist/api/zentaoApi.js

@@ -1119,13 +1119,35 @@ export class ZentaoAPI {
         }
     }
     // 模块相关API
+    /**
+     * 将完整的Module对象转换为简化的SimpleModule对象
+     */
+    simplifyModule(module) {
+        const simple = {
+            id: module.id,
+            name: module.name,
+            parent: module.parent,
+            grade: module.grade
+        };
+        // 递归处理子模块
+        if (module.children && module.children.length > 0) {
+            simple.children = module.children.map(child => this.simplifyModule(child));
+        }
+        return simple;
+    }
+    /**
+     * 获取模块列表（返回简化数据）
+     */
     async getModules(type, id) {
         try {
             console.log(`正在获取模块列表，类型: ${type}, ID: ${id}...`);
             const params = { type, id };
             const response = await this.request('GET', '/modules', params);
-            console.log('获取模块列表响应:', response);
-            return response.modules;
+            console.log('获取模块列表响应（原始数据）:', response);
+            // 转换为简化格式
+            const simpleModules = response.modules.map(module => this.simplifyModule(module));
+            console.log('获取模块列表响应（简化数据）:', simpleModules);
+            return simpleModules;
         }
         catch (error) {
             console.error('获取模块列表失败:', error);

package/dist/types/zentao.d.ts

@@ -626,8 +626,19 @@ export interface Module {
     owner: string;
     collector?: string;
     short?: string;
+    deleted?: string;
+    from?: number;
+    url?: string;
+    children?: Module[];
 }
 export type ModuleType = 'story' | 'task' | 'bug' | 'case' | 'feedback' | 'product';
+export interface SimpleModule {
+    id: string;
+    name: string;
+    parent: string;
+    grade: string;
+    children?: SimpleModule[];
+}
 export interface FileUploadResponse {
     id: number;
     url: string;

package/package.json

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