Kapture

Uma extensão do Chrome DevTools que permite automação de navegador através do Model Context Protocol (MCP) para aplicações de IA.

GitHub
182
Experimente este MCPPatrocinado

Documentação

Kapture - Automação de Navegador via Chrome DevTools

Kapture é uma Extensão do Chrome DevTools que permite automação de navegador através do Model Context Protocol (MCP). Ela permite que aplicações de IA como Claude controlem navegadores web através de uma arquitetura de três camadas.

✨ Recurso Principal: Múltiplos clientes de IA podem se conectar ao mesmo servidor! Claude Desktop, Cline e outros clientes MCP podem controlar abas do navegador através de uma única instância do servidor.

Disponível na Chrome Web Store

Kapture DevTools Extension Panel

Visão Geral

Kapture conecta assistentes de IA com navegadores web através de:

  • Servidor MCP: Gerencia a comunicação do protocolo MCP
  • Extensão do Chrome: Service worker em segundo plano executa comandos de automação do navegador (DevTools não precisa estar aberto)
  • Ponte WebSocket: Comunicação em tempo real entre servidor e extensões
  • Suporte a Múltiplos Clientes: Múltiplos clientes de IA podem se conectar simultaneamente via WebSocket

Arquitetura

How Kapture Works

Início Rápido

1. Instalar Dependências

# Server
cd server
npm install
npm run build

# Test App (optional)
cd test-app
npm install

2. Instalar a Extensão do Chrome

Opção A: Instalar pela Chrome Web Store (Recomendado)

  1. Visite a página do Kapture na Chrome Web Store
  2. Clique em "Adicionar ao Chrome"
  3. Confirme a instalação

Opção B: Carregar sem empacotar (Modo Desenvolvedor)

  1. Abra o Chrome e navegue até chrome://extensions/
  2. Ative o "Modo desenvolvedor"
  3. Clique em "Carregar sem compactação"
  4. Selecione a pasta extension

3. Iniciar o Servidor MCP

Configure seu cliente de IA e abra-o. Ele iniciará o servidor MCP automaticamente.

OU

Execute o App de Teste:

cd test-app
npm run dev

O servidor inicia na porta 61822.

# Server
cd server
npm start

# Test App
cd test-app
npm start

4. Conectar uma Aba

  1. Abra qualquer site no Chrome
  2. Clique no ícone da barra de ferramentas do Kapture e alterne o botão de conexão
  3. A extensão se conecta ao servidor na porta 61822 (o selo mostra ✓ quando conectado)

Alternativamente, conecte-se pelo painel "Kapture" no DevTools, ou carregue uma página com ?kapture-connect=true na URL para conexão automática.

Usando com Claude Desktop

Adicione à configuração do seu Claude Desktop:

Opção 1: Usando o comando bridge (Recomendado)

Este comando único inicia o servidor e gerencia a tradução stdio-para-WebSocket:

{
  "mcpServers": {
    "kapture": {
      "command": "npx",
      "args": ["-y", "kapture-mcp@latest", "bridge"]
    }
  }
}

Opção 2: Conexão WebSocket direta (Avançado)

Para casos de uso avançados onde você precisa de controle manual do servidor:

  1. Inicie o servidor manualmente:
npx kapture-mcp
  1. Configure o Claude Desktop para conectar via WebSocket:
{
  "mcpServers": {
    "kapture": {
      "transport": "websocket",
      "url": "ws://localhost:61822/mcp"
    }
  }
}

Nota: Esta abordagem requer gerenciamento manual do ciclo de vida do servidor. Use a Opção 1 (comando bridge) para a maioria dos casos de uso.

🚀 Execute Múltiplos Assistentes de IA Simultaneamente

Kapture suporta múltiplos clientes MCP conectando ao mesmo servidor! Você pode executar Claude Desktop, Cline e outros clientes MCP simultaneamente através de uma única instância do servidor.

Como Funciona

  • Todos os clientes MCP conectam via WebSocket para ws://localhost:61822/mcp
  • Todos os clientes MCP compartilham acesso às mesmas abas do navegador
  • Notificações são transmitidas para todos os clientes conectados

Detecção Inteligente de Servidor

Ao executar npx kapture-mcp, o comando detecta automaticamente se um servidor já está em execução:

  • Nenhum servidor existente: Inicia um novo servidor na porta 61822
  • Servidor já em execução: Mostra informações de conexão e sai graciosamente

Isso previne erros e confusão quando múltiplos clientes tentam iniciar servidores.

Configurando Múltiplos Clientes

Cada cliente deve usar a mesma configuração de comando bridge:

Claude Desktop:

{
  "mcpServers": {
    "kapture": {
      "command": "npx",
      "args": ["-y", "kapture-mcp@latest", "bridge"]
    }
  }
}

Cline/VS Code:

{
  "cline.mcpServers": {
    "kapture": {
      "command": "npx",
      "args": ["-y", "kapture-mcp@latest", "bridge"]
    }
  }
}

Outros Clientes MCP: Use o mesmo padrão de configuração com "command": "npx" e "args": ["-y", "kapture-mcp@latest", "bridge"].

