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

Was kann man mit Debugg AI MCP machen?

Führen Sie einen KI-Browser-Agenten gegen eine beliebige URL aus — beschreiben Sie in natürlicher Sprache, was getestet werden soll, und check_app_in_browser navigiert, interagiert und gibt Bestehen/Nichtbestehen mit Screenshots zurück.
Durchsuchen Sie mehrere Seiten ohne LLM-Kosten — senden Sie bis zu 20 URLs an probe_page für schnelle Screenshots, Konsolenfehler und Netzwerkzusammenfassungen in einem einzigen Batch.
Lösen Sie einen Knowledge-Graph-Crawl aus — verwenden Sie trigger_crawl, damit ein KI-Agent Ihre App erkundet und den Knowledge-Graph des Projekts befüllt.
Verwalten Sie Testsuiten und Testfälle — erstellen, listen, ausführen und überprüfen Sie Ergebnisse von Testsuiten über test_suite und definieren Sie einzelne Fälle mit test_case.
Überprüfen Sie Ausführungsartefakte — rufen Sie vollständige Ausführungsdetails, Screenshots, HAR-Traces und Konsolenprotokolle über executions ab, um Fehler zu debuggen.
Durchsuchen Sie Projekte, Umgebungen und Ausführungen als Ressourcen — referenzieren Sie Entitäten direkt über debugg-ai://-URIs für Kontext, ohne Tools aufzurufen.

Dokumentation

Debugg AI — MCP Server

KI-gestütztes Browser-Testing über das Model Context Protocol. Verweisen Sie auf eine beliebige URL (oder localhost) und beschreiben Sie, was getestet werden soll – ein KI-Agent durchsucht Ihre App und liefert Bestanden/Fehlgeschlagen mit Screenshots zurück.

Einrichtung

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

Holen Sie sich 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

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 (vollständiger KI-Agent) und probe_page (schlanke Seitenprüfung 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, sofern unterstützt, andernfalls confirm: true).

Browser

`check_app_in_browser`

Führt einen KI-Browser-Agenten für Ihre App aus. Der Agent navigiert, interagiert und berichtet mit Screenshots zurück. Localhost-URLs werden automatisch über ngrok getunnelt.

Parameter	Typ	Beschreibung
`description`	string erforderlich	Was getestet werden soll (natürliche Sprache)
`url`	string erforderlich	Ziel-URL – `http://localhost:3000` wird automatisch getunnelt
`environmentId`	string	UUID einer bestimmten Umgebung
`credentialId`	string	UUID eines bestimmten Berechtigungsnachweises
`credentialRole`	string	Berechtigungsnachweis nach Rolle auswählen (z. B. `admin`, `guest`)
`username`	string	Benutzername für die Anmeldung (flüchtig – nicht persistent)
`password`	string	Passwort für die Anmeldung (flüchtig – nicht persistent)
`repoName`	string	Automatisch erkannten Git-Repo-Namen überschreiben (z. B. `my-org/my-repo`)

Ein fokussierter Check pro Aufruf. Der Agent hat ein internes Budget von ca. 25 Schritten; teilen Sie umfangreichere Suiten auf mehrere Aufrufe auf.

Jeder erfolgreiche Durchlauf liefert einen browserSession-Block zusammen mit dem Screenshot – vorab signierte S3-URLs für die erfasste HAR (vollständige Netzwerkaufzeichnung) und das Konsolenprotokoll (jede JS-Konsolennachricht). Verwenden Sie sie, um Refetch-Schleifen, Hydratationsfehler 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-URLs – rufen Sie die übergeordnete Ausführung über executions {action:"get", uuid} erneut ab, um sie zu erneuern. harStatus / consoleLogStatus unterscheiden 'downloaded' (URL abrufbar), 'not_available' (Seite hat nichts ausgegeben), 'failed' (Erfassung fehlgeschlagen). Bei einem neuen Durchlauf sind die URLs häufig null, da die Erfassung asynchron hochgeladen wird, 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 persistiert werden.

`trigger_crawl`

