Hakalab-MCP v2.1

Servidor MCP con Sistema de Sesiones para Automatización Web

🚀 Descripción

Hakalab-MCP es un servidor Model Context Protocol (MCP) que proporciona automatización web completa con soporte para Selenium y Playwright. Incluye 24 herramientas para controlar navegadores, interactuar con elementos, y crear suites de pruebas automatizadas.

NUEVO en v2.1: Sistema de sesiones con IDs únicos para manejar múltiples navegadores simultáneamente.

✨ Características

• ✅ Sistema de Sesiones: Maneja múltiples navegadores simultáneamente con IDs únicos
• ✅ Doble Motor: Selenium WebDriver + Playwright
• ✅ Múltiples Navegadores: Chrome, Firefox, Edge, Safari, Chromium, WebKit
• ✅ 24 Herramientas: Gestión completa de navegadores e interacciones
• ✅ Múltiples Selectores: CSS, XPath, ID, Name, Class, Tag
• ✅ Esperas Inteligentes: Configurable por herramienta
• ✅ Modo Headless: Para ejecución sin interfaz
• ✅ Screenshots: Capturas automáticas con timestamp
• ✅ Framework BDD: Integración con Behave y Allure
• ✅ Súper Liviano: Solo ~15 KB

📦 Instalación

Opción 1: Uso Directo con npx (Recomendado)

No requiere instalación previa. Simplemente agrega la configuración a tu cliente MCP:

{
  "mcpServers": {
    "hakalab-mcp": {
      "command": "npx",
      "args": ["-y", "hakalab-mcp"]
    }
  }
}

Opción 2: Instalación Global

npm install -g hakalab-mcp

Opción 3: Instalación Local

npm install hakalab-mcp

🔧 Configuración

Para Kiro IDE

Agrega esta configuración a ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "hakalab-mcp": {
      "command": "npx",
      "args": ["-y", "hakalab-mcp"],
      "disabled": false,
      "autoApprove": [
        "open_browser",
        "close_browser",
        "navigate_to_url",
        "click_element",
        "fill_input",
        "take_screenshot"
      ]
    }
  }
}

Para Claude Desktop

Agrega esta configuración a ~/.claude_desktop_config.json:

{
  "mcpServers": {
    "hakalab-mcp": {
      "command": "npx",
      "args": ["-y", "hakalab-mcp"]
    }
  }
}

🛠️ Herramientas Disponibles (24 Total)

🔄 Gestión de Sesiones (4) - NUEVO en v2.1

• list_sessions - Lista todas las sesiones activas
• get_session_info - Obtiene información de una sesión
• switch_session - Cambia la sesión activa
• close_all_browsers - Cierra todos los navegadores

🌐 Gestión de Navegadores (2)

• open_browser - Abre un navegador con Selenium o Playwright
• close_browser - Cierra el navegador actual o especificado
• navigate_to_url - Navega a una URL específica
• go_back - Navega hacia atrás en el historial
• go_forward - Navega hacia adelante en el historial
• refresh_page - Recarga la página actual

🎯 Interacciones Básicas (6)

• click_element - Hace clic en un elemento
• double_click_element - Hace doble clic en un elemento
• right_click_element - Hace clic derecho en un elemento
• fill_input - Completa un campo de texto
• select_option - Selecciona una opción en un select/combobox
• hover_element - Pasa el mouse sobre un elemento

🔧 Interacciones Avanzadas (4)

• drag_and_drop - Arrastra un elemento y lo suelta en otro
• scroll_to_element - Hace scroll hasta un elemento
• take_screenshot - Toma una captura de pantalla
• get_current_url - Obtiene la URL actual
• get_page_title - Obtiene el título de la página

🧪 Framework BDD (6)

• create_test_suite - Crea suite completa (feature, steps, page object)
• execute_tests - Ejecuta pruebas del framework
• list_test_files - Lista archivos de prueba
• create_page_object - Crea un Page Object independiente
• sanitize_tests - Valida archivos de prueba
• generate_allure_report - Genera reporte de Allure

📝 Ejemplos de Uso

Sistema de Sesiones (NUEVO v2.1)

El MCP ahora soporta múltiples navegadores simultáneamente. Cada navegador tiene un ID único de sesión:

1. "Abre Chrome con Playwright"
   → Respuesta: ✅ Sesión: session_1704067200000_abc123def

