Debugg AI

Debugg AI — Serveur MCP

Tests de navigateur pilotés par IA via le Model Context Protocol. Pointez-le vers n’importe quelle URL (ou localhost) et décrivez ce qu’il faut tester — un agent IA parcourt votre application et renvoie succès/échec avec des captures d’écran.

Configuration

Nécessite Node.js 20.20.0 ou ultérieur (exigence transitive de posthog-node@^5.26.0).

Obtenez une clé API sur debugg.ai, puis ajoutez-la à la configuration de votre client MCP :

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

Ou avec Docker :

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

Outils

Le serveur expose 8 outils : trois outils Navigateur plus un outil basé sur l’action par entité gérée. Les outils principaux sont check_app_in_browser (agent IA complet) et probe_page (sonde de page légère sans LLM). Les autres — project, environment, test_suite, test_case, executions — prennent chacun un discriminateur action (par ex. {"action":"list"}) qui sélectionne l’opération. Les actions destructrices delete nécessitent une confirmation (une invite de sollicitation lorsque c’est pris en charge, sinon confirm: true).

Navigateur

check_app_in_browser

Exécute un agent de navigateur IA sur votre application. L’agent navigue, interagit et rend compte avec des captures d’écran. Les URL localhost sont automatiquement tunnellisées via ngrok.

Paramètre	Type	Description
description	chaîne obligatoire	Ce qu’il faut tester (langage naturel)
url	chaîne obligatoire	URL cible — http://localhost:3000 est auto-tunnellisée
environmentId	chaîne	UUID d’un environnement spécifique
credentialId	chaîne	UUID d’un identifiant spécifique
credentialRole	chaîne	Choisir un identifiant par rôle (par ex. admin, guest)
username	chaîne	Nom d’utilisateur pour la connexion (éphémère — non persisté)
password	chaîne	Mot de passe pour la connexion (éphémère — non persisté)
repoName	chaîne	Remplacer le nom du dépôt git auto-détecté (par ex. my-org/my-repo)

Une vérification ciblée par appel. L’agent dispose d’un budget interne d’environ 25 étapes ; répartissez les suites plus larges sur plusieurs appels.

Chaque exécution réussie renvoie un bloc browserSession en plus de la capture d’écran — des URL S3 pré-signées pour le HAR capturé (trace réseau complète) et le journal de console (chaque message de la console JS). Utilisez-les pour détecter les boucles de rechargement, les erreurs d’hydratation et d’autres problèmes d’exécution qui passent les vérifications de type et les tests unitaires :

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

Les URL sont des S3 pré-signées de courte durée — récupérez l’exécution parente via executions {action:"get", uuid} pour les renouveler. harStatus / consoleLogStatus distinguent 'downloaded' (URL récupérable), 'not_available' (la page n’a rien émis), 'failed' (la capture a échoué). Lors d’une nouvelle exécution, les URL sont généralement null car le téléversement des captures est asynchrone après la fin de l’agent — interrogez executions {action:"get", uuid: executionId} jusqu’à ce que le statut atteigne 'downloaded'. Les en-têtes d’autorisation / Cookie / token/secret/api_key sont nettoyés côté serveur avant que les artefacts ne soient persistés.

trigger_crawl

Déclenche une exploration par agent de navigateur côté serveur pour peupler le graphe de connaissances du projet. Les URL localhost sont automatiquement tunnellisées. Renvoie {executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?} avec knowledgeGraph.imported === true en cas d’ingestion réussie. Le bloc browserSession (URL HAR + journal de console, même forme que ci-dessus) est également présent sur les explorations terminées.

probe_page

Sonde de page par lot légère sans LLM. Passez 1 à 20 URL ; chacune navigue, attend le chargement et renvoie l’état rendu — capture d’écran + métadonnées de page + erreurs de console structurées + résumé réseau. Pas de boucle d’agent, pas de coût LLM, pas d’assertions de scénario. Utilisez-la pour « est-ce que je viens de casser /paramètres ? », une vérification multi-routes après une refactorisation, des balayages CI par PR et des vérifications rapides de disponibilité où la boucle d’agent de 60 à 150 s de check_app_in_browser est excessive.

