headless-cms-mcp-pipeline

Pipeline de Contenido MCP para CMS Headless

Cuándo Usarlo

• Gestionar, redactar o publicar entradas de blog y páginas en WordPress Headless a través del Protocolo de Contexto de Modelo (MCP).
• Orquestar pipelines autónomos de generación de artículos con IA para un frontend headless basado en Next.js.
• Conectar agentes de IA externos a Sayoti Suite MCP RPC (/wp-json/sayoti-mcp/v1/rpc).
• Sincronizar los estándares editoriales, la Matriz de The Borderline, las reglas clínicas de E-E-A-T y las directrices visuales de la marca entre el CMS y el agente de IA.
• Configurar menús de navegación dinámicos headless, auditorías de palabras clave focales en página y roles de página especializados (Lead Magnets, Política de Privacidad, Términos del Servicio).

---

Prerrequisitos y Política de Cero Secretos

⚠️ Protección Estricta de Credenciales (Cero Filtración de Secretos)

• NUNCA codifiques de forma fija claves API, contraseñas o tokens de portador dentro de SKILL.md o archivos rastreados por git.
• Todas las credenciales deben resolverse estrictamente a partir de variables de entorno en $HERMES_HOME/.env o archivos .env específicos del perfil.
• Credenciales requeridas por este pipeline:
  1. MCP_SAYOTI_CMS_KEY: La clave secreta maestra para la autenticación MCP RPC de WordPress (headers: {'X-Sayoti-Key': '${MCP_SAYOTI_CMS_KEY}'}).
  2. HERMES_CUSTOM_9ROUTER_SAYOTI_MY_ID_API_KEY o NINEROUTER_API_KEY: La clave API para la puerta de enlace de modelos múltiples de 9Router (image_generate y embeddings).
• Configuración del Servidor MCP de WordPress (en config.yaml bajo mcp_servers):

  mcp_servers:
    sayoti-cms:
      url: "http://wordpress-sentra/wp-json/sayoti-mcp/v1/rpc"
      headers:
        X-Sayoti-Key: "${MCP_SAYOTI_CMS_KEY}"
      enabled: true
      timeout: 180
  

• Prerrequisito de Base de Datos Vectorial:
  • En la administración de WordPress (sayoti_mcp_settings), embedding_status debe estar configurado como enabled con el modelo local/nomic-embed-text para admitir rag_search y la indexación automática de publicaciones.

---

Principios Arquitectónicos

1. WordPress como Almacén de Datos Puro (Cero Timeout):

   • WordPress nunca debe ejecutar llamadas de IA síncronas de larga duración (generación de LLM, modelos de difusión) durante las solicitudes REST/MCP.
   • El agente de IA (Hermes) actúa como el motor de ejecución: realiza investigación, redacta copia, genera imágenes a través de 9Router e incrusta medios antes de enviar datos al CMS.
   • Las operaciones del CMS (save_post, save_page) deben ejecutarse puramente como transacciones rápidas de base de datos (< 1 segundo) y activar la revalidación ISR bajo demanda de Next.js.

2. Separación Estricta de Entidades mediante Upsert:

   • Siempre usa herramientas upsert dedicadas para entidades de contenido distintas: save_post para artículos de blog y save_page para páginas estáticas/aterrizaje.
   • No combines publicaciones y páginas en una sola herramienta genérica con parámetros condicionales; los esquemas distintos eliminan la fuga de parámetros y las alucinaciones del LLM.
   • Lógica Upsert: si existe un id o slug coincidente, realiza una actualización; si no, crea contenido nuevo.

3. Roles de Página Especializados y Clasificación de Lead Magnets:

   • Las páginas cumplen roles comerciales o legales específicos en el embudo: standard, lead_magnet, privacy_policy, terms_of_service o disclaimer.
   • Nunca dejes ambigüedad en las páginas de lead magnet. Siempre clasifica page_role: 'lead_magnet' y especifica el tipo exacto de activo mediante lead_magnet_type (por ejemplo, "Checklist de Hitos del Desarrollo de 2 a 7 Años (PDF)").
   • El CMS expone esto a través de /wp-json/sayoti/v1/site-settings y registra insignias de estado de publicación ([🎁 LEAD MAGNET: ...], [🔒 POLÍTICA DE PRIVACIDAD], [📜 TÉRMINOS DEL SERVICIO]) en la administración de WordPress para que los editores humanos reconozcan inmediatamente las funciones de la página.

