Debugg AI

offiziell

Ermöglicht es Ihren Code-Generierungsagenten, 0-Konfigurations-End-to-End-Tests gegen neue Codeänderungen in entfernten Browsern über die Debugg AI-Testplattform zu erstellen und auszuführen.

GitHub

Dieses MCP ausprobierenGesponsert

Was kann man mit Debugg AI MCP machen?

KI-Browsertests ausführen — Bitten Sie den Assistenten, check_app_in_browser gegen eine beliebige URL oder localhost auszuführen, und beschreiben Sie in natürlicher Sprache, was getestet werden soll. Sie erhalten Bestehen/Nichtbestehen-Ergebnisse mit Screenshots.
Mehrere Seiten schnell prüfen — Verwenden Sie probe_page, um 1–20 URLs in einem Batch auf Konsolenfehler, Netzwerkprobleme und gerenderten Zustand zu prüfen – ohne LLM-Kosten oder Agentenschleifen.
Knowledge-Graph-Crawls auslösen — Rufen Sie trigger_crawl auf, um einen serverseitigen Browser-Agenten-Crawl zu starten, der den Wissensgraphen des Projekts mit HAR- und Konsolenprotokoll-Artefakten befüllt.
Testsuiten und Testfälle verwalten — Erstellen, ausführen und überprüfen Sie Ergebnisse für test_suite- und test_case-Entitäten, mit Ergebnissen und Bestehensquoten pro Test.
Ausführungsartefakte prüfen — Rufen Sie vollständige Ausführungsdetails über executions ab, einschließlich Screenshots, HAR-Netzwerkspuren und Konsolenprotokollen, um Laufzeitprobleme zu debuggen.
Umgebungen und Sitzungen verwalten — Erstellen oder aktualisieren Sie Umgebungen mit Anmeldedaten über environment und verwenden Sie sessions/clearSessions, um die Wiederverwendung warmer Login-Sitzungen zu steuern.

Dokumentation

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, genauso wie dieses Projekt bereits für die ngrok-Binärdatei vorgeht — im Normalfall müssen Sie nichts selbst installieren. Falls dieser Download nie ausgeführt wurde (npm install --ignore-scripts, eine Offline-/Air-Gapped-Installation), zeigen Sie mit 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 stiller Hänger. Öffentliche URL-Aufrufe, alle Nicht-Browser-Werkzeuge 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 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 schlagen mit CaddyBinaryNotFoundError innerhalb dieses Images fehl, bis es neu gebaut (Dockerfile korrigiert) und neu veröffentlicht wird, oder CADDY_BIN auf ein separat eingebackenes zeigt. Öffentliche 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 wichtigsten Werkzeuge sind check_app_in_browser (vollständiger KI-Agent) und probe_page (leichtgewichtiger Seiten-Probe ohne LLM). 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 über ngrok getunnelt.

Parameter	Typ	Beschreibung
`description`	string erforderlich	Was zu testen ist (natürliche Sprache)
`url`	string erforderlich	Ziel-URL — `http://localhost:3000` wird automatisch getunnelt
`environmentId`	string	UUID einer bestimmten Umgebung
`credentialId`	string	UUID einer bestimmten Anmeldedaten
`credentialRole`	string	Anmeldedaten nach Rolle auswählen (z. B. `admin`, `guest`)
`username`	string	Benutzername für die Anmeldung (flüchtig — nicht gespeichert)
`password`	string	Passwort für die Anmeldung (flüchtig — nicht gespeichert)
`loginCredentials`	array	Konten für Anmeldungen, auf die der Agent während der Aufgabe trifft — `[{username, password, label?}]`
`useEnvironmentCredentials`	boolean	Standard `true`. `false` verbietet das automatische Ausfüllen der gespeicherten Anmeldedaten der Umgebung; ohne benanntes Konto bedeutet es überhaupt nicht anmelden
`freshSession`	boolean	Standard `false`. `true` erzwingt eine echte Anmeldung anstelle der Wiederverwendung der für dieses Konto gehaltenen warmen Sitzung
`auth`	object	Authentifizierungs-Vorbedingung — `{precondition, entryUrl, deepUrl, environmentId, username, password}`
`repoName`	string	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 Testreihen 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 gespeicherten Anmeldedaten der Umgebung zurück, und die Ablehnung des falschen Kontos durch die App sieht aus wie ein Anwendungsfehler. Alles, was Sie als Parameter übergeben, schlägt die Umgebungsstandardwerte für jede Anmeldung im Lauf, nicht nur für die erste:

username / password (oder credentialId / credentialRole) — die Identität des Laufs.
auth.username / auth.password — legt die Vorbedingungs-Anmeldung 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 eine Aufteilung 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.

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, anstatt 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 ohne 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-basiert, 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, anstatt sich als kaputte App zu tarnen:

"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 ist task | explicit | credential_id (ein von Ihnen benanntes Konto) oder env | env_default (das gespeicherte Konto der Umgebung). credentialWarning erscheint nur, wenn Sie ein Konto benannt haben und trotzdem ein Umgebungsstandard verwendet 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 — vorab signierte S3-URLs für das erfasste HAR (vollständige Netzwerkablaufverfolgung) und Konsolenprotokoll (jede JS-Konsolenmeldung). Verwenden Sie sie, um Refetch-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 vorab signierte S3 — holen Sie die übergeordnete Ausführung über executions {action:"get", uuid} erneut, 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 hochlädt, nachdem der Agent fertig ist — 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 werden automatisch getunnelt. Gibt {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} mit knowledgeGraph.imported === true bei erfolgreicher Aufnahme zurück. Der browserSession-Block (HAR- + Konsolenprotokoll-URLs, gleiche Form wie oben) ist auch bei abgeschlossenen Crawls vorhanden.

`probe_page`

Leichtgewichtiger Seiten-Probe ohne LLM für Stapel. Ü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-Smoke nach einem Refactor, CI-Pro-PR-Durchläufe und schnelle Ist-es-verfügbar-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`	string erforderlich	Öffentliche URL oder localhost (automatisch getunnelt)
`targets[].waitForLoadState`	enum	`'domcontentloaded'` (Standard, + eine begrenzte Inhaltsberuhigung) / `'load'` (wartet auch auf Drittanbieter-Einbettungen) / `'networkidle'` (akzeptiert, nie ausgegeben — das Netzwerk einer Live-Site wird nicht im Leerlauf)
`targets[].waitForSelector`	string	Optionaler CSS-Selektor, auf den nach der Navigation gewartet werden soll
`targets[].timeoutMs`	number	Timeout pro URL, 1000–30000 (Standard 10000)
`includeHtml`	boolean	Rohes HTML in jedem Ergebnis zurückgeben (Standard false)
`captureScreenshots`	boolean	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 lässt die anderen nicht fehlschlagen.

Der networkSummary-Aggregationsschlüssel ist origin + pathname — Refetch-Schleifen (?n=0..4, das wiederholt denselben Endpunkt trifft) kollabieren in einen einzelnen Eintrag mit der Anzahl, sodass /api/poll, das mit count: 47 auftaucht, das umsetzbare „unendliche Refetch-Schleife"-Signal ist, das Benutzer ursprünglich angefordert haben.

Leistungsbudget: <10s für 1 URL, <25s für 20. Localhost-Totport 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 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 aus der DebuggAI-Web-App.

`environment`

Aktion	Parameter	Ergebnis
`get`	`{uuid, projectUuid?}`	Umgebung mit eingebetteten 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?}`	Erstellte Umgebung (optional mit Anmeldedaten)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	Aktualisierte 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, mit `isUsable` und einem `usableCount`
`clearSessions`	`{uuid, username?, credentialId?, confirm?}`	Macht sie ungültig, sodass der nächste Lauf sich wirklich einloggt — unscoped Löschungen erfordern Bestätigung

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

sessions / clearSessions verwalten die warmen authentifizierten Sitzungen, die das Backend wiederverwendet, um den Login zu überspringen (siehe Sitzungswiederverwendung). Sitzungsinhalte werden nie zurückgegeben — ein Sitzungs-Cookie ist eine Inhaber-Anmeldedatei. clearSessions markiert Sitzungen als ungültig, anstatt 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?}`	Aktualisierter Testfall
`delete`	`{testUuid, confirm?}`	Soft-Delete — erfordert Bestätigung

`executions`

Aktion	Parameter	Ergebnis
`get`	`{uuid}`	Vollständige Details (`nodeExecutions` + Status + 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 Filtermodus-Antwort ist paginiert. Antwortstruktur:

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

Übergib optional page (1-basiert, Standard 1) und pageSize (Standard 20, max. 200; übermäßig große Werte werden begrenzt). Keine Antwort wird jemals stillschweigend abgeschnitten.

Ressourcen

Neben den 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	Inhalt
`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 + Artefakt-Links

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

