CMS Headless para IA

Qué incluye este pack

Este pack reúne los cinco backends headless que vale la pena instalar cuando necesitas que un agente IA lea o mute datos reales de negocio — contenido, productos, órdenes, usuarios — sin escribir endpoints CRUD a medida.

La división es intencional: Strapi para contenido editorial, Medusa / Vendure para datos de producto+orden, Directus / Hasura para superficies SQL arbitrarias. La mayoría de sistemas en producción eligen uno de cada fila según qué casos de uso dominan.

Por qué headless importa para agentes

Los CMS tradicionales entregan HTML; los agentes no consumen HTML bien. Los CMS headless entregan JSON tipado y schemas GraphQL. La diferencia se acumula:

• Introspección de schema. Los endpoints GraphQL son auto-documentados. Un agente puede llamar __schema y descubrir qué campos existen, qué retornan, qué argumentos aceptan. Sin docs API manuales que sincronizar.
• Seguridad de mutación. Los endpoints REST + GraphQL declaran operaciones de escritura explícitamente con tipos de entrada. Los agentes pueden validar antes de enviar, y el server rechaza payloads malformados en la capa de transporte en vez de tras una escritura parcial.
• Permisos. Cada herramienta aquí entrega control de acceso basado en roles. Puedes darle al agente un token con scope que solo lea ciertos tipos de contenido o solo mute recursos específicos, con logs de auditoría.
• Multi-lenguaje e i18n. Strapi y Directus tienen soporte de locale de primera clase, lo cual importa cuando el agente está generando o traduciendo contenido.

Estas propiedades son por las que un CMS headless, aunque excesivo para el equipo humano de contenido, suele ser el sustrato correcto para un producto agente-driven.

Instala en un comando

# Instala el pack completo
tokrepo install pack/headless-cms-for-ai

# O elige un backend
tokrepo install strapi
tokrepo install hasura

Cada herramienta se instala como snippet Docker compose más un skill Claude Code que conoce la superficie API. El skill expone métodos tipados como strapi.list_articles({ filters }) para que el agente no tenga que armar URLs REST a mano.

Errores comunes

• Drift de schema entre agente y server. Cuando agregas un tipo de contenido en el admin UI, el cache de schema local del agente queda rancio. Re-introspecta cada inicio de sesión, o cablea un webhook para que el agente invalide en cambios de tipo de contenido.
• Queries N+1 desde agentes. Los agentes tienden a fetchear de a un registro. Usa endpoints bulk (Strapi populate=*, selecciones anidadas Hasura) y presupuesta queries — pon rate limit por agente.
• Tokens de lectura públicos. Es tentador dar al agente un token de lectura amplio. No. Limita scope a colecciones específicas; revoca en cambio de rol. Las cinco herramientas tienen UI de permisos finos.
• Idempotencia de mutación. Los agentes reintentan. Si un agente reintenta createOrder tras un blip de red, tendrás duplicados. Usa idempotency keys (Medusa los soporta nativamente; para los otros, capa un campo request_id).
• Backups. Los CMS headless centralizan contenido; si la BD se corrompe pierdes un año de trabajo editorial. Configura snapshots diarios antes de dejar al agente escribir en producción.

Conceptos erróneos comunes

• "Hasura y Directus son intercambiables." Se solapan en "exponer SQL como GraphQL" pero difieren en audiencia: Hasura es para ingenieros que quieren una capa GraphQL fina sobre Postgres; Directus es para equipos que también quieren UI admin de contenido. Si solo necesitas la API, usa Hasura. Si no-ingenieros editarán datos, Directus.
• "Strapi puede reemplazar a Medusa para comercio." Strapi maneja contenido bellamente pero le faltan workflow de orden, pago, e inventario. Usa Medusa o Vendure, luego apunta Strapi a contenido adyacente a productos (blog, páginas marketing).
• "GraphQL siempre es mejor que REST para agentes." A veces — la introspección de schema es genial. Pero para list/get simple, los endpoints REST son más fáciles de cachear y más fáciles para que el agente componga con herramientas a nivel HTTP. Las cinco hablan ambas; elige por llamada.

Relación con otros packs

• Postgres para Agentes IA es la capa de datos bajo Hasura y Directus.
• Stack de Servidores MCP incluye wrappers MCP sobre estos CMS para que el agente los use vía MCP en vez de HTTP crudo.
• Constructores de Apps IA consumen estos endpoints GraphQL desde el frontend.