Construindo um CLI que Controla Qualquer Site Usando o Protocolo Chrome DevTools e IA

A automação de navegadores tradicionalmente significava iniciar instâncias headless, lutar com fluxos de autenticação e manter seletores frágeis. Mas há uma maneira melhor. Conectando uma ferramenta CLI diretamente à sua sessão de navegador existente através do Protocolo Chrome DevTools (CDP), você pode construir interfaces de linha de comando que controlam qualquer site no qual você já esteja logado — sem gerenciamento de credenciais, sem resolução de CAPTCHA, sem manipulação de cookies.

Neste tutorial, você construirá um CLI em TypeScript que se conecta a uma instância do Chrome em execução, executa scripts em páginas ao vivo, extrai dados estruturados e faz a ponte entre fluxos de trabalho de terminal e a web moderna. Este é o mesmo padrão arquitetônico por trás de ferramentas como o modo connect() do Puppeteer e o emergente ecossistema do Protocolo de Contexto de Modelo (MCP) que permite que agentes de IA controlem navegadores.

Por que Reutilizar uma Sessão de Navegador Ao Vivo?

A maioria dos tutoriais de automação web começa com puppeteer.launch() ou playwright.chromium.launch(). Isso cria um navegador novo, sem cookies, sem extensões, sem sessões logadas. Você imediatamente enfrenta dois problemas:

1. A autenticação é difícil. Fluxos OAuth, MFA, CAPTCHAs e detecção de bots lutam contra logins automatizados.
2. A página que você vê não é a página que seu bot vê. Extensões, flags de recursos ligadas a contas e conteúdo personalizado diferem.

Conectando-se a um navegador que você já usa, você contorna ambos os problemas completamente. Seu CLI herda todos os cookies, todas as extensões, todas as sessões autenticadas. Se você pode ver isso no seu navegador, seu CLI pode interagir com isso.

Esse padrão é especialmente poderoso para:

• Ferramentas internas por trás de SSO onde a autenticação programática é impossível
• Dashboards que requerem login humano, mas extração de dados repetitiva
• Fluxos de trabalho assistidos por IA onde um LLM precisa ler ou agir sobre o conteúdo da página
• Ferramentas de desenvolvedor que aumentam seu navegador com superpoderes de terminal

Visão Geral da Arquitetura

O sistema tem três camadas:

┌──────────────┐     CDP (WebSocket)     ┌──────────────────┐
│   Seu CLI    │ ◄──────────────────────► │  Navegador Chrome │
│  (Node.js)   │                          │  (--remote-debug) │
└──────┬───────┘                          └──────────────────┘
       │
       │  Opcional: Ponte MCP
       │
┌──────▼───────┐
│   Agente IA  │
│  (LLM/Ferramenta)  │
└──────────────┘

O Protocolo Chrome DevTools (CDP) é um protocolo baseado em WebSocket que o Chrome expõe quando iniciado com a flag --remote-debugging-port. Ele fornece acesso programático completo a cada aba: manipulação de DOM, avaliação de JavaScript, interceptação de rede, acesso a cookies, capturas de tela e mais.

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto para conectar modelos de IA a ferramentas externas. Ao envolver sua ponte CDP como um servidor MCP, você permite que agentes de IA controlem o navegador através de uma interface de ferramenta bem definida — a mesma arquitetura usada pelas capacidades de uso de computador do Claude e sistemas semelhantes.

A chave da percepção: o CDP não é apenas para testes. É uma API de controle de navegador de propósito geral, e combiná-lo com um CLI fornece uma interface scriptável para toda a web.

Passo 1: Iniciar o Chrome com Depuração Remota

Primeiro, inicie o Chrome com a porta de depuração aberta. Esta é a única configuração necessária do lado do navegador.

macOS:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222

Linux:

google-chrome --remote-debugging-port=9222

Windows:

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

Verifique se está funcionando visitando http://localhost:9222/json/version em outro navegador ou com curl:

curl http://localhost:9222/json/version

Você deve ver JSON com a URL do depurador WebSocket do navegador:

{
  "Browser": "Chrome/131.0.6778.86",
  "Protocol-Version": "1.3",
  "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/..."
}

Passo 2: Configuração do Projeto

Inicialize um projeto TypeScript com a biblioteca cliente CDP:

mkdir browser-cli && cd browser-cli
npm init -y
npm install chrome-remote-interface commander
npm install -D typescript @types/node tsx
npx tsc --init --target ES2022 --module Node16 --moduleResolution Node16

chrome-remote-interface é um cliente CDP leve. commander lida com a análise de argumentos CLI. Usamos tsx para executar TypeScript diretamente durante o desenvolvimento.

Passo 3: Conectar ao Chrome e Listar Abas Abertas

Crie src/browser.ts — o módulo central que gerencia a conexão CDP:

import CDP from "chrome-remote-interface";

export interface TabInfo {
  id: string;
  title: string;
  url: string;
}

export async function listTabs(port = 9222): Promise<TabInfo