Operações e Automação de SEO (seo-ops)

O que Operações e Automação de SEO (seo-ops) faz?

Um runbook automatizado para inicializar o servidor MCP seo, integrar verificações de qualidade pré-push e em CI/CD, e executar auditorias técnicas e de ranqueamento baseadas em evidências.

---

Fase 0: Verificação Pré-Voo e Auto-Instalação Obrigatórias

[!IMPORTANT] Premissa de Configuração Zero: Antes de realizar qualquer análise de código ou auditoria, verifique se o CLI seo e o servidor MCP estão configurados e disponíveis na sessão atual.

flowchart TD
    Start["Invocar /seo-ops"] --> Check{"O SEO MCP / CLI está configurado?"}
    Check -->|Não / Ausente| AutoInstall["1. Executar Auto-Instalação<br/>('npm i -g seo' + escrever mcp_config.json)"]
    AutoInstall --> TestDaemon["2. Verificar: 'npx -y seo mcp serve --test'"]
    TestDaemon --> PromptRestart["3. Solicitar ao usuário reinicialização do Agente/IDE e PARAR"]
    Check -->|Sim / Ativo| RouteIntent["Prosseguir para o Roteamento de Intenção do Usuário"]

Runbook de Auto-Instalação (Acionado quando MCP / CLI está ausente)

1. Instalar Pacote:

   npm install -g seo
   

2. Configurar Servidor MCP: Certifique-se de que .agents/mcp_config.json (e ~/.gemini/config/mcp_config.json) contém:

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

3. Verificar Daemon:

   npx -y seo mcp serve --test
   

4. Solicitar Reinicialização e Parar Turno: Se as ferramentas MCP foram adicionadas recentemente nesta sessão, o Antigravity requer uma recarga de sessão/janela para registrar as ferramentas. Declare claramente:

   "O CLI seo e o servidor MCP foram instalados e registrados. Por favor, recarregue a janela do IDE ou reinicie a sessão do agente para que as novas ferramentas MCP (seo_list_reports, seo_describe_report, seo_run_report) sejam carregadas. Em seguida, invoque /seo-ops novamente." NÃO prossiga para edições manuais de código ou suposições inventadas sem ferramentas ativas.

---

Roteamento de Intenção Ativo (Quando MCP / CLI está Pronto)

Quando os pré-requisitos forem satisfeitos, pergunte ao usuário ou inspecione o contexto para descobrir seu objetivo:

flowchart LR
    Route["Sessão Ativa"] --> A["1. Configuração de CI/CD & Pré-Push (setup-cicd)"]
    Route --> B["2. Auditoria Técnica & On-Page (audit-technical)"]
    Route --> C["3. Search Console & Auditoria de Crescimento (audit-gsc)"]
    Route --> D["4. Verificação de Saúde do Ambiente (check-health)"]

---

Caminho A: CI/CD do Repositório e Verificação de Qualidade Pré-Push (setup-cicd)

Imponha verificações de SEO com zero regressão nos pipelines de desenvolvimento e implantação:

• 1. Verificar Node 22+: Execute node -v para garantir tempo de execução Node 22+.
• 2. Configurar Hook Pré-Push Local:
  • Implante script runner pré-push (scripts/seo-pre-push.ps1 ou scripts/seo-pre-push.sh) com sondagem automática do servidor de desenvolvimento (reutilizando instâncias ativas ou iniciando cmd.exe /c pnpm run dev com limpeza da árvore de processos).
  • Em .husky/pre-push, execute etapas discretas:

    pnpm run test:all
    pnpm run seo:pre-push
    

  • Veja guia-pipeline-cicd.md.
• 3. Instalar Workflow do GitHub Actions:
  • Crie .github/workflows/seo-check.yml usando template-seo-ci.yml.
• 4. Validar Pipeline:
  • Windows: powershell -ExecutionPolicy Bypass -File .agents/skills/seo-ops/scripts/verify-seo-setup.ps1 -Mode cicd
  • Linux/macOS: bash .agents/skills/seo-ops/scripts/verify-seo-setup.sh -m cicd

---

Caminho B: Auditoria Técnica & On-Page (audit-technical)

Execute varreduras baseadas em evidências em builds locais ou URLs ao vivo:

• 1. Iniciar Build Local / Alvo:
  • Execute pnpm build && pnpm start em http://127.0.0.1:3000.
• 2. Executar Auditoria Técnica:
  • Via MCP: Chame seo_run_report com reportId: "audit-page" ou "site-crawl" e params: {"url": "http://127.0.0.1:3000"}.
  • Via CLI:

    npx -y seo report --url http://127.0.0.1:3000 --actions-only --json
    

• 3. Remediar Código Next.js:
  • Atualize generateMetadata() (title, description, OpenGraph, canonicals).
  • Corrija componentes de dados estruturados JSON-LD (BreadcrumbList, Article, WebSite).
  • Corrija tags <Link> quebradas internas e app/sitemap.ts.
  • Veja guia-otimizacao-ranqueamento.md.
• 4. Verificar Correções:
  • Reexecute seo audit-page --url <url-alvo> para confirmar status limpo sem achados.

---

Caminho C: Search Console e Oportunidades de Crescimento (audit-gsc)

Desbloqueie oportunidades de ranqueamento em domínios ao vivo com o Search Console:

• 1. Descobrir Relatórios via MCP:
  • Chame seo_list_reports (categoria: "gsc" ou "pseo").
  • Chame seo_describe_report para reportId: "quick-wins", "second-page" ou "pseo-patterns".
• 2. Executar Auditoria de Oportunidades:
  • Chame seo_run_report com a propriedade alvo (site: "sc-domain:example.com").
• 3. Aplicar Melhorias:
  • Quick Wins (Posições 4–10): Refine <title> e <meta description> para aumentar CTR.
  • Segunda Página (Posições 10–20): Adicione links internos contextuais de páginas pai de alta autoridade e aprofunde o conteúdo.
  • Padrões pSEO: Estruture rotas dinâmicas com generateStaticParams().
• 4. Re-Verificar: Confirme que metadados e schemas atualizados são renderizados na build SSR de produção.

---

Casos Extremos e Armadilhas Conhecidas

• Requerimento de Reinicialização de Processo: Quando .agents/mcp_config.json é modificado, o agente não pode acessar novas ferramentas até que a sessão/janela seja recarregada. Nunca pule o prompt de reinicialização.
• Resolução de Caminhos no Windows: Sempre use "command": "npx" com ["-y", "seo", "mcp", "serve"] para evitar erros de busca de binário %PATH% no Windows.
• Sem Suposições Estáticas: Nunca inspecione código estaticamente para SEO sem executar primeiro as ferramentas MCP ou o relatório CLI.
• Separação de Evidências: Mantenha evidências de varredura observadas separadas de estimativas de palavras-chave de provedores externos.

---

Guias e Recursos de Referência

• Guia de Configuração e Referência de Ferramentas MCP
• Guia de Pipeline CI/CD e Pré-Push
• Guia de Ranqueamento SEO e Remediação de Código
• Template de Workflow CI do GitHub Actions
• Template JSON de Configuração MCP