禅道 MCP 工具

这是一个基于 Python 的 MCP（Model Context Protocol）工具，用于连接禅道Bug管理系统。支持通过 npm/npx 直接使用。

使用场景与AI沟通话术

场景一：创建Bug

话术示例：

• "帮我创建一个Bug，标题是'登录页面验证码不显示'，重现步骤是：1. 打开登录页面 2. 点击验证码区域 3. 验证码未显示"
• "创建一个Bug，标题'支付接口超时'，步骤：调用支付接口后等待30秒无响应，截图路径是 /path/to/screenshot.png"
• "在禅道创建一个Bug，标题'数据导出功能异常'，重现步骤：进入数据管理页面，点击导出按钮，提示错误"

场景二：获取需求详情

话术示例：

• "帮我获取需求ID为12345的需求详情"
• "查询一下需求12345的详细信息，包括标题、描述、验收标准等"
• "获取需求12345的完整信息"

场景三：创建任务

话术示例：

• "帮我创建一个任务，任务名称是'优化登录接口性能'，分配给张三"
• "创建一个开发任务，名称'修复支付bug'，优先级高，分配给李四"
• "在禅道创建一个任务，标题'重构用户模块'，分配给王五，预计3天完成"

场景四：指派任务

话术示例：

• "把任务ID为67890的任务指派给张三"
• "将任务67890重新指派给李四，备注'需要紧急处理'"
• "指派任务67890给王五，备注说明'这个任务需要前端配合'"

场景五：查询BUG列表

话术示例：

• "帮我查询产品365下所有已确认的BUG"
• "查询产品365中分配给张三的未解决BUG"
• "获取产品365在2024-01-01到2024-01-31期间创建的BUG列表"
• "查询产品365中状态为'激活'的BUG，创建人是李四"
• "帮我拉取产品365下所有已确认但未解决的BUG"

场景六：批量解决BUG

话术示例：

• "批量解决产品365下的BUG，BUG ID是[76016, 75241]，解决方案是fixed，解决人是68249，解决版本是2700"
• "将产品365的BUG [76016, 75241] 标记为'设计如此'，解决人是张三"
• "批量解决BUG，产品ID 365，BUG列表[76016, 75241]，解决方案duplicate（重复上报），解决人李四"

场景七：创建测试用例

话术示例：

• "帮我创建一个接口测试用例，名称'用户登录接口测试'，接口地址是 /api/login，请求方法是POST"
• "创建一个功能测试用例，名称'用户注册流程测试'，步骤包括：1. 打开注册页面 2. 填写信息 3. 提交注册"
• "在禅道创建一个测试用例，类型是接口测试，名称'订单查询接口'"

场景八：批量创建测试用例

话术示例：

• "从CSV文件 /path/to/cases.csv 批量创建测试用例"
• "帮我将CSV文件中的测试用例批量提交到禅道，文件路径是 /path/to/test_cases.csv"
• "从CSV文件批量创建接口测试用例，文件路径 /path/to/api_cases.csv"

场景九：上传截图到BUG

话术示例：

• "把截图 /path/to/screenshot.png 上传到BUG 12345"
• "上传图片到BUG 12345，图片路径是 /path/to/image.jpg，文件名改为'错误截图'"
• "帮我把截图上传到BUG 12345的附件中"

场景十：查看配置

话术示例：

• "查看一下当前的禅道配置信息"
• "显示当前的配置"
• "获取配置信息"

功能特性

• ✅ 创建Bug（支持截图上传）
• ✅ 获取需求详情
• ✅ 创建任务
• ✅ 指派任务
• ✅ 查询BUG列表（支持多条件筛选）
• ✅ 批量解决BUG
• ✅ 创建测试用例
• ✅ 批量从CSV文件创建测试用例
• ✅ 上传图片到Bug附件
• ✅ 支持配置文件（支持JSON注释）
• ✅ 自动格式化步骤为HTML

安装

前置要求

• Node.js: >= 14.0.0
• Python: >= 3.10（必需，因为 mcp 包要求 Python 3.10+）

安装方式

方式一：通过 npx 使用（推荐，无需安装）

直接在 Cursor 配置中使用，无需手动安装：

npx -y @bangdao-ai/zentao-mcp@latest

方式二：全局安装

npm install -g @bangdao-ai/zentao-mcp@latest

方式三：本地安装（开发模式）

git clone https://github.com/bangdao-ai/zentao-mcp.git
cd zentao-mcp
pip3 install -r requirements.txt

详细安装指南请参考：docs/INSTALL.md

配置

在 Cursor 中配置

在 Cursor 的 MCP 配置文件中添加：

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": [
        "-y",
        "@bangdao-ai/zentao-mcp@latest"
      ],
      "env": {
        "ZENTAO_PRODUCT_ID": "your-product-id",
        "ZENTAO_OPENED_BY": "your-user-id",
        "KEY": "your-api-key",
        "ZENTAO_KEYWORDS": "AI",
        "ZENTAO_TITLE_PREFIX": "",
        "ZENTAO_ROLE_TYPE": "test"
      }
    }
  }
}

配置说明：

