Debugg AI

resmi

Kod üretme aracılarınızın, Debugg AI test platformu aracılığıyla uzak tarayıcılardaki yeni kod değişikliklerine karşı sıfır yapılandırmalı uçtan uca testler oluşturmasını ve çalıştırmasını sağlayın.

GitHub

Bu MCP'yi deneyinSponsorlu

Debugg AI MCP ile neler yapabilirsiniz?

AI tarayıcı testlerini çalıştırın — Asistanı herhangi bir URL veya localhost üzerinde check_app_in_browser çağırması için yönlendirin, doğal dilde ne test edileceğini açıklayın ve ekran görüntüleriyle birlikte geçti/kaldı sonuçları alın.
Birden fazla sayfayı hızlıca inceleyin — probe_page kullanarak 1–20 URL'yi konsol hataları, ağ sorunları ve işlenmiş durum için toplu kontrol edin; LLM maliyeti veya aracı döngüleri olmadan.
Bilgi grafiği taramalarını tetikleyin — trigger_crawl çağırarak projenin bilgi grafiğini HAR ve konsol günlüğü yapıtlarıyla dolduran sunucu tarafı bir tarayıcı aracı taraması başlatın.
Test paketlerini ve durumlarını yönetin — test_suite ve test_case varlıkları için testler oluşturun, çalıştırın ve sonuçları inceleyin; test başına sonuçlar ve geçme oranlarıyla.
Yürütme yapıtlarını inceleyin — executions aracılığıyla ekran görüntüleri, HAR ağ izleri ve konsol günlükleri dahil tam yürütme ayrıntılarını alarak çalışma zamanı sorunlarını hata ayıklayın.
Ortamları ve oturumları yönetin — environment ile kimlik bilgileri içeren ortamlar oluşturun veya güncelleyin ve sıcak giriş oturumu yeniden kullanımını kontrol etmek için sessions/clearSessions kullanın.

Dokümantasyon

Debugg AI — MCP Sunucusu

Yapay zeka destekli tarayıcı testleri, Model Context Protocol üzerinden. Herhangi bir URL'ye (veya localhost'a) yönlendirin ve ne test edileceğini tanımlayın — bir yapay zeka ajanı uygulamanızda gezinir ve ekran görüntüleriyle birlikte geçti/kaldı sonucunu döndürür.

Kurulum

Node.js 20.20.0 veya üzeri gerektirir (posthog-node@^5.26.0 kaynaklı geçişli gereksinim).

http://localhost:... URL'lerini test etmek için caddy ikili dosyası gerekir — check_app_in_browser, probe_page ve trigger_crawl, localhost hedeflerini yerel bir Caddy ters proxy üzerinden tüneller. Bu otomatik olarak kurulur: @radically-straightforward/caddy npm bağımlılığı, platformunuz için sabitlenmiş bir Caddy sürümünü npm install/npx sırasında indirir — bu projenin zaten ngrok ikili dosyası için yaptığıyla aynı şekilde — normal durumda kendiniz bir şey kurmanıza gerek yoktur. Bu indirme hiç çalışmadıysa (npm install --ignore-scripts, çevrimdışı/hava boşluklu kurulum), CADDY_BIN'u kendi kurulumunuza yönlendirin (brew install caddy / apt install caddy / bkz. caddyserver.com/docs/install) — eksik olması, ilk localhost-URL çağrısında sessiz bir takılma değil, net bir hata olarak ortaya çıkar. Genel-URL çağrıları, her tarayıcı dışı araç ve test_suite {action:"run"} (kendi özel tünelini kullanır ve Caddy'yi tamamen atlar) her iki durumda da buna ihtiyaç duymaz.

debugg.ai adresinden bir API anahtarı alın, ardından MCP istemci yapılandırmanıza ekleyin:

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

Veya Docker ile:

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

