# 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-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cat2Bug MCP 代理服务

MCP，通常指 Model Context Protocol（模型上下文协议），它是 AI 大模型统一连接外部工具和数据源的一套标准接口。Cat2Bug-MCP服务使 Claude Code、CodeX、Cursor等AI工具能够与 Cat2Bug-Platform 的缺陷管理、测试用例管理、项目管理和报告功能进行交互，我们可以通过聊天方式让AI帮我们测试、修复、检测缺陷。

![Cat2Bug-MCP介绍](readme/assets/cat2bug-mcp-architecture.png)

## 功能特性

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

## 关联产品

| 名称                                                          | 类型          | 说明                                                                |
|-------------------------------------------------------------|-------------|:------------------------------------------------------------------|
| [Cat2Bug-Platform](https://gitee.com/cat2bug/cat2bug-platform) | 缺陷管理平台      | 缺陷管理平台，用于管理测试用例、测试计划、需求、任务、BUG、文档等  |
| [Cat2Bug-App](https://gitee.com/cat2bug/cat2bug-app)        | 缺陷管理手机端     | Cat2Bug-Platform平台的手机端系统                                          |
| [Cat2Bug-Chrome](https://gitee.com/cat2bug/cat2bug-chrome)     | 缺陷管理谷歌浏览器插件 | Cat2Bug-Platform平台的谷歌浏览器插件                                        |
| [Cat2Bug-JLog](https://gitee.com/cat2bug/cat2bug-jlog)      | 错误日志采集框架    | 获取项目中的异常日志，并将日志报告提交到Cat2Bug-Platform                              |
| [Cat2Bug-JUnit](https://gitee.com/cat2bug/cat2bug-junit) | 单元测试框架      | 自动化单元测试框架，目前可以自动扫描Controller接口，随机提供参数测试，并将测试报告提交到Cat2Bug-Platform |


## 安装

### 前置要求

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

### 从 npm 安装（npm / pnpm / yarn）

**npm、pnpm、yarn 都从同一 [npm 注册表](https://www.npmjs.com/) 拉包**，任选其一即可：

```bash
npm install -g @cat2bug/mcp
# 或
pnpm add -g @cat2bug/mcp
# 或
yarn global add @cat2bug/mcp
```

### 从源码安装

1. 克隆仓库：
```bash
git clone https://gitee.com/cat2bug/cat2bug-mcp.git
cd cat2bug-mcp
```

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

3. 构建项目：
```bash
npm run build
```
构建完成后，项目根目录会生成dist文件夹，里面的文件即是编译好的服务程序。

## 使用

以下以 **Cursor** 为例，说明如何配置并在对话中使用 Cat2Bug MCP。Claude Code、CodeX 等支持 MCP 的 AI 工具配置方式类似，仅需将 MCP 配置文件路径改为对应产品要求即可。

### 1. 准备 API 密钥

1. 启动并登录 [Cat2Bug-Platform](https://gitee.com/cat2bug/cat2bug-platform)。
2. 进入目标项目的 **API 管理**（或项目设置中的 API Key 入口），创建或复制 **项目 API 密钥**。

> 注意：API 密钥与项目绑定。

### 2. 在 Cursor 中配置 MCP

Cursor 通过 **stdio** 启动 MCP 进程。配置文件可放在：

| 作用域 | 路径 | 说明 |
|--------|------|------|
| 当前项目 | `.cursor/mcp.json` | 仅在本仓库/项目生效，适合团队各自填 Key |
| 全局 | `~/.cursor/mcp.json` | 本机所有 Cursor 工作区可用 |

仓库内提供了示例 [`readme/cursor-mcp.json.example`](readme/cursor-mcp.json.example)。复制为项目下的 `.cursor/mcp.json`（或写入 `~/.cursor/mcp.json`）后填入你的地址与密钥（**`.cursor/` 目录已在 `.gitignore` 中，勿把含真实 Key 的配置提交到 git**）。

#### 方式 A：从源码运行（本仓库开发）

先完成 [安装](#安装) 中的 `npm install` 与 `npm run build`，再配置：

```json
{
  "mcpServers": {
    "cat2bug": {
      "command": "node",
      "args": ["/你的路径/cat2bug-mcp/dist/index.js"],
      "env": {
        "CAT2BUG_BASE_URL": "http://localhost:2020",
        "CAT2BUG_API_KEY": "你的项目API密钥"
      }
    }
  }
}
```

将 `args` 中的路径改为你本机 `cat2bug-mcp` 仓库里 **`dist/index.js` 的绝对路径**。

#### 方式 B：从 npm 全局安装

```bash
npm install -g @cat2bug/mcp
```

```json
{
  "mcpServers": {
    "cat2bug": {
      "command": "cat2bug-mcp",
      "env": {
        "CAT2BUG_BASE_URL": "http://localhost:2020",
        "CAT2BUG_API_KEY": "你的项目API密钥"
      }
    }
  }
}
```

#### 方式 C：npx 免安装

```json
{
  "mcpServers": {
    "cat2bug": {
      "command": "npx",
      "args": ["-y", "@cat2bug/mcp"],
      "env": {
        "CAT2BUG_BASE_URL": "http://localhost:2020",
        "CAT2BUG_API_KEY": "你的项目API密钥"
      }
    }
  }
}
```

#### 凭证的另外两种方式（可选）

除 MCP `env` 外，还可任选其一补全或替代凭据（**`env` 中已设置的项优先于配置文件**）：

- **配置文件**：`~/.cat2bug-mcp/config.json`，内容形如 `{"baseUrl":"http://localhost:2020","apiKey":"你的密钥"}`。
- **对话内 login**：在 Cursor 聊天中让 AI 调用 **`login`** 工具，传入 `url` 与 `apiKey`，会写入上述配置文件并作用于当前 MCP 会话。

### 3. 启用并重载 MCP

1. 保存 `.cursor/mcp.json`（或 `~/.cursor/mcp.json`）。
2. 打开 Cursor **Settings → MCP**，确认出现 **`cat2bug`** 服务器且状态为已连接（绿色）。
3. 若刚修改配置，在 MCP 面板点击 **Refresh**，或重启 Cursor。

连接成功后，Agent 对话中会出现 Cat2Bug 相关工具（如 `listDefects`、`createDefect`、`list_test_cases` 等）。

### 4. 在对话中使用

配置完成后，**直接用自然语言**在 Cursor 聊天或 Agent 模式中操作即可，无需手写 JSON-RPC。例如：

| 你说的话 | MCP 会做的事 |
|----------|----------------|
| 「帮我查一下缺陷列表」 | 调用 `listDefects` |
| 「创建一个缺陷，标题是登录按钮无响应」 | 调用 `createDefect` |
| 「查看 #12 缺陷详情」 | 调用 `getDefectDetail` |
| 「列出测试用例」 | 调用 `list_test_cases` |
| 「获取当前项目信息」 | 调用 `get_project_info` |

也可以带筛选条件，例如：「查处理中的 BUG」「把缺陷指派给 demo」。

**建议工作流：**

1. 先问「查一下项目信息和成员列表」，确认已连上正确项目。
2. 再查缺陷/用例，或让 AI 根据用例协助测试、登记缺陷。
3. 需要换项目或轮换 Key 时，改 MCP `env` 或调用 `login`。

更完整的参数说明见 [readme/工具参考.md](readme/工具参考.md)；Claude Code 专项说明见 [readme/Claude-Code-使用指南.md](readme/Claude-Code-使用指南.md)。

### 5. 常见问题

| 现象 | 处理 |
|------|------|
| MCP 未出现或报错 | 确认 Node.js ≥ 18；源码方式需已 `npm run build`；`args` 路径为**绝对路径** |
| `系统尚未完成安装，请先完成安装向导` | 在浏览器打开 Cat2Bug 平台，先完成安装向导 |
| 401 / Access Denied | 检查 `CAT2BUG_API_KEY` 是否为**当前项目**的 Key；`CAT2BUG_BASE_URL` 是否正确（含 `/dev-api` 时勿漏） |
| 工具列表为空 | MCP 面板 Refresh；确认 JSON 格式正确、服务器名为 `cat2bug` |

排障详见 [readme/故障排除.md](readme/故障排除.md)。

## Cat2Bug交流群

| QQ群： [731462000](https://qm.qq.com/cgi-bin/qm/qr?k=G_vJa478flcFo_1ohJxNYD0mRKafQ7I1&jump_from=webapi&authKey=EL0KrLpnjYWqNN9YXTVksNlNFrV9DHYyPMx2RVOhXqLzfnmc+Oz8oQ38aBOGx90t) | 微信群：Cat2Bug                                                                 |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| <img src="https://www.cat2bug.com/prod-api/images/qq.png" style="width: 150px; height: 150px;">                                                                  | <img src="https://www.cat2bug.com/prod-api/images/wechat.png" style="width: 150px; height: 150px;"> |