Debugg AI

Debugg AI — MCP-Server

KI-gestütztes Browser-Testen über das Model Context Protocol. Geben Sie eine beliebige URL (oder localhost) an und beschreiben Sie, was getestet werden soll — ein KI-Agent durchsucht Ihre App und liefert Bestanden/Nicht bestanden mit Screenshots.

Einrichtung

Erfordert Node.js 20.20.0 oder neuer (transitive Anforderung von posthog-node@^5.26.0).

Das Testen von http://localhost:...-URLs erfordert die caddy-Binärdatei — check_app_in_browser, probe_page und trigger_crawl tunneln localhost-Ziele über einen lokalen Caddy-Reverse-Proxy. Dies wird automatisch installiert: Die @radically-straightforward/caddy-npm-Abhängigkeit lädt eine festgelegte Caddy-Version für Ihre Plattform während npm install/npx herunter — im Normalfall müssen Sie selbst nichts installieren. Es ist jetzt die einzige Binärdatei, die dieses Paket herunterlädt; der Tunnel-Client selbst ist reines TypeScript — er ersetzte das ngrok-Paket, das den ngrok-Agenten abrief. Wenn dieser Download nie ausgeführt wurde (npm install --ignore-scripts, eine Offline-/Air-Gapped-Installation), zeigen Sie CADDY_BIN auf Ihre eigene Installation (brew install caddy / apt install caddy / siehe caddyserver.com/docs/install) — ein Fehlen zeigt sich als klare Fehlermeldung beim ersten localhost-URL-Aufruf, nicht als stilles Hängen. Public-URL-Aufrufe, jedes Nicht-Browser-Werkzeug und test_suite {action:"run"} (das einen eigenen dedizierten Tunnel verwendet und Caddy vollständig umgeht) benötigen es in beiden Fällen nicht.

Holen Sie einen API-Schlüssel unter debugg.ai und fügen Sie ihn dann zu Ihrer MCP-Client-Konfiguration hinzu:

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

Oder mit Docker:

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

Der Dockerfile-Schritt von npm install würde caddy auf demselben automatischen Weg aufnehmen, wie es lokale Installationen im Prinzip tun — aber zum Zeitpunkt dieses Schreibens Dockerfile nicht COPY mehrere Verzeichnisse, die der Build jetzt benötigt (handlers, tools, types, config) und verweist weiterhin auf ein tunnels/-Verzeichnis, das nicht mehr existiert, sodass ein frischer Build wahrscheinlich fehlschlägt, bevor das relevant wird. Das ist eine vorbestehende Lücke, die nichts mit Caddy zu tun hat. Das derzeit veröffentlichte quinnosha/debugg-ai-mcp-Image stammt ohnehin aus der Zeit vor der Caddy-Abhängigkeit — localhost-URL-Aufrufe an check_app_in_browser/probe_page/trigger_crawl werden mit CaddyBinaryNotFoundError in diesem Image fehlschlagen, bis es neu gebaut (Dockerfile korrigiert) und neu veröffentlicht wird, oder CADDY_BIN auf ein separat eingebackenes zeigt. Public-URL-Aufrufe, die Nicht-Browser-Werkzeuge und test_suite {action:"run"} sind in beiden Fällen nicht betroffen.

Werkzeuge

Der Server stellt 8 Werkzeuge bereit: drei Browser-Werkzeuge plus ein aktionsbasiertes Werkzeug pro verwalteter Entität. Die Hauptwerkzeuge sind check_app_in_browser (voller KI-Agent) und probe_page (leichtgewichtiger No-LLM-Seitensondierer). Die übrigen — project, environment, test_suite, test_case, executions — nehmen jeweils einen action-Diskriminator (z. B. {"action":"list"}), der die Operation auswählt. Destruktive delete-Aktionen erfordern eine Bestätigung (eine Aufforderung zur Eingabe, wo unterstützt, andernfalls confirm: true).

Browser

