BugMojo

@bugmojo/mcp-server

将 AI 编码 Agent — Claude Code、Cursor、VS Code、Claude Desktop — 连接到 BugMojo 缺陷跟踪系统的 MCP 服务。

为什么使用

BugMojo 可直接从浏览器捕获像素级精准的缺陷报告，包括会话回放、控制台日志、网络请求和屏幕截图。此 MCP 服务会将这些上下文交给你的 AI 编码 Agent：它可以通过经 API 密钥验证的 BugMojo REST API 列出、搜索和读取缺陷，提交新缺陷，更新状态／优先级／受派人，以及添加评论。你的 Agent 可以依据完整的捕获上下文修复缺陷，而不只是根据一行描述。

需要完整功能吗？ 回归测试套件／运行、测试工作流、Agent、会话回放摘要，以及内联控制台／网络日志，可通过 https://www.bugmojo.com/api/mcp 上托管的 OAuth 身份验证 HTTP 端点使用 — 请参阅下文的完整功能（OAuth HTTP）。此 npm 包有意保持为精简的缺陷处理封装，让每个工具都对应一个真实端点（不会出现 404）。

安装

需要 Node.js 18+。 无需安装 — MCP 客户端会使用 npx 运行它：

npx -y @bugmojo/mcp-server

也可以全局安装 bugmojo-mcp 命令：

npm install -g @bugmojo/mcp-server
# or
pnpm add -g @bugmojo/mcp-server
# or
yarn global add @bugmojo/mcp-server

它通过 stdio 使用 MCP，并读取两个环境变量（见下文）。

快速开始（Claude Code，60 秒）

1. 在 BugMojo 控制面板的 Settings → API Keys 下生成 API 密钥（密钥以 bm_key_ 开头）。
2. 注册此服务：

claude mcp add bugmojo -e BUGMOJO_API_KEY=bm_key_your_key_here -- npx -y @bugmojo/mcp-server

3. 向 Claude 提问：“列出未解决的 CRITICAL 缺陷，并总结最新的一项。”

配置

变量	必需	说明
BUGMOJO_API_KEY	✅	你的 BugMojo API 密钥（以 bm_key_ 开头）。在控制面板的 Settings → API Keys 下生成。
BUGMOJO_API_URL	—	你的 BugMojo 实例的基础 URL。默认为 https://www.bugmojo.com — 仅在使用可自托管或本地实例时设置（例如 http://localhost:3000）。

客户端设置

Claude Code

使用 CLI（针对当前用户）：

claude mcp add bugmojo -e BUGMOJO_API_KEY=bm_key_your_key_here -- npx -y @bugmojo/mcp-server

或者在仓库根目录中提交项目级 .mcp.json，供整个团队使用：

