mcp-seo-audit

mcp-seo-audit

Um servidor local Model Context Protocol para auditorias técnicas de SEO, renderização de JavaScript, análises do Search Console, verificações de desempenho e monitoramento recorrente. Suas 43 ferramentas retornam evidências, URLs afetadas, correções sugeridas e limites explícitos de cobertura.

Versão atual do código-fonte: 2.1.0. Instale este checkout para usar os recursos abaixo. Uma atualização no GitHub não publica um pacote PyPI nem um lançamento no MCP Registry; uvx mcp-seo-audit ainda pode resolver uma versão publicada mais antiga.

A implantação suportada é stdio para um usuário local confiável, não um serviço hospedado multi-tenant. Rastreamentos de sites públicos não exigem credenciais do Google. Baseado em AminForou/mcp-gsc, com sua atribuição MIT preservada.

Instalar e conectar

Requer Python 3.11 ou posterior.

git clone https://github.com/GiorgiKemo/mcp-seo-audit.git
cd mcp-seo-audit
python -m venv .venv

Ative com .venv/Scripts/Activate.ps1 no Windows PowerShell ou source .venv/bin/activate no macOS/Linux, depois instale as dependências de runtime fixadas e este pacote:

python -m pip install --require-hashes -r requirements.lock
python -m pip install --no-deps .

O lock inclui o pacote Python opcional de navegador. A renderização de JavaScript também precisa do Chromium:

python -m playwright install chromium

Para uma instalação menor do código-fonte sem suporte a navegador, python -m pip install . resolve intervalos de dependências principais em vez do lock completo. Para adicionar suporte a navegador depois, use python -m pip install ".[browser]" e instale o Chromium. Para desenvolvimento editável, use python -m pip install -e ".[dev,browser]".

O Linux pode exigir dependências de navegador do sistema operacional; python -m playwright install --with-deps chromium as instala onde você administra esses pacotes. O sandbox do Chromium permanece ativado. Execute como um usuário não-root suportado com os recursos de SO necessários, em vez de desativar o sandbox.

No Ubuntu 23.10+, uma restrição de namespace de usuário do AppArmor pode causar o erro No usable sandbox do Chromium. Peça ao administrador da máquina para seguir as instruções de AppArmor por executável do Chromium, permitindo userns para os caminhos exatos dos executáveis do Chromium e headless-shell instalados. Mantenha esses arquivos de navegador confiáveis e atualize o perfil após atualizações do navegador. O workflow de CI demonstra essa configuração limitada; ele mantém o sandbox do Chromium e a restrição em todo o sistema.

Docker

Construa e conecte o contêiner stdio não-root com um volume nomeado para histórico de auditoria e configuração:

docker build -t mcp-seo-audit:2.1.0 .
docker run --rm -i -v seo-audit-data:/data mcp-seo-audit:2.1.0

Configure o cliente MCP para iniciar o comando docker run. Nenhuma porta HTTP é exposta. A imagem suporta rastreamento bruto por padrão; ela inclui o pacote Python de navegador, mas nenhum binário do Chromium ou dependências de SO do navegador. Auditorias renderizadas exigem uma configuração de imagem separada que instala ambos e suporta o sandbox de navegador ativado.

Execute um lote de agendamentos explicitamente ativados contra o mesmo volume de dados:

docker run --rm --entrypoint mcp-seo-monitor -v seo-audit-data:/data mcp-seo-audit:2.1.0 --once

Credenciais do Google são opcionais para auditorias de sites públicos. Para usar ferramentas do Google, monte explicitamente seu próprio arquivo de credenciais somente leitura e defina a variável de ambiente de caminho de credencial correspondente; nunca copie credenciais para a imagem. Consulte as configurações de autenticação abaixo.

Configuração do cliente MCP

Adicione um servidor stdio na configuração do seu cliente MCP. Por exemplo, no Windows:

{
  "mcpServers": {
    "seo-audit": {
      "command": "C:/path/to/mcp-seo-audit/.venv/Scripts/mcp-seo-audit.exe",
      "env": {
        "GSC_SKIP_OAUTH": "true",
        "SEO_AUDIT_ENABLE_WRITE_TOOLS": "false",
        "SEO_AUDIT_ALLOW_PRIVATE_URLS": "false"
      }
    }
  }
}