check_app_in_browser

Führt einen KI-Browser-Agenten gegen Ihre App aus. Der Agent navigiert, interagiert und berichtet mit Screenshots. Localhost-URLs werden automatisch durch den Debugg-Tunnel-Server getunnelt.

Parameter	Typ	Beschreibung
description	Zeichenkette erforderlich	Was zu testen ist (natürliche Sprache)
url	Zeichenkette erforderlich	Ziel-URL — http://localhost:3000 wird automatisch getunnelt
environmentId	Zeichenkette	UUID einer bestimmten Umgebung
credentialId	Zeichenkette	UUID einer bestimmten Anmeldedaten
credentialRole	Zeichenkette	Anmeldedaten nach Rolle auswählen (z. B. admin, guest)
username	Zeichenkette	Benutzername für die Anmeldung (flüchtig — nicht gespeichert)
password	Zeichenkette	Passwort für die Anmeldung (flüchtig — nicht gespeichert)
loginCredentials	Array	Konten für Anmeldungen, die der Agent während der Aufgabe erreicht — [{username, password, label?}]
useEnvironmentCredentials	Boolesch	Standard true. false verbietet das automatische Ausfüllen der gespeicherten Anmeldedaten der Umgebung; ohne benanntes Konto bedeutet es überhaupt nicht anmelden
freshSession	Boolesch	Standard false. true erzwingt eine echte Anmeldung statt der Wiederverwendung der warmen Sitzung, die für dieses Konto gehalten wird
auth	Objekt	Auth-Vorbedingung — {precondition, entryUrl, deepUrl, environmentId, username, password}
repoName	Zeichenkette	Automatisch erkannten Git-Repository-Namen überschreiben (z. B. my-org/my-repo)

Eine fokussierte Prüfung pro Aufruf. Der Agent hat ein internes Budget von etwa 25 Schritten; teilen Sie größere Suiten auf mehrere Aufrufe auf.

Anmeldedaten: als Parameter übergeben, nicht als Prosa

Ein Konto nur in description zu nennen, bedeutet nicht, dass der Agent es verwendet — er fällt auf die gespeicherte Anmeldedaten der Umgebung zurück, und die Ablehnung des falschen Kontos durch die App sieht wie ein Anwendungsfehler aus. Alles, was Sie als Parameter übergeben, schlägt die Umgebungsstandard für jede Anmeldung im Lauf, nicht nur die erste:

• username / password (oder credentialId / credentialRole) — die Identität des Laufs.
• auth.username / auth.password — legt die Vorbedingungsanmeldung fest, wenn Sie auch auth.precondition: "login" verwenden.
• loginCredentials — Konten für ein Anmeldeformular, das der Agent mitten in der Aufgabe erreicht. Dies ist das für Abläufe wie Passwort festlegen → zur Anmeldung weitergeleitet → als das gerade erstellte Konto anmelden, bei denen das Aufteilen in separate Aufrufe den Browserzustand verlieren würde.

Setzen Sie useEnvironmentCredentials: false, wenn ein stiller Rückfall auf den Standard-Testbenutzer die Prüfung ungültig machen würde.

Cross-Domain-SSO? Ein Lauf tippt Anmeldedaten nur auf dem eigenen Host der App und seinen Subdomains; eine Anmeldeseite auf einer anderen Domain wird als offscope_host verweigert. Fügen Sie den Host des Identitätsanbieters zur authorizedCredentialHosts der Umgebung hinzu (siehe environment).

Eine Seite prüfen, die keine Anmeldung benötigt? Übergeben Sie useEnvironmentCredentials: false und nennen Sie kein Konto. Diese Kombination bedeutet genau das, was sie sagt — nicht anmelden — und der Lauf überspringt die Authentifizierung vollständig, statt nach einem Anmeldeformular zu suchen. Verwenden Sie es für öffentliche Seiten, Marketing-Websites, Dokumentationen und alles vor der Authentifizierung. Es ist auch schneller: Beim Standard (auto) folgt der Agent einem „Anmelden"-Link von Ihrer Seite und versucht das gespeicherte Konto der Umgebung, bevor er irgendetwas auswertet.