Startet einen serverseitigen Browser-Agenten-Crawl, um den Wissensgraphen des Projekts zu befü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`

Schlanke Batch-Seitenprüfung ohne LLM. Übergeben Sie 1-20 URLs; jede navigiert, wartet auf das Laden und gibt den gerenderten Zustand zurück – Screenshot + Seitenmetadaten + strukturierte Konsolenfehler + Netzwerkzusammenfassung. Keine Agent-Schleife, keine LLM-Kosten, keine Szenario-Assertions. Verwenden Sie es für „Habe ich gerade /settings kaputt gemacht?“, Multi-Route-Smoke-Tests nach einem Refactor, CI-Prüfungen pro PR und schnelle Ist-es-verfügbar-Checks, bei denen die 60-150s dauernde Agent-Schleife 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	`'load'` (Standard) / `'domcontentloaded'` / `'networkidle'`
`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)

Der gesamte Batch teilt sich eine einzige Backend-Ausführung + Browser-Sitzung + Tunnel – 5 URLs in einem Aufruf sind dramatisch schneller als 5 parallele Einzel-URL-Aufrufe. Das error-Feld pro URL bewahrt die Batch-Resilienz: Ein einzelnes fehlgeschlagenes Ziel führt nicht zum Fehlschlag der anderen.

Der networkSummary-Aggregationsschlüssel ist origin + pathname – Refetch-Schleifen (?n=0..4, die wiederholt denselben Endpunkt treffen) werden zu einem einzigen Eintrag mit der Anzahl zusammengefasst, sodass /api/poll, das mit count: 47 erscheint, das umsetzbare Signal für eine „unendliche Refetch-Schleife“ ist, nach dem ursprünglich gefragt wurde.

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?}`	Seitenweise Zusammenfassungen
`create`	`{name, platform, (teamUuid\|teamName), (repoUuid\|repoName)}`	Erstelltes Projekt

Team und Repo werden entweder über die UUID oder den Namen aufgelöst (exakte Übereinstimmung ohne Berücksichtigung der Groß-/Kleinschreibung; NotFound, wenn keiner, AmbiguousMatch, wenn mehrere). Es gibt kein update/delete – benennen oder löschen Sie ein Projekt über die DebuggAI-Webanwendung.

`environment`

Aktion	Parameter	Ergebnis
`get`	`{uuid, projectUuid?}`	Umgebung mit eingebetteten Berechtigungsnachweisen (Passwörter werden nie zurückgegeben)
`list`	`{projectUuid?, q?, page?, pageSize?}`	Seitenweise Umgebungen, jede mit einem Array von Berechtigungsnachweisen
`create`	`{name, url, description?, projectUuid?, credentials?}`	Erstellte Umgebung (optional mit Berechtigungsnachweisen bestückt)
`update`	`{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}`	Gepatchte Umgebung; Berechtigungsoperationen laufen entfernen → aktualisieren → hinzufügen
`delete`	`{uuid, projectUuid?, confirm?}`	Löscht Umgebung (kaskadiert Berechtigungsnachweise) – erfordert Bestätigung

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

`test_suite`

Aktion	Parameter	Ergebnis
`list`	`{projectUuid\|projectName, search?, page?, pageSize?}`	Seitenweise 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` + Status + Fehlerinfo) + Screenshot-/GIF-Artefakte
`list`	`{status?, projectUuid?, page?, pageSize?}`	Seitenweise Zusammenfassungen

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

Paginierung

Jede Antwort im Filtermodus ist paginiert. Antwortstruktur:

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

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

Ressourcen

Neben den Werkzeugen 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`	Letzte Ausführungen (erste Seite)
`debugg-ai://project/{uuid}`	Ein Projekt, vollständige Details
`debugg-ai://environment/{uuid}`	Eine Umgebung (Berechtigungsnachweise eingebettet, Passwörter geschwärzt)
`debugg-ai://execution/{uuid}`	Eine Ausführung, vollständige Knotendetails + Artefakt-Links

Lesevorgänge werden an dieselben Handler weitergeleitet wie die Werkzeuge project / environment / executions, sodass die Daten und die Authentifizierung identisch sind. Ressourcen sind additiv – Clients ohne Ressourcenunterstützung verwenden weiterhin die Werkzeuge.

Sicherheitsinvarianten

