npm package: @rodrigolacerda/mcp-selenium-br
Description: Servidor MCP para automação Selenium com comandos em português - VS Code integration
Author: Rodrigo Lacerda
Latest version: 1.1.2

# 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

```bash
# 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:

```json
{
  "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`:

```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:**
```javascript
{
  "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
```javascript
// 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
```javascript
// 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

```bash
# 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](LICENSE) para detalhes.

## 🙏 Agradecimentos

- [Selenium WebDriver](https://selenium.dev/) - Framework de automação web
- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocolo de contexto para IA
- [TypeScript](https://www.typescriptlang.org/) - Linguagem de programação
- Inspirado no projeto [angiejones/mcp-selenium](https://github.com/angiejones/mcp-selenium)