Paramètre	Type	Description
targets	tableau obligatoire	1 à 20 entrées : [{url, waitForSelector?, waitForLoadState?, timeoutMs?}]
targets[].url	chaîne obligatoire	URL publique ou localhost (auto-tunnellisée)
targets[].waitForLoadState	enum	'load' (par défaut) / 'domcontentloaded' / 'networkidle'
targets[].waitForSelector	chaîne	Sélecteur CSS optionnel à attendre après la navigation
targets[].timeoutMs	nombre	Délai d’expiration par URL, 1000-30000 (par défaut 10000)
includeHtml	booléen	Renvoyer le HTML brut dans chaque résultat (par défaut faux)
captureScreenshots	booléen	Renvoyer un PNG par cible (par défaut vrai)

L’ensemble du lot partage une seule exécution backend + session de navigateur + tunnel — 5 URL en un seul appel est considérablement plus rapide que 5 appels parallèles à URL unique. Le champ error par URL préserve la résilience du lot : une cible unique échouée ne fait pas échouer les autres.

La clé d’agrégation networkSummary est origin + pathname — les boucles de rechargement (?n=0..4 atteignant répétitivement le même point de terminaison) sont réduites en une seule entrée avec le compte, de sorte que /api/poll apparaissant avec count: 47 est le signal de « boucle de rechargement infinie » actionnable que les utilisateurs ont initialement demandé.

Budget de performance : <10 s pour 1 URL, <25 s pour 20. Un port mort localhost renvoie LocalServerUnreachable en <2 s sans consommer d’exécution de workflow.

project

Action	Paramètres	Résultat
get	{uuid}	Détail organisé du projet
list	{q?, page?, pageSize?}	Résumés paginés
create	{name, platform, (teamUuid|teamName), (repoUuid|repoName)}	Projet créé

L’équipe et le dépôt sont résolus par soit l’uuid soit le nom (correspondance exacte insensible à la casse ; NotFound si aucun, AmbiguousMatch si plusieurs). Il n’y a pas de update/delete — renommez ou supprimez un projet depuis l’application web DebuggAI.

environment

Action	Paramètres	Résultat
get	{uuid, projectUuid?}	Environnement avec identifiants inclus (les mots de passe ne sont jamais renvoyés)
list	{projectUuid?, q?, page?, pageSize?}	Environnements paginés, chacun avec un tableau d’identifiants
create	{name, url, description?, projectUuid?, credentials?}	Environnement créé (ensemence optionnellement des identifiants)
update	{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}	Environnement patché ; les opérations d’identifiants s’exécutent supprimer → mettre à jour → ajouter
delete	{uuid, projectUuid?, confirm?}	Supprime l’environnement (cascade les identifiants) — nécessite une confirmation

projectUuid se résout automatiquement à partir du dépôt git s’il est omis. Les échecs par identifiant apparaissent dans credentialWarnings[] sans bloquer l’opération sur l’environnement.

test_suite

Action	Paramètres	Résultat
list	{projectUuid|projectName, search?, page?, pageSize?}	Suites paginées avec statut + taux de réussite
create	{name, description, projectUuid|projectName}	Suite créée
run	{suiteUuid|(suiteName+project), targetUrl?}	Déclenche tous les tests de manière asynchrone
results	{suiteUuid|(suiteName+project)}	Suite + résultats par test
delete	{suiteUuid|(suiteName+project), confirm?}	Suppression logicielle — nécessite une confirmation

test_case

Action	Paramètres	Résultat
create	{name, description, agentTaskDescription, suiteUuid|(suiteName+project), relativeUrl?, maxSteps?}	Cas de test créé (non exécuté automatiquement)
update	{testUuid, name?, description?, agentTaskDescription?}	Cas de test patché
delete	{testUuid, confirm?}	Suppression logicielle — nécessite une confirmation

executions

Action	Paramètres	Résultat
get	{uuid}	Détail complet (nodeExecutions + état + infoErreur) + artefacts de capture d’écran/gif
list	{status?, projectUuid?, page?, pageSize?}	Résumés paginés

