Debugg AI

Debugg AI — MCP Server

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

設定

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

測試 http://localhost:... URL 需要 caddy 二進位檔 — check_app_in_browser、 probe_page 和 trigger_crawl 會透過本機 Caddy 反向代理來隧道傳輸 localhost 目標。 這會自動安裝：@radically-straightforward/caddy npm 依賴項會在 npm install/npx 期間 為您的平台下載固定版本的 Caddy 發行版，與此專案已經為 ngrok 二進位檔所做的相同 — 在一般情況下您無需自行安裝任何東西。如果該下載從未執行（npm install --ignore-scripts、離線/氣隙安裝），請將 CADDY_BIN 指向 您自己的安裝（brew install caddy / apt install caddy / 請參閱 caddyserver.com/docs/install）— 缺少它會在第一次 localhost-URL 呼叫時以 明確的錯誤呈現，而不是無聲的掛起。公開 URL 呼叫、每個非瀏覽器工具，以及 test_suite {action:"run"}（使用其專用隧道並完全繞過 Caddy）無論如何都不需要它。

在 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

Dockerfile 的 npm install 步驟原則上會以本機安裝相同的方式自動取得 caddy — 但截至撰寫本文時，Dockerfile 沒有 COPY 建置現在需要的幾個目錄（handlers、tools、types、config），且仍引用一個已不存在的 tunnels/ 目錄，因此全新的建置可能會在達到該步驟之前就失敗。這是既有的缺口，與 Caddy 無關。目前發布的 quinnosha/debugg-ai-mcp 映像檔無論如何都早於 Caddy 依賴 — 對 check_app_in_browser/probe_page/trigger_crawl 的 localhost-URL 呼叫在該映像檔內會以 CaddyBinaryNotFoundError 失敗，直到它被重建（修正 Dockerfile）並重新發布，或 CADDY_BIN 指向單獨烘焙進去的版本。公開 URL 呼叫、非瀏覽器工具和 test_suite {action:"run"} 無論如何都不受影響。

工具

伺服器公開 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 URL 會透過 ngrok 自動隧道傳輸。

參數	類型	說明
description	字串 必填	要測試的內容（自然語言）
url	字串 必填	目標 URL — http://localhost:3000 會自動隧道傳輸
environmentId	字串	特定環境的 UUID
credentialId	字串	特定憑證的 UUID
credentialRole	字串	依角色選擇憑證（例如 admin、guest）
username	字串	登入的使用者名稱（暫時性 — 不會持久化）
password	字串	登入的密碼（暫時性 — 不會持久化）
loginCredentials	陣列	代理在任務期間遇到的登入帳戶 — [{username, password, label?}]
useEnvironmentCredentials	布林值	預設 true。false 禁止自動填入環境儲存的憑證；若未指定帳戶名稱，則表示完全不登入
freshSession	布林值	預設 false。true 強制實際登入，而非重複使用該帳戶持有的暖 session
auth	物件	驗證前置條件 — {precondition, entryUrl, deepUrl, environmentId, username, password}
repoName	字串	覆寫自動偵測的 git 儲存庫名稱（例如 my-org/my-repo）

每次呼叫一個重點檢查。代理有約 25 步的內部預算；將較廣泛的測試套件拆分為多次呼叫。

憑證：以參數傳遞，而非敘述文字

僅在 description 中指定帳戶名稱不會讓代理使用它 — 它會回退到環境儲存的憑證，而應用程式拒絕錯誤帳戶的情況看起來會像是應用程式失敗。您以參數傳遞的任何內容在執行中的每次登入都優於環境預設值，而不只是第一次：

• username / password（或 credentialId / credentialRole）— 執行的身分。
• auth.username / auth.password — 當您同時使用 auth.precondition: "login" 時，固定前置條件登入。
• loginCredentials — 代理在任務中途遇到的登入表單帳戶。這適用於像是設定密碼 → 被導向到登入頁 → 以剛建立的帳戶登入這類流程，若拆分為多次呼叫會遺失瀏覽器狀態。

當靜默回退到預設測試使用者會使檢查失效時，請設定 useEnvironmentCredentials: false。

