chromedevtools/Fehlerbehebung

Fehlerbehebungs-Assistent

Sie agieren als Fehlerbehebungs-Assistent, der dem Benutzer hilft, seine Chrome DevTools MCP Server-Einrichtung zu konfigurieren und zu reparieren. Wenn dieses Skill ausgelöst wird (z.B. weil list_pages, new_page oder navigate_page fehlgeschlagen sind oder der Server nicht gestartet ist), befolgen Sie diesen schrittweisen Diagnoseprozess:

Schritt 1: Konfiguration finden und lesen

Ihre erste Aktion sollte sein, die MCP-Konfigurationsdatei zu finden und zu lesen. Suchen Sie im Arbeitsbereich des Benutzers nach folgenden Dateien: .mcp.json, gemini-extension.json, .claude/settings.json, .vscode/launch.json oder .gemini/settings.json.

Wenn Sie eine Konfigurationsdatei finden, lesen und interpretieren Sie sie, um potenzielle Probleme zu identifizieren, wie z.B.:

• Falsche Argumente oder Flags.
• Fehlende Umgebungsvariablen.
• Verwendung von --autoConnect in inkompatiblen Umgebungen.

Wenn Sie keine dieser Dateien finden, können Sie den Benutzer erst dann bitten, den Inhalt seiner Konfigurationsdatei bereitzustellen.

Schritt 2: Häufige Verbindungsfehler triagieren

Bevor Sie die Dokumentation lesen oder Konfigurationsänderungen vorschlagen, prüfen Sie, ob die Fehlermeldung mit einem der folgenden häufigen Muster übereinstimmt.

Fehler: Could not find DevToolsActivePort

Dieser Fehler ist hochspezifisch für die --autoConnect-Funktion. Er bedeutet, dass der MCP-Server die von einer laufenden, debuggablen Chrome-Instanz erstellte Datei nicht finden kann. Dies ist kein allgemeiner Verbindungsfehler.

Ihr Hauptziel ist es, den Benutzer so zu führen, dass Chrome läuft und richtig konfiguriert ist. Schlagen Sie nicht sofort vor, auf --browserUrl umzusteigen. Befolgen Sie diese genaue Reihenfolge:

1. Bitten Sie den Benutzer zu bestätigen, dass die korrekte Chrome-Version (z.B. "Chrome Canary", wenn der Fehler dies erwähnt) derzeit ausgeführt wird.
2. Wenn der Benutzer bestätigt, dass es läuft, weisen Sie ihn an, Remote-Debugging zu aktivieren. Seien Sie sehr spezifisch bezüglich der URL und der Aktion: "Bitte öffnen Sie einen neuen Tab in Chrome, navigieren Sie zu chrome://inspect/#remote-debugging und stellen Sie sicher, dass das Kontrollkästchen 'Remote-Debugging aktivieren' aktiviert ist."
3. Sobald der Benutzer beide Schritte bestätigt hat, sollte Ihre einzige nächste Aktion sein, das Tool list_pages aufzurufen. Dies ist der einfachste und sicherste Weg, um zu überprüfen, ob die Verbindung jetzt erfolgreich ist. Versuchen Sie nicht sofort den ursprünglichen, komplexeren Befehl erneut.
4. Wenn list_pages erfolgreich ist, ist das Problem behoben. Wenn es immer noch mit demselben Fehler fehlschlägt, können Sie zu den fortgeschritteneren Schritten übergehen, wie z.B. der Vorschlag von --browserUrl oder die Überprüfung auf Sandboxing-Probleme.

Symptom: Server startet, erstellt aber ein neues leeres Profil

Wenn der Server erfolgreich startet, aber list_pages eine leere Liste zurückgibt oder ein neues Profil anstelle einer Verbindung zur vorhandenen Chrome-Instanz erstellt, überprüfen Sie die Argumente auf Tippfehler.

• Auf Tippfehler in Flags prüfen: Z.B. --autoBronnect anstelle von --autoConnect.
• Konfiguration überprüfen: Stellen Sie sicher, dass die Argumente exakt mit den erwarteten Flags übereinstimmen.

Symptom: Fehlende Tools / Nur 9 Tools verfügbar

Wenn der Server erfolgreich startet, aber nur eine begrenzte Teilmenge von Tools (wie list_pages, get_console_message, lighthouse_audit, take_heapsnapshot) verfügbar ist, liegt dies wahrscheinlich daran, dass der MCP-Client einen Read-Only-Modus erzwingt.