Sicherheitsinvarianten

Passwörter sind schreibgeschützt. Sie erscheinen nie im Antwortkörper eines Tools.
Tunnel-URLs (*.ngrok.debugg.ai) werden aus allen Browser-Agent-Antworten entfernt, einschließlich von Agenten verfasstem Text.
404s vom Backend erscheinen als isError: true mit {error: 'NotFound', ...}, nie als geworfene Ausnahmen.
Fehlendes DEBUGGAI_API_KEY erscheint als strukturierter Tool-Fehler beim ersten Aufruf — der Server registriert und listet Tools weiterhin normal.

Migration zu v3.0.0 (aktionsbasierte Tools)

v3 hat die 20 Verb-basierten Tools zu 8 aktionsbasierten Tools konsolidiert. 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 — nutze 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 eine 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 hat eine Oberfläche mit 22 Tools auf 11 reduziert. Zuordnung altes Tool → neues Tool:

Entfernt	Ersatz
`list_projects`, `get_project`	`search_projects` (UUID-Modus vs. Filtermodus)
`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

Änderungen der Antwortstruktur: Das nackte count-Feld in Listenantworten ist entfernt — nutze 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 ist an diesen Slug gebunden, 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 ein 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` setzen für den Remote-Transport
`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): Der Tunnelzustand (die ngrok-Sitzungstunnel, seine Caddy-Instanz und seine Port-Routen-Sperre) ist prozessintern, pro Aufrufer über einen Hash des Bearer-Tokens — es gibt keine prozessübergreifende Koordination. Der Betrieb mehrerer Replicas hinter einem einfachen Round-Robin-Load-Balancer bedeutet, dass Aufrufe eines Aufrufers auf verschiedenen Replicas landen können und einen Tunnel pro Replica, das sie treffen, erzeugen, statt einen für die gesamte Sitzung (zusätzliche ngrok-Kosten, begrenzt durch die Replica-Anzahl, selbstheilend über die bestehende 55-Minuten-Leerlauf-Autoabschaltung — nie ein sitzungsübergreifender Korrektheitsfehler, da jeder einzelne Tool-Aufruf für seine gesamte Dauer auf einer Replica bleibt). Um das gewünschte Verhalten „ein Tunnel pro Sitzung" bei einer Multi-Replica-HTTP-Bereitstellung zu erreichen, konfiguriere sitzungsaffines Routing am Load-Balancer (sticky/consistent-hash, basierend auf derselben Identität, die getSessionKey() ableitet — 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 mit standardmäßig aktivierter Telemetrie ausgeliefert — ein eingebetteter schreibgeschützter PostHog-Projektschlüssel (phc_*), damit das Team Cache-Trefferquoten, Poll-Kadenz, Tunnelzuverlässigkeit und andere Betriebskennzahlen über die Installationsbasis hinweg beobachten kann. Erfasste Ereignisse:

Ereignis	Wann
`tool.executed` / `tool.failed`	Pro Tool-Aufruf
`workflow.executed`	Pro Browser-Agent-Ausführung (trägt `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) — nie der rohe Schlüssel, keine personenbezogenen Daten.
phc_*-Schlüssel sind gemäß PostHog-Konvention schreibgeschützt; sicher in Quellcode einzubetten.
Setze DEBUGGAI_TELEMETRY_DISABLED=1, um vollständig abzulehnen (löst zu einem No-Op-Anbieter auf; 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-Flow-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 zeigt — den frisch gebauten lokalen Code. Sie wird nur aktiv, wenn das Arbeitsverzeichnis von Claude Code dieses Repository ist.

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

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

Nach Codeänderungen hier führe npm run mcp:local aus (das nur neu baut), damit der nächste Aufruf von debugg-ai-local deine Änderungen übernimmt.

Links

Dashboard · Dokumentation · Issues · Discord