Sitzungswiederverwendung: warum eine Prüfung „kein Anmeldeformular" melden kann

Läufe melden sich nicht jedes Mal an. Nach einer verifizierten Anmeldung erfasst das Backend die Sitzung dieses Kontos und stellt sie beim nächsten Lauf für dieselbe Identität wieder her, was die Anmeldung vollständig überspringt — deshalb kann eine Prüfung legitimerweise mit submitted: false und keinem Anmeldeformular zurückkommen: Sie war bereits angemeldet. Ein wiederhergestellter Lauf meldet sich in logins mit reason: "restored_session", sodass Sie ihn von einem Lauf unterscheiden können, der wirklich kein Formular gefunden hat.

Sitzungen sind pro Konto Schlüssel, sodass das Benennen eines anderen Kontos niemals die Sitzung eines anderen wiederverwendet. Zwei Möglichkeiten, die Wiederverwendung zu umgehen:

• freshSession: true bei einem einzelnen Aufruf — melden Sie sich dieses eine Mal wirklich an und erfassen Sie dann erneut. Verwenden Sie es, wenn der Anmeldeablauf das ist, was Sie prüfen, wenn Sie vermuten, dass die gespeicherte Sitzung veraltet ist, oder wenn der einzige Weg der App zwischen Personas eine Abmeldung ist.
• environment-Werkzeug, action: "clearSessions" — gespeicherte Sitzungen ungültig machen, sodass nachfolgende Läufe sich anmelden. Mit username / credentialId eingrenzen; unbegrenzte Löschungen erfordern eine Bestätigung, weil sich dann jedes Konto in der Umgebung erneut authentifiziert.

Verwenden Sie action: "sessions", um zu sehen, was eine Umgebung derzeit hält und ob jede wiederverwendet würde.

Ergebnisse melden die tatsächlich verwendete Identität, sodass eine falsche sichtbar ist, statt sich als kaputte App zu tarnen:

"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 ist task | explicit | credential_id (ein von Ihnen benanntes Konto) oder env | env_default (das gespeicherte Konto der Umgebung). submitted ist nur wahr, wenn Anmeldedaten tatsächlich eingegeben und übermittelt wurden; reason sagt, was passiert ist (z. B. offscope_host, restored_session), und detail ist, wenn vorhanden, eine menschenlesbare Erklärung davon — bei einer offscope_host-Verweigerung nennt es den Host und wie man ihn autorisiert. credentialWarning erscheint nur, wenn Sie ein Konto benannt haben und eine Umgebungsstandard für ein anderes Konto tatsächlich übermittelt wurde — niemals für eine Anmeldung, die verweigert oder übersprungen wurde. loginError erscheint, wenn ein benanntes Konto nicht aufgelöst werden konnte und der Lauf sich weigerte, ein anderes zu ersetzen.

Jeder erfolgreiche Lauf gibt einen browserSession-Block zusammen mit dem Screenshot zurück — vorsignierte S3-URLs für das erfasste HAR (vollständige Netzwerkablaufverfolgung) und Konsolenprotokoll (jede JS-Konsolenmeldung). Verwenden Sie sie, um Nachlade-Schleifen, Hydrierungsfehler und andere Laufzeitprobleme zu erkennen, die Typprüfungen und Unit-Tests bestehen:

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

URLs sind kurzlebige vorsignierte S3 — rufen Sie die übergeordnete Ausführung über executions {action:"get", uuid} erneut ab, um zu erneuern. harStatus / consoleLogStatus unterscheiden 'downloaded' (URL abrufbar), 'not_available' (Seite hat nichts ausgegeben), 'failed' (Erfassung unterbrochen). Bei einem frischen Lauf sind die URLs häufig null, weil die Erfassung asynchron nach dem Abschluss des Agenten hochlädt — pollen Sie executions {action:"get", uuid: executionId}, bis der Status 'downloaded' erreicht. Autorisierungs- / Cookie- / token/secret/api_key-Header werden serverseitig bereinigt, bevor die Artefakte gespeichert werden.