No macOS/Linux, use o caminho absoluto para .venv/bin/mcp-seo-audit. Os locais dos arquivos de configuração variam por cliente. O processo aguarda mensagens MCP na stdin; iniciá-lo sem um cliente pode parecer uma espera silenciosa. get_server_status relata configuração/prontidão local sem revelar credenciais ou comprovar acesso à conta do Google.

Acesso opcional ao Google

• OAuth: ative a API Search Console no Google Cloud, crie um aplicativo OAuth Desktop e defina GSC_OAUTH_CLIENT_SECRETS_FILE para o JSON do cliente baixado. Defina GSC_SKIP_OAUTH=false. A primeira operação do Google pode abrir o consentimento no navegador. Ative a API Web Search Indexing se usar suas ferramentas.
• Conta de serviço: defina GSC_CREDENTIALS_PATH para o arquivo de chave, conceda à conta acesso à propriedade relevante do Search Console e use GSC_SKIP_OAUTH=true.
• APIs de desempenho: defina CRUX_API_KEY para CrUX e opcionalmente PAGESPEED_API_KEY para PageSpeed Insights. GOOGLE_API_KEY é o fallback do PageSpeed.

Mantenha as credenciais fora do checkout. Os tokens OAuth usam por padrão o diretório de dados do usuário ou GSC_TOKEN_FILE. Tokens legados ao lado do servidor permanecem como fallback de leitura durante a migração; a reautenticação com falha preserva o token funcional.

Mutações de propriedade/sitemap do Google e chamadas de publicação da API Indexing exigem SEO_AUDIT_ENABLE_WRITE_TOOLS=true. Ferramentas locais de projeto/histórico não exigem esse sinalizador de gravação no Google. O sinalizador não reduz os escopos OAuth concedidos.

Auditar um site

Pergunte ao seu cliente MCP:

Crie um relatório de SEO estruturado para https://example.com/ com até 25 páginas. Inclua descoberta de sitemap, compare HTML bruto e renderizado e mostre lacunas de cobertura antes de priorizar correções.

A ferramenta subjacente aceita:

get_seo_audit_report(
  start_url="https://example.com/",
  max_pages=25,
  respect_robots=True,
  render_mode="compare",
  include_sitemaps=True,
  max_seconds=180
)

render_mode usa como padrão raw; rendered analisa o DOM resultante, e compare também captura diferenças do HTML retornado pelo servidor. Relatórios diretos usam como padrão include_sitemaps=False. O orçamento de tempo de rastreamento usa como padrão 180 segundos, configurável de 5 a 600. Os relatórios divulgam cobertura parcial e motivos de interrupção.

Os relatórios incluem um esquema JSON versionado, carimbo de data/hora, IDs de regras estáveis, gravidade, evidências, URLs afetadas, recomendações, observações de página e cobertura. As verificações cobrem erros HTTP e fontes de links, metadados, cabeçalhos, indexabilidade, canônicos, títulos/descrições duplicados, imagens, links, hreflang e perfis JSON-LD selecionados.

A descoberta de sitemap segue índices de mesma origem limitados e combina URLs de sitemap com descoberta de links. Uma URL de sitemap sem um link de entrada observado é um candidato a órfão dentro da amostra, não uma prova de que todo o site não tem link para ela.

As verificações de hreflang cobrem sintaxe de idioma/região e autorreferências observadas, links de retorno, consistência de cluster e conflitos alternate/canônico. Alternates não visitados ou de origem cruzada permanecem não verificados. As verificações de dados estruturados cobrem campos básicos de Product, BreadcrumbList e família Article, divulgando tipos/contextos não suportados e referências não resolvidas. Elas não certificam elegibilidade para rich results nem implementam todo o vocabulário do Schema.org.

Comparar correções

Chame compare_seo_audits(baseline_json, current_json) com dois relatórios serializados usando a mesma URL inicial e configurações. Se o seu cliente envolver um relatório sob structuredContent.result, serialize o relatório interno.

Resultado	Significado
new	Uma descoberta apareceu com evidências aplicáveis em ambos os snapshots.
resolved	Uma reavaliação aplicável bem-sucedida verificou que a descoberta desapareceu.
persistent	A descoberta permanece.
newly_observed	A linha de base não cobriu a página ou suas dependências.
unverified	Uma página ou URL relacionada necessária não foi reavaliada com sucesso.

