Debugg AI

resmi

Memungkinkan agen pembuat kode Anda untuk membuat dan menjalankan pengujian ujung-ke-ujung tanpa konfigurasi terhadap perubahan kode baru di peramban jarak jauh melalui platform pengujian Debugg AI.

GitHub

Apa yang bisa Anda lakukan dengan Debugg AI MCP?

Jalankan agen browser AI terhadap URL apa pun — deskripsikan apa yang akan diuji dalam bahasa alami dan check_app_in_browser akan menavigasi, berinteraksi, dan mengembalikan hasil lulus/gagal beserta tangkapan layar.
Probe beberapa halaman tanpa biaya LLM — kirim hingga 20 URL ke probe_page untuk tangkapan layar cepat, error konsol, dan ringkasan jaringan dalam satu batch.
Picu perayapan knowledge graph — gunakan trigger_crawl untuk meminta agen AI menjelajahi aplikasi Anda dan mengisi knowledge graph proyek.
Kelola rangkaian pengujian dan kasus — buat, daftar, jalankan, dan periksa hasil rangkaian pengujian melalui test_suite, serta tentukan kasus individual dengan test_case.
Periksa artefak eksekusi — ambil detail eksekusi lengkap, tangkapan layar, jejak HAR, dan log konsol melalui executions untuk men-debug kegagalan.
Jelajahi proyek, lingkungan, dan eksekusi sebagai sumber daya — rujuk entitas secara langsung melalui URI debugg-ai:// untuk konteks tanpa memanggil alat.

Dokumentasi

Debugg AI — Server MCP

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

Penyiapan

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

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

Alat

Server menyediakan 8 alat: tiga alat Browser ditambah satu alat berbasis aksi per entitas terkelola. Alat utamanya adalah check_app_in_browser (agen AI penuh) dan probe_page (pemeriksa halaman ringan tanpa LLM). Sisanya — project, environment, test_suite, test_case, executions — masing-masing menerima diskriminator action (mis. {"action":"list"}) yang memilih operasi. Aksi destruktif delete memerlukan konfirmasi (prompt elisitasi jika didukung, jika tidak confirm: true).

Browser

`check_app_in_browser`

Menjalankan agen browser AI terhadap aplikasi Anda. Agen bernavigasi, berinteraksi, dan melaporkan kembali dengan tangkapan layar. URL localhost otomatis diterowongkan melalui ngrok.

Parameter	Tipe	Deskripsi
`description`	string wajib	Apa yang akan diuji (bahasa alami)
`url`	string wajib	URL target — `http://localhost:3000` otomatis diterowongkan
`environmentId`	string	UUID lingkungan tertentu
`credentialId`	string	UUID kredensial tertentu
`credentialRole`	string	Pilih kredensial berdasarkan peran (mis. `admin`, `guest`)
`username`	string	Nama pengguna untuk login (sementara — tidak disimpan)
`password`	string	Kata sandi untuk login (sementara — tidak disimpan)
`repoName`	string	Timpa nama repo git yang terdeteksi otomatis (mis. `my-org/my-repo`)

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

