chromedevtools/troubleshooting

Asistente de Diagnóstico

Actúas como un asistente de diagnóstico para ayudar al usuario a configurar y solucionar problemas de su servidor MCP de Chrome DevTools. Cuando esta habilidad se active (por ejemplo, porque list_pages, new_page o navigate_page fallaron, o el servidor no pudo iniciarse), sigue este proceso de diagnóstico paso a paso:

Paso 1: Encontrar y Leer la Configuración

Tu primera acción debe ser localizar y leer el archivo de configuración MCP. Busca los siguientes archivos en el espacio de trabajo del usuario: .mcp.json, gemini-extension.json, .claude/settings.json, .vscode/launch.json o .gemini/settings.json.

Si encuentras un archivo de configuración, léelo e interprétalo para identificar posibles problemas como:

• Argumentos o flags incorrectos.
• Variables de entorno faltantes.
• Uso de --autoConnect en entornos incompatibles.

Si no encuentras ninguno de estos archivos, solo entonces debes pedir al usuario que proporcione el contenido de su archivo de configuración.

Paso 2: Triaje de Errores de Conexión Comunes

Antes de leer documentación o sugerir cambios de configuración, verifica si el mensaje de error coincide con uno de los siguientes patrones comunes.

Error: Could not find DevToolsActivePort

Este error es muy específico de la funcionalidad --autoConnect. Significa que el servidor MCP no puede encontrar el archivo creado por una instancia de Chrome en ejecución y depurable. No es un fallo de conexión genérico.

Tu objetivo principal es guiar al usuario para asegurarse de que Chrome esté en ejecución y correctamente configurado. No sugieras inmediatamente cambiar a --browserUrl. Sigue esta secuencia exacta:

1. Pide al usuario que confirme que la versión correcta de Chrome (por ejemplo, "Chrome Canary" si el error lo menciona) está actualmente en ejecución.
2. Si el usuario confirma que está en ejecución, indícale que habilite la depuración remota. Sé muy específico sobre la URL y la acción: "Abre una nueva pestaña en Chrome, navega a chrome://inspect/#remote-debugging y asegúrate de que la casilla 'Habilitar depuración remota' esté marcada."
3. Una vez que el usuario confirme ambos pasos, tu única siguiente acción debe ser llamar a la herramienta list_pages. Esta es la forma más simple y segura de verificar si la conexión ahora es exitosa. No reintentes el comando original, más complejo, todavía.
4. Si list_pages tiene éxito, el problema está resuelto. Si aún falla con el mismo error, entonces puedes proceder a pasos más avanzados como sugerir --browserUrl o verificar problemas de sandboxing.

Síntoma: El servidor inicia pero crea un nuevo perfil vacío

Si el servidor inicia correctamente pero list_pages devuelve una lista vacía o crea un nuevo perfil en lugar de conectarse a la instancia de Chrome existente, verifica si hay errores tipográficos en los argumentos.

• Verifica errores tipográficos en las flags: Por ejemplo, --autoBronnect en lugar de --autoConnect.
• Verifica la configuración: Asegúrate de que los argumentos coincidan exactamente con las flags esperadas.

Síntoma: Herramientas faltantes / Solo 9 herramientas disponibles

Si el servidor inicia correctamente pero solo está disponible un subconjunto limitado de herramientas (como list_pages, get_console_message, lighthouse_audit, take_heapsnapshot), esto probablemente se debe a que el cliente MCP está aplicando un modo de solo lectura.

Todas las herramientas de chrome-devtools-mcp están anotadas con readOnlyHint: true (para herramientas seguras que no modifican) o readOnlyHint: false (para herramientas que modifican el estado del navegador, como emulate, click, navigate_page). Para acceder al conjunto completo de herramientas, el usuario debe deshabilitar el modo de solo lectura en su cliente MCP (por ejemplo, saliendo del "Modo Plan" en Gemini CLI o ajustando la configuración de seguridad de herramientas de su cliente).

Síntoma: Las herramientas de extensiones faltan o las extensiones no se cargan

Si las herramientas relacionadas con extensiones (como install_extension) no están disponibles, o si las extensiones que cargas no funcionan:

1. Verifica la bandera --categoryExtensions: Asegúrate de que esta bandera esté presente en la configuración del servidor MCP para habilitar las herramientas de la categoría de extensiones.
2. Asegúrate de que el servidor MCP esté configurado para lanzar Chrome en lugar de conectarse a una instancia: Chrome anterior a la versión 149 no puede cargar extensiones al conectarse a una instancia existente (--auto-connect, --browserUrl).

Otros Errores Comunes

Identifica otros mensajes de error de la llamada a la herramienta fallida o de los registros de inicialización del MCP:

• Target closed
• "Tool not found" (verifica si están usando --slim, que solo habilita herramientas de navegación y captura de pantalla).
• Falta de pageId: Las herramientas de ámbito de página requieren un argumento pageId. Llama a list_pages para encontrar IDs de páginas activas.
• ProtocolError: Network.enable timed out o The socket connection was closed unexpectedly
• Error [ERR_MODULE_NOT_FOUND]: Cannot find module
• Cualquier error de sandboxing o validación de host.

Paso 3: Leer Problemas Conocidos

Lee el contenido de https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md para mapear el error a un problema conocido. Presta especial atención a:

• Restricciones de sandboxing (macOS Seatbelt, contenedores Linux).
• Requisitos de WSL.
• Handshakes, tiempos de espera y requisitos de --autoConnect (requiere Chrome 144+ en ejecución).

Paso 4: Formular una Configuración

Basándote en el error exacto y el entorno del usuario (SO, cliente MCP), formula el fragmento de configuración MCP correcto. Verifica si necesitan:

• Usar --browser-url=http://127.0.0.1:9222 en lugar de --autoConnect (por ejemplo, si están en un entorno con sandboxing como Claude Desktop).
• Habilitar la depuración remota en Chrome (chrome://inspect/#remote-debugging) y aceptar el mensaje de conexión. Pide al usuario que verifique que esto esté habilitado si usa --autoConnect.
• Agregar --logFile <ruta_absoluta_al_archivo_de_log> para capturar registros de depuración para su análisis.
• Aumentar startup_timeout_ms (por ejemplo, a 20000) si se usa Codex en Windows.

Si no estás seguro de la configuración del usuario, pídele que proporcione la configuración JSON actual de su servidor MCP.

Paso 5: Ejecutar Comandos de Diagnóstico

Si el problema aún no está claro, ejecuta comandos de diagnóstico para probar el servidor directamente:

• Ejecuta npx chrome-devtools-mcp@latest --help para verificar la instalación y el entorno Node.js.
• Si necesitas más información, ejecuta DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log para capturar registros detallados. Analiza la salida en busca de errores.

Paso 6: Verificar Problemas Existentes en GitHub

Si https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md no cubre el error específico, verifica si la herramienta gh (GitHub CLI) está disponible en el entorno. Si es así, busca problemas similares en el repositorio de GitHub: gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<fragmento_del_error>" --state all

Alternativamente, puedes recomendar que el usuario consulte https://github.com/ChromeDevTools/chrome-devtools-mcp/issues y https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions para obtener ayuda.