Une erreur 404 du backend apparaît comme isError: true avec {error: 'NotFound', message, uuid}. Les identifiants sont toujours renvoyés sans les mots de passe.

Pagination

Chaque réponse en mode filtre est paginée. Forme de la réponse :

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

Passez les paramètres optionnels page (indexé à 1, par défaut 1) et pageSize (par défaut 20, max 200 ; les valeurs excessives sont plafonnées). Aucune réponse n’est jamais tronquée silencieusement.

Ressources

En plus des outils, le serveur expose les entités en lecture seule en tant que ressources MCP afin que les clients puissent les parcourir et les @-mentionner comme contexte :

URI	Quoi
debugg-ai://projects	Tous les projets (première page)
debugg-ai://environments	Environnements pour le projet auto-détecté
debugg-ai://executions	Exécutions récentes (première page)
debugg-ai://project/{uuid}	Un projet, détail complet
debugg-ai://environment/{uuid}	Un environnement (identifiants inclus, mots de passe expurgés)
debugg-ai://execution/{uuid}	Une exécution, détail complet du nœud + liens vers les artefacts

Les lectures sont distribuées aux mêmes gestionnaires que les outils project / environment / executions, donc les données et l’authentification sont identiques. Les ressources sont additives — les clients sans prise en charge des ressources continuent d’utiliser les outils.

Invariants de sécurité

• Les mots de passe sont en écriture seule. Ils n’apparaissent jamais dans aucun corps de réponse d’aucun outil.
• Les URL de tunnel (*.ngrok.debugg.ai) sont supprimées de toutes les réponses de l’agent de navigateur, y compris le texte rédigé par l’agent.
• Les erreurs 404 du backend apparaissent comme isError: true avec {error: 'NotFound', ...}, jamais comme des exceptions levées.
• L’absence de DEBUGGAI_API_KEY apparaît comme une erreur d’outil structurée lors de la première invocation — le serveur s’enregistre et liste toujours les outils normalement.

Migration vers la v3.0.0 (outils basés sur l’action)

La v3 a consolidé les 20 outils par verbe en 8 outils basés sur l’action. Ancien outil → nouveau tool {action} :

Supprimé	Remplacement
search_projects	project {action:"get"} / project {action:"list"}
create_project	project {action:"create"}
update_project, delete_project	Abandonnés — utilisez l’application web DebuggAI
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 paramètre headless	Abandonné — toujours sans tête

Les actions delete nécessitent désormais une confirmation (invite de sollicitation, ou confirm: true). Les clients récupèrent la nouvelle surface au redémarrage de MCP.

Migration depuis la v1.x (changement cassant dans la v2.0.0)

La v2 a réduit une surface de 22 outils à 11. Mappage ancien outil → nouvel outil :

Supprimé	Remplacement
list_projects, get_project	search_projects (mode uuid vs mode filtre)
list_environments, get_environment	search_environments
list_credentials, get_credential	search_environments — identifiants inclus sur chaque environnement
create_credential	create_environment({credentials: [...]}) ensemencement, ou update_environment({addCredentials: [...]})
update_credential	update_environment({updateCredentials: [{uuid, ...patch}]})
delete_credential	update_environment({removeCredentialIds: [uuid]})
list_teams, list_repos	create_project({teamName, repoName}) — résolution de nom avec gestion de l’ambiguïté
list_executions, get_execution	search_executions
cancel_execution	Abandonné — l’arrêt du backend est automatique

Changements de forme de réponse : le champ nu count sur les réponses de liste a disparu — utilisez pageInfo.totalCount.

Configuration

Var d’env	Obligatoire	Objectif
DEBUGGAI_API_KEY	oui	Clé API backend. Alias : DEBUGGAI_API_TOKEN, DEBUGGAI_JWT_TOKEN.
DEBUGGAI_API_URL	non	URL de base du backend. Par défaut https://api.debugg.ai.
DEBUGGAI_TOKEN_TYPE	non	token (par défaut) ou bearer.
LOG_LEVEL	non	error / warn / info (par défaut) / debug.
POSTHOG_API_KEY	non	Remplacer la clé de projet de télémétrie intégrée (par ex. fork privé).
DEBUGGAI_TELEMETRY_DISABLED	non	Mettre à 1 / true / yes / on pour désactiver entièrement la télémétrie.

