headless-cms-mcp-pipeline

Pipeline de Conteúdo Headless CMS MCP

Quando Usar

• Gerenciar, criar ou publicar posts de blog e páginas no WordPress Headless via Model Context Protocol (MCP).
• Orquestrar pipelines autônomos de geração de artigos por IA contra um frontend headless Next.js.
• Conectar agentes de IA externos ao MCP RPC do Sayoti Suite (/wp-json/sayoti-mcp/v1/rpc).
• Sincronizar padrões editoriais, The Borderline Matrix, regras clínicas E-E-A-T e diretrizes visuais da marca entre CMS e agente de IA.
• Configurar menus de navegação headless dinâmicos, auditorias de palavra-chave focada na página e funções de página especializadas (Ímãs de Lead, Política de Privacidade, Termos de Serviço).

---

Pré-requisitos e Política de Zero Segredo

⚠️ Proteção Estrita de Credenciais (Vazamento de Segredo Zero)

• NUNCA codifique chaves de API, senhas ou tokens de portador dentro de SKILL.md ou arquivos rastreados pelo git.
• Todas as credenciais devem ser estritamente resolvidas a partir de variáveis de ambiente em $HERMES_HOME/.env ou arquivos .env específicos de perfil.
• Credenciais necessárias para este pipeline:
  1. MCP_SAYOTI_CMS_KEY: A chave secreta mestre para autenticação MCP RPC do WordPress (headers: {'X-Sayoti-Key': '${MCP_SAYOTI_CMS_KEY}'}).
  2. HERMES_CUSTOM_9ROUTER_SAYOTI_MY_ID_API_KEY ou NINEROUTER_API_KEY: A chave de API para o gateway multi-modelo 9Router (image_generate e embeddings).
