Debugg AI

Debugg AI — MCP Server

Kiểm thử trình duyệt hỗ trợ AI thông qua Giao thức ngữ cảnh mô hình. Trỏ tới 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 gián tiếp từ posthog-node@^5.26.0).

Kiểm thử URL http://localhost:... yêu cầu binary caddy — check_app_in_browser, probe_page và trigger_crawl đường hầm các mục tiêu localhost thông qua proxy ngược Caddy cục bộ. Điều này được cài đặt tự động: dependency npm @radically-straightforward/caddy tải xuống một bản phát hành Caddy cố định cho nền tảng của bạn trong quá trình npm install/npx, giống như dự án này đã làm cho binary ngrok — không cần tự cài đặt gì trong trường hợp thông thường. Nếu quá trình tải xuống đó chưa bao giờ chạy (npm install --ignore-scripts, cài đặt ngoại tuyến/không kết nối mạng), hãy trỏ CADDY_BIN tới bản cài đặt của riêng bạn (brew install caddy / apt install caddy / xem caddyserver.com/docs/install) — thiếu nó sẽ hiển thị lỗi rõ ràng ở lần gọi URL localhost đầu tiên, không phải treo im lặng. Các lệnh gọi URL công khai, mọi công cụ không phải trình duyệt và test_suite {action:"run"} (sử dụng đường hầm chuyên dụng riêng và bỏ qua Caddy hoàn toàn) không cần nó trong cả hai trường hợp.

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

Bước npm install của Dockerfile sẽ nhận caddy theo cách tự động tương tự như cài đặt cục bộ về nguyên tắc — nhưng tại thời điểm viết bài này, Dockerfile không COPY một số thư mục mà bản dựng hiện cần (handlers, tools, types, config) và vẫn tham chiếu đến thư mục tunnels/ không còn tồn tại, vì vậy bản dựng mới có khả năng thất bại trước khi điều đó có ý nghĩa. Đó là một khoảng trống có sẵn, không liên quan đến Caddy. Hình ảnh quinnosha/debugg-ai-mcp hiện được xuất bản có trước dependency Caddy bất kể — các lệnh gọi URL localhost tới check_app_in_browser/probe_page/trigger_crawl sẽ thất bại với CaddyBinaryNotFoundError bên trong hình ảnh đó cho đến khi nó được xây dựng lại (Dockerfile được sửa) và xuất bản lại, hoặc CADDY_BIN trỏ tới một cái được tích hợp riêng. Các lệnh gọi URL công khai, các công cụ không phải trình duyệt và test_suite {action:"run"} không bị ảnh hưởng trong cả hai trường hợp.

Công cụ