Veja o guia completo de múltiplos assistentes →

Benefícios de Múltiplos Assistentes de IA:

  • Fluxos de Trabalho Paralelos: Tenha o Claude Desktop pesquisando enquanto o Cline desenvolve código
  • Tarefas Especializadas: Use diferentes clientes de IA para diferentes tipos de automação
  • Colaboração em Equipe: Múltiplos membros da equipe podem usar suas ferramentas de IA preferidas simultaneamente
  • Testes e Desenvolvimento: Teste scripts de automação com uma IA enquanto desenvolve com outra

Então peça ao Claude para interagir com páginas web:

  • "Navegue até example.com e tire um screenshot"
  • "Clique no botão de busca"
  • "Preencha o campo de email com test@example.com"

Ferramentas MCP Disponíveis

  • navigate - Navegar para URL
  • back - Botão voltar do navegador
  • forward - Botão avançar do navegador
  • reload - Recarregar a página atual (similar a pressionar F5)
  • click - Clicar em elementos (usa o primeiro elemento correspondente, retorna seletor único)
  • hover - Passar o mouse sobre elementos (usa o primeiro elemento correspondente, retorna seletor único)
  • fill - Preencher campos de entrada definindo o valor diretamente (usa o primeiro elemento correspondente, retorna seletor único)
  • type - Digitar uma string como pressionamentos de tecla individuais (eventos de tecla reais; funciona em entradas "falsas" que ignoram element.value)
  • insertText - Inserir uma string inteira de uma vez (dispara eventos de entrada mas não eventos por tecla; bom para texto em massa e editores como Google Docs)
  • clear - Limpar um campo de texto via selecionar-tudo + Backspace (eventos de tecla reais; funciona em entradas "falsas")
  • select - Selecionar opções de dropdown (apenas HTML <select>, usa o primeiro elemento correspondente, retorna seletor único)
  • keypress - Enviar eventos de teclado para a página ou elementos específicos (suporta teclas modificadoras)
  • scroll - Rolar um elemento para a visualização (seletor/xpath) ou para uma coordenada absoluta x/y do documento
  • elements - Consultar todos os elementos que correspondem a um seletor CSS ou XPath com filtragem opcional de visibilidade
  • console_logs - Obter o conteúdo do console da aba (mensagens de console, exceções não capturadas, entradas geradas pelo navegador)
  • watch_console - Observar o console em tempo real por um tempo limite obrigatório (ms), então retornar tudo que foi registrado durante a janela
  • network_monitor - Ligar/desligar o monitoramento de rede para uma aba (booleano enabled). Enquanto ligado, os metadados de cada requisição são capturados em um buffer por aba. Observadores são rastreados por identidade do cliente: ativar é idempotente, o monitoramento permanece ligado até que todos os observadores desativem (ou force:true), e clientes desconectados são liberados automaticamente. O buffer é limpo quando o monitoramento para completamente. Ative antes do tráfego que você deseja observar — a captura não tem histórico. (Extensão 1.1.0+)
  • network_requests - Listar as requisições capturadas; cada uma carrega um requestId, um seq monotônico, e hasPostData quando a requisição tinha payload. Consulte incrementalmente passando o cursor da chamada anterior como since.
  • network_body - Buscar os corpos de uma requisição por requestId (o monitoramento deve estar ligado): o payload POST requestBody e o body da resposta. Truncado para maxBytes (padrão 65536) com bodyTruncated:true enquanto size reporta o comprimento total; retorna bodyError se o corpo da resposta foi removido ou está em streaming (text/event-stream não pode ser lido via CDP).
  • evaluate - Executar JavaScript na página e retornar o resultado. Desligado por padrão: só disponível após ativar o botão "Permitir execução de JS" no popup da extensão ou painel DevTools para uma aba conectada. A permissão é redefinida ao desconectar.
  • compose - Executar uma sequência de comandos contra uma aba em uma única chamada. Script é um comando por linha como <tool>?<query-string> (mais wait?t=<ms>); executa em ordem, para no primeiro erro, retorna um array de respostas por comando.

Nota sobre Seletores: Ferramentas que aceitam um parâmetro selector (click, hover, fill, type, insertText, clear, select, keypress, scroll, screenshot, dom) operarão apenas no primeiro elemento que corresponder ao seletor CSS. A resposta da ferramenta inclui o seletor único do elemento real que foi usado, que pode incluir um ID gerado automaticamente se o elemento não tivesse um.

Suporte a XPath: Todas as ferramentas que aceitam um parâmetro selector também aceitam um parâmetro xpath como alternativa. Isso é particularmente útil para:

  • Encontrar elementos por conteúdo de texto: xpath: "//button[contains(text(), 'Submit')]"
  • Relações complexas entre elementos: xpath: "//div[@class='container']//span[2]"
  • Quando seletores CSS são insuficientes

Use selector OU xpath, não ambos. Se ambos forem fornecidos, selector tem precedência.

Ferramenta Keypress

