bugAgent

官方

將 bugAgent 連接到任何 M

造訪 bugagent.com試用此 MCP贊助

你可以用 bugAgent MCP 做什麼？

  • 提交錯誤報告 — 請您的助理建立錯誤報告，並自動分類至19種類型，包含嚴重性與優先順序設定。
  • 列出與篩選報告 — 使用 list_bug_reports 依專案、嚴重性、狀態、類型或搜尋文字查詢錯誤，支援分頁，最多100筆結果。
  • 挑選下一個要處理的錯誤 — 讓您的助理呼叫 pick_next_bug，為您的團隊取得優先順序最高且未指派的錯誤（S1→S3，最舊優先）。
  • 原子化認領錯誤 — 使用 claim_bug 以無競爭條件的方式將錯誤轉為進行中狀態並指派給您，避免重複工作。
  • 管理測試套件與測試案例 — 建立測試套件、執行回歸套件，並列出過去7天內失敗的測試案例。

文件

Connect bug Agent 到任何相容 MCP 的 AI 用戶端。

直接從你的 AI 編程助手建立、分類和管理錯誤、功能請求等。無需切換上下文，無需複製貼上——只需描述問題，bug Agent 就會處理其餘部分。

外部 MCP 用戶端與 bug Agent 的儀表板 AI 助手是分開的。儀表板助手在所有方案中預設為關閉，需要明確啟用工作區；其 ai_assistant 閘道不會停用 MCP 或整合。MCP 驗證、範圍、工作區/專案權限和工具特定權限仍然適用。

開始使用

bug Agent 運行託管的 MCP 伺服器，讓 AI 用戶端可以透過 Model Context Protocol 建立、查詢和管理錯誤報告、功能請求、增強功能等。用戶端直接連接到託管的 Streamable HTTP 端點。

取得你的 API 金鑰

建立免費帳戶；新的工作區擁有者會直接進入 API 金鑰設定。回訪用戶可以從 Settings → Developers → API Keys 產生金鑰。

設定你的 AI 用戶端

在你的用戶端設定中將 bug Agent 新增為 MCP 伺服器（請參閱下方設定）。

開始提交錯誤

用自然語言描述錯誤，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

設定

建議：託管 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"
      }
    }
  }
}

連接到伺服器

bug Agent MCP 伺服器位於 https://mcp.bugagent.com/mcp，透過 Streamable HTTP 傳輸運行。從以下八個用戶端中的任何一個連接——選擇最適合你工作流程的那個。

如需小型可直接複製的設定、範圍金鑰指南和安全入門提示，請使用公開的 MCP 快速入門。

🔑

先取得你的 API 金鑰。 登入 Settings → Developers，點擊 Create API Key，選擇你的用戶端需要的範圍，然後複製該值（以 ba_live_ 開頭）。你只會看到一次，所以請貼到安全的地方。MCP 用戶端只會列出這些範圍授予的工具。下面的連接範例使用此金鑰；需要互動式 OAuth/工作階段或付費方案權限的提示會另外標示。

選項 1 — MCP Inspector（Web UI，建議首次測試使用）

官方的 Anthropic 工具。啟動一個本機 Web UI，你可以在其中點擊每個工具、填寫參數並查看回應。零設定，無需 IDE。

macOS（終端機）

npx @modelcontextprotocol/inspector

Windows（PowerShell 或 CMD）

npx @modelcontextprotocol/inspector

在開啟的瀏覽器 UI 中：

  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 個錯誤報告」——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 個開啟的錯誤報告。」

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

檢查伺服器在 /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 與你的用戶端相同的端點和金鑰進行比較；匿名探索或不同的金鑰不是有效的比較。檢查是否有專案層級的設定覆蓋你的使用者層級連接，然後在憑證變更後重新連接或重新啟動。

如果已驗證的伺服器目錄包含某個工具，但用戶端仍然無法發現它，請記錄用戶端版本、伺服器版本、工具名稱/數量以及任何 schema 錯誤，並移除憑證和客戶資料。使用 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 會自動從你的自然語言提示解析工具呼叫。試試：「列出我按嚴重性排序的開啟錯誤。」

選項 5 — Cursor（Mac + Windows）

