# Servidor MCP Selenium WebDriver

Un servidor MCP (Model Context Protocol) completo que implementa Selenium WebDriver para automatización de navegadores con capacidades avanzadas de evasión de detección, soporte para múltiples navegadores y funcionalidades completas de interacción web.

## Características Principales

### 🚀 Automatización Completa de Navegadores
- **Navegación web**: Navegar a URLs, obtener información de páginas
- **Interacción con elementos**: Buscar, hacer clic, escribir texto, subir archivos
- **Acciones de ratón**: Hover, drag and drop, clic derecho, doble clic
- **Manejo de teclado**: Envío de teclas especiales (Enter, Tab, flechas, etc.)
- **Capturas de pantalla**: Pantalla completa o elementos específicos
- **Ejecución de JavaScript**: Scripts personalizados en el navegador

### 🕵️ Evasión de Detección Avanzada
- **Undetected Chrome**: Integración con undetected-chromedriver
- **Randomización**: User agents y viewports aleatorios
- **Scripts stealth**: Ocultación de propiedades de automatización
- **Simulación humana**: Escritura y scroll con delays realistas
- **Gestión de cookies**: Control completo de cookies y sesiones

### 🌐 Soporte Multi-Navegador
- **Chrome**: Soporte completo con evasión de detección
- **Firefox**: Implementación nativa de Selenium
- **Detección automática**: Identificación de navegadores instalados
- **Configuraciones específicas**: Optimizaciones por navegador

### ⚙️ Gestión Avanzada de Sesiones
- **Múltiples sesiones**: Hasta 10 sesiones simultáneas por defecto
- **Gestión automática**: Limpieza de sesiones expiradas
- **Configuraciones flexibles**: Presets para diferentes casos de uso
- **Proxies**: Soporte para HTTP, HTTPS y SOCKS

## Instalación

### Requisitos Previos

- Python 3.8 o superior
- Chrome y/o Firefox instalados
- Dependencias del sistema para Selenium

### Instalación de Dependencias

```bash
# Clonar o descargar el proyecto
cd mcp_selenium_server

# Instalar dependencias de Python
pip install -r requirements.txt
```

### Dependencias del Sistema

#### Ubuntu/Debian
```bash
# Chrome
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update
sudo apt install google-chrome-stable

# Firefox
sudo apt install firefox
```

#### CentOS/RHEL
```bash
# Chrome
sudo yum install -y google-chrome-stable

# Firefox
sudo yum install firefox
```

#### Windows
- Descargar e instalar Chrome desde https://www.google.com/chrome/
- Descargar e instalar Firefox desde https://www.mozilla.org/firefox/

#### macOS
```bash
# Con Homebrew
brew install --cask google-chrome
brew install --cask firefox
```

## Configuración

### Configuraciones Predefinidas

El servidor incluye tres configuraciones predefinidas:

#### 1. Configuración por Defecto
```python
DEFAULT_CONFIG = ServerConfig(
    max_sessions=10,
    session_timeout=3600,
    default_browser="chrome",
    browser_options=BrowserOptions(
        headless=False,
        window_width=1920,
        window_height=1080,
        incognito=True
    )
)
```

#### 2. Configuración Stealth (Recomendada para evasión)
```python
STEALTH_CONFIG = ServerConfig(
    browser_options=BrowserOptions(
        headless=True,
        user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
        disable_images=True,
        custom_args=[
            "--disable-blink-features=AutomationControlled",
            "--disable-dev-shm-usage",
            "--no-first-run",
            # ... más argumentos stealth
        ]
    ),
    detection_evasion=DetectionEvasionConfig(
        use_undetected_chrome=True,
        stealth_mode=True,
        randomize_user_agent=True,
        randomize_viewport=True
    )
)
```

#### 3. Configuración de Rendimiento
```python
PERFORMANCE_CONFIG = ServerConfig(
    browser_options=BrowserOptions(
        headless=True,
        disable_images=True,
        disable_javascript=False,
        custom_args=[
            "--disable-dev-shm-usage",
            "--disable-gpu",
            "--no-sandbox"
        ]
    )
)
```

### Configuración de Proxies

