PlayMCP Browser Automation Server

Um servidor para automação de navegador usando Playwright, fornecendo ferramentas poderosas para raspagem web, testes e automação.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor de Automação de Navegador PlayMCP

Um servidor MCP (Model Context Protocol) abrangente para automação de navegador usando Playwright. Este servidor fornece 38 ferramentas poderosas para web scraping, testes e automação.

PlayBrowser Automation Server MCP server

Recursos

🚀 Automação Central do Navegador (21 ferramentas)

Navegação: navigate, goForward, goBack (via scroll)
Interação: click, type, hover, dragAndDrop, selectOption
Controle do Mouse: moveMouse, mouseMove, mouseClick, mouseDrag
Teclado: pressKey
Espera: waitForText, waitForSelector
Capturas de Tela: screenshot, takeScreenshot (aprimoradas)
Informações da Página: getPageSource, getPageText, getPageTitle, getPageUrl
Análise de Elementos: getElementContent, getElementHierarchy
Scripts e Estilos: getScripts, getStylesheets, getMetaTags

🔍 Extração Avançada de Dados (7 ferramentas)

Links e Imagens: getLinks, getImages
Formulários: getForms
Monitoramento do Console: getConsoleMessages
Monitoramento de Rede: getNetworkRequests
Execução de JavaScript: executeJavaScript, evaluateWithReturn

📁 Operações com Arquivos (2 ferramentas)

Upload de Arquivos: uploadFiles
Tratamento de Diálogos: handleDialog

⚙️ Gerenciamento do Navegador (8 ferramentas)

Controle do Navegador: openBrowser, closeBrowser
Gerenciamento de Viewport: resize
Manipulação de Páginas: scroll (aprimorada com feedback)
Hierarquia de Elementos: Análise profunda do DOM com profundidade configurável
Capturas de Tela Aprimoradas: Página inteira, elementos específicos, caminhos personalizados
Coordenadas do Mouse: Controle de mouse com precisão de pixel
Condições de Espera: Espera inteligente por elementos e texto

Início Rápido

Instalação

# Clone the repository
git clone https://github.com/jomon003/PlayMCP.git
cd PlayMCP

# Install dependencies
npm install

# Build the project
npm run build

# Test the server
npm test

Uso Básico

// Start the server
node ./dist/server.js

// Send MCP commands via JSON-RPC
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Categorias de Ferramentas

🎯 Navegação e Interação

navigate: Ir para qualquer URL
goForward: Navegar para frente no histórico do navegador
click: Clicar em elementos com resolução inteligente de seletores
type: Digitar texto com simulação realista de teclado
hover: Passar o mouse sobre elementos para tooltips e interações
dragAndDrop: Arrastar elementos entre locais
selectOption: Escolher opções em menus suspensos e seleções múltiplas
pressKey: Enviar teclas específicas do teclado (Enter, Escape, etc.)

⏱️ Espera Inteligente

waitForText: Aguardar um texto específico aparecer
waitForSelector: Aguardar elementos carregarem
Timeouts e tratamento de erros integrados

🖱️ Controle Preciso do Mouse

mouseMove: Mover para coordenadas exatas
mouseClick: Clicar em pixels específicos
mouseDrag: Arrastar entre pontos de coordenadas
moveMouse: Posicionamento aprimorado do mouse

📊 Extração de Dados

getElementHierarchy: Análise profunda da estrutura do DOM
getConsoleMessages: Monitorar a saída do console do navegador
getNetworkRequests: Rastrear requisições e respostas HTTP
getLinks: Extrair todos os links da página com metadados
getImages: Obter todas as imagens com atributos
getForms: Analisar estruturas e campos de formulários

🎬 Visual e Mídia

screenshot: Captura de tela básica
takeScreenshot: Capturas de tela avançadas (página inteira, elementos, caminhos personalizados)
resize: Controlar dimensões do viewport

📁 Operações com Arquivos e Diálogos

uploadFiles: Tratar uploads de entrada de arquivos
handleDialog: Gerenciar alertas, confirmações e prompts

⚙️ Execução de JavaScript

executeJavaScript: Executar código JavaScript
evaluateWithReturn: Executar JS com valores de retorno

Controles Centrais do Navegador

openBrowser - Iniciar uma nova instância do navegador com modo headless opcional
navigate - Navegar para qualquer URL
click - Clicar em elementos usando seletores CSS
type - Digitar texto em campos de entrada
moveMouse - Mover o mouse para coordenadas específicas
scroll - Rolar a página por valores especificados com feedback aprimorado e suporte a rolagem suave
screenshot - Tirar capturas de tela da página, viewport ou elementos específicos
closeBrowser - Fechar a instância do navegador