Cursor 有內建的 MCP 支援。使用適當範圍的工作區 API 金鑰，Cursor 內的 AI 助手可以在不離開編輯器的情況下提交錯誤、列出報告和運行支援的自動化工作流程。安全性、效能和探索掃描需要委派的 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）並輸入 「建立一個標題為『登入失敗』且嚴重性為高的錯誤報告。」 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 個開啟的錯誤報告。」

其他支援 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 用戶端、已登入使用者和授予範圍的不透明 token；token 不能對另一個服務重放，也不能由另一個用戶端兌換。

  1. 在 bug Agent 中：開啟 Settings → Developers → MCP Connectors。點擊 Generate connector，給它一個描述主機的名稱（例如 「Claude.ai（工作）」），貼上你的 MCP 主機要求的重新導向 URI（對於 Claude.ai 網頁應用程式是 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 頁面管理和撤銷產生的連接器。撤銷是立即的——該連接器的下一個請求會回傳 invalid_client。

注意： Claude Code、Cursor、VS Code 和 MCP Inspector 不需要此流程——它們會自動處理動態用戶端註冊（RFC 7591）並如上所示透過 API 金鑰驗證。MCP Connectors 表單僅適用於需要靜態 OAuth 憑證的主機。

OAuth 存取和重新整理值只會顯示給主機。它們是不透明的，在重新整理時輪換，且 bug Agent 只以單向雜湊儲存；上游身分重新整理憑證在靜止時加密。絕不要將 OAuth token 複製到 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 連線到 https://mcp.bugagent.com/mcp，並使用標頭 Authorization: Bearer ba_live_YOUR_KEY_HERE；支援 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 傳送 Accept: application/json, text/event-stream 以符合標準的 Streamable HTTP。bug Agent 目前會正規化缺失或不完整的值，但整合不應依賴該相容性行為。

錯誤工作區的資料 每個 API 金鑰僅限於一個工作區。請從您要查詢的工作區在 Settings → Developers 中產生新金鑰。

工具顯示但呼叫靜默失敗 檢查回應中的 isError: true 和傳回的內容。可見的工具仍可能因方案、角色、功能權限、專案成員資格、所有權或無效輸入而被拒絕。只有在讀取工具錯誤後才檢查伺服器健康狀態。

MCP Inspector CORS 錯誤 在 Inspector UI 中為 Connection Type 選擇 Proxy（而非 Direct）。Inspector 會透過本機 Node 程序進行代理，以繞過瀏覽器 CORS 限制。

MCP Inspector v2 以代碼 5 退出 Inspector v2 在工具回應包含 isError: true 時會傳回非零退出代碼。請讀取回應訊息以了解方案、權限、輸入或執行時期錯誤；Inspector v1 對相同的失敗工具回應可能傳回退出代碼 0。

Codex CLI — 工具無法辨識 驗證 ~/.codex/config.toml 使用 [mcp_servers.bugagent]，設定 bearer_token_env_var = "BUGAGENT_API_KEY"，並在啟動 Codex 前匯出該變數。如果工具仍未顯示，請檢查 codex --version。

MCP 功能

對話式工作階段仍是工作區限定的試行功能。儲存工作階段產生的腳本需要其擁有者透過 僅限工作階段的儲存腳本端點 明確的 Workbench 核准。沒有 MCP 核准工具：要求代理程式草擬腳本不會建立或排程自動化。

完整的互動/OAuth 目錄包含 141 個工具。工作區 API 金鑰只能探索其選定範圍允許的最小權限子集；帳戶、API 金鑰管理、團隊管理、進階測試、筆記和時間追蹤工具僅限互動工作階段使用，除非項目明確指定 API 金鑰範圍。

🐛

錯誤報告管理

