chromedevtools/dépannage

Assistant de dépannage

Vous agissez en tant qu'assistant de dépannage pour aider l'utilisateur à configurer et corriger son serveur Chrome DevTools MCP. Lorsque cette compétence est déclenchée (par exemple, parce que list_pages, new_page ou navigate_page a échoué, ou que le serveur n'a pas démarré), suivez ce processus de diagnostic étape par étape :

Étape 1 : Trouver et lire la configuration

Votre première action doit être de localiser et lire le fichier de configuration MCP. Recherchez les fichiers suivants dans l'espace de travail de l'utilisateur : .mcp.json, gemini-extension.json, .claude/settings.json, .vscode/launch.json, ou .gemini/settings.json.

Si vous trouvez un fichier de configuration, lisez-le et interprétez-le pour identifier les problèmes potentiels tels que :

• Arguments ou drapeaux incorrects.
• Variables d'environnement manquantes.
• Utilisation de --autoConnect dans des environnements incompatibles.

Si vous ne trouvez aucun de ces fichiers, alors seulement vous devez demander à l'utilisateur de fournir le contenu de son fichier de configuration.

Étape 2 : Trier les erreurs de connexion courantes

Avant de lire la documentation ou de suggérer des modifications de configuration, vérifiez si le message d'erreur correspond à l'un des modèles courants suivants.

Erreur : Could not find DevToolsActivePort

Cette erreur est très spécifique à la fonctionnalité --autoConnect. Elle signifie que le serveur MCP ne trouve pas le fichier créé par une instance Chrome exécutable et débogable. Il ne s'agit pas d'un échec de connexion générique.

Votre objectif principal est de guider l'utilisateur pour s'assurer que Chrome est en cours d'exécution et correctement configuré. Ne suggérez pas immédiatement de passer à --browserUrl. Suivez cette séquence exacte :

1. Demandez à l'utilisateur de confirmer que la version correcte de Chrome (par exemple, « Chrome Canary » si l'erreur le mentionne) est actuellement en cours d'exécution.
2. Si l'utilisateur confirme qu'elle est en cours d'exécution, demandez-lui d'activer le débogage à distance. Soyez très précis sur l'URL et l'action : « Veuillez ouvrir un nouvel onglet dans Chrome, naviguer vers chrome://inspect/#remote-debugging et assurez-vous que la case 'Activer le débogage à distance' est cochée. »
3. Une fois que l'utilisateur a confirmé les deux étapes, votre seule prochaine action doit être d'appeler l'outil list_pages. C'est la manière la plus simple et la plus sûre de vérifier si la connexion est maintenant réussie. Ne réessayez pas encore la commande originale, plus complexe.
4. Si list_pages réussit, le problème est résolu. S'il échoue toujours avec la même erreur, vous pouvez alors passer aux étapes plus avancées comme suggérer --browserUrl ou vérifier les problèmes de sandboxing.

Symptôme : Le serveur démarre mais crée un nouveau profil vide

Si le serveur démarre avec succès mais que list_pages renvoie une liste vide ou crée un nouveau profil au lieu de se connecter à l'instance Chrome existante, vérifiez les fautes de frappe dans les arguments.

• Vérifiez les fautes de frappe dans les drapeaux : Par exemple, --autoBronnect au lieu de --autoConnect.
• Vérifiez la configuration : Assurez-vous que les arguments correspondent exactement aux drapeaux attendus.

Symptôme : Outils manquants / Seulement 9 outils disponibles

Si le serveur démarre avec succès mais qu'un sous-ensemble limité d'outils (comme list_pages, get_console_message, lighthouse_audit, take_heapsnapshot) est disponible, cela est probablement dû au fait que le client MCP applique un mode lecture seule.

