Debugg AI

chính thức

Cho phép các tác nhân sinh mã của bạn tạo và chạy các bài kiểm tra đầu cuối không cần cấu hình đối với các thay đổi mã mới trong trình duyệt từ xa thông qua nền tảng kiểm thử Debugg AI.

GitHub

Bạn có thể làm gì với Debugg AI MCP?

Chạy một tác nhân trình duyệt AI trên bất kỳ URL nào — mô tả nội dung cần kiểm tra bằng ngôn ngữ tự nhiên và check_app_in_browser sẽ điều hướng, tương tác, và trả về kết quả đạt/không đạt kèm ảnh chụp màn hình.
Thăm dò nhiều trang mà không tốn chi phí LLM — gửi tối đa 20 URL tới probe_page để nhận ảnh chụp màn hình nhanh, lỗi console, và tóm tắt mạng trong một lô duy nhất.
Kích hoạt quá trình thu thập đồ thị tri thức — sử dụng trigger_crawl để một tác nhân AI khám phá ứng dụng của bạn và điền vào đồ thị tri thức của dự án.
Quản lý bộ kiểm thử và các ca kiểm thử — tạo, liệt kê, chạy và kiểm tra kết quả của các bộ kiểm thử qua test_suite, và định nghĩa các ca riêng lẻ với test_case.
Kiểm tra các tạo phẩm thực thi — truy xuất chi tiết thực thi đầy đủ, ảnh chụp màn hình, dấu vết HAR, và nhật ký console thông qua executions để gỡ lỗi các lỗi.
Duyệt các dự án, môi trường và lần thực thi như các tài nguyên — tham chiếu trực tiếp các thực thể qua URI debugg-ai:// để lấy ngữ cảnh mà không cần gọi công cụ.

Tài liệu

Debugg AI — MCP Server

Kiểm thử trình duyệt bằng AI thông qua Model Context Protocol. Trỏ đến bất kỳ URL nào (hoặc localhost) và mô tả những gì cần kiểm thử — một tác nhân AI sẽ duyệt ứng dụng của bạn và trả về kết quả đạt/không đạt kèm ảnh chụp màn hình.

Thiết lập

Yêu cầu Node.js 20.20.0 trở lên (yêu cầu phụ thuộc từ posthog-node@^5.26.0).

Lấy khóa API tại debugg.ai, sau đó thêm vào cấu hình máy khách MCP của bạn:

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

Hoặc với Docker:

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

Công cụ

Máy chủ cung cấp 8 công cụ: ba công cụ Trình duyệt cộng với một công cụ dựa trên hành động cho mỗi thực thể được quản lý. Các công cụ chính là check_app_in_browser (tác nhân AI đầy đủ) và probe_page (thăm dò trang nhẹ không cần LLM). Phần còn lại — project, environment, test_suite, test_case, executions — mỗi công cụ nhận một bộ phân biệt action (ví dụ: {"action":"list"}) để chọn thao tác. Các hành động hủy delete yêu cầu xác nhận (lời nhắc gợi ý nếu được hỗ trợ, nếu không thì confirm: true).

Trình duyệt

`check_app_in_browser`

Chạy một tác nhân trình duyệt AI trên ứng dụng của bạn. Tác nhân điều hướng, tương tác và báo cáo lại kèm ảnh chụp màn hình. Các URL localhost được tự động tạo đường hầm qua ngrok.

Tham số	Loại	Mô tả
`description`	chuỗi bắt buộc	Nội dung cần kiểm thử (ngôn ngữ tự nhiên)
`url`	chuỗi bắt buộc	URL đích — `http://localhost:3000` được tự động tạo đường hầm
`environmentId`	chuỗi	UUID của một môi trường cụ thể
`credentialId`	chuỗi	UUID của một thông tin xác thực cụ thể
`credentialRole`	chuỗi	Chọn thông tin xác thực theo vai trò (ví dụ: `admin`, `guest`)
`username`	chuỗi	Tên người dùng để đăng nhập (tạm thời — không được lưu trữ)
`password`	chuỗi	Mật khẩu để đăng nhập (tạm thời — không được lưu trữ)
`repoName`	chuỗi	Ghi đè tên kho git được tự động phát hiện (ví dụ: `my-org/my-repo`)