```python
proxy_config = {
    "http": "http://proxy.example.com:8080",
    "https": "https://proxy.example.com:8080",
    "socks": "socks5://proxy.example.com:1080"
}
```

## Uso Básico

### Iniciar el Servidor

```bash
# Modo desarrollo
python server.py

# Con MCP CLI
mcp dev server.py

# Instalar en Claude Desktop
mcp install server.py
```

### Ejemplo de Uso Básico

```python
# 1. Iniciar navegador
result = start_browser(
    browser_type="chrome",
    options={
        "headless": False,
        "window_width": 1920,
        "window_height": 1080
    },
    detection_evasion={
        "use_undetected_chrome": True,
        "stealth_mode": True
    }
)
session_id = result["session_id"]

# 2. Navegar a una página
navigate_to_url(session_id, "https://example.com")

# 3. Buscar un elemento
element = find_element(
    session_id=session_id,
    strategy="css_selector",
    value="input[name='search']"
)

# 4. Escribir texto
type_text(
    session_id=session_id,
    strategy="css_selector",
    value="input[name='search']",
    text="selenium automation"
)

# 5. Hacer clic en botón
click_element(
    session_id=session_id,
    strategy="css_selector",
    value="button[type='submit']"
)

# 6. Tomar captura de pantalla
take_screenshot(
    session_id=session_id,
    file_path="/path/to/screenshot.png"
)

# 7. Cerrar navegador
close_browser(session_id)
```

## Herramientas MCP Disponibles

### Gestión de Navegadores

| Herramienta | Descripción |
|-------------|-------------|
| `start_browser` | Inicia una nueva sesión de navegador |
| `close_browser` | Cierra una sesión específica |
| `detect_available_browsers` | Detecta navegadores instalados |
| `get_recommended_browser` | Obtiene el navegador recomendado |
| `check_browser_support` | Verifica soporte de WebDriver |

### Navegación y Páginas

| Herramienta | Descripción |
|-------------|-------------|
| `navigate_to_url` | Navega a una URL específica |
| `get_page_info` | Obtiene información de la página actual |
| `execute_script` | Ejecuta JavaScript en el navegador |

### Interacción con Elementos

| Herramienta | Descripción |
|-------------|-------------|
| `find_element` | Busca elementos con diferentes estrategias |
| `click_element` | Hace clic en un elemento |
| `type_text` | Escribe texto en un elemento |
| `upload_file` | Sube archivos a inputs de tipo file |

### Acciones Avanzadas

| Herramienta | Descripción |
|-------------|-------------|
| `perform_mouse_action` | Acciones de ratón (hover, drag & drop) |
| `send_keys` | Envía teclas especiales |
| `take_screenshot` | Captura pantalla completa o elementos |

### Evasión de Detección

| Herramienta | Descripción |
|-------------|-------------|
| `apply_stealth_mode` | Aplica todas las técnicas stealth |
| `randomize_user_agent` | Cambia a un user agent aleatorio |
| `randomize_viewport` | Cambia el tamaño de ventana |
| `simulate_human_typing` | Escritura con delays humanos |
| `scroll_like_human` | Scroll gradual simulando humano |
| `add_random_delay` | Agrega delays aleatorios |

### Gestión de Sesiones

| Herramienta | Descripción |
|-------------|-------------|
| `list_active_sessions` | Lista todas las sesiones activas |
| `get_session_info` | Información detallada de una sesión |
| `close_all_sessions` | Cierra todas las sesiones |
| `cleanup_expired_sessions` | Limpia sesiones expiradas |

### Gestión de Cookies

| Herramienta | Descripción |
|-------------|-------------|
| `manage_cookies` | Gestión completa de cookies |

### Configuración del Servidor

| Herramienta | Descripción |
|-------------|-------------|
| `get_server_status` | Estado actual del servidor |
| `update_server_config` | Actualiza configuración con presets |

## Ejemplos Avanzados

### Automatización con Evasión de Detección