trigger_crawl

Löst einen serverseitigen Browser-Agenten-Crawl aus, um den Wissensgraphen des Projekts zu füllen. Localhost-URLs tunneln automatisch. Gibt {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} mit knowledgeGraph.skipped === false bei erfolgreicher Aufnahme zurück. crawlSummary und knowledgeGraph tragen nur die Schlüssel, die die Crawl-/Import-Knoten des Backends meldeten — eine fehlende Anzahl ist abwesend, niemals eine ausgefüllte 0. Der browserSession-Block (HAR + Konsolenprotokoll-URLs, gleiche Form wie oben) ist auch bei abgeschlossenen Crawls vorhanden.

probe_page

Leichtgewichtiger No-LLM-Stapelseitensondierer. Übergeben Sie 1-20 URLs; jede navigiert, beruhigt sich auf Inhalt (das DOM wird ruhig, begrenzt — niemals auf Netzwerkstille, die eine Live-App nie erreicht) und gibt den gerenderten Zustand zurück — Screenshot + Seitenmetadaten + strukturierte Konsolenfehler + Netzwerkzusammenfassung. Keine Agentenschleife, keine LLM-Kosten, keine Szenario-Assertions. Verwenden Sie es für „Habe ich gerade /settings kaputt gemacht?", Multi-Routen-Rauchtest nach einem Refactoring, CI-Pro-PR-Durchläufe und schnelle Ist-es-auf-Prüfungen, bei denen die 60-150s-Agentenschleife von check_app_in_browser übertrieben ist.

