Lighthouse MCP Server

Lighthouse MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona capacidades integrales de auditoría y análisis de rendimiento web mediante Google Lighthouse. Este servidor permite a los LLM y agentes de IA realizar evaluaciones detalladas del rendimiento de sitios web, auditorías de accesibilidad, análisis de SEO, comprobaciones de seguridad y monitoreo de Core Web Vitals.

🌟 Características principales

• 🚀 Análisis de rendimiento: Auditorías completas de Lighthouse con Core Web Vitals, puntuaciones de rendimiento y recomendaciones de optimización
• ♿ Auditorías de accesibilidad: Verificación de cumplimiento de WCAG y análisis de puntuación de accesibilidad
• 🔍 Análisis de SEO: Auditorías de optimización para motores de búsqueda y recomendaciones de mejores prácticas
• 🔒 Evaluación de seguridad: Escaneo de HTTPS, CSP y vulnerabilidades de seguridad
• 📊 Análisis de recursos: Oportunidades de optimización de JavaScript, CSS, imágenes y fuentes
• 📱 Móvil vs Escritorio: Análisis comparativo entre dispositivos con opciones de limitación de velocidad
• ⚡ Core Web Vitals: Monitoreo de LCP, INP y CLS con verificación de umbrales
• 🎯 Presupuestos de rendimiento: Umbrales de rendimiento personalizados y monitoreo de presupuestos
• 🤖 Navegación agéntica: Auditorías de Lighthouse 13 sobre cómo una página sirve a agentes de IA (herramientas WebMCP, árbol de accesibilidad de agentes, llms.txt)
• 🧩 Salida estructurada: Cada herramienta declara un outputSchema y devuelve structuredContent validados, de modo que los clientes reciben datos tipados en lugar de una cadena JSON que analizar
• 📚 Recursos de referencia: Pautas integradas y mejores prácticas para rendimiento web, accesibilidad, SEO y seguridad

🛠️ Requisitos

• Node.js 22.0.0 o superior
• Navegador Chrome/Chromium (gestionado automáticamente por Lighthouse)
• VS Code, Cursor, Windsurf, Claude Desktop o cualquier otro cliente MCP

🚀 Primeros pasos

Instale el servidor Lighthouse MCP con su cliente preferido usando una de las siguientes configuraciones:

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

Perfiles de Chrome persistentes (sesiones de inicio de sesión)

Si necesita sesiones autenticadas, inicie con un perfil de Chrome persistente y ejecute en modo con interfaz:

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": [
        "@danielsogl/lighthouse-mcp@latest",
        "--profile-path",
        "<profile-path>",
        "--no-headless"
      ]
    }
  }
}

Puede pasar banderas adicionales de Chrome con --chrome-flag, por ejemplo --chrome-flag=--disable-gpu. Si el valor de la bandera comienza con -- y coincide con un nombre de opción conocido, prefiera --chrome-flag=... para evitar analizarlo como una opción de nivel superior. El modo de perfil desactiva el restablecimiento de almacenamiento de Lighthouse para que las cookies y el almacenamiento local persistan entre ejecuciones. Si --user-data-dir apunta a un directorio inexistente, se creará y se tratará como un perfil nuevo. Establezca --profile-path en la Ruta de perfil que se muestra en chrome://version (p. ej., .../Default). Nota: la depuración remota de Chrome requiere un directorio de datos de usuario no predeterminado, así que reutilice un directorio de perfil dedicado en lugar del predeterminado del sistema. También puede pasar --user-data-dir + --profile-directory por separado si lo prefiere. Adjuntar solo con --chrome-port no conserva el almacenamiento; incluya una bandera de perfil para mantener las sesiones.

Opciones de CLI

Banderas de tiempo de ejecución compatibles con el servidor MCP:

• --profile-path <path>: usa la Ruta de perfil de chrome://version (deriva automáticamente el directorio de datos de usuario + nombre de perfil)
• --user-data-dir <path>: reutiliza un directorio de perfil de Chrome para sesiones persistentes
• --profile-directory <name>: selecciona un perfil dentro del directorio de datos de usuario
• --chrome-path <path>: ruta explícita al ejecutable de Chrome/Chromium (anula la detección automática; también respeta la variable de entorno CHROME_PATH)
• --chrome-flag <flag> o --chrome-flag=<flag>: pasa banderas adicionales de Chrome (repetible)
• --chrome-port <port> o --remote-debugging-port <port>: se adjunta a una instancia de Chrome existente iniciada con depuración remota habilitada
• --headless: fuerza el modo sin interfaz
• --no-headless: fuerza el modo con interfaz

Registro

Lighthouse registra en stderr. El servidor lo mantiene en error para no inundar los registros de su cliente MCP; establezca LIGHTHOUSE_LOG_LEVEL en silent, info o verbose al depurar (por ejemplo, cuando Chrome no se inicia).

LIGHTHOUSE_LOG_LEVEL=verbose npx @danielsogl/lighthouse-mcp@latest