Páginas ausentes nunca provam correções. Uma fronteira de links descobertos concluída nunca estabelece cobertura completa do site. Descobertas de contagem de palavras, comprimento de título e metadados sociais são orientação de revisão, não requisitos de classificação.

Salvar projetos e monitorar mudanças

Crie um projeto via MCP:

create_audit_project(
  project_id="example",
  start_url="https://example.com/",
  max_pages=25,
  render_mode="raw",
  include_sitemaps=True,
  retention=30
)
run_project_audit(project_id="example")

Projetos sempre respeitam robots.txt e começam com agendamento desativado. IDs usam 1-64 letras minúsculas, dígitos, hífens ou sublinhados, começando com letra ou dígito. O ID de auditoria retornado identifica um snapshot imutável. Use list_project_audits, get_project_audit e compare_project_audits para histórico. Execuções bem-sucedidas podam snapshots antigos para a retenção configurada.

Opte por um agendamento diário:

set_audit_schedule(project_id="example", enabled=True, interval_seconds=86400)

Execute o worker separado no mesmo ambiente instalado, com as mesmas configurações de SEO_AUDIT_DATA_DIR e rede:

mcp-seo-monitor

Ou processe um lote limitado e saia, adequado para um agendador de SO externo:

mcp-seo-monitor --once

O servidor MCP nunca inicia um worker automaticamente. A primeira execução agendada vence um intervalo após a ativação. --once processa no máximo 25 projetos vencidos; repita-o ou mantenha o worker em execução para filas maiores. A sondagem usa como padrão 30 segundos, configurável com --poll-seconds de 1 a 60. Ctrl+C cancela a auditoria ativa e interrompe o worker. Desativar um agendamento impede reivindicações futuras; uma execução ativa pode terminar.

Leases de banco de dados coordenam workers concorrentes. Execuções têm um tempo limite externo de dez minutos e um lease de onze minutos para recuperação de falhas; o orçamento de rastreamento do relatório pode parar antes. Falhas usam backoff exponencial limitado a 24 horas, ou o intervalo configurado quando maior. Após uma falha de processo, outro worker pode reivindicar o projeto quando o lease expirar.

Leia list_audit_events(project_id="example", after_id=0) para mudanças locais de descobertas verificadas, transições de falha e recuperação. Salve next_after_id e passe-o na próxima vez. Descobertas inalteradas e mudanças apenas de amostragem permanecem silenciosas. Nenhum e-mail, webhook, notificação push ou outra mensagem de saída é enviada.

Armazenamento e retenção

O banco de dados é audits.sqlite3 sob:

Plataforma	Diretório padrão
Windows	%LOCALAPPDATA%/mcp-seo-audit
macOS	~/Library/Application Support/mcp-seo-audit
Linux	$XDG_DATA_HOME/mcp-seo-audit, ou ~/.local/share/mcp-seo-audit

Substitua com SEO_AUDIT_DATA_DIR. Use um sistema de arquivos local com bloqueio SQLite confiável; não compartilhe um banco de dados entre hosts nem o coloque em um sistema de arquivos de rede não confiável.

Limites: 100 projetos, 1-100 snapshots por projeto (padrão 30), 10 MiB por snapshot e os 500 eventos mais recentes por projeto. Intervalos de agendamento são de 60 segundos a 31 dias. Carimbos de data/hora de armazenamento são segundos Unix UTC. A retenção limita contagens, não o uso global de disco; provisione espaço em disco para seus tamanhos de relatório.

Relatórios podem conter metadados de página, parâmetros de URL e dados de negócios. O armazenamento não é criptografado por aplicativo. Para fazer backup, pare o servidor e o monitor, depois copie com segurança o diretório de dados, incluindo arquivos sidecar SQLite. Restaure com processos parados e mantenha o backup original até a verificação. O diretório também pode conter tokens OAuth: trate backups como sensíveis e nunca os anexe a problemas públicos.

Análises e desempenho

get_search_analytics_snapshot pagina com orçamentos explícitos de linhas/requisições/tempo: padrão 25.000 linhas, máximo 100.000 linhas, no máximo 10 páginas de API em 180 segundos. Linhas parciais sobrevivem a falhas do provedor. A cobertura inclui motivo de interrupção, linhas duplicadas e atualidade; contagens de páginas de API excluem tentativas de repetição adicionais. O Google ainda limita resultados a linhas superiores selecionadas, então esgotar uma janela de API não estabelece cobertura completa de tráfego. Referência de consulta do Google.