Parameter	Typ	Beschreibung
targets	Array erforderlich	1-20 Einträge: [{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	Zeichenkette erforderlich	Öffentliche URL oder localhost (automatisch getunnelt)
targets[].waitForLoadState	Aufzählung	'domcontentloaded' (Standard, + ein begrenztes Inhalts-Beruhigen) / 'load' (wartet auch auf Drittanbieter-Einbettungen) / 'networkidle' (akzeptiert, niemals ausgegeben — das Netzwerk einer Live-Site wird nicht im Leerlauf)
targets[].waitForSelector	Zeichenkette	Optionaler CSS-Selektor, auf den nach der Navigation gewartet wird
targets[].timeoutMs	Zahl	Timeout pro URL, 1000-30000 (Standard 10000)
includeHtml	Boolesch	Rohes HTML in jedem Ergebnis zurückgeben (Standard false)
captureScreenshots	Boolesch	Ein PNG pro Ziel zurückgeben (Standard true)

Alle Ziele in einem Stapel teilen einen Sitzungstunnel, aber nur Stapel mit demselben Port (oder alle öffentlich) teilen eine einzelne Backend-Ausführung — 5 URLs auf einem Port in einem Aufruf ist dramatisch schneller als 5 parallele Einzel-URL-Aufrufe. Ein Stapel, der mehrere lokale Ports mischt, zerlegt sich in eine sequenzielle Backend-Ausführung pro Portgruppe (immer noch ein Aufruf, immer noch ein zusammengeführtes results[] in Ihrer ursprünglichen Reihenfolge, aber N Backend-Roundtrips statt einem — langsamer, nicht abgelehnt). Das error-Feld pro URL bewahrt die Stapelresilienz: Ein einzelnes fehlgeschlagenes Ziel schlägt die anderen nicht fehl. networkSummary-Aggregationsschlüssel ist origin + pathname — Refetch-Schleifen (?n=0..4 trifft wiederholt denselben Endpunkt) werden zu einem einzelnen Eintrag mit der Anzahl zusammengefasst, sodass /api/poll, das mit count: 47 erscheint, das umsetzbare „Endlosschleife beim Refetch“-Signal ist, das Benutzer ursprünglich angefordert haben.

Leistungsbudget: <10s für 1 URL, <25s für 20. Ein toter Localhost-Port gibt LocalServerUnreachable in <2s zurück, ohne eine Workflow-Ausführung zu verbrauchen.

project

Aktion	Parameter	Ergebnis
get	{uuid}	Kuratierte Projektdetails
list	{q?, page?, pageSize?}	Paginierte Zusammenfassungen
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	Erstelltes Projekt

Team und Repository werden entweder per UUID oder per Name aufgelöst (case-insensitive exakte Übereinstimmung; NotFound wenn keins, AmbiguousMatch wenn mehrere). Es gibt kein update/delete — benennen Sie ein Projekt um oder löschen Sie es über die DebuggAI-Web-App.

environment

Aktion	Parameter	Ergebnis
get	{uuid, projectUuid?}	Umgebung mit inline eingefügten Anmeldedaten (Passwörter werden nie zurückgegeben)
list	{projectUuid?, q?, page?, pageSize?}	Paginierte Umgebungen, jeweils mit einem Anmeldedaten-Array
create	{name, url, description?, projectUuid?, credentials?, authorizedCredentialHosts?}	Erstellte Umgebung (optional mit Anmeldedaten-Seeds)
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?}	Gepatchte Umgebung; Anmeldedaten-Operationen laufen entfernen → aktualisieren → hinzufügen
delete	{uuid, projectUuid?, confirm?}	Löscht Umgebung (kaskadiert Anmeldedaten) — erfordert Bestätigung
sessions	{uuid, username?, credentialId?}	Erfasste Login-Sitzungen der Umgebung, pro Konto, jeweils mit eigenem isUsable
clearSessions	{uuid, username?, credentialId?, confirm?}	Macht sie ungültig, sodass der nächste Lauf sich wirklich einloggt — ungezielte Löschungen erfordern Bestätigung

projectUuid wird automatisch aus dem Git-Repository aufgelöst, wenn es weggelassen wird. Fehler pro Anmeldedatum erscheinen in credentialWarnings[], ohne die Umgebungsoperation zu blockieren.

authorizedCredentialHosts listet Hosts auf, auf denen ein Lauf außer dem eigenen Host der App Anmeldedaten dieser Umgebung verwenden darf — für Cross-Domain-SSO fügen Sie hier den IdP-Host hinzu (z. B. ["auth.example.com"]). Nur nackte Hostnamen: kein Schema, Pfad, Port oder Wildcard (Subdomains des App-Hosts sind bereits abgedeckt). Bei update ersetzt es die Liste; [] leert sie. get/list geben sie zurück, wenn der Server sie unterstützt. Die Antwort spiegelt die gespeicherte Liste wider; wenn der Server sie nicht persistiert hat (ältere Server ignorieren das Feld), trägt das Ergebnis authorizedCredentialHostsWarning: {requested, returned} statt eines stillen Erfolgs.

sessions / clearSessions verwalten die warmen authentifizierten Sitzungen, die das Backend wiederverwendet, um den Login zu überspringen (siehe Sitzungswiederverwendung). Sitzungsinhalte werden nie zurückgegeben — ein Sitzungscookie ist eine Inhaber-Anmeldedaten. clearSessions markiert Sitzungen als ungültig, statt die Zeilen zu löschen, sodass die Wiederverwendung sofort stoppt, während der Erfassungsverlauf lesbar bleibt.

test_suite

Aktion	Parameter	Ergebnis
list	{projectUuid|projectName, search?, page?, pageSize?}	Paginierte Suiten mit Status + Erfolgsquote
create	{name, description, projectUuid|projectName}	Erstellte Suite
run	{suiteUuid|(suiteName+project), targetUrl?}	Löst alle Tests asynchron aus
results	{suiteUuid|(suiteName+project)}	Suite + Ergebnisse pro Test
delete	{suiteUuid|(suiteName+project), confirm?}	Soft-Delete — erfordert Bestätigung

test_case

Aktion	Parameter	Ergebnis
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	Erstellter Testfall (nicht automatisch ausgeführt)
update	{testUuid, name?, description?, agentTaskDescription?}	Gepatchter Testfall
delete	{testUuid, confirm?}	Soft-Delete — erfordert Bestätigung

executions

Aktion	Parameter	Ergebnis
get	{uuid}	Vollständige Details (nodeExecutions + Zustand + errorInfo) + Screenshot/GIF-Artefakte
list	{status?, projectUuid?, page?, pageSize?}	Paginierte Zusammenfassungen

404 vom Backend erscheint als isError: true mit {error: 'NotFound', message, uuid}. Anmeldedaten werden immer ohne Passwörter zurückgegeben.

Paginierung

Jede list-Antwort ist paginiert. Antwortform:

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

Übergeben Sie optional page (1-indexiert, Standard 1) und pageSize (Standard 20, max. 200; übermäßige Werte werden begrenzt). Keine Antwort wird jemals stillschweigend abgeschnitten.

Ein get gibt das eine Objekt unter seinem Singularnamen zurück — {project}, {execution}, {project, environment} — ohne pageInfo.

Ressourcen

Neben Tools stellt der Server die schreibgeschützten Entitäten als MCP-Ressourcen bereit, damit Clients sie durchsuchen und als Kontext @-erwähnen können:

URI	Was
debugg-ai://projects	Alle Projekte (erste Seite)
debugg-ai://environments	Umgebungen für das automatisch erkannte Projekt
debugg-ai://executions	Aktuelle Ausführungen (erste Seite)
debugg-ai://project/{uuid}	Ein Projekt, vollständige Details
debugg-ai://environment/{uuid}	Eine Umgebung (Anmeldedaten inline, Passwörter geschwärzt)
debugg-ai://execution/{uuid}	Eine Ausführung, vollständige Knotendetails + Artefaktlinks

Lesezugriffe werden an dieselben Handler wie die project / environment / executions-Tools weitergeleitet, sodass Daten und Authentifizierung identisch sind. Ressourcen sind additiv — Clients ohne Ressourcenunterstützung verwenden weiterhin die Tools.

Sicherheitsinvarianten

• Passwörter sind schreibgeschützt. Sie erscheinen nie in einem Antworttext eines Tools.
• Tunnel-URLs (*.tunnel.debugg.ai und das zurückgezogene *.ngrok.debugg.ai, auf das historische Läufe noch verweisen) werden aus allen Browser-Agent-Antworten entfernt, einschließlich agentenverfasstem Text.
• 404s vom Backend erscheinen als isError: true mit {error: 'NotFound', ...}, nie als ausgelöste Ausnahmen.
• Fehlendes DEBUGGAI_API_KEY erscheint als strukturierter Tool-Fehler beim ersten Aufruf — der Server registriert und listet Tools weiterhin normal.

Migration auf v6.0.0 (Backend-Urteile, kein MCP-verfasster Text)

Ein Lauf-Urteil ist pass | fail | error, wobei das reason des Backends wörtlich weitergegeben wird. Ein Lauf, der nie einen Test versucht hat, liest outcome: null, skipped: true, skipReason.

Entfernt	Ersatz
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 bei Warnungen und Ergebnissen	strukturierte Felder nur

Vollständige Liste: CHANGELOG.md 6.0.0.

Migration auf v3.0.0 (aktionsbasierte Tools)

v3 konsolidierte die 20 Verben-Tools in 8 aktionsbasierte Tools. Altes Tool → neues tool {action}:

Entfernt	Ersatz
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project, delete_project	Entfernt — verwenden Sie die DebuggAI-Web-App
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-Parameter	Entfernt — immer headless

delete-Aktionen erfordern jetzt Bestätigung (Elicitation-Prompt oder confirm: true). Clients übernehmen die neue Oberfläche beim MCP-Neustart.

Migration von v1.x (Breaking Change in v2.0.0)

v2 reduzierte eine 22-Tool-Oberfläche auf 11. Altes-Tool → neues-Tool-Zuordnung:

Entfernt	Ersatz
list_projects, get_project	search_projects (UUID-Modus vs. Filter-Modus)
list_environments, get_environment	search_environments
list_credentials, get_credential	search_environments — Anmeldedaten inline bei jeder Umgebung
create_credential	create_environment({credentials: [...]})-Seed oder update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams, list_repos	create_project({teamName, repoName}) — Namensauflösung mit Mehrdeutigkeitsbehandlung
list_executions, get_execution	search_executions
cancel_execution	Entfernt — Backend-Fahrplan ist automatisch

Antwortform-Änderungen: das nackte count-Feld bei Listenantworten ist weg — verwenden Sie pageInfo.totalCount.

Konfiguration

Umgebungsvariable	Erforderlich	Zweck
DEBUGGAI_API_KEY	ja	Backend-API-Schlüssel. Aliase: DEBUGGAI_API_TOKEN, DEBUGGAI_JWT_TOKEN.
DEBUGGAI_API_URL	nein	Backend-Basis-URL. Standard: https://api.debugg.ai.
DEBUGGAI_TOKEN_TYPE	nein	token (Standard) oder bearer.
DEBUGGAI_EVAL_TEMPLATE	nein	Überschreibt den Slug des App-Evaluierungs-Workflows, an den check_app_in_browser sendet. Standard: flow/e2es/app-eval. Der Versand pinnt auf diesen Slug, sodass eine Backend-Vorlagenumbenennung ihn nicht brechen kann.
LOG_LEVEL	nein	error / warn / info (Standard) / debug.
POSTHOG_API_KEY	nein	Überschreibt den eingebetteten Telemetrie-Projektschlüssel (z. B. privater Fork).
DEBUGGAI_TELEMETRY_DISABLED	nein	Auf 1 / true / yes / on setzen, um Telemetrie vollständig zu deaktivieren.

DEBUGGAI_API_KEY=your_api_key

Remote / HTTP-Transport (optional)

Standardmäßig spricht der Server stdio (lokales npx). Er kann stattdessen als gehostetes, mehrbenutzerfähiges Remote-MCP über zustandsloses Streamable HTTP + OAuth laufen:

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

Es ist ein OAuth-Ressourcenserver: Jedes POST /mcp benötigt Authorization: Bearer <token>; fehlende/ungültige Token erhalten eine 401 mit einem WWW-Authenticate, das auf die RFC-9728-Metadaten verweist, und Clients führen den OAuth-Flow gegen den beworbenen Autorisierungsserver aus. Das Bearer-Token ist anfragebezogen — api.debugg.ai validiert es.

Endpunkt	Zweck
POST /mcp	MCP Streamable HTTP (bearer-geschützt)
GET /.well-known/oauth-protected-resource	RFC-9728-Metadaten (Autorisierungsserver-Erkennung)
GET /health	Load-Balancer / ECS-Healthcheck

Umgebungsvariable	Standard	Zweck
DEBUGGAI_MCP_TRANSPORT	stdio	Auf http für den Remote-Transport setzen
PORT	3000	HTTP-Listen-Port
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	Öffentliche Ressourcen-URL dieses Servers (RFC 9728 resource)
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	Autorisierungsserver, der Clients beworben wird
DEBUGGAI_TOKEN_TYPE	token	Auf bearer setzen, damit OAuth-Token als Authorization: Bearer weitergeleitet werden

stdio-Installationen benötigen keine davon.

Multi-Replica-Bereitstellungen (Go/No-Go vor dem Rollout): Tunnelzustand (der Sitzungstunnel, seine Caddy-Instanz und seine Port-Routen-Sperre) ist prozessintern, pro Aufrufer über einen Hash des Bearer-Tokens — es gibt keine Cross-Prozess-Koordination. Wenn mehrere Replicas hinter einem einfachen Round-Robin-Load-Balancer laufen, können Aufrufe eines Aufrufers auf verschiedene Replicas landen und einen Tunnel pro Replica, die sie treffen, statt einen für die gesamte Sitzung erzeugen (begrenzt durch die Replica-Anzahl, selbstheilend über die bestehende 55-minütige Leerlauf-Autoabschaltung — nie ein Cross-Sitzungs-Korrektheitsfehler, da jeder einzelne Tool-Aufruf für seine gesamte Dauer auf einer Replica bleibt). Um das beabsichtigte „ein Tunnel pro Sitzung“-Verhalten bei einer Multi-Replica-HTTP-Bereitstellung zu erreichen, konfigurieren Sie sitzungsaffines Routing am Load-Balancer (sticky/consistent-hash, basierend auf derselben Identität, von der getSessionKey() abgeleitet wird — in der Praxis das Authorization-Bearer-Token des Aufrufers). Siehe docs/local-tunnel-multiplexer-architecture-2026-07-31.md §2.1 für die vollständige Begründung und den ehrlichen Degradationspfad, falls dies nicht konfiguriert ist.

Telemetrie

Der MCP-Server wird standardmäßig mit aktivierter Telemetrie ausgeliefert – ein eingebetteter, schreibgeschützter PostHog-Projektschlüssel (phc_*), damit das Team Cache-Trefferquoten, Abfragefrequenz, Tunnel-Zuverlässigkeit und andere Betriebskennzahlen über die gesamte Installationsbasis hinweg beobachten kann. Erfasste Ereignisse:

Ereignis	Zeitpunkt
tool.executed / tool.failed	Pro Tool-Aufruf
workflow.executed	Pro Browser-Agent-Ausführung (enthält pollCount, durationMs, finalIntervalMs)
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	Pro Tunnel-Lebenszyklus-Ereignis
template.lookup / project.lookup	Cache-Treffer/Fehlschlag mit durationMs bei Kaltaufruf

Datenschutz-Haltung:

• Die eindeutige ID ist SHA-256(api_key).slice(0, 16) – niemals der rohe Schlüssel, keine personenbezogenen Daten.
• phc_*-Schlüssel sind gemäß PostHog-Konvention schreibgeschützt; sicher in den Quellcode einzubetten.
• Setzen Sie DEBUGGAI_TELEMETRY_DISABLED=1, um sich vollständig abzumelden (löst einen No-Op-Anbieter aus; keine Ereignisse verlassen den Prozess).

Der aktive Modus wird beim Start protokolliert:

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)

Lokale Entwicklung

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

Die Evaluierungssuite startet den gebauten MCP-Server als Unterprozess, testet jedes Tool gegen ein echtes Backend und schreibt pro Ablauf Artefakte nach scripts/evals/artifacts/<timestamp>/. Siehe scripts/evals/flows/ für die einzelnen Szenarien.

MCP-Registrierung: debugg-ai-local vs. debugg-ai

Dieses Repository enthält eine .mcp.json, die einen projektbezogenen Server namens debugg-ai-local registriert, der auf node dist/index.js verweist – den frisch gebauten lokalen Code. Sie wird nur aktiviert, wenn das Arbeitsverzeichnis von Claude Code dieses Repository ist.

Ihre anderen Projekte sollten die benutzerbezogene debugg-ai-Registrierung verwenden, die aus dem veröffentlichten npm-Paket bezieht:

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

Nachdem Sie Code hier bearbeitet haben, führen Sie npm run mcp:local aus (das nur neu baut), damit der nächste Aufruf von debugg-ai-local Ihre Änderungen übernimmt.

Links

Dashboard · Dokumentation · Issues · Discord

---

Apache-2.0-Lizenz © 2025 DebuggAI