Dockerfile'ün npm install adımı, caddy'i yerel kurulumların yaptığı aynı otomatik şekilde, prensipte yakalardı — ancak bu yazının yazıldığı tarih itibarıyla Dockerfile, derlemenin artık ihtiyaç duyduğu birkaç dizini (handlers, tools, types, config) COPY yapmıyor ve hâlâ artık var olmayan bir tunnels/ dizinine referans veriyor, bu yüzden taze bir derleme muhtemelen bu önemli hale gelmeden başarısız olur. Bu, Caddy ile ilgisi olmayan, önceden var olan bir boşluktur. Şu anda yayınlanan quinnosha/debugg-ai-mcp imajı her durumda Caddy bağımlılığından öncedir — check_app_in_browser/probe_page/trigger_crawl adreslerine yapılan localhost-URL çağrıları, bu imajın içinde CaddyBinaryNotFoundError ile başarısız olur; imaj yeniden derlenip (Dockerfile düzeltilerek) yeniden yayınlanana veya CADDY_BIN ayrı olarak gömülmüş bir tanesine işaret edene kadar. Genel-URL çağrıları, tarayıcı dışı araçlar ve test_suite {action:"run"} her iki durumda da etkilenmez.

Araçlar

Sunucu 8 araç sunar: üç Tarayıcı aracı artı yönetilen her varlık için bir eylem tabanlı araç. Öne çıkan araçlar check_app_in_browser (tam yapay zeka ajanı) ve probe_page (hafif, LLM'siz sayfa denetçisi). Geri kalanlar — project, environment, test_suite, test_case, executions — her biri işlemi seçen bir action ayırt edici (ör. {"action":"list"}) alır. Yıkıcı delete eylemleri onay gerektirir (desteklenen yerlerde bir aydınlatma istemi, aksi takdirde confirm: true).

Tarayıcı

`check_app_in_browser`

Uygulamanıza karşı bir yapay zeka tarayıcı ajanı çalıştırır. Ajan gezinir, etkileşime girer ve ekran görüntüleriyle birlikte rapor verir. Localhost URL'leri ngrok üzerinden otomatik olarak tünellenir.

Parametre	Tür	Açıklama
`description`	string zorunlu	Ne test edileceği (doğal dil)
`url`	string zorunlu	Hedef URL — `http://localhost:3000` otomatik tünellenir
`environmentId`	string	Belirli bir ortamın UUID'si
`credentialId`	string	Belirli bir kimlik bilgisinin UUID'si
`credentialRole`	string	Role göre bir kimlik bilgisi seçin (ör. `admin`, `guest`)
`username`	string	Giriş için kullanıcı adı (geçici — kalıcı değil)
`password`	string	Giriş için şifre (geçici — kalıcı değil)
`loginCredentials`	array	Ajanın görev sırasında karşılaştığı girişler için hesaplar — `[{username, password, label?}]`
`useEnvironmentCredentials`	boolean	Varsayılan `true`. `false`, ortamın saklanan kimlik bilgilerinin otomatik doldurulmasını yasaklar; adlandırılmış hesap yoksa hiç giriş yapma anlamına gelir
`freshSession`	boolean	Varsayılan `false`. `true`, o hesap için tutulan sıcak oturumu yeniden kullanmak yerine gerçek bir girişi zorlar
`auth`	object	Kimlik doğrulama ön koşulu — `{precondition, entryUrl, deepUrl, environmentId, username, password}`
`repoName`	string	Otomatik algılanan git repo adını geçersiz kıl (ör. `my-org/my-repo`)

Çağrı başına tek odaklı kontrol. Ajanın ~25 adımlık dahili bütçesi vardır; daha geniş paketleri birden çok çağrıya bölün.

Kimlik bilgileri: bunları parametre olarak iletin, düz metin olarak değil

Yalnızca description içinde bir hesap adı vermek, ajanın onu kullanmasını sağlamaz — ortamın saklanan kimlik bilgisine geri döner ve uygulamanın yanlış hesabı reddetmesi, bir uygulama hatası gibi görünür. Parametre olarak ilettiğiniz her şey, çalıştırmanın her girişinde ortam varsayılanını yener, yalnızca ilkinde değil:

username / password (veya credentialId / credentialRole) — çalıştırmanın kimliği.
auth.username / auth.password — auth.precondition: "login" de kullandığınızda ön koşul girişini sabitler.
loginCredentials — ajanın görevin ortasında ulaştığı bir giriş formu için hesaplar. Bu, şifre belirle → oturum açma ekranına yönlendiril → az önce oluşturduğunuz hesapla giriş yap gibi akışlar içindir; burada ayrı çağrılara bölmek tarayıcı durumunu kaybeder.

Varsayılan test kullanıcısına sessiz bir geri dönüş kontrolü geçersiz kılacağında useEnvironmentCredentials: false ayarlayın.

Hiç giriş gerektirmeyen bir sayfayı mı kontrol ediyorsunuz? useEnvironmentCredentials: false iletin ve hiçbir hesap adlandırmayın. Bu kombinasyon tam olarak söylediği anlama gelir — giriş yapma — ve çalıştırma, bir giriş formu aramak yerine kimlik doğrulamayı tamamen atlar. Genel sayfalar, pazarlama siteleri, dokümanlar ve kimlik doğrulama öncesi her şey için kullanın. Ayrıca daha hızlıdır: varsayılan (auto) üzerinde ajan, herhangi bir şeyi değerlendirmeden önce sayfanızdaki bir "Giriş yap" bağlantısını takip eder ve ortamın saklanan hesabını dener.

Oturum yeniden kullanımı: bir kontrolün neden "giriş formu yok" bildirebileceği

Çalıştırmalar her seferinde giriş yapmaz. Doğrulanmış bir girişten sonra arka uç, o hesabın oturumunu yakalar ve aynı kimlik için sonraki çalıştırmada onu geri yükler; bu da girişi tamamen atlar — bu yüzden bir kontrol meşru olarak submitted: false ve giriş formu olmadan geri gelebilir: zaten oturum açılmıştı. Geri yüklenen bir çalıştırma, kendisini logins içinde reason: "restored_session" ile bildirir; böylece gerçekten form bulamayan bir çalıştırmadan ayırt edebilirsiniz.

Oturumlar hesap başına anahtarlanır, bu nedenle farklı bir hesap adlandırmak asla başkasınınkini yeniden kullanmaz. Yeniden kullanımı atlamanın iki yolu:

Tek bir çağrıda freshSession: true — bu sefer gerçekten giriş yapın, ardından yeniden yakalayın. Giriş akışının kendisini kontrol ettiğinizde, saklanan oturumun bayat olduğundan şüphelendiğinizde veya uygulamanın kişilikler arasındaki tek yolunun çıkış yapmak olduğu durumlarda kullanın.
environment aracı, action: "clearSessions" — saklanan oturumları geçersiz kılın, böylece sonraki çalıştırmalar giriş yapar. username / credentialId ile daraltın; kapsamsız temizlikler onay gerektirir çünkü ortamdaki her hesap daha sonra yeniden kimlik doğrular.

Bir ortamın şu anda ne tuttuğunu ve her birinin yeniden kullanılıp kullanılmayacağını görmek için action: "sessions" kullanın.

Sonuçlar gerçekte kullanılan kimliği bildirir; böylece yanlış bir kimlik, bozuk bir uygulama gibi gizlenmek yerine görünür olur:

"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, task | explicit | credential_id (adlandırdığınız bir hesap) veya env | env_default (ortamın saklanan hesabı) şeklindedir. credentialWarning, yalnızca bir hesap adlandırdığınızda ve yine de bir ortam varsayılanı kullanıldığında görünür. loginError, adlandırılmış bir hesap çözülemediğinde ve çalıştırma farklı bir tane koymayı reddettiğinde görünür.

Her başarılı çalıştırma, ekran görüntüsünün yanında bir browserSession bloğu döndürür — yakalanan HAR (tam ağ izi) ve konsol günlüğü (her JS konsol mesajı) için önceden imzalanmış S3 URL'leri. Bunları yeniden getirme döngülerini, hidrasyon hatalarını ve tür kontrollerini ve birim testlerini geçen diğer çalışma zamanı sorunlarını tespit etmek için kullanın:

"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'ler kısa ömürlü önceden imzalanmış S3'tür — yenilemek için üst yürütmeyi executions {action:"get", uuid} ile yeniden getirin. harStatus / consoleLogStatus, 'downloaded' (URL getirilebilir), 'not_available' (sayfa hiçbir şey yaymadı), 'failed' (yakalama bozuldu) arasında ayrım yapar. Yeni bir çalıştırmada URL'ler genellikle null olur çünkü yakalama, ajan bitirdikten sonra asenkron olarak yüklenir — durum 'downloaded' değerine ulaşana kadar executions {action:"get", uuid: executionId} yoklayın. Yetkilendirme / Çerez / token/secret/api_key başlıkları, yapılar kalıcı hale getirilmeden önce sunucu tarafında temizlenir.

`trigger_crawl`

Projenin bilgi grafiğini doldurmak için sunucu tarafı bir tarayıcı-ajan taraması başlatır. Localhost URL'leri otomatik olarak tünellenir. Başarılı alımda knowledgeGraph.imported === true ile {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} döndürür. browserSession bloğu (HAR + konsol-günlüğü URL'leri, yukarıdakiyle aynı şekil) tamamlanan taramalarda da bulunur.