prioritize_audit_issues ordena descobertas de relatório por gravidade, depois cliques/impressões de página observados. A correspondência de URL é exata; páginas sem correspondência são desconhecidas, não tráfego zero. Não prevê ganhos de receita ou classificação.

Chamadas do Google são executadas fora do loop de eventos por meio de um worker serializado porque o transporte de cliente em cache não é seguro para threads. Leituras repetem erros selecionados de limite de taxa/servidor no máximo duas vezes com atrasos limitados; mutações são tentadas uma vez. O cancelamento impede repetições posteriores, mas uma requisição já enviada ao Google pode ainda ser concluída.

Relatórios CrUX mostram dados de campo onde disponíveis; resultados PageSpeed/Lighthouse são medições de laboratório. Dados de campo ausentes não são uma avaliação reprovada de Core Web Vitals. Lighthouse local exige um executável Lighthouse instalado, Chrome/Chromium e SEO_AUDIT_ENABLE_LOCAL_LIGHTHOUSE=true explícito. Downloads via npx são desativados por padrão. O processo Chrome separado do Lighthouse não herda a rede protegida do rastreador renderizado; use-o apenas com alvos confiáveis. Consulte SECURITY.md.

A API Indexing suporta páginas JobPosting elegíveis e BroadcastEvent incorporadas em VideoObject. A aceitação de notificação não é prova de indexação/remoção; esta não é uma API de indexação de propósito geral para cada página. Orientação da API Indexing do Google.

Referência de ferramentas

Área	Ferramentas
Propriedades	list_properties, add_site, delete_site
Analytics de pesquisa	get_search_analytics, get_advanced_search_analytics, get_performance_overview, get_search_by_page_query, compare_search_periods, get_search_analytics_snapshot
Oportunidades de SEO	find_striking_distance_keywords, detect_cannibalization, split_branded_queries, prioritize_audit_issues
Inspeção de URL	inspect_url, batch_inspect_urls
Notificações de indexação	request_indexing, request_removal, check_indexing_notification, batch_request_indexing
Sitemaps do Google	get_sitemaps, submit_sitemap, delete_sitemap
Desempenho	get_core_web_vitals, get_pagespeed_insights, run_lighthouse_audit
Inspeção ao vivo	inspect_robots_txt, analyze_sitemap, analyze_page_seo, crawl_site_seo, audit_live_site
Relatórios estruturados	get_seo_audit_report, compare_seo_audits, site_audit
Projetos e monitoramento	create_audit_project, list_audit_projects, set_audit_schedule, run_project_audit, list_project_audits, get_project_audit, compare_project_audits, list_audit_events
Autenticação e status	reauthenticate, get_server_status

site_audit combina dados da conta Google. audit_live_site é um relatório de texto do site ao vivo. get_seo_audit_report é o fluxo de trabalho estruturado de rastreamento/comparação. As descrições das ferramentas expõem entradas e anotações de leitura/gravação aos clientes.

Configuração

Reinicie o servidor após alterar a configuração.

Variável	Padrão	Finalidade
GSC_OAUTH_CLIENT_SECRETS_FILE	client_secrets.json ao lado do servidor	Arquivo de cliente desktop OAuth; prefira um caminho externo explícito.
GSC_CREDENTIALS_PATH	Locais convencionais de conta de serviço	Caminho JSON da conta de serviço.
GSC_TOKEN_FILE	token.json no diretório de dados do usuário	Destino do token; o token legado do pacote é um fallback de leitura.
GSC_SKIP_OAUTH	false	Ignorar OAuth interativo para ferramentas do Google.
GSC_DATA_STATE	all	all inclui dados provisórios; final solicita dados finalizados.
CRUX_API_KEY	Vazio	Chave da API CrUX.
PAGESPEED_API_KEY	GOOGLE_API_KEY ou vazio	Chave do PageSpeed Insights.
GOOGLE_API_KEY	Vazio	Chave PageSpeed de fallback.
SEO_AUDIT_DATA_DIR	Diretório de dados do usuário da plataforma	Armazenamento de projetos/histórico e local padrão do token.
SEO_AUDIT_BROWSER_PATH	Playwright Chromium	Executável Chromium instalado opcional para rastreamento renderizado.
SEO_AUDIT_ENABLE_WRITE_TOOLS	false	Habilitar ferramentas Google mutáveis.
SEO_AUDIT_ALLOW_PRIVATE_URLS	false	Permitir destinos privados apenas para testes deliberadamente confiáveis.
SEO_AUDIT_MAX_FETCH_BYTES	5242880	Limite de bytes decodificados por resposta; também limita entradas diretas de relatórios JSON.
SEO_AUDIT_MAX_REDIRECTS	5	Limite de redirecionamentos de busca HTTP.
SEO_AUDIT_MAX_SITEMAP_URLS	50000	Limite de URLs para análise individual de sitemap.
SEO_AUDIT_MAX_CRAWL_PAGES	100	Teto para tentativas de páginas rastreadas.
SEO_AUDIT_ENABLE_LOCAL_LIGHTHOUSE	false	Permitir execução separada do Lighthouse para alvos confiáveis.
LIGHTHOUSE_BINARY	Detecção automática	Caminho do executável Lighthouse instalado.
LIGHTHOUSE_CHROME_PATH	CHROME_PATH ou detecção automática	Caminho do Chrome para Lighthouse local.
SEO_AUDIT_ALLOW_NPX_LIGHTHOUSE	false	Permitir baixar/executar Lighthouse por meio de npx.
LIGHTHOUSE_NO_SANDBOX	false	Substituição legada de sandbox somente Lighthouse; mantenha desabilitado normalmente.

