# MCP Server Puppeteer

Un servidor MCP (Model Context Protocol) para automatización de navegadores web usando Puppeteer en modo **headless**.

## Descripción

Este servidor MCP proporciona herramientas para controlar navegadores web mediante Puppeteer en modo headless (sin interfaz gráfica), permitiendo a aplicaciones de IA navegar por sitios web, interactuar con elementos, tomar capturas de pantalla y ejecutar JavaScript en el navegador. **Optimizado para ejecutarse en servidores sin entorno gráfico.**

## Características

- **Modo Headless**: Ejecuta sin interfaz gráfica, ideal para servidores
- **Navegación**: Navegar a URLs
- **Interacción**: Hacer clic, rellenar formularios, seleccionar opciones
- **Captura**: Tomar screenshots de páginas completas o elementos específicos
- **Evaluación**: Ejecutar código JavaScript en el contexto del navegador
- **Hover**: Pasar el cursor sobre elementos
- **Optimizado para servidores**: Configuración optimizada para entornos sin GUI (Docker, VPS, etc.)

## Requisitos

- Node.js 17 o superior
- npm o yarn

## Instalación

```bash
# Instalar dependencias
npm install

# Compilar el proyecto
npm run build
```

## Uso

### Con Claude Desktop

Agrega la siguiente configuración a tu archivo de configuración de Claude Desktop:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": [
        "/RUTA/ABSOLUTA/A/puppeteer/build/index.js"
      ]
    }
  }
}
```

### Con otros clientes MCP

Ejecuta el servidor directamente:

```bash
node build/index.js
```

## Herramientas Disponibles

### puppeteer_navigate
Navega a una URL en el navegador.

**Parámetros:**
- `url` (string, requerido): La URL a la que navegar

**Ejemplo:**
```json
{
  "url": "https://example.com"
}
```

### puppeteer_click
Hace clic en un elemento usando un selector CSS.

**Parámetros:**
- `selector` (string, requerido): Selector CSS del elemento

**Ejemplo:**
```json
{
  "selector": "button.submit"
}
```

### puppeteer_fill
Rellena un campo de entrada con texto.

**Parámetros:**
- `selector` (string, requerido): Selector CSS del campo
- `value` (string, requerido): Texto a introducir

**Ejemplo:**
```json
{
  "selector": "input[name='email']",
  "value": "user@example.com"
}
```

### puppeteer_screenshot
Toma una captura de pantalla de la página actual o de un elemento específico.

**Parámetros:**
- `name` (string, requerido): Nombre del archivo (sin extensión)
- `selector` (string, opcional): Selector CSS para capturar solo un elemento
- `width` (number, opcional): Ancho del viewport (default: 800)
- `height` (number, opcional): Alto del viewport (default: 600)

**Ejemplo:**
```json
{
  "name": "homepage",
  "width": 1920,
  "height": 1080
}
```

### puppeteer_evaluate
Ejecuta código JavaScript en el contexto del navegador.

**Parámetros:**
- `script` (string, requerido): Código JavaScript a ejecutar

**Ejemplo:**
```json
{
  "script": "document.title"
}
```

### puppeteer_hover
Pasa el cursor sobre un elemento.

**Parámetros:**
- `selector` (string, requerido): Selector CSS del elemento

**Ejemplo:**
```json
{
  "selector": ".menu-item"
}
```

### puppeteer_select
Selecciona una opción de un elemento select/dropdown.

**Parámetros:**
- `selector` (string, requerido): Selector CSS del elemento select
- `value` (string, requerido): Valor a seleccionar

**Ejemplo:**
```json
{
  "selector": "select#country",
  "value": "ES"
}
```

```

## Desarrollo

```bash
# Modo watch (recompila automáticamente)
npm run watch

# Compilar
npm run build
```

## Configuración para Servidores

Este servidor está configurado para ejecutarse en **modo headless** por defecto, lo que significa que:

- ✅ No requiere servidor X11 o entorno gráfico
- ✅ Funciona en contenedores Docker
- ✅ Compatible con servidores Linux sin GUI
- ✅ Optimizado para uso en VPS/Cloud
- ✅ Menor consumo de recursos

### Flags de optimización incluidos:

```typescript
--no-sandbox                    // Necesario en entornos Docker
--disable-setuid-sandbox        // Mejora compatibilidad
--disable-dev-shm-usage         // Evita problemas de memoria en contenedores
--disable-gpu                   // No requiere aceleración gráfica
--disable-software-rasterizer   // Reduce uso de CPU
```

### Uso en Docker

Si ejecutas este servidor en Docker, asegúrate de instalar las dependencias necesarias:

```dockerfile
FROM node:20-slim

# Instalar dependencias de Chromium
RUN apt-get update && apt-get install -y \
    chromium \
    chromium-sandbox \
    fonts-liberation \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libatspi2.0-0 \
    libcups2 \
    libdbus-1-3 \
    libdrm2 \
    libgbm1 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libwayland-client0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxkbcommon0 \
    libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# Configurar Puppeteer para usar Chromium instalado
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
    PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

CMD ["node", "build/index.js"]
```

## Seguridad

- El servidor tiene acceso completo al navegador y puede ejecutar JavaScript arbitrario
- Solo úsalo con fuentes de confianza
- Ten cuidado al ejecutar código JavaScript desde entradas no confiables
- En producción, considera remover el flag `--disable-web-security` del código fuente

## Ventajas del Modo Headless

1. **Sin dependencias gráficas**: No requiere X11, Xvfb o servidor gráfico
2. **Menor consumo de recursos**: ~60% menos uso de memoria comparado con modo gráfico
3. **Más rápido**: Las operaciones son 10-20% más rápidas sin renderizado gráfico
4. **Compatible con CI/CD**: Funciona en pipelines de integración continua
5. **Escalable**: Fácil de replicar en múltiples contenedores
6. **Más estable**: Menos propensoa fallos relacionados con el sistema gráfico

## Casos de Uso

- Web scraping automatizado
- Testing de aplicaciones web
- Generación de PDFs y screenshots
- Automatización de tareas en navegadores
- Integración con sistemas de IA para navegación web
- Monitoreo y validación de sitios web

## Licencia

MIT

## Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request en el repositorio.