`probe_page`

Hafif, LLM'siz toplu sayfa denetçisi. 1-20 URL iletin; her biri gezinir, içerikte durulur (DOM'un sessizleşmesi, sınırlı — asla ağ sessizliğinde değil, canlı bir uygulamanın asla ulaşamayacağı bir durum) ve işlenmiş durumu döndürür — ekran görüntüsü + sayfa meta verileri + yapılandırılmış konsol hataları + ağ özeti. Ajan döngüsü yok, LLM maliyeti yok, senaryo iddiası yok. "Az önce /settings'i mi bozdum?", yeniden düzenleme sonrası çok yönlü duman testi, CI başına-PR taramaları ve check_app_in_browser'ün 60-150sn ajan döngüsünün aşırı olduğu hızlı çalışıyor mu kontrolleri için kullanın.

Parametre	Tür	Açıklama
`targets`	array zorunlu	1-20 girdi: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]`
`targets[].url`	string zorunlu	Genel URL veya localhost (otomatik tünellenir)
`targets[].waitForLoadState`	enum	`'domcontentloaded'` (varsayılan, + sınırlı bir içerik durulması) / `'load'` (ayrıca üçüncü taraf gömmelerini bekler) / `'networkidle'` (kabul edilir, asla verilmez — canlı bir sitenin ağı boşta kalmaz)
`targets[].waitForSelector`	string	Gezinme sonrası beklemek için isteğe bağlı CSS seçici
`targets[].timeoutMs`	number	URL başına zaman aşımı, 1000-30000 (varsayılan 10000)
`includeHtml`	boolean	Her sonuçta ham HTML döndür (varsayılan false)
`captureScreenshots`	boolean	Hedef başına bir PNG döndür (varsayılan true)

Bir toplu işteki tüm hedefler tek bir oturum tünelini paylaşır, ancak yalnızca aynı bağlantı noktasındaki (veya tamamen genel) toplu işler tek bir arka uç yürütmesini paylaşır — tek çağrıda bir bağlantı noktasındaki 5 URL, 5 paralel tek-URL çağrısından önemli ölçüde daha hızlıdır. Birden çok yerel bağlantı noktasını karıştıran bir toplu iş, bağlantı noktası grubu başına bir sıralı arka uç yürütmesine ayrışır (yine tek çağrı, yine orijinal sıranızda tek birleştirilmiş results[], ancak bir yerine N arka uç gidiş-dönüşü — daha yavaş, reddedilmez). URL başına error alanı toplu iş dayanıklılığını korur: tek bir başarısız hedef diğerlerini başarısız yapmaz.

networkSummary toplama anahtarı origin + pathname'dır — yeniden getirme döngüleri (aynı uç noktaya tekrar tekrar vuran ?n=0..4) sayıyla birlikte tek bir girdiye daralır; böylece count: 47 ile görünen /api/poll, kullanıcıların başlangıçta istediği eyleme geçirilebilir "sonsuz yeniden getirme döngüsü" sinyalidir.

Performans bütçesi: 1 URL için <10sn, 20 için <25sn. Localhost ölü bağlantı noktası, bir iş akışı yürütmesi yakmadan <2sn içinde LocalServerUnreachable döndürür.

`project`

Eylem	Parametreler	Sonuç
`get`	`{uuid}`	Seçilmiş proje detayı
`list`	`{q?, page?, pageSize?}`	Sayfalanmış özetler
`create`	`{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}`	Oluşturulan proje

Takım ve repo, uuid veya ad ile çözülür (büyük/küçük harf duyarsız tam eşleşme; hiçbiri yoksa NotFound, birden çok varsa AmbiguousMatch). update/delete yoktur — bir projeyi DebuggAI web uygulamasından yeniden adlandırın veya silin.

`environment`

Eylem	Parametreler	Sonuç
`get`	`{uuid, projectUuid?}`	Kimlik bilgileri satır içi olarak eklenmiş ortam (şifreler asla döndürülmez)
`list`	`{projectUuid?, q?, page?, pageSize?}`	Sayfalanmış ortamlar, her biri kimlik bilgileri dizisiyle birlikte
`create`	`{name, url, description?, projectUuid?, credentials?}`	Oluşturulan ortam (isteğe bağlı olarak kimlik bilgilerini tohumlar)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	Yamanmış ortam; kimlik bilgisi işlemleri kaldır → güncelle → ekle sırasıyla çalışır
`delete`	`{uuid, projectUuid?, confirm?}`	Ortamı siler (kimlik bilgilerini basamaklı olarak siler) — onay gerektirir
`sessions`	`{uuid, username?, credentialId?}`	Ortamın tuttuğu, hesap başına yakalanan oturum açma oturumları, `isUsable` ve bir `usableCount` ile birlikte
`clearSessions`	`{uuid, username?, credentialId?, confirm?}`	Bunları geçersiz kılar, böylece bir sonraki çalıştırma gerçekten giriş yapar — kapsamı belirsiz temizlemeler onay gerektirir

projectUuid belirtilmediğinde git deposundan otomatik olarak çözümlenir. Kimlik bilgisi başına hatalar, ortam işlemini engellemeden credentialWarnings[] içinde yüzeye çıkar.

sessions / clearSessions, arka uçun girişi atlamak için yeniden kullandığı sıcak kimliği doğrulanmış oturumları yönetir (bkz. Oturum yeniden kullanımı). Oturum içerikleri asla döndürülmez — bir oturum çerezi, taşıyıcı kimlik bilgisidir. clearSessions, satırları silmek yerine oturumları geçersiz olarak işaretler, böylece yeniden kullanım anında dururken yakalama geçmişi okunabilir kalır.

`test_suite`

Eylem	Parametreler	Sonuç
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	Durum + geçme oranı ile sayfalanmış paketler
`create`	`{name, description, projectUuid\|projectName}`	Oluşturulan paket
`run`	`{suiteUuid\|(suiteName+project), targetUrl?}`	Tüm testleri eşzamansız olarak tetikler
`results`	`{suiteUuid\|(suiteName+project)}`	Paket + test başına sonuçlar
`delete`	`{suiteUuid\|(suiteName+project), confirm?}`	Yumuşak silme — onay gerektirir

`test_case`

Eylem	Parametreler	Sonuç
`create`	`{name, description, agentTaskDescription, suiteUuid\|(suiteName+project), relativeUrl?, maxSteps?}`	Oluşturulan test senaryosu (otomatik çalıştırılmaz)
`update`	`{testUuid, name?, description?, agentTaskDescription?}`	Yamanmış test senaryosu
`delete`	`{testUuid, confirm?}`	Yumuşak silme — onay gerektirir

`executions`

Eylem	Parametreler	Sonuç
`get`	`{uuid}`	Tam ayrıntı (`nodeExecutions` + durum + errorInfo) + ekran görüntüsü/gif yapıtları
`list`	`{status?, projectUuid?, page?, pageSize?}`	Sayfalanmış özetler

Arka uçtan 404, isError: true ile {error: 'NotFound', message, uuid} olarak yüzeye çıkar. Kimlik bilgileri her zaman şifreler olmadan döndürülür.

Sayfalama

Her filtre modu yanıtı sayfalanmıştır. Yanıt şekli:

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

İsteğe bağlı page (1 tabanlı, varsayılan 1) ve pageSize (varsayılan 20, maks 200; aşırı büyük değerler sıkıştırılır) iletin. Hiçbir yanıt asla sessizce kesilmez.

Kaynaklar

Araçların yanı sıra, sunucu salt okunur varlıkları MCP kaynakları olarak sunar; böylece istemciler bunlara göz atabilir ve bağlam olarak @-bahsedebilir:

URI	Ne
`debugg-ai://projects`	Tüm projeler (ilk sayfa)
`debugg-ai://environments`	Otomatik algılanan proje için ortamlar
`debugg-ai://executions`	Son yürütmeler (ilk sayfa)
`debugg-ai://project/{uuid}`	Bir proje, tam ayrıntı
`debugg-ai://environment/{uuid}`	Bir ortam (kimlik bilgileri satır içi, şifreler redakte edilmiş)
`debugg-ai://execution/{uuid}`	Bir yürütme, tam düğüm ayrıntısı + yapıt bağlantıları