```python
# Configuración stealth completa
session_result = start_browser(
    browser_type="chrome",
    options={
        "headless": True,
        "disable_images": True,
        "incognito": True
    },
    detection_evasion={
        "use_undetected_chrome": True,
        "stealth_mode": True,
        "randomize_user_agent": True,
        "randomize_viewport": True
    }
)
session_id = session_result["session_id"]

# Aplicar modo stealth adicional
apply_stealth_mode(session_id)

# Navegar con delays humanos
navigate_to_url(session_id, "https://example.com")
add_random_delay(1.0, 3.0)

# Scroll humano
scroll_like_human(session_id, "down", 500, 8)
add_random_delay(0.5, 1.5)

# Escritura humana
simulate_human_typing(
    session_id=session_id,
    strategy="id",
    value="search-input",
    text="automated search query",
    min_delay=0.05,
    max_delay=0.15
)

# Gestión de cookies
manage_cookies(
    session_id=session_id,
    action="add",
    cookie_data={
        "name": "session_token",
        "value": "abc123",
        "domain": "example.com"
    }
)
```

### Automatización de Formularios

```python
# Llenar formulario complejo
session_id = start_browser("chrome")["session_id"]
navigate_to_url(session_id, "https://forms.example.com")

# Campos de texto
type_text(session_id, "id", "first_name", "John")
type_text(session_id, "id", "last_name", "Doe")
type_text(session_id, "id", "email", "john.doe@example.com")

# Seleccionar dropdown
click_element(session_id, "id", "country_select")
click_element(session_id, "xpath", "//option[text()='United States']")

# Subir archivo
upload_file(
    session_id=session_id,
    strategy="id",
    value="file_upload",
    file_path="/path/to/document.pdf"
)

# Checkbox
click_element(session_id, "id", "terms_checkbox")

# Enviar formulario
click_element(session_id, "css_selector", "button[type='submit']")

# Esperar y verificar
add_random_delay(2.0, 4.0)
page_info = get_page_info(session_id)
print(f"Página actual: {page_info['title']}")
```

### Scraping con Múltiples Sesiones

```python
# Iniciar múltiples sesiones
sessions = []
urls = ["https://site1.com", "https://site2.com", "https://site3.com"]

for i, url in enumerate(urls):
    result = start_browser(
        browser_type="chrome",
        options={"headless": True},
        detection_evasion={"use_undetected_chrome": True}
    )
    session_id = result["session_id"]
    sessions.append(session_id)
    
    # Navegar en paralelo
    navigate_to_url(session_id, url)
    apply_stealth_mode(session_id)

# Procesar cada sesión
for i, session_id in enumerate(sessions):
    # Extraer datos
    elements = find_element(
        session_id=session_id,
        strategy="css_selector",
        value=".data-item",
        multiple=True
    )
    
    # Tomar captura
    take_screenshot(
        session_id=session_id,
        file_path=f"/screenshots/site_{i+1}.png"
    )

# Limpiar todas las sesiones
close_all_sessions()
```

## Estrategias de Localización de Elementos

El servidor soporta todas las estrategias estándar de Selenium:

| Estrategia | Descripción | Ejemplo |
|------------|-------------|---------|
| `id` | Por atributo ID | `"search-button"` |
| `name` | Por atributo name | `"username"` |
| `class_name` | Por clase CSS | `"btn-primary"` |
| `tag_name` | Por nombre de etiqueta | `"button"` |
| `css_selector` | Selector CSS | `"div.container > p"` |
| `xpath` | Expresión XPath | `"//div[@class='content']//p"` |
| `link_text` | Texto exacto del enlace | `"Click here"` |
| `partial_link_text` | Texto parcial del enlace | `"Click"` |

### Ejemplos de Selectores

```python
# Por ID
find_element(session_id, "id", "submit-btn")

# Por clase CSS
find_element(session_id, "class_name", "form-control")

# Selector CSS complejo
find_element(session_id, "css_selector", "div.modal .btn-primary:not(:disabled)")

# XPath avanzado
find_element(session_id, "xpath", "//table//tr[contains(@class, 'data-row')][position()>1]")

# Múltiples elementos
find_element(session_id, "css_selector", ".product-item", multiple=True)
```

## Configuración de Proxies

### Tipos de Proxy Soportados