可恢復的 Google Sheets 螢幕截圖匯入使用獨立的 REST POST /api/reports/import-attachment 端點搭配 reports:write，並使用 reports:read 取得 GET 狀態。未新增螢幕截圖匯入 MCP 工具。此僅限 JPEG/PNG 的 API 會在報告完成前驗證私人儲存空間和精確對應的 Jira 問題；舊版報告上傳仍僅限工作階段。

  • 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 — 直接讀取一個 Epic，需提供必要的 id（UUID 或工作區/專案短 ID）。僅傳回 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 問題；否則該問題將保持不變。
  • add_comment — 在錯誤報告（UUID 或短 ID，內容 1-10000 字元）上新增評論。如果報告已同步到 Jira，評論會自動推送到連結的 Jira 問題。私人附件 Markdown（例如 ![proof](/api/attachments/ATTACHMENT_UUID)）會變成 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，目標報告必須是標準子項目。在建立/更新 Epic 指派時，建議使用 parent_epic_id。
  • 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 套件（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 優先順序與支援的自訂 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、裝置、虛擬使用者、持續時間、分數閾值和自動錯誤建立切換。僅限 Enterprise
  • run_performance_test — 為網頁效能測試觸發頁面稽核和負載測試。回傳執行 ID 以輪詢結果。行動應用程式分析執行從儀表板觸發
  • get_performance_results — 取得完整結果，包括 Lighthouse 分數（效能、無障礙、最佳做法、SEO）、Core Web Vitals（LCP、FID、CLS、FCP、TTFB、INP、TBT、SI）和負載測試指標（VU、請求、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 — 建立安全掃描設定。網頁掃描使用 Quick Scanner + Nuclei（4,000+ 範本），有三種深度等級和可選的驗證掃描。行動掃描使用 MobSF 進行 APK/IPA 二進位分析。可設定的自動錯誤建立與嚴重性閾值。僅限 Enterprise
  • run_security_scan — 觸發漏洞掃描。網頁掃描需要 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 → 自動化週期性執行（例如主分支的每週 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. 在儀表板檢閱 PR，位於 /dashboard/code-review
  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 參數。預設的基於憑證探索仍需要可重複使用的 session。
  • get_exploration — 取得探索設定，附代理設定、安全驗證中繼資料和最近的執行。密碼和密文永遠不會回傳。
  • get_exploration_run — 取得執行結果，附每個代理的進度、階段資料、附代理歸因的發現（agent_index、agent_strategy）和關聯的錯誤
  • get_exploration_usage — 檢查每月使用量。探索性 AI 僅限 Enterprise；Enterprise：無限制（10 個代理）

範例工作流程

  1. create_exploration 搭配 agent_count: 5 → 設定 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 → 開始測試 session 筆記
  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 取得原始腳本，然後以 name 設為 "[Copy] Original Name" 呼叫 create_automation，並傳入原始 script、target_url 和 project_id。複製的自動化會以 draft 狀態啟動，且沒有版本歷史。
  • list_automations — 列出 Playwright 自動化腳本。可依 project_id 或 status（draft、active、paused）篩選。回傳自動化陣列，包含名稱、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 提供可用的選擇器並重試該步驟一次 — 斷言永遠不會被修復，因此真正的回歸仍會失敗 — 且每次修復都會記錄在執行 stdout 中。模擬模式（預設）：可選的 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、時區、裝置和通知設定。週期性列會保留 null 的 run_at 和 once_status；一次性列則有 null 的 cron。一次性狀態：pending、claimed、missed、dispatched、failed、uncertain。這些是派送狀態，而非測試結果；請檢查 list_automation_runs 以取得結果。
  • 週期性 Web 排程： create_schedule 會驗證五個數值 cron 欄位和時區，並回傳未來的 UTC next_run_at。支援每月和每年重複。例如，America/Toronto 中的 30 12 23 9 * 表示每年 9 月 23 日 12:30，而非一次性執行。無效或不可能的時程會在建立前被拒絕。當「每月中的某日」和「每週中的某日」都受限時，兩者必須同時符合。不存在的日光節約時間會被跳過；重複的牆鐘時間可能發生兩次。派送發生在排程器的下一次輪詢時，不一定在精確的分鐘。現有的週期性行為不變。
  • 一次性 Web 排程： 使用 { "automation_id": "AUTOMATION_UUID", "run_at": "2030-12-15T09:30:00-05:00", "timezone": "America/Toronto" } 呼叫 create_schedule，選擇未來的日期並省略 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）篩選。僅限企業方案。
  • create_time_entry — 記錄 QA 任務所花費的時間。需要 description、category 和 duration_minutes。可選用設定 project_id 和 entry_date（預設為今天）。僅限企業方案。
  • update_time_entry — 更新現有的時間記錄。需要 id。可更新 description、category、duration_minutes、project_id 或 entry_date。僅限企業方案。
  • delete_time_entry — 永久刪除時間記錄。需要 id。僅限企業方案。

