Debugg AI

Debugg AI — MCP Server

Pengujian browser bertenaga AI melalui Model Context Protocol. Arahkan ke URL apa pun (atau localhost) dan jelaskan apa yang ingin diuji — agen AI menjelajahi aplikasi Anda dan mengembalikan hasil lulus/gagal beserta tangkapan layar.

Pengaturan

Membutuhkan Node.js 20.20.0 atau lebih baru (persyaratan turunan dari posthog-node@^5.26.0).

Pengujian URL http://localhost:... membutuhkan biner caddy — check_app_in_browser, probe_page, dan trigger_crawl membuat terowongan target localhost melalui proxy balik Caddy lokal. Ini terinstal secara otomatis: dependensi npm @radically-straightforward/caddy mengunduh rilis Caddy yang disematkan untuk platform Anda selama npm install/npx — tidak perlu menginstal apa pun sendiri dalam kasus normal. Ini sekarang menjadi satu-satunya biner yang diunduh paket ini; klien terowongan itu sendiri murni TypeScript — ini menggantikan paket ngrok, yang mengambil agen ngrok. Jika unduhan itu tidak pernah berjalan (npm install --ignore-scripts, instalasi offline/terisolasi), arahkan CADDY_BIN ke instalasi Anda sendiri (brew install caddy / apt install caddy / lihat caddyserver.com/docs/install) — ketiadaannya muncul sebagai kesalahan yang jelas pada panggilan URL localhost pertama, bukan hang yang diam-diam. Panggilan URL publik, setiap alat non-browser, dan test_suite {action:"run"} (yang menggunakan terowongan khusus sendiri dan sepenuhnya melewati Caddy) tidak membutuhkannya juga.

Dapatkan kunci API di debugg.ai, lalu tambahkan ke konfigurasi klien MCP Anda:

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

Atau dengan Docker:

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

Langkah npm install dari Dockerfile akan mengambil caddy dengan cara otomatis yang sama seperti instalasi lokal lakukan, pada prinsipnya — tetapi pada saat penulisan ini, Dockerfile tidak COPY beberapa direktori yang dibutuhkan build sekarang (handlers, tools, types, config) dan masih merujuk ke direktori tunnels/ yang tidak lagi ada, jadi build baru kemungkinan gagal sebelum itu menjadi masalah. Itu celah yang sudah ada sebelumnya, tidak terkait dengan Caddy. Yang saat ini diterbitkan gambar quinnosha/debugg-ai-mcp mendahului dependensi Caddy — panggilan URL localhost ke check_app_in_browser/probe_page/trigger_crawl akan gagal dengan CaddyBinaryNotFoundError di dalam gambar itu sampai dibangun ulang (Dockerfile diperbaiki) dan diterbitkan ulang, atau CADDY_BIN menunjuk ke satu yang disertakan secara terpisah. Panggilan URL publik, alat non-browser, dan test_suite {action:"run"} tidak terpengaruh.

Alat

Server mengekspos 8 alat: tiga alat Browser plus satu alat berbasis tindakan per entitas yang dikelola. Alat utama adalah check_app_in_browser (agen AI penuh) dan probe_page (probe halaman ringan tanpa LLM). Sisanya — project, environment, test_suite, test_case, executions — masing-masing mengambil diskriminator action (misalnya {"action":"list"}) yang memilih operasi. Tindakan delete yang merusak memerlukan konfirmasi (prompt elisitasi jika didukung, jika tidak confirm: true).

Browser

check_app_in_browser

Menjalankan agen browser AI terhadap aplikasi Anda. Agen menavigasi, berinteraksi, dan melaporkan kembali dengan tangkapan layar. URL localhost secara otomatis diterowongkan melalui server terowongan debugg.