Extração de Conteúdo da Página

getPageSource - Obter o código-fonte HTML completo
getPageText - Obter o conteúdo de texto (sem HTML)
getPageTitle - Obter o título da página
getPageUrl - Obter a URL atual
getScripts - Extrair todo o código JavaScript da página
getStylesheets - Extrair todas as folhas de estilo CSS
getMetaTags - Obter todas as meta tags com seus atributos
getLinks - Obter todos os links com href, texto e título
getImages - Obter todas as imagens com src, alt e dimensões
getForms - Obter todos os formulários com seus campos e atributos
getElementContent - Obter conteúdo HTML e texto de elementos específicos
getElementHierarchy - Obter a estrutura hierárquica do DOM com relações pai-filho

Recursos Avançados

executeJavaScript - Executar código JavaScript arbitrário na página e retornar resultados

Referência de Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros Obrigatórios
`openBrowser`	Iniciar instância do navegador	`headless?: boolean, debug?: boolean`
`navigate`	Navegar para URL	`url: string`
`click`	Clicar em elemento	`selector: string`
`type`	Digitar texto em elemento	`selector: string, text: string`
`moveMouse`	Mover mouse para coordenadas	`x: number, y: number`
`scroll`	Rolar página com feedback	`x: number, y: number, smooth?: boolean`
`screenshot`	Tirar captura de tela	`path: string, type?: string, selector?: string`
`getPageSource`	Obter código-fonte HTML	Nenhum
`getPageText`	Obter conteúdo de texto	Nenhum
`getPageTitle`	Obter título da página	Nenhum
`getPageUrl`	Obter URL atual	Nenhum
`getScripts`	Obter código JavaScript	Nenhum
`getStylesheets`	Obter folhas de estilo CSS	Nenhum
`getMetaTags`	Obter meta tags	Nenhum
`getLinks`	Obter todos os links	Nenhum
`getImages`	Obter todas as imagens	Nenhum
`getForms`	Obter todos os formulários	Nenhum
`getElementContent`	Obter conteúdo do elemento	`selector: string`
`getElementHierarchy`	Obter hierarquia do DOM	`selector?: string, maxDepth?: number, includeText?: boolean, includeAttributes?: boolean`
`executeJavaScript`	Executar JavaScript	`script: string`
`closeBrowser`	Fechar navegador	Nenhum

Instalação

Etapas Completas de Instalação

Pré-requisitos
- Node.js 16+ (baixe em nodejs.org)
- Git (para clonar o repositório)

Clonar e Configurar

git clone <repository-url>
cd PlayMCP
npm install
npm run build

Instalar Navegadores do Playwright
```
npx playwright install
```
Isso baixa os binários necessários do navegador (Chromium, Firefox, Safari).
Verificar a Instalação
```
npm run start
```
Você deve ver "Browser Automation MCP Server starting..." se tudo estiver funcionando.

Instalação Rápida

git clone <repository-url>
cd PlayMCP
npm install && npm run build && npx playwright install

Uso

Como Servidor MCP

Adicione ao seu arquivo de configuração MCP:

Configuração MCP Padrão:

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/server.js"],
      "cwd": "/path/to/PlayMCP",
      "description": "Browser automation server using Playwright"
    }
  }
}

Configuração Alternativa (funciona com VS Code GitHub Copilot):

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/PlayMCP/dist/server.js"]
    }
  }
}

Para usuários Windows:

{
  "servers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\path\\to\\PlayMCP\\dist\\server.js"]
    }
  }
}

Integração com VS Code GitHub Copilot

Este servidor MCP é totalmente compatível com VS Code GitHub Copilot. Após adicionar a configuração acima às suas configurações MCP, você pode usar todas as ferramentas de automação do navegador diretamente no VS Code.

Exemplos de Configuração

Claude Desktop (localização do config.json):

Windows: %APPDATA%\Claude\config.json
macOS: ~/Library/Application Support/Claude/config.json
Linux: ~/.config/Claude/config.json

Extensão MCP do VS Code: Adicione ao seu settings.json do VS Code ou ao arquivo de configuração MCP.

Exemplo de Configuração Completa:

{
  "mcpServers": {
    "playmcp-browser": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/username/PlayMCP/dist/server.js"],
      "description": "Browser automation with Playwright"
    }
  }
}