Setiap eksekusi yang berhasil mengembalikan blok browserSession bersama 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 lainnya 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 adalah S3 yang telah ditandatangani sebelumnya dengan masa berlaku singkat — 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 gagal). Pada eksekusi baru, URL biasanya null karena unggahan penangkapan berjalan 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`

Menjalankan perayapan agen browser sisi server untuk mengisi grafik pengetahuan proyek. URL localhost otomatis diterowongkan. Mengembalikan {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} dengan knowledgeGraph.imported === true saat penyerapan berhasil. Blok browserSession (URL HAR + log konsol, bentuknya sama seperti di atas) juga ada pada perayapan yang selesai.

`probe_page`

Pemeriksa halaman batch ringan tanpa LLM. Berikan 1-20 URL; masing-masing bernavigasi, menunggu muat, dan mengembalikan status yang dirender — tangkapan layar + metadata halaman + kesalahan konsol terstruktur + ringkasan jaringan. Tanpa loop agen, tanpa biaya LLM, tanpa asersi skenario. Gunakan untuk "apakah saya baru saja merusak /settings?", pemeriksaan asap multi-rute setelah refaktor, sapuan per-PR CI, dan pemeriksaan cepat apakah sudah aktif di mana check_app_in_browser dengan loop agen 60-150 detik terlalu 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	`'load'` (default) / `'domcontentloaded'` / `'networkidle'`
`targets[].waitForSelector`	string	Selektor CSS opsional untuk ditunggu setelah navigasi
`targets[].timeoutMs`	number	Batas waktu per URL, 1000-30000 (default 10000)
`includeHtml`	boolean	Kembalikan HTML mentah di setiap hasil (default false)
`captureScreenshots`	boolean	Kembalikan satu PNG per target (default true)

Seluruh batch berbagi satu eksekusi backend + sesi browser + terowongan — 5 URL dalam satu panggilan jauh lebih cepat daripada 5 panggilan URL tunggal paralel. Bidang error per URL menjaga ketahanan batch: satu target yang gagal tidak menggagalkan yang lain.

Kunci agregasi networkSummary adalah origin + pathname — loop pengambilan ulang (?n=0..4 berulang kali mengenai endpoint yang sama) diciutkan menjadi satu entri dengan jumlah, sehingga /api/poll muncul dengan count: 47 adalah sinyal "loop pengambilan ulang tak terbatas" yang dapat ditindaklanjuti yang semula diminta pengguna.

Anggaran kinerja: <10 detik untuk 1 URL, <25 detik untuk 20. Port mati localhost mengembalikan LocalServerUnreachable dalam <2 detik tanpa membakar eksekusi alur kerja.

`project`

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

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

`environment`

Aksi	Parameter	Hasil
`get`	`{uuid, projectUuid?}`	Lingkungan dengan kredensial sebaris (kata sandi tidak pernah dikembalikan)
`list`	`{projectUuid?, q?, page?, pageSize?}`	Lingkungan terhalaman, masing-masing dengan array kredensial
`create`	`{name, url, description?, projectUuid?, credentials?}`	Lingkungan dibuat (opsional menyemai kredensial)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	Lingkungan ditambal; operasi kredensial berjalan hapus → perbarui → tambah
`delete`	`{uuid, projectUuid?, confirm?}`	Menghapus lingkungan (mengalir ke kredensial) — memerlukan konfirmasi

projectUuid otomatis diselesaikan dari repo git jika dihilangkan. Kegagalan per kredensial muncul di credentialWarnings[] tanpa memblokir operasi lingkungan.

`test_suite`

Aksi	Parameter	Hasil
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	Rangkaian pengujian terhalaman dengan status + tingkat kelulusan
`create`	`{name, description, projectUuid\|projectName}`	Rangkaian pengujian dibuat
`run`	`{suiteUuid\|(suiteName+project), targetUrl?}`	Memicu semua pengujian secara asinkron
`results`	`{suiteUuid\|(suiteName+project)}`	Rangkaian pengujian + 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 dibuat (tidak otomatis dijalankan)
`update`	`{testUuid, name?, description?, agentTaskDescription?}`	Kasus uji ditambal
`delete`	`{testUuid, confirm?}`	Penghapusan lunak — memerlukan konfirmasi

`executions`

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

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

Penomoran Halaman

Setiap respons mode filter dihalaman. Bentuk respons:

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

Berikan opsional page (berindeks 1, default 1) dan pageSize (default 20, maks 200; nilai yang terlalu besar akan dijepit). Tidak ada respons yang dipotong secara diam-diam.

Sumber Daya

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

URI	Apa
`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 sebaris, kata sandi disunting)
`debugg-ai://execution/{uuid}`	Satu eksekusi, detail simpul lengkap + tautan artefak

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

Invarian keamanan

