bugAgent

官方

将bugAgent连接到任何兼容MCP的AI客户端。直接从AI编码助手中提交、分类和管理缺陷、功能请求等。无需切换上下文，无需复制粘贴——只需描述问题，bugAgent会处理其余部分。

访问 bugagent.com

你可以用 bugAgent MCP 做什么？

  • 提交错误报告 — 用自然语言描述错误，bugAgent 会自动按类型和严重程度分类，然后保存。
  • 提交功能请求 — 请你的助手提交功能请求，bugAgent 会自动将其归类为功能请求并评定严重程度。
  • 列出最近的报告 — 请你的助手列出你最近的错误报告，例如通过 list_bug_reports。
  • 搜索和筛选报告 — 查询特定项目中的未解决严重错误，或按严重程度汇总本周提交的所有报告。
  • 更新工单并添加评论 — 更改报告状态、将其分配给自己，或为现有工单添加评论。
  • 从客户端连接 — 将托管的 Streamable HTTP 端点添加到 Claude Desktop、Claude Code、Codex、Cursor、VS Code，或通过 curl-example 连接。

文档

将 bug Agent 连接到任何兼容 MCP 的 AI 客户端。

直接从 AI 编码助手中提交、分类和管理 Bug、功能请求等。无需切换上下文，也无需复制粘贴——只需描述问题，bug Agent 就会处理剩下的工作。

外部 MCP 客户端与 bug Agent 仪表板中的 AI Assistant 相互独立。仪表板助手在所有套餐中默认关闭，且需要明确启用工作区；其 ai_assistant 开关不会禁用 MCP 或集成。MCP 身份验证、作用域、工作区/项目权限以及特定工具的使用权限仍然适用。

开始使用

bug Agent 运行托管的 MCP 服务器，让 AI 客户端能够通过 Model Context Protocol 创建、查询和管理 Bug 报告、功能请求、增强请求等。客户端直接连接到托管的 Streamable HTTP 端点。

获取 API 密钥

创建免费账户；新工作区所有者会直接进入 API 密钥设置页面。回访用户可以从 Settings → Developers → API Keys 生成密钥。

配置 AI 客户端

在客户端的配置中将 bug Agent 添加为 MCP 服务器（请参阅下方的设置说明）。

开始提交 Bug

用自然语言描述 Bug，bug Agent 会自动分类、补充信息并保存。

# Create a bug report
"File a bug: Login button is unresponsive on iOS Safari.
Steps: tap login, nothing happens. Expected: navigate to
dashboard. Severity: high."

# bugAgent auto-classifies as UI bug, severity high

# File a feature request
"Feature request: Add dark mode toggle to the
settings page. Users have asked for this in surveys."

# Auto-classified as feature-request, severity medium

设置

专注于 Bug 捕获的插件

查看公开的插件源码和设置清单。这是源码预览；托管 OAuth 验证和 OpenAI 目录发布尚待完成。

专用端点 https://mcp.bugagent.com/mcp/capture 仅提供 capture_get_profile、capture_list_projects、capture_search_reports、capture_get_report 和 capture_create_report。它不提供管理、删除、评论或测试执行功能。OpenAI 目录是否收录取决于单独的审核和发布流程。

使用 OAuth 连接。捕获权限仅限此端点，不能用于完整的 /mcp 端点。读取需要 bugs:read；创建需要 bugs:write。仍支持工作区 API 密钥，需具备 reports:read 和 reports:write，且权限仅限其所属工作区。

请先选择已授权的工作区和项目。搜索和报告读取需要明确的 workspace_id 和 project_id；结果数量有限并采用分页。搜索结果只是可能匹配项，并不保证不存在重复项。

创建前，请检查目标位置、标题、描述、类型和严重程度。将 approved: true 和稳定的 UUID request_id 与已批准的内容一并发送。仅在重试完全相同的请求时复用同一请求 ID；如果内容发生变化，请求将被拒绝。现有套餐限制和已配置的 Jira 转发仍然适用。

图像解读可能有助于撰写草稿，但此端点不会上传附件。请打开已创建的工单，附加私密证据。切勿在对话中粘贴密码、令牌或其他机密信息。

推荐：托管的 Streamable HTTP

直接连接到 https://mcp.bugagent.com/mcp。无需安装任何内容，也无需在本地保持运行。将工作区 API 密钥作为 bearer token 添加：

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

💡

将 ba_live_YOUR_KEY_HERE 替换为你从 Settings → Developers 获取的实际 API 密钥。

可选的 stdio 桥接程序

仅当客户端要求使用 stdio 且无法连接远程 HTTP 服务器时，才使用已发布的桥接程序。按需使用 npx -y bugagent-mcp 运行：