Parameter	Tipe	Deskripsi
description	string wajib	Apa yang akan diuji (bahasa alami)
url	string wajib	URL target — http://localhost:3000 diterowongkan otomatis
environmentId	string	UUID dari lingkungan tertentu
credentialId	string	UUID dari kredensial tertentu
credentialRole	string	Pilih kredensial berdasarkan peran (misalnya admin, guest)
username	string	Nama pengguna untuk login (sementara — tidak disimpan)
password	string	Kata sandi untuk login (sementara — tidak disimpan)
loginCredentials	array	Akun untuk login yang ditemui agen selama tugas — [{username, password, label?}]
useEnvironmentCredentials	boolean	Default true. false melarang pengisian otomatis kredensial tersimpan lingkungan; tanpa akun yang disebutkan berarti jangan login sama sekali
freshSession	boolean	Default false. true memaksa login sungguhan alih-alih menggunakan kembali sesi hangat yang dipegang untuk akun itu
auth	objek	Prasyarat autentikasi — {precondition, entryUrl, deepUrl, environmentId, username, password}
repoName	string	Menimpa nama repositori git yang terdeteksi otomatis (misalnya my-org/my-repo)

Satu pemeriksaan terfokus per panggilan. Agen memiliki anggaran internal ~25 langkah; bagi rangkaian yang lebih luas ke beberapa panggilan.

Kredensial: berikan sebagai parameter, bukan prosa

Menyebutkan akun hanya di description tidak membuat agen menggunakannya — agen kembali ke kredensial tersimpan lingkungan, dan penolakan aplikasi terhadap akun yang salah terlihat seperti kegagalan aplikasi. Apa pun yang Anda berikan sebagai parameter mengalahkan default lingkungan untuk setiap login dalam proses, bukan hanya yang pertama:

• username / password (atau credentialId / credentialRole) — identitas proses.
• auth.username / auth.password — mengunci login prasyarat saat Anda juga menggunakan auth.precondition: "login".
• loginCredentials — akun untuk formulir login yang ditemui agen di tengah tugas. Ini yang untuk alur seperti atur kata sandi → dialihkan ke masuk → login sebagai akun yang baru Anda buat, di mana memisahkan ke panggilan terpisah akan kehilangan status browser.

Setel useEnvironmentCredentials: false saat fallback diam-diam ke pengguna uji default akan membatalkan pemeriksaan.

SSO lintas domain? Proses hanya mengetik kredensial di host aplikasi sendiri dan subdomainnya; halaman masuk di domain lain ditolak sebagai offscope_host. Tambahkan host penyedia identitas ke authorizedCredentialHosts lingkungan (lihat environment).

Memeriksa halaman yang tidak memerlukan login sama sekali? Berikan useEnvironmentCredentials: false dan jangan sebutkan akun. Kombinasi itu berarti persis seperti yang dikatakan — jangan login — dan proses melewati autentikasi sepenuhnya alih-alih mencari formulir login. Gunakan untuk halaman publik, situs pemasaran, dokumentasi, dan apa pun sebelum autentikasi. Ini juga lebih cepat: pada default (auto) agen akan mengikuti tautan "Masuk" dari halaman Anda dan mencoba akun tersimpan lingkungan sebelum mengevaluasi apa pun.

Penggunaan kembali sesi: mengapa pemeriksaan melaporkan "tidak ada formulir login"

Proses tidak login setiap saat. Setelah login terverifikasi, backend menangkap sesi akun itu dan memulihkannya pada proses berikutnya untuk identitas yang sama, yang melewati login sepenuhnya — itulah mengapa pemeriksaan dapat dengan sah kembali dengan submitted: false dan tanpa formulir login: sudah masuk. Proses yang dipulihkan melaporkan dirinya di logins dengan reason: "restored_session", sehingga Anda dapat membedakannya dari proses yang benar-benar tidak menemukan formulir.

Sesi dikunci per akun, jadi menyebutkan akun berbeda tidak pernah menggunakan kembali milik orang lain. Dua cara untuk melewati penggunaan kembali:

• freshSession: true pada satu panggilan — login sungguhan sekali ini, lalu tangkap ulang. Gunakan saat alur login adalah yang Anda periksa, saat Anda mencurigai sesi tersimpan basi, atau saat satu-satunya rute aplikasi antar persona adalah logout.
• Alat environment, action: "clearSessions" — batalkan sesi tersimpan sehingga proses berikutnya login. Persempit dengan username / credentialId; pembersihan tanpa cakupan memerlukan konfirmasi karena setiap akun di lingkungan kemudian mengautentikasi ulang.