Exemplos de Ferramentas

Web Scraping Básico:

// Open browser and navigate
await openBrowser({ headless: false, debug: true })
await navigate({ url: "https://example.com" })

// Extract content
const title = await getPageTitle()
const links = await getLinks()
const forms = await getForms()

Automação de Formulários:

// Fill out a form
await click({ selector: "#login-button" })
await type({ selector: "#username", text: "user@example.com" })
await type({ selector: "#password", text: "password123" })
await click({ selector: "#submit" })

Interação com Páginas:

// Enhanced scrolling with feedback
await scroll({ x: 0, y: 500, smooth: false })
// Returns: { before: {x: 0, y: 0}, after: {x: 0, y: 500}, scrolled: {x: 0, y: 500} }

// Smooth scrolling
await scroll({ x: 0, y: 300, smooth: true })

// Mouse interaction
await moveMouse({ x: 100, y: 200 })
await click({ selector: ".dropdown-menu" })

Análise de Estrutura do DOM:

// Get page hierarchy (3 levels deep)
await getElementHierarchy({ maxDepth: 3 })

// Get detailed hierarchy with text and attributes
await getElementHierarchy({ 
  selector: "#main-content", 
  maxDepth: -1, 
  includeText: true, 
  includeAttributes: true 
})

// Get basic structure of a specific section
await getElementHierarchy({ selector: ".sidebar", maxDepth: 2 })

Execução Avançada de JavaScript:

// Run custom JavaScript
await executeJavaScript({ 
  script: "document.querySelectorAll('h1').length" 
})

// Modify page content
await executeJavaScript({ 
  script: "document.body.style.backgroundColor = 'lightblue'" 
})

// Extract complex data
await executeJavaScript({ 
  script: `
    Array.from(document.querySelectorAll('article')).map(article => ({
      title: article.querySelector('h2')?.textContent,
      summary: article.querySelector('p')?.textContent
    }))
  `
})

Captura de Tela e Documentação:

// Take screenshots
await screenshot({ path: "./full-page.png", type: "page" })
await screenshot({ path: "./element.png", type: "element", selector: "#main-content" })

Início Rápido

Instalar e configurar:

git clone <repo-url> && cd PlayMCP
npm install && npm run build && npx playwright install

Adicionar à configuração do seu cliente MCP

Começar a automatizar:

await openBrowser({ debug: true })
await navigate({ url: "https://news.ycombinator.com" })
const links = await getLinks()
console.log(`Found ${links.length} links`)

// Analyze page structure
const hierarchy = await getElementHierarchy({ maxDepth: 2 })
console.log('Page structure:', hierarchy)

Desenvolvimento

src/server.ts - Implementação principal do servidor MCP
src/controllers/playwright.ts - Controlador do navegador Playwright
src/mcp/ - Implementação do protocolo MCP
src/types/ - Definições de tipos TypeScript

Requisitos

Requisitos do Sistema

Node.js 16+ (versão LTS recomendada)
Sistema Operacional: Windows, macOS ou Linux
Memória: Pelo menos 2GB de RAM (4GB+ recomendado para uso intenso)
Espaço em Disco: ~500MB para binários do navegador e dependências

Dependências

Playwright: Gerencia a automação do navegador (instalado automaticamente)
TypeScript: Para compilação (dependência de desenvolvimento)
Binários do Navegador: Baixados via npx playwright install

Solução de Problemas

Problemas Comuns

Erro "Browser not initialized"
- Certifique-se de chamar openBrowser antes de outras operações do navegador
- Verifique se a versão do Node.js é 16 ou superior

Falha na instalação do Playwright

# Try manual browser installation
npx playwright install chromium
# Or install all browsers
npx playwright install

Erros de permissão no Linux/macOS

# Make sure the script is executable
chmod +x dist/server.js

Problemas de caminho na configuração MCP
- Use caminhos absolutos na configuração
- No Windows, use barras invertidas duplas: C:\\path\\to\\PlayMCP\\dist\\server.js
- Verifique se o caminho existe: node /path/to/PlayMCP/dist/server.js
Navegador trava ou expira
- Tente executar com headless: false para depuração
- Aumente a memória do sistema se estiver executando múltiplas instâncias do navegador
- Verifique se o software antivírus está bloqueando processos do navegador

Testando Sua Instalação

# Test the server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node ./dist/server.js

Você deve ver uma resposta JSON listando todas as ferramentas disponíveis.

Licença

Licença MIT