Máy chủ hiển thị 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ụ nổi bật là check_app_in_browser (tác nhân AI đầy đủ) và probe_page (trình dò trang nhẹ không 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 delete phá hủy yêu cầu xác nhận (lời nhắc khơi gợi khi được hỗ trợ, nếu không thì confirm: true).

Trình duyệt

check_app_in_browser

Chạy tác nhân trình duyệt AI đối với ứng dụng của bạn. Tác nhân điều hướng, tương tác và báo cáo kèm ảnh chụp màn hình. Các URL localhost được tự động đưa qua đường hầm bằng 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 mục tiêu — http://localhost:3000 được tự động đưa qua đườ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ữ)
loginCredentials	mảng	Tài khoản cho các lần đăng nhập mà tác nhân gặp trong nhiệm vụ — [{username, password, label?}]
useEnvironmentCredentials	boolean	Mặc định true. false cấm tự động điền thông tin xác thực đã lưu của môi trường; khi không có tài khoản nào được đặt tên, điều đó có nghĩa là không đăng nhập gì cả
freshSession	boolean	Mặc định false. true buộc đăng nhập thực thay vì tái sử dụng phiên ấm được giữ cho tài khoản đó
auth	đối tượng	Điều kiện tiên quyết xác thực — {precondition, entryUrl, deepUrl, environmentId, username, password}
repoName	chuỗi	Ghi đè tên kho git được phát hiện tự động (ví dụ: my-org/my-repo)

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

Thông tin xác thực: truyền chúng dưới dạng tham số, không phải văn xuôi

Chỉ đặt tên tài khoản trong description không khiến tác nhân sử dụng nó — nó sẽ quay lại sử dụng thông tin xác thực đã lưu của môi trường và việc ứng dụng từ chối tài khoản sai sẽ trông giống như lỗi ứng dụng. Bất cứ điều gì bạn truyền dưới dạng tham số đều thắng mặc định của môi trường cho mọi lần đăng nhập trong lần chạy, không chỉ lần đầu tiên:

• username / password (hoặc credentialId / credentialRole) — danh tính của lần chạy.
• auth.username / auth.password — ghim lần đăng nhập điều kiện tiên quyết khi bạn cũng sử dụng auth.precondition: "login".
• loginCredentials — tài khoản cho biểu mẫu đăng nhập mà tác nhân gặp giữa chừng nhiệm vụ. Đây là lựa chọn cho các luồng như đặt mật khẩu → bị chuyển đến trang đăng nhập → đăng nhập bằng tài khoản bạn vừa tạo, khi việc chia thành các lần gọi riêng biệt sẽ làm mất trạng thái trình duyệt.

Đặt useEnvironmentCredentials: false khi việc quay lại mặc định người dùng thử nghiệm một cách im lặng sẽ làm mất hiệu lực kiểm tra.

Đang kiểm tra một trang không cần đăng nhập? Truyền useEnvironmentCredentials: false và không đặt tên tài khoản nào. Sự kết hợp đó có nghĩa chính xác như những gì nó nói — không đăng nhập — và lần chạy bỏ qua xác thực hoàn toàn thay vì tìm kiếm biểu mẫu đăng nhập. Sử dụng nó cho các trang công khai, trang tiếp thị, tài liệu và bất cứ thứ gì trước xác thực. Nó cũng nhanh hơn: trên mặc định (auto), tác nhân sẽ theo liên kết "Đăng nhập" khỏi trang của bạn và thử tài khoản đã lưu của môi trường trước khi đánh giá bất cứ điều gì.

Tái sử dụng phiên: tại sao một kiểm tra có thể báo cáo "không có biểu mẫu đăng nhập"

Các lần chạy không đăng nhập mỗi lần. Sau khi đăng nhập được xác minh, backend sẽ chụp phiên của tài khoản đó và khôi phục nó ở lần chạy tiếp theo cho cùng danh tính, điều này bỏ qua đăng nhập hoàn toàn — đó là lý do tại sao một kiểm tra có thể hợp lệ quay lại với submitted: false và không có biểu mẫu đăng nhập: nó đã được đăng nhập. Một lần chạy được khôi phục tự báo cáo trong logins với reason: "restored_session", vì vậy bạn có thể phân biệt nó với một lần chạy thực sự không tìm thấy biểu mẫu.

Các phiên được khóa theo từng tài khoản, vì vậy việc đặt tên một tài khoản khác không bao giờ tái sử dụng của người khác. Hai cách để bỏ qua việc tái sử dụng:

• freshSession: true trên một lần gọi — đăng nhập thực một lần này, sau đó chụp lại. Sử dụng khi luồng đăng nhập chính là thứ bạn đang kiểm tra, khi bạn nghi ngờ phiên đã lưu bị cũ hoặc khi tuyến đường duy nhất của ứng dụng giữa các nhân vật là đăng xuất.
• Công cụ environment, action: "clearSessions" — vô hiệu hóa các phiên đã lưu để các lần chạy tiếp theo đăng nhập. Thu hẹp bằng username / credentialId; việc xóa không có phạm vi yêu cầu xác nhận vì mọi tài khoản trên môi trường sau đó sẽ xác thực lại.

Sử dụng action: "sessions" để xem môi trường hiện đang giữ gì và liệu mỗi phiên có được tái sử dụng hay không.

Kết quả báo cáo danh tính thực sự được sử dụng, vì vậy một danh tính sai sẽ hiển thị thay vì ngụy trang thành ứng dụng bị hỏng:

"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 là task | explicit | credential_id (một tài khoản bạn đã đặt tên) hoặc env | env_default (tài khoản đã lưu của môi trường). credentialWarning chỉ xuất hiện khi bạn đặt tên một tài khoản và mặc định của môi trường vẫn được sử dụng. loginError xuất hiện khi một tài khoản được đặt tên không thể được giải quyết và lần chạy từ chối thay thế bằng một tài khoản khác.

Mọi lần chạy thành công đều trả về khối browserSession cùng với ảnh chụp màn hình — các URL S3 được ký trước cho HAR đã chụp (dấu vết mạng đầy đủ) và nhật ký bảng điều khiển (mọi thông báo bảng điều khiển JS). Sử dụng chúng để phát hiện các vòng lặp tìm nạp lại, lỗi hydrat hóa và các vấn đề thời gian chạy khác vượt qua kiểm tra loại và kiểm tra đơ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ý trước có thời gian ngắn — tìm nạp 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ìm nạp), 'not_available' (trang không phát ra gì), 'failed' (chụp bị hỏng). Trên một lần chạy mới, các URL thường là null vì quá trình chụp tải lên không đồng bộ sau khi tác nhân hoàn thành — hãy thăm dò executions {action:"get", uuid: executionId} cho đến khi trạng thái đạt 'downloaded'. Các tiêu đề Ủy quyền / 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 quá trình thu thập dữ liệu 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 được đưa qua đường hầm tự động. Trả về {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} với knowledgeGraph.imported === true khi tiếp nhận thành công. Khối browserSession (URL HAR + nhật ký bảng điều khiển, cùng định dạng như trên) cũng có mặt trên các lần thu thập đã hoàn thành.