Okumalar, project / environment / executions araçlarıyla aynı işleyicilere dağıtılır, bu nedenle veri ve kimlik doğrulama aynıdır. Kaynaklar katkısaldır — kaynak desteği olmayan istemciler araçları kullanmaya devam eder.

Güvenlik değişmezleri

Şifreler yalnızca yazılabilir. Hiçbir araçtan gelen hiçbir yanıt gövdesinde asla görünmezler.
Tünel URL'leri (*.ngrok.debugg.ai), aracı tarafından yazılan metin dahil olmak üzere tüm tarayıcı aracı yanıtlarından çıkarılır.
Arka uçtan 404'ler, fırlatılan istisnalar olarak değil, isError: true ile {error: 'NotFound', ...} olarak yüzeye çıkar.
Eksik DEBUGGAI_API_KEY, ilk çağrıda yapılandırılmış bir araç hatası olarak yüzeye çıkar — sunucu yine de araçları normal şekilde kaydeder ve listeler.

v3.0.0'a Geçiş (eylem tabanlı araçlar)

v3, 20 fiil başına aracı 8 eylem tabanlı araçta birleştirdi. Eski araç → yeni tool {action}:

Kaldırılan	Yerine Geçen
`search_projects`	`project {action:"get"}` / `project {action:"list"}`
`create_project`	`project {action:"create"}`
`update_project`, `delete_project`	Kaldırıldı — DebuggAI web uygulamasını kullanın
`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` `headless` parametresi	Kaldırıldı — her zaman headless