WSL2 / Ruta personalizada de Chrome

Si se selecciona el binario de Chrome incorrecto (p. ej., Chrome de Windows en lugar del binario de Linux en WSL2), establezca la ruta explícitamente:

# Via CLI flag
npx @danielsogl/lighthouse-mcp@latest --chrome-path /usr/bin/google-chrome

# Via environment variable
CHROME_PATH=/usr/bin/google-chrome npx @danielsogl/lighthouse-mcp@latest

En su configuración de MCP:

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest", "--chrome-path", "/usr/bin/google-chrome"]
    }
  }
}

Prueba de humo E2E (perfil)

Ejecute una auditoría real con un perfil persistente (use un directorio de perfil existente e inicie sesión una vez si es necesario):

npm run smoke:profile -- --url https://example.com \
  --profile-path "<profile-path>" \
  --no-headless

Prueba de humo E2E (adjuntar a Chrome existente)

Inicie Chrome con depuración remota habilitada:

/path/to/GoogleChromeExecutable \
  --remote-debugging-port=9222 \
  --user-data-dir /path/to/chrome-profile

Reemplace /path/to/GoogleChromeExecutable con la ruta del binario de Chrome/Chromium de su plataforma.

Luego adjunte Lighthouse a esa instancia:

npm run smoke:profile -- --url https://example.com --chrome-port 9222

Para conservar el almacenamiento al adjuntar, pase la ruta del perfil para que Lighthouse mantenga las cookies/almacenamiento local:

npm run smoke:profile -- --url https://example.com \
  --chrome-port 9222 \
  --profile-path "<profile-path>"

Instalar en VS Code

# For VS Code
code --add-mcp '{"name":"lighthouse","command":"npx","args":["-y","@danielsogl/lighthouse-mcp@latest"]}'

# For VS Code Insiders
code-insiders --add-mcp '{"name":"lighthouse","command":"npx","args":["-y","@danielsogl/lighthouse-mcp@latest"]}'

Instalar en Cursor

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

Instalar en Windsurf

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

Instalar en Claude Desktop

{
  "mcpServers": {
    "lighthouse": {
      "command": "npx",
      "args": ["@danielsogl/lighthouse-mcp@latest"]
    }
  }
}

🔧 Herramientas disponibles

El servidor Lighthouse MCP proporciona las siguientes herramientas para un análisis web integral:

🏁 Herramientas de auditoría

⚡ Herramientas de rendimiento

🔍 Herramientas de análisis

🔒 Herramientas de seguridad

💬 Prompts disponibles

El servidor Lighthouse MCP incluye prompts reutilizables que ayudan a los LLM a proporcionar análisis y recomendaciones estructurados:

📊 Prompts de análisis

📚 Recursos disponibles

El servidor Lighthouse MCP proporciona recursos de referencia integrados con pautas esenciales y mejores prácticas:

🎯 Prompts de estrategia

🔧 Detalles de los parámetros de los prompts

• auditResults: Resultados de auditoría JSON de las herramientas de Lighthouse
• focusArea: Categoría específica en la que enfocarse ("performance", "accessibility", "seo", "best-practices", "agentic-browsing")
• beforeAudit / afterAudit: Resultados de auditoría de Lighthouse antes y después de los cambios
• changesImplemented: Descripción de los cambios realizados entre auditorías
• currentMetrics: Métricas de rendimiento actuales de las auditorías
• targetGoals: Objetivos de rendimiento específicos o metas comerciales
• timeframe: Cronograma para implementar las mejoras
• framework: Framework de frontend o stack tecnológico
• constraints: Restricciones técnicas o comerciales
• websiteType: Tipo de sitio web (por ejemplo, comercio electrónico, blog, corporativo)
• targetAudience: Información sobre la audiencia objetivo o el mercado
• complianceLevel: Nivel de cumplimiento de WCAG ("AA" o "AAA")
• userGroups: Grupos de usuarios específicos a considerar para la accesibilidad

📋 Detalles de los parámetros

Parámetros comunes

• url (obligatorio): La URL del sitio web a analizar
• device: Dispositivo objetivo ("desktop" o "mobile", predeterminado: "desktop")
• includeDetails: Incluir información detallada de la auditoría (predeterminado: false)
• throttling: Habilitar la limitación de red/CPU (predeterminado: false)

Parámetros específicos

• categories: Categorías de Lighthouse a auditar (["performance", "accessibility", "best-practices", "seo", "agentic-browsing"])
• threshold: Umbrales personalizados para métricas (por ejemplo, {"lcp": 2.5, "inp": 200, "cls": 0.1})
• budget: Límites de presupuesto de rendimiento (por ejemplo, {"performanceScore": 90, "largestContentfulPaint": 2500})
• resourceTypes: Tipos de recursos a analizar (["images", "javascript", "css", "fonts", "other"])
• minBytes: Umbral mínimo de tamaño de archivo para el análisis (predeterminado: 2048)
• checks: Comprobaciones de seguridad a realizar (["https", "csp", "hsts", "origin-isolation", "clickjacking", "trusted-types", "third-party-cookies", "deprecations"])