```python
# HTTP Proxy
proxy_config = {"http": "http://proxy.example.com:8080"}

# HTTPS Proxy
proxy_config = {"https": "https://proxy.example.com:8080"}

# SOCKS Proxy
proxy_config = {"socks": "socks5://proxy.example.com:1080"}

# Proxy con autenticación
proxy_config = {"http": "http://user:pass@proxy.example.com:8080"}

# Usar proxy al iniciar navegador
start_browser(
    browser_type="chrome",
    proxy=proxy_config,
    options={"headless": True}
)
```

## Manejo de Errores

El servidor maneja automáticamente los errores comunes y proporciona mensajes descriptivos:

```python
# Ejemplo de respuesta con error
{
    "success": False,
    "error": "Timeout: Elemento no encontrado",
    "message": "No se pudo encontrar elemento con id='missing-element' en 10 segundos"
}

# Ejemplo de respuesta exitosa
{
    "success": True,
    "session_id": "abc123-def456",
    "message": "Navegador chrome iniciado exitosamente"
}
```

### Errores Comunes y Soluciones

| Error | Causa | Solución |
|-------|-------|----------|
| `Sesión no encontrada` | ID de sesión inválido | Verificar que la sesión esté activa |
| `Timeout: Elemento no encontrado` | Selector incorrecto o elemento no visible | Revisar selector y aumentar timeout |
| `WebDriverException` | Problema con el driver | Reinstalar webdriver-manager |
| `ElementNotInteractableException` | Elemento no clickeable | Usar scroll o esperar a que sea visible |

## Mejores Prácticas

### Para Evasión de Detección

1. **Usar configuración stealth**: Siempre aplicar `STEALTH_CONFIG` para sitios que detectan bots
2. **Delays aleatorios**: Agregar delays entre acciones para simular comportamiento humano
3. **Randomización**: Cambiar user agents y viewports regularmente
4. **Gestión de cookies**: Mantener cookies de sesión para parecer un usuario real
5. **Scroll gradual**: Usar `scroll_like_human` en lugar de scroll instantáneo

### Para Rendimiento

1. **Modo headless**: Usar para operaciones en lote
2. **Deshabilitar imágenes**: Reducir tiempo de carga
3. **Gestión de sesiones**: Cerrar sesiones no utilizadas
4. **Timeouts apropiados**: Configurar timeouts según la velocidad del sitio

### Para Estabilidad

1. **Manejo de errores**: Siempre verificar `success` en las respuestas
2. **Limpieza de sesiones**: Usar `cleanup_expired_sessions` regularmente
3. **Verificar elementos**: Usar `find_element` antes de interactuar
4. **Capturas de pantalla**: Tomar capturas para debugging

## Limitaciones

- **Máximo de sesiones**: 10 sesiones simultáneas por defecto (configurable)
- **Timeout de sesión**: 1 hora por defecto (configurable)
- **Navegadores soportados**: Chrome y Firefox únicamente
- **Detección**: Algunos sitios avanzados pueden detectar automatización

## Solución de Problemas

### Problemas de Instalación

```bash
# Error: ChromeDriver no encontrado
pip install --upgrade webdriver-manager

# Error: Dependencias del sistema
sudo apt-get install -y libgconf-2-4 libxss1 libxtst6 libxrandr2 libasound2 libpangocairo-1.0-0 libatk1.0-0 libcairo-gobject2 libgtk-3-0 libgdk-pixbuf2.0-0

# Error: Permisos
sudo chmod +x /usr/bin/google-chrome
```

### Problemas de Ejecución

```bash
# Verificar navegadores disponibles
python -c "
from browser_detection import BrowserDetection
bd = BrowserDetection()
print(bd.detect_available_browsers())
"

# Probar configuración básica
python -c "
from webdriver_manager import WebDriverManager
wm = WebDriverManager()
driver = wm.create_driver('chrome', BrowserOptions())
print('Chrome funciona correctamente')
driver.quit()
"
```

## Contribución

Para contribuir al proyecto:

1. Fork el repositorio
2. Crear una rama para la nueva característica
3. Implementar cambios con tests
4. Enviar pull request

## Licencia

Este proyecto está bajo la licencia MIT.