Playwright Record MCP

Automação de navegador usando Playwright com gravação de vídeo. Permite que LLMs interajam com páginas web por meio de snapshots estruturados de acessibilidade.

GitHub
6
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

Playwright Record MCP

Playwright Record MCP é um servidor de Model Context Protocol (MCP) que fornece capacidades de automação de navegador usando Playwright. Este servidor adiciona funcionalidade de gravação de vídeo para registrar interações do navegador. Ele permite que LLMs (Modelos de Linguagem de Grande Porte) interajam com páginas da web por meio de snapshots de acessibilidade estruturados, sem exigir capturas de tela ou modelos visuais.

Principais Recursos

  • Rápido e leve: Usa a árvore de acessibilidade do Playwright, não entrada baseada em pixels.
  • Amigável para LLMs: Não precisa de modelos de visão, opera puramente em dados estruturados.
  • Aplicação determinística de ferramentas: Evita ambiguidades comuns em abordagens baseadas em capturas de tela.
  • Gravação de vídeo: Capacidade de gravar interações do navegador como vídeo.

Casos de Uso

  • Navegação na web e preenchimento de formulários
  • Extração de dados de conteúdo estruturado
  • Testes automatizados orientados por LLM
  • Interação geral com navegador para agentes
  • Gravação e análise de interações do navegador

Instalação

Instalação via NPM

npm install @playwright/record-mcp

Ou

npx @playwright/record-mcp

Exemplo de Configuração

NPX

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/record-mcp@latest"
      ]
    }
  }
}

Instalação no VS Code

Você pode instalar o servidor Playwright Record MCP usando a CLI do VS Code:

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/record-mcp@latest"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/record-mcp@latest"]}'

Após a instalação, o servidor Playwright Record MCP estará disponível para uso com seu agente GitHub Copilot no VS Code.

Opções de Linha de Comando

O servidor Playwright Record MCP suporta as seguintes opções de linha de comando:

  • --browser <browser>: Navegador ou canal do Chrome a ser usado. Valores possíveis:
    • chrome, firefox, webkit, msedge
    • Canais do Chrome: chrome-beta, chrome-canary, chrome-dev
    • Canais do Edge: msedge-beta, msedge-canary, msedge-dev
    • Padrão: chrome
  • --caps <caps>: Lista separada por vírgulas de capacidades a serem habilitadas, valores possíveis: tabs, pdf, history, wait, files, install. O padrão é todas.
  • --cdp-endpoint <endpoint>: Endpoint CDP para conectar
  • --executable-path <path>: Caminho para o executável do navegador
  • --headless: Executar navegador em modo headless (com interface por padrão)
  • --port <port>: Porta para escutar no transporte SSE
  • --user-data-dir <path>: Caminho para o diretório de dados do usuário
  • --vision: Executar servidor que usa capturas de tela (snapshots Aria são usados por padrão)
  • --record: Gravar interações do navegador como vídeo (novo recurso)
  • --record-path <path>: Caminho para salvar arquivos de gravação (padrão: ./recordings)
  • --record-format <format>: Formato de gravação, valores possíveis: mp4, webm (padrão: mp4)

Diretório de Dados do Usuário

O Playwright Record MCP iniciará o navegador com um novo perfil, localizado em:

  • Windows: %USERPROFILE%\AppData\Local\ms-playwright\mcp-chrome-profile
  • macOS: ~/Library/Caches/ms-playwright/mcp-chrome-profile
  • Linux: ~/.cache/ms-playwright/mcp-chrome-profile

Todas as informações de login serão armazenadas nesse perfil; você pode excluí-lo entre sessões se quiser limpar o estado offline.

Executando Navegador Headless (Navegador sem GUI)

Este modo é útil para operações em segundo plano ou em lote.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/record-mcp@latest",
        "--headless"
      ]
    }
  }
}

Usando Gravação de Vídeo

Para usar o recurso de gravação de vídeo, use a flag --record:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/record-mcp@latest",
        "--record"
      ]
    }
  }
}

Para especificar o caminho de salvamento do arquivo de gravação:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/record-mcp@latest",
        "--record",
        "--record-path", "./my-recordings"
      ]
    }
  }
}

Para especificar o formato de gravação:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/record-mcp@latest",
        "--record",
        "--record-format", "webm"
      ]
    }
  }
}

Executando Navegador com Interface no Linux sem DISPLAY

Ao executar um navegador com interface em um sistema sem display ou a partir de processos de trabalho de IDEs, execute o servidor MCP em um ambiente com DISPLAY e passe a flag --port para habilitar o transporte SSE.