Limites de rastreamento e renderização

• Os rastreamentos permanecem na origem inicial, usam o agente de usuário mcp-seo-audit e preservam parâmetros de consulta/caminho. O Googlebot pode receber regras diferentes.
• Rastreamentos recursivos respeitam robots.txt por padrão, incluindo redirecionamentos e recursos renderizados. Inspeções de página única fazem solicitações diretas. Desabilite robots apenas para um site que você controla.
• O parsing de robots é limitado a 500 KiB. Páginas rastreadas são espaçadas em pelo menos 0,2 segundos; atrasos de rastreamento de até 10 segundos são respeitados. Atrasos maiores e erros temporários de robots adiam o rastreamento.
• Os orçamentos de páginas incluem URLs tentadas, erros e respostas não HTML. A descoberta de sitemaps em relatórios separadamente limita 10 documentos, 20 vezes o orçamento de páginas em candidatos, 5 MiB por documento decodificado e até 45 segundos dentro do orçamento de rastreamento restante.
• HTTP protegido valida todas as respostas DNS e conecta a um IP validado, preservando a verificação de hostname TLS. Destinos privados, loopback, reservados e traduzidos inseguros são bloqueados por padrão, incluindo redirecionamentos.
• Páginas renderizadas usam um contexto Chromium sandboxed novo, busca de recursos GET/HEAD protegida, service workers/WebSockets/downloads bloqueados e nenhuma sessão de navegador autenticada. Padrões: 30 segundos, 80 solicitações, 20 MiB por página e intervalo de estabilização de 750 ms. Recursos bloqueados, erros de JavaScript ou trabalho inacabado produzem cobertura parcial. Sites que exigem login, gravações, WebSockets ou esperas mais longas podem renderizar de forma incompleta.
• Conteúdo rastreado é dado não confiável. Os clientes não devem tratar texto de página, metadados ou descobertas como permissão para executar comandos ou enviar mensagens.

Esses controles suportam auditoria local. Eles não são autenticação, isolamento de locatário ou substituto para egresso controlado para cargas de trabalho não confiáveis. Veja SECURITY.md e a auditoria de implementação.

Desenvolvimento e verificação

python -m pip install -e ".[dev]"
python -m pytest -q
python -m build
python -m pip_audit

Os testes isolam credenciais e usam fixtures HTTP controlados e APIs Google simuladas. CI é configurado para Windows/Linux e Python 3.11/3.13/3.14, com integração de navegador habilitada no Python 3.13 e uma verificação separada de contêiner não root. Para integração local de navegador, instale Chromium e defina SEO_AUDIT_TEST_BROWSER=1 antes de executar pytest. Passar em testes offline não estabelece permissões Google ao vivo, cotas, conclusão de CI remota ou publicação de pacotes; evidências de lançamento pertencem ao registro de auditoria.

Veja CONTRIBUTING.md para verificações de alteração/lançamento e CHANGELOG.md para alterações.

Licença

MIT. Trabalho original com direitos autorais 2025 Amin Foroutan; contribuições do projeto com direitos autorais 2025-2026 GiorgiKemo.