• Configuração do Servidor MCP WordPress (em config.yaml sob 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
  

• Pré-requisito do Banco de Dados Vetorial:
  • No admin do WordPress (sayoti_mcp_settings), embedding_status deve estar definido como enabled com o modelo local/nomic-embed-text para suportar rag_search e indexação automática de posts.

---

Princípios Arquitetônicos

1. WordPress como um Repositório de Dados Puro (Zero Timeout):

   • O WordPress nunca deve executar chamadas de IA síncronas de longa duração (geração LLM, modelos de difusão) durante solicitações REST/MCP.
   • O agente de IA (Hermes) atua como o motor de execução: ele realiza pesquisa, rascunha texto, gera visuais via 9Router e incorpora mídia antes de enviar dados ao CMS.
   • As operações do CMS (save_post, save_page) devem ser executadas puramente como transações rápidas de banco de dados (< 1 segundo) e acionar a revalidação ISR On-Demand do Next.js.

2. Separação Estrita de Entidades via Upsert:

   • Sempre use ferramentas upsert dedicadas para entidades de conteúdo distintas: save_post para artigos de blog e save_page para páginas estáticas/de destino.
   • Não combine posts e páginas em uma única ferramenta genérica com parâmetros condicionais; esquemas distintos eliminam vazamentos de parâmetros e alucinações de LLM.
   • Lógica Upsert: se um id ou slug correspondente existir, execute uma atualização; se não, crie novo conteúdo.

3. Funções de Página Especializadas e Classificação de Ímã de Lead:

   • As páginas atendem a funções comerciais ou legais específicas no funil: standard, lead_magnet, privacy_policy, terms_of_service ou disclaimer.
   • Nunca deixe páginas de ímã de lead ambíguas. Sempre classifique page_role: 'lead_magnet' e declare o tipo exato de ativo via lead_magnet_type (por exemplo, "Checklist Marco do Desenvolvimento 2–7 Anos (PDF)").
   • O CMS expõe estes via /wp-json/sayoti/v1/site-settings e registra emblemas de estado do post ([🎁 ÍMÃ DE LEAD: ...], [🔒 POLÍTICA DE PRIVACIDADE], [📜 TERMOS DE SERVIÇO]) no Admin do WordPress para que editores humanos reconheçam imediatamente as funções da página.

4. Menus de Navegação Headless Dinâmicos:

   • Os menus nunca devem ser codificados no frontend. O WordPress é a única fonte da verdade via /wp-json/sayoti/v1/menus?location=primary e footer.
   • Atualizar menus no Admin do WP (Aparência -> Menus) dispara um webhook de revalidação ISR com a tag menu e o caminho /, atualizando instantaneamente o cabeçalho e rodapé do Next.js sem reimplantação.
   • Sempre pré-popular menus de navegação padrão na primeira execução para que o painel de administração do WP tenha um menu limpo e pronto para edição imediatamente.

5. Fonte Única da Verdade para Regras Editoriais e Visuais:

   • As regras editoriais (content.md), padrões E-E-A-T (sayoti-editorial.md), regras visuais da marca (sayoti-visual-branding.md) e regras de SEO On-Page residem em opções do banco de dados do WordPress.
   • O agente busca essas regras dinamicamente via get_editorial_guidelines para que as saídas permaneçam 100% alinhadas com a geração no painel.

6. Arquitetura de 2 Plugins Desacoplados (Conteúdo Universal vs Ponte Headless):

   • Nunca acople IA, Clusters de Tópicos e servidor MCP à lógica de redirecionamento Headless. Um plugin monolítico quebra se um cliente já tiver um tema WordPress ativo (Astra, Elementor, Divi) e quiser apenas o motor de IA/SEO.
   • Separe em dois plugins limpos e independentes:
     • sayoti-content-engine: Universal e agnóstico de tema. Carrega MariaDB 11.8 Vector RAG, Clusters de Tópicos (Hub & Spoke), Explorador de Links, Cura automática de links quebrados, Escritor de IA no Painel, CPT de Ímã de Lead e CRM, e Servidor MCP (/wp-json/sayoti-mcp/v1/rpc). Sem redirecionamentos, sem dependências do Next.js. Funciona em QUALQUER instalação WordPress existente.
     • sayoti-headless-bridge: Instalado apenas ao usar um frontend Headless Next.js. Carrega redirecionamentos de template 301 (com alternância configurável), REST /site-settings e /menus, webhooks de revalidação ISR, Controlador de Página (página inicial e funções legais) e tags de rastreamento de marketing dinâmicas (GTM, Meta Pixel, TikTok, Ads) com esquema de SEO Local (Google Maps e endereço comercial).

---

Fluxo de Trabalho Abrangente de Geração de Artigos em 10 Etapas

[Prompt de Tópico do Usuário]
        ↓ 1. Ingerir Tarefa
[MCP WordPress: get_topic_cluster & get_editorial_guidelines]
        ↓ 2. Buscar Taxonomia de Pilar e Diretrizes Editoriais
[Agente (Hermes): Palavra-chave Foco e Ângulo]
        ↓ 3. Formular Palavra-chave Foco e Ângulo Específico
[MCP WordPress: rag_search]
        ↓ 4. Verificar Canibalização Semântica (>80%) e Buscar Candidatos a Links Internos
[Pesquisa na Web: Hierarquia de Citações Universal de 4 Níveis]
        ↓ 5. Verificar Fatos e Fundamentar Afirmações
[Agentes da Agência: content-creator]
        ↓ 6. Carregar Persona de Escrita Especialista
[Criação de Conteúdo: Nativo do Gutenberg]
        ↓ 7. Rascunhar 900-1500 palavras HTML Semântico (Gancho, H2s, Link do Hub, FAQ, CTA, Aviso Legal)
[9Router image_generate + MCP upload_media]
        ↓ 8. Carregar Ativos Visuais com Marca d'Água Adaptativa (Zero-Timeout)
[MCP WordPress: save_post]
        ↓ 9. Transação Instantânea de Banco de Dados + Índice Vetorial Automático + ISR do Next.js
[MCP WordPress: audit_post_seo]
        ↓ 10. Auditar Pontuação de SEO (Alvo 80-100%) e Entregar Relatório ao Vivo
[Ao vivo no Vercel Next.js]

Etapa 1: Ingerir Tópico e Contexto

Receber a solicitação de conteúdo inicial do usuário ou do calendário editorial. Identificar pontos problemáticos do público-alvo e intenção comercial.

Etapa 2: Recuperar Diretrizes e Taxonomias

Chamar ferramentas sayoti-cms para estabelecer limites estruturais:

1. get_topic_cluster: Inspecionar pilares de categoria disponíveis e recuperar o Hub Principal oficial (ID do Post, Título, Slug) para a categoria pretendida.
2. get_editorial_guidelines: Buscar limites ativos de tamanho editorial (900–1.500 palavras), anatomia de abertura obrigatória, regras de acordeão de FAQ, estrutura de ação e paletas de cores hexadecimais oficiais.

Etapa 3: Pesquisa Profunda de Palavra-chave Foco e Formulação de Ângulo

• Intenção de Pesquisa e Pesquisa de Palavra-chave: NÃO escolha simplesmente uma frase aleatória sem pesquisa. Pesquise ativamente o comportamento de pesquisa realista e as consultas usadas pelo público-alvo definido no perfil (perguntas informacionais, problemas ou comparações investigativas via pesquisa na web/padrões de palavras-chave).
• Selecionar Palavra-chave Foco Primária: Com base nas descobertas da pesquisa, estabeleça exatamente 1 Palavra-chave Foco Primária com intenção de pesquisa de cauda longa clara (por exemplo, "cara melatih anak speech delay 2 tahun mandiri" em vez de termos amplos e genéricos).
• Definir Ângulo Afiado e Único: Ancore a palavra-chave escolhida a um ângulo distinto (por exemplo, transição de idade específica, rotinas domésticas diárias realistas ou etapas tangíveis aplicáveis em ≤24 horas).
• Mapeamento de URL Único: Garantir que esta palavra-chave foco seja estritamente dedicada a uma única URL exclusiva para evitar competição futura de palavras-chave.

Etapa 4: Verificação Semântica RAG e Verificação de Canibalização

Executar rag_search(query: "<palavra-chave_foco> <ângulo>", limit: 5):

1. Filtro de Canibalização: Se qualquer artigo publicado exibir >80% de similaridade semântica no mesmo ângulo, mude o ângulo imediatamente (por exemplo, mudar de sintomas gerais para rotinas domésticas ou transições de marcos específicos).
2. Descoberta de Links Horizontais: Observar artigos existentes relevantes retornados pela pesquisa vetorial para servir como links internos contextuais.

Etapa 5: Pesquisa de Citações em Vários Níveis (Hierarquia Universal de 4 Níveis)

Fundamentar todas as afirmações factuais usando a Hierarquia de Evidências Universal:

• Nível 1 (Autoridades Estatutárias e Científicas Primárias - Padrão Ouro): Associações clínicas oficiais (IDAI, Himpsi, PPHI, OMS, CDC, AAP), diretrizes governamentais de saúde e periódicos revisados por pares. Obrigatório para números de marcos de idade, definições clínicas e alegações médicas.
• Nível 2 (Pesquisas Secundárias e da Indústria de Reputação): Agências de notícias confiáveis (Kompas, Antara, BBC) e white papers institucionais para tendências macro.
• Nível 3 (Sentimento de Campo e Observacional): Dificuldades reais do público/usuário, notas de campo de profissionais e discussões da comunidade. Usar para criar ganchos de abertura empáticos. Sempre rotular como sentimento ou observação prática de campo, nunca como fato normativo, estatutário ou clínico.
• Nível 4 (Proibido): Fazendas de conteúdo, blogs de SEO não creditados e reformulações de IA sem links primários. Nunca citar.

Etapa 6: Carregar Persona Especialista

Invocar agency_agents_load(agent="content-creator") (ou especialista da Agência apropriado) e aplicar o tom de comunicação ditado pelo SOUL.md do perfil ativo.

Etapa 7: Rascunhar HTML Semântico Completo (Nativo do Gutenberg)

Compor 900–1.500 palavras de HTML semântico usando comentários de bloco nativos do WordPress Gutenberg (<!-- wp:paragraph -->, <!-- wp:heading -->, <!-- wp:separator -->, <!-- wp:list -->):

1. H1 Único: Lidado pelo template da página; iniciar o corpo diretamente com parágrafos de abertura.
2. Anatomia de Abertura de 3 Parágrafos:
   • Parágrafo 1 (O Gancho): Cenário da vida real validando as dificuldades do público (derivado de insights do Nível 3).
   • Parágrafo 2 (Resposta Rápida): Resposta direta natural e calmante (sem rótulo rígido "Resposta Rápida:").
   • Parágrafo 3 (Transição): Convite caloroso para explorar soluções juntos.
3. Elaboração por H2: 3 a 5 parágrafos abrangentes por título, integrando etapas práticas de estimulação doméstica (≤24 horas).
4. Integração de Links Internos:
   • Vertical (Obrigatório): Link contextual natural de volta ao Hub Principal nas primeiras 300–500 palavras: <a href="/posts/<slug-do-hub>" class="text-primary font-semibold underline hover:text-accent">...</a>.
   • Horizontal: Link contextual para artigos spoke relacionados descobertos na Etapa 4.
5. Regra de Contraste de Card de Destaque: Notas especiais devem usar <div class="my-8 rounded-2xl border-2 border-primary/25 bg-card p-6 sm:p-8 shadow-sm"> com títulos em text-primary font-bold ou text-foreground font-bold. Nunca usar text-secondary em cards claros.
6. Sequência de Fechamento:
   • <h2>Kesimpulan &amp; Langkah Pendampingan Terbaik</h2>: Resumo com 3 links de ação (/metode-belajar, /checklist-milestone, /kontak ou WhatsApp direto).
   • <h2>Pertanyaan yang Sering Diajukan Orang Tua (FAQ)</h2>: Mínimo de 5 perguntas formatadas 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 do aviso legal.
   • Aviso Legal Clínico Obrigatório: <div class="my-6 rounded-xl border border-border bg-muted/30 p-4 text-xs italic text-muted-foreground leading-relaxed">Catatan: Informação neste guia é educativa para apoiar a estimulação independente em casa e não substitui a avaliação direta e as recomendações médicas de um pediatra ou terapeuta profissional.</div>
   • <h2>Referências</h2>: <ol> lista de fontes verificadas com URLs https:// clicáveis completas correspondentes às citações inline.
7. 7 Critérios de SEO On-Page: Palavra-chave foco presente no Título, Slug do Permalink, primeiras 100 palavras, pelo menos um H2/H3, Resumo e densidade mantida entre 0,5%–2,0%.

Etapa 8: Geração Visual e Carregamento de Mídia (Zero Timeout)

1. Gerar imagem via image_generate (9Router) aplicando cores hexadecimais oficiais da marca e regra estrita anti_text_rule (sem texto/números/marcas d'água na tela).
2. Carregar imagem via ferramenta MCP upload_media:
   • Passar image_url ou image_base64.
   • Passar apply_watermark: true para a imagem destacada (marca automaticamente o logotipo da marca de forma adaptativa via PHP GD) e apply_watermark: false para ilustrações de corpo H2.
   • A ferramenta retorna id oficial (ID do anexo) e url no domínio do CMS (https://cms...), 100% compatível com remotePatterns do Next.js Vercel.
3. Incorporar imagens no artigo diretamente em blocos <figure class="wp-block-image size-large"><img src="..." alt="..." /><figcaption>...</figcaption></figure>.

Etapa 9: Publicação Instantânea (save_post)

Chamar save_post com:

• title, slug, content, category_id, focus_keyword, excerpt.
• featured_media_id: Definir para o id do anexo retornado de upload_media na Etapa 8.
• generate_featured_image: false e generate_in_article_images: false (ignora a geração síncrona de imagem no lado do servidor; executa como uma gravação instantânea no banco de dados <1 segundo, eliminando completamente os riscos de timeout).
• O WordPress automaticamente:
  1. Salva o post e atualiza os campos de meta SEO.
  2. Aciona a revalidação ISR On-Demand do Next.js.
  3. Indexa partes do artigo na tabela de embeddings vetoriais MariaDB (wp_sayoti_vectors).

Etapa 10: Auditoria de SEO e Relatório Final

1. Chamar audit_post_seo(post_id: <id>) para obter uma auditoria abrangente de SEO (palavra-chave foco, estrutura de cabeçalhos, meta descrições, densidade, legibilidade).
2. Visar uma Pontuação de SEO de 80-100%.
3. Se a pontuação estiver abaixo de 80%, aplicar correções direcionadas (ajustar densidade de palavras-chave, adicionar cabeçalhos ausentes, reescrever meta descrições) e reauditar.
4. Relatar a Pontuação Final ao usuário com confirmação ao vivo da URL publicada.

---

Fluxo de Trabalho de Geração de Página (Lead Magnet, Política de Privacidade, Termos de Serviço)

O fluxo é análogo ao de posts, mas usando save_page com a função de página apropriada:

1. Página Padrão: Conteúdo informativo ou de destino padrão.
2. Lead Magnet: page_role: 'lead_magnet', lead_magnet_type definido para o ativo (por exemplo, "Checklist Gratuito"). Nenhuma SEO audit é necessária; o foco está na conversão.
3. Páginas Legais (Política de Privacidade, Termos, Aviso Legal): Conteúdo gerado de acordo com modelos legais e regulamentações locais. Nenhuma pesquisa de palavra-chave é necessária.

---

Ferramentas MCP Expostas pelo sayoti-cms

Ferramenta	Descrição
get_topic_cluster	Recuperar clusters de tópicos Hub & Spoke disponíveis.
get_editorial_guidelines	Buscar regras editoriais ativas, limites de comprimento e paletas de cores.
rag_search	Pesquisar semânticamente posts existentes para verificar canibalização e encontrar links internos.
save_post	Criar ou atualizar um post de blog (upsert).
save_page	Criar ou atualizar uma página (upsert) com funções especializadas.
upload_media	Carregar e opcionalmente aplicar marca d'água a ativos de imagem.
audit_post_seo	Auditar a otimização de SEO de um post e retornar uma pontuação.