4. Menús de Navegación Dinámicos Headless:

   • Los menús nunca deben estar codificados de forma fija en el frontend. WordPress es la fuente única de verdad a través de /wp-json/sayoti/v1/menus?location=primary y footer.
   • Actualizar los menús en la administración de WP (Apariencia -> Menús) activa un webhook de revalidación ISR con la etiqueta menu y la ruta /, actualizando instantáneamente el encabezado y pie de página de Next.js sin necesidad de redespliegue.
   • Siempre siembra automáticamente los menús de navegación predeterminados en la primera ejecución para que el panel de administración de WP tenga un menú limpio y listo para editar de inmediato.

5. Fuente Única de Verdad para Reglas Editoriales y Visuales:

   • Las reglas editoriales (content.md), los estándares de E-E-A-T (sayoti-editorial.md), las reglas visuales de la marca (sayoti-visual-branding.md) y las reglas de palabras clave SEO en página residen en las opciones de la base de datos de WordPress.
   • El agente obtiene estas reglas dinámicamente a través de get_editorial_guidelines para garantizar que los resultados estén 100% alineados con la generación dentro del panel.

6. Arquitectura de 2 Plugins Desacoplados (Contenido Universal vs. Puente Headless):

   • Nunca acoples la IA, los clústeres de temas y el servidor MCP a la lógica de redirección Headless. Un plugin monolítico se rompe si un cliente ya tiene un tema activo de WordPress (Astra, Elementor, Divi) y solo quiere el motor de IA/SEO.
   • Separa en dos plugins limpios e independientes:
     • sayoti-content-engine: Universal y agnóstico al tema. Incluye MariaDB 11.8 Vector RAG, Clústeres de Temas (Hub and Spoke), Explorador de Enlaces, Autocuración de Enlaces Rotos, Escritor de IA en el Panel, Gestor de Lead Magnets y CRM, y Servidor MCP (/wp-json/sayoti-mcp/v1/rpc). Sin redirecciones, sin dependencias de Next.js. Funciona en CUALQUIER instalación existente de WordPress.
     • sayoti-headless-bridge: Solo se instala cuando se usa un frontend Headless de Next.js. Incluye redirecciones de plantillas 301 (con interruptor configurable), REST /site-settings y /menus, webhooks de revalidación ISR, Controlador de Páginas (página de inicio y roles legales) y etiquetas dinámicas de seguimiento de marketing (GTM, Meta Pixel, TikTok, Ads) con esquema SEO Local (Google Maps y dirección comercial).

---

Flujo de Trabajo Integral de Generación de Artículos en 10 Pasos

[Prompt de Tema del Usuario]
        ↓ 1. Ingesta de Tarea
[WordPress MCP: get_topic_cluster & get_editorial_guidelines]
        ↓ 2. Obtener Taxonomía Pilar y Directrices Editoriales
[Agente (Hermes): Palabra Clave y Ángulo]
        ↓ 3. Formular Palabra Clave Focus y Ángulo Específico
[WordPress MCP: rag_search]
        ↓ 4. Verificar Canibalización Semántica (>80%) y Obtener Candidatos a Enlaces Internos
[Investigación Web: Jerarquía de Citas Universal de 4 Niveles]
        ↓ 5. Verificar Hechos y Fundamentar Afirmaciones
[Agentes de la Agencia: content-creator]
        ↓ 6. Cargar Persona de Escritura Especializada
[Redacción de Contenido: Nativo de Gutenberg]
        ↓ 7. Redactar 900-1500 palabras de HTML Semántico (Hook, H2s, Enlace Hub, FAQ, CTA, Aviso Legal)
[9Router image_generate + MCP upload_media]
        ↓ 8. Cargar lateralmente Activos Visuales con Marca de Agua Adaptativa (Cero Timeout)
[WordPress MCP: save_post]
        ↓ 9. Transacción Instantánea de Base de Datos + Indexación Vectorial Automática + ISR de Next.js
[WordPress MCP: audit_post_seo]
        ↓ 10. Auditar Puntuación SEO (Objetivo 80-100%) y Entregar Informe en Vivo
[En vivo en Vercel Next.js]

Paso 1: Ingesta del Tema y Contexto

Recibe la solicitud de contenido inicial del usuario o del calendario editorial. Identifica los puntos débiles del público objetivo y la intención comercial.

Paso 2: Recuperar Directrices y Taxonomías