delete eylemleri artık onay gerektirir (sorgulama istemi veya confirm: true). İstemciler, MCP yeniden başlatıldığında yeni yüzeyi alır.

v1.x'ten Geçiş (v2.0.0'da kırıcı değişiklik)

v2, 22 araçlık yüzeyi 11'e indirdi. Eski araç → yeni araç eşlemesi:

Kaldırılan	Yerine Geçen
`list_projects`, `get_project`	`search_projects` (uuid modu vs filtre modu)
`list_environments`, `get_environment`	`search_environments`
`list_credentials`, `get_credential`	`search_environments` — kimlik bilgileri her ortamda satır içi
`create_credential`	`create_environment({credentials: [...]})` tohumu veya `update_environment({addCredentials: [...]})`
`update_credential`	`update_environment({updateCredentials: [{uuid, ...patch}]})`
`delete_credential`	`update_environment({removeCredentialIds: [uuid]})`
`list_teams`, `list_repos`	`create_project({teamName, repoName})` — belirsizlik işleme ile ad çözümleme
`list_executions`, `get_execution`	`search_executions`
`cancel_execution`	Kaldırıldı — arka uç kapanması otomatiktir

Yanıt şekli değişiklikleri: liste yanıtlarındaki çıplak count alanı kaldırıldı — pageInfo.totalCount kullanın.