Mỗi lần gọi chỉ nên tập trung vào một kiểm tra. Tác nhân có ngân sách nội bộ khoảng 25 bước; hãy chia các bộ kiểm thử lớn hơn thành nhiều lần gọi.

Mỗi lần chạy thành công trả về một khối browserSession cùng với ảnh chụp màn hình — các URL S3 được ký sẵn cho HAR (dấu vết mạng đầy đủ) và nhật ký console (mọi thông báo console JS) đã được ghi lại. Sử dụng chúng để phát hiện các vòng lặp tải lại, lỗi hydration và các vấn đề thời gian chạy khác mà vượt qua kiểm tra kiểu và kiểm thử đơn vị:

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

Các URL là S3 được ký sẵn có thời hạn ngắn — hãy tải lại lần thực thi cha qua executions {action:"get", uuid} để gia hạn. harStatus / consoleLogStatus phân biệt 'downloaded' (URL có thể tải), 'not_available' (trang không phát ra gì), 'failed' (ghi lại bị hỏng). Trong một lần chạy mới, các URL thường là null vì việc tải lên ghi lại diễn ra không đồng bộ sau khi tác nhân kết thúc — hãy thăm dò executions {action:"get", uuid: executionId} cho đến khi trạng thái đạt 'downloaded'. Các tiêu đề Authorization / Cookie / token/secret/api_key được làm sạch phía máy chủ trước khi các tạo phẩm được lưu trữ.

`trigger_crawl`

Kích hoạt một cuộc thu thập dữ liệu của tác nhân trình duyệt phía máy chủ để điền vào đồ thị tri thức của dự án. Các URL localhost tự động tạo đường hầm. Trả về {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} với knowledgeGraph.imported === true khi nhập thành công. Khối browserSession (URL HAR + nhật ký console, cùng hình dạng như trên) cũng có mặt trong các lần thu thập hoàn tất.

`probe_page`

Thăm dò trang hàng loạt nhẹ không cần LLM. Truyền 1-20 URL; mỗi URL điều hướng, chờ tải và trả về trạng thái được kết xuất — ảnh chụp màn hình + siêu dữ liệu trang + lỗi console có cấu trúc + tóm tắt mạng. Không có vòng lặp tác nhân, không có chi phí LLM, không có xác nhận kịch bản. Sử dụng nó cho các câu hỏi "tôi vừa làm hỏng /settings?", kiểm tra khói đa tuyến sau khi tái cấu trúc, quét CI cho mỗi PR và kiểm tra nhanh xem có hoạt động không khi check_app_in_browser với vòng lặp tác nhân 60-150 giây là quá mức cần thiết.