DEBUGGAI_API_KEY=your_api_key

Transport distant / HTTP (optionnel)

Par défaut, le serveur parle stdio (npx local). Il peut à la place s’exécuter en tant que MCP distant hébergé, multi-utilisateur sur HTTP Streamable sans état + OAuth :

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

Il s'agit d'un Serveur de Ressources OAuth : chaque POST /mcp nécessite Authorization: Bearer <token> ; les jetons manquants ou invalides reçoivent un 401 avec un WWW-Authenticate pointant vers les métadonnées RFC 9728, et les clients exécutent le flux OAuth contre le serveur d'autorisation annoncé. Le porteur est limité à la requête — api.debugg.ai le valide.

Point de terminaison	Objectif
POST /mcp	MCP Streamable HTTP (protégé par porteur)
GET /.well-known/oauth-protected-resource	Métadonnées RFC 9728 (découverte du serveur d'autorisation)
GET /health	Vérification de santé Load-balancer / ECS

Variable d'env	Valeur par défaut	Objectif
DEBUGGAI_MCP_TRANSPORT	stdio	Définir sur http pour le transport distant
PORT	3000	Port d'écoute HTTP
DEBUGGAI_MCP_PUBLIC_URL	https://mcp.debugg.ai	URL publique de ressource de ce serveur (RFC 9728 resource)
DEBUGGAI_OAUTH_ISSUER	https://auth.debugg.ai	Serveur d'autorisation annoncé aux clients
DEBUGGAI_TOKEN_TYPE	token	Définir sur bearer pour que les jetons OAuth soient transmis en tant que Authorization: Bearer

Les installations stdio n'ont besoin d'aucune de ces variables.

Télémétrie

Le serveur MCP est livré avec la télémétrie activée par défaut — une clé de projet PostHog en écriture seule intégrée (phc_*) afin que l'équipe puisse observer les taux de succès du cache, la cadence d'interrogation, la fiabilité du tunnel et d'autres métriques opérationnelles sur l'ensemble du parc installé. Événements capturés :

Événement	Quand
tool.executed / tool.failed	Par appel d'outil
workflow.executed	Par exécution d'agent navigateur (porte pollCount, durationMs, finalIntervalMs)
tunnel.provisioned / tunnel.provision_retry / tunnel.stopped	Par événement de cycle de vie du tunnel
template.lookup / project.lookup	Succès/échec du cache avec durationMs lors d'un appel à froid

Posture de confidentialité :

• L'ID distinct est SHA-256(api_key).slice(0, 16) — jamais la clé brute, aucune donnée personnelle.
• Les clés phc_* sont en écriture seule par convention PostHog ; leur intégration dans le code source est sans danger.
• Définissez DEBUGGAI_TELEMETRY_DISABLED=1 pour vous désinscrire complètement (se résout en un fournisseur inactif ; aucun événement ne quitte le processus).

Le mode actif est journalisé au démarrage :

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)

Développement local

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

La suite d'évaluation lance le serveur MCP compilé en tant que sous-processus, exerce chaque outil contre un backend réel et écrit les artefacts par flux dans scripts/evals/artifacts/<timestamp>/. Voir scripts/evals/flows/ pour les scénarios individuels.

Enregistrement MCP : debugg-ai-local vs debugg-ai

Ce dépôt fournit un .mcp.json qui enregistre un serveur limité au projet nommé debugg-ai-local pointant vers node dist/index.js — le code local fraîchement compilé. Il s'active uniquement lorsque le répertoire de travail de Claude Code est ce dépôt.

Vos autres projets doivent utiliser l'enregistrement limité à l'utilisateur debugg-ai qui tire depuis le paquet npm publié :

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

Après avoir modifié le code ici, exécutez npm run mcp:local (qui ne fait que recompiler) afin que la prochaine invocation de debugg-ai-local prenne en compte vos modifications.

Liens

Tableau de bord · Documentation · Problèmes · Discord

---

Licence Apache-2.0 © 2025 DebuggAI