# cat2bug-mcp

**Repository Path**: cat2bug/cat2bug-mcp

## Basic Information

- **Project Name**: cat2bug-mcp
- **Description**: cat2bug与ai通讯的代理程序
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-10
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cat2Bug MCP 服务器

Cat2Bug 平台 API 的 MCP（模型上下文协议）服务器实现。该服务器使 Claude 和其他 MCP 客户端能够与 Cat2Bug 的缺陷管理、测试用例管理、项目管理和报告功能进行交互。

## 功能特性

- **23 个集成工具** - 全面的 Cat2Bug 平台交互
- **安全的 API 密钥管理** - 加密文件存储
- **完整的缺陷生命周期管理** - 创建、更新、处理、通过、驳回、关闭、重新开启
- **测试用例管理** - 列表、创建、更新、删除
- **项目和交付物管理**
- **团队成员管理**
- **缺陷报告和分析**
- **文件上传支持** - 图片和附件
- **JSON-RPC 2.0 协议** - 可靠的通信

## 安装

### 前置要求

- Node.js 18+
- npm 或 yarn
- Cat2Bug 平台实例（本地或远程）
- 有效的 Cat2Bug API 密钥

### 安装步骤

1. 克隆仓库：
```bash
git clone <repository-url>
cd cat2bug-mcp
```

2. 安装依赖：
```bash
npm install
```

3. 构建项目：
```bash
npm run build
```

4. 使用 `login` 工具配置 Cat2Bug 凭证（见使用部分）

## 使用

### 启动服务器

```bash
npm start
```

服务器将在 stdin/stdout 上监听 JSON-RPC 2.0 请求。

### 开发模式

用于开发和自动重新加载：
```bash
npm run dev
```

### 配置

服务器将配置存储在 `~/.cat2bug-mcp/config.json` 中。该文件包含：
- `baseUrl`: Cat2Bug 实例的基础 URL
- `apiKey`: 你的 Cat2Bug API 密钥

**安全提示**：配置文件以受限权限（模式 0600）创建，确保只有所有者可以读取。

### 使用 Login 工具进行初始设置

在使用其他工具之前，使用你的 Cat2Bug 实例进行身份验证：

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "login",
    "arguments": {
      "url": "http://localhost:8022",
      "apiKey": "your-api-key-here"
    }
  }
}
```

成功响应：
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "登录成功。配置已保存到 ~/.cat2bug-mcp/config.json"
      }
    ],
    "isError": false
  }
}
```

## 工具

该服务器提供 23 个工具，分为以下类别：

### 认证 (1 个工具)
- **login** - 使用 URL 和 API 密钥登录

### 缺陷管理 (10 个工具)
- **listDefects** - 查询缺陷列表
- **createDefect** - 创建缺陷
- **updateDefect** - 修改缺陷
- **getDefectDetail** - 查看缺陷详情
- **handleDefect** - 修复缺陷
- **passDefect** - 通过缺陷
- **rejectDefect** - 驳回缺陷
- **assignDefect** - 指派缺陷
- **closeDefect** - 关闭缺陷
- **openDefect** - 开启缺陷

### 项目管理 (1 个工具)
- **getProjectInfo** - 获取项目信息

### 成员管理 (1 个工具)
- **listMembers** - 查看项目成员列表

### 测试用例管理 (5 个工具)
- **listTestCases** - 查看测试用例列表
- **getTestCaseDetail** - 查看测试用例详情
- **createTestCase** - 创建测试用例
- **updateTestCase** - 更新测试用例
- **deleteTestCase** - 删除测试用例

### 交付物管理 (3 个工具)
- **listDeliverables** - 查看交付物树形列表
- **getDeliverableDetail** - 查看交付物详情
- **createDeliverable** - 创建交付物

### 报告管理 (1 个工具)
- **pushDefectReport** - 推送缺陷报告

### 文件管理 (1 个工具)
- **uploadImage** - 上传图片

详细的工具文档请参见 `readme/工具参考.md`。

## 工具调用示例

### 查询缺陷列表

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "listDefects",
    "arguments": {
      "pageNum": 1,
      "pageSize": 10
    }
  }
}
```

响应：
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"total\": 100, \"rows\": [...]}"
      }
    ],
    "isError": false
  }
}
```

### 创建缺陷

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "createDefect",
    "arguments": {
      "defectName": "登录按钮无响应",
      "defectType": 1,
      "defectLevel": 2,
      "defectDescribe": "点击登录按钮时没有反应"
    }
  }
}
```

## 错误处理

### 未登录错误

如果在调用工具前未登录，将收到错误响应：

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "请先调用 login(url, apiKey)"
      }
    ],
    "isError": true
  }
}
```

### API 错误

当 Cat2Bug API 返回错误时：

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "API 错误: 缺陷不存在"
      }
    ],
    "isError": true
  }
}
```

### JSON-RPC 错误

对于协议级错误：

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "error": {
    "code": -32602,
    "message": "无效参数",
    "data": "缺少必需参数: defectName"
  }
}
```

## 脚本命令

项目包含以下 npm 脚本：

```bash
# 开发模式（带自动重新加载）
npm run dev

# 构建项目
npm run build

# 启动服务器
npm start

# 运行测试
npm test

# 代码检查
npm run lint

# 清理构建文件
npm run clean

# 重新构建
npm run rebuild

# 代码格式化
npm run format

# 类型检查
npm run type-check

# 发布前准备
npm run prepublishOnly
```

## 测试

项目包含全面的测试套件：

```bash
# 运行所有测试
npm test

# 运行特定测试文件
npm test -- config.test.ts

# 生成覆盖率报告
npm test -- --coverage
```

测试覆盖率：
- 配置管理：91.66%
- API 客户端：76.31%
- 服务器：100%
- 认证：93.1%
- 集成：100%

详见 `readme/测试文档.md`。

## 部署

### 本地部署

```bash
npm install
npm run build
npm start
```

### Docker 部署

```bash
docker build -t cat2bug-mcp .
docker run -it cat2bug-mcp
```

### 生产部署

详见 `readme/部署指南.md`。

## 安全

### API 密钥管理

- API 密钥存储在 `~/.cat2bug-mcp/config.json`
- 文件权限设置为 600（仅所有者可读写）
- 建议在生产环境使用专用的 API 密钥
- 定期轮换 API 密钥

详见 `readme/安全指南.md`。

## 故障排除

常见问题和解决方案请参见 `readme/故障排除.md`。

## 快速开始

5 分钟快速开始指南请参见 `readme/快速开始.md`。

## 贡献

欢迎贡献。请确保：
1. 代码遵循现有风格
2. 所有测试通过
3. 新功能包含测试
4. 文档已更新

详见 `readme/贡献指南.md`。

## 许可证

MIT

## 支持

如有问题、疑问或功能请求，请在项目仓库中提交 issue。

## 更新日志

### 版本 0.1.0
- 初始发布
- 23 个 Cat2Bug 平台集成工具
- 安全的 API 密钥管理
- 完整的缺陷生命周期管理
- 测试用例管理
- 项目和交付物管理
- 团队成员管理
- 缺陷报告
- 文件上传支持

详见 `readme/更新日志.md`。