Debugg AI

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.

Ç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.

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

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

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

test_case

executions

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:

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}:

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:

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

Yapılandırma

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.

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:

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

Apache-2.0 Lisansı © 2025 DebuggAI