範例工作流程

  1. create_time_entry → 記錄 45 分鐘的回歸測試
  2. list_time_entries → 檢視本週的時間記錄
  3. update_time_entry → 調整持續時間或類別
  4. delete_time_entry → 移除不正確的記錄

☑️

測試案例

測試管理，包含階層式資料夾、巢狀套件（最多 3 層深，執行時子套件會自動展開）、拖放重新排序，以及分析報告標籤頁，包含 KPI 趨勢、失敗分析、套件健康度、覆蓋率和測試人員生產力。所有工具都直接呼叫 Supabase — 無 HTTP 來回，延遲與儀表板相同。

免費版限制： 10 個儲存的測試案例、1 個套件、3 個資料夾、每個案例 128 KB 的結構化內容、2 個有效的工作區 API 金鑰，以及每個 UTC 日曆月總共 10 次測試執行。其中最多 3 次執行可使用 Hermes 或其他外部代理，且有 1 個有效的外部執行，每個外部方案中最多 10 個案例。免費 API 金鑰 MCP 流量限制為每個金鑰 30 個請求，每個工作區每分鐘 60 個請求。企業版測試案例儲存和執行次數無限制，但受一般平台保護措施約束。

AI 測試案例產生、AI 標籤建議、Figma 匯入和測試案例檔案附件需要企業版。128 KB 免費版結構化內容限制與企業版檔案附件是分開的。免費版可以儲存 URL 參考。核心 MCP 測試案例工具在上述限制內仍可在免費版使用。

