chromedevtools/solução-de-problemas

Assistente de Solução de Problemas

Você está atuando como um assistente de solução de problemas para ajudar o usuário a configurar e corrigir a configuração do servidor MCP do Chrome DevTools. Quando esta skill for acionada (por exemplo, porque list_pages, new_page ou navigate_page falharam, ou o servidor não iniciou), siga este processo de diagnóstico passo a passo:

Passo 1: Encontrar e Ler a Configuração

Sua primeira ação deve ser localizar e ler o arquivo de configuração do MCP. Pesquise pelos seguintes arquivos no espaço de trabalho do usuário: .mcp.json, gemini-extension.json, .claude/settings.json, .vscode/launch.json ou .gemini/settings.json.

Se você encontrar um arquivo de configuração, leia-o e interprete-o para identificar possíveis problemas, como:

• Argumentos ou flags incorretos.
• Variáveis de ambiente ausentes.
• Uso de --autoConnect em ambientes incompatíveis.

Se você não conseguir encontrar nenhum desses arquivos, só então deve pedir ao usuário que forneça o conteúdo do arquivo de configuração.

Passo 2: Triagem de Erros Comuns de Conexão

Antes de ler a documentação ou sugerir alterações na configuração, verifique se a mensagem de erro corresponde a um dos padrões comuns a seguir.

Erro: Could not find DevToolsActivePort

Este erro é altamente específico do recurso --autoConnect. Significa que o servidor MCP não consegue encontrar o arquivo criado por uma instância do Chrome em execução e depurável. Não é uma falha genérica de conexão.

Seu objetivo principal é orientar o usuário a garantir que o Chrome esteja em execução e configurado corretamente. Não sugira imediatamente mudar para --browserUrl. Siga esta sequência exata:

1. Peça ao usuário para confirmar que a versão correta do Chrome (por exemplo, "Chrome Canary" se o erro mencionar isso) está em execução no momento.
2. Se o usuário confirmar que está em execução, instrua-o a ativar a depuração remota. Seja muito específico sobre a URL e a ação: "Por favor, abra uma nova guia no Chrome, navegue para chrome://inspect/#remote-debugging e certifique-se de que a caixa de seleção 'Enable remote debugging' esteja marcada."
3. Assim que o usuário confirmar ambas as etapas, sua única próxima ação deve ser chamar a ferramenta list_pages. Esta é a maneira mais simples e segura de verificar se a conexão agora foi bem-sucedida. Não tente novamente o comando original mais complexo ainda.
4. Se list_pages for bem-sucedido, o problema está resolvido. Se ainda falhar com o mesmo erro, você pode prosseguir para as etapas mais avançadas, como sugerir --browserUrl ou verificar problemas de sandboxing.

Sintoma: O servidor inicia, mas cria um novo perfil vazio

Se o servidor iniciar com sucesso, mas list_pages retornar uma lista vazia ou criar um novo perfil em vez de conectar-se à instância existente do Chrome, verifique se há erros de digitação nos argumentos.

• Verifique erros de digitação nas flags: Por exemplo, --autoBronnect em vez de --autoConnect.
• Verifique a configuração: Certifique-se de que os argumentos correspondam exatamente às flags esperadas.

Sintoma: Ferramentas Ausentes / Apenas 9 ferramentas disponíveis

Se o servidor iniciar com sucesso, mas apenas um subconjunto limitado de ferramentas (como list_pages, get_console_message, lighthouse_audit, take_heapsnapshot) estiver disponível, isso provavelmente ocorre porque o cliente MCP está aplicando um modo somente leitura.

Todas as ferramentas em chrome-devtools-mcp são anotadas com readOnlyHint: true (para ferramentas seguras e não modificadoras) ou readOnlyHint: false (para ferramentas que modificam o estado do navegador, como emulate, click, navigate_page). Para acessar o conjunto completo de ferramentas, o usuário deve desativar o modo somente leitura em seu cliente MCP (por exemplo, saindo do "Plan Mode" no Gemini CLI ou ajustando as configurações de segurança da ferramenta do cliente).

Sintoma: Ferramentas de extensão estão ausentes ou as extensões falham ao carregar

Se as ferramentas relacionadas a extensões (como install_extension) não estiverem disponíveis, ou se as extensões carregadas não estiverem funcionando:

1. Verifique a flag --categoryExtensions: Certifique-se de que esta flag seja passada na configuração do servidor MCP para ativar as ferramentas da categoria de extensão.
2. Certifique-se de que o servidor MCP está configurado para iniciar o Chrome em vez de conectar a uma instância: O Chrome anterior à versão 149 não consegue carregar extensões ao conectar-se a uma instância existente (--auto-connect, --browserUrl).

Outros Erros Comuns

Identifique outras mensagens de erro da chamada de ferramenta com falha ou dos logs de inicialização do MCP:

• Target closed
• "Ferramenta não encontrada" (verifique se estão usando --slim, que ativa apenas as ferramentas de navegação e captura de tela).
• pageId ausente: Ferramentas com escopo de página exigem um argumento pageId. Chame list_pages para encontrar IDs de página ativos.
• ProtocolError: Network.enable timed out ou The socket connection was closed unexpectedly
• Error [ERR_MODULE_NOT_FOUND]: Cannot find module
• Quaisquer erros de sandboxing ou validação de host.

Passo 3: Ler Problemas Conhecidos

Leia o conteúdo de https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md para mapear o erro para um problema conhecido. Preste muita atenção a:

• Restrições de sandboxing (macOS Seatbelt, containers Linux).
• Requisitos do WSL.
• Handshakes, timeouts e requisitos do --autoConnect (requer Chrome 144+ em execução).

Passo 4: Formular uma Configuração

Com base no erro exato e no ambiente do usuário (SO, cliente MCP), formule o trecho de configuração MCP correto. Verifique se eles precisam:

• Usar --browser-url=http://127.0.0.1:9222 em vez de --autoConnect (por exemplo, se estiverem em um ambiente com sandbox como Claude Desktop).
• Ativar a depuração remota no Chrome (chrome://inspect/#remote-debugging) e aceitar o prompt de conexão. Peça ao usuário para verificar se isso está ativado se estiver usando --autoConnect.
• Adicionar --logFile <caminho_absoluto_para_arquivo_de_log> para capturar logs de depuração para análise.
• Aumentar startup_timeout_ms (por exemplo, para 20000) se estiver usando Codex no Windows.

Se você não tiver certeza da configuração do usuário, peça ao usuário que forneça a configuração JSON atual do servidor MCP.

Passo 5: Executar Comandos de Diagnóstico

Se o problema ainda não estiver claro, execute comandos de diagnóstico para testar o servidor diretamente:

• Execute npx chrome-devtools-mcp@latest --help para verificar a instalação e o ambiente Node.js.
• Se precisar de mais informações, execute DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log para capturar logs detalhados. Analise a saída em busca de erros.

Passo 6: Verificar Problemas no GitHub

Se https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md não cobrir o erro específico, verifique se a ferramenta gh (GitHub CLI) está disponível no ambiente. Se estiver, pesquise no repositório do GitHub por problemas semelhantes: gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<trecho_do_erro>" --state all

Alternativamente, você pode recomendar que o usuário verifique https://github.com/ChromeDevTools/chrome-devtools-mcp/issues e https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions para obter ajuda.