Tham số	Loại	Mô tả
`targets`	mảng bắt buộc	1-20 mục: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]`
`targets[].url`	chuỗi bắt buộc	URL công khai hoặc localhost (tự động tạo đường hầm)
`targets[].waitForLoadState`	enum	`'load'` (mặc định) / `'domcontentloaded'` / `'networkidle'`
`targets[].waitForSelector`	chuỗi	Bộ chọn CSS tùy chọn để chờ sau khi điều hướng
`targets[].timeoutMs`	số	Thời gian chờ cho mỗi URL, 1000-30000 (mặc định 10000)
`includeHtml`	boolean	Trả về HTML thô trong mỗi kết quả (mặc định false)
`captureScreenshots`	boolean	Trả về một PNG cho mỗi mục tiêu (mặc định true)

Toàn bộ lô chia sẻ một lần thực thi backend + phiên trình duyệt + đường hầm — 5 URL trong một lần gọi nhanh hơn đáng kể so với 5 lần gọi URL đơn song song. Trường error cho mỗi URL bảo toàn khả năng phục hồi của lô: một mục tiêu thất bại không làm hỏng các mục tiêu khác.

Khóa tổng hợp networkSummary là origin + pathname — các vòng lặp tải lại (?n=0..4 liên tục truy cập cùng một điểm cuối) được thu gọn thành một mục duy nhất với số đếm, vì vậy /api/poll xuất hiện với count: 47 là tín hiệu "vòng lặp tải lại vô hạn" có thể hành động mà người dùng ban đầu yêu cầu.

Ngân sách hiệu suất: <10 giây cho 1 URL, <25 giây cho 20. Cổng chết localhost trả về LocalServerUnreachable trong <2 giây mà không tiêu tốn một lần thực thi quy trình làm việc.

`project`

Hành động	Tham số	Kết quả
`get`	`{uuid}`	Chi tiết dự án được tuyển chọn
`list`	`{q?, page?, pageSize?}`	Tóm tắt phân trang
`create`	`{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}`	Dự án đã tạo

Nhóm và kho được giải quyết bằng hoặc uuid hoặc tên (khớp chính xác không phân biệt chữ hoa chữ thường; NotFound nếu không có, AmbiguousMatch nếu có nhiều). Không có update/delete — đổi tên hoặc xóa dự án từ ứng dụng web DebuggAI.

`environment`

Hành động	Tham số	Kết quả
`get`	`{uuid, projectUuid?}`	Môi trường với thông tin xác thực được nhúng (mật khẩu không bao giờ được trả về)
`list`	`{projectUuid?, q?, page?, pageSize?}`	Môi trường phân trang, mỗi môi trường có một mảng thông tin xác thực
`create`	`{name, url, description?, projectUuid?, credentials?}`	Môi trường đã tạo (tùy chọn gieo thông tin xác thực)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	Môi trường đã vá; các thao tác thông tin xác thực chạy xóa → cập nhật → thêm
`delete`	`{uuid, projectUuid?, confirm?}`	Xóa môi trường (xếp tầng thông tin xác thực) — yêu cầu xác nhận

projectUuid tự động giải quyết từ kho git khi bị bỏ qua. Các lỗi cho mỗi thông tin xác thực hiển thị trong credentialWarnings[] mà không chặn thao tác môi trường.

`test_suite`

Hành động	Tham số	Kết quả
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	Bộ kiểm thử phân trang với trạng thái + tỷ lệ đạt
`create`	`{name, description, projectUuid\|projectName}`	Bộ kiểm thử đã tạo
`run`	`{suiteUuid\|(suiteName+project), targetUrl?}`	Kích hoạt tất cả kiểm thử không đồng bộ
`results`	`{suiteUuid\|(suiteName+project)}`	Bộ kiểm thử + kết quả cho mỗi kiểm thử
`delete`	`{suiteUuid\|(suiteName+project), confirm?}`	Xóa mềm — yêu cầu xác nhận

`test_case`

Hành động	Tham số	Kết quả
`create`	`{name, description, agentTaskDescription, suiteUuid\|(suiteName+project), relativeUrl?, maxSteps?}`	Trường hợp kiểm thử đã tạo (không tự động chạy)
`update`	`{testUuid, name?, description?, agentTaskDescription?}`	Trường hợp kiểm thử đã vá
`delete`	`{testUuid, confirm?}`	Xóa mềm — yêu cầu xác nhận

`executions`

Hành động	Tham số	Kết quả
`get`	`{uuid}`	Chi tiết đầy đủ (`nodeExecutions` + trạng thái + errorInfo) + tạo phẩm ảnh chụp màn hình/gif
`list`	`{status?, projectUuid?, page?, pageSize?}`	Tóm tắt phân trang

Lỗi 404 từ backend hiển thị dưới dạng isError: true với {error: 'NotFound', message, uuid}. Thông tin xác thực luôn được trả về mà không có mật khẩu.

Phân trang

Mọi phản hồi chế độ lọc đều được phân trang. Hình dạng phản hồi:

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

Truyền page tùy chọn (chỉ mục bắt đầu từ 1, mặc định 1) và pageSize (mặc định 20, tối đa 200; các giá trị quá lớn sẽ bị giới hạn). Không có phản hồi nào bị cắt bớt một cách âm thầm.

Tài nguyên

Cùng với các công cụ, máy chủ hiển thị các thực thể chỉ đọc dưới dạng tài nguyên MCP để máy khách có thể duyệt và @-đề cập chúng như ngữ cảnh:

URI	Nội dung
`debugg-ai://projects`	Tất cả dự án (trang đầu tiên)
`debugg-ai://environments`	Môi trường cho dự án được tự động phát hiện
`debugg-ai://executions`	Các lần thực thi gần đây (trang đầu tiên)
`debugg-ai://project/{uuid}`	Một dự án, chi tiết đầy đủ
`debugg-ai://environment/{uuid}`	Một môi trường (thông tin xác thực được nhúng, mật khẩu được biên tập lại)
`debugg-ai://execution/{uuid}`	Một lần thực thi, chi tiết nút đầy đủ + liên kết tạo phẩm