💡 Ejemplos de uso

Auditoría básica de rendimiento

// Get overall performance score
{
  "tool": "get_performance_score",
  "arguments": {
    "url": "https://example.com",
    "device": "mobile"
  }
}

Análisis de Core Web Vitals

// Check Core Web Vitals with custom thresholds
{
  "tool": "get_core_web_vitals",
  "arguments": {
    "url": "https://example.com",
    "device": "mobile",
    "includeDetails": true,
    "threshold": {
      "lcp": 2.5,
      "inp": 200,
      "cls": 0.1
    }
  }
}

Evaluación de seguridad

// Comprehensive security audit
{
  "tool": "get_security_audit",
  "arguments": {
    "url": "https://example.com",
    "checks": ["https", "csp", "hsts"]
  }
}

Optimización de recursos

// Find optimization opportunities
{
  "tool": "analyze_resources",
  "arguments": {
    "url": "https://example.com",
    "resourceTypes": ["images", "javascript"],
    "minSize": 1024
  }
}

Uso de recursos de referencia

Accede a las pautas integradas y las mejores prácticas:

// Get Core Web Vitals thresholds
{
  "resource": {
    "uri": "lighthouse://performance/core-web-vitals-thresholds"
  }
}

// Access WCAG accessibility guidelines
{
  "resource": {
    "uri": "lighthouse://accessibility/wcag-guidelines"
  }
}

// Get framework-specific optimization guides
{
  "resource": {
    "uri": "lighthouse://frameworks/optimization-guides"
  }
}

Uso de prompts para análisis

// Analyze audit results with focused recommendations
{
  "prompt": "analyze-audit-results",
  "arguments": {
    "auditResults": "{...lighthouse audit json...}",
    "focusArea": "performance"
  }
}

// Create a performance improvement plan
{
  "prompt": "create-performance-plan",
  "arguments": {
    "currentMetrics": "{...current performance metrics...}",
    "targetGoals": "Achieve 90+ performance score and sub-2s LCP",
    "timeframe": "3 months"
  }
}

// Compare before/after audit results
{
  "prompt": "compare-audits",
  "arguments": {
    "beforeAudit": "{...before audit results...}",
    "afterAudit": "{...after audit results...}",
    "changesImplemented": "Implemented lazy loading and image optimization"
  }
}

🎯 Casos de uso

• Monitoreo de rendimiento: Seguimiento automatizado del rendimiento y monitoreo de Core Web Vitals
• Cumplimiento de accesibilidad: Verificación de cumplimiento de WCAG 2.1 y orientación para la remediación
• Optimización de SEO: Auditorías técnicas de SEO y recomendaciones de optimización para motores de búsqueda
• Evaluación de seguridad: Escaneo de vulnerabilidades y validación de mejores prácticas de seguridad
• Optimización de recursos: Análisis de paquetes e identificación de oportunidades de optimización
• Presupuestos de rendimiento: Monitoreo automatizado de presupuestos de rendimiento y alertas
• Integración CI/CD: Puertas de calidad automatizadas y detección de regresiones de rendimiento

🏗️ Arquitectura

El servidor está construido usando:

• Model Context Protocol SDK: Para la implementación del servidor MCP
• Google Lighthouse: Para la auditoría de rendimiento web
• Chrome Launcher: Para la automatización del navegador
• TypeScript: Para la seguridad de tipos y una mejor experiencia de desarrollo
• Zod: Para la validación de esquemas en tiempo de ejecución

🧪 Pruebas

npm run test:run      # unit tests
npm run test:coverage # unit tests with coverage
npm run test:e2e      # end-to-end tests

La suite de pruebas de extremo a extremo compila el servidor, lo inicia a través de stdio con un cliente MCP real y ejecuta auditorías reales de Lighthouse contra una página de prueba servida en loopback. Requiere que Chrome esté instalado; establece CHROME_PATH si se encuentra en una ubicación no estándar.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Lee nuestra Guía de contribución para obtener detalles sobre:

• Estilo de código y estándares
• Requisitos de prueba
• Proceso de solicitudes de extracción
• Configuración del entorno de desarrollo

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT; consulta el archivo LICENSE para más detalles.

🔒 Seguridad

Para problemas de seguridad, consulta nuestra Política de seguridad.

📞 Soporte

• 🐛 Informes de errores: GitHub Issues
• 💬 Discusiones: GitHub Discussions
• 📧 Correo electrónico: security@codingrules.ai

🙏 Agradecimientos

• Al equipo de Google Lighthouse por el excelente motor de auditoría
• A Anthropic por la especificación del Model Context Protocol
• A la comunidad de código abierto por la inspiración y las contribuciones continuas

Hecho con ❤️ por Daniel Sogl