PlayMCP Browser Automation Server

Un servidor para la automatización de navegadores usando Playwright, que proporciona herramientas potentes para web scraping, pruebas y automatización.

GitHub
15
Prueba este MCPPatrocinado

Documentación

Servidor de Automatización de Navegador PlayMCP

Un servidor MCP (Protocolo de Contexto de Modelo) integral para automatización de navegador usando Playwright. Este servidor proporciona 38 herramientas potentes para extracción web, pruebas y automatización.

PlayBrowser Automation Server MCP server

Características

🚀 Automatización Principal del Navegador (21 herramientas)

  • Navegación: navigate, goForward, goBack (mediante desplazamiento)
  • Interacción: click, type, hover, dragAndDrop, selectOption
  • Control del Ratón: moveMouse, mouseMove, mouseClick, mouseDrag
  • Teclado: pressKey
  • Espera: waitForText, waitForSelector
  • Capturas de Pantalla: screenshot, takeScreenshot (mejoradas)
  • Información de la Página: getPageSource, getPageText, getPageTitle, getPageUrl
  • Análisis de Elementos: getElementContent, getElementHierarchy
  • Scripts y Estilos: getScripts, getStylesheets, getMetaTags

🔍 Extracción Avanzada de Datos (7 herramientas)

  • Enlaces e Imágenes: getLinks, getImages
  • Formularios: getForms
  • Monitoreo de Consola: getConsoleMessages
  • Monitoreo de Red: getNetworkRequests
  • Ejecución de JavaScript: executeJavaScript, evaluateWithReturn

📁 Operaciones de Archivos (2 herramientas)

  • Carga de Archivos: uploadFiles
  • Manejo de Diálogos: handleDialog

⚙️ Gestión del Navegador (8 herramientas)

  • Control del Navegador: openBrowser, closeBrowser
  • Gestión de Viewport: resize
  • Manipulación de Páginas: scroll (mejorada con retroalimentación)
  • Jerarquía de Elementos: Análisis profundo del DOM con profundidad configurable
  • Capturas de Pantalla Mejoradas: Página completa, elementos específicos, rutas personalizadas
  • Coordenadas del Ratón: Control del ratón con precisión de píxel
  • Condiciones de Espera: Espera inteligente para elementos y texto

Inicio Rápido

Instalación

# 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":{}}

Categorías de Herramientas

🎯 Navegación e Interacción

  • navigate: Ir a cualquier URL
  • goForward: Navegar hacia adelante en el historial del navegador
  • click: Hacer clic en elementos con resolución inteligente de selectores
  • type: Escribir texto con simulación realista de teclado
  • hover: Pasar el cursor sobre elementos para tooltips e interacciones
  • dragAndDrop: Arrastrar elementos entre ubicaciones
  • selectOption: Elegir opciones de listas desplegables y selecciones múltiples
  • pressKey: Enviar teclas específicas del teclado (Enter, Escape, etc.)

⏱️ Espera Inteligente

  • waitForText: Esperar a que aparezca texto específico
  • waitForSelector: Esperar a que los elementos se carguen
  • Tiempos de espera integrados y manejo de errores

🖱️ Control Preciso del Ratón

  • mouseMove: Moverse a coordenadas exactas
  • mouseClick: Hacer clic en píxeles específicos
  • mouseDrag: Arrastrar entre puntos de coordenadas
  • moveMouse: Posicionamiento mejorado del ratón

📊 Extracción de Datos

  • getElementHierarchy: Análisis profundo de la estructura del DOM
  • getConsoleMessages: Monitorear la salida de la consola del navegador
  • getNetworkRequests: Rastrear solicitudes y respuestas HTTP
  • getLinks: Extraer todos los enlaces de la página con metadatos
  • getImages: Obtener todas las imágenes con atributos
  • getForms: Analizar estructuras y campos de formularios

🎬 Visual y Multimedia

  • screenshot: Captura de pantalla básica
  • takeScreenshot: Capturas de pantalla avanzadas (página completa, elementos, rutas personalizadas)
  • resize: Controlar las dimensiones del viewport

📁 Operaciones de Archivos y Diálogos

  • uploadFiles: Manejar cargas de archivos de entrada
  • handleDialog: Gestionar alertas, confirmaciones y avisos

⚙️ Ejecución de JavaScript

  • executeJavaScript: Ejecutar código JavaScript
  • evaluateWithReturn: Ejecutar JS con valores de retorno

Controles Principales del Navegador

  • openBrowser - Lanzar una nueva instancia del navegador con modo headless opcional
  • navigate - Navegar a cualquier URL
  • click - Hacer clic en elementos usando selectores CSS
  • type - Escribir texto en campos de entrada
  • moveMouse - Mover el ratón a coordenadas específicas
  • scroll - Desplazar la página por cantidades especificadas con retroalimentación mejorada y soporte de desplazamiento suave
  • screenshot - Tomar capturas de pantalla de la página, viewport o elementos específicos
  • closeBrowser - Cerrar la instancia del navegador