• ZENTAO_PRODUCT_ID（必需）：产品ID
• ZENTAO_OPENED_BY（必需）：创建人和指派人ID（同一个人），作为API认证的code参数
• KEY（必需）：API认证密钥，作为API认证的key参数
• ZENTAO_KEYWORDS（可选）：关键词，默认为空
• ZENTAO_TITLE_PREFIX（可选）：标题前缀，默认为空
• ZENTAO_ROLE_TYPE（可选）：角色类型，默认为"test"

兜底配置（可选）

如果未在环境变量中配置，可以使用配置文件 bug_config.json。配置文件路径可通过环境变量 ZENTAO_CONFIG_PATH 指定。

MCP 工具

1. create_bug

创建Bug到禅道系统。

参数：

• title (必需): Bug标题
• steps (必需): 重现步骤（支持换行，会自动转换为HTML格式）
• product_id (可选): 产品ID
• opened_by (可选): 创建人和指派人
• screenshot_path (可选): 截图文件路径
• severity (可选): 严重程度（默认3）
• pri (可选): 优先级（默认3）
• type (可选): Bug类型（默认codeissue）
• environment (可选): 环境（默认测试环境）
• story (可选): 相关需求id
• task (可选): 相关任务id
• mailto (可选): 抄送人账号
• keywords (可选): 关键词

2. upload_image_to_bug

上传图片到指定Bug的附件。

参数：

• bug_id (必需): Bug ID
• image_path (必需): 图片文件路径
• custom_filename (可选): 自定义文件名

3. create_case

创建测试用例到禅道系统。

参数：

• product (必需): 产品ID
• type (必需): 用例类型（interface 或 feature）
• title (必需): 用例名称
• opened_by (必需): 创建人
• module (可选): 模块ID（默认0）
• stage (可选): 阶段（默认intergrate）
• precondition (可选): 前置条件
• keywords (可选): 关键词
• steps (可选): 测试步骤数组
• expects (可选): 预期结果数组

4. create_cases_from_csv

从CSV文件批量创建测试用例。

参数：

• csv_file_path (必需): CSV文件路径
• case_type (可选): 用例类型（interface、feature、接口测试、功能测试，会自动识别）
• product_id (可选): 产品ID
• opened_by (可选): 创建人
• keywords (可选): 关键词

CSV格式：

• 接口测试用例需要包含：用例名称、接口地址、请求方法、请求体、断言、预期结果
• 功能测试用例需要包含：用例名称、预期结果

5. submit_csv_cases_to_zentao

将CSV文件中的所有测试用例提交到禅道（会自动备份原文件）。

参数：

• csv_file_path (必需): CSV文件路径
• case_type (可选): 用例类型（interface、feature、接口测试、功能测试，会自动识别）
• product_id (可选): 产品ID
• opened_by (可选): 创建人
• keywords (可选): 关键词

6. get_config

获取当前配置信息。

7. get_story_detail

获取需求详情。

参数：

• story_id (必需): 需求ID

返回：包含需求标题、描述、验收标准、创建人、指派人等详细信息

8. create_task

创建任务。

参数：

• task_data (必需): 任务数据对象，包含任务相关字段（form-data格式）

注意：任务数据的具体字段请参考禅道API文档，常见字段包括：

• name: 任务名称
• assignedTo: 指派人
• pri: 优先级
• estimate: 预计工时
• desc: 任务描述
• 等其他字段

9. assign_task

指派任务。

参数：

• task_id (必需): 任务ID
• assigned_to (必需): 新的指派人（姓名或工号）
• comment (可选): 指派备注

10. get_bug_list

拉取已确认/未解决的BUG列表。

参数：

• product_id (必需): 产品ID
• assigned_to (可选): 指派人（姓名或工号）
• opened_by (可选): 创建人（姓名或工号）
• resolved_by (可选): 解决人（姓名或工号）
• confirmed (可选): 是否确认（2=已确认，1=未确认，0或不传=所有）
• status (可选): 状态（激活/已解决/已关闭）
• start_date (可选): 创建开始日期（格式：YYYY-MM-DD）
• end_date (可选): 创建截止日期（格式：YYYY-MM-DD）

11. resolve_bug

批量解决BUG。

参数：

• product_id (必需): 产品ID
• bug_ids (必需): BUG ID列表（数组）
• resolution (必需): 解决方案，可选值：
  • fixed: 修复解决
  • bydesign: 设计如此
  • reqchange: 修改需求
  • duplicate: 重复上报
  • external: 外部原因
  • notrepro: 无法重现
  • postponed: 延期处理
  • willnotfix: 不予解决
  • tostory: 转为需求
  • history: 历史遗留
  • configchange: 调整配置
• resolved_by (必需): 解决人（姓名或工号）
• resolved_build (可选): 解决版本ID（当解决方案为fixed时必传）

项目结构

禅道mcp/
├── src/                        # 源码目录
│   ├── mcp_server.py          # MCP服务器主文件
│   └── zentao_nexus.py         # 禅道工具类
├── scripts/                    # 脚本目录
│   └── publish/                # 发布脚本
├── docs/                       # 文档目录
│   ├── PUBLISH.md              # 发布指南
│   └── README-PUBLISH.md       # 发布脚本使用指南
├── index.js                    # npm 入口文件
├── package.json                # npm 包配置
├── requirements.txt            # Python 依赖
└── README.md                   # 项目说明

详细的项目结构说明请参考 docs/PROJECT-STRUCTURE.md

发布

参考 PUBLISH.md 了解如何发布到 npm。

许可证

MIT