{
  "mcpServers": {
    "bugmojo": {
      "command": "npx",
      "args": ["-y", "@bugmojo/mcp-server"],
      "env": {
        "BUGMOJO_API_KEY": "bm_key_your_key_here"
      }
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "bugmojo": {
      "command": "npx",
      "args": ["-y", "@bugmojo/mcp-server"],
      "env": {
        "BUGMOJO_API_KEY": "bm_key_your_key_here"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（针对项目）：

{
  "mcpServers": {
    "bugmojo": {
      "command": "npx",
      "args": ["-y", "@bugmojo/mcp-server"],
      "env": {
        "BUGMOJO_API_KEY": "bm_key_your_key_here"
      }
    }
  }
}

VS Code（MCP）

.vscode/mcp.json：

{
  "servers": {
    "bugmojo": {
      "command": "npx",
      "args": ["-y", "@bugmojo/mcp-server"],
      "env": {
        "BUGMOJO_API_KEY": "bm_key_your_key_here"
      }
    }
  }
}

其他 MCP 客户端

将客户端指向相同的 stdio 命令：npx -y @bugmojo/mcp-server（或全局安装后使用 bugmojo-mcp），并在环境中设置 BUGMOJO_API_KEY。只有在使用可自托管实例时才添加 BUGMOJO_API_URL。

工具

工具	功能
list_bugs	按项目、状态、优先级和受派人列出／筛选缺陷（分页）。
get_bug	查看单个缺陷的完整详情：描述、评论、标签、录屏／屏幕截图。
search_bugs	对缺陷标题和描述进行全文搜索。
create_bug	在项目中创建缺陷（标题、描述、优先级、受派人）。需要具有写入权限的密钥。
update_bug	更新状态、优先级、受派人、标题或描述。需要具有写入权限的密钥。
add_comment	为缺陷添加评论。需要具有写入权限的密钥。

这就是此 npm 包的全部内容 — 六个工具，每个工具都对应一个真实的 /api/v1/bugs/* 端点。

完整功能（OAuth HTTP）

回归测试套件/运行、测试（QA）工作流、Agent、会话回放摘要（summarize_replay）以及内联控制台/网络日志（get_bug_console_logs、get_bug_network_logs）由托管的、通过 OAuth 2.1 认证的流式端点提供，而不是由此 npm 包提供。将支持 HTTP 的 MCP 客户端指向：

https://www.bugmojo.com/api/mcp

客户端首次使用时会打开浏览器进行登录（无需管理 API 密钥）。可选查询参数：?workspace=<slug> 将连接绑定到工作区，?mode=admin 则会额外开放管理工具。

// Claude Code / clients that support remote MCP servers
{
  "mcpServers": {
    "bugmojo": {
      "type": "http",
      "url": "https://www.bugmojo.com/api/mcp"
    }
  }
}

示例

配置完成后，可以向 Agent 提出如下要求：

“列出项目 X 中所有未关闭的严重级别 BUG，打开最新的一条，并总结复现步骤。”

Agent 会调用 list_bugs（status=OPEN、priority=CRITICAL），然后调用 get_bug 获取完整上下文，包括 BugMojo 在浏览器中捕获的会话回放。

工作原理

此包是一个精简的无状态客户端：它将 MCP 工具调用转换为经过身份验证的 HTTPS 请求，发送到 BugMojo REST API（/api/v1）。所有业务逻辑和数据都存储在你的 BugMojo 实例中，本地不会存储任何内容。

故障排除

“BUGMOJO_API_KEY environment variable is required”
密钥未传递到服务器进程。在 MCP 配置的 env 块中填写密钥（或向 claude mcp add 传入 -e BUGMOJO_API_KEY=...）——并非所有 MCP 客户端都会继承 shell 导出的环境变量。

“BUGMOJO_API_KEY must start with 'bm_key_' prefix”
你复制了错误的值（例如会话令牌或被截断的密钥）。在控制面板的 Settings → API Keys 下重新生成密钥，并复制完整的 bm_key_... 字符串。

“Authentication failed ... Check your BUGMOJO_API_KEY”（401）
密钥已被撤销，或属于其他实例。请生成新的密钥；如果你使用可自托管版本，也请确认 BUGMOJO_API_URL 指向该实例。

创建/更新/评论时出现“Permission denied”（403）
你的密钥为只读。create_bug、update_bug 和 add_comment 需要具有写入权限范围的密钥。

“fetch failed” / ECONNREFUSED
服务器无法访问 BUGMOJO_API_URL。默认值为 https://www.bugmojo.com；如果你设置了自托管/本地 URL，请确保对应实例正在运行且可访问。

首次运行时服务器立即断开连接
请确保配置使用 "args": ["-y", "@bugmojo/mcp-server"]——如果没有 -y，npx 首次运行时的“Ok to proceed?”提示会卡住 stdio 握手。同时确认 node --version 为 18 或更高版本。

相关包

包	用途
@bugmojo/widget	与框架无关的站点内反馈与采集组件核心
@bugmojo/react	React / Next.js SDK——提供程序、错误边界、钩子
@bugmojo/react-native	React Native + Expo SDK——摇一摇提交报告
@bugmojo/cli	获取 BUG 的 Playwright 复现包，并在本地验证修复

链接

• 网站 — https://www.bugmojo.com
• 文档与问题（GitHub）— https://github.com/viveksinra/bugmojo-sdk
• 问题 — https://github.com/viveksinra/bugmojo-sdk/issues
• 更新日志 — https://github.com/viveksinra/bugmojo-sdk/blob/main/packages/mcp-server/CHANGELOG.md
• Model Context Protocol — https://modelcontextprotocol.io

许可证

MIT © Softech Infra