{
  "mcpServers": {
    "bugagent": {
      "command": "npx",
      "args": ["-y", "bugagent-mcp"],
      "env": {
        "BUGAGENT_API_KEY": "ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

连接到服务器

在触屏设备的仪表板中，轻点侧边栏标签一次即可导航。选项和 Restore 是独立控件，也可以通过键盘访问。侧边栏的显示与否不会授予或撤销 MCP 权限。

bug Agent MCP 服务器已通过 Streamable HTTP 传输在 https://mcp.bugagent.com/mcp 上运行。可从以下八种客户端中的任意一种连接——选择最适合你工作流程的客户端。

如需简洁、可直接复制的配置、作用域密钥指南和安全的入门提示，请使用公开的 MCP 快速入门指南。

🔑

请先获取 API 密钥。 登录 Settings → Developers，点击 Create API Key，选择客户端所需的作用域，然后复制密钥（以 ba_live_ 开头）。密钥只会显示一次，请妥善保存。MCP 客户端只会列出这些作用域允许使用的工具。以下连接示例使用此密钥；需要交互式 OAuth/会话或付费套餐权限的提示会另行标明。

选项 1 — MCP Inspector（Web UI，推荐首次测试时使用）

Anthropic 官方工具。它会启动本地 Web UI，你可以在其中逐一点击工具、填写参数并查看响应。无需配置，也不需要 IDE。

macOS（Terminal）

npx @modelcontextprotocol/inspector

Windows（PowerShell 或 CMD）

npx @modelcontextprotocol/inspector

在打开的浏览器界面中：

  1. Transport Type：选择 Streamable HTTP
  2. URL：https://mcp.bugagent.com/mcp
  3. Connection Type：选择 Proxy（默认选项——Inspector 会通过本地 Node 进程代理连接，以绕过浏览器 CORS 限制）
  4. 打开 Server Settings → Custom Headers 并添加：
    • Header Name：X-Api-Key
      • Value：ba_live_YOUR_KEY_HERE（不要加 Bearer 前缀）
  5. 点击 Connect。左侧面板会列出 API 密钥所选作用域允许使用的 bug Agent 工具。
  6. 点击任意工具（例如 list_bug_reports），填写参数，然后点击 Run Tool。响应会显示在右侧。

先决条件：MCP Inspector v2 需要 Node.js 22.19 或更高版本。如果尚未安装，请从 nodejs.org 安装当前版本的 Node.js。

如果 Inspector 返回 invalid_client，说明它正在尝试使用已保存的 OAuth 连接，而不是 API 密钥身份验证。移除已保存的服务器（或清除其存储的 OAuth 状态），重新添加，然后使用上面的 X-Api-Key 自定义标头。不要将 ba_live_ 密钥填入 OAuth client_id 字段。

选项 2 — Claude Desktop（Mac + Windows）

如果你使用 Claude Desktop 应用，可以将 bug Agent 添加为永久 MCP 服务器。使用工作区 API 密钥时，Claude 只能使用该密钥作用域允许的工具。委托式 OAuth 则会开放完整的交互式工具目录。

macOS

  1. 打开 Claude Desktop → 菜单栏 Claude → Settings → Developer → Edit Config。这会打开 ~/Library/Application Support/Claude/claude_desktop_config.json。
  2. 在 mcpServers 下添加 bug Agent 条目： 
    {
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}
  3. 保存文件并完全退出 Claude Desktop（按 Cmd+Q，而不只是关闭窗口）。
  4. 重新启动 Claude Desktop。聊天输入框底部的工具锤子图标现在应显示 bug Agent 工具。
  5. 试试看：输入 “列出我最近的 5 个 Bug 报告”——Claude 会自动调用 list_bug_reports。

Windows

  1. 打开 Claude Desktop → File → Settings → Developer → Edit Config。这会打开 %APPDATA%\Claude\claude_desktop_config.json（通常是 C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json）。
  2. 添加 macOS 部分中显示的相同 JSON 代码块。
  3. 保存文件，并从系统托盘中完全退出 Claude Desktop（右键点击 Claude 图标 → Quit），然后重新启动。
  4. 工具锤子图标会显示 bug Agent 工具。

选项 3 — Claude Code（CLI）

如果你在终端中使用 Claude Code（Claude 的 CLI 版本），可以用一条命令注册 bug Agent 服务器。在 macOS、Linux 和 Windows 上的操作完全相同。

claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp \
  --header "Authorization: Bearer ba_live_YOUR_KEY_HERE"

然后重新启动 Claude Code 会话。验证连接状态：

claude mcp list

列表中应显示带绿色圆点的 bugagent。请从兼容 API 密钥的提示开始：“列出我最近的 5 个未关闭 Bug 报告。”

已连接，但缺少某些工具？

请检查 /mcp 中的服务器工具数量，而不只是当前对话中已加载的工具。Claude Code 可以通过工具搜索按需发现工具。让它搜索 bugAgent 中的 list_test_cases、list_test_suites 或 get_test_run_plan。请参阅 Claude Code 的工具搜索文档。

工具目录会根据 API 密钥作用域进行筛选。读取测试用例需要 test_cases:read；读取测试套件/运行记录需要 test_runs:read。只申请实际需要的写入作用域。使用与客户端相同的端点和密钥比较经过身份验证的 tools/list；匿名发现或使用不同密钥进行比较都无效。检查是否有项目级配置覆盖了用户级连接，然后在凭据变更后重新连接或重启。

如果经过身份验证的服务器目录中包含某个工具，但客户端仍无法发现它，请记录客户端版本、服务器版本、工具名称/数量以及任何架构错误，并移除凭据和客户数据。如果会话使用 ENABLE_TOOL_SEARCH=false claude 启动，可以区分延迟发现和加载问题，但这会加载所有工具定义并占用更多上下文；仅将其用作临时诊断手段。不要仅为增加工具数量而扩大权限或拆分端点。

之后如需移除：

claude mcp remove bugagent

选项 4 — OpenAI Codex CLI

如果你使用 OpenAI Codex CLI，请导出 API 密钥并将 bug Agent 添加到 ~/.codex/config.toml。

永久注册（添加到配置中）

[mcp_servers.bugagent]
url = "https://mcp.bugagent.com/mcp"
bearer_token_env_var = "BUGAGENT_API_KEY"

设置 API 密钥

export BUGAGENT_API_KEY="ba_live_YOUR_KEY_HERE"

在该环境中启动或重启 Codex。Codex 会根据你的自然语言提示自动解析工具调用。试试：“列出我的未关闭 Bug，并按严重程度排序。”

选项 5 — Cursor（Mac + Windows）

Cursor 内置了 MCP 支持。使用作用域设置适当的工作区 API 密钥后，Cursor 中的 AI 助手可以提交 Bug、列出报告并运行受支持的自动化工作流，无需离开编辑器。安全、性能和探索性扫描需要委托式 OAuth 以及相应的套餐权限。

  1. 打开 Cursor → Settings（Mac 上按 Cmd+, / Windows 上按 Ctrl+,）→ 左侧边栏中的 MCP。
  2. 点击 + Add new MCP server。
  3. 选择 HTTP 传输类型。
  4. 填写：
    • Name：bugagent
      • URL：https://mcp.bugagent.com/mcp
      • Header name：Authorization
      • Header value：Bearer ba_live_YOUR_KEY_HERE
  5. 点击 Save。连接成功后，Cursor 会显示绿色指示灯。
  6. 打开 Cursor 聊天窗口（Cmd+L / Ctrl+L），输入 “创建一个标题为‘登录故障’、严重程度为高的 Bug 报告。” Cursor 会调用 create_bug_report。

替代方式：Cursor 也会读取 ~/.cursor/mcp.json（Mac）或 %USERPROFILE%\.cursor\mcp.json（Windows）。添加与 Claude Desktop 部分所示相同格式的 JSON。

选项 6 — 使用 Continue 扩展的 VS Code（Mac + Windows）

如果你更喜欢 VS Code，Continue 扩展 原生支持 MCP 服务器。

  1. 从 VS Code Marketplace 安装 Continue 扩展。
  2. 打开 Continue 配置：命令面板（Cmd+Shift+P / Ctrl+Shift+P）→ Continue: Open config.json。文件位于：
    • macOS：~/.continue/config.json
      • Windows：%USERPROFILE%\.continue\config.json
  3. 添加一个 mcpServers 条目： 
    {
  "mcpServers": [
    {
      "name": "bugagent",
      "type": "streamable-http",
      "url": "https://mcp.bugagent.com/mcp",
      "requestOptions": {
        "headers": {
          "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
        }
      }
    }
  ]
}
  4. 保存。Continue 会自动重新加载，并在侧边栏中显示 bug Agent 工具。
  5. 打开 Continue 聊天面板并试试：“列出我最近的 5 个未关闭 Bug 报告。”

其他支持 MCP 的 VS Code 扩展：Cline、Roo Code 和 Windsurf（分支版本）都采用类似的 JSON 配置模式，使用 mcpServers 键和 HTTP 传输。

选项 7 — 支持 OAuth 的宿主（以 Claude.ai 网页版为例）

某些 MCP 宿主通过 OAuth 2.0 进行身份验证，并要求预先提供静态的 client_id 和 client_secret，而不是接受 bearer API 密钥。请从 bug Agent 仪表板生成一对连接器凭据，并将其粘贴到宿主的连接器表单中。这对凭据用于标识 MCP 客户端；获得授权后，工具执行会使用已登录用户及其当前启用的 bug Agent 工作区。以下操作指南以最常见的示例 Claude.ai 网页应用为例。

i

资源绑定的 OAuth。 受保护资源标识符为 https://mcp.bugagent.com/mcp。支持标准的宿主会从 /.well-known/oauth-protected-resource/mcp 中发现该标识符，并将其作为 RFC 8707 resource 参数发送。bug Agent 会签发不透明令牌，并将其绑定到该资源、OAuth 客户端、已登录用户和已授予的作用域；令牌不能在其他服务上重放，也不能由其他客户端兑换。

  1. 在 bug Agent 中：打开 Settings → Developers → MCP Connectors。点击 Generate connector，为其命名以描述主机（例如 “Claude.ai (work)”），粘贴 MCP 主机要求的重定向 URI（对于 Claude.ai 网页应用，该 URI 为 https://claude.ai/api/mcp/auth_callback；其他主机请查看其连接器文档），并将身份验证方法选为 Confidential。复制成功页面上仅显示一次的 client_id 和 client_secret。
  2. 在 MCP 主机的连接器 / OAuth 设置中，粘贴：
    • Server URL：https://mcp.bugagent.com/mcp
      • Client ID + Client Secret：来自第 1 步
      • Authorization URL：https://mcp.bugagent.com/authorize
      • Token URL：https://mcp.bugagent.com/token
      • 如有要求，填写 Protected resource / audience：https://mcp.bugagent.com/mcp 对于 Claude.ai：前往 claude.ai/customize/connectors 并点击 Add MCP connector。
  3. 保存。主机会将你重定向到 bug Agent，让你登录（使用 Google 或电子邮件/密码，取决于你登录控制面板时使用的方法）并批准授权，然后完成 OAuth 握手。
  4. 在同一 Settings 页面管理生成的连接器。只有创建者可以撤销租户连接器；工作区管理员无法撤销其他成员注册的连接器。确认撤销后，该注册会从活动列表中移除。名称相同的独立注册仍然彼此不同：请比较它们的 Client ID。如果无法确认撤销，页面会显示错误，而非成功消息。撤销会阻止新的连接器身份验证。先前签发的访问令牌可能会在过期前继续有效。

注意： Claude Code、Cursor、VS Code 和 MCP Inspector 不需要此流程——它们会自动处理动态客户端注册（RFC 7591），并按上述方式通过 API 密钥进行身份验证。MCP Connectors 表单仅适用于要求静态 OAuth 凭据的主机。

OAuth 访问令牌和刷新令牌仅向主机显示。它们是不透明的，刷新时会轮换；bug Agent 仅以单向哈希形式存储这些令牌；上游身份刷新凭据则以静态加密方式存储。切勿将 OAuth 令牌复制到 REST API 请求或其他 MCP 服务器中。

选项 8 — 使用 curl 直接通过 HTTP 连接（终端）

如果你想在不使用任何客户端的情况下直接测试服务器，或将其集成到脚本中，可以使用 curl 访问 HTTP 端点。MCP 协议通过 Streamable HTTP 使用 JSON-RPC 2.0。

macOS / Linux

# Set your API key as a variable
export BUGAGENT_API_KEY="ba_live_YOUR_KEY_HERE"

# 1. Initialize the MCP connection
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl-example","version":"1.0.0"}}}'

# 2. List tools visible to this key
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Call a tool — list 5 reports from a specific project
curl -N -s https://mcp.bugagent.com/mcp \
  -H "Authorization: Bearer $BUGAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"list_bug_reports",
      "arguments":{"project":"bugagent","limit":5}
    }
  }'

Windows (PowerShell)

# Set your API key
$env:BUGAGENT_API_KEY = "ba_live_YOUR_KEY_HERE"

# Use Invoke-RestMethod (PowerShell's curl equivalent)
$headers = @{
  "Authorization" = "Bearer $env:BUGAGENT_API_KEY"
  "Content-Type" = "application/json"
  "Accept" = "application/json, text/event-stream"
}

# 1. Initialize
$body = '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"powershell-example","version":"1.0.0"}}}'
Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" \`
  -Method Post -Headers $headers -Body $body

# 2. List tools visible to this key
$body = '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" \`
  -Method Post -Headers $headers -Body $body

# 3. Call list_bug_reports for a specific project
$body = @{
  jsonrpc = "2.0"
  id = 3
  method = "tools/call"
  params = @{
    name = "list_bug_reports"
    arguments = @{ project = "bugagent"; limit = 5 }
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "https://mcp.bugagent.com/mcp" \`
  -Method Post -Headers $headers -Body $body

响应可能是 JSON 或 Server-Sent Events。每个 SSE 块都是以 data: 为前缀、后跟 JSON 对象的一行。符合标准的客户端应发送 Accept: application/json, text/event-stream；bug Agent 目前会为兼容性规范化缺失或不完整的 Accept 值。

ℹ️

故障排除：401 Unauthorized： 检查你的 API 密钥是否已在 Settings → Developers 中撤销。密钥以 ba_live_ 开头。如果仍无法解决，请重新生成密钥并重试。

访问模型与最小权限范围

完整的 OAuth 工具目录包含 141 个工具。工作区 API 密钥只能看到映射到其所选范围的工具。未经身份验证的发现可能会显示工具元数据，但 tools/call 始终需要 API 密钥或 OAuth 令牌。

读取错误报告并解决项目 reports:read

创建和更新错误报告 reports:read, reports:write

使用情况监控 usage:read

检查 Jira 同步状态 jira:read

同步或合并 Jira 报告 jira:write

编写 Web 自动化 automations:write

运行 Web 自动化并读取运行记录 automations:run

查看移动资产和运行记录 mobile:read

管理移动资产 mobile:read, mobile:write

运行移动自动化 mobile:read, mobile:run

管理测试目录 reports:read, test_cases:read, test_cases:write

外部测试执行工作器 test_runs:read, test_runs:write

API 密钥绑定到创建它们的工作区。工具输入可以将调用范围缩小到已授权的项目，但不能将密钥切换到其他工作区。使用 list_projects 解析项目 UUID，并拒绝含糊不清的名称。

工具标题和注释

tools/list 返回的每个工具都包含易于理解的标题以及读/写提示。缺失的读取提示来自经过明确审核的列表，而非工具名称前缀或 API 密钥范围。包括 false 在内的显式注释会予以保留。

  • readOnlyHint: true 表示工具不会修改其环境。
  • readOnlyHint: false 与 destructiveHint: false 表示追加式写入，而非只读操作。
  • readOnlyHint: false 与 destructiveHint: true 表示可能具有破坏性的写入。未分类的工具使用这些保守默认值。破坏性提示仅对写入操作有意义。

login 并非只读：在 stdio 模式下，它会保存凭据。analyze_fix_area 和 check_config_drift 可能具有破坏性，因为它们会替换已保存的分析结果或配置基线。

注释不会授予访问权限，也不能替代身份验证、工作区/项目授权、API 密钥范围或权益检查。是否显示确认提示取决于客户端的权限策略和用户设置；这些提示不能保证调用时一定会显示确认提示。

如需以编程方式发现和审计工具，请下载生成的 mcp-tool-index.json。其中记录了全部 141 个运行时工具、API 密钥范围或仅限 OAuth 的访问权限、权益类别、输入名称、输出架构模式以及显式声明的 MCP 注释。null 注释表示调用位置未声明该注释；应用默认值后，请使用已连接服务器的 tools/list 响应获取生效的注释。

!

仅限 OAuth 的工具： 账户、API 密钥和团队管理、Jira 连接管理、其他集成、高级测试控制、备注、时间跟踪及其他交互式操作，不会因添加 API 密钥范围而解锁。Jira 报告检查、同步和合并工具是一个有限例外，可通过 jira:read 和 jira:write 使用。

试试看 — 自然语言提示

连接后，你无需了解工具名称或参数。只需用自然语言描述需求，AI 助手就会自动调用正确的 bug Agent 工具。

错误报告、限定范围的测试管理、Playwright 自动化、移动自动化和使用情况提示，适用于具有相应范围的 API 密钥。安全、性能、探索性测试、账户、团队、备注、时间跟踪以及其他未指定 API 密钥范围的条目，需要委派 OAuth 和任何适用的套餐权益。

错误报告

List my 5 most recent bug reports
Show all open critical bugs in the Auth project
Create a bug titled "Login broken on Safari" with severity s2
Update TEST-451 status to in-progress and assign it to me
Add a comment to TEST-451: "root cause confirmed — null check missing in auth middleware"
Show me everything filed this week, grouped by severity

测试管理

Create a test suite called "Smoke Tests" with cases for login, checkout, and account settings
Run the Regression suite and list all failures
Use Hermes to execute the curated "Checkout smoke" suite and report every result to bugAgent
Show failing test cases from the last 7 days
Which test cases have never been run in the past 90 days?
Get a pass-rate trend for this month vs last month

安全与性能

Run a security scan on https://app.example.com
Get this month's security scan results — show only high and critical findings
Create a performance test for the landing page and check Lighthouse scores
What are the Core Web Vitals for our checkout flow?

Playwright 自动化

Create a Playwright script that logs in and verifies the dashboard loads
Run the checkout automation on iPhone 15 Pro on a real device
Optimize the login automation script
Show runs for the checkout automation — any failures?
Schedule the smoke test suite to run every weekday at 6 AM UTC

探索式 AI

Run an exploratory AI session on https://app.example.com with 5 parallel agents
Get the latest exploration run results — list any bugs that were filed
What testing strategies did the agents use and which found the most issues?

使用情况与统计数据

Check my plan usage for this month
Show team bug stats for this week broken down by severity and type
List all team members and their roles
How many security scans do I have left this month?

快速参考

八种连接选项的设置参考。API 密钥客户端通过 Streamable HTTP 使用标头 Authorization: Bearer ba_live_YOUR_KEY_HERE 连接到 https://mcp.bugagent.com/mcp；支持 OAuth 的主机则使用在控制面板中生成的连接器凭据。

Claude Desktop — macOS ~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop — Windows %APPDATA%\Claude\claude_desktop_config.json

Claude Code (CLI) claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp --header "Authorization: Bearer ba_live_..."

Codex CLI ~/.codex/config.toml

Cursor — macOS Settings → MCP UI，或 ~/.cursor/mcp.json

Cursor — Windows %USERPROFILE%\.cursor\mcp.json

VS Code + Continue ~/.continue/config.json (macOS) / %USERPROFILE%\.continue\config.json (Windows)

支持 OAuth 的主机 Settings → Developers → MCP Connectors — 生成主机的 client_id 和 client_secret

直接通过 HTTP 连接 (curl) curl / Invoke-RestMethod — 包含 Accept: application/json, text/event-stream

故障排除

401 Unauthorized 密钥错误、已过期或已撤销。请检查 Settings → Developers — 密钥以 ba_live_ 开头。必要时重新生成。

客户端中未显示工具 API 密钥客户端只会列出密钥所选范围允许的工具。请在 Settings → Developers 中检查密钥，然后在更改配置后完全退出并重新启动客户端。在 Claude Desktop 中，按 Cmd+Q（而不只是关闭窗口）。在 Cursor 中，检查 Settings → MCP 中是否显示绿色圆点。

客户端中缺少字段 将客户端的架构与同一端点的原始 tools/list 进行比较。如果两者不同，请刷新或重新连接工具目录，然后开始新的聊天。如果问题仍然存在，请收集端点、客户端版本和原始 tools/list 响应；缓存过期只是可能的原因之一。

Accept header required 对符合标准的 Streamable HTTP，请发送 Accept: application/json, text/event-stream。bug Agent 目前会规范化缺失或不完整的值，但集成不应依赖这种兼容行为。

工作区数据错误 每个 API 密钥都限定在一个工作区内。请在你想查询的工作区中，通过 Settings → Developers 生成新密钥。

工具已显示，但调用静默失败 检查响应中的 isError: true 和返回内容。工具可见并不代表调用一定获准；套餐、角色、功能权益、项目成员身份、所有权或无效输入都可能导致拒绝。读取工具错误后，再检查服务器运行状况。

MCP Inspector CORS 错误 在 Inspector UI 的 Connection Type 中选择 Proxy（而非 Direct）。Inspector 会通过本地 Node 进程进行代理，以绕过浏览器的 CORS 限制。

MCP Inspector v2 以代码 5 退出 当工具响应包含 isError: true 时，Inspector v2 会返回非零退出代码。请阅读响应消息，查看套餐、权限、输入或运行时错误；对于相同的失败工具响应，Inspector v1 可能会返回退出代码 0。

Codex CLI — 无法识别工具 确认 ~/.codex/config.toml 使用 [mcp_servers.bugagent]，设置 bearer_token_env_var = "BUGAGENT_API_KEY"，并在启动 Codex 前导出该变量。如果工具仍未显示，请检查 codex --version。

MCP 功能

对话式会话仍处于受工作区限制的试点阶段。保存由会话生成的脚本，需要其所有者通过 仅限会话的保存脚本端点 在 Workbench 中明确批准。没有 MCP 审批工具：要求代理起草脚本不会创建或安排自动化任务。

保留云浏览器截图只会通过所有者会话保留端点创建发现草稿。实时刷新不会替换所选截图；保存仍需要当前所有者访问权限、原始授权的浏览器代次以及可用来源。所有者必须先在 Workbench 中审核并批准，之后才能提交错误报告及其私有证据。没有用于保留帧或绕过该审批的 MCP 工具。

浏览器启动授权也仅限控制面板所有者。API 密钥、MCP 工具和通用聊天回答都无法授予此授权。批准仅涵盖一个只读浏览器和私有截图捕获，不包括登录、表单操作或会议录制。生产环境的云浏览器主机不会因这些授权控制而激活。

完整的交互式/OAuth 工具目录包含 141 个工具。工作区 API 密钥只能发现其所选范围允许的最小权限子集；账户、API 密钥管理、团队管理、高级测试、备注和时间跟踪工具仅限交互式会话使用，除非某个条目明确指定了 API 密钥范围。

🐛

错误报告管理

报告更新会以原子方式记录实际的更改前/更改后值，包括复现字段、内部备注和标签。未更改的值和失败的写入不会创建字段历史记录。控制面板的 Change Log 会展开纯文本差异，并分页显示较早的条目。附件历史记录保留描述性元数据，不保留签名 URL 或已删除文件。不会回填缺失的历史值。不会新增 MCP 历史工具或实时编辑冲突协议；已获授权的客户端可以使用报告历史 REST 端点。 update_bug_report 还接受字符串字段 steps_to_reproduce、expected_result 和 actual_result。省略的字段会保留；空字符串会清除文本。更新仍遵循现有的工作区/项目授权和 reports:write 范围要求。

可恢复的 Google Sheets 截图导入使用单独的 REST POST /api/reports/import-attachment 端点，并使用 reports:write；使用 reports:read 获取状态。不会添加截图导入 MCP 工具。此仅支持 JPEG/PNG 的 API 会验证私有存储和准确映射的 Jira 问题，然后才报告完成；旧版报告上传仍仅限会话使用。

打开私有报告和测试运行附件链接时，会重新检查有效的工作区成员身份和当前项目权限。下载测试运行内容需要仪表板会话，而非 MCP API 密钥。已签发的存储链接可能在最多 60 秒内仍然有效，请勿分享。

  • create_bug_report — 创建新报告，并在 19 种类型中自动分类——包括错误、功能请求、增强、技术债务等（标题：3-500 个字符）。可选的 attachments 数组接受 base64 编码的文件，每个文件最大 400 MB：任何图像、视频、音频、PDF 或文本/JSON 文件。将 format_description: true 设为自动使用 AI 将描述重新整理为结构化模板。传入 time_spent_seconds 以跟踪 QA 工作量。传入 priority（urgent / high / normal / low）以独立于严重程度设置修复紧急程度。传入 is_epic: true 以创建 Epic，或传入 parent_epic_id（UUID/短 ID）以在同一授权项目中创建子项。响应包含层级字段以及 project_id、project、short_id、legacy_short_id 和 project_short_id。
  • list_bug_reports — 列出并筛选报告（每页最多 100 条）。项目筛选会在分页前于服务器端应用。可按 project（UUID、slug、精确名称或工单前缀）、project_id、project_slug、project_prefix、workspace（UUID、精确名称或工作区工单前缀）、workspace_id / team_id、is_epic、type、severity、status、resolution、root_cause 或 reporter_user_id 筛选。search 筛选器会搜索报告文本；仅包含数字的输入（例如 366）会同时精确查找旧版和项目工单编号，因此会排除包含这些数字但无关的文本。每条结果都包含租户范围内的人员/项目标识符，以及 is_epic、parent_epic_id、parent_epic 和有长度限制的 epic_progress。报告读取工具不会公开成员电子邮件地址。
  • pick_next_bug — 按优先级顺序返回代理循环应处理的下一个错误（S1 → S2 → S3，每个级别内按时间从早到晚）。自动限定在你的工作区范围内——返回团队所有项目中状态为 status new、awaiting-triage 或 confirmed 且严重程度为 S1-S3 的工单。只读——不会以原子方式认领工单。可选参数：severity（单个级别）、limit（1-50，默认值为 1）。返回包含 count 和 bugs 的对象；每个错误都是精简的队列行，而非完整的 list_bug_reports 结构。与 claim_bug 配合使用，实现先读取再认领的模式。
  • claim_bug — 以原子方式将错误从 status new、awaiting-triage 或 confirmed 转换为 status='in-progress'，将 assigned_to 设为调用用户，并记录 claimed_at=NOW()。通过 Postgres 的 UPDATE-WHERE-RETURNING 模式避免并发竞争——如果两个代理在短时间内对同一 ID 调用 claim_bug，恰好一个会收到包含错误正文的 claimed:true，另一个会收到带原因字符串的 claimed:false。成功响应包含 reporter_user_id、reporter_name、assigned_to 和 assignee_name。pg_cron 清理器会自动将过期认领（状态为 in-progress + claimed_at > 30 分钟）释放回 new，因此崩溃代理的工单会自动重新进入队列，无需人工干预。输入：id（UUID 或短 ID）。
  • get_bug_report — 按 UUID 或工作区/项目短 ID 获取报告的完整详情。返回标准人员/项目/质量字段，以及 is_epic、父项标识、汇总进度和 Epic 的有界首个子项页面。
  • 原生报告标签： create_bug_report 和 update_bug_report 接受作为字符串数组的 tags，例如 {"tags":["login","regression"]}。去重前最多接受 20 个原始元素。字符串会去除首尾空白，必须非空且不超过 50 个 Unicode 码点，并且不能包含 ASCII 控制字符（U+0000 至 U+001F 或 U+007F）。去除首尾空白后会删除完全重复的项；保留大小写，且 Login 与 login 不同。更新时，数组会替换所有标签，[] 会清除标签，省略则保留标签。创建时，省略表示不添加标签。null 和无效元素会被拒绝。创建、获取、列表和更新结果都会公开原生 tags。
  • 标签筛选： 调用 list_bug_reports 并传入 {"project":"bugagent","tags":["login","regression"]}，即可在分页前按区分大小写的方式匹配所有请求的标签。适用相同的标签限制；省略或传入 [] 时不应用标签筛选。现有的 reports:read / reports:write 范围和工作区/项目授权保持不变。此功能不会添加可视化标签 UI，也不会自动导入、同步或回填 Jira 标签。
  • get_epic — 使用必填的 id（UUID 或工作区/项目短 ID）直接读取一个 Epic。仅返回 Epic 记录，不会隐式加载子报告。需要有权访问其工作区和项目；API 密钥调用方需要 reports:read。使用 list_epic_children 单独读取子项。
  • list_epic_children — 使用 id、limit（1–100）和 offset 对 Epic 的子报告进行分页。返回 children、total、has_more 和通过 SQL 聚合的 epic_progress，无需加载所有子报告。
  • update_bug_report — 更新标准报告字段以及 is_epic 和 parent_epic_id。传入 parent_epic_id: null 可解除关联；重新指定父项/解除关联以原子方式执行，并要求同一工作区、同一项目的授权。提升为 Epic 时会解除现有父项关联；有子项的 Epic 不能降级。现有的状态/解决方案/根本原因和分配通知规则仍然适用。对于关联 Jira 的报告，如果 status 发生变化，且恰好有一个合法工作流转换与映射状态匹配，则会通过 Jira 工作流转换同步到 Jira 问题；否则不会更改该问题。
  • add_comment — 向错误报告添加评论（UUID 或短 ID，正文为 1-10000 个字符）。如果报告已同步到 Jira，评论会自动推送到关联的 Jira 问题。类似 ![proof](/api/attachments/ATTACHMENT_UUID) 的私有附件 Markdown 会在 Jira 中转换为绝对地址的、经过身份验证的 bugAgent 智能链接。查看者必须登录 bugAgent，并有权访问该报告的工作区和项目；不保证 Jira 原生内联预览可用。
  • list_comments — 按时间从早到晚列出报告已存储的评论串——每条评论包含作者姓名、parentId（串接回复）、createdAt 和 updatedAt。评论不属于 get_bug_report，因此需要通过此工具读取工单讨论。接受 UUID 或短 ID。此读取操作不会刷新 Jira。需要获取最新 Jira 评论的定时集成可以先使用经过授权的、由管理员持有的 API 密钥调用 POST /api/jira/comments-refresh。使用评论 ID 和内容修订版本区分新评论与编辑；如果刷新失败，不要声称提供了完整的活动报告。
  • link_bug_reports — 在同一授权项目中的两份报告之间创建有方向的语义链接。对于 parent-of，来源报告必须是 Epic，目标报告必须是标准子项。创建/更新时优先使用 parent_epic_id 指定 Epic。
  • unlink_bug_reports — 按 UUID 删除先前创建的错误报告链接（link_id，由 link_bug_reports 或 list_bug_report_links 返回）。
  • list_bug_report_links — 列出与某个错误报告相关的所有用户整理的链接。每条链接都会按所提供报告的视角呈现——例如，如果此报告是目标，则存储的 duplicate-of 行会显示为 duplicated-by；parent-of 会显示为 subtask-of；depends-on 会显示为 blocks；testing-blocked-by 会显示为 blocks-testing。related-to 是对称的。此工具补充了 get_bug_report 返回的自动检测 similar_reports 字段。
  • classify_bug — 将描述分类为 19 种报告类型之一（错误、功能、增强等），并提供置信度分数
  • flush_reports — 批量删除旧报告（仅限管理员）

📊

使用情况与分析

  • get_usage — 检查使用情况是否超出计划限制。API 密钥调用方需要 usage:read。
  • get_stats — 每日计数、类型/严重程度/状态细分

📁

项目管理

  • list_projects — 列出可访问的项目及其 id、name、slug、ticket_prefix、描述和默认状态。使用这些值通过错误报告和测试目录工具指定正确的项目。
  • create_project — 创建新项目（如果是第一个项目，则自动设为默认项目）
  • delete_project — 永久删除项目及其所有关联数据（错误报告、自动化、测试用例、移动应用、计划、地理快照、备注、时间条目）。仅限所有者/管理员。不能删除最后一个项目。存储空间会自动释放
  • export_okf_bundle — 将项目的 QA 知识导出为 OKF/OQA Markdown 包——包括错误报告、测试用例、自动化以及性能、安全和探索性测试（Open Query Agent 格式，由 oqa.ai 使用）。默认导出当前项目；传入可选的 project（slug 或名称）可导出其他项目。返回包中的文件列表，以及以 base64 编码的 zip 格式提供的整个包

🔐

身份验证与账户

  • register_account — 创建新账户（密码：8-128 个字符，速率限制：5 次/15 分钟）
  • login — 登录并获取访问令牌（速率限制：5 次/15 分钟）
  • update_profile — 更新显示名称
  • change_password — 更改账户密码
  • get_settings — 读取个人资料和通知偏好设置。
  • update_settings — 更新受支持的个人资料和通知偏好设置。仅限 OAuth 修改。

🔑

API 密钥管理

  • generate_api_key — 创建命名 API 密钥
  • list_api_keys — 列出有效密钥（仅显示前缀）
  • regenerate_api_key — 撤销并替换密钥
  • delete_api_key — 永久撤销密钥

👥

团队管理

  • list_workspaces — 列出你所属的工作区、你在每个工作区中的角色，以及会话默认使用的工作区。支持多工作区的主机可以使用 X-BugAgent-Workspace 标头固定请求（仅限有效成员）
  • list_team_members — 列出工作区的所有成员及其角色、状态和 booster 标记
  • invite_team_member — 通过电子邮件邀请用户（管理员可以邀请贡献者和管理员；只有所有者可以邀请管理员）。邀请链接 5 天后过期

🎯

集成

Jira Cloud 报告同步包含在 Free 和 Enterprise 计划中。工作区管理员必须先在仪表板中连接 Jira。之后，工作区 API 密钥可以使用 jira:read 进行比较，并使用 jira:write 进行同步/合并；Atlassian 计划和 API 限制仍然适用。

  • sync_to_jira — 使用团队共享连接将报告推送到 Jira。路由到映射到报告的 bugAgent 项目的 Jira 项目（工作区默认项目作为回退），并使用其字段映射：v2 将优先级与自定义严重性分开处理，而未版本化映射保留旧版的严重性到优先级转换。可选的 projectKey 只能选择该已配置映射或工作区默认项目；任意 Jira 项目都会被拒绝。**通常不需要使用此工具：**当项目的同步模式为 auto_new 或 auto_all 时，你创建的报告会自动推送——在 manual 模式下手动推送时才调用此工具。
  • check_jira_sync — 只读比较已授权关联报告的标题以及映射后的状态、优先级和严重性。使用报告保存的项目和 Jira 连接。版本 2 会将 Jira Priority 与受支持的自定义 Severity 字段分别映射；未版本化映射保留旧版的优先级到严重性行为。此工具不会比较评论、附件、类型或所有 Jira 字段。
  • merge_jira_sync — 使用 prefer: jira 拉取 Jira 值，或使用 prefer: bugagent 推送本地值，以合并这些映射字段。推送状态时会使用合法的 Jira 工作流转换。未映射的出站冲突、远程写入失败和并发本地更改都会返回错误，而不会声称所有内容均已同步。评论和附件仍由单独的仪表板同步工作流处理。跨系统写入不是原子操作。
  • push_to_claude — 为错误报告生成（或重新生成）开发者备注——包括根本原因、建议修复方案、验证步骤和风险评估。接受 UUID 或短 ID（WRKID-545）。使用平台密钥——无需单独配置团队 Claude 连接。运行自适应链：对于 s3 / medium 或 s4 / low 错误，执行三个步骤（Sonnet 起草 → OpenAI gpt-5 评审 → Sonnet 综合）；对于严重性最高的两个级别——s1 / critical 或 s2 / high——执行五个步骤（起草 → 评审 → Sonnet 反驳 → Claude Opus 裁决者读取完整对话记录，并以独立判断撰写最终备注）。响应会公开每一轮：analysis、draft、critique、rebuttal、challenger_model、adjudicator_model，以及一个 debated 标志。任何步骤失败时都会转而采用次优答案。创建错误时会自动触发；通常仅在手动重新生成时调用。
  • analyze_fix_area — 生成（或重新生成）开发者备注中的“可能的修复区域”子块——由 Sonnet 输出简短内容，指出修复最可能涉及代码库中的哪个位置。接受 UUID 或短 ID。使用平台 Anthropic 密钥。当团队有一个 github_connections 行且项目映射了 github_repo 时，输出会以已连接代码库中的真实文件片段为依据；否则会回退到通用指导，并提示连接代码库。返回 likely_fix_area 文本、generated_at、repo_used 和一个 grounded 标志。创建错误时会自动触发——代理通常仅在手动重新生成时才需要调用此工具。
  • upgrade_plan — 获取销售协助的 Enterprise 注册链接

⚡

性能测试

  • create_performance_test — 创建性能测试配置，包括 URL、设备、虚拟用户数、持续时间、分数阈值和自动创建错误的开关。可选的 project 接受当前工作区中的项目 UUID、slug、精确名称或工单前缀。若省略，则使用工作区默认项目，其次使用最早创建的项目；调用者必须有权访问该项目。使用 list_projects 选择项目。空白、未知或无权访问的项目会被拒绝。name 不能为空白，且会进行去除首尾空格处理。性能测试名称在工作区和项目范围内必须唯一，比较时忽略大小写和首尾空格；若发生冲突，请选择其他名称。仅限 Enterprise
  • run_performance_test — 为 Web 性能测试触发页面审计和负载测试。返回用于轮询结果的运行 ID。移动应用性能分析运行需从仪表板触发
  • get_performance_results — 获取完整结果，包括 Lighthouse 分数（Performance、Accessibility、Best Practices、SEO）、Core Web Vitals（LCP、FID、CLS、FCP、TTFB、INP、TBT、SI）和负载测试指标（VUs、请求数、RPS、p50/p90/p95/p99 延迟）
  • list_performance_tests — 列出当前团队的所有性能测试配置
  • get_performance_usage — 检查每月性能测试用量。性能测试仅限 Enterprise。Free=0，Enterprise=无限

示例工作流

  1. get_performance_usage → 检查剩余配额
  2. create_performance_test → 为你的 URL 配置测试
  3. run_performance_test → 触发审计和负载测试
  4. get_performance_results → 查看分数和核心指标

🛡

安全扫描

  • create_security_scan — 创建安全扫描配置。Web 扫描使用 Quick Scanner + Nuclei（4,000+ 个模板），提供三个深度级别和可选的身份验证扫描。移动端扫描使用 MobSF 分析 APK/IPA 二进制文件。可配置自动创建错误及其严重性阈值。可选的 project 接受当前工作区中的项目 UUID、slug、精确名称或工单前缀。若省略，则使用工作区默认项目，其次使用最早创建的项目；调用者必须有权访问该项目。使用 list_projects 选择项目。空白、未知或无权访问的项目会被拒绝。name 不能为空白，且会进行去除首尾空格处理。安全扫描名称在工作区和项目范围内必须唯一，比较时忽略大小写和首尾空格，且与性能测试名称分别独立；若发生冲突，请选择其他名称。仅限 Enterprise
  • run_security_scan — 触发漏洞扫描。Web 扫描需要验证 DNS 域名。移动端扫描需要上传应用。返回用于轮询结果的运行 ID
  • get_security_results — 获取完整结果，包括安全分数（0-100）、按严重性分类的发现（Critical、High、Medium、Low、Info），以及 CWE 引用、OWASP 映射、证据和修复指导
  • list_security_scans — 列出当前团队的所有安全扫描配置，并显示上次分数以及身份验证/深度徽标
  • get_security_usage — 检查每月安全扫描用量。安全扫描仅限 Enterprise。Enterprise=无限
  • list_security_schedules — 列出团队的所有计划安全扫描，包括 cron、时区、启用状态、下次运行时间和通知设置。与父级扫描配置（名称、scan_type、target_url）联接
  • create_security_schedule — 为安全扫描创建定期计划。需要 scan_id 和 cron_expression。每个扫描配置只能有一个计划。可选的 timezone、notify_on_fail（none/email/slack/both）、notify_email、slack_channel_id。每次运行都会计入每月上限；管理员用户不受上限限制。运行时始终从扫描配置读取扫描深度
  • delete_security_schedule — 删除计划安全扫描。不会影响父级扫描配置或已完成的运行

示例工作流

  1. get_security_usage → 检查剩余配额
  2. create_security_scan → 为你的 URL 或代码库配置扫描
  3. run_security_scan → 触发一次性漏洞扫描
  4. create_security_schedule → 自动执行定期扫描（例如，每周对 main 分支运行 SAST）
  5. get_security_results → 查看发现和修复建议

📖

代码审查

  • list_code_reviews — 列出团队近期的 AI 代码审查。返回质量分数、严重性计数、PR 信息和时间戳。仅限 Enterprise
  • get_code_review — 获取包含所有发现的代码审查。每项发现包括严重性、类别（bug/security/performance/style/logic/maintainability）、标题、描述、代码建议、文件路径和行号
  • get_code_review_usage — 检查代码审查用量。AI 代码审查仅限 Enterprise；Enterprise 套餐不限量
  • get_code_review_analytics — 获取审查分析数据：趋势、发现类别/来源、严重性分布、速度指标、热门代码库/作者。支持回溯 7/30/90 天

示例工作流

  1. get_code_review_usage → 检查剩余审查次数
  2. 在仪表板的 /dashboard/code-review 审查 PR
  3. list_code_reviews → 查看近期审查
  4. get_code_review → 获取发现和建议

🔍

探索式 AI

多代理自主网站错误查找工具，最多支持 10 个并行代理，每个代理使用不同的测试策略。

  • list_explorations — 列出团队的探索式 AI 配置
  • create_exploration — 创建新的探索任务。接受 agent_count（1–10，最多 10）以运行多个并行代理，并为其分配不同策略：happy_path、edge_case、security、accessibility、error_path、performance、mobile、data_integrity、navigation、custom。此工具无法配置凭据或身份验证模式。请明确通过仪表板或 REST 配置并启动 仅测试登录流程，然后使用 get_exploration 和 get_exploration_run 检查配置和结果。切勿根据指令推断模式，也不要在 MCP 参数中填写凭据。默认的基于凭据的探索仍需要可重复使用的会话。
  • get_exploration — 获取探索配置，包括代理设置、安全的身份验证元数据和近期运行记录。绝不会返回密码和密文。
  • get_exploration_run — 获取运行结果，包括各代理的进度、阶段数据、带代理归属信息的发现（agent_index、agent_strategy）以及关联错误
  • get_exploration_usage — 检查每月用量。探索式 AI 仅限 Enterprise；Enterprise：不限量（10 个代理）

示例工作流

  1. 使用 agent_count: 5 调用 create_exploration → 配置 5 个并行代理
  2. 从仪表板或通过 POST /api/explorations/run 触发运行
  3. get_exploration_run → 轮询各代理的进度和发现
  4. 在仪表板中查看带代理归属信息的去重发现

📝

备注

  • list_notes — 列出备注，可选按关键词、项目、可见性、文件夹、标签、归档状态、wiki、日期范围和排序方式筛选。返回用户拥有的备注或与其共享的备注。
  • create_note — 以 5 种格式之一创建备注：markdown、plain、bugtemplate、checklist、outline。将 visibility 设为 private 或 shared。若未提供标题，则根据前 30 个字符自动生成标题。可选的 attachments 数组接受 base64 编码的文件，每个文件最大 400 MB：任何图像、视频、音频、PDF 或文本/JSON 文件。传入 time_spent_seconds 以跟踪 QA 工作量。
  • get_note — 获取备注的完整详情，包括内容和附件。需要 id。
  • update_note — 更新标题、内容、格式、可见性、项目或 time_spent_seconds。传入 attachments 数组可将新文件（每个最大 400 MB）追加到备注现有附件中，而不会替换它们。只有作者可以更新。需要 id。
  • delete_note — 永久删除备注及其附件。只有作者可以删除。需要 id。
  • list_note_folders — 列出备注/wiki 文件夹，可选限定到某个项目。
  • create_note_folder — 创建项目范围内的备注/wiki 文件夹，可选设置父文件夹、可见性、收藏状态和队友访问权限。

示例工作流

  1. create_note → 开始记录测试会话
  2. update_note → 测试时追加观察结果
  3. list_notes → 按关键词或项目搜索过往备注
  4. get_note → 获取包含附件的完整备注

🤖

自动化

  • create_automation — 使用自定义 Playwright 脚本创建新的自动化（无需 FAB 录制）。需要 name。可选：target_url（若省略，则从脚本中的第一个 page.goto(...) URL 自动推导）、script（Node.js/JavaScript/TypeScript 或 Python — 自动检测语言；默认使用占位符）、status（draft 或 active，默认值：draft）、project_id。返回自动化 id。**提示 — 复制自动化：**使用 get_automation 获取原始脚本，然后调用 create_automation，将 name 设为 "[Copy] Original Name"，并传入原始的 script、target_url 和 project_id。副本的状态为 draft，且没有版本历史。
  • list_automations — 列出 Playwright 自动化脚本。按 project_id 或 status（draft、active、paused）筛选。返回自动化数组，包含 name、target_url、last_run_status 和 run_count。
  • get_automation — 获取完整的自动化详情，包括 Playwright 脚本和近期运行记录。需要 id。返回自动化及其当前的 script、一个 script_versions 堆栈（按时间从旧到新排列，最多包含 100 条历史记录，每条为 { script, source, timestamp }），以及一个 recent_runs 数组，其中每次运行都包含执行时使用的 script_version_label / script_version_source。如果需要选择特定历史版本，请在调用 run_automation 前调用此工具。
  • run_automation — 立即触发一次 Playwright 测试运行。需要 automation_id。**定位器自愈（自动）：**定位器操作超时时，运行器会请求 Claude 提供可用的选择器，并重试该步骤一次 — 断言不会自愈，因此真实回归仍会失败 — 每次自愈都会记录在运行标准输出中。模拟模式（默认）：可选的 device，用于指定模拟设备配置文件（例如 desktop、iphone-15）。真实模式：设置 browserstack: true，并使用 bs_browser（chrome、firefox、safari、edge）、bs_os（Windows、OS X）和 bs_os_version，即可在真实桌面浏览器上运行。**真实移动设备：**设置 bs_os: "android"（设备："Samsung Galaxy S25 Ultra"、"Google Pixel 10"、"OnePlus 13R"）或 bs_os: "ios"（设备："iPhone 17 Pro Max"、"iPhone 16 Pro Max"、"iPhone 15 Pro Max"），并在 bs_os_version 中传入设备名称。两种模式都在后台运行；真实模式描述的是执行环境，而非可见的交互会话。Node.js 脚本通过 browserstack-node-sdk 路由（支持桌面、Android 和 iPhone）。Python 脚本通过 browserstack-sdk（pytest-playwright）路由，仅支持桌面 — Python 不支持真实移动设备，因为 pytest-playwright 的 browser_type.connect() 无法驱动 BrowserStack 的真实移动设备端点。视频和网络日志会自动捕获；控制台日志仅支持桌面。**版本重放：**使用 get_automation 检查 script_versions，然后传入首选的持久化 version_label（例如 "v103"）。仍支持旧版 version_index，但不得与 version_label 同时使用。**默认行为：如果两个选择器都省略，则运行当前保存的脚本。**已清理的标签和无效索引会被拒绝，而不会静默运行当前版本。运行记录会保存实际运行的精确快照；从失败运行自动创建的任何错误报告都会深度链接回编辑器中的对应版本。
  • list_automation_runs — 列出某个自动化的近期运行记录。需要 automation_id。返回包含状态、duration_ms 和 error_message 的运行记录。
  • list_schedules — 列出所有已安排的 Web 自动化运行，包含可为 null 的 cron_expression、可为 null 的 run_at、once_status、时区、设备和通知设置。周期性记录的 run_at 和 once_status 保持为 null；一次性记录的 cron 为 null。一次性状态：pending、claimed、missed、dispatched、failed、uncertain。这些是调度状态，而非测试结果；请检查 list_automation_runs 查看结果。
  • 周期性 Web 调度：create_schedule 会验证五个数字 cron 字段和时区，并返回未来的 UTC next_run_at。支持按月和按年重复。例如，30 12 23 9 * 在 America/Toronto 中表示每年 9 月 23 日 12:30，而非一次性运行。创建前会拒绝无效或不可能的时间设置。当月中的日期和星期几都有限定时，两者必须同时匹配。夏令时中不存在的时间会被跳过；重复的本地时间可能发生两次。调度会在调度器的下一次轮询时触发，不一定恰好在指定分钟。现有周期性行为保持不变。
  • **一次性 Web 调度：**调用 create_schedule 并传入 { "automation_id": "AUTOMATION_UUID", "run_at": "2030-12-15T09:30:00-05:00", "timezone": "America/Toronto" }，选择未来日期，并省略 cron_expression。必须且只能提供一个时间字段。run_at 要求使用带时区偏移的 ISO 8601 未来时间戳（显式偏移或 Z）；IANA 时区仅用于显示。已启用的待处理调度会在到期后的首次 cron 轮询时执行；若延迟超过一小时，则标记为 missed。调度会在分发前以原子方式认领并禁用，消耗后无法重新启用。确定的分发失败状态为 failed；分发结果不明确时状态为 uncertain，且绝不会自动重试。安排另一次尝试前，请先检查运行记录。dispatched 不表示已完成或已通过。只能通过 API/MCP 创建，不会新增仪表板创建模式。
  • Web 调度时区使用 IANA 标识符，例如 America/Argentina/Buenos_Aires。仪表板选择器包含服务器支持的所有地区和城市，默认使用你的个人资料时区；MCP 时区默认值仍为 UTC。
  • create_schedule — 创建已安排的 Web 自动化运行。需要 automation_id，并且必须且只能提供 cron_expression 或 run_at 之一。支持可选的设备、时区、失败通知、电子邮件和 Slack 频道设置。请先通过仪表板连接 Slack，并选择机器人所属的频道；仅安装 webhook 并不足够。请参阅 Slack 设置和频道发现。
  • **一次性发布与恢复：**部署匹配的 API/MCP 和调度器代码前，先应用数据库迁移 374_one_time_web_schedules.sql。工作进程崩溃后，claimed 可能仍会保留：对于已认领或状态不确定的分发，在创建替代项前先检查运行历史。超过一小时的延迟时间戳绝不会自动执行。
  • **草稿 Web 自动化：**创建调度、重新启用调度，或更改其 cron 表达式或时区前，请先激活自动化。create_schedule 会在因草稿状态而拒绝操作前验证工作区和项目访问权限。自动化处于草稿状态时，现有调度会跳过周期；暂停、删除、固定和仅更改通知仍可用。没有用于 Web update_schedule 的 MCP 工具；请使用仪表板进行这些更新。
  • delete_schedule — 删除已安排的 Web 自动化运行
  • list_mobile_schedules — 列出所有已安排的移动自动化运行，包含设备、cron、时区和通知
  • create_mobile_schedule — 在真实设备上创建已安排的移动自动化运行。需要 automation_id 和 cron_expression；devices 为可选项。
  • delete_mobile_schedule — 删除已安排的移动自动化运行
  • optimize_automation_script — 将 Playwright 脚本发送给 Sonnet 4，进行 AI 驱动的优化。应用一份包含 12 项的检查清单，修复选择器、等待策略、断言、错误处理、身份验证模式、移动设备兼容性和严格模式。需要 automation_id。优化前会保存当前脚本版本。返回优化后的脚本和更改摘要。
  • undo_automation_script — 将自动化脚本还原到上一版本。最多保留 100 个历史版本。需要 automation_id。返回还原后的脚本和剩余版本数。

示例工作流

  1. create_automation → 使用自定义脚本创建测试
  2. list_automations → 浏览可用测试
  3. get_automation → 检查 Playwright 脚本
  4. run_automation → 触发测试
  5. list_automation_runs → 查看结果和耗时

⏱️

时间跟踪

  • list_time_entries — 列出团队的时间条目。按 period（today、week、month、all）、project_id、category 和 sort（newest、oldest、most_time、least_time）筛选。仅限 Enterprise 计划。
  • create_time_entry — 记录 QA 任务耗时。需要 description、category 和 duration_minutes。可选设置 project_id 和 entry_date（默认为今天）。仅限 Enterprise 计划。
  • update_time_entry — 更新现有时间条目。需要 id。可更新 description、category、duration_minutes、project_id 或 entry_date。仅限 Enterprise 计划。
  • delete_time_entry — 永久删除时间条目。需要 id。仅限 Enterprise 计划。

示例工作流

  1. create_time_entry → 记录 45 分钟的回归测试
  2. list_time_entries → 查看本周的时间条目
  3. update_time_entry → 调整时长或类别
  4. delete_time_entry → 删除错误条目

☑️

测试用例

测试管理功能包括分层文件夹、嵌套套件（最多 3 层深度，运行时会自动展开子套件）、拖放排序，以及包含 KPI 趋势、失败分析、套件健康度、覆盖率和测试人员效率分析的 Reports 分析标签页。所有工具都直接调用 Supabase — 无需 HTTP 往返，延迟与仪表板相同。

**Free 限制：**最多存储 10 个测试用例、1 个套件、3 个文件夹；每个用例的结构化内容最多 128 KB；最多 2 个活跃工作区 API 密钥；每个 UTC 日历月最多运行 10 次测试。其中最多 3 次可使用 Hermes 或其他外部代理，最多同时运行 1 个外部任务，且每个外部计划最多包含 10 个用例。Free API 密钥的 MCP 流量限制为每个密钥每分钟 30 个请求、每个工作区每分钟 60 个请求。Enterprise 的测试用例存储和运行次数不限，但仍受平台通用保护措施约束。

AI 测试用例生成、AI 标签建议、Figma 导入和测试用例文件附件仅限 Enterprise。Free 的 128 KB 结构化内容限制与 Enterprise 文件附件分开计算。Free 可以存储 URL 引用。在上述限制范围内，Free 仍可使用核心 MCP 测试用例工具。

免手动执行：运行审核页面采用轮播形式，每次显示一个用例，支持键盘快捷键（P 通过 · F 失败 · B 阻止 · S 跳过）和语音控制。点击麦克风，然后说“通过”、“失败”、“阻止”、“跳过”、“下一个”、“上一个”、“添加备注”（将语音转录到备注字段）、“保存备注”或“关闭语音”。成功结果会自动前进到下一个未测试用例；失败时则停留在当前用例，以便测试人员口述详情并创建错误报告。支持 Chrome、Edge 和 Safari。

用例与文件夹
  • list_test_cases — 列出可访问的测试用例，可选使用 project 选择器以及 search、priority、type、status 和 sort 筛选条件。添加 folder_id（未归档时为 null）或 suite_id 以筛选直接归属，不包含后代。API 密钥调用方需要 test_cases:read。limit 默认为 50（1-200）；offset 默认为 0（0-1000000）。未更改的 cases 数组还会附带 total / total_count（表示所有获授权的匹配项）、limit、offset、has_more 和可为 null 的 next_offset。此前 total 错误地表示页面长度。请持续跟进 next_offset，直到其为 null；不要根据页面长度推断是否已完成。超出偏移量 1000000 的后续请求会明确失败；请缩小筛选范围，而不要收到无法使用的游标或错误的完成状态。超过 1 MiB 用例数据的页面会明确失败：请使用更小的 limit 重试，而不是接受被省略的记录。排序使用稳定的 ID 作为平局判定，但并发编辑可能导致偏移分页发生变化。
  • 分页示例： 使用 {"project":"test-bed","limit":50,"offset":0} 调用 list_test_cases。对于 55 个匹配项，响应包含 total:55, has_more:true, next_offset:50。使用 offset:50 重复请求，以获取剩余五项和 has_more:false, next_offset:null。
  • create_test_case — 在必需的 project 选择器中创建测试用例（UUID、slug、精确名称或工单前缀；请先调用 list_projects）。有两种模板变体：steps（默认）——通过 steps 数组提供逐步的 { action, expected } 网格；text——通过 text_content 提供单个自由格式描述。两种字段可在同一次调用中发送。可选的 urls 数组（最多 10 个 http/https URL）可附加参考链接，Free 计划可用。文件附件需要 Enterprise 和仪表板会话。API 密钥调用方需要 test_cases:write。
  • 分页恢复： 请求超出可用结果范围的用例偏移量会返回明确错误；请从偏移量 0 重新开始。用例在请求之间被删除时也可能发生这种情况。请使用返回的续页信息，而不要猜测下一个偏移量。
  • 用例标识符： list_test_cases、get_test_case、create_test_case 和 update_test_case 会返回 UUID id、不可变的 short_id（例如 TEST-BA-CASE-123）以及数字型 case_number，包括精简的更新/无操作响应。没有项目的旧版用例使用 TEST-CASE-123。缺失的标识符会以 null 返回；请使用 UUID 作为回退值。标识符由数据库分配；调用方无法更改标识符，也无法在创建时选择标识符。前缀重命名不会改写现有 ID。
  • 单个用例查询： get_test_case 和 update_test_case 接受 id 中的 UUID 或完整短 ID；link_test_case_to_bug 和 list_test_case_links 接受 case_id 中的任一种。精确查询活动工作区之前，会规范化首尾空格、字母大小写和数字补零。授权依据存储的工作区和项目，而非 ID 前缀。裸数字、部分 ID 和通配符搜索均不受支持。批量用例数组、执行结果 case_id、缺陷 ID、文件夹 ID 和套件 ID 仍仅接受 UUID。链接记录保留 UUID case_id。
  • 编号间隙： 用例编号不一定连续。编辑 URL 或递增编号可能导致用例不存在或无法访问；这并不能保证找到下一个用例。请使用列表工具发现用例并遵循其分页信息。
  • 工作区范围： 不同工作区中可能存在相同的短 ID。MCP 仅在活动工作区中解析该 ID；使用其他工作区的短 ID 前，请切换工作区上下文。分享仪表板短 ID URL 时，请保留 ?team=<case.team_id>，例如 /dashboard/test-cases/TEST-BA-CASE-123?team=<team-uuid>。UUID 永久链接保留现有的跨工作区授权行为。MCP 不会构造永久链接。
  • get_test_case — 获取获授权的用例记录，包括步骤和标识符。不会加载变更历史或执行历史。示例：{"id":"TEST-BA-CASE-123"}。
  • 执行时长估算： get_test_case 会返回 estimated_time_seconds 和兼容性别名 estimated_time，两者单位均为秒。已存储的 0 保持为 0；未知或缺失的估算值为 null。当两个名称都存在时，以规范字段为准，包括显式的 null；仅有旧版 estimated_time 值时，将其视为秒，不进行转换。list_test_cases 使用 estimated_time_seconds。create_test_case 输入仍为 estimated_time，单位同样为秒；REST 请求和响应使用 estimated_time_seconds。
  • list_test_case_folders — 列出可访问的文件夹。最多返回 500 个；接受灵活的 project 选择器和 parent_folder_id 筛选条件（仅查询顶层文件夹时使用 "root"）。API 密钥调用方需要 test_cases:read。
  • get_test_case_folder — 通过必需的 id（UUID）直接读取一个测试用例文件夹。仅返回文件夹记录，不会隐式加载后代文件夹或测试用例。需要有权访问其工作区和项目；API 密钥调用方需要 test_cases:read。
  • 测试用例 type 值适用于 list_test_cases、create_test_case 和 bulk_update_test_cases：functional（创建时的默认值）、regression、smoke、integration、performance、security、usability、exploratory。写入前会拒绝无效类型。端到端流程请使用 integration；e2e、accessibility 和 other 不是受支持的测试用例类型。自动化脚本类型属于单独的契约。
  • create_test_case_folder — 在 list_projects 返回的必需 project 中创建文件夹（通过 parent_folder_id 最多嵌套 3 层）。需要具备工作区贡献者或更高级别的访问权限，并有权访问该项目。API 密钥调用方还需要 test_cases:write。
  • update_test_case_folder — 按文件夹 UUID 更新：id、可选的 name（去除首尾空格后为 1-120 个字符）、可为 null 的 description（最多 50000 个字符）、可为 null 的 parent_folder_id 和可为 null 的 card_color。指定父 UUID 会在同一工作区和项目内移动文件夹及其子树；null 会将其移至根目录。颜色接受小写调色板 #1e293b, #7c2d12, #713f12, #14532d, #1e3a5f, #312e81, #581c87, #831843, #4a044e, #fef08a, #fca5a5, #93c5fd；null 会清除颜色。未提供的字段保持不变。至少需要一个更新字段。未知、拼写错误或无效字段会导致整个请求被拒绝，不保存任何更改。自身/后代循环、与同级、直接父级或直接子级重名（忽略大小写和首尾空格），以及子树深度超过 3（根目录深度为 0）均会被拒绝。后代深度会以原子方式更新；用例 ID 和归属关系保持不变。冲突的并发更改可能导致失败；重试前请重新读取文件夹。需要具备活动项目的贡献者或更高级别访问权限；API 密钥还需要 test_cases:write。示例：{"id":"folder-uuid","card_color":"#93c5fd"}。返回更新后的 id、team_id、project_id、name、description、card_color、parent_folder_id、depth 和 updated_at。文件夹 get/list 读取也会包含 card_color。
  • update_test_case — 通过 id 中的 UUID 或完整短 ID 修补现有用例，且至少提供一个字段：name（或别名 title）、description、preconditions、steps、template_type、text_content、priority、type、status 或 folder_id。未提供的字段保持不变；steps 会替换整个数组（[] 会清空数组）。显式的 null 会清除描述、前置条件、text_content 或文件夹归属；空的 text_content 也会清除内容。如果同时发送 name 和 title，两者必须一致。优先级和类型使用创建时的枚举；状态为 active、draft 或 deprecated。更改类型时会将 type_tags 与新类型对齐，与 PATCH API 的行为一致。不支持移动工作区/项目或写入文件元数据。文件夹必须属于完全相同的工作区和项目。需要 test_cases:write。返回用例摘要、id、short_id、case_number 和 changed；值未更改时返回 changed: false。更新已确认但历史记录未确认时，会返回 warnings；不要为了修复历史记录而重复更新。发生并发更改错误时，请重新读取用例再重试。套件归属是独立操作：请使用下方的批量工具，而不要在此工具中使用 suite_id。不提供删除工具。
  • bulk_update_test_cases — 对 1–500 个用例 UUID 执行一项操作；单个用例请传入一个 ID。set_folder 接受 params.folder_id（要移动到的 UUID；显式的 null 表示取消归档）。add_to_suite 和 remove_from_suite 接受 params.suite_id；添加操作不会移除其他归属，也不会移动文件夹。还支持 set_priority、set_status、set_type、add_tags、remove_tags、pin 和 unpin。API 密钥需要 test_cases:write。返回 applied、skipped 和 errors；组织级操作会统计已确认更改的行数、对 ID 去重，并跳过已有的归属关系。
  • 创建时的归属： create_test_case 接受可选的 folder_id 和 suite_id。请使用 list_test_case_folders 和 list_test_suites 查找目标（API 密钥调用方进行套件发现时需要 test_runs:read）。文件夹是单一目录位置；套件则是多对多的测试计划归属关系。目标必须属于调用方获授权的同一工作区和完全相同的项目，包括旧版未限定范围的用例。无法访问的用例 ID 会被跳过且不提供详情；目标不匹配则会被拒绝。无效的创建目标会在创建用例前导致请求失败。
  • 部分创建： 用例创建和套件附加是分开的写入操作。如果附加失败，响应会返回已创建的用例 ID、suite_id: null 和一个 warnings 数组。不要重复调用 create_test_case；请对返回的 ID 使用 add_to_suite 重试 bulk_update_test_cases。
  • link_test_case_to_bug — 在测试用例与缺陷报告 UUID（verified_by、covers 或 relates）之间建立可追溯关系。两条记录都必须属于活动工作区，且其项目必须可由调用方访问。
  • list_test_case_links — 列出某个测试用例的所有可追溯链接。
  • list_test_case_review_candidates — 失效测试标记：never_run（创建时间已达 90 天或以上）、always_passes（90 天内连续通过 5 次或以上）、always_skipped（连续跳过 3 次或以上）。
  • mark_test_case_review_flags — 将当前的归档候选标记持久化到 test_cases.review_flag。每周一 09:00 UTC 通过 pg_cron 自动运行。
导入
  • Figma 导入（Enterprise）（仅限仪表板会话）：上传 Figma 画板的 zip 导出文件（最大 100 MiB），Claude 会分析每个屏幕，并将测试用例草拟到你选择或创建的文件夹中。解码前，归档文件最多允许 1,000 个条目；每个条目展开（解码）后不得超过 20 MiB，展开数据总量不得超过 100 MiB；预算也包括忽略的文件和目录。解码后的画板缓冲区必须与其声明的大小一致。格式错误的归档文件、大小不匹配和超出限制都会导致任务在 AI 分析前失败；失败时会保留原始上传文件以供重试，但受存储清理策略约束。有效归档文件会进入多轮处理流程（分类 → 逐屏生成用例 → 基于共享前缀屏幕生成流程级用例 → 自我批评），并使用提示缓存、429 重试和逐帧 AI 错误隔离。用例会以 status=active 创建，带有 ai_generated=true 标签，并通过 source='figma' 和 source_frame_name 保留指向原始画板的链接。使用平台的 Anthropic 密钥——无需为每个团队单独连接 Claude。
套件与运行
  • list_test_suites — 列出最多 50 个可访问的测试套件，可选使用灵活的 project 筛选条件。每个套件都包含一个精确的整数 case_count：所有状态的直接分配用例，不包括后代套件中的用例，并排除其他工作区或其他项目中的用例（仍包含没有项目的旧版用例）。计数不受已获取的成员行数限制。为兼容执行工作器，API 密钥调用方需要 test_runs:read。
  • get_test_suite — 使用必需的 id（UUID）直接读取一个测试套件。仅返回套件记录，不会隐式加载子套件或成员测试用例。需要有权访问其工作区和项目；API 密钥调用方需要 test_runs:read。
  • create_test_suite — 在 list_projects 返回的必需 project 中创建套件。通过 parent_suite_id 最多嵌套 3 层。API 密钥调用方需要 test_cases:write。
  • update_test_suite — 按套件 UUID 更新：id、可选的 name（去除首尾空格后为 1-120 个字符）、可为 null 的 description（最多 50000 个字符），以及 status（active/archived）。未提供的字段和用例成员关系会保留。需要对项目具有活跃贡献者或更高权限，并需要 test_cases:write。不支持移动父级和固定；移动父级需要原子性地维护后代深度。返回 id、team_id、project_id、name、description、parent_suite_id、depth、status 和 updated_at。示例：{"id":"suite-uuid","name":"Checkout regression","description":null}。
  • list_test_runs — 列出测试运行，包含套件名称、受指派人以及通过/失败摘要。通过仪表板上传的运行证据使用私有链接，需要登录仪表板并有权访问该运行的工作区和项目；MCP API 密钥不授予文件访问权限。
  • create_test_run — 创建由仪表板管理的套件运行。运行父套件会自动包含其所有后代子套件中的每个用例（同时关联到父套件和子套件的用例只会添加一次）。每个 test_run_results 行都会记录用例所属的源子套件，以便结果页面按来源分组。
外部代理执行

这些工具可让 Hermes 或其他代理运行时执行已批准的套件，而无需成为 QA 系统的事实记录来源。使用仅具有 test_runs:read 和 test_runs:write 权限的工作区范围密钥。套件会提供项目边界；调用方无法覆盖该边界。

  • start_test_plan — 使用稳定的 external_run_id 启动或恢复不可变的套件快照。重复使用同一 ID 时，会返回现有的匹配运行及其第一页，而不会创建重复运行。
  • get_test_run_plan — 读取规范运行状态和稳定的计划页面。传入上一个 next_cursor；页面默认包含 100 个用例，最多为 200 个。
  • report_test_results — 使用 passed、failed、blocked 或 skipped 状态提交 1–200 个结果。完全相同的重试是安全的；尝试用另一种状态覆盖用例会被拒绝。
  • abort_test_run — 幂等地停止中断的运行，同时保留已接受的部分结果和规范摘要。

**配额行为：**使用相同的 external_run_id 重试 start_test_plan，即可恢复匹配的运行，而不会额外消耗一次运行配额。删除数据不会重置每月运行用量。

**运行时边界：**用例快照不包含凭据、文件正文和私有附件路径。MVP 中的结果证据为文本。目标凭据保留在执行运行时中。浏览器、模型和网络成本由客户承担，客户必须限制目标访问和网络出口。缺陷和发布决策仍由人工负责。

Hermes Agent 指南 将此流程打包为由 bugAgent 维护的社区技能。公开入门套件 包含可直接复制的配置和可安装的技能。这不是 Nous Research 的官方集成。

报告（Tier 1 + Tier 4 分析）
  • get_test_reports_overview — 显示某个时间范围的关键 KPI（通过率、已完成运行数、已执行用例数），并与上一个等长时间范围进行比较。与 Reports 标签页中的 KPI 栏显示的数据相同。此工具不会创建已保存的 Project Report。Enterprise XLSX Project Reports 及其计划由仪表板管理；此版本未启用用于管理这些已保存内容的 MCP 工具。
  • **仪表板报告控件：**Reports 标签页可将多个套件（包括后代套件）合并到一个筛选报告中。已完成的运行还提供 Export PDF 操作，其覆盖率分母为该运行中包含的用例。这些仪表板控件不会增加 MCP 工具参数；下载单次运行的 PDF 需要登录仪表板。
  • **仪表板用例筛选器：**CSV 导出会应用当前 Cases 筛选条件，并涵盖所有匹配页面。Suite Health 和 Coverage by suite 会在所选套件范围内，按子套件的实际父级对其进行分组。仅用于层级结构的父级会显示短横线，不会汇总子级指标。共享相同用例但无关的套件仍会被排除。这些修复不会更改 MCP 工具参数。
  • get_test_reports_failures — 提供四种“该修复什么？”列表：failing_cases（失败率 ≥50%，至少 3 次运行）、flaky_cases（通过/失败状态切换次数最多）、failing_suites（失败率 ≥30%，至少 5 次运行）、regressed_cases（最近一次失败，且该时间范围内更早有一次通过）。

示例工作流

  1. create_test_case_folder → 创建文件夹树（例如 Smoke → Auth）。在同一项目中创建测试用例时，使用返回的文件夹 ID；仪表板的 New Test Case 表单也支持内联创建文件夹。
  2. create_test_case → 定义用例；使用 update_test_case 编辑内容，使用 bulk_update_test_cases 管理套件成员关系
  3. 示例 tools/call：{"name":"update_test_case","arguments":{"id":"00000000-0000-4000-8000-000000000001","title":"Verify login rejection","steps":[{"action":"Submit an incorrect password","expected":"An error is shown; no session is created"}],"status":"active","folder_id":null}}。未提供的优先级、类型和描述保持不变。
  4. create_test_suite → 构建测试计划（子套件可选，最多嵌套 3 层）
  5. create_test_run → 从父套件创建由人工/仪表板管理的运行——自动包含子套件
  6. start_test_plan → 启动或恢复可安全重试的外部代理运行
  7. get_test_run_plan → 获取所有不可变计划页面，然后在所选运行时中执行
  8. report_test_results → 返回有界结果批次；如果无法安全继续执行，则调用 abort_test_run
  9. get_test_reports_failures → 运行完成后询问“本周该修复什么？”
  10. get_test_reports_overview → 按周跟踪通过率趋势

⚡

团队扩充

  • scale_team — 通过扩充测试人员即时扩大 QA 团队。系统会自动创建具有测试人员访问权限的账户。指定 team_size（1–10）、location、duration、budget，并可选指定 product_url、product_types 和 tech_levels。Enterprise 计划提供此功能。获得批准前不会向您收费。

示例工作流

  1. scale_team → 为期 1 个月，在美国安排 5 名高级测试人员
  2. list_team_members → 确认新测试人员已显示在团队中
  3. list_bug_reports → 查看扩充测试人员提交的报告

📱

移动测试（Enterprise）

移动资源按项目划分范围。在创建、导入和筛选列表时，传入 project_id 或灵活的 project 选择器。自动化会继承关联应用的项目；否则，服务器会使用工作区默认项目。未筛选的列表仍可能包含尚未迁移的旧版工作区级记录。

  • list_mobile_apps — 列出已上传的应用，可选按 project_id / project、platform 和 limit 筛选。返回每个应用的 project_id，以便代理在后续操作中继续使用同一项目。
  • upload_mobile_app — 注册 APK（Android）或 IPA（iOS）应用，以便在真实设备上测试。需要 name、platform（android / ios）和 file_url；传入 project_id 可将其分配到当前项目。对于 iOS，请上传 IPA 以便在真实设备上运行，然后使用控制面板上传模拟器 .app 构建版本以进行录制。
  • update_mobile_app — 将应用二进制文件替换为新版本。清除缓存的 URL 和模拟器构建版本，以便所有自动化在下次运行时使用新版本。需要 app_id 和 file_url。可选：version。私有的关联登录配置文件需要其创建者处于活跃状态；共享配置文件需要对同一项目具有活跃访问权限。计划任务继承受保护的自动化默认设置。
  • list_mobile_automations — 列出移动自动化，可选按 project_id / project、app_id、status 和 limit 筛选。结果包含 project_id 和关联的应用 ID。
  • create_mobile_automation — 创建测试脚本。需要 name、app_id、script_type（YAML 使用 maestro，Appium Python 使用 appium，Appium JavaScript 使用 appium_js）和 script；如果应用尚未限定到项目，请传入 project_id。对于一个经过外部验证且自包含的 Maestro YAML 流程，将 execution_mode 设为 browserstack_maestro；否则默认为 appium_actions。YAML appId 必须与关联应用存储的软件包 ID 或 bundle ID 匹配；如果未存储，则由首个通过验证的原生流程确定。占位应用 ID 和混淆的 Android 资源 ID 将被拒绝。支持内联 runFlow，但 v1 不支持外部流程/脚本文件引用。原生 Maestro 会保留诸如 inputRandomText 和 copyTextFrom 之类的命令，以及诸如 ${maestro.copiedText} 和 ${output.value} 之类的运行时表达式。同一项目中的 credential_id 可提供完整的 inputText 值，值为 ${USERNAME} / ${PASSWORD}。同一项目中的 variable_profile_id 可为引用的 ${DATA_*} 值保存默认值；每个引用的键都必须存在。数据配置文件只能包含非机密的合成数据。
  • import_mobile_script — 导入现有移动测试脚本并将其转换为可运行的自动化，同时保留开发者自己的定位器，以便运行时精确解析元素。支持的方言：Appium‑Python、WebdriverIO、Maestro（YAML 流程）和 Playwright（移动 Web）。混淆的 Android 资源 ID 占位符会被跳过，并在选择器映射 warnings 中报告。仅支持 Android 应用。需要 name、app_id 和 script；可选 target_devices 和 project_id。返回自动化以及 action_count、检测到的 dialect 和选择器映射 warnings。
  • run_mobile_automation — 在真实设备上启动移动自动化。需要 automation_id；可选 device、os_version、credential_id 和原生 Maestro 的 variable_profile_id。对于数据，省略 variable_profile_id 以继承自动化默认值，传入 null 表示不使用配置文件，或传入同一项目中的 UUID 以覆盖默认值。每个引用的 ${DATA_*} 键都必须存在。私有登录配置文件需要其创建者处于活跃状态；共享登录配置文件需要对同一项目具有活跃访问权限。系统会过滤完全匹配的已知凭据值，并尽力根据已持久化的文本证据过滤完全匹配的数据配置文件值；转换过的、部分的、编码后的或源自应用的数据值可能仍会保留。经授权的私有视频/屏幕截图仍可访问，并可能显示被测应用呈现的值，因此数据配置文件只能包含非机密的合成值。如果凭据脱敏上下文不可用，或无法证明清理过程安全，则会隐藏详细的凭据相关文本，同时保留状态和可用的视觉证据。诊断信息需要工作区和项目授权；媒体链接五分钟后过期。
  • list_mobile_runs — 获取经授权的移动运行结果（状态、设备、结果摘要、私有视频和屏幕截图链接、BrowserStack 会话、在安全可用时经过过滤的凭据相关原生 Maestro 日志和失败信息，以及任何自动创建的 bug）。运行诊断信息会强制执行工作区成员资格和项目访问权限。可选筛选条件：project_id、automation_id、status（queued、running、passed、failed、error、archived）和 limit。默认不包含已归档的运行记录。
  • create_login_profile — 创建仅写入的加密用户名/密码配置文件，可供 Mobile、Web Automation 和 Exploratory AI 重用。需要 project_id、name、username 和 password；可选的 visibility 为 private（默认值）或 shared。私有配置文件仅创建者可用。共享配置文件可供对同一项目具有访问权限的活跃成员使用。
  • create_mobile_credential — create_login_profile 的兼容名称；使用相同的输入和安全边界。
  • list_login_profiles — 仅列出调用者可见的配置文件，可选指定一个 project_id。返回非机密元数据，包括 visibility；省略其他用户拥有的私有配置文件和无法访问的项目。
  • list_mobile_credentials — list_login_profiles 的兼容名称；绝不返回凭据机密信息。
  • update_login_profile — 重命名、轮换或更改 visibility。活跃创建者可更新任何字段。活跃工作区所有者/管理员可重命名或轮换共享配置文件，但不能更改可见性；私有配置文件仍仅限创建者使用。
  • update_mobile_credential — update_login_profile 的兼容名称；使用相同的所有权和项目检查。
  • delete_login_profile — 创建者软删除；仅共享配置文件支持所有者/管理员进行生命周期恢复。清除未来使用的默认值，同时保留审计历史。
  • delete_mobile_credential — delete_login_profile 的兼容名称；保留历史引用以供审计。
  • create_mobile_variable_profile — 使用 project_id、name 和一个 variables 对象（例如 {"DATA_EMAIL":"qa@example.test","DATA_REGION":"ca"}）创建可重用、限定项目范围的合成测试数据。键必须是大写的 DATA_* 标识符。配置文件允许包含 1–100 个字符串，每个值最多 4096 个 UTF-8 字节，总计最多 65536 字节。拒绝保留的凭据/运行时名称。切勿存储凭据、令牌、生产环境个人数据或其他机密信息。
  • list_mobile_variable_profiles — 列出指定授权 project_id 的 Mobile/Both 配置文件及其可读取的非机密值。适用项目分配规则。现有配置文件和移动端创建时默认使用 both；创建/更新时接受 platform（mobile 或 both）。Web-only 配置文件不包含在移动目录访问和运行时使用范围内。
  • update_mobile_variable_profile — 重命名配置文件，或通过 id 替换其完整的 variables 对象。只有活跃创建者或活跃工作区所有者/管理员可以更新。
  • delete_mobile_variable_profile — 按 id 软删除配置文件。只有活跃创建者或活跃工作区所有者/管理员可以删除；清除自动化默认值，同时保留历史运行引用。
  • list_mobile_schedules、create_mobile_schedule、delete_mobile_schedule — 列出、创建和删除真实设备计划任务。计划任务继承所选自动化的项目上下文、登录配置文件和非机密变量配置文件。私有登录配置文件需要其创建者处于活跃状态；共享登录配置文件需要对同一项目具有活跃访问权限。非机密变量配置文件保留其创建者或所有者/管理员策略。计划任务的更改和删除仅限活跃计划任务创建者或活跃工作区所有者/管理员。

Web 测试数据目录

Automate Web 也可使用相同的非机密项目目录。这些工具需要工作区具备 automation 权限，以及 API 密钥具备 automations:write 范围（包括读取操作）。不需要 Mobile 访问权限。值不会与加密登录配置文件共用记录。目前目录尚不支持将配置文件值绑定或注入 Web 运行。

  • create_web_variable_profile：必需参数 project_id、name、variables；可选参数 platform（web 或 both），默认值为 web。使用与移动端相同的 DATA_* 限制。返回配置文件，包括其 platform。
  • list_web_variable_profiles：必需参数 project_id；返回仅包含 Web/Both 记录的 { profiles: [...] }。
  • get_web_variable_profile：必需参数 id；返回可访问的 Web/Both 配置文件及其合成值。
  • update_web_variable_profile：必需参数 id；可选参数 name、完整替换的 variables 或 platform（web 或 both）。需要活跃创建者或活跃工作区所有者/管理员。若要将 Both 缩小为 Mobile，请使用 Mobile 目录并具备 Mobile 访问权限。
  • delete_web_variable_profile：必需参数 id；管理权限相同。软删除并返回 { deleted: true }，同时保留审计历史。

示例：使用 list_projects 解析项目，使用 {"project_id":"PROJECT_UUID","name":"Canadian checkout","platform":"both","variables":{"DATA_REGION":"CA"}} 调用 create_web_variable_profile，然后使用 list_web_variable_profiles 验证。无法访问的项目/配置文件会报错，且不会泄露其值；无效数据或项目范围内的重复名称会被拒绝。

示例工作流 — Android

  1. list_projects → 解析目标 project_id
  2. upload_mobile_app → 在该项目中注册 APK
  3. 在控制面板中安全录制，或使用 import_mobile_script / create_mobile_automation
  4. list_mobile_automations → 在同一项目中解析自动化
  5. run_mobile_automation → 在真实设备上触发自动化，可选使用登录配置文件
  6. list_mobile_runs → 检查状态、结果摘要、私有视觉链接和 BrowserStack 会话元数据
  7. 失败时会自动创建 bug 报告，其中包含失败快照和步骤明细

示例工作流 — iOS

  1. upload_mobile_app → 使用 project_id 注册 IPA，以便在真实设备上运行
  2. 在应用详情页上传模拟器 .app 构建版本（用于录制）
  3. 在浏览器中录制测试 → 从模拟器捕获操作
  4. run_mobile_automation → 在 iPhone 上触发已保存的自动化（使用 IPA）
  5. update_mobile_app → 准备就绪后将 IPA 替换为新版本

示例工作流 — 原生 Maestro

  1. upload_mobile_app → 在目标项目中注册 APK 或 IPA
  2. create_mobile_credential → 可选：为需要身份验证的流程创建同一项目中的配置文件
  3. create_mobile_variable_profile → 可选：创建流程使用的同一项目合成 DATA_* 值
  4. create_mobile_automation → 传入一个可正常运行的 YAML 流程，其中包含关联应用的准确软件包/bundle appId、script_type: maestro 和 execution_mode: browserstack_maestro。使用 ${USERNAME} / ${PASSWORD} 进行登录，并使用 ${DATA_EMAIL} 风格的占位符输入合成数据；传入配置文件 ID 以保存默认值。
  5. run_mobile_automation → 选择兼容设备，并可选覆盖登录或变量配置文件。省略变量配置文件以继承默认值，或传入 null 以在单次运行中禁用它。
  6. list_mobile_runs → 检查经授权的通过/失败摘要、私有视频/屏幕截图、经过过滤的日志、实际步骤名称、详细失败信息和会话元数据。如果无法确认凭据相关运行的清理过程安全，则会隐藏详细文本，同时保留状态和可用的视觉证据。

**使用 AI 优化：**允许名单中的 beta 版本可通过控制面板和 REST 优化端点使用。目前公共目录中尚无 Refine MCP 工具。

✅

合规与证据（企业版）

  • collect_compliance_evidence — 从已连接的服务（Cloudflare、GitHub、Sentry、Supabase、Railway）触发自动化证据收集。返回运行 ID。收集 SSL/TLS 设置、WAF 状态、Dependabot 警报、错误趋势、部署历史等信息。
  • check_config_drift — 检查所有已连接服务的安全配置是否偏离基线（SSL 模式、TLS 版本、HSTS、WAF 规则、安全标头）。
  • generate_access_review — 创建季度访问审查报告。审计团队成员、角色、MFA 状态、API 密钥使用情况，并生成建议（例如，撤销不活跃的密钥）。
  • get_security_events — 查询跨服务安全事件时间线。按来源（cloudflare、sentry、github）和严重程度（critical、high、medium、low、info）筛选。事件会在各服务之间自动关联。

合规覆盖范围

这些工具有助于满足 SOC2（CC4.1、CC6.1、CC7.2、CC8.1）、ISO 27001（A.5.18、A.8.8、A.8.9、A.8.15-16、A.8.29）和 GDPR（Art. 5、25、32、33）的合规要求。

兼容的客户端

bug Agent 可与任何支持 Model Context Protocol 的客户端配合使用。以下是常用客户端的设置指南：

打开 Settings → Developer → Edit Config，然后添加：

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

保存后重启 Claude Desktop。

✳️

Cursor

打开 Settings → MCP Servers → Add Server，或编辑项目根目录中的 .cursor/mcp.json：

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

🌊

Windsurf

打开 Settings → MCP → Add Server，或编辑 MCP 配置文件：

{
  "mcpServers": {
    "bugagent": {
      "type": "http",
      "url": "https://mcp.bugagent.com/mcp",
      "headers": {
        "Authorization": "Bearer ba_live_YOUR_KEY_HERE"
      }
    }
  }
}

直接从终端添加 bug Agent：

claude mcp add --transport http bugagent https://mcp.bugagent.com/mcp --header "Authorization: Bearer ba_live_YOUR_KEY_HERE"

这会直接连接到托管的 Streamable HTTP 服务器。

对于需要 stdio 的客户端，请使用已发布的 bugagent-mcp 桥接程序：

  • 命令：npx
  • 命令行：npx -y bugagent-mcp
  • 参数：["-y", "bugagent-mcp"]
  • 环境变量：BUGAGENT_API_KEY

获取帮助

需要帮助？我们随时为您提供支持。

Discord 社区

加入我们的 Discord，获取实时支持并参与社区讨论。

电子邮件支持

support@bugagent.com — 我们通常会在 24 小时内回复。