Lighthouse MCP Server

Lighthouse MCP Server

Um servidor Model Context Protocol (MCP) que fornece recursos abrangentes de auditoria e análise de desempenho web usando o Google Lighthouse. Este servidor permite que LLMs e agentes de IA realizem avaliações detalhadas de desempenho de sites, auditorias de acessibilidade, análise de SEO, verificações de segurança e monitoramento de Core Web Vitals.

🌟 Principais Recursos

• 🚀 Análise de Desempenho: Auditorias completas do Lighthouse com Core Web Vitals, pontuações de desempenho e recomendações de otimização
• ♿ Auditorias de Acessibilidade: Verificação de conformidade com WCAG e análise de pontuação de acessibilidade
• 🔍 Análise de SEO: Auditorias de otimização para mecanismos de busca e recomendações de melhores práticas
• 🔒 Avaliação de Segurança: Verificação de HTTPS, CSP e varredura de vulnerabilidades de segurança
• 📊 Análise de Recursos: Oportunidades de otimização de JavaScript, CSS, imagens e fontes
• 📱 Mobile vs Desktop: Análise comparativa entre dispositivos com opções de throttling
• ⚡ Core Web Vitals: Monitoramento de LCP, INP, CLS com verificação de limites
• 🎯 Orçamentos de Desempenho: Limites de desempenho personalizados e monitoramento de orçamento
• 🤖 Navegação Agêntica: Auditorias do Lighthouse 13 para avaliar o quão bem uma página atende agentes de IA (ferramentas WebMCP, árvore de acessibilidade para agentes, llms.txt)
• 🧩 Saída Estruturada: Cada ferramenta declara um outputSchema e retorna structuredContent validados, para que os clientes recebam dados tipados em vez de uma string JSON para analisar
• 📚 Recursos de Referência: Diretrizes integradas e melhores práticas para desempenho web, acessibilidade, SEO e segurança

🛠️ Requisitos

• Node.js 22.0.0 ou mais recente
• Navegador Chrome/Chromium (gerenciado automaticamente pelo Lighthouse)
• VS Code, Cursor, Windsurf, Claude Desktop ou qualquer outro cliente MCP

🚀 Começando

Instale o Lighthouse MCP server com seu cliente preferido usando uma das configurações abaixo:

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

Perfis Persistentes do Chrome (Sessões de Login)

Se você precisar de sessões autenticadas, inicie com um perfil persistente do Chrome e execute com interface gráfica:

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

Você pode passar sinalizadores extras do Chrome com --chrome-flag, por exemplo --chrome-flag=--disable-gpu. Se o valor do sinalizador começar com -- e corresponder a um nome de opção conhecido, prefira --chrome-flag=... para evitar que seja analisado como uma opção de nível superior. O modo de perfil desativa a redefinição de armazenamento do Lighthouse, para que cookies e armazenamento local persistam entre execuções. Se --user-data-dir apontar para um diretório inexistente, ele será criado e tratado como um perfil novo. Defina --profile-path para o Caminho do Perfil mostrado em chrome://version (por exemplo, .../Default). Observação: a depuração remota do Chrome exige um diretório de dados de usuário não padrão, então reutilize um diretório de perfil dedicado em vez do padrão do sistema. Você também pode passar --user-data-dir + --profile-directory separadamente, se preferir. Anexar apenas com --chrome-port não preserva o armazenamento; inclua um sinalizador de perfil para manter as sessões.

Opções de CLI

Sinalizadores de tempo de execução suportados para o servidor MCP:

• --profile-path <path>: use o Caminho do Perfil de chrome://version (deriva automaticamente o diretório de dados do usuário + nome do perfil)
• --user-data-dir <path>: reutilize um diretório de perfil do Chrome para sessões persistentes
• --profile-directory <name>: selecione um perfil dentro do diretório de dados do usuário
• --chrome-path <path>: caminho explícito para o executável do Chrome/Chromium (substitui a detecção automática; também respeita a variável de ambiente CHROME_PATH)
• --chrome-flag <flag> ou --chrome-flag=<flag>: repassar sinalizadores extras do Chrome (repetível)
• --chrome-port <port> ou --remote-debugging-port <port>: anexar a uma instância existente do Chrome iniciada com depuração remota habilitada
• --headless: forçar modo headless
• --no-headless: forçar modo com interface gráfica

Registro de Logs

O Lighthouse registra logs em stderr. O servidor mantém isso em error para não inundar os logs do seu cliente MCP; defina LIGHTHOUSE_LOG_LEVEL para silent, info ou verbose ao depurar (por exemplo, quando o Chrome falhar ao iniciar).

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

WSL2 / Caminho Personalizado do Chrome

Se o binário errado do Chrome for selecionado (por exemplo, Chrome do Windows em vez do binário Linux no WSL2), defina o caminho explicitamente:

# 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

Na sua configuração MCP:

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

Teste de Fumaça E2E (Perfil)

Execute uma auditoria real com um perfil persistente (use um diretório de perfil existente e faça login uma vez, se necessário):

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

Teste de Fumaça E2E (Anexar ao Chrome Existente)

Inicie o Chrome com depuração remota habilitada:

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

Substitua /path/to/GoogleChromeExecutable pelo caminho do binário do Chrome/Chromium da sua plataforma.

Em seguida, anexe o Lighthouse a essa instância:

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