Passwörter sind nur schreibbar. Sie erscheinen niemals in einem Antworttext eines Werkzeugs.
Tunnel-URLs (*.ngrok.debugg.ai) werden aus allen Browser-Agenten-Antworten entfernt, einschließlich vom Agenten verfasstem Text.
404-Fehler vom Backend erscheinen als isError: true mit {error: 'NotFound', ...}, niemals als geworfene Ausnahmen.
Fehlender DEBUGGAI_API_KEY erscheint als strukturierter Werkzeugfehler beim ersten Aufruf – der Server registriert und listet Werkzeuge weiterhin normal.

Migration zu v3.0.0 (aktionsbasierte Werkzeuge)

v3 konsolidierte die 20 Werkzeuge pro Verb zu 8 aktionsbasierten Werkzeugen. Altes Werkzeug → neues tool {action}:

Entfernt	Ersatz
`search_projects`	`project {action:"get"}` / `project {action:"list"}`
`create_project`	`project {action:"create"}`
`update_project`, `delete_project`	Entfallen – verwenden Sie die DebuggAI-Webanwendung
`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	Entfallen – immer headless

delete-Aktionen erfordern jetzt eine Bestätigung (Aufforderung zur Eingabe 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 Oberfläche mit 22 Werkzeugen auf 11. Zuordnung altes Werkzeug → neues Werkzeug:

Entfernt	Ersatz
`list_projects`, `get_project`	`search_projects` (UUID-Modus vs. Filtermodus)
`list_environments`, `get_environment`	`search_environments`
`list_credentials`, `get_credential`	`search_environments` – Berechtigungsnachweise eingebettet in 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`	Entfallen – das Herunterfahren des Backends erfolgt automatisch

Änderungen der Antwortstruktur: Das bloße count-Feld in Listenantworten ist verschwunden – verwenden Sie pageInfo.totalCount.

Konfiguration

Umgebungsvariable	Erforderlich	Zweck
`DEBUGGAI_API_KEY`	ja	Backend-API-Schlüssel. Aliasse: `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`.
`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 die Telemetrie vollständig zu deaktivieren.

DEBUGGAI_API_KEY=your_api_key

Remote-/HTTP-Transport (optional)

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

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

Es handelt sich um einen OAuth Resource Server: Jede POST /mcp benötigt Authorization: Bearer <token>; fehlende oder ungültige Token erhalten einen 401 mit einem WWW-Authenticate, der auf die RFC 9728-Metadaten verweist, und Clients führen den OAuth- Flow gegen den angegebenen Autorisierungsserver aus. Der Bearer ist anfragebezogen – api.debugg.ai validiert ihn.

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 Health Check

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 angezeigt wird
`DEBUGGAI_TOKEN_TYPE`	`token`	Auf `bearer` setzen, damit OAuth-Token als `Authorization: Bearer` weitergeleitet werden

stdio-Installationen benötigen keine dieser Variablen.

Telemetrie

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

Ereignis	Wann
`tool.executed` / `tool.failed`	Pro Werkzeugaufruf
`workflow.executed`	Pro Browser-Agent-Ausführung (enthält `pollCount`, `durationMs`, `finalIntervalMs`)
`tunnel.provisioned` / `tunnel.provision_retry` / `tunnel.stopped`	Pro Tunnel-Lebenszyklusereignis
`template.lookup` / `project.lookup`	Cache-Treffer/-Verfehlung mit `durationMs` bei Kaltstart

Datenschutzhaltung:

Die eindeutige ID ist SHA-256(api_key).slice(0, 16) – niemals der rohe Schlüssel, keine PII.
phc_*-Schlüssel sind gemäß PostHog-Konvention schreibgeschützt; sicher im Quellcode einbettbar.
Setzen Sie DEBUGGAI_TELEMETRY_DISABLED=1, um vollständig zu deaktivieren (wird zu einem No-Op-Provider aufgelöst; 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, führt jedes Werkzeug gegen ein echtes Backend aus und schreibt Artefakte pro Ablauf 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 aktiv, 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 hier Code bearbeitet haben, führen Sie npm run mcp:local aus (was lediglich neu baut), damit der nächste Aufruf von debugg-ai-local Ihre Änderungen übernimmt.

Links

Dashboard · Dokumentation · Issues · Discord