probe_page

Trình dò trang hàng loạt nhẹ không LLM. Truyền 1-20 URL; mỗi URL điều hướng, ổn định trên nội dung (DOM trở nên im lặng, có giới hạn — không bao giờ dựa trên sự im lặng của mạng, điều mà một ứng dụng trực tiếp không bao giờ đạt được) và trả về trạng thái đã kết xuất — ảnh chụp màn hình + siêu dữ liệu trang + lỗi bảng điều khiển 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 "tôi vừa làm hỏng /settings?", kiểm tra khói nhiều tuyến sau khi tái cấu trúc, quét CI mỗi PR và kiểm tra nhanh xem có hoạt động không khi vòng lặp tác nhân 60-150 giây của check_app_in_browser 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 (được đưa qua đường hầm tự động)
targets[].waitForLoadState	enum	'domcontentloaded' (mặc định, + ổn định nội dung có giới hạn) / 'load' (cũng chặn trên các nhúng bên thứ ba) / 'networkidle' (được chấp nhận, không bao giờ được phát hành — mạng của một trang trực tiếp không bao giờ chuyển sang trạng thái rảnh)
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ờ 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)

Tất cả các mục tiêu trong một lô chia sẻ một đường hầm phiên, nhưng chỉ các lô cùng cổng (hoặc tất cả công khai) chia sẻ một lần thực thi backend duy nhất — 5 URL trên một cổng trong một lần gọi nhanh hơn đáng kể so với 5 lần gọi URL đơn song song. Một lô trộn nhiều cổng cục bộ phân rã thành một lần thực thi backend tuần tự cho mỗi nhóm cổng (vẫn là một lần gọi, vẫn là một results[] được hợp nhất theo thứ tự ban đầu của bạn, nhưng N lần khứ hồi backend thay vì một — chậm hơn, không bị từ chối). Trường error mỗi URL duy trì khả năng phục hồi của lô: một mục tiêu thất bại đơn lẻ không làm thất bại 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ìm nạp lại (?n=0..4 liên tục truy cập cùng một điểm cuối) thu gọn thành một mục duy nhất kèm 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ìm nạp 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 đốt cháy 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 uuid hoặc tên (khớp chính xác không phân biệt hoa 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 một dự án từ ứng dụng web DebuggAI.

environment

Hành động	Tham số	Kết quả
get	{uuid, projectUuid?}	Env 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?}	Danh sách env có phân trang, mỗi env có một mảng thông tin xác thực
create	{name, url, description?, projectUuid?, credentials?}	Env đã tạo (tùy chọn gieo thông tin xác thực)
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}	Env đã vá; các thao tác thông tin xác thực chạy theo thứ tự xóa → cập nhật → thêm
delete	{uuid, projectUuid?, confirm?}	Xóa env (xóa tầng thông tin xác thực) — yêu cầu xác nhận
sessions	{uuid, username?, credentialId?}	Các phiên đăng nhập đã thu thập mà env đang giữ, theo từng tài khoản, với isUsable và usableCount
clearSessions	{uuid, username?, credentialId?, confirm?}	Vô hiệu hóa chúng để lần chạy tiếp theo đăng nhập thực sự — xóa không phạm vi yêu cầu xác nhận