Llama a las herramientas de sayoti-cms para establecer límites estructurales:

1. get_topic_cluster: Inspecciona los pilares de categoría disponibles y recupera el Hub Principal oficial (ID de publicación, Título, Slug) para la categoría prevista.
2. get_editorial_guidelines: Obtén los límites de longitud editorial activos (900–1,500 palabras), la anatomía de apertura obligatoria, las reglas del acordeón de preguntas frecuentes, el marco de acción y las paletas de colores hexadecimales oficiales.

Paso 3: Investigación Profunda de Palabras Clave Focus y Formulación de Ángulo

• Intención de Búsqueda e Investigación de Palabras Clave: NO te limites a elegir una frase al azar sin investigación. Investiga activamente el comportamiento de búsqueda real y las consultas utilizadas por el público objetivo definido en el perfil (preguntas informativas, problemas o comparaciones investigativas a través de la búsqueda web/patrones de palabras clave).
• Seleccionar Palabra Clave Focus Primaria: Basándote en los hallazgos de la investigación, establece exactamente 1 Palabra Clave Focus Primaria con una intención de búsqueda de cola larga clara (por ejemplo, "cara melatih anak speech delay 2 tahun mandiri" en lugar de términos genéricos amplios).
• Definir Ángulo Nítido y Único: Ancla la palabra clave elegida a un ángulo distintivo (por ejemplo, transición de edad específica, rutinas diarias realistas en el hogar o pasos tangibles aplicables en ≤24 horas).
• Mapeo de URL Única: Garantiza que esta palabra clave focus esté estrictamente dedicada a una sola URL única para evitar la competencia futura de palabras clave.

Paso 4: Verificación RAG Semántica y Comprobación de Canibalización

Ejecuta rag_search(query: "<focus_keyword> <angle>", limit: 5):

1. Filtro de Canibalización: Si algún artículo publicado muestra >80% de similitud semántica en el mismo ángulo, cambia el ángulo inmediatamente (por ejemplo, pasa de síntomas generales a rutinas domésticas o transiciones de hitos específicos).
2. Descubrimiento de Enlaces Horizontales: Anota los artículos existentes relevantes devueltos por la búsqueda vectorial para que sirvan como enlaces internos contextuales.

Paso 5: Investigación de Citas Multinivel (Jerarquía Universal de 4 Niveles)

Fundamenta todas las afirmaciones fácticas utilizando la Jerarquía de Evidencia Universal:

• Nivel 1 (Autoridades Estatutarias y Científicas Primarias - Estándar de Oro): Asociaciones clínicas oficiales (IDAI, Himpsi, PPHI, OMS, CDC, AAP), directrices gubernamentales de salud y revistas revisadas por pares. Obligatorio para números de hitos de edad, definiciones clínicas y afirmaciones médicas.
• Nivel 2 (Investigación Secundaria y de la Industria Reputable): Agencias de noticias creíbles (Kompas, Antara, BBC) y documentos técnicos institucionales para tendencias macro.
• Nivel 3 (Sentimiento de Campo y Observacional): Luchas reales de la audiencia/usuario, notas de campo de profesionales y discusiones comunitarias. Úsalos para crear hooks de apertura empáticos. Siempre etiqueta como sentimiento u observación de campo práctica, nunca como hecho estatutario o clínico normativo.
• Nivel 4 (Prohibido): Granjas de contenido, blogs SEO sin crédito y reelaboraciones de IA sin enlaces primarios. Nunca cites.

Paso 6: Cargar Persona Especializada

Invoca agency_agents_load(agent="content-creator") (o el especialista de Agencia apropiado) y aplica el tono de comunicación dictado por el SOUL.md del perfil activo.

Paso 7: Redactar HTML Semántico Completo (Nativo de Gutenberg)

Redacta de 900 a 1500 palabras de HTML semántico utilizando comentarios de bloque nativos de WordPress Gutenberg (<!-- wp:paragraph -->, <!-- wp:heading -->, <!-- wp:separator -->, <!-- wp:list -->):

1. H1 Único: Gestionado por la plantilla de página; comienza el cuerpo directamente con párrafos de apertura.
2. Anatomía de Apertura de 3 Párrafos:
   • Párrafo 1 (El Hook): Escenario de la vida real que valida las luchas del público (derivado de ideas del Nivel 3).
   • Párrafo 2 (Respuesta Rápida): Respuesta directa natural y tranquilizadora (sin etiqueta rígida "Respuesta Rápida:").
   • Párrafo 3 (Transición): Invitación cálida a explorar soluciones juntos.