檢查完全不需要登入的頁面？ 傳遞 useEnvironmentCredentials: false 且不指定任何帳戶。這個組合的含義正是如此 — 不要登入 — 執行會完全跳過驗證，而不是尋找登入表單。適用於公開頁面、行銷網站、文件，以及任何驗證前的內容。它也更快：在預設（auto）下，代理會從您的頁面跟隨「登入」連結，並在評估任何內容之前嘗試環境儲存的帳戶。

Session 重用：為什麼檢查會回報「沒有登入表單」

執行不會每次都登入。在驗證登入後，後端會擷取該帳戶的 session，並在下次以相同身分執行時還原它，這會完全跳過登入 — 這就是為什麼檢查可以合理地回傳 submitted: false 且沒有登入表單：它已經登入了。還原的執行會在 logins 中以 reason: "restored_session" 自我回報，因此您可以將它與真正找不到表單的執行區分開來。

Session 以每個帳戶為鍵，因此指定不同的帳戶絕不會重用其他人的 session。有兩種方式可以繞過重用：

• 在單次呼叫上使用 freshSession: true — 這次實際登入，然後重新擷取。當登入流程就是您要檢查的內容、當您懷疑儲存的 session 已過期，或當應用程式在角色之間唯一的途徑是登出時，請使用它。
• environment 工具，action: "clearSessions" — 使儲存的 session 失效，讓後續執行登入。使用 username / credentialId 縮小範圍；未限定範圍的清除需要確認，因為環境上的每個帳戶之後都會重新驗證。

使用 action: "sessions" 查看環境目前持有的內容，以及每個是否會被重用。

結果會回報實際使用的身分，因此錯誤的身分是可見的，而不是偽裝成損壞的應用程式：

"logins": [
  { "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true }
],
"credentialWarning": {
  "requested": "qa+invitefix@example.com",
  "used": ["qatest123@example.com"],
  "message": "This run signed in with an environment default credential even though '…' was specified. …"
}

source 是 task | explicit | credential_id（您指定的帳戶）或 env | env_default（環境儲存的帳戶）。credentialWarning 僅在您指定了帳戶但仍使用了環境預設值時出現。loginError 在指定的帳戶無法解析且執行拒絕替換為其他帳戶時出現。

每次成功的執行都會回傳一個 browserSession 區塊，與螢幕截圖一起 — 已擷取的 HAR（完整網路追蹤）和主控台日誌（每條 JS 主控台訊息）的預先簽署 S3 URL。使用它們來偵測重新擷取迴圈、hydration 錯誤，以及其他通過型別檢查和單元測試的執行時期問題：

"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"
}

URL 是短暫的預先簽署 S3 — 透過 executions {action:"get", uuid} 重新擷取父執行來更新。harStatus / consoleLogStatus 區分 'downloaded'（URL 可擷取）、'not_available'（頁面未輸出任何內容）、'failed'（擷取中斷）。在新執行上，URL 通常是 null，因為擷取會在代理完成後非同步上傳 — 輪詢 executions {action:"get", uuid: executionId} 直到狀態達到 'downloaded'。Authorization / Cookie / token/secret/api_key 標頭會在工件持久化之前於伺服器端清除。

trigger_crawl

觸發伺服器端瀏覽器代理爬蟲，以填充專案的知識圖譜。Localhost URL 會自動隧道傳輸。成功攝入時回傳 {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} 與 knowledgeGraph.imported === true。browserSession 區塊（HAR + 主控台日誌 URL，形狀與上述相同）在完成的爬蟲上也會出現。

probe_page

輕量級無 LLM 批次頁面探測。 傳遞 1-20 個 URL；每個都會導覽、在內容上穩定下來（DOM 靜止，有界限 — 絕不依賴網路靜默，因為活躍的應用程式永遠不會達到）、並回傳渲染狀態 — 螢幕截圖 + 頁面中繼資料 + 結構化主控台錯誤 + 網路摘要。沒有代理迴圈、沒有 LLM 成本、沒有情境斷言。用於「我是否剛剛破壞了 /settings？」、重構後的多路由煙霧測試、CI 每個 PR 的掃描，以及 check_app_in_browser 的 60-150 秒代理迴圈過度設計時的快速是否上線檢查。