npx @playwright/record-mcp@latest --port 8931

Em seguida, na configuração do cliente MCP, defina o url para o endpoint SSE:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/sse"
    }
  }
}

Docker

NOTA: A implementação Docker atualmente suporta apenas Chromium headless.

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "mcp/playwright-record"]
    }
  }
}

Para construir com Docker:

docker build -t mcp/playwright-record .

Modos de Ferramenta

As ferramentas estão disponíveis em dois modos:

  1. Modo Snapshot (padrão): Usa snapshots de acessibilidade para melhor desempenho e confiabilidade
  2. Modo Visão: Usa capturas de tela para interações baseadas em visual

Para usar o Modo Visão, adicione a flag --vision ao iniciar o servidor:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/record-mcp@latest",
        "--vision"
      ]
    }
  }
}

O Modo Visão funciona melhor com modelos de uso de computador que conseguem interagir com elementos usando o espaço de coordenadas X-Y, com base na captura de tela fornecida.

Uso Programático com Transportes Personalizados

import http from 'http';

import { createServer } from '@playwright/record-mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright Record MCP server with SSE transport
  const mcpServer = await createServer({ headless: true, record: true });
  const transport = new SSEServerTransport('/messages', res);
  await mcpServer.connect(transport);

  // ...
});

Interações Baseadas em Snapshot

  • browser_snapshot

    • Descrição: Capturar snapshot de acessibilidade da página atual, isso é melhor que captura de tela
    • Parâmetros: Nenhum

  • browser_click

    • Descrição: Realizar clique em uma página da web
    • Parâmetros:
      • element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
      • ref (string): Referência exata do elemento alvo do snapshot da página

  • browser_drag

    • Descrição: Realizar arrastar e soltar entre dois elementos
    • Parâmetros:
      • startElement (string): Descrição legível do elemento de origem usada para obter permissão para interagir com o elemento
      • startRef (string): Referência exata do elemento de origem do snapshot da página
      • endElement (string): Descrição legível do elemento de destino usada para obter permissão para interagir com o elemento
      • endRef (string): Referência exata do elemento de destino do snapshot da página

  • browser_hover

    • Descrição: Passar o mouse sobre o elemento na página
    • Parâmetros:
      • element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
      • ref (string): Referência exata do elemento alvo do snapshot da página

  • browser_type

    • Descrição: Digitar texto em elemento editável
    • Parâmetros:
      • element (string): Descrição legível do elemento usada para obter permissão para interagir com o elemento
      • ref (string): Referência exata do elemento alvo do snapshot da página
      • text (string): Texto para digitar no elemento
      • submit (booleano, opcional): Se deve enviar o texto digitado (pressionar Enter depois)
      • slowly (booleano, opcional): Se deve digitar um caractere por vez. Útil para acionar manipuladores de teclado na página. Por padrão, todo o texto é preenchido de uma vez.

Ferramentas de Gravação de Vídeo (Novo Recurso)

  • browser_record_start

    • Descrição: Iniciar gravação de interações do navegador
    • Parâmetros:
      • path (string, opcional): Caminho para salvar o arquivo de gravação
      • format (string, opcional): Formato de gravação (mp4 ou webm)

  • browser_record_stop

    • Descrição: Parar e salvar a gravação de interações do navegador
    • Parâmetros: Nenhum

  • browser_record_pause

    • Descrição: Pausar a gravação atual
    • Parâmetros: Nenhum

  • browser_record_resume

    • Descrição: Retomar uma gravação pausada
    • Parâmetros: Nenhum

  • browser_record_list

    • Descrição: Retornar uma lista dos arquivos de gravação atuais
    • Parâmetros: Nenhum

Exemplos

Iniciando e Parando a Gravação de Vídeo

// Start video recording
await mcpServer.invoke('browser_record_start', {
  path: './my-recordings/test-recording.mp4',
  format: 'mp4'
});

// Perform browser navigation
await mcpServer.invoke('browser_navigate', {
  url: 'https://example.com'
});

// Interact with the page
const snapshot = await mcpServer.invoke('browser_snapshot');
// Find elements in the snapshot...

// Stop video recording
await mcpServer.invoke('browser_record_stop');

Navegadores Suportados

  • Chrome
  • Firefox
  • WebKit
  • Microsoft Edge

Requisitos

  • Node.js 18 ou superior
  • O navegador necessário deve estar instalado (ou use a ferramenta browser_install para instalá-lo)

Licença

Licença Apache-2.0