免手持執行：執行檢閱頁面是輪播介面，一次只顯示一個案例，具備鍵盤快捷鍵（P 通過 · F 失敗 · B 封鎖 · S 跳過）和語音控制。按一下麥克風，然後說「Pass」、「Fail」、「Block」、「Skip」、「Next」、「Previous」、「Add notes」（會轉錄到備註欄位）、「Save notes」或「Voice off」。成功結果時會自動前進到下一個未測試的案例；失敗時會停留在原地，讓測試人員可以口述詳細資訊並建立錯誤。適用於 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；請勿以頁面長度推斷完成。超過 offset 1000000 的接續會明確失敗；請縮小篩選條件，而非接收無法使用的游標或錯誤的完成狀態。超過 1 MiB 案例資料的頁面會明確失敗：請以較小的 limit 重試，而非接受遺漏的記錄。使用穩定 ID 作為排序依據，但並行編輯可能導致 offset 頁面偏移。
  • 分頁範例： 以 {"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。
  • 分頁復原： 請求超出可用結果範圍的案例 offset 會回傳明確錯誤；請從 offset 0 重新開始。這也可能發生在請求之間案例被移除時。請遵循回傳的接續指示，而非猜測下一個 offset。
  • 案例識別碼： 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、bug ID、資料夾 ID 和套件 ID 仍僅限 UUID。連結記錄保留 UUID case_id。
  • 編號間隙： 案例編號不須連續。編輯 URL 或遞增編號可能導致案例遺失或無法存取；這並非保證的下一案例操作。請使用清單工具探索案例，並遵循其分頁。
  • 工作區範圍： 相同的短 ID 可能存在於不同工作區。MCP 僅在作用中工作區解析；請先切換工作區內容，再使用其他工作區的短 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 — 在必要的 project（由 list_projects 回傳）中建立資料夾（透過 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。資料夾取得/清單讀取也包含 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；請以 add_to_suite 針對回傳的 ID 重試 bulk_update_test_cases。
  • link_test_case_to_bug — 在測試案例和 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 — 在必要的 project 中建立套件，該值由 list_projects 回傳。透過 parent_suite_id 最多巢狀 3 層。API 金鑰呼叫者需要 test_cases:write。
  • update_test_suite — 依套件 UUID 更新：id、可選的 name（去除空白後 1-120 個字元）、可為空的 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 — 列出測試執行，包含套件名稱、指派對象，以及通過/失敗摘要。
  • 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 — 提交 1–200 個結果，狀態為 passed、failed、blocked 或 skipped。完全相同的重試是安全的；嘗試以其他狀態覆寫案例會被拒絕。
  • abort_test_run — 冪等地停止中斷的執行，同時保留已接受的部分結果和標準摘要。

配額行為： 使用相同的 external_run_id 重試 start_test_plan 以恢復相符的執行，而不會消耗另一次執行。刪除資料不會重設每月執行使用量。

執行邊界： 案例快照排除憑證、檔案內文和私人附件路徑。結果證據在 MVP 中為文字。目標憑證保留在執行環境中。瀏覽器、模型和網路成本仍由客戶端承擔，客戶必須限制目標存取和網路出口。人類仍負責缺陷和發布決策。

Hermes 代理指南 將此迴圈包裝為 bugAgent 維護的社群技能。公開入門套件 包含可直接複製的設定和可安裝的技能。這不是 Nous Research 的官方整合。

報告（第 1 層 + 第 4 層分析）
  • get_test_reports_overview — 某時間範圍的標題 KPI（通過率、完成的執行數、執行的案例數），並與先前同等時間範圍的差異。與「報告」頁籤 KPI 列顯示的數字相同。這不會建立已儲存的專案報告。Enterprise XLSX 專案報告及其排程在儀表板中管理；此版本未啟用這些已儲存工件的 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；儀表板的「新增測試案例」表單也提供內聯資料夾建立功能。
  2. create_test_case → 定義案例；使用 update_test_case 編輯內容，使用 bulk_update_test_cases 組織套件成員資格
  3. 範例工具/呼叫：{"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 → 在美國佈建 5 名資深測試人員，為期 1 個月
  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（maestro 用於 YAML，appium 用於 Appium Python，appium_js 用於 Appium JavaScript）和 script；當應用程式尚未限定於專案範圍時，請傳入 project_id。對於一個經外部驗證、自包含的 Maestro YAML 流程，請將 execution_mode 設為 browserstack_maestro；否則預設為 appium_actions。YAML 的 appId 必須與連結應用程式儲存的套件或 bundle ID 相符；若未儲存，則第一個通過驗證的原生流程會建立該 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（行動網頁）。會跳過混淆的 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 日誌和失敗（在安全可用的情況下），以及任何自動建立的錯誤）。執行診斷會強制執行工作區成員資格和專案存取權。選用篩選條件：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 — 列出 Mobile/Both 設定檔及其可讀的非機密值，適用於單一授權的 project_id。適用專案指派規則。現有設定檔和行動建立預設為 both；建立/更新接受 platform（mobile 或 both）。僅限 Web 的設定檔會從行動目錄存取和執行時期使用中排除。
  • update_mobile_variable_profile — 重新命名設定檔，或透過 id 取代其完整的 variables 物件。僅限有效的建立者或有效的工作區擁有者/管理員可更新。
  • delete_mobile_variable_profile — 透過 id 軟刪除設定檔。僅限有效的建立者或有效的工作區擁有者/管理員可刪除；會清除自動化預設值，同時保留歷史執行參照。
  • list_mobile_schedules、create_mobile_schedule、delete_mobile_schedule — 列出、建立和移除真實裝置排程。排程會從其選定的自動化繼承專案內容、登入設定檔和非機密變數設定檔。私人登入設定檔需要其有效的建立者；共用登入設定檔需要有效的同專案存取權。非機密變數設定檔保留其建立者或擁有者/管理員政策。排程變更和刪除僅限於有效的排程建立者或有效的工作區擁有者/管理員。

Web 測試資料目錄

相同的非機密專案目錄也可從 Automate Web 使用。這些工具需要工作區的 automation 權利和 automations:write API 金鑰範圍，包括讀取。它們不需要 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 存取權的行動目錄。
  • delete_web_variable_profile：必填 id；相同的管理權限。軟刪除並回傳 { deleted: true }，保留稽核歷史記錄。

範例：使用 list_projects 解析專案，使用 create_web_variable_profile 搭配 {"project_id":"PROJECT_UUID","name":"Canadian checkout","platform":"both","variables":{"DATA_REGION":"CA"}} 呼叫，然後使用 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. 失敗會自動建立錯誤報告，包含失敗快照和步驟分解

範例工作流程 — 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（第 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 小時內回覆。