@zzp123/mcp-zentao 1.18.7 → 1.18.9

package/README.md

@@ -1,463 +1,527 @@
-# MCP-Zentao
-
-[![npm version](https://badge.fury.io/js/%40zzp123%2Fmcp-zentao.svg)](https://www.npmjs.com/package/@zzp123/mcp-zentao)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-禅道项目管理系统的高级API集成包，提供任务管理、Bug跟踪等功能的完整封装，专为Cursor IDE设计的MCP扩展。**支持产品经理、测试工程师、开发工程师三种角色的精简版本，大幅减少上下文占用。**
-
-## 📦 安装
-
-```bash
-npm install @zzp123/mcp-zentao -g
-```
-
-## 🎭 角色版本选择
-
-从 v1.17.0 开始，提供了三个角色专用的精简版本，每个版本只包含对应角色常用的工具，**可显著减少 LLM 上下文占用 30-45%**：
-
-| 版本 | 命令 | 工具数量 | 文件大小 | 适用角色 |
-|------|------|---------|---------|---------|
-| **完整版** | `zentao` | 91个 | 67 KB | 需要使用全部功能 |
-| **产品经理版** | `zentao-pm` | 39个 | 39 KB (-57%) | 需求、产品、计划管理 |
-| **测试工程师版** | `zentao-qa` | 26个 | 25 KB (-71%) | Bug、测试用例管理 |
-| **开发工程师版** | `zentao-dev` | 38个 | 35 KB (-58%) | 任务、项目、Bug解决 |
-
-### 如何选择版本？
-
-在 Claude Desktop 配置文件中，将 `command` 字段改为对应的命令即可：
-
-```json
-{
-  "mcpServers": {
-    "zentao-pm": {
-      "command": "zentao-pm",
-      "args": []
-    }
-  }
-}
-```
-
-### 各版本包含的功能
-
-<details>
-<summary><b>产品经理版 (zentao-pm)</b> - 点击展开</summary>
-
-- ✅ 初始化配置
-- ✅ 需求管理（创建、查看、修改、删除）
-- ✅ 产品管理
-- ✅ 计划管理
-- ✅ 项目集管理
-- ✅ Bug查看（只读）
-- ✅ 任务查看（只读）
-- ✅ 评论功能
-- ✅ 文件上传
-</details>
-
-<details>
-<summary><b>测试工程师版 (zentao-qa)</b> - 点击展开</summary>
-
-- ✅ 初始化配置
-- ✅ Bug管理（创建、查看、修改、解决、删除）
-- ✅ 测试用例管理
-- ✅ 需求查看（只读）
-- ✅ 任务查看（只读）
-- ✅ 评论功能
-- ✅ 文件上传
-</details>
-
-<details>
-<summary><b>开发工程师版 (zentao-dev)</b> - 点击展开</summary>
-
-- ✅ 初始化配置
-- ✅ 任务管理（创建、查看、更新、完成、删除）
-- ✅ Bug解决（查看、解决、评论）
-- ✅ 项目管理
-- ✅ 执行管理
-- ✅ 构建版本管理
-- ✅ 需求查看（只读）
-- ✅ 评论功能
-- ✅ 文件上传
-</details>
-
-## 🎯 Claude Code Skills
-
-**新功能！** 现在提供 Claude Code Skills 支持，让你通过自然语言更便捷地使用禅道功能。
-
-### 什么是 Skills？
-
-Skills 是 Claude Code 的功能扩展，通过它你可以：
-- 用自然语言描述需求，无需记住命令
-- 智能化的任务管理和状态更新
-- 更友好的交互体验
-
-### 可用的 Skills
-
-目前提供以下 Skills：
-
-| Skill | 适用角色 | 功能 | 文档 |
-|-------|---------|-----|------|
-| **zentao-dev** | 开发工程师 | 任务管理、Bug解决、项目管理 | [文档](./.claude/skills/zentao-dev/) |
-
-### 如何使用 Skills？
-
-1. **安装 MCP 服务器**（如果还没安装）：
-   ```bash
-   npm install -g @zzp123/mcp-zentao
-   ```
-
-2. **配置 Claude Desktop**（参考下方 MCP 配置）
-
-3. **在 Claude Code 中使用**：
-   ```
-   你：查看我今天的任务
-   AI：[显示任务列表]
-
-   你：开始处理任务 #123
-   AI：✓ 任务已更新为"进行中"状态
-   ```
-
-详细使用指南请查看 [Skills 文档](./.claude/skills/zentao-dev/README.md)
-
-## 📋 版本历史
-
-查看完整的版本更新历史，请访问 [CHANGELOG.md](./CHANGELOG.md)
-
-**最新版本**: v1.17.6 - 2025-11-10
-- 💬 评论工具完全统一（移除所有便捷工具，统一使用 addComment）
-- 📊 完整版 91个工具，PM版 39个，QA版 26个，Dev版 38个
-- 🎯 累计减少约 106行重复代码，完全统一评论API
-
-**近期版本**:
-- v1.17.5 - 评论工具简化（移除 addBugComment 和 addTaskComment）
-- v1.17.4 - 产品经理版移除工单管理（42个工具）
-- v1.17.3 - 测试工程师版移除构建和工单管理（29个工具）
-
-## 使用方法
-
-### 首次使用（配置禅道信息）
-
-首次使用时，需要提供禅道的配置信息：
-
-```bash
-zentao '{"config":{"url":"https://your-zentao-url","username":"your-username","password":"your-password","apiVersion":"v1"},"name":"张三","age":25,"skills":["编程","设计"]}'
-```
-
-配置信息会被保存在用户目录下的 `.zentao/config.json` 文件中，后续使用时无需再次提供。
-
-### 后续使用
-
-配置完成后，只需要提供任务相关的信息即可：
-
-```bash
-zentao '{"name":"张三","age":25,"skills":["编程","设计"]}'
-```
-
-### 更新配置
-
-如果需要更新禅道配置信息，只需要再次提供 config 参数即可：
-
-```bash
-zentao '{"config":{"url":"https://new-zentao-url","username":"new-username","password":"new-password","apiVersion":"v1"},"name":"张三","age":25,"skills":["编程","设计"]}'
-```
-
-## 配置文件位置
-
-配置文件保存在用户目录下的 `.zentao/config.json` 文件中：
-
-- Windows: `C:\Users\你的用户名\.zentao\config.json`
-- macOS/Linux: `~/.zentao/config.json`
-
-## 功能特性
-
-- 支持配置信息的持久化存储
-- 自动管理禅道API的认证信息
-- 提供任务创建、更新、完成等功能
-- 支持Bug跟踪和处理
-- 完整的类型定义支持
-
-## 注意事项
-
-- 配置文件中包含敏感信息，请确保文件权限设置正确
-- 建议定期更新密码，以确保安全性
-- 如遇到问题，可以删除配置文件重新配置
-
-## 许可证
-
-MIT
-
-## 特点
-
-- 完整的禅道API封装
-- 简单易用的接口设计
-- 类型安全（TypeScript支持）
-- 完善的错误处理
-- 自动化的认证管理
-
-## 与其他项目的区别
-
-不同于通用的数据库操作工具（如 mcp-mysql-server），本项目专注于提供：
-
-1. 禅道系统特定的业务功能
-2. 高级别的API抽象
-3. 完整的禅道工作流支持
-4. 开箱即用的禅道集成方案
-
-## 本地开发
-
-1. 克隆仓库
-```bash
-git clone https://github.com/bigtian/mcp-zentao.git
-cd mcp-zentao
-```
-
-2. 安装依赖
-```bash
-npm install
-```
-
-3. 运行测试
-```bash
-npm test
-```
-
-4. 构建项目
-```bash
-npm run build
-```
-
-## Docker 使用
-
-### 使用 docker-compose（推荐）
-
-1. 复制环境变量模板并修改配置
-```bash
-cp .env.example .env
-# 编辑 .env 文件，填入你的禅道系统配置
-```
-
-2. 启动服务
-```bash
-docker-compose up -d
-```
-
-3. 查看日志
-```bash
-docker-compose logs -f
-```
-
-### 手动使用 Docker
-
-1. 构建镜像
-```bash
-docker build -t mcp-zentao .
-```
-
-2. 运行容器
-```bash
-docker run -d \
-  --name mcp-zentao \
-  -p 3000:3000 \
-  -e ZENTAO_URL=your-zentao-url \
-  -e ZENTAO_USERNAME=your-username \
-  -e ZENTAO_PASSWORD=your-password \
-  -e ZENTAO_API_VERSION=v1 \
-  -v $(pwd)/logs:/app/logs \
-  mcp-zentao
-```
-
-### 在 Cursor IDE 中配置
-
-在 Cursor IDE 的配置文件中添加以下配置：
-
-```json
-{
-  "mcpServers": {
-    "zentao": {
-      "url": "http://localhost:3000"
-    }
-  }
-}
-```
-
-## 基本使用
-
-```typescript
-import { ZentaoAPI } from '@zzp123/mcp-zentao';
-
-// 创建API实例
-const api = new ZentaoAPI({
-    url: 'https://your-zentao-url',  // 你的禅道系统URL
-    username: 'your-username',        // 用户名
-    password: 'your-password',        // 密码
-    apiVersion: 'v1'                 // API版本，默认为v1
-});
-
-// 获取我的任务列表
-async function getMyTasks() {
-    try {
-        const tasks = await api.getMyTasks();
-        console.log('我的任务:', tasks);
-    } catch (error) {
-        console.error('获取任务失败:', error);
-    }
-}
-
-// 获取我的Bug列表
-async function getMyBugs() {
-    try {
-        const bugs = await api.getMyBugs();
-        console.log('我的Bug:', bugs);
-    } catch (error) {
-        console.error('获取Bug失败:', error);
-    }
-}
-
-// 完成任务
-async function finishTask(taskId: number) {
-    try {
-        await api.finishTask(taskId);
-        console.log('任务已完成');
-    } catch (error) {
-        console.error('完成任务失败:', error);
-    }
-}
-
-// 解决Bug (v1.4.0+)
-async function resolveBug(bugId: number) {
-    try {
-        const result = await api.resolveBug(bugId, {
-            resolution: 'fixed',
-            resolvedBuild: 'trunk',
-            assignedTo: 'admin',
-            comment: '问题已修复'
-        });
-        console.log('Bug已解决:', result);
-    } catch (error) {
-        console.error('解决Bug失败:', error);
-    }
-}
-
-// 上传剪贴板图片 (v1.3.1+)
-async function uploadClipboardImage() {
-    try {
-        // 注意：需要先复制图片到系统剪贴板
-        const result = await api.uploadFile({
-            filename: 'screenshot.png',
-            uid: 'optional-uid'
-        });
-        console.log('图片已上传:', result);
-    } catch (error) {
-        console.error('上传失败:', error);
-    }
-}
-```
-
-## API文档
-
-### ZentaoAPI 类
-
-#### 构造函数
-
-```typescript
-constructor(config: {
-    url: string;          // 禅道系统URL
-    username: string;     // 用户名
-    password: string;     // 密码
-    apiVersion?: string;  // API版本，默认为v1
-})
-```
-
-#### 方法
-
-1. `getMyTasks(): Promise<Task[]>`
-   - 获取当前用户的任务列表
-   - 返回: Promise<Task[]>
-
-2. `getMyBugs(): Promise<Bug[]>`
-   - 获取当前用户的Bug列表
-   - 返回: Promise<Bug[]>
-
-3. `finishTask(taskId: number): Promise<void>`
-   - 完成指定ID的任务
-   - 参数: taskId - 任务ID
-   - 返回: Promise<void>
-
-4. `resolveBug(bugId: number, resolution: ResolveBugRequest): Promise<Bug>` (v1.4.0+)
-   - 解决指定ID的Bug
-   - 参数:
-     - bugId - Bug ID
-     - resolution - Bug解决方案
-   - 返回: Promise<Bug> - 返回更新后的Bug对象
-
-5. `uploadFile(request: UploadFileRequest): Promise<FileUploadResponse>` (v1.2.0+)
-   - 上传文件到禅道
-   - 参数: UploadFileRequest - 文件上传请求
-   - 返回: Promise<FileUploadResponse> - 包含文件ID和访问URL
-
-6. `downloadFile(fileId: number): Promise<Buffer>` (v1.2.0+)
-   - 从禅道下载文件
-   - 参数: fileId - 文件ID
-   - 返回: Promise<Buffer> - 文件的二进制数据
-
-### 类型定义
-
-```typescript
-interface Task {
-    id: number;
-    name: string;
-    status: string;
-    pri: number;
-    assignedTo: string;
-    deadline: string;
-    // ... 其他任务属性
-}
-
-interface Bug {
-    id: number;
-    title: string;
-    status: string;
-    severity: number;
-    resolvedBy: string;
-    resolution: string;
-    // ... 其他Bug属性
-}
-
-// v1.4.0+
-type ResolutionType = 'fixed' | 'bydesign' | 'duplicate' | 'external' | 'notrepro' | 'postponed' | 'willnotfix';
-
-interface ResolveBugRequest {
-    resolution: ResolutionType;  // 解决方案（必填）
-    resolvedBuild?: string;      // 解决版本（resolution='fixed'时必填）
-    assignedTo?: string;         // 指派给
-    comment?: string;            // 备注
-    duplicateBug?: number;       // 重复Bug的ID（resolution='duplicate'时必填）
-}
-
-// v1.2.0+
-interface UploadFileRequest {
-    file: Buffer;           // 文件数据
-    filename: string;       // 文件名
-    uid?: string;          // 唯一标识符（可选）
-}
-
-interface FileUploadResponse {
-    id: number;     // 文件ID
-    url: string;    // 文件访问URL
-}
-```
-
-## 注意事项
-
-1. 确保提供正确的禅道系统URL和API版本
-2. 用户名和密码需要有相应的API访问权限
-3. 所有API调用都是异步的，需要使用async/await或Promise处理
-4. 错误处理建议使用try/catch进行捕获
-
-## 开发环境
-
-- Node.js >= 14.0.0
-- TypeScript >= 4.0.0
-
-## 贡献
-
-欢迎提交Issue和Pull Request！
+# MCP-Zentao
+
+[![npm version](https://badge.fury.io/js/%40zzp123%2Fmcp-zentao.svg)](https://www.npmjs.com/package/@zzp123/mcp-zentao)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+禅道项目管理系统的高级API集成包，提供任务管理、Bug跟踪等功能的完整封装，专为Cursor IDE设计的MCP扩展。**支持产品经理、测试工程师、开发工程师三种角色的精简版本，大幅减少上下文占用。**
+
+## 📦 安装
+
+```bash
+npm install @zzp123/mcp-zentao -g
+```
+
+## 🎭 角色版本选择
+
+从 v1.17.0 开始，提供了三个角色专用的精简版本，每个版本只包含对应角色常用的工具，**可显著减少 LLM 上下文占用 30-45%**：
+
+| 版本 | 命令 | 工具数量 | 文件大小 | 适用角色 |
+|------|------|---------|---------|---------|
+| **完整版** | `zentao` | 91个 | 67 KB | 需要使用全部功能 |
+| **产品经理版** | `zentao-pm` | 39个 | 39 KB (-57%) | 需求、产品、计划管理 |
+| **测试工程师版** | `zentao-qa` | 26个 | 25 KB (-71%) | Bug、测试用例管理 |
+| **开发工程师版** | `zentao-dev` | 38个 | 35 KB (-58%) | 任务、项目、Bug解决 |
+
+### 如何选择版本？
+
+在 Claude Desktop 配置文件中，将 `command` 字段改为对应的命令即可：
+
+```json
+{
+  "mcpServers": {
+    "zentao-pm": {
+      "command": "zentao-pm",
+      "args": []
+    }
+  }
+}
+```
+
+### 各版本包含的功能
+
+<details>
+<summary><b>产品经理版 (zentao-pm)</b> - 点击展开</summary>
+
+- ✅ 初始化配置
+- ✅ 需求管理（创建、查看、修改、删除）
+- ✅ 产品管理
+- ✅ 计划管理
+- ✅ 项目集管理
+- ✅ Bug查看（只读）
+- ✅ 任务查看（只读）
+- ✅ 评论功能
+- ✅ 文件上传
+</details>
+
+<details>
+<summary><b>测试工程师版 (zentao-qa)</b> - 点击展开</summary>
+
+- ✅ 初始化配置
+- ✅ Bug管理（创建、查看、修改、解决、删除）
+- ✅ 测试用例管理
+- ✅ 需求查看（只读）
+- ✅ 任务查看（只读）
+- ✅ 评论功能
+- ✅ 文件上传
+</details>
+
+<details>
+<summary><b>开发工程师版 (zentao-dev)</b> - 点击展开</summary>
+
+- ✅ 初始化配置
+- ✅ 任务管理（创建、查看、更新、完成、删除）
+- ✅ Bug解决（查看、解决、评论）
+- ✅ 项目管理
+- ✅ 执行管理
+- ✅ 构建版本管理
+- ✅ 需求查看（只读）
+- ✅ 评论功能
+- ✅ 文件上传
+</details>
+
+## 🎯 Claude Code Skills
+
+**新功能！** 现在提供 Claude Code Skills 支持，让你通过自然语言更便捷地使用禅道功能。
+
+### 什么是 Skills？
+
+Skills 是 Claude Code 的功能扩展，通过它你可以：
+- 用自然语言描述需求，无需记住命令
+- 智能化的任务管理和状态更新
+- 更友好的交互体验
+
+### 可用的 Skills
+
+目前提供以下 Skills：
+
+| Skill | 适用角色 | 功能 | 文档 |
+|-------|---------|-----|------|
+| **zentao-dev** | 开发工程师 | 任务管理、Bug解决、项目管理 | [文档](./.claude/skills/zentao-dev/) |
+
+### 如何使用 Skills？
+
+1. **安装 MCP 服务器**（如果还没安装）：
+   ```bash
+   npm install -g @zzp123/mcp-zentao
+   ```
+
+2. **配置 Claude Desktop**（参考下方 MCP 配置）
+
+3. **在 Claude Code 中使用**：
+   ```
+   你：查看我今天的任务
+   AI：[显示任务列表]
+
+   你：开始处理任务 #123
+   AI：✓ 任务已更新为"进行中"状态
+   ```
+
+详细使用指南请查看 [Skills 文档](./.claude/skills/zentao-dev/README.md)
+
+## 📋 版本历史
+
+查看完整的版本更新历史，请访问 [CHANGELOG.md](./CHANGELOG.md)
+
+**最新版本**: v1.17.6 - 2025-11-10
+- 💬 评论工具完全统一（移除所有便捷工具，统一使用 addComment）
+- 📊 完整版 91个工具，PM版 39个，QA版 26个，Dev版 38个
+- 🎯 累计减少约 106行重复代码，完全统一评论API
+
+**近期版本**:
+- v1.17.5 - 评论工具简化（移除 addBugComment 和 addTaskComment）
+- v1.17.4 - 产品经理版移除工单管理（42个工具）
+- v1.17.3 - 测试工程师版移除构建和工单管理（29个工具）
+
+## 使用方法
+
+### 首次使用（配置禅道信息）
+
+首次使用时，需要提供禅道的配置信息：
+
+```bash
+zentao '{"config":{"url":"https://your-zentao-url","username":"your-username","password":"your-password","apiVersion":"v1"},"name":"张三","age":25,"skills":["编程","设计"]}'
+```
+
+配置信息会被保存在用户目录下的 `.zentao/config.json` 文件中，后续使用时无需再次提供。
+
+### 后续使用
+
+配置完成后，只需要提供任务相关的信息即可：
+
+```bash
+zentao '{"name":"张三","age":25,"skills":["编程","设计"]}'
+```
+
+### 更新配置
+
+如果需要更新禅道配置信息，只需要再次提供 config 参数即可：
+
+```bash
+zentao '{"config":{"url":"https://new-zentao-url","username":"new-username","password":"new-password","apiVersion":"v1"},"name":"张三","age":25,"skills":["编程","设计"]}'
+```
+
+## 配置文件位置
+
+配置文件保存在用户目录下的 `.zentao/config.json` 文件中：
+
+- Windows: `C:\Users\你的用户名\.zentao\config.json`
+- macOS/Linux: `~/.zentao/config.json`
+
+## 功能特性
+
+- 支持配置信息的持久化存储
+- 自动管理禅道API的认证信息
+- 提供任务创建、更新、完成等功能
+- 支持Bug跟踪和处理
+- 完整的类型定义支持
+
+## 注意事项
+
+- 配置文件中包含敏感信息，请确保文件权限设置正确
+- 建议定期更新密码，以确保安全性
+- 如遇到问题，可以删除配置文件重新配置
+
+## 许可证
+
+MIT
+
+## 特点
+
+- 完整的禅道API封装
+- 简单易用的接口设计
+- 类型安全（TypeScript支持）
+- 完善的错误处理
+- 自动化的认证管理
+
+## 与其他项目的区别
+
+不同于通用的数据库操作工具（如 mcp-mysql-server），本项目专注于提供：
+
+1. 禅道系统特定的业务功能
+2. 高级别的API抽象
+3. 完整的禅道工作流支持
+4. 开箱即用的禅道集成方案
+
+## 本地开发
+
+1. 克隆仓库
+```bash
+git clone https://github.com/bigtian/mcp-zentao.git
+cd mcp-zentao
+```
+
+2. 安装依赖
+```bash
+npm install
+```
+
+3. 运行测试
+```bash
+npm test
+```
+
+4. 构建项目
+```bash
+npm run build
+```
+
+## Docker 使用
+
+### 使用 docker-compose（推荐）
+
+1. 复制环境变量模板并修改配置
+```bash
+cp .env.example .env
+# 编辑 .env 文件，填入你的禅道系统配置
+```
+
+2. 启动服务
+```bash
+docker-compose up -d
+```
+
+3. 查看日志
+```bash
+docker-compose logs -f
+```
+
+### 手动使用 Docker
+
+1. 构建镜像
+```bash
+docker build -t mcp-zentao .
+```
+
+2. 运行容器
+```bash
+docker run -d \
+  --name mcp-zentao \
+  -p 3000:3000 \
+  -e ZENTAO_URL=your-zentao-url \
+  -e ZENTAO_USERNAME=your-username \
+  -e ZENTAO_PASSWORD=your-password \
+  -e ZENTAO_API_VERSION=v1 \
+  -v $(pwd)/logs:/app/logs \
+  mcp-zentao
+```
+
+### 在 Cursor IDE 中配置
+
+在 Cursor IDE 的配置文件中添加以下配置：
+
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "url": "http://localhost:3000"
+    }
+  }
+}
+```
+
+## 🚦 传输方式：STDIO 与 HTTP 双支持
+
+默认使用 STDIO 传输（适合本地/CLI 场景）。如果需要通过 URL 与 MCP 客户端通信，可启用 HTTP 传输。两种配置方式任选其一：
+
+**方式 1：环境变量**
+- `MCP_TRANSPORT=http` 启用 HTTP（默认 `stdio`）
+- `MCP_HTTP_PORT`（或 `MCP_PORT`）：端口，默认 3000
+- `MCP_HTTP_HOST`（或 `MCP_HOST`）：监听地址，默认 `0.0.0.0`
+- `MCP_HTTP_PATH`：路由前缀，默认 `/mcp`
+- 安全可选：`MCP_ALLOWED_HOSTS`、`MCP_ALLOWED_ORIGINS`（逗号分隔），`MCP_DNS_PROTECTION=true`
+
+示例：
+```bash
+MCP_TRANSPORT=http MCP_HTTP_PORT=3000 MCP_HTTP_PATH=/mcp zentao --config "{\"url\":\"http://your-zentao\",\"username\":\"u\",\"password\":\"p\",\"apiVersion\":\"v1\"}"
+```
+
+**方式 2：CLI 参数**
+- `--transport http`
+- `--http-port 3000`（或 `--port`）
+- `--http-host 0.0.0.0`（或 `--host`）
+- `--http-path /mcp`
+- 安全可选：`--allowed-hosts host1,host2`，`--allowed-origins http://a,http://b`，`--dns-protection true`
+
+示例：
+```bash
+zentao --transport http --http-port 3000 --http-path /mcp --config "{\"url\":\"http://your-zentao\",\"username\":\"u\",\"password\":\"p\",\"apiVersion\":\"v1\"}"
+```
+
+HTTP 模式下客户端需要连接到 `http://<host>:<port><path>`（默认 `http://localhost:3000/mcp`）。
+
+**方式 3：交互式初始化（最便捷）**
+
+运行一次交互式向导，选择 STDIO/HTTP 并保存到 `~/.zentao/transport.json`，后续无需再带参数：
+```bash
+zentao --init-transport
+# 或 zentao-dev / zentao-pm / zentao-qa 均可
+```
+
+交互式示例：
+```
+=== MCP 传输方式初始化 ===
+选择传输方式 (1) stdio (2) http [1]: 2
+HTTP 端口 [3000]: 4000
+HTTP 路径前缀 (如 /mcp) [/mcp]: /zentao
+监听地址 [0.0.0.0]: 127.0.0.1
+允许的 Host 列表(逗号分隔，可留空): localhost:4000
+允许的 Origin 列表(逗号分隔，可留空): https://example.com
+启用 DNS Rebinding 防护? (y/N): y
+```
+
+最终配置会写入 `~/.zentao/transport.json`，示例：
+```json
+{
+  "transport": "http",
+  "host": "127.0.0.1",
+  "port": 4000,
+  "path": "/zentao",
+  "allowedHosts": ["localhost:4000"],
+  "allowedOrigins": ["https://example.com"],
+  "dnsProtection": true
+}
+```
+该文件优先级低于环境变量/CLI 参数，因此仍可通过临时参数覆盖。
+
+## 基本使用
+
+```typescript
+import { ZentaoAPI } from '@zzp123/mcp-zentao';
+
+// 创建API实例
+const api = new ZentaoAPI({
+    url: 'https://your-zentao-url',  // 你的禅道系统URL
+    username: 'your-username',        // 用户名
+    password: 'your-password',        // 密码
+    apiVersion: 'v1'                 // API版本，默认为v1
+});
+
+// 获取我的任务列表
+async function getMyTasks() {
+    try {
+        const tasks = await api.getMyTasks();
+        console.log('我的任务:', tasks);
+    } catch (error) {
+        console.error('获取任务失败:', error);
+    }
+}
+
+// 获取我的Bug列表
+async function getMyBugs() {
+    try {
+        const bugs = await api.getMyBugs();
+        console.log('我的Bug:', bugs);
+    } catch (error) {
+        console.error('获取Bug失败:', error);
+    }
+}
+
+// 完成任务
+async function finishTask(taskId: number) {
+    try {
+        await api.finishTask(taskId);
+        console.log('任务已完成');
+    } catch (error) {
+        console.error('完成任务失败:', error);
+    }
+}
+
+// 解决Bug (v1.4.0+)
+async function resolveBug(bugId: number) {
+    try {
+        const result = await api.resolveBug(bugId, {
+            resolution: 'fixed',
+            resolvedBuild: 'trunk',
+            assignedTo: 'admin',
+            comment: '问题已修复'
+        });
+        console.log('Bug已解决:', result);
+    } catch (error) {
+        console.error('解决Bug失败:', error);
+    }
+}
+
+// 上传剪贴板图片 (v1.3.1+)
+async function uploadClipboardImage() {
+    try {
+        // 注意：需要先复制图片到系统剪贴板
+        const result = await api.uploadFile({
+            filename: 'screenshot.png',
+            uid: 'optional-uid'
+        });
+        console.log('图片已上传:', result);
+    } catch (error) {
+        console.error('上传失败:', error);
+    }
+}
+```
+
+## API文档
+
+### ZentaoAPI 类
+
+#### 构造函数
+
+```typescript
+constructor(config: {
+    url: string;          // 禅道系统URL
+    username: string;     // 用户名
+    password: string;     // 密码
+    apiVersion?: string;  // API版本，默认为v1
+})
+```
+
+#### 方法
+
+1. `getMyTasks(): Promise<Task[]>`
+   - 获取当前用户的任务列表
+   - 返回: Promise<Task[]>
+
+2. `getMyBugs(): Promise<Bug[]>`
+   - 获取当前用户的Bug列表
+   - 返回: Promise<Bug[]>
+
+3. `finishTask(taskId: number): Promise<void>`
+   - 完成指定ID的任务
+   - 参数: taskId - 任务ID
+   - 返回: Promise<void>
+
+4. `resolveBug(bugId: number, resolution: ResolveBugRequest): Promise<Bug>` (v1.4.0+)
+   - 解决指定ID的Bug
+   - 参数:
+     - bugId - Bug ID
+     - resolution - Bug解决方案
+   - 返回: Promise<Bug> - 返回更新后的Bug对象
+
+5. `uploadFile(request: UploadFileRequest): Promise<FileUploadResponse>` (v1.2.0+)
+   - 上传文件到禅道
+   - 参数: UploadFileRequest - 文件上传请求
+   - 返回: Promise<FileUploadResponse> - 包含文件ID和访问URL
+
+6. `downloadFile(fileId: number): Promise<Buffer>` (v1.2.0+)
+   - 从禅道下载文件
+   - 参数: fileId - 文件ID
+   - 返回: Promise<Buffer> - 文件的二进制数据
+
+### 类型定义
+
+```typescript
+interface Task {
+    id: number;
+    name: string;
+    status: string;
+    pri: number;
+    assignedTo: string;
+    deadline: string;
+    // ... 其他任务属性
+}
+
+interface Bug {
+    id: number;
+    title: string;
+    status: string;
+    severity: number;
+    resolvedBy: string;
+    resolution: string;
+    // ... 其他Bug属性
+}
+
+// v1.4.0+
+type ResolutionType = 'fixed' | 'bydesign' | 'duplicate' | 'external' | 'notrepro' | 'postponed' | 'willnotfix';
+
+interface ResolveBugRequest {
+    resolution: ResolutionType;  // 解决方案（必填）
+    resolvedBuild?: string;      // 解决版本（resolution='fixed'时必填）
+    assignedTo?: string;         // 指派给
+    comment?: string;            // 备注
+    duplicateBug?: number;       // 重复Bug的ID（resolution='duplicate'时必填）
+}
+
+// v1.2.0+
+interface UploadFileRequest {
+    file: Buffer;           // 文件数据
+    filename: string;       // 文件名
+    uid?: string;          // 唯一标识符（可选）
+}
+
+interface FileUploadResponse {
+    id: number;     // 文件ID
+    url: string;    // 文件访问URL
+}
+```
+
+## 注意事项
+
+1. 确保提供正确的禅道系统URL和API版本
+2. 用户名和密码需要有相应的API访问权限
+3. 所有API调用都是异步的，需要使用async/await或Promise处理
+4. 错误处理建议使用try/catch进行捕获
+
+## 开发环境
+
+- Node.js >= 14.0.0
+- TypeScript >= 4.0.0
+
+## 贡献
+
+欢迎提交Issue和Pull Request！

package/dist/index-dev.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -783,9 +786,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => {
+await startServerTransport(server, { args }).catch(err => {
     process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
     process.exit(1);
 });

package/dist/index-pm.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -908,9 +911,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => {
+await startServerTransport(server, { args }).catch(err => {
     process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
     process.exit(1);
 });

package/dist/index-qa.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -720,6 +723,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => { process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n'); process.exit(1); });
+await startServerTransport(server, { args }).catch(err => {
+    process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
+    process.exit(1);
+});

package/dist/index.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { ZentaoAPI } from './api/zentaoApi.js';
 import { loadConfig, saveConfig } from './config.js';
 import { withApi } from './mcpHelpers.js';
+import { interactiveInitTransport, startServerTransport } from './serverTransport.js';
 // 解析命令行参数
 const args = process.argv.slice(2);
 let configData = null;
+if (await interactiveInitTransport({ args })) {
+    process.exit(0);
+}
 // 查找 --config 参数
 const configIndex = args.indexOf('--config');
 if (configIndex !== -1 && configIndex + 1 < args.length) {
@@ -1540,9 +1543,7 @@ server.tool("deleteComment", "删除评论 - 只能删除自己的评论，管
             }]
     };
 });
-// Start receiving messages on stdin and sending messages on stdout
-const transport = new StdioServerTransport();
-await server.connect(transport).catch(err => {
+await startServerTransport(server, { args }).catch(err => {
     process.stderr.write('[FATAL] MCP server failed: ' + String(err) + '\n');
     process.exit(1);
 });

package/dist/serverTransport.d.ts

@@ -0,0 +1,20 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+interface TransportLogger {
+    info?: (message: string) => void;
+    error?: (message: string) => void;
+}
+export interface StartTransportOptions {
+    args?: string[];
+    logger?: TransportLogger;
+}
+export interface InteractiveInitOptions {
+    args?: string[];
+    logger?: TransportLogger;
+}
+export declare function startServerTransport(server: McpServer, options?: StartTransportOptions): Promise<void>;
+/**
+ * 交互式初始化：让用户选择 STDIO / HTTP 及 HTTP 参数，并将结果写入 ~/.zentao/transport.json
+ * 返回 true 表示已处理（应在入口处直接 exit）
+ */
+export declare function interactiveInitTransport(options?: InteractiveInitOptions): Promise<boolean>;
+export {};

package/dist/serverTransport.js

@@ -0,0 +1,151 @@
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import readline from 'node:readline';
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { loadTransportConfig, saveTransportConfig } from './transportConfig.js';
+const DEFAULT_HTTP_PORT = 3000;
+const DEFAULT_HTTP_PATH = '/mcp';
+const getArgValue = (args, flag) => {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === flag) {
+            return args[i + 1];
+        }
+        if (arg.startsWith(`${flag}=`)) {
+            return arg.substring(flag.length + 1);
+        }
+    }
+    return undefined;
+};
+const parsePort = (value) => {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0 && parsed <= 65535) {
+        return parsed;
+    }
+    return undefined;
+};
+export async function startServerTransport(server, options = {}) {
+    const args = options.args ?? [];
+    const logger = options.logger ?? {
+        info: (msg) => process.stdout.write(msg + '\n'),
+        error: (msg) => process.stderr.write(msg + '\n')
+    };
+    const fileConfig = loadTransportConfig();
+    const mode = (process.env.MCP_TRANSPORT || getArgValue(args, '--transport') || fileConfig?.transport || 'stdio').toLowerCase();
+    if (mode !== 'http') {
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        return;
+    }
+    const portStr = process.env.MCP_HTTP_PORT
+        || process.env.MCP_PORT
+        || getArgValue(args, '--http-port')
+        || getArgValue(args, '--port')
+        || (fileConfig?.port ? String(fileConfig.port) : undefined);
+    const host = process.env.MCP_HTTP_HOST
+        || process.env.MCP_HOST
+        || getArgValue(args, '--http-host')
+        || getArgValue(args, '--host')
+        || fileConfig?.host
+        || '0.0.0.0';
+    const pathSetting = process.env.MCP_HTTP_PATH
+        || getArgValue(args, '--http-path')
+        || fileConfig?.path
+        || DEFAULT_HTTP_PATH;
+    const port = parsePort(portStr) ?? DEFAULT_HTTP_PORT;
+    const normalizedPath = pathSetting.startsWith('/') ? pathSetting : `/${pathSetting}`;
+    const allowedHosts = (process.env.MCP_ALLOWED_HOSTS || getArgValue(args, '--allowed-hosts'))?.split(',').map(h => h.trim()).filter(Boolean)
+        || fileConfig?.allowedHosts;
+    const allowedOrigins = (process.env.MCP_ALLOWED_ORIGINS || getArgValue(args, '--allowed-origins'))?.split(',').map(o => o.trim()).filter(Boolean)
+        || fileConfig?.allowedOrigins;
+    const enableDnsProtection = (process.env.MCP_DNS_PROTECTION || getArgValue(args, '--dns-protection')) === 'true'
+        || Boolean(fileConfig?.dnsProtection);
+    const httpTransport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        enableJsonResponse: true,
+        allowedHosts,
+        allowedOrigins,
+        enableDnsRebindingProtection: enableDnsProtection
+    });
+    await server.connect(httpTransport);
+    const httpServer = createServer(async (req, res) => {
+        const reqPath = new URL(req.url || '/', 'http://localhost').pathname;
+        if (reqPath !== normalizedPath) {
+            res.writeHead(404).end('Not Found');
+            return;
+        }
+        try {
+            await httpTransport.handleRequest(req, res);
+        }
+        catch (error) {
+            logger.error?.(`[ERROR] HTTP transport request failed: ${String(error)}`);
+            res.writeHead(500).end('Internal Server Error');
+        }
+    });
+    httpServer.listen(port, host, () => {
+        const displayHost = host === '0.0.0.0' ? 'localhost' : host;
+        logger.info?.(`[INFO] MCP HTTP server listening at http://${displayHost}:${port}${normalizedPath}`);
+    });
+    httpServer.on('error', (err) => {
+        logger.error?.(`[ERROR] HTTP server error: ${String(err)}`);
+    });
+}
+/**
+ * 交互式初始化：让用户选择 STDIO / HTTP 及 HTTP 参数，并将结果写入 ~/.zentao/transport.json
+ * 返回 true 表示已处理（应在入口处直接 exit）
+ */
+export async function interactiveInitTransport(options = {}) {
+    const args = options.args ?? [];
+    const logger = options.logger ?? {
+        info: (msg) => process.stdout.write(msg + '\n'),
+        error: (msg) => process.stderr.write(msg + '\n')
+    };
+    if (!args.includes('--init-transport')) {
+        return false;
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    const ask = (query) => new Promise(resolve => rl.question(query, resolve));
+    try {
+        logger.info?.('=== MCP 传输方式初始化 ===');
+        const modeInput = await ask('选择传输方式 (1) stdio (2) http [1]: ');
+        const chosenMode = modeInput.trim() === '2' ? 'http' : 'stdio';
+        if (chosenMode === 'stdio') {
+            saveTransportConfig({ transport: 'stdio' });
+            logger.info?.('已保存：使用 STDIO 传输');
+            return true;
+        }
+        const portInput = await ask('HTTP 端口 [3000]: ');
+        const pathInput = await ask('HTTP 路径前缀 (如 /mcp) [/mcp]: ');
+        const hostInput = await ask('监听地址 [0.0.0.0]: ');
+        const allowedHostsInput = await ask('允许的 Host 列表(逗号分隔，可留空): ');
+        const allowedOriginsInput = await ask('允许的 Origin 列表(逗号分隔，可留空): ');
+        const dnsInput = await ask('启用 DNS Rebinding 防护? (y/N): ');
+        const port = parsePort(portInput?.trim()) ?? DEFAULT_HTTP_PORT;
+        const pathSetting = pathInput?.trim() || '/mcp';
+        const host = hostInput?.trim() || '0.0.0.0';
+        const allowedHosts = allowedHostsInput.split(',').map(s => s.trim()).filter(Boolean);
+        const allowedOrigins = allowedOriginsInput.split(',').map(s => s.trim()).filter(Boolean);
+        const dnsProtection = dnsInput.trim().toLowerCase() === 'y';
+        const config = {
+            transport: 'http',
+            host,
+            port,
+            path: pathSetting.startsWith('/') ? pathSetting : `/${pathSetting}`,
+            allowedHosts: allowedHosts.length ? allowedHosts : undefined,
+            allowedOrigins: allowedOrigins.length ? allowedOrigins : undefined,
+            dnsProtection
+        };
+        saveTransportConfig(config);
+        logger.info?.(`已保存：HTTP 模式 http://${host}:${port}${config.path}`);
+        return true;
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/transportConfig.d.ts

@@ -0,0 +1,12 @@
+export type TransportMode = 'stdio' | 'http';
+export interface TransportConfig {
+    transport: TransportMode;
+    host?: string;
+    port?: number;
+    path?: string;
+    allowedHosts?: string[];
+    allowedOrigins?: string[];
+    dnsProtection?: boolean;
+}
+export declare function saveTransportConfig(config: TransportConfig): void;
+export declare function loadTransportConfig(): TransportConfig | null;

package/dist/transportConfig.js

@@ -0,0 +1,23 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const CONFIG_DIR = path.join(os.homedir(), '.zentao');
+const TRANSPORT_FILE = path.join(CONFIG_DIR, 'transport.json');
+export function saveTransportConfig(config) {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(TRANSPORT_FILE, JSON.stringify(config, null, 2));
+}
+export function loadTransportConfig() {
+    try {
+        if (fs.existsSync(TRANSPORT_FILE)) {
+            const config = JSON.parse(fs.readFileSync(TRANSPORT_FILE, 'utf-8'));
+            return config;
+        }
+    }
+    catch {
+        // ignore parse errors, return null
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zzp123/mcp-zentao",
-    "version": "1.18.7",
+    "version": "1.18.9",
     "description": "禅道项目管理系统的高级API集成包 - 完整版，包含所有94个工具。另有产品经理、测试工程师、开发工程师专用精简版本可选",
     "main": "dist/index.js",
     "type": "module",