# ZenTao Bugs MCP Server

基于 FastMCP 的禅道 Bug 管理 MCP 服务器，提供产品搜索、Bug 查询和解决功能。

## 🚀 快速开始

### 安装

```bash
npm install -g mcp-zentao-bugs
```

### 配置与运行

#### 方法1: 设置环境变量
```bash
export ZENTAO_BASE_URL="https://your-zentao.com"
export ZENTAO_ACCOUNT="your-username"
export ZENTAO_PASSWORD="your-password"
mcp-zentao-bugs
```

#### 方法2: 使用 .env 文件
```bash
# 在当前目录创建 .env 文件
echo "ZENTAO_BASE_URL=https://your-zentao.com" > .env
echo "ZENTAO_ACCOUNT=your-username" >> .env
echo "ZENTAO_PASSWORD=your-password" >> .env
mcp-zentao-bugs
```

> 💡 **提示**：全局安装后，`.env` 文件会自动被加载，无需额外配置。

#### 方法3: 一次性设置
```bash
ZENTAO_BASE_URL="https://your-zentao.com" \
ZENTAO_ACCOUNT="your-username" \
ZENTAO_PASSWORD="your-password" \
mcp-zentao-bugs
```

### 命令行选项

```bash
mcp-zentao-bugs --help      # 显示帮助信息
mcp-zentao-bugs --version   # 显示版本信息
```

## 功能特性

- 🔐 **自动登录** - 启动时自动登录禅道并持有 Token
- 🧠 **智能搜索** - 一步完成产品和BUG搜索：找到唯一产品时直接返回BUG列表，多个产品时提供选择
- 🐛 **Bug 管理** - 查询产品下的 Bug、获取详情、标记解决
- 🖼️ **图片提取** - 自动从BUG步骤中提取图片URL，便于查看截图
- 🎯 **精准搜索** - API层面过滤激活BUG，自动翻页确保获取足够的活跃BUG
- 📡 **SSE 流式传输** - 通过 Server-Sent Events 实时推送日志和结果
- 🔄 **串行处理** - 单进程队列处理，确保工具调用有序执行
- 🚀 **FastMCP 标准** - 兼容 MCP 协议，支持 HTTP Streaming 和 SSE
- 📉 **流量优化** - 智能合并搜索步骤，减少API调用和数据传输

## 工具列表

| 工具名 | 参数 | 描述 |
|--------|------|------|
| `searchProducts` | `keyword?: string`, `limit?: number` | **搜索产品**：查看有哪些可用的产品，帮助选择精确的产品名称。支持关键词搜索 |
| `getMyBug` | `productName: string`, `keyword?: string` | **获取我的BUG详情**：获取指定产品的一个BUG详情（指派给我的激活BUG）。**这是最常用的工具**，直接返回BUG的完整详情，而不是列表。**使用产品名称而不是ID，更符合业务习惯** |
| `getMyBugs` | `productId: number`, `keyword?: string`, `allStatuses?: boolean`, `limit?: number` | **获取我的BUG列表**：获取指派给我的BUG列表（**默认只返回激活状态**）。用于查看需要处理的BUG列表。**必须指定产品ID以保持专注** |
| `getNextBug` | `productId: number`, `keyword?: string` | **获取下一个BUG**：获取下一个需要处理的BUG（指派给我的激活BUG）。使用 **for yield 生成器模式**，高效找到第一个匹配的BUG后立即返回。**必须指定产品ID以保持专注** |
| `getBugStats` | `productId: number`, `activeOnly?: boolean` | **BUG统计**：获取指派给我的BUG统计信息（总数、激活数量等）。用于了解工作量和进度。**必须指定产品ID以保持专注** |
| `getBugDetail` | `bugId: number` | **BUG详情**：返回 Bug 全字段 + 原始 HTML 步骤 + 提取的图片URL列表 |
| `markBugResolved` | `bugId: number`, `comment?: string` | **标记已解决**：把 Bug 置为已解决（resolution=fixed） |

### 典型工作流程

#### 🔄 日常BUG处理流程

**步骤1：查看可用产品（可选）**
```json
{
  "keyword": "电商",
  "limit": 10
}
```
- 🔍 **产品发现**：查看有哪些可用的产品
- 📝 **精确命名**：获取准确的产品名称，避免模糊匹配

**步骤2：获取一个BUG的完整详情**
```json
{
  "productName": "电商平台",
  "keyword": "登录"
}
```
- 🎯 **精准定位**：通过产品名称自动找到指派给你的第一个激活BUG
- 📋 **完整详情**：直接返回BUG的完整信息，无需额外调用
- ⚡ **高效搜索**：使用产品名称，更符合业务习惯
- 🔍 **精确匹配**：如果找到多个产品会提示用户选择，确保准确性