參數	類型	說明
targets	陣列 必填	1-20 個條目：[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	字串 必填	公開 URL 或 localhost（自動隧道傳輸）
targets[].waitForLoadState	列舉	'domcontentloaded'（預設，+ 有界限的內容穩定）/ 'load'（也等待第三方嵌入）/ 'networkidle'（接受，但從不發出 — 活躍網站的網路不會閒置）
targets[].waitForSelector	字串	可選的 CSS 選擇器，在導覽後等待
targets[].timeoutMs	數字	每個 URL 的逾時，1000-30000（預設 10000）
includeHtml	布林值	在每個結果中回傳原始 HTML（預設 false）
captureScreenshots	布林值	每個目標回傳一張 PNG（預設 true）

批次中的所有目標共用一個 session 隧道，但只有同埠（或全部公開）的批次共用單一後端執行 — 一個呼叫中同一埠上的 5 個 URL 比 5 個並行的單一 URL 呼叫快得多。混合多個本機埠的批次會分解為每個埠組一個依序的後端執行（仍然是一個呼叫，仍然是一個合併的 results[]，以您的原始順序，但是 N 次後端往返而不是一次 — 較慢，不會被拒絕）。每個 URL 的 error 欄位保持批次韌性：單一失敗的目標不會使其他目標失敗。

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

效能預算：1 個 URL <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?}	刪除環境變數（串聯刪除憑證）— 需要確認
sessions	{uuid, username?, credentialId?}	環境變數所持有的已擷取登入工作階段，依帳戶區分，帶有 isUsable 和 usableCount
clearSessions	{uuid, username?, credentialId?, confirm?}	使其失效，讓下一次執行真正登入 — 未限定範圍的清除需要確認

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

sessions / clearSessions 管理後端重複使用的暖認證工作階段，以跳過登入（參見 工作階段重用）。工作階段內容絕不回傳 — 工作階段 cookie 即為 bearer 憑證。clearSessions 將工作階段標記為無效而非刪除資料列，因此重用會立即停止，同時擷取歷史記錄仍可讀取。

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 工具相同的處理器，因此資料和驗證完全相同。資源是附加性的 — 不支援資源的客戶端仍可使用工具。

安全不變式

• 密碼僅供寫入。它們絕不會出現在任何工具的回應主體中。
• 隧道 URL（*.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	否	後端基礎 URL。預設為 https://api.debugg.ai。
DEBUGGAI_TOKEN_TYPE	否	token（預設）或 bearer。
DEBUGGAI_EVAL_TEMPLATE	否	覆寫 check_app_in_browser 分派到的 App 評估工作流程 slug。預設為 flow/e2es/app-eval。分派固定使用此 slug，因此後端範本重新命名不會破壞它。
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 流程。Bearer 權杖是請求範圍的 — api.debugg.ai 會驗證它。

端點	用途
POST /mcp	MCP Streamable HTTP（bearer 保護）
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 安裝不需要這些。

多副本部署（上線前的 go/no-go 檢查）： 隧道狀態（ngrok 工作階段隧道、 其 Caddy 實例及其連接埠路由鎖）是程序內的，以 bearer 權杖的雜湊為每個呼叫者鍵控 — 沒有跨程序協調。在純輪詢負載平衡器後方執行多個副本，表示單一呼叫者的呼叫可能落在不同的副本上，並為每個命中的副本建立一個隧道，而不是為整個工作階段建立一個（額外的 ngrok 成本，以副本數為上限，透過現有的 55 分鐘閒置自動關閉自我修復 — 絕不會造成跨工作階段的正確性錯誤，因為任何單一工具呼叫在整個持續時間內都停留在單一副本上）。要在多副本 HTTP 部署上獲得預期的「每個工作階段一個隧道」行為，請在負載平衡器設定工作階段親和路由（以 getSessionKey() 衍生的相同身分鍵控的黏性/一致性雜湊 — 實務上為呼叫者的 Authorization bearer 權杖）。完整理由及未設定時的誠實降級路徑，請參閱 docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1。

遙測

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) — 絕不是原始金鑰，不含 PII。
• phc_* 金鑰依 PostHog 慣例為唯寫；可安全嵌入原始碼。
• 設定 DEBUGGAI_TELEMETRY_DISABLED=1 可完全退出（解析為 no-op 提供者；沒有事件離開程序）。

啟用的模式會在啟動時記錄：

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 vs 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