Extracción de Contenido de Página

  • getPageSource - Obtener el código fuente HTML completo
  • getPageText - Obtener el contenido de texto (sin HTML)
  • getPageTitle - Obtener el título de la página
  • getPageUrl - Obtener la URL actual
  • getScripts - Extraer todo el código JavaScript de la página
  • getStylesheets - Extraer todas las hojas de estilo CSS
  • getMetaTags - Obtener todas las metaetiquetas con sus atributos
  • getLinks - Obtener todos los enlaces con href, texto y título
  • getImages - Obtener todas las imágenes con src, alt y dimensiones
  • getForms - Obtener todos los formularios con sus campos y atributos
  • getElementContent - Obtener contenido HTML y de texto de elementos específicos
  • getElementHierarchy - Obtener la estructura jerárquica del DOM con relaciones padre-hijo

Capacidades Avanzadas

  • executeJavaScript - Ejecutar código JavaScript arbitrario en la página y devolver resultados

Referencia de Herramientas Disponibles

HerramientaDescripciónParámetros Requeridos
openBrowserLanzar instancia del navegadorheadless?: boolean, debug?: boolean
navigateNavegar a URLurl: string
clickHacer clic en elementoselector: string
typeEscribir texto en elementoselector: string, text: string
moveMouseMover ratón a coordenadasx: number, y: number
scrollDesplazar página con retroalimentaciónx: number, y: number, smooth?: boolean
screenshotTomar captura de pantallapath: string, type?: string, selector?: string
getPageSourceObtener fuente HTMLNinguno
getPageTextObtener contenido de textoNinguno
getPageTitleObtener título de páginaNinguno
getPageUrlObtener URL actualNinguno
getScriptsObtener código JavaScriptNinguno
getStylesheetsObtener hojas de estilo CSSNinguno
getMetaTagsObtener metaetiquetasNinguno
getLinksObtener todos los enlacesNinguno
getImagesObtener todas las imágenesNinguno
getFormsObtener todos los formulariosNinguno
getElementContentObtener contenido de elementoselector: string
getElementHierarchyObtener jerarquía del DOMselector?: string, maxDepth?: number, includeText?: boolean, includeAttributes?: boolean
executeJavaScriptEjecutar JavaScriptscript: string
closeBrowserCerrar navegadorNinguno

Instalación

Pasos Completos de Instalación

  1. Requisitos previos

    • Node.js 16+ (descargar de nodejs.org)
    • Git (para clonar el repositorio)

  2. Clonar y Configurar

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

  3. Instalar Navegadores de Playwright

    npx playwright install

    Esto descarga los binarios necesarios del navegador (Chromium, Firefox, Safari).

  4. Verificar la Instalación

    npm run start

    Deberías ver "Browser Automation MCP Server starting..." si todo funciona correctamente.

Instalación Rápida

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

Uso

Como Servidor MCP

Agrega a tu archivo de configuración MCP:

Configuración MCP Estándar:

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

Configuración Alternativa (funciona con VS Code GitHub Copilot):

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

Para usuarios de Windows:

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

Integración con VS Code GitHub Copilot

Este servidor MCP es totalmente compatible con VS Code GitHub Copilot. Después de agregar la configuración anterior a tu configuración MCP, puedes usar todas las herramientas de automatización del navegador directamente dentro de VS Code.

Ejemplos de Configuración

Claude Desktop (ubicación de config.json):

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

Extensión MCP de VS Code: Agrega a tu settings.json de VS Code o archivo de configuración MCP.

Ejemplo de Configuración Completa:

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

Ejemplos de Herramientas

Extracción Web Básica:

// 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()

Automatización de Formularios:

// 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" })

Interacción con la Página:

// 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álisis de Estructura del 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 })

Ejecución Avanzada 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 Pantalla y Documentación:

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

Inicio Rápido

  1. Instalar y configurar:

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

  2. Agregar a la configuración de tu cliente MCP

  3. Comenzar 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)

Desarrollo

  • src/server.ts - Implementación principal del servidor MCP
  • src/controllers/playwright.ts - Controlador del navegador Playwright
  • src/mcp/ - Implementación del protocolo MCP
  • src/types/ - Definiciones de tipos TypeScript

Requisitos

Requisitos del Sistema

  • Node.js 16+ (versión LTS recomendada)
  • Sistema Operativo: Windows, macOS o Linux
  • Memoria: Al menos 2GB de RAM (4GB+ recomendado para uso intensivo)
  • Espacio en Disco: ~500MB para binarios del navegador y dependencias

Dependencias

  • Playwright: Maneja la automatización del navegador (instalado automáticamente)
  • TypeScript: Para compilación (dependencia de desarrollo)
  • Binarios del Navegador: Descargados mediante npx playwright install

Solución de Problemas

Problemas Comunes

  1. Error de "Browser not initialized"

    • Asegúrate de llamar a openBrowser antes de otras operaciones del navegador
    • Verifica que la versión de Node.js sea 16 o superior

  2. La instalación de Playwright falla

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

  3. Errores de permisos en Linux/macOS

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

  4. Problemas de rutas en la configuración MCP

    • Usa rutas absolutas en la configuración
    • En Windows, usa dobles barras invertidas: C:\\path\\to\\PlayMCP\\dist\\server.js
    • Verifica que la ruta exista: node /path/to/PlayMCP/dist/server.js

  5. El navegador se bloquea o expira

    • Intenta ejecutar con headless: false para depuración
    • Aumenta la memoria del sistema si ejecutas múltiples instancias del navegador
    • Verifica si el software antivirus está bloqueando los procesos del navegador

Probando tu Instalación

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

Deberías ver una respuesta JSON que enumera todas las herramientas disponibles.

Licencia

Licencia MIT