Các lần đọc được gửi đến cùng các trình xử lý như các công cụ project / environment / executions, vì vậy dữ liệu và xác thực giống hệt nhau. Tài nguyên là bổ sung — máy khách không hỗ trợ tài nguyên vẫn tiếp tục sử dụng các công cụ.

Bất biến bảo mật

Mật khẩu chỉ được ghi. Chúng không bao giờ xuất hiện trong bất kỳ phần thân phản hồi nào từ bất kỳ công cụ nào.
Các URL đường hầm (*.ngrok.debugg.ai) bị loại bỏ khỏi tất cả các phản hồi của tác nhân trình duyệt, bao gồm cả văn bản do tác nhân tạo ra.
Lỗi 404 từ backend hiển thị dưới dạng isError: true với {error: 'NotFound', ...}, không bao giờ là ngoại lệ được ném ra.
Thiếu DEBUGGAI_API_KEY hiển thị dưới dạng lỗi công cụ có cấu trúc trong lần gọi đầu tiên — máy chủ vẫn đăng ký và liệt kê các công cụ bình thường.

Di chuyển lên v3.0.0 (công cụ dựa trên hành động)

v3 đã hợp nhất 20 công cụ theo động từ thành 8 công cụ dựa trên hành động. Công cụ cũ → tool {action} mới:

Đã xóa	Thay thế
`search_projects`	`project {action:"get"}` / `project {action:"list"}`
`create_project`	`project {action:"create"}`
`update_project`, `delete_project`	Đã bỏ — sử dụng ứng dụng web 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` tham số `headless`	Đã bỏ — luôn không đầu

Các hành động delete hiện yêu cầu xác nhận (lời nhắc gợi ý, hoặc confirm: true). Máy khách sẽ nhận bề mặt mới khi khởi động lại MCP.

Di chuyển từ v1.x (thay đổi phá vỡ trong v2.0.0)

v2 đã thu gọn bề mặt 22 công cụ xuống còn 11. Ánh xạ công cụ cũ → công cụ mới:

Đã xóa	Thay thế
`list_projects`, `get_project`	`search_projects` (chế độ uuid so với chế độ lọc)
`list_environments`, `get_environment`	`search_environments`
`list_credentials`, `get_credential`	`search_environments` — thông tin xác thực được nhúng trên mỗi môi trường
`create_credential`	`create_environment({credentials: [...]})` gieo, hoặc `update_environment({addCredentials: [...]})`
`update_credential`	`update_environment({updateCredentials: [{uuid, ...patch}]})`
`delete_credential`	`update_environment({removeCredentialIds: [uuid]})`
`list_teams`, `list_repos`	`create_project({teamName, repoName})` — giải quyết tên với xử lý mơ hồ
`list_executions`, `get_execution`	`search_executions`
`cancel_execution`	Đã bỏ — việc tắt backend là tự động

Thay đổi hình dạng phản hồi: trường count trần trên các phản hồi danh sách đã biến mất — sử dụng pageInfo.totalCount.

Cấu hình

Biến môi trường	Bắt buộc	Mục đích
`DEBUGGAI_API_KEY`	có	Khóa API backend. Bí danh: `DEBUGGAI_API_TOKEN`, `DEBUGGAI_JWT_TOKEN`.
`DEBUGGAI_API_URL`	không	URL cơ sở backend. Mặc định là `https://api.debugg.ai`.
`DEBUGGAI_TOKEN_TYPE`	không	`token` (mặc định) hoặc `bearer`.
`LOG_LEVEL`	không	`error` / `warn` / `info` (mặc định) / `debug`.
`POSTHOG_API_KEY`	không	Ghi đè khóa dự án đo từ xa được nhúng (ví dụ: fork riêng tư).
`DEBUGGAI_TELEMETRY_DISABLED`	không	Đặt thành `1` / `true` / `yes` / `on` để tắt hoàn toàn đo từ xa.

DEBUGGAI_API_KEY=your_api_key

Vận chuyển từ xa / HTTP (tùy chọn)

Theo mặc định, máy chủ giao tiếp qua stdio (npx cục bộ). Thay vào đó, nó có thể chạy như một MCP từ xa được lưu trữ, đa người dùng qua HTTP có thể truyền phát không trạng thái + OAuth:

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

