Debugg AI

Debugg AI — MCP 伺服器

透過 Model Context Protocol 進行 AI 驅動的瀏覽器測試。將其指向任何網址（或 localhost）並描述要測試的內容——AI 代理程式會瀏覽您的應用程式，並回傳通過/失敗結果及螢幕截圖。

設定

需要 Node.js 20.20.0 或更新版本（來自 posthog-node@^5.26.0 的傳遞性需求）。

在 debugg.ai 取得 API 金鑰，然後新增至您的 MCP 用戶端設定：

{
  "mcpServers": {
    "debugg-ai": {
      "command": "npx",
      "args": ["-y", "@debugg-ai/debugg-ai-mcp"],
      "env": {
        "DEBUGGAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

或使用 Docker：

docker run -i --rm --init -e DEBUGGAI_API_KEY=your_api_key quinnosha/debugg-ai-mcp

工具

伺服器提供 8 個工具：三個瀏覽器工具，加上每個受管理實體一個基於動作的工具。主要工具為 check_app_in_browser（完整的 AI 代理程式）和 probe_page（輕量級、無 LLM 的頁面探查）。其餘工具——project、environment、test_suite、test_case、executions——各自接受一個 action 判別器（例如 {"action":"list"}）來選擇操作。破壞性的 delete 動作需要確認（在支援的情況下會出現提示，否則為 confirm: true）。

瀏覽器

check_app_in_browser

對您的應用程式執行 AI 瀏覽器代理程式。代理程式會導航、互動，並回傳螢幕截圖。Localhost 網址會透過 ngrok 自動建立通道。

參數	類型	描述
description	字串 必填	要測試的內容（自然語言）
url	字串 必填	目標網址——http://localhost:3000 會自動建立通道
environmentId	字串	特定環境的 UUID
credentialId	字串	特定憑證的 UUID
credentialRole	字串	依角色選擇憑證（例如 admin、guest）
username	字串	用於登入的使用者名稱（暫時性——不會持久化）
password	字串	用於登入的密碼（暫時性——不會持久化）
repoName	字串	覆蓋自動偵測到的 git 儲存庫名稱（例如 my-org/my-repo）

每次呼叫進行一項重點檢查。代理程式有大約 25 步的內部預算；將較大的測試套件拆分到多次呼叫中。

每次成功執行都會回傳一個 browserSession 區塊以及螢幕截圖——包含用於擷取的 HAR（完整網路追蹤）和主控台記錄（每條 JS 主控台訊息）的預簽名 S3 網址。使用它們來偵測重新擷取迴圈、水合錯誤以及其他通過型別檢查和單元測試的執行階段問題：

"browserSession": {
  "harUrl": "https://...session_18139.har?X-Amz-...",
  "consoleLogUrl": "https://...session_18139_console.json?X-Amz-...",
  "recordingUrl": "https://...session_18139_recording.webm?X-Amz-...",
  "harStatus": "downloaded",
  "consoleLogStatus": "downloaded",
  "harRedactionStatus": "redacted",
  "consoleLogRedactionStatus": "redacted"
}

網址是短效期的預簽名 S3——透過 executions {action:"get", uuid} 重新擷取父執行以更新。harStatus / consoleLogStatus 用於區分 'downloaded'（可擷取的網址）、'not_available'（頁面未發出任何內容）、'failed'（擷取中斷）。在新的執行中，網址通常為 null，因為擷取上傳是在代理程式完成後非同步進行的——輪詢 executions {action:"get", uuid: executionId} 直到狀態達到 'downloaded'。授權 / Cookie / token/secret/api_key 標頭在成品持久化之前會在伺服器端被清除。

trigger_crawl

觸發伺服器端瀏覽器代理程式爬取，以填充專案的知識圖譜。Localhost 網址會自動建立通道。成功擷取後回傳 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} 和 knowledgeGraph.imported === true。browserSession 區塊（HAR + 主控台記錄網址，格式與上述相同）也會在完成的爬取中出現。

probe_page

輕量級、無 LLM 的批次頁面探查。 傳遞 1-20 個網址；每個網址會導航、等待載入，並回傳渲染狀態——螢幕截圖 + 頁面元資料 + 結構化主控台錯誤 + 網路摘要。沒有代理程式迴圈、沒有 LLM 成本、沒有情境斷言。適用於「我是否剛弄壞了 /settings？」、重構後的多路由煙霧測試、CI 中每個 PR 的掃描，以及快速檢查是否正常運作，而無需使用 check_app_in_browser 的 60-150 秒代理程式迴圈。

參數	類型	描述
targets	陣列 必填	1-20 個條目：[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	字串 必填	公開網址或 localhost（自動建立通道）
targets[].waitForLoadState	列舉	'load'（預設）/ 'domcontentloaded' / 'networkidle'
targets[].waitForSelector	字串	導航後要等待的選用 CSS 選擇器
targets[].timeoutMs	數字	每個網址的逾時時間，1000-30000（預設 10000）
includeHtml	布林值	在每個結果中回傳原始 HTML（預設 false）
captureScreenshots	布林值	每個目標回傳一個 PNG（預設 true）

整個批次共享單一的後端執行 + 瀏覽器工作階段 + 通道——一次呼叫處理 5 個網址，比 5 個平行的單一網址呼叫快得多。每個網址的 error 欄位保留了批次彈性：單一目標失敗不會導致其他目標失敗。

networkSummary 聚合鍵是 origin + pathname——重新擷取迴圈（?n=0..4 重複命中同一個端點）會合併成帶有計數的單一條目，因此 /api/poll 顯示為 count: 47 就是使用者最初要求的、可據以行動的「無限重新擷取迴圈」訊號。

效能預算：1 個網址 <10 秒，20 個網址 <25 秒。Localhost 無效埠在 <2 秒內回傳 LocalServerUnreachable，不會消耗工作流程執行。

project

動作	參數	結果
get	{uuid}	精選的專案詳細資料
list	{q?, page?, pageSize?}	分頁摘要
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	已建立的專案

團隊和儲存庫可透過 uuid 或名稱（不區分大小寫的精確匹配；若無則為 NotFound，若有多個則為 AmbiguousMatch）來解析。沒有 update/delete——請從 DebuggAI 網頁應用程式重新命名或刪除專案。

environment

動作	參數	結果
get	{uuid, projectUuid?}	內嵌憑證的環境（密碼絕不回傳）
list	{projectUuid?, q?, page?, pageSize?}	分頁環境，每個都帶有憑證陣列
create	{name, url, description?, projectUuid?, credentials?}	已建立的環境（可選擇植入憑證）
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}	已修補的環境；憑證操作執行 移除 → 更新 → 新增
delete	{uuid, projectUuid?, confirm?}	刪除環境（連帶刪除憑證）——需要確認

projectUuid 在省略時會從 git 儲存庫自動解析。每個憑證的失敗會顯示在 credentialWarnings[] 中，而不會阻止環境操作。

test_suite

動作	參數	結果
list	{projectUuid|projectName, search?, page?, pageSize?}	帶有狀態和通過率的分頁測試套件
create	{name, description, projectUuid|projectName}	已建立的測試套件
run	{suiteUuid|(suiteName+project), targetUrl?}	非同步觸發所有測試
results	{suiteUuid|(suiteName+project)}	測試套件 + 每個測試的結果
delete	{suiteUuid|(suiteName+project), confirm?}	軟刪除——需要確認

test_case

動作	參數	結果
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	已建立的測試案例（不會自動執行）
update	{testUuid, name?, description?, agentTaskDescription?}	已修補的測試案例
delete	{testUuid, confirm?}	軟刪除——需要確認

executions

動作	參數	結果
get	{uuid}	完整詳細資料（nodeExecutions + 狀態 + errorInfo）+ 螢幕截圖/gif 成品
list	{status?, projectUuid?, page?, pageSize?}	分頁摘要

來自後端的 404 會顯示為 isError: true 和 {error: 'NotFound', message, uuid}。憑證始終在回傳時不包含密碼。

分頁

每個篩選模式回應都是分頁的。回應格式：

{
  "filter": { "...echoed query params..." },
  "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
  "<items>": [ ... ]
}

傳遞選用的 page（從 1 開始索引，預設為 1）和 pageSize（預設 20，最大 200；過大的值會被限制）。任何回應都不會被靜默截斷。

資源

除了工具之外，伺服器還將唯讀實體公開為 MCP 資源，以便用戶端可以瀏覽並以 @ 提及它們作為上下文：

URI	內容
debugg-ai://projects	所有專案（第一頁）
debugg-ai://environments	自動偵測到的專案的環境
debugg-ai://executions	最近的執行（第一頁）
debugg-ai://project/{uuid}	一個專案，完整詳細資料
debugg-ai://environment/{uuid}	一個環境（內嵌憑證，密碼已遮蔽）
debugg-ai://execution/{uuid}	一次執行，完整節點詳細資料 + 成品連結

讀取會分派到與 project / environment / executions 工具相同的處理常式，因此資料和驗證是相同的。資源是附加的——不支援資源的用戶端可以繼續使用工具。

安全性不變條件

• 密碼是唯寫的。它們絕不會出現在任何工具的任何回應主體中。
• 通道網址（*.ngrok.debugg.ai）會從所有瀏覽器代理程式回應中移除，包括代理程式編寫的文字。
• 來自後端的 404 會顯示為 isError: true 和 {error: 'NotFound', ...}，絕不會作為拋出的例外。
• 缺少 DEBUGGAI_API_KEY 會在第一次調用時顯示為結構化工具錯誤——伺服器仍會正常註冊並列出工具。

遷移至 v3.0.0（基於動作的工具）

v3 將 20 個基於動詞的工具整合為 8 個基於動作的工具。舊工具 → 新的 tool {action}：

已移除	替代方案
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project、delete_project	已捨棄——請使用 DebuggAI 網頁應用程式
search_environments	environment {action:"get"} / {action:"list"}
create_environment / update_environment / delete_environment	environment {action:"create"|"update"|"delete"}
create_test_suite / search_test_suites / run_test_suite / get_test_suite_results / delete_test_suite	test_suite {action:"create"|"list"|"run"|"results"|"delete"}
create_test_case / update_test_case / delete_test_case	test_case {action:"create"|"update"|"delete"}
search_executions	executions {action:"get"|"list"}
trigger_crawl headless 參數	已捨棄——始終為無頭模式

delete 動作現在需要確認（提示，或 confirm: true）。用戶端在 MCP 重新啟動後會採用新的介面。

從 v1.x 遷移（v2.0.0 中的重大變更）

v2 將 22 個工具介面縮減為 11 個。舊工具 → 新工具的對應：

已移除	替代方案
list_projects、get_project	search_projects（uuid 模式 vs 篩選模式）
list_environments、get_environment	search_environments
list_credentials、get_credential	search_environments——每個環境內嵌憑證
create_credential	create_environment({credentials: [...]}) 植入，或 update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams、list_repos	create_project({teamName, repoName})——具備歧義處理的名稱解析
list_executions、get_execution	search_executions
cancel_execution	已捨棄——後端關閉是自動的

回應格式變更：清單回應中原始的 count 欄位已移除——請使用 pageInfo.totalCount。

設定

環境變數	必填	用途
DEBUGGAI_API_KEY	是	後端 API 金鑰。別名：DEBUGGAI_API_TOKEN、DEBUGGAI_JWT_TOKEN。
DEBUGGAI_API_URL	否	後端基礎網址。預設為 https://api.debugg.ai。
DEBUGGAI_TOKEN_TYPE	否	token（預設）或 bearer。
LOG_LEVEL	否	error / warn / info（預設）/ debug。
POSTHOG_API_KEY	否	覆蓋內嵌的遙測專案金鑰（例如用於私人分支）。
DEBUGGAI_TELEMETRY_DISABLED	否	設定為 1 / true / yes / on 以完全停用遙測。

DEBUGGAI_API_KEY=your_api_key

遠端 / HTTP 傳輸（選用）

預設情況下，伺服器使用 stdio（本機 npx）。它也可以作為託管的多使用者遠端 MCP，透過無狀態 Streamable HTTP + OAuth 執行：

DEBUGGAI_MCP_TRANSPORT=http PORT=3000 DEBUGGAI_TOKEN_TYPE=bearer npx -y @debugg-ai/debugg-ai-mcp@latest

它是一個 OAuth 資源伺服器：每個 POST /mcp 都需要 Authorization: Bearer <token>；遺失或無效的權杖會收到一個 401，並附帶一個 指向 RFC 9728 中繼資料的 WWW-Authenticate，而用戶端會針對所公告的授權伺服器執行 OAuth 流程。該承載是請求範圍限定的 — api.debugg.ai 會對其進行驗證。

端點	用途
POST /mcp	MCP 可串流 HTTP（受承載保護）
GET /.well-known/oauth-protected-resource	RFC 9728 中繼資料（授權伺服器探索）
GET /health	負載平衡器 / ECS 健康檢查

環境變數	預設值	用途
DEBUGGAI_MCP_TRANSPORT	stdio	設定為 http 以用於遠端傳輸
PORT	3000	HTTP 監聽埠
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	此伺服器的公開資源 URL（RFC 9728 resource）
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	向用戶端公告的授權伺服器
DEBUGGAI_TOKEN_TYPE	token	設定為 bearer，以便 OAuth 權杖作為 Authorization: Bearer 轉送

stdio 安裝不需要上述任何設定。

遙測

MCP 伺服器預設啟用遙測功能 — 內嵌一個唯寫的 PostHog 專案金鑰（phc_*），以便團隊能夠觀察整個安裝基礎中的快取命中率、輪詢節奏、通道可靠性以及其他營運指標。擷取的事件：

事件	觸發時機
tool.executed / tool.failed	每次工具呼叫
workflow.executed	每次瀏覽器代理執行（攜帶 pollCount、durationMs、finalIntervalMs）
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	每次通道生命週期事件
template.lookup / project.lookup	快取命中/未命中，並在冷呼叫時附帶 durationMs

隱私保護措施：

• 區分 ID 是 SHA-256(api_key).slice(0, 16) — 絕非原始金鑰，不含個人識別資訊。
• phc_* 金鑰依 PostHog 慣例為唯寫；可安全內嵌於原始碼中。
• 設定 DEBUGGAI_TELEMETRY_DISABLED=1 即可完全退出（解析為無操作提供者；不會有任何事件離開程序）。

啟動時會記錄啟用模式：

Telemetry enabled (PostHog, DebuggAI default project). Set DEBUGGAI_TELEMETRY_DISABLED=1 to opt out.
Telemetry enabled (PostHog, custom POSTHOG_API_KEY)
Telemetry disabled (DEBUGGAI_TELEMETRY_DISABLED is set)

本地開發

npm install
npm run build
npm run test:e2e        # real end-to-end evals against the backend

評估套件會將建置好的 MCP 伺服器作為子程序啟動，針對真實後端測試每個工具，並將每個流程的產出寫入 scripts/evals/artifacts/<timestamp>/。請參閱 scripts/evals/flows/ 以了解個別情境。

MCP 註冊：debugg-ai-local 與 debugg-ai

此儲存庫提供一個 .mcp.json，它會註冊一個名為 debugg-ai-local 的專案範圍伺服器，指向 node dist/index.js — 即剛建置好的本地程式碼。它僅在 Claude Code 的工作目錄為此儲存庫時才會啟用。

您的其他專案應使用使用者範圍的 debugg-ai 註冊，該註冊會從已發布的 npm 套件中提取：

npm run mcp:global      # registers debugg-ai in ~/.claude.json to npx -y @debugg-ai/debugg-ai-mcp

在此處編輯程式碼後，請執行 npm run mcp:local（它只會重新建置），以便下次叫用 debugg-ai-local 時能套用您的變更。

連結

儀表板 · 文件 · 問題回報 · Discord

---

Apache-2.0 授權 © 2025 DebuggAI