Yapılandırma

Ortam değişkeni	Gerekli	Amaç
`DEBUGGAI_API_KEY`	evet	Arka uç API anahtarı. Takma adlar: `DEBUGGAI_API_TOKEN`, `DEBUGGAI_JWT_TOKEN`.
`DEBUGGAI_API_URL`	hayır	Arka uç temel URL'si. Varsayılan: `https://api.debugg.ai`.
`DEBUGGAI_TOKEN_TYPE`	hayır	`token` (varsayılan) veya `bearer`.
`DEBUGGAI_EVAL_TEMPLATE`	hayır	`check_app_in_browser`'nın gönderdiği App Evaluation iş akışı slug'ını geçersiz kıl. Varsayılan: `flow/e2es/app-eval`. Gönderim, bu slug'a sabitlenir, böylece arka uç şablon yeniden adlandırması onu bozamaz.
`LOG_LEVEL`	hayır	`error` / `warn` / `info` (varsayılan) / `debug`.
`POSTHOG_API_KEY`	hayır	Gömülü telemetri proje anahtarını geçersiz kıl (örn. özel çatal).
`DEBUGGAI_TELEMETRY_DISABLED`	hayır	Telemetriyi tamamen devre dışı bırakmak için `1` / `true` / `yes` / `on` olarak ayarlayın.