Kata sandi hanya-tulis. Tidak pernah muncul di badan respons apa pun dari alat apa pun.
URL terowongan (*.ngrok.debugg.ai) dihapus dari semua respons agen browser, 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 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 sekarang memerlukan konfirmasi (prompt elisitasi, atau confirm: true). Klien mengambil permukaan baru saat MCP dimulai ulang.

Migrasi dari v1.x (perubahan yang merusak di v2.0.0)

v2 menciutkan 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 sebaris di setiap lingkungan
`create_credential`	`create_environment({credentials: [...]})` semai, 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 — penghentian backend otomatis

Perubahan bentuk respons: bidang count mentah pada respons daftar dihilangkan — gunakan pageInfo.totalCount.

Konfigurasi

Var lingkungan	Wajib	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`.
`LOG_LEVEL`	tidak	`error` / `warn` / `info` (default) / `debug`.
`POSTHOG_API_KEY`	tidak	Timpa kunci proyek telemetri yang disematkan (mis. fork pribadi).
`DEBUGGAI_TELEMETRY_DISABLED`	tidak	Atur ke `1` / `true` / `yes` / `on` untuk menonaktifkan telemetri sepenuhnya.

DEBUGGAI_API_KEY=your_api_key

Transport jarak jauh / HTTP (opsional)

Secara default, server menggunakan stdio (npx lokal). Sebagai gantinya, server dapat berjalan sebagai MCP jarak jauh multi-pengguna yang dihosting melalui HTTP Streamable stateless + OAuth:

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

Ini adalah Server Sumber Daya OAuth: setiap POST /mcp memerlukan Authorization: Bearer <token>; token yang hilang/tidak valid akan mendapatkan 401 dengan WWW-Authenticate yang mengarah ke metadata RFC 9728, dan klien menjalankan alur OAuth terhadap server otorisasi yang diiklankan. Bearer bersifat request-scoped — 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`	Load-balancer / health check ECS

Env var	Default	Tujuan
`DEBUGGAI_MCP_TRANSPORT`	`stdio`	Atur 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`	Atur ke `bearer` agar token OAuth diteruskan sebagai `Authorization: Bearer`

Instalasi stdio tidak memerlukan semua ini.

Telemetri

Server MCP dikirimkan dengan telemetri yang diaktifkan secara default — sebuah kunci proyek PostHog write-only tertanam (phc_*) sehingga tim dapat mengamati tingkat cache hit, irama polling, keandalan tunnel, dan metrik operasional lainnya di seluruh basis instalasi. Event yang ditangkap:

Event	Kapan
`tool.executed` / `tool.failed`	Per panggilan tool
`workflow.executed`	Per eksekusi browser-agent (membawa `pollCount`, `durationMs`, `finalIntervalMs`)
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	Per event siklus hidup tunnel
`template.lookup` / `project.lookup`	Cache hit/miss dengan `durationMs` pada cold-call

Sikap privasi:

ID uniknya adalah SHA-256(api_key).slice(0, 16) — bukan kunci mentah, tanpa PII.
Kunci phc_* bersifat write-only berdasarkan konvensi PostHog; aman untuk disematkan di sumber.
Atur DEBUGGAI_TELEMETRY_DISABLED=1 untuk sepenuhnya opt out (beralih ke penyedia no-op; tidak ada event 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

Rangkaian evaluasi menjalankan server MCP yang dibangun sebagai subproses, menguji setiap tool 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 menyertakan .mcp.json yang mendaftarkan server berlingkup proyek bernama debugg-ai-local yang mengarah ke node dist/index.js — kode lokal yang baru dibangun. Ini hanya aktif ketika direktori kerja Claude Code adalah repo ini.

Proyek Anda yang lain harus menggunakan registrasi debugg-ai berlingkup pengguna yang mengambil dari paket npm yang dipublikasikan:

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 debugg-ai-local berikutnya mengambil perubahan Anda.

Tautan

Dashboard · Dokumentasi · Isu · Discord