**步骤3：标记为已解决**
```json
{
  "bugId": 123,
  "comment": "已修复登录页面显示问题"
}
```
- ✅ **快速解决**：一键标记BUG为已解决状态

**步骤4：继续下一个**
重复步骤2，处理下一个BUG...

#### 📊 其他工具使用场景

**查看BUG列表（批量操作时）**
```json
{
  "productId": 1,
  "limit": 20,
  "keyword": "界面"
}
```

**查看BUG统计**
```json
{
  "productId": 1,
  "activeOnly": true
}
```

#### 📊 工作量管理

**查看我的BUG统计**
```json
{
  "productId": 1,
  "activeOnly": true
}
```
- 📈 **工作量统计**：了解当前有多少激活BUG需要处理
- 📋 **优先级排序**：按严重程度自动排序

**查看我的BUG列表**
```json
{
  "productId": 1,
  "limit": 20,
  "keyword": "界面"
}
```
- 📝 **批量查看**：获取指派给你的BUG列表
- 🔍 **关键词搜索**：快速定位特定类型的BUG

#### 🎯 工具优势

- **🎯 默认指派给我**：所有工具默认只查询指派给你的BUG，减少干扰
- **⚡ 默认激活状态**：默认只显示激活状态的BUG，专注待处理任务
- **🏷️ 产品名称友好**：主要工具支持使用产品名称而不是ID，更符合业务习惯
- **📋 直接返回详情**：`getMyBug` 直接返回BUG的完整详情，减少调用步骤
- **🔍 精确匹配验证**：模糊搜索产品时，如果找到多个产品会提示用户选择，确保准确性
- **🔒 必须指定产品**：所有工具都要求指定产品，确保一段时间内专注一个产品
- **🔄 流程优化**：工具设计完全符合"获取→处理→解决→下一个"的工作流程
- **💰 流量节省**：使用生成器模式，找到即停止，避免不必要的数据传输
- **📊 智能统计**：提供准确的工作量统计，便于进度管理

### 图片提取功能

`getBugDetail` 工具现在支持自动从BUG步骤中提取图片：

```json
{
  "bug": {
    "id": 123,
    "title": "登录页面显示异常",
    "steps": "<p>步骤1：打开登录页面</p><p><img src=\"https://example.com/screenshot.png\" /></p>",
    "stepsImages": [
      "https://example.com/screenshot.png"
    ]
  }
}
```

**特性**：
- 🖼️ **自动识别** - 从HTML内容中提取所有`<img>`标签的`src`属性
- 🔗 **URL过滤** - 只返回HTTP/HTTPS开头的有效图片链接
- 📋 **独立存储** - 图片URL单独存储在`stepsImages`数组中，便于访问 |

## 快速开始

### 1. 环境配置

复制 `.env.example` 为 `.env` 并配置禅道信息：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# 禅道配置
ZENTAO_BASE_URL=https://your-zentao.com/api.php/
ZENTAO_ACCOUNT=your-username
ZENTAO_PASSWORD=your-password

# 服务器端口
PORT=3000
```

### 2. 安装依赖

```bash
pnpm install
```

### 3. 启动服务器

```bash
# 方式1: 使用 npx (推荐)
npx mcp-zentao-bugs

# 方式2: 本地安装后运行
pnpm start

# 方式3: 开发模式（文件变化自动重启）
pnpm dev
```

服务器启动后会：
- 自动登录禅道获取 Token
- 在指定端口启动 HTTP Streaming 服务
- 提供 `/mcp`（HTTP Streaming）和 `/sse`（SSE）端点

### 4. 健康检查

```bash
curl http://localhost:3000/health
```

## MCP 客户端配置

### Trae / Claude Code 配置

在 Trae 或 Claude Code 的 MCP 配置中添加：

```json
{
  "mcpServers": {
    "zentao-server": {
      "url": "http://localhost:3000/sse"
    }
  }
}
```

### Claude Desktop 配置

在 Claude Desktop 的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "zentao-server": {
      "command": "node",
      "args": ["src/mcp-server.mjs"],
      "env": {
        "ZENTAO_BASE_URL": "https://your-zentao.com/api.php/",
        "ZENTAO_ACCOUNT": "your-username",
        "ZENTAO_PASSWORD": "your-password",
        "PORT": "3000"
      }
    }
  }
}
```

## 开发

### 项目结构