DEBUGGAI_API_KEY=your_api_key

Uzaktan / HTTP taşıma (isteğe bağlı)

Varsayılan olarak sunucu stdio (yerel npx) konuşur. Bunun yerine, durumsuz Streamable HTTP + OAuth üzerinden barındırılan, çok kullanıcılı uzak bir MCP olarak çalışabilir:

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

Bir OAuth Kaynak Sunucusudur: her POST /mcp, Authorization: Bearer <token> gerektirir; eksik/geçersiz belirteçler, RFC 9728 meta verilerini gösteren bir WWW-Authenticate ile 401 alır ve istemciler, reklamı yapılan yetkilendirme sunucusuna karşı OAuth akışını çalıştırır. Taşıyıcı, istek kapsamlıdır — api.debugg.ai onu doğrular.

Uç nokta	Amaç
`POST /mcp`	MCP Streamable HTTP (taşıyıcı korumalı)
`GET /.well-known/oauth-protected-resource`	RFC 9728 meta verileri (yetkilendirme sunucusu keşfi)
`GET /health`	Yük dengeleyici / ECS sağlık kontrolü

Ortam değişkeni	Varsayılan	Amaç
`DEBUGGAI_MCP_TRANSPORT`	`stdio`	Uzaktan taşıma için `http` olarak ayarlayın
`PORT`	`3000`	HTTP dinleme bağlantı noktası
`DEBUGGAI_MCP_PUBLIC_URL`	`https://mcp.debugg.ai`	Bu sunucunun genel kaynak URL'si (RFC 9728 `resource`)
`DEBUGGAI_OAUTH_ISSUER`	`https://auth.debugg.ai`	İstemcilere reklamı yapılan yetkilendirme sunucusu
`DEBUGGAI_TOKEN_TYPE`	`token`	OAuth belirteçlerinin `Authorization: Bearer` olarak iletilmesi için `bearer` olarak ayarlayın

stdio kurulumları bunların hiçbirine ihtiyaç duymaz.