Para preservar o armazenamento ao anexar, passe o caminho do perfil para que o Lighthouse mantenha cookies/armazenamento local:

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

Instalar no 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 no Cursor

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

Instalar no Windsurf

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

Instalar no Claude Desktop

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

🔧 Ferramentas Disponíveis

O Lighthouse MCP server fornece as seguintes ferramentas para análise web abrangente:

🏁 Ferramentas de Auditoria

⚡ Ferramentas de Desempenho

🔍 Ferramentas de Análise

🔒 Ferramentas de Segurança

💬 Prompts Disponíveis

O Lighthouse MCP server inclui prompts reutilizáveis que ajudam LLMs a fornecer análises e recomendações estruturadas:

📊 Prompts de Análise

📚 Recursos Disponíveis

O Lighthouse MCP server fornece recursos de referência integrados com diretrizes essenciais e melhores práticas:

🎯 Prompts de Estratégia

🔧 Detalhes dos Parâmetros dos Prompts

• auditResults: Resultados de auditoria JSON das ferramentas Lighthouse
• focusArea: Categoria específica para focar ("performance", "accessibility", "seo", "best-practices", "agentic-browsing")
• beforeAudit / afterAudit: Resultados de auditoria Lighthouse antes e depois das alterações
• changesImplemented: Descrição das alterações feitas entre auditorias
• currentMetrics: Métricas de desempenho atuais das auditorias
• targetGoals: Metas de desempenho específicas ou objetivos de negócio
• timeframe: Cronograma para implementar melhorias
• framework: Framework frontend ou stack de tecnologia
• constraints: Restrições técnicas ou de negócio
• websiteType: Tipo de site (ex.: e-commerce, blog, corporativo)
• targetAudience: Público-alvo ou informações de mercado
• complianceLevel: Nível de conformidade WCAG ("AA" ou "AAA")
• userGroups: Grupos de usuários específicos a considerar para acessibilidade

📋 Detalhes dos Parâmetros

Parâmetros Comuns

• url (obrigatório): A URL do site a ser analisado
• device: Dispositivo alvo ("desktop" ou "mobile", padrão: "desktop")
• includeDetails: Incluir informações detalhadas da auditoria (padrão: false)
• throttling: Habilitar throttling de rede/CPU (padrão: false)

Parâmetros Específicos

• categories: Categorias Lighthouse para auditar (["performance", "accessibility", "best-practices", "seo", "agentic-browsing"])
• threshold: Limites personalizados para métricas (ex.: {"lcp": 2.5, "inp": 200, "cls": 0.1})
• budget: Limites de orçamento de desempenho (ex.: {"performanceScore": 90, "largestContentfulPaint": 2500})
• resourceTypes: Tipos de recursos a analisar (["images", "javascript", "css", "fonts", "other"])
• minBytes: Limite mínimo de tamanho de arquivo para análise (padrão: 2048)
• checks: Verificações de segurança a realizar (["https", "csp", "hsts", "origin-isolation", "clickjacking", "trusted-types", "third-party-cookies", "deprecations"])

💡 Exemplos de Uso

Auditoria Básica de Desempenho

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

Análise 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
    }
  }
}

Avaliação de Segurança

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

Otimização de Recursos

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

Usando Recursos de Referência

Acesse diretrizes integradas e melhores práticas:

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

Usando Prompts para Análise

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

• Monitoramento de Desempenho: Rastreamento automatizado de desempenho e monitoramento de Core Web Vitals
• Conformidade de Acessibilidade: Verificação de conformidade WCAG 2.1 e orientação de correção
• Otimização de SEO: Auditorias técnicas de SEO e recomendações de otimização para mecanismos de busca
• Avaliação de Segurança: Varredura de vulnerabilidades e validação de melhores práticas de segurança
• Otimização de Recursos: Análise de bundles e identificação de oportunidades de otimização
• Orçamentos de Desempenho: Monitoramento automatizado de orçamento de desempenho e alertas
• Integração CI/CD: Portões de qualidade automatizados e detecção de regressão de desempenho

🏗️ Arquitetura

O servidor é construído usando:

• Model Context Protocol SDK: Para implementação do servidor MCP
• Google Lighthouse: Para auditoria de desempenho web
• Chrome Launcher: Para automação de navegador
• TypeScript: Para segurança de tipos e melhor experiência de desenvolvimento
• Zod: Para validação de esquema em tempo de execução

🧪 Testes

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

A suíte de ponta a ponta compila o servidor, o inicia via stdio com um cliente MCP real e executa auditorias Lighthouse reais contra uma página de teste servida em loopback. Requer Chrome instalado; defina CHROME_PATH se ele estiver em um local não padrão.

🤝 Contribuindo

Contribuições são bem-vindas! Leia nosso Guia de Contribuição para detalhes sobre:

• Estilo e padrões de código
• Requisitos de teste
• Processo de pull request
• Configuração de desenvolvimento

📜 Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🔒 Segurança

Para problemas de segurança, consulte nossa Política de Segurança.

📞 Suporte

• 🐛 Relatórios de Bugs: GitHub Issues
• 💬 Discussões: GitHub Discussions
• 📧 E-mail: security@codingrules.ai

🙏 Agradecimentos

• Equipe do Google Lighthouse pelo excelente motor de auditoria
• Anthropic pela especificação do Model Context Protocol
• A comunidade de código aberto pela inspiração e contribuições contínuas

Construído com ❤️ por Daniel Sogl