3. Elaboración por H2: De 3 a 5 párrafos completos por encabezado, integrando pasos prácticos de estimulación en el hogar (≤24 horas).
4. Integración de Enlaces Internos:
   • Vertical (Obligatorio): Enlace contextual natural de vuelta al Hub Principal en las primeras 300–500 palabras: <a href="/posts/<hub-slug>" class="text-primary font-semibold underline hover:text-accent">...</a>.
   • Horizontal: Enlace contextual a artículos relacionados descubiertos en el Paso 4.
5. Regla de Contraste de Tarjeta de Llamada: Las notas especiales deben usar <div class="my-8 rounded-2xl border-2 border-primary/25 bg-card p-6 sm:p-8 shadow-sm"> con títulos en text-primary font-bold o text-foreground font-bold. Nunca uses text-secondary en tarjetas claras.
6. Secuencia de Cierre:
   • <h2>Conclusión y Mejores Pasos de Acompañamiento</h2>: Resumen con 3 enlaces de acción (/metodo-de-aprendizaje, /checklist-de-hitos, /contacto o WhatsApp directo).
   • <h2>Preguntas Frecuentes de los Padres (FAQ)</h2>: Mínimo 5 preguntas formateadas como <details class="faq-accordion mb-4 rounded-xl border border-border p-4 bg-card transition-all"><summary class="cursor-pointer font-semibold text-foreground flex items-center justify-between"><span>...</span><span class="text-primary font-bold ml-2">+</span></summary><div class="mt-3 text-sm text-foreground/80 leading-relaxed border-t border-border pt-3">...</div></details>. Colocado ANTES del aviso legal.
   • Aviso Legal Clínico Obligatorio: <div class="my-6 rounded-xl border border-border bg-muted/30 p-4 text-xs italic text-muted-foreground leading-relaxed">Nota: La información en esta guía tiene fines educativos para apoyar la estimulación independiente en el hogar y no reemplaza la evaluación directa ni las recomendaciones médicas de un pediatra o terapeuta profesional.</div>
   • <h2>Referencias</h2>: <ol> lista de fuentes verificadas con URL https:// completas y enlazables que coincidan con las citas en línea.
7. 7 Criterios de SEO en Página: Palabra clave focus presente en el Título, Slug de Permalink, primeras 100 palabras, al menos un H2/H3, Extracto y densidad mantenida entre 0.5% y 2.0%.

Paso 8: Generación Visual y Carga Lateral de Medios (Cero Timeout)

1. Genera imagen a través de image_generate (9Router) aplicando los colores hexadecimales oficiales de la marca y la estricta anti_text_rule (sin texto/números/marcas de agua en el lienzo).
2. Sube la imagen a través de la herramienta MCP upload_media:
   • Pasa image_url o image_base64.
   • Pasa apply_watermark: true para la imagen destacada (estampa automáticamente el logotipo de la marca de forma adaptativa a través de PHP GD) y apply_watermark: false para las ilustraciones del cuerpo de los H2.
   • La herramienta devuelve el id oficial (ID del adjunto) y la url en el dominio del CMS (https://cms...), 100% compatible con remotePatterns de Next.js Vercel.
3. Incrusta las imágenes dentro del artículo directamente en bloques <figure class="wp-block-image size-large"><img src="..." alt="..." /><figcaption>...</figcaption></figure>.

Paso 9: Publicación Instantánea (save_post)

Llama a save_post con:

• title, slug, content, category_id, focus_keyword, excerpt.
• featured_media_id: Establécelo en el id del adjunto devuelto por upload_media en el Paso 8.
• generate_featured_image: false y generate_in_article_images: false (omite la generación de imágenes síncrona del lado del servidor; se ejecuta como una escritura instantánea en la base de datos <1 segundo, eliminando completamente los riesgos de tiempo de espera).
• WordPress automáticamente:
  1. Guarda la publicación y actualiza los campos meta de SEO.
  2. Activa la revalidación ISR bajo demanda de Next.js.
  3. Indexa fragmentos de artículos en la tabla de embeddings vectoriales de MariaDB (wp_sayoti_vectors).

Paso 10: Auditoría SEO e Informe Final

1. Llama a audit_post_seo(post_id: <id>) para

… [truncado por traducción]