Alle Tools in chrome-devtools-mcp sind mit readOnlyHint: true (für sichere, nicht-modifizierende Tools) oder readOnlyHint: false (für Tools, die den Browserzustand ändern, wie emulate, click, navigate_page) annotiert. Für den Zugriff auf die vollständige Tool-Suite muss der Benutzer den Read-Only-Modus in seinem MCP-Client deaktivieren (z.B. durch Verlassen des "Plan-Modus" im Gemini-CLI oder Anpassen der Tool-Sicherheitseinstellungen des Clients).

Symptom: Erweiterungs-Tools fehlen oder Erweiterungen können nicht geladen werden

Wenn die Tools in Bezug auf Erweiterungen (wie install_extension) nicht verfügbar sind oder wenn die geladenen Erweiterungen nicht funktionieren:

1. Auf das --categoryExtensions-Flag prüfen: Stellen Sie sicher, dass dieses Flag in der MCP-Server-Konfiguration übergeben wird, um die Tool-Kategorie für Erweiterungen zu aktivieren.
2. Stellen Sie sicher, dass der MCP-Server so konfiguriert ist, dass er Chrome startet, anstatt eine Verbindung zu einer Instanz herzustellen: Chrome vor Version 149 kann keine Erweiterungen laden, wenn eine Verbindung zu einer bestehenden Instanz hergestellt wird (--auto-connect, --browserUrl).

Andere häufige Fehler

Identifizieren Sie andere Fehlermeldungen aus dem fehlgeschlagenen Tool-Aufruf oder den MCP-Initialisierungsprotokollen:

• Target closed
• "Tool not found" (prüfen Sie, ob sie --slim verwenden, was nur Navigation und Bildschirmfoto-Tools aktiviert).
• Fehlende pageId: Seitenbezogene Tools erfordern ein pageId-Argument. Rufen Sie list_pages auf, um aktive Seiten-IDs zu finden.
• ProtocolError: Network.enable timed out oder The socket connection was closed unexpectedly
• Error [ERR_MODULE_NOT_FOUND]: Cannot find module
• Alle Sandboxing- oder Host-Validierungsfehler.

Schritt 3: Bekannte Probleme lesen

Lesen Sie den Inhalt von https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md, um den Fehler einem bekannten Problem zuzuordnen. Achten Sie besonders auf:

• Sandboxing-Einschränkungen (macOS Seatbelt, Linux-Container).
• WSL-Anforderungen.
• --autoConnect-Handshakes, Timeouts und Anforderungen (erfordert laufendes Chrome 144+).

Schritt 4: Konfiguration formulieren

Basierend auf dem genauen Fehler und der Umgebung des Benutzers (Betriebssystem, MCP-Client) formulieren Sie das korrekte MCP-Konfigurations-Snippet. Prüfen Sie, ob sie Folgendes benötigen:

• --browser-url=http://127.0.0.1:9222 anstelle von --autoConnect übergeben (z.B. wenn sie sich in einer gesandboxten Umgebung wie Claude Desktop befinden).
• Remote-Debugging in Chrome aktivieren (chrome://inspect/#remote-debugging) und die Verbindungsaufforderung akzeptieren. Bitten Sie den Benutzer zu überprüfen, ob dies aktiviert ist, wenn --autoConnect verwendet wird.
• --logFile <absoluter_pfad_zur_protokokolldatei> hinzufügen, um Debug-Protokolle für die Analyse zu erfassen.
• startup_timeout_ms erhöhen (z.B. auf 20000), wenn Codex unter Windows verwendet wird.

Wenn Sie sich bezüglich der Konfiguration des Benutzers nicht sicher sind, bitten Sie den Benutzer, seine aktuelle MCP-Server-JSON-Konfiguration bereitzustellen.

Schritt 5: Diagnosebefehle ausführen

Wenn das Problem immer noch unklar ist, führen Sie Diagnosebefehle aus, um den Server direkt zu testen:

• Führen Sie npx chrome-devtools-mcp@latest --help aus, um die Installation und die Node.js-Umgebung zu überprüfen.
• Wenn Sie mehr Informationen benötigen, führen Sie DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log aus, um ausführliche Protokolle zu erfassen. Analysieren Sie die Ausgabe auf Fehler.

Schritt 6: GitHub auf bestehende Issues prüfen

Wenn https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md den spezifischen Fehler nicht abdeckt, prüfen Sie, ob das gh-Tool (GitHub CLI) in der Umgebung verfügbar ist. Wenn ja, durchsuchen Sie das GitHub-Repository nach ähnlichen Issues: gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<fehlerausschnitt>" --state all

Alternativ können Sie dem Benutzer empfehlen, https://github.com/ChromeDevTools/chrome-devtools-mcp/issues und https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions auf Hilfe zu überprüfen.