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 mana pun — deskripsikan apa yang ingin diuji dalam bahasa alami dan check_app_in_browser akan menavigasi, berinteraksi, serta mengembalikan hasil lulus/gagal beserta tangkapan layar dan artefak sesi.
Periksa beberapa halaman tanpa beban AI — berikan 1–20 URL ke probe_page untuk pemeriksaan status render cepat, error konsol, dan ringkasan jaringan setelah refaktor atau penerapan.
Picu perayapan sisi server — gunakan trigger_crawl untuk mengisi grafik pengetahuan proyek dengan merayapi URL target.
Kelola rangkaian dan kasus pengujian — buat, daftarkan, jalankan, dan lihat hasil untuk entitas test_suite dan test_case, termasuk penghapusan lunak dengan konfirmasi.
Periksa detail eksekusi dan artefak — ambil status eksekusi lengkap, tangkapan layar, HAR, dan log konsol melalui tindakan executions get atau list.
Jelajahi proyek, lingkungan, dan eksekusi sebagai sumber daya — akses ringkasan hanya-baca di URI seperti debugg-ai://projects 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

Membutuhkan Node.js 20.20.0 atau yang 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 delete yang bersifat destruktif 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 secara 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 dari lingkungan tertentu
`credentialId`	string	UUID dari 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 proses yang berhasil mengembalikan blok browserSession bersama tangkapan layar — URL S3 yang telah ditandatangani sebelumnya untuk HAR yang diambil (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 dan berumur pendek — 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' (pengambilan gagal). Pada proses baru, URL biasanya null karena pengambilan diunggah secara 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 setelah 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 pemuatan, 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 (otomatis diterowongkan)
`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 hitungan, 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 dengan paginasi
`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 dengan paginasi, masing-masing dengan array kredensial
`create`	`{name, url, description?, projectUuid?, credentials?}`	Lingkungan dibuat (opsional menyertakan kredensial)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	Lingkungan ditambal; operasi kredensial berjalan hapus → perbarui → tambah
`delete`	`{uuid, projectUuid?, confirm?}`	Menghapus lingkungan (kaskade kredensial) — memerlukan konfirmasi

projectUuid diselesaikan secara otomatis 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 dengan paginasi + 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 dijalankan otomatis)
`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 dengan paginasi

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

Paginasi

Setiap respons mode filter menggunakan paginasi. Bentuk respons:

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

Berikan opsional page (indeks 1, default 1) dan pageSize (default 20, maks 200; nilai yang terlalu besar akan dibatasi). 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 @-mention 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 mendaftarkan 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 tanpa kepala

Tindakan 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: [...]})` 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 — penghentian backend otomatis

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

Konfigurasi

Var env	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`.
`DEBUGGAI_EVAL_TEMPLATE`	tidak	Timpa slug alur kerja Evaluasi Aplikasi yang dikirim oleh `check_app_in_browser`. Default ke `flow/e2es/app-eval`. Pengiriman disematkan ke slug ini sehingga penggantian nama template backend tidak dapat merusaknya.
`LOG_LEVEL`	tidak	`error` / `warn` / `info` (default) / `debug`.
`POSTHOG_API_KEY`	tidak	Timpa kunci proyek telemetri tersemat (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 (lokal npx). Server juga 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 · Docs · Issues · Discord