```
├── src/
│   ├── mcp-server.mjs     # FastMCP 服务器主文件
│   ├── zentao-api.mjs     # 禅道 API 封装模块
│   └── server.mjs         # 原始 SSE 服务器（备用）
├── scripts/               # 发布和工具脚本
│   ├── publish.sh         # Linux/macOS 发布脚本
│   ├── publish.bat        # Windows 发布脚本
│   └── pre-publish.js     # 发布前检查脚本
├── api-docs/              # API 文档
├── .env                   # 环境变量配置
├── .env.example           # 环境变量模板
├── package.json
└── README.md
```

### 环境变量

| 变量名 | 必填 | 说明 |
|--------|------|------|
| `ZENTAO_BASE_URL` | ✅ | 禅道 API 基础地址 |
| `ZENTAO_ACCOUNT` | ✅ | 禅道登录账号 |
| `ZENTAO_PASSWORD` | ✅ | 禅道登录密码 |
| `PORT` | ❌ | 服务器端口（默认：3000） |

### 脚本命令

```bash
# 安装依赖
pnpm install

# 启动服务器
pnpm start

# 开发模式（监听文件变化）
pnpm dev
```

## API 端点

- **HTTP Streaming**: `http://localhost:3000/mcp`
- **SSE**: `http://localhost:3000/sse`
- **健康检查**: `http://localhost:3000/health`

## 技术栈

- **FastMCP** - MCP 服务器框架
- **Node.js 20+** - 运行时环境
- **Zod** - 参数验证
- **dotenv** - 环境变量管理
- **模块化架构** - 禅道API独立封装，便于维护和测试

## 故障排除

### 登录失败

1. 检查 `.env` 文件中的禅道配置是否正确
2. 确认网络可以访问禅道服务器
3. 验证账号密码是否有权限访问 API

### 连接问题

1. 确认服务器已启动：`curl http://localhost:3000/health`
2. 检查防火墙设置，确保端口可访问
3. 查看服务器日志获取详细错误信息

### 工具调用失败

1. 检查禅道 Token 是否有效（Token 过期需要重启服务器）
2. 确认传入的参数格式正确
3. 查看服务器日志中的错误信息

### API 分页问题

**问题描述**：禅道API的分页机制存在特殊行为，当请求的页码超出最大页数时，API不会返回空数据，而是返回第一页的数据，但返回的页码字段与请求的页码不一致。

**解决方案**：
- **分页有效性检查**：通过比较 `data.page` 与请求的 `page` 参数来判断是否超出最大页数
- **智能分页**：逐页获取数据，当检测到页码不一致时停止分页
- **性能优化**：设置合理的最大页数限制（50页），防止无限循环
- **数据完整性**：确保在到达最后一页时正确处理所有数据

**实现细节**：
```javascript
// 检查分页是否有效：如果返回的页码与请求的页码不一致，说明已超出最大页数
if (data.page && data.page !== page) {
  break; // 已到达最后一页
}
```

## 发布到 npmjs

### 发布前准备

1. **注册 npm 账号**
   ```bash
   npm adduser
   # 或使用现有账号: npm login
   ```

2. **检查项目状态**
   ```bash
   # 运行发布前检查
   npm run pre-release
   
   # 或手动检查
   ./scripts/publish.sh patch --dry-run
   ```

### 发布流程

#### 方式1: 使用发布脚本 (推荐)

```bash
# 发布补丁版本
./scripts/publish.sh patch

# 发布次要版本
./scripts/publish.sh minor

# 发布主要版本
./scripts/publish.sh major
```

#### 方式2: 使用 npm 命令

```bash
# 发布补丁版本
npm run release:patch

# 发布次要版本
npm run release:minor

# 发布主要版本
npm run release:major
```

#### 方式3: 手动发布

```bash
# 1. 更新版本
npm version patch

# 2. 发布
npm publish

# 3. 推送标签
git push && git push --tags
```

### 发布脚本功能

- **自动检查**: 检查项目状态、依赖、文件完整性
- **版本管理**: 自动更新版本号并创建 git tag
- **安全发布**: 检查 npm 登录状态和包名可用性
- **跨平台支持**: 提供 bash 和 Windows batch 脚本

### 版本管理策略

- **patch**: 修复 bug，向后兼容 (1.0.0 → 1.0.1)
- **minor**: 新增功能，向后兼容 (1.0.0 → 1.1.0)
- **major**: 重大变更，可能不兼容 (1.0.0 → 2.0.0)

### 发布检查清单

- [ ] 测试通过 (`npm test`)
- [ ] README.md 更新完整
- [ ] 版本号已更新
- [ ] 所有更改已提交
- [ ] npm 账号已登录
- [ ] 包名可用性检查

## 许可证

ISC License