Operaciones y Automatización SEO (seo-ops)

¿Qué hace Operaciones y Automatización SEO (seo-ops)?

Un runbook automatizado para arrancar el servidor MCP seo, integrar compuertas de calidad pre-push y en CI/CD, y ejecutar auditorías técnicas y de posicionamiento basadas en evidencia.

---

Fase 0: Verificación Pre-Vuelo Obligatoria y Auto-Instalación

[!IMPORTANT] Suposición de Configuración Cero Manual: Antes de realizar cualquier análisis de código o auditoría, verifica que la CLI seo y el servidor MCP estén configurados y disponibles en la sesión actual.

flowchart TD
    Start["Invocar /seo-ops"] --> Check{"¿Está configurado el SEO MCP / CLI?"}
    Check -->|No / Falta| AutoInstall["1. Ejecutar Auto-Instalación<br/>('npm i -g seo' + escribir mcp_config.json)"]
    AutoInstall --> TestDaemon["2. Verificar: 'npx -y seo mcp serve --test'"]
    TestDaemon --> PromptRestart["3. Solicitar al usuario reinicio del Agente/IDE y DETENERSE"]
    Check -->|Sí / Activo| RouteIntent["Proceder al Enrutamiento de Intención del Usuario"]

Runbook de Auto-Instalación (Se activa cuando falta MCP / CLI)

1. Instalar Paquete:

   npm install -g seo
   

2. Configurar Servidor MCP: Asegurar que .agents/mcp_config.json (y ~/.gemini/config/mcp_config.json) contenga:

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

3. Verificar Daemon:

   npx -y seo mcp serve --test
   

4. Solicitar Reinicio y Detener Turno: Si las herramientas MCP se agregaron recién en esta sesión, Antigravity requiere recargar la sesión/ventana para registrar las herramientas. Indica claramente:

   "La CLI seo y el servidor MCP se han instalado y registrado. Por favor, recarga la ventana del IDE o reinicia la sesión del agente para que las nuevas herramientas MCP (seo_list_reports, seo_describe_report, seo_run_report) se carguen, y luego vuelve a invocar /seo-ops." NO procedas a ediciones manuales de código o conjeturas inventadas sin herramientas activas.

---

Enrutamiento de Intención Activo (Cuando MCP / CLI está Listo)

Cuando los prerrequisitos estén satisfechos, pregunta al usuario o inspecciona el contexto para determinar su objetivo:

flowchart LR
    Route["Sesión Activa"] --> A["1. Configuración CI/CD y Pre-Push (setup-cicd)"]
    Route --> B["2. Auditoría Técnica y On-Page (audit-technical)"]
    Route --> C["3. Auditoría de Search Console y Crecimiento (audit-gsc)"]
    Route --> D["4. Verificación de Salud del Entorno (check-health)"]

---

Vía A: Compuerta de Calidad CI/CD y Pre-Push del Repositorio (setup-cicd)

Impón compuertas de calidad SEO sin regresión en los pipelines de desarrollo y despliegue:

• 1. Verificar Node 22+: Ejecuta node -v para asegurar el runtime Node 22+.
• 2. Configurar Hook Local Pre-Push:
  • Desplegar script ejecutor pre-push (scripts/seo-pre-push.ps1 o scripts/seo-pre-push.sh) con auto-detección del servidor de desarrollo (reutilizando instancias activas o lanzando cmd.exe /c pnpm run dev con limpieza del árbol de procesos).
  • En .husky/pre-push, ejecutar pasos discretos:

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

  • Ver guia-pipeline-cicd.md.
• 3. Instalar Workflow de GitHub Actions:
  • Crear .github/workflows/seo-check.yml usando seo-ci.yml.template.
• 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

---

Vía B: Auditoría Técnica y On-Page (audit-technical)

Ejecuta rastreos basados en evidencia sobre builds locales o URLs en vivo:

• 1. Iniciar Build Local / Destino:
  • Ejecutar pnpm build && pnpm start en http://127.0.0.1:3000.
• 2. Ejecutar Auditoría Técnica:
  • Mediante MCP: Llamar a seo_run_report con reportId: "audit-page" o "site-crawl" y params: {"url": "http://127.0.0.1:3000"}.
  • Mediante CLI:

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

• 3. Remediar Código Next.js:
  • Actualizar generateMetadata() (title, description, OpenGraph, canónicos).
  • Corregir componentes de datos estructurados JSON-LD (BreadcrumbList, Article, WebSite).
  • Corregir etiquetas <Link> rotas internas y app/sitemap.ts.
  • Ver guia-optimizacion-posicionamiento.md.
• 4. Verificar Correcciones:
  • Re-ejecutar seo audit-page --url <url-destino> para confirmar estado limpio sin hallazgos.

---

Vía C: Search Console y Oportunidades de Crecimiento (audit-gsc)

Descubre oportunidades de posicionamiento en dominios en vivo con Search Console:

• 1. Descubrir Informes mediante MCP:
  • Llamar a seo_list_reports (categoría: "gsc" o "pseo").
  • Llamar a seo_describe_report para reportId: "quick-wins", "second-page" o "pseo-patterns".
• 2. Ejecutar Auditoría de Oportunidades:
  • Llamar a seo_run_report con la propiedad objetivo (site: "sc-domain:example.com").
• 3. Aplicar Mejoras:
  • Quick Wins (Posiciones 4–10): Refinar <title> y <meta description> para aumentar el CTR.
  • Segunda Página (Posiciones 10–20): Agregar enlaces internos contextuales desde páginas padre con alta autoridad y profundizar el contenido.
  • Patrones pSEO: Crear rutas dinámicas con generateStaticParams().
• 4. Re-Verificar: Confirmar que los metadatos y esquemas actualizados se rendericen en la compilación SSR de producción.

---

Casos Extremos y Problemas Conocidos

• Requisito de Reinicio de Proceso: Cuando se modifica .agents/mcp_config.json, el agente no puede acceder a las nuevas herramientas hasta que se recargue la sesión/ventana. Nunca omitas la solicitud de reinicio.
• Resolución de Rutas en Windows: Usa siempre "command": "npx" con ["-y", "seo", "mcp", "serve"] para evitar errores de búsqueda binaria en %PATH% en Windows.
• Sin Suposiciones Estáticas: Nunca inspecciones código estáticamente para SEO sin ejecutar primero las herramientas MCP o el informe CLI.
• Separación de Evidencia: Mantén la evidencia observada del rastreo separada de las estimaciones de palabras clave de proveedores externos.

---

Guías de Referencia y Recursos

• Guía de Configuración MCP y Referencia de Herramientas
• Guía de Pipeline CI/CD y Pre-Push
• Guía de Posicionamiento SEO y Corrección de Código
• Plantilla de Workflow CI para GitHub Actions
• Plantilla de Configuración MCP JSON