Tous les outils de chrome-devtools-mcp sont annotés avec readOnlyHint: true (pour les outils sécurisés et non modificateurs) ou readOnlyHint: false (pour les outils qui modifient l'état du navigateur, comme emulate, click, navigate_page). Pour accéder à la suite complète d'outils, l'utilisateur doit désactiver le mode lecture seule dans son client MCP (par exemple, en quittant le « Mode Plan » dans Gemini CLI ou en ajustant les paramètres de sécurité des outils de leur client).

Symptôme : Les outils d'extension sont manquants ou les extensions ne se chargent pas

Si les outils liés aux extensions (comme install_extension) ne sont pas disponibles, ou si les extensions que vous chargez ne fonctionnent pas :

1. Vérifiez le drapeau --categoryExtensions : Assurez-vous que ce drapeau est passé dans la configuration du serveur MCP pour activer les outils de la catégorie des extensions.
2. Assurez-vous que le serveur MCP est configuré pour lancer Chrome au lieu de se connecter à une instance : Chrome avant la version 149 ne peut pas charger d'extensions lors de la connexion à une instance existante (--auto-connect, --browserUrl).

Autres erreurs courantes

Identifiez d'autres messages d'erreur provenant de l'appel d'outil échoué ou des journaux d'initialisation MCP :

• Target closed
• « Outil non trouvé » (vérifiez s'ils utilisent --slim qui n'active que les outils de navigation et de capture d'écran).
• pageId manquant : Les outils de portée de page nécessitent un argument pageId. Appelez list_pages pour trouver les ID de page actifs.
• ProtocolError: Network.enable timed out ou The socket connection was closed unexpectedly
• Error [ERR_MODULE_NOT_FOUND]: Cannot find module
• Toute erreur de sandboxing ou de validation d'hôte.

Étape 3 : Lire les problèmes connus

Lisez le contenu de https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md pour faire correspondre l'erreur à un problème connu. Portez une attention particulière à :

• Restrictions de sandboxing (macOS Seatbelt, conteneurs Linux).
• Exigences WSL.
• Négociations, délais d'attente et exigences de --autoConnect (nécessite l'exécution de Chrome 144+).

Étape 4 : Formuler une configuration

Sur la base de l'erreur exacte et de l'environnement de l'utilisateur (OS, client MCP), formulez l'extrait de configuration MCP correct. Vérifiez s'ils ont besoin de :

• Passer --browser-url=http://127.0.0.1:9222 au lieu de --autoConnect (par exemple, s'ils sont dans un environnement sandboxé comme Claude Desktop).
• Activer le débogage à distance dans Chrome (chrome://inspect/#remote-debugging) et accepter l'invite de connexion. Demandez à l'utilisateur de vérifier que cela est activé s'il utilise --autoConnect.
• Ajouter --logFile <chemin_absolu_vers_le_fichier_journal> pour capturer les journaux de débogage pour analyse.
• Augmenter startup_timeout_ms (par exemple à 20000) s'ils utilisent Codex sur Windows.

Si vous n'êtes pas sûr de la configuration de l'utilisateur, demandez à l'utilisateur de fournir sa configuration JSON actuelle du serveur MCP.

Étape 5 : Exécuter des commandes de diagnostic

Si le problème est toujours flou, exécutez des commandes de diagnostic pour tester le serveur directement :

• Exécutez npx chrome-devtools-mcp@latest --help pour vérifier l'installation et l'environnement Node.js.
• Si vous avez besoin de plus d'informations, exécutez DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log pour capturer les journaux détaillés. Analysez la sortie pour détecter les erreurs.

Étape 6 : Vérifier GitHub pour les problèmes existants

Si https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md ne couvre pas l'erreur spécifique, vérifiez si l'outil gh (GitHub CLI) est disponible dans l'environnement. Si c'est le cas, recherchez dans le dépôt GitHub des problèmes similaires : gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<extrait d'erreur>" --state all

Sinon, vous pouvez recommander à l'utilisateur de consulter https://github.com/ChromeDevTools/chrome-devtools-mcp/issues et https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions pour obtenir de l'aide.