A ferramenta keypress simula eventos de teclado. Ela aceita:

  • key (obrigatório): A combinação de teclas a pressionar. Pode ser:
    • Tecla única: "a", "Enter", "Tab", "Escape", " " (espaço), "Shift", "Control"
    • Com modificadores: "Control+a", "Shift+Tab", "Alt+F4", "Meta+Shift+p"
    • Nomes de modificadores: Control (ou Ctrl), Shift, Alt, Meta (ou Cmd/Command)
    • Nota: Ao enviar apenas uma tecla modificadora (ex.: "Shift"), é tratado como pressionar essa tecla sozinha
    • Modificadores duplicados são ignorados (ex.: "Shift+Shift+a" é o mesmo que "Shift+a")
  • selector ou xpath (opcional): Direcionar para um elemento específico. Se não for fornecido, envia para document.body

Exemplos:

// Press Enter
{ "key": "Enter", "selector": "#login-form" }

// Select all text (Ctrl+A)
{ "key": "Control+a", "selector": "#username" }

// Zoom in (Ctrl+Plus)
{ "key": "Control++", "selector": "body" }

// Zoom out (Ctrl+Minus)
{ "key": "Control+-", "selector": "body" }

// New tab (Ctrl+T)
{ "key": "Control+t" }

// Close tab (Ctrl+W or Cmd+W on Mac)
{ "key": "Meta+w" }

Recursos MCP

  • kapture://tabs - Listar todas as abas do navegador conectadas
  • kapture://tab/{tabId} - Obter informações detalhadas sobre uma aba específica
  • kapture://tab/{tabId}/console - Obter logs do console de uma aba específica (com suporte a paginação)
  • kapture://tab/{tabId}/screenshot - Capturar screenshots de uma aba ou elemento
  • kapture://tab/{tabId}/dom - Obter conteúdo HTML de uma aba ou elemento
  • kapture://tab/{tabId}/elementsFromPoint - Obter elementos em coordenadas específicas
  • kapture://tab/{tabId}/elements?selector={selector}&visible={true|false|all} - Consultar todos os elementos que correspondem a um seletor CSS ou XPath com filtragem opcional de visibilidade

Desenvolvimento

Desenvolvimento do Servidor

cd server
npm run dev    # Development with hot-reload

App de Teste

cd test-app
npm run dev    # Run Electron test app

Desenvolvimento da Extensão

Após fazer alterações:

  1. Vá para chrome://extensions/
  2. Clique em atualizar na extensão Kapture

Componentes Principais

Servidor (/server/src):

  • mcp-server-manager.ts - Implementação do protocolo MCP (uma instância do servidor por cliente)
  • browser-websocket-manager.ts - Servidor WebSocket para conexões de extensão
  • tab-registry.ts - Rastreamento de abas
  • tool-handler.ts + tools.yaml - Definições de ferramentas MCP e despacho

Extensão (/extension):

  • background.js + modules/ - Service worker: gerencia conexões WebSocket e executa comandos (via APIs chrome.debugger e chrome.tabs)
  • page-helpers.js - Script de conteúdo que gerencia comandos DOM (dom, elements, fill, select, ...)
  • modules/background-console.js - Recuperação de console via CDP (lê o buffer de console por página do Chrome; sem armazenamento de logs no lado da extensão)
  • popup.js - Popup da barra de ferramentas com botão de conexão
  • panel.js - Painel DevTools (botão de conexão, visualizador de mensagens WebSocket)

Recursos do Painel DevTools

  • Botão de Conexão - Conectar/desconectar a aba inspecionada
  • Status da Conexão - Indicador de conexão com o servidor em tempo real
  • Visualizador de Mensagens - Visualização ao vivo das mensagens WebSocket entre extensão e servidor
  • Configuração de Keepalive - Intervalo de ping configurável

O painel é opcional — conexões e comandos são gerenciados pelo service worker em segundo plano, então a automação funciona com o DevTools fechado.

Solução de Problemas

Problemas de Conexão

  • A extensão se conecta ao servidor na porta 61822
  • Verifique se o servidor está em execução (curl http://localhost:61822/)
  • Verifique o selo do ícone da barra de ferramentas: ✓ = conectado, ↻ = tentando novamente
  • Verifique o console do service worker em segundo plano (chrome://extensions/ → Kapture → service worker)
  • Verifique os logs do servidor no terminal

Extensão Não Aparecendo

  • Certifique-se de que a extensão está carregada e habilitada
  • Feche e reabra o DevTools
  • Recarregue a extensão em chrome://extensions/

Timeouts de Comando

  • O timeout padrão é de 5 segundos
  • Alguns comandos aceitam parâmetro de timeout personalizado
  • Verifique se os seletores de elementos estão corretos

Segurança

  • Os comandos DOM são executados no mundo isolado do content script; comandos de entrada/navegação/captura de tela usam chrome.debugger (CDP)
  • Cada aba possui um ID único que evita interferência entre abas
  • Sem acesso direto ao sistema de arquivos a partir da extensão
  • O registro de abas impõe isolamento de comandos

Licença

MIT