Servidor MCP Selenium

Um servidor MCP (Model Context Protocol) completo para automação Selenium com TypeScript, projetado para integração direta com VS Code e GitHub Copilot.

🚀 Características

• Automação completa do navegador com Selenium WebDriver
• Suporte para múltiplos navegadores: Chrome, Firefox, Edge
• Integração nativa com VS Code através do protocolo MCP
• Comandos em português para facilidade de uso
• Configurações avançadas do navegador (headless, window size, user data dir)
• Captura de screenshots automática
• Execução de JavaScript personalizado
• Gerenciamento de frames/iframes
• Localização de elementos com múltiplas estratégias

📦 Instalação

# Clone o repositório
git clone <seu-repositorio>
cd MCP_Selenium

# Instale as dependências
npm install

# Compile o projeto
npm run build

🛠️ Configuração

VS Code MCP Configuration

O arquivo .vscode/mcp.json já está configurado para usar o servidor localmente:

{
  "servers": {
    "mcp-selenium": {
      "type": "stdio", 
      "command": "node",
      "args": ["c:\\Estudos\\MCP_Selenium\\build\\index.js"]
    }
  }
}

Claude Desktop Configuration

Para usar com Claude Desktop, adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "selenium": {
      "command": "node",
      "args": ["C:\\caminho\\completo\\para\\MCP_Selenium\\build\\index.js"]
    }
  }
}

🎯 Ferramentas Disponíveis

1. start_browser - Iniciar Navegador

Inicia uma sessão do navegador com opções personalizáveis.

Parâmetros:

• browser: chrome | firefox | edge
• options: (opcional)
  • headless: boolean - Executar em modo headless
  • windowSize: { width: number, height: number }
  • arguments: string[] - Argumentos adicionais
  • userDataDir: string - Diretório de dados do usuário
  • downloadPath: string - Caminho para downloads

Exemplo:

{
  "browser": "chrome",
  "options": {
    "headless": false,
    "windowSize": { "width": 1920, "height": 1080 },
    "arguments": ["--no-sandbox", "--disable-dev-shm-usage"]
  }
}

2. navigate - Navegar para URL

Navega para uma URL específica.

Parâmetros:

• url: string - URL para navegar

3. find_element - Encontrar Elemento

Localiza um elemento na página.

Parâmetros:

• strategy: id | name | className | tagName | linkText | partialLinkText | css | xpath
• value: string - Valor para a estratégia
• timeout: number (opcional) - Timeout em ms (padrão: 10000)

4. click_element - Clicar Elemento

Clica em um elemento específico.

Parâmetros:

• strategy: estratégia de localização
• value: string - Valor para localizar
• timeout: number (opcional)

5. send_keys - Digitar Texto

Digita texto em um elemento.

Parâmetros:

• strategy: estratégia de localização
• value: string - Valor para localizar
• text: string - Texto para digitar
• clear: boolean (opcional) - Limpar campo antes (padrão: true)
• timeout: number (opcional)

6. get_element_text - Obter Texto

Obtém o texto de um elemento.

Parâmetros:

• strategy: estratégia de localização
• value: string - Valor para localizar
• timeout: number (opcional)

7. get_element_attribute - Obter Atributo

Obtém um atributo específico de um elemento.

Parâmetros:

• strategy: estratégia de localização
• value: string - Valor para localizar
• attribute: string - Nome do atributo
• timeout: number (opcional)

8. wait_for_element - Aguardar Elemento

Aguarda até que um elemento apareça na página.

Parâmetros:

• strategy: estratégia de localização
• value: string - Valor para localizar
• timeout: number (opcional)
• visible: boolean (opcional) - Aguardar visibilidade (padrão: true)

9. execute_script - Executar JavaScript

Executa código JavaScript na página.

Parâmetros:

• script: string - Código JavaScript
• args: any[] (opcional) - Argumentos para o script

10. take_screenshot - Capturar Screenshot

Captura uma screenshot da página atual.

Parâmetros:

• filename: string (opcional) - Nome do arquivo
• path: string (opcional) - Diretório (padrão: "./screenshots")

11. get_page_info - Informações da Página

Obtém informações sobre a página atual (título, URL, etc.).

12. switch_to_frame - Mudar para Frame

Muda o contexto para um frame/iframe específico.

Parâmetros:

• strategy: index | id | name | element
• value: string | number - Identificador do frame
• timeout: number (opcional)

13. switch_to_default_content - Voltar ao Conteúdo Principal

Volta para o conteúdo principal da página (sai de frames).

14. scroll_to_element - Rolar até Elemento

Rola a página até um elemento específico.

Parâmetros:

• strategy: estratégia de localização
• value: string - Valor para localizar
• timeout: number (opcional)

15. close_session - Fechar Sessão

Fecha a sessão atual do navegador.

💡 Exemplos de Uso

Exemplo 1: Automação de Login

// 1. Iniciar navegador
start_browser({ "browser": "chrome", "options": { "headless": false } })

// 2. Navegar para site
navigate({ "url": "https://example.com/login" })

// 3. Preencher formulário
send_keys({ "strategy": "id", "value": "username", "text": "meu_usuario" })
send_keys({ "strategy": "id", "value": "password", "text": "minha_senha" })

// 4. Clicar botão login
click_element({ "strategy": "css", "value": "button[type='submit']" })

// 5. Aguardar redirecionamento
wait_for_element({ "strategy": "css", "value": ".dashboard" })

// 6. Capturar screenshot
take_screenshot({ "filename": "dashboard.png" })

Exemplo 2: Scraping de Dados

// 1. Iniciar navegador headless
start_browser({ 
  "browser": "chrome", 
  "options": { 
    "headless": true,
    "arguments": ["--no-sandbox"] 
  } 
})

// 2. Navegar e extrair dados
navigate({ "url": "https://example.com/products" })

// 3. Obter informações de produtos
get_element_text({ "strategy": "css", "value": ".product-title" })
get_element_attribute({ "strategy": "css", "value": ".price", "attribute": "data-price" })

// 4. Executar JavaScript customizado
execute_script({ 
  "script": "return Array.from(document.querySelectorAll('.product')).map(p => ({ title: p.querySelector('.title').textContent, price: p.querySelector('.price').textContent }))"
})

🔧 Desenvolvimento

Scripts Disponíveis

# Desenvolvimento com watch mode
npm run dev

# Build do projeto
npm run build

# Iniciar servidor
npm start

# Teste do servidor
npm test

Estrutura do Projeto

MCP_Selenium/
├── src/
│   └── index.ts          # Servidor MCP principal
├── build/                # Arquivos compilados
├── .vscode/
│   └── mcp.json         # Configuração MCP para VS Code
├── .github/
│   └── copilot-instructions.md
├── screenshots/          # Screenshots capturadas
├── package.json
├── tsconfig.json
└── README.md

🛡️ Segurança

• O servidor executa localmente, mantendo controle total sobre as operações
• Todas as ações do navegador requerem comandos explícitos
• Screenshots são salvas localmente no diretório do projeto
• Não há comunicação com serviços externos além dos sites navegados

🚨 Pré-requisitos

• Node.js 18+
• Chrome, Firefox ou Edge instalados
• VS Code (para integração MCP)

📝 Limitações Conhecidas

• Suporte apenas para um navegador ativo por vez
• Screenshots são salvas apenas localmente
• Requer que os drivers do navegador estejam disponíveis no PATH

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• Selenium WebDriver - Framework de automação web
• Model Context Protocol - Protocolo de contexto para IA
• TypeScript - Linguagem de programação
• Inspirado no projeto angiejones/mcp-selenium