Cat2Bug MCP 服务器

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

文档：专题与索引见 readme/文档索引.md。仓库内 Markdown 存放约定见 readme/文档规范.md（根目录仅保留本 README.md，其余文档放在 readme/）。

功能特性

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

安装

从 npm 安装（npm / pnpm / yarn）

npm、pnpm、yarn 都从同一 npm 注册表 拉包，任选其一即可：

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

不全局安装时，可用 npx @cat2bug/mcp（或 pnpm dlx @cat2bug/mcp、yarn dlx @cat2bug/mcp）直接运行已发布版本。

安装后 MCP 配置里把 command 指到可执行文件即可，例如全局安装后仍为命令名 cat2bug-mcp（与包名 @cat2bug/mcp 不同），或：

"command": "npx",
"args": ["-y", "@cat2bug/mcp"]

postinstall：安装完成后会尝试把包内自带的 Claude Code skills 复制到 ~/.claude/skills/。若不需要（CI 或企业环境），安装前可设环境变量：CAT2BUG_MCP_NO_SKILLS=1。

维护者发布到 npm（包名为 @cat2bug/mcp，需在 npm 上对 @cat2bug 作用域拥有 publish 权限；公开作用域包已配置 publishConfig.access）：

1. 登录：npm login（或使用 token 写入 ~/.npmrc）
2. 若出现 E403 … Two-factor authentication or granular access token with bypass 2fa enabled is required：说明当前账号启用了 2FA 或 npm 要求发布时必须满足其一——在终端用已开 2FA 的账号执行 npm publish 并按提示输入 OTP；或在 npm 网站 Access Tokens 创建 Granular Access Token，勾选 Publish 权限及 Bypass two-factor authentication (if enabled)（仅当你接受该选项且策略允许时），把 token 写入 ~/.npmrc 的 //registry.npmjs.org/:_authToken=。
3. 在本仓库根目录执行：npm publish（会执行 prepublishOnly：构建、测试、lint）

pnpm publish、yarn npm publish 与 npm publish 面向同一注册表，任选其一即可（需在对应客户端已登录 npm）。

前置要求

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

从源码安装

1. 克隆仓库：

git clone <repository-url>
cd cat2bug-mcp

2. 安装依赖：

npm install

3. 构建项目：

npm run build

4. 配置 Cat2Bug 凭证：在 MCP 的 env 中设置 CAT2BUG_BASE_URL + CAT2BUG_API_KEY，或写入 ~/.cat2bug-mcp/config.json，或使用 login 工具（见使用部分）

使用

在 Claude Code 中通过 MCP 手动接入的完整步骤（含 claude mcp add、.mcp.json、全局 env / 配置文件 / login 与 /dev-api 说明）见 readme/Claude-Code-使用指南.md。

启动服务器

npm start

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

开发模式

用于开发和自动重新加载：

npm run dev

配置

服务器将配置存储在 ~/.cat2bug-mcp/config.json 中。该文件包含：

• baseUrl: Cat2Bug 实例的基础 URL
• apiKey: 你的 Cat2Bug API 密钥

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

使用 Login 工具进行初始设置

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

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

成功响应：

{
  "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。

工具调用示例

查询缺陷列表

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

响应：

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

创建缺陷

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

错误处理

未登录错误

如果在调用工具前未配置 Base URL + API Key（env、配置文件或 login），可能收到错误响应，例如：

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "请配置 CAT2BUG_BASE_URL + CAT2BUG_API_KEY，或 ~/.cat2bug-mcp/config.json，或调用 login(url, apiKey)"
      }
    ],
    "isError": true
  }
}

API 错误

当 Cat2Bug API 返回错误时：

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

JSON-RPC 错误

对于协议级错误：

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

脚本命令

项目包含以下 npm 脚本：

# 开发模式（带自动重新加载）
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

测试

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

# 运行所有测试
npm test

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

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

测试覆盖率：

• 配置管理：91.66%
• API 客户端：76.31%
• 服务器：100%
• 认证：93.1%
• 集成：100%

详见 readme/测试文档.md。

部署

本地部署

npm install
npm run build
npm start

Docker 部署

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。