projectUuid tự động phân giải từ kho git khi bỏ trống. Các lỗi theo từng thông tin xác thực hiển thị trong credentialWarnings[] mà không chặn thao tác env.

sessions / clearSessions quản lý các phiên xác thực ấm mà backend tái sử dụng để bỏ qua đăng nhập (xem Tái sử dụng phiên). Nội dung phiên không bao giờ được trả về — cookie phiên là thông tin xác thực bearer. clearSessions đánh dấu phiên không hợp lệ thay vì xóa các hàng, để việc tái sử dụng dừng ngay lập tức trong khi lịch sử thu thập vẫn có thể đọc được.

test_suite

Hành động	Tham số	Kết quả
list	{projectUuid|projectName, search?, page?, pageSize?}	Danh sách bộ kiểm thử có phân trang kèm 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ả theo từng 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?}	Ca kiểm thử đã tạo (không tự động chạy)
update	{testUuid, name?, description?, agentTaskDescription?}	Ca 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 có phân trang

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 tùy chọn page (bắt đầu từ 1, mặc định 1) và pageSize (mặc định 20, tối đa 200; giá trị vượt quá sẽ bị kẹp). 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

Bên cạnh các công cụ, máy chủ còn 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 làm ngữ cảnh:

URI	Nội dung
debugg-ai://projects	Tất cả dự án (trang đầu)
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)
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 nội tuyến, mật khẩu được biên tập)
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

Việc đọc được điều phối đến cùng các trình xử lý như các công cụ project / environment / executions, nên dữ liệu và xác thực là 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 dùng các công cụ.

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

• Mật khẩu chỉ 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.
• URL đường hầm (*.ngrok.debugg.ai) bị loại bỏ khỏi mọi 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 viết.
• 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 ở 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 đã gộp 20 công cụ theo từng động từ thành 8 công cụ dựa trên hành động. Công cụ cũ → tool {action} mới:

Đã gỡ bỏ	Thay thế
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project, delete_project	Đã bỏ — 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"}
Tham số trigger_crawl headless	Đã bỏ — luôn headless

Các hành động delete giờ yêu cầu xác nhận (lời nhắc elicitation, hoặc confirm: true). Máy khách 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:

Đã gỡ bỏ	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 nội tuyến trên mỗi env
create_credential	create_environment({credentials: [...]}) seed, 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}) — phân giải 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 phản hồi danh sách đã biến mất — 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 gốc backend. Mặc định là https://api.debugg.ai.
DEBUGGAI_TOKEN_TYPE	không	token (mặc định) hoặc bearer.
DEBUGGAI_EVAL_TEMPLATE	không	Ghi đè slug quy trình Đánh giá Ứng dụng mà check_app_in_browser điều phối đến. Mặc định là flow/e2es/app-eval. Điều phối ghim vào slug này để việc đổi tên mẫu backend không thể phá vỡ nó.
LOG_LEVEL	không	error / warn / info (mặc định) / debug.
POSTHOG_API_KEY	không	Ghi đè khóa dự án telemetry nhúng (ví dụ: fork riêng tư).
DEBUGGAI_TELEMETRY_DISABLED	không	Đặt thành 1 / true / yes / on để tắt telemetry hoàn toàn.

DEBUGGAI_API_KEY=your_api_key

Truyền tải từ xa / HTTP (tùy chọn)

Theo mặc định, máy chủ nói stdio (npx cục bộ). Thay vào đó, nó có thể chạy như một MCP từ xa đa người dùng được lưu trữ qua Streamable HTTP 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

Nó là một Máy chủ Tài nguyên OAuth: mọi POST /mcp cần Authorization: Bearer <token>; token thiếu/không hợp lệ nhận 401 với WWW-Authenticate trỏ đến siêu dữ liệu RFC 9728, và máy khách chạy luồng OAuth chống lại máy chủ ủy quyền được quảng cáo. 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 (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 bộ cân bằng tải / 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 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 cáo cho máy khách
DEBUGGAI_TOKEN_TYPE	token	Đặt thành bearer để token OAuth chuyển tiếp dưới dạng Authorization: Bearer

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

Triển khai nhiều bản sao (go/no-go trước khi phát hành): trạng thái đường hầm (phiên đường hầm ngrok, phiên bản Caddy của nó, và khóa định tuyến cổng của nó) nằm trong tiến trình, khóa theo từng người gọi bằng hàm băm của token bearer — không có sự phối hợp giữa các tiến trình. Chạy nhiều bản sao sau một bộ cân bằng tải round-robin đơn giản nghĩa là các cuộc gọi của một người có thể rơi vào các bản sao khác nhau và tạo một đường hầm cho mỗi bản sao họ chạm vào thay vì một cho toàn bộ phiên (chi phí ngrok thêm, giới hạn bởi số bản sao, tự phục hồi qua cơ chế tự tắt sau 55 phút không hoạt động hiện có — không bao giờ là lỗi đúng sai giữa các phiên, vì bất kỳ cuộc gọi công cụ đơn lẻ nào vẫn ở trên một bản sao trong suốt thời gian của nó). Để có hành vi "một đường hầm mỗi phiên" như dự định trên triển khai HTTP nhiều bản sao, hãy cấu hình định tuyến theo phiên tại bộ cân bằng tải (băm dính/đồng nhất khóa theo cùng danh tính mà getSessionKey() suy ra — trong thực tế, token bearer Authorization của người gọi). Xem docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 để biết lý do đầy đủ và đường suy giảm trung thực nếu điều này không được cấu hình.

Telemetry

Máy chủ MCP đi kèm với telemetry đượ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 đường hầm, và các chỉ số vận hành khác trên cơ sở cài đặt. Các sự kiện được thu thập:

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 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 trên cuộc gọi nguội

Lập trường quyền riêng tư:

• ID riêng 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 trong mã nguồn.
• Đặt DEBUGGAI_TELEMETRY_DISABLED=1 để từ chối hoàn toàn (phân giải thành nhà cung cấp no-op; không có sự kiện nào rời khỏi tiến trình).

Chế độ hoạt động được ghi nhật ký 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 chạy máy chủ MCP đã xây dựng dưới dạng tiến trình con, thực thi mọi công cụ chống lại 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

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

Các dự án khác của bạn nên dùng đăng ký debugg-ai có phạm vi người dùng kéo 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ỉ xây dựng lại) để lần gọi tiếp theo của debugg-ai-local nhận 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

---

Giấy phép Apache-2.0 © 2025 DebuggAI