Çok kopyalı dağıtımlar (yayın öncesi git/gitme): tünel durumu (ngrok oturum tüneli, Caddy örneği ve bağlantı noktası yolu kilidi) süreç içidir, arayan başına taşıyıcı belirtecinin karmasıyla anahtarlanır — çapraz süreç koordinasyonu yoktur. Düz bir round-robin yük dengeleyicinin arkasında birden çok kopya çalıştırmak, bir arayanın çağrılarının farklı kopyalara düşebileceği ve tüm oturum için bir yerine her ulaştıkları kopya için bir tünel oluşturabileceği anlamına gelir (ekstra ngrok maliyeti, kopya sayısıyla sınırlı, mevcut 55 dakikalık boşta otomatik kapanma yoluyla kendi kendini iyileştiren — asla oturumlar arası bir doğruluk hatası değildir, çünkü herhangi bir tek araç çağrısı tüm süresi boyunca tek bir kopyada kalır). Çok kopyalı bir HTTP dağıtımında amaçlanan "oturum başına bir tünel" davranışını elde etmek için, yük dengeleyicide oturum benzeşimli yönlendirme yapılandırın (getSessionKey()'nın türettiği aynı kimliğe anahtarlı yapışkan/tutarlı karma — pratikte, arayanın Authorization taşıyıcı belirteci). Tam gerekçe ve bu yapılandırılmazsa dürüst düşüş yolu için docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1'e bakın.

Telemetri

MCP sunucusu, varsayılan olarak etkin telemetriyle birlikte gelir — ekibin kurulum tabanı genelinde önbellek isabet oranlarını, yoklama sıklığını, tünel güvenilirliğini ve diğer operasyonel ölçümleri gözlemleyebilmesi için gömülü yalnızca yazılabilir bir PostHog proje anahtarı (phc_*). Yakalanan olaylar:

Olay	Ne zaman
`tool.executed` / `tool.failed`	Araç çağrısı başına
`workflow.executed`	Tarayıcı aracı yürütmesi başına (`pollCount`, `durationMs`, `finalIntervalMs` taşır)
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	Tünel yaşam döngüsü olayı başına
`template.lookup` / `project.lookup`	Soğuk çağrıda `durationMs` ile önbellek isabeti/ıskası

Gizlilik duruşu:

Ayrı kimlik SHA-256(api_key).slice(0, 16)'dir — asla ham anahtar değil, PII yok.
phc_* anahtarları PostHog kuralı gereği yalnızca yazılabilir; kaynağa gömmek güvenlidir.
Tamamen vazgeçmek için DEBUGGAI_TELEMETRY_DISABLED=1 ayarlayın (no-op sağlayıcıya çözümlenir; süreçten hiçbir olay çıkmaz).

Etkin mod, başlangıçta günlüğe kaydedilir:

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)

Yerel Geliştirme

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

Değerlendirme paketi, oluşturulmuş MCP sunucusunu bir alt süreç olarak başlatır, her aracı gerçek bir arka uca karşı çalıştırır ve akış başına yapıtları scripts/evals/artifacts/<timestamp>/ konumuna yazar. Bireysel senaryolar için scripts/evals/flows/'ya bakın.

MCP kaydı: `debugg-ai-local` vs `debugg-ai`

Bu depo, node dist/index.js'i işaret eden debugg-ai-local adlı proje kapsamlı bir sunucu kaydeden bir .mcp.json ile birlikte gelir — yeni oluşturulmuş yerel kod. Yalnızca Claude Code'un çalışma dizini bu depo olduğunda etkinleşir.

Diğer projeleriniz, yayınlanan npm paketinden çeken kullanıcı kapsamlı debugg-ai kaydını kullanmalıdır:

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

Buradaki kodu düzenledikten sonra, debugg-ai-local'ün bir sonraki çağrısının değişikliklerinizi alması için npm run mcp:local çalıştırın (yalnızca yeniden oluşturur).

Bağlantılar

Dashboard · Docs · Issues · Discord