Gunakan action: "sessions" untuk melihat apa yang saat ini dipegang lingkungan dan apakah masing-masing akan digunakan kembali.

Hasil melaporkan identitas yang benar-benar digunakan, sehingga yang salah terlihat alih-alih menyamar sebagai aplikasi rusak:

"logins": [
  { "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true },
  { "username": "qatest123@example.com", "source": "env_default", "submitted": false, "authenticated": false,
    "reason": "offscope_host", "detail": "refused to enter credentials on auth.idp.example: not part of this run's scope …" }
],
"credentialWarning": {
  "requested": "qa+invitefix@example.com",
  "used": ["qatest123@example.com"]
}

source adalah task | explicit | credential_id (akun yang Anda sebutkan) atau env | env_default (akun tersimpan lingkungan). submitted benar hanya saat kredensial benar-benar diketik dan dikirimkan; reason mengatakan apa yang terjadi (misalnya offscope_host, restored_session), dan detail, saat ada, adalah penjelasan yang dapat dibaca manusia — untuk penolakan offscope_host ia menyebutkan host dan cara mengotorisasinya. credentialWarning muncul hanya saat Anda menyebutkan akun dan default lingkungan untuk akun berbeda benar-benar dikirimkan — tidak pernah untuk login yang ditolak atau dilewati. loginError muncul saat akun yang disebutkan tidak dapat diselesaikan dan proses menolak untuk mengganti dengan yang berbeda.

Setiap proses yang berhasil mengembalikan blok browserSession di samping tangkapan layar — URL S3 yang telah ditandatangani sebelumnya untuk HAR yang ditangkap (jejak jaringan lengkap) dan log konsol (setiap pesan konsol JS). Gunakan untuk mendeteksi loop pengambilan ulang, kesalahan hidrasi, dan masalah runtime lain yang lolos pemeriksaan tipe dan pengujian unit:

"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 berumur pendek S3 yang telah ditandatangani sebelumnya — ambil ulang eksekusi induk melalui executions {action:"get", uuid} untuk memperbarui. harStatus / consoleLogStatus membedakan 'downloaded' (URL dapat diambil), 'not_available' (halaman tidak mengeluarkan apa pun), 'failed' (penangkapan rusak). Pada proses baru, URL biasanya null karena penangkapan diunggah asinkron setelah agen selesai — polling executions {action:"get", uuid: executionId} hingga status mencapai 'downloaded'. Header Otorisasi / Cookie / token/secret/api_key dibersihkan di sisi server sebelum artefak disimpan.

trigger_crawl

Memicu perayapan agen browser sisi server untuk mengisi grafik pengetahuan proyek. URL localhost diterowongkan otomatis. Mengembalikan {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} dengan knowledgeGraph.skipped === false pada penyerapan yang berhasil. crawlSummary dan knowledgeGraph hanya membawa kunci yang dilaporkan node perayapan/impor backend — jumlah yang hilang tidak ada, tidak pernah diisi dengan 0. Blok browserSession (URL HAR + log konsol, bentuk yang sama seperti di atas) juga ada pada perayapan yang selesai.

probe_page

Probe halaman batch ringan tanpa LLM. Berikan 1-20 URL; masing-masing menavigasi, menetap pada konten (DOM menjadi tenang, terbatas — tidak pernah pada keheningan jaringan, yang tidak pernah dicapai aplikasi langsung), dan mengembalikan status yang dirender — tangkapan layar + metadata halaman + kesalahan konsol terstruktur + ringkasan jaringan. Tidak ada loop agen, tidak ada biaya LLM, tidak ada asersi skenario. Gunakan untuk "apakah saya baru saja merusak /settings?", pemeriksaan asap multi-rute setelah refaktor, sapuan per-PR di CI, dan pemeriksaan cepat apakah aktif di mana loop agen 60-150 detik check_app_in_browser berlebihan.

Parameter	Tipe	Deskripsi
targets	array wajib	1-20 entri: [{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	string wajib	URL publik atau localhost (diterowongkan otomatis)
targets[].waitForLoadState	enum	'domcontentloaded' (default, + penenangan konten terbatas) / 'load' (juga menunggu embed pihak ketiga) / 'networkidle' (diterima, tidak pernah dikeluarkan — jaringan situs langsung tidak menjadi idle)
targets[].waitForSelector	string	Selektor CSS opsional untuk menunggu setelah navigasi
targets[].timeoutMs	angka	Batas waktu per URL, 1000-30000 (default 10000)
includeHtml	boolean	Mengembalikan HTML mentah di setiap hasil (default false)
captureScreenshots	boolean	Mengembalikan satu PNG per target (default true)

Semua target dalam satu batch berbagi satu sesi terowongan, tetapi hanya batch dengan port yang sama (atau semua publik) yang berbagi satu eksekusi backend — 5 URL pada satu port dalam satu panggilan jauh lebih cepat daripada 5 panggilan paralel satu URL. Batch yang mencampur beberapa port lokal terurai menjadi satu eksekusi backend berurutan per grup port (tetap satu panggilan, tetap satu results[] yang digabungkan dalam urutan asli Anda, tetapi N perjalanan pulang-pergi backend alih-alih satu — lebih lambat, tidak ditolak). Bidang error per URL mempertahankan ketahanan batch: satu target yang gagal tidak menggagalkan yang lain. Kunci agregasi networkSummary adalah origin + pathname — loop pengambilan ulang (?n=0..4 yang berulang kali memanggil endpoint yang sama) menyatu menjadi satu entri dengan jumlahnya, sehingga /api/poll yang muncul dengan count: 47 adalah sinyal "loop pengambilan ulang tak terbatas" yang dapat ditindaklanjuti seperti yang diminta pengguna.

Anggaran performa: <10 detik untuk 1 URL, <25 detik untuk 20. Port mati di localhost mengembalikan LocalServerUnreachable dalam <2 detik tanpa menghabiskan eksekusi workflow.

project

Aksi	Parameter	Hasil
get	{uuid}	Detail proyek yang dikurasi
list	{q?, page?, pageSize?}	Ringkasan berpagina
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	Proyek yang dibuat

Tim dan repositori diselesaikan dengan uuid atau nama (pencocokan tepat tanpa membedakan huruf besar/kecil; NotFound jika tidak ada, AmbiguousMatch jika ada banyak). Tidak ada update/delete — ganti nama atau hapus proyek dari aplikasi web DebuggAI.

environment

Aksi	Parameter	Hasil
get	{uuid, projectUuid?}	Env dengan kredensial yang disisipkan (kata sandi tidak pernah dikembalikan)
list	{projectUuid?, q?, page?, pageSize?}	Env berpagina, masing-masing dengan array kredensial
create	{name, url, description?, projectUuid?, credentials?, authorizedCredentialHosts?}	Env yang dibuat (opsional mengisi kredensial awal)
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?}	Env yang di-patch; operasi kredensial berjalan hapus → perbarui → tambah
delete	{uuid, projectUuid?, confirm?}	Menghapus env (menghapus kredensial secara berjenjang) — memerlukan konfirmasi
sessions	{uuid, username?, credentialId?}	Sesi login yang ditangkap yang dimiliki env, per akun, masing-masing dengan isUsable sendiri
clearSessions	{uuid, username?, credentialId?, confirm?}	Membatalkannya sehingga proses berikutnya login sungguhan — penghapusan tanpa lingkup memerlukan konfirmasi

projectUuid ter-resolve otomatis dari repositori git jika dihilangkan. Kegagalan per-kredensial muncul di credentialWarnings[] tanpa memblokir operasi env.

authorizedCredentialHosts mencantumkan host tempat proses dapat memasukkan kredensial lingkungan ini selain host aplikasi itu sendiri — untuk SSO lintas domain, tambahkan host IdP di sini (misalnya ["auth.example.com"]). Hanya nama host polos: tanpa skema, jalur, port, atau wildcard (subdomain dari host aplikasi sudah tercakup). Pada update daftar tersebut diganti; [] menghapusnya. get/list mengembalikannya jika server mendukungnya. Respons menggema daftar yang disimpan; jika server tidak menyimpannya (server lama mengabaikan kolom ini), hasilnya membawa authorizedCredentialHostsWarning: {requested, returned} alih-alih keberhasilan senyap.

sessions / clearSessions mengelola sesi terautentikasi hangat yang digunakan ulang backend untuk melewati login (lihat Penggunaan ulang sesi). Isi sesi tidak pernah dikembalikan — cookie sesi adalah kredensial bearer. clearSessions menandai sesi sebagai tidak valid alih-alih menghapus barisnya, sehingga penggunaan ulang berhenti segera sementara riwayat tangkapan tetap dapat dibaca.

test_suite

Aksi	Parameter	Hasil
list	{projectUuid|projectName, search?, page?, pageSize?}	Rangkaian berpagina dengan status + tingkat kelulusan
create	{name, description, projectUuid|projectName}	Rangkaian yang dibuat
run	{suiteUuid|(suiteName+project), targetUrl?}	Memicu semua pengujian secara asinkron
results	{suiteUuid|(suiteName+project)}	Rangkaian + hasil per-pengujian
delete	{suiteUuid|(suiteName+project), confirm?}	Penghapusan lunak — memerlukan konfirmasi

test_case

Aksi	Parameter	Hasil
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	Kasus uji yang dibuat (tidak dijalankan otomatis)
update	{testUuid, name?, description?, agentTaskDescription?}	Kasus uji yang di-patch
delete	{testUuid, confirm?}	Penghapusan lunak — memerlukan konfirmasi

executions

Aksi	Parameter	Hasil
get	{uuid}	Detail lengkap (nodeExecutions + status + errorInfo) + artefak tangkapan layar/gif
list	{status?, projectUuid?, page?, pageSize?}	Ringkasan berpagina

404 dari backend muncul sebagai isError: true dengan {error: 'NotFound', message, uuid}. Kredensial selalu dikembalikan tanpa kata sandi.

Paginasi

Setiap respons list dipaginasi. Bentuk respons:

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

Berikan page opsional (berindeks 1, default 1) dan pageSize (default 20, maks 200; nilai berlebihan dijepit). Tidak ada respons yang pernah dipotong secara senyap.

get mengembalikan satu objek di bawah nama tunggalnya — {project}, {execution}, {project, environment} — tanpa pageInfo.

Sumber Daya

Selain alat, server mengekspos entitas hanya-baca sebagai sumber daya MCP sehingga klien dapat menjelajah dan menyebutnya dengan @ sebagai konteks:

URI	Isi
debugg-ai://projects	Semua proyek (halaman pertama)
debugg-ai://environments	Lingkungan untuk proyek yang terdeteksi otomatis
debugg-ai://executions	Eksekusi terbaru (halaman pertama)
debugg-ai://project/{uuid}	Satu proyek, detail lengkap
debugg-ai://environment/{uuid}	Satu lingkungan (kredensial disisipkan, kata sandi disunting)
debugg-ai://execution/{uuid}	Satu eksekusi, detail node lengkap + tautan artefak

Pembacaan mengirim ke penangan yang sama dengan alat project / environment / executions, sehingga data dan autentikasi identik. Sumber daya bersifat aditif — klien tanpa dukungan sumber daya tetap menggunakan alat.

Invariants keamanan

• Kata sandi hanya-tulis. Kata sandi tidak pernah muncul di badan respons mana pun dari alat apa pun.
• URL terowongan (*.tunnel.debugg.ai, dan *.ngrok.debugg.ai yang sudah pensiun yang masih dirujuk proses historis) dihapus dari semua respons agen peramban, termasuk teks yang ditulis agen.
• 404 dari backend muncul sebagai isError: true dengan {error: 'NotFound', ...}, tidak pernah sebagai pengecualian yang dilempar.
• DEBUGGAI_API_KEY yang hilang muncul sebagai kesalahan alat terstruktur pada pemanggilan pertama — server tetap mendaftar dan mencantumkan alat secara normal.

Migrasi ke v6.0.0 (vonis backend, tanpa teks yang ditulis MCP)

Vonis proses adalah pass | fail | error, dengan reason backend diteruskan apa adanya. Proses yang tidak pernah mencoba pengujian terbaca sebagai outcome: null, skipped: true, skipReason.

Dihapus	Pengganti
success	outcome
failureCategory	outcome + reason
stepsTaken / stepsBudget / stepsRemaining	budget: {maxSteps, usedSteps}
failedNode	errorInfo
get → projects[0] / executions[0] / environments[0] + pageInfo + filter	{project} / {execution} / {project, environment}
message / note pada peringatan dan hasil	hanya kolom terstruktur

Daftar lengkap: CHANGELOG.md 6.0.0.

Migrasi ke v3.0.0 (alat berbasis aksi)

v3 menggabungkan 20 alat per-kata kerja menjadi 8 alat berbasis aksi. Alat lama → tool {action} baru:

Dihapus	Pengganti
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project, delete_project	Dihapus — gunakan aplikasi 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 parameter headless	Dihapus — selalu headless

Aksi delete kini memerlukan konfirmasi (prompt elisitasi, atau confirm: true). Klien mengambil permukaan baru saat MCP dimulai ulang.

Migrasi dari v1.x (perubahan besar di v2.0.0)

v2 menggabungkan permukaan 22 alat menjadi 11. Pemetaan alat lama → alat baru:

Dihapus	Pengganti
list_projects, get_project	search_projects (mode uuid vs mode filter)
list_environments, get_environment	search_environments
list_credentials, get_credential	search_environments — kredensial disisipkan di setiap env
create_credential	create_environment({credentials: [...]}) seed, atau update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams, list_repos	create_project({teamName, repoName}) — resolusi nama dengan penanganan ambiguitas
list_executions, get_execution	search_executions
cancel_execution	Dihapus — penonaktifan backend bersifat otomatis

Perubahan bentuk respons: kolom count polos pada respons daftar telah hilang — gunakan pageInfo.totalCount.

Konfigurasi

Variabel env	Diperlukan	Tujuan
DEBUGGAI_API_KEY	ya	Kunci API backend. Alias: DEBUGGAI_API_TOKEN, DEBUGGAI_JWT_TOKEN.
DEBUGGAI_API_URL	tidak	URL dasar backend. Default ke https://api.debugg.ai.
DEBUGGAI_TOKEN_TYPE	tidak	token (default) atau bearer.
DEBUGGAI_EVAL_TEMPLATE	tidak	Menimpa slug workflow Evaluasi Aplikasi yang dituju check_app_in_browser. Default ke flow/e2es/app-eval. Pengiriman mengunci slug ini sehingga penggantian nama templat backend tidak dapat merusaknya.
LOG_LEVEL	tidak	error / warn / info (default) / debug.
POSTHOG_API_KEY	tidak	Menimpa kunci proyek telemetri yang disematkan (misalnya fork pribadi).
DEBUGGAI_TELEMETRY_DISABLED	tidak	Setel ke 1 / true / yes / on untuk menonaktifkan telemetri sepenuhnya.

DEBUGGAI_API_KEY=your_api_key

Transport HTTP / jarak jauh (opsional)

Secara default server berbicara stdio (npx lokal). Server juga dapat berjalan sebagai MCP jarak jauh multi-pengguna yang dihosting melalui Streamable HTTP tanpa status + OAuth:

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

Ini adalah Resource Server OAuth: setiap POST /mcp memerlukan Authorization: Bearer <token>; token yang hilang/tidak valid mendapatkan 401 dengan WWW-Authenticate yang menunjuk ke metadata RFC 9728, dan klien menjalankan alur OAuth terhadap server otorisasi yang diiklankan. Bearer bersifat lingkup-permintaan — api.debugg.ai memvalidasinya.

Endpoint	Tujuan
POST /mcp	MCP Streamable HTTP (dilindungi bearer)
GET /.well-known/oauth-protected-resource	Metadata RFC 9728 (penemuan server otorisasi)
GET /health	Pemeriksaan kesehatan penyeimbang beban / ECS

Variabel env	Default	Tujuan
DEBUGGAI_MCP_TRANSPORT	stdio	Setel ke http untuk transport jarak jauh
PORT	3000	Port listen HTTP
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	URL sumber daya publik server ini (RFC 9728 resource)
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	Server otorisasi yang diiklankan ke klien
DEBUGGAI_TOKEN_TYPE	token	Setel ke bearer sehingga token OAuth diteruskan sebagai Authorization: Bearer

Instalasi stdio tidak memerlukan semua ini.

Penerapan multi-replika (go/no-go sebelum peluncuran): status terowongan (terowongan sesi, instance Caddy-nya, dan kunci rute port-nya) berada dalam proses, dikunci per pemanggil oleh hash token bearer — tidak ada koordinasi lintas proses. Menjalankan beberapa replika di belakang penyeimbang beban round-robin biasa berarti panggilan satu pemanggil dapat mendarat di replika berbeda dan membuat satu terowongan per replika yang mereka sentuh alih-alih satu untuk seluruh sesi (dibatasi oleh jumlah replika, menyembuhkan diri melalui penghentian otomatis 55 menit yang ada — tidak pernah menjadi bug kebenaran lintas sesi, karena setiap panggilan alat tunggal tetap di satu replika selama durasinya). Untuk mendapatkan perilaku "satu terowongan per sesi" yang dimaksud pada penerapan HTTP multi-replika, konfigurasikan routing afinitas sesi di penyeimbang beban (hash lengket/konsisten yang dikunci pada identitas yang sama yang diturunkan getSessionKey() — dalam praktiknya, token bearer Authorization pemanggil). Lihat docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 untuk alasan lengkap dan jalur degradasi yang jujur jika ini tidak dikonfigurasi.

Telemetri

Server MCP dikirim dengan telemetri yang diaktifkan secara default — kunci PostHog tertanam yang hanya dapat ditulis (phc_*) sehingga tim dapat mengamati tingkat cache hit, irama polling, keandalan tunnel, dan metrik operasional lainnya di seluruh basis instalasi. Peristiwa yang ditangkap:

Peristiwa	Kapan
tool.executed / tool.failed	Per panggilan alat
workflow.executed	Per eksekusi agen browser (membawa pollCount, durationMs, finalIntervalMs)
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	Per peristiwa siklus hidup tunnel
template.lookup / project.lookup	Cache hit/miss dengan durationMs pada panggilan dingin

Postur privasi:

• ID yang berbeda adalah SHA-256(api_key).slice(0, 16) — tidak pernah kunci mentah, tanpa PII.
• Kunci phc_* hanya dapat ditulis sesuai konvensi PostHog; aman untuk disematkan di sumber.
• Atur DEBUGGAI_TELEMETRY_DISABLED=1 untuk memilih keluar sepenuhnya (menyelesaikan ke penyedia tanpa operasi; tidak ada peristiwa yang meninggalkan proses).

Mode aktif dicatat saat boot:

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)

Pengembangan Lokal

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

Suite eval memunculkan server MCP yang dibangun sebagai subproses, menjalankan setiap alat terhadap backend nyata, dan menulis artefak per-alur ke scripts/evals/artifacts/<timestamp>/. Lihat scripts/evals/flows/ untuk skenario individual.

Registrasi MCP: debugg-ai-local vs debugg-ai

Repo ini mengirimkan .mcp.json yang mendaftarkan server bercakupan proyek bernama debugg-ai-local yang menunjuk ke node dist/index.js — kode lokal yang baru dibangun. Ini hanya aktif ketika direktori kerja Claude Code adalah repo ini.

Proyek lain Anda harus menggunakan registrasi debugg-ai bercakupan pengguna yang menarik dari paket npm yang diterbitkan:

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

Setelah mengedit kode di sini, jalankan npm run mcp:local (yang hanya membangun ulang) sehingga pemanggilan berikutnya dari debugg-ai-local mengambil perubahan Anda.

Tautan

Dashboard · Dokumen · Masalah · Discord

---

Lisensi Apache-2.0 © 2025 DebuggAI