Đây là một Máy chủ Tài nguyên OAuth: mỗi POST /mcp cần Authorization: Bearer <token>; token bị thiếu/không hợp lệ sẽ nhận được 401 kèm WWW-Authenticate trỏ đến siêu dữ liệu RFC 9728, và các máy khách chạy luồng OAuth dựa trên máy chủ ủy quyền được quảng bá. Bearer có phạm vi theo yêu cầu — api.debugg.ai xác thực nó.

Điểm cuối	Mục đích
`POST /mcp`	MCP Streamable HTTP (được bảo vệ bằng bearer)
`GET /.well-known/oauth-protected-resource`	Siêu dữ liệu RFC 9728 (khám phá máy chủ ủy quyền)
`GET /health`	Kiểm tra sức khỏe Load-balancer / ECS

Biến môi trường	Mặc định	Mục đích
`DEBUGGAI_MCP_TRANSPORT`	`stdio`	Đặt thành `http` cho truyền tải từ xa
`PORT`	`3000`	Cổng lắng nghe HTTP
`DEBUGGAI_MCP_PUBLIC_URL`	`https://mcp.debugg.ai`	URL tài nguyên công khai của máy chủ này (RFC 9728 `resource`)
`DEBUGGAI_OAUTH_ISSUER`	`https://auth.debugg.ai`	Máy chủ ủy quyền được quảng bá cho máy khách
`DEBUGGAI_TOKEN_TYPE`	`token`	Đặt thành `bearer` để token OAuth được chuyển tiếp dưới dạng `Authorization: Bearer`

Các bản cài đặt stdio không cần bất kỳ biến nào trong số này.

Đo lường từ xa

Máy chủ MCP được cung cấp với tính năng đo lường từ xa được bật theo mặc định — một khóa dự án PostHog chỉ ghi được nhúng (phc_*) để nhóm có thể quan sát tỷ lệ trúng bộ nhớ đệm, nhịp độ thăm dò, độ tin cậy của đường hầm và các chỉ số vận hành khác trên toàn bộ cơ sở cài đặt. Các sự kiện được ghi lại:

Sự kiện	Khi nào
`tool.executed` / `tool.failed`	Mỗi lần gọi công cụ
`workflow.executed`	Mỗi lần thực thi tác nhân trình duyệt (mang theo `pollCount`, `durationMs`, `finalIntervalMs`)
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	Mỗi sự kiện vòng đời đường hầm
`template.lookup` / `project.lookup`	Trúng/trượt bộ nhớ đệm với `durationMs` khi gọi lạnh

Quan điểm về quyền riêng tư:

ID phân biệt là SHA-256(api_key).slice(0, 16) — không bao giờ là khóa thô, không có PII.
Các khóa phc_* chỉ ghi theo quy ước PostHog; an toàn để nhúng vào nguồn.
Đặt DEBUGGAI_TELEMETRY_DISABLED=1 để từ chối hoàn toàn (chuyển thành nhà cung cấp không hoạt động; không có sự kiện nào rời khỏi tiến trình).

Chế độ đang hoạt động được ghi lại khi khởi động:

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)

Phát triển cục bộ

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

Bộ đánh giá khởi tạo máy chủ MCP đã xây dựng như một tiến trình con, thực thi mọi công cụ dựa trên một backend thực và ghi các tạo phẩm theo từng luồng vào scripts/evals/artifacts/<timestamp>/. Xem scripts/evals/flows/ để biết các kịch bản riêng lẻ.

Đăng ký MCP: `debugg-ai-local` so với `debugg-ai`

Repo này cung cấp một .mcp.json đăng ký một máy chủ phạm vi dự án có tên debugg-ai-local trỏ đến node dist/index.js — mã cục bộ vừa được xây dựng. Nó chỉ kích hoạt khi thư mục làm việc của Claude Code là repo này.

Các dự án khác của bạn nên sử dụng đăng ký debugg-ai phạm vi người dùng lấy từ gói npm đã xuất bản:

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

Sau khi chỉnh sửa mã ở đây, chạy npm run mcp:local (chỉ đơn giản là xây dựng lại) để lần gọi debugg-ai-local tiếp theo nhận được các thay đổi của bạn.

Liên kết

Bảng điều khiển · Tài liệu · Vấn đề · Discord