2. "Abre Firefox con Selenium"
   → Respuesta: ✅ Sesión: session_1704067205000_xyz789uvw

3. "Lista todas las sesiones"
   → Muestra ambas sesiones activas

4. "Ve a https://www.google.com"
   → Usa la sesión actual (Firefox)

5. "Cambia a la sesión session_1704067200000_abc123def"
   → Ahora los comandos van a Chrome

6. "Ve a https://www.github.com"
   → Ahora en Chrome

7. "Toma una captura de pantalla"
   → Screenshot de Chrome

8. "Cambia a la sesión session_1704067205000_xyz789uvw"
   → Vuelve a Firefox

9. "Toma una captura de pantalla"
   → Screenshot de Firefox

Ejemplo 1: Búsqueda en Google

1. "Abre Chrome con Playwright"
2. "Ve a https://www.google.com"
3. "Completa el campo de búsqueda con 'hola mundo'"
4. "Haz click en el botón de búsqueda"
5. "Toma una captura de pantalla"
6. "Cierra el navegador"

Ejemplo 2: Automatización de Formulario

1. "Abre Firefox con Selenium"
2. "Ve a https://example.com/form"
3. "Completa el campo 'nombre' con 'Juan'"
4. "Completa el campo 'email' con '[email protected]'"
5. "Selecciona 'Opción 1' en el combobox"
6. "Haz click en el botón 'Enviar'"
7. "Toma una captura del resultado"

Ejemplo 3: Interacciones Complejas

1. "Abre Chrome con Playwright en modo headless"
2. "Ve a https://example.com"
3. "Pasa el mouse sobre el menú principal"
4. "Haz click en 'Productos'"
5. "Haz scroll hasta el producto deseado"
6. "Arrastra el producto al carrito"
7. "Toma una captura"

📋 Requisitos

• Node.js: 18.0.0 o superior
• npm: 8.0.0 o superior
• Navegadores: Chrome, Firefox, Edge, Safari (según el motor)

🎯 Casos de Uso

• ✅ Automatización de pruebas web
• ✅ Web scraping
• ✅ Pruebas de regresión
• ✅ Pruebas de UI
• ✅ Automatización de tareas repetitivas
• ✅ Validación de funcionalidad
• ✅ Pruebas de compatibilidad

🐛 Solución de Problemas

Sistema de Sesiones

P: ¿Cómo sé qué sesión está activa?

• Usa list_sessions para ver todas las sesiones. La sesión activa tiene un ▶️

P: ¿Qué pasa si no especifico un session_id?

• El MCP usa la sesión activa actual. Si no hay sesión activa, devuelve un error.

P: ¿Puedo tener múltiples navegadores abiertos?

• Sí, puedes abrir tantos como necesites. Cada uno tiene su propio ID de sesión.

P: ¿Cómo cambio entre navegadores?

• Usa switch_session con el ID de la sesión que quieres activar.

P: ¿Qué pasa si cierro un navegador?

• Se elimina la sesión. Si era la activa, se activa otra automáticamente.

Errores Comunes

Error: "No hay sesión activa"

• Abre un navegador primero con open_browser

Error: "Sesión no encontrada"

• El ID de sesión es incorrecto o la sesión fue cerrada

Error: "Browser not found"

• Asegúrate de tener el navegador instalado
• Para Playwright: ejecuta npx playwright install

Error: "Timeout waiting for element"

• Aumenta el wait_time en los parámetros
• Verifica que el selector sea correcto

Error: "Connection refused"

• Verifica que el MCP esté correctamente configurado
• Reinicia tu cliente MCP

📚 Documentación Completa

Para documentación detallada, consulta README_MCP.md

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abre un Pull Request

📄 Licencia

MIT License - ver LICENSE para más detalles

👨‍💻 Autor

Haka Lab - Felipe Farías

🔗 Enlaces

• npm: https://www.npmjs.com/package/hakalab-mcp
• GitLab: https://gitlab.com/felipe_farias/hakalab-mcp
• Issues: https://gitlab.com/felipe_farias/hakalab-mcp/-/issues

📞 Soporte

Para reportar bugs o solicitar features, abre un issue en el repositorio de GitLab.

¡Disfruta automatizando con Hakalab-MCP! 🚀