Motor de Contenido para Productos Shopify

Un pipeline de n8n que convierte un producto básico (product_name, product_description) en un kit de marketing completo listo para revisión — investigación SEO, texto de página de producto, una entrada de blog, anuncios de Google + Meta, publicaciones en redes sociales, un correo electrónico y una imagen principal — y escribe una fila por producto en una hoja de revisión. Nada se publica automáticamente; un humano aprueba.

Junto con el flujo de trabajo, este repositorio incluye las dos cosas que lo hacen operativo en lugar de una demostración: un entorno de evaluación que puntúa cada kit generado según las propias reglas del motor (límites de longitud, palabras prohibidas, hechos inventados) y un servidor MCP para que cualquier agente — Claude Desktop, Claude Code, Cursor, el tuyo propio — pueda validar borradores y ejecutar procesos.

product_name + product_description
        │
        ▼
 ┌────────────── n8n ──────────────┐
 │ idempotency gate → 3 LLM calls  │──▶ Review sheet (status=done | failed)
 │ strict JSON → validate → map    │──▶ hero image → Drive
 │ dry-run · retry · dead-letter   │──▶ batch summary email
 └─────────────────────────────────┘
        ▲                       │
   MCP server               eval harness
 (validate / run)      (rules + LLM judge, gates CI)

Por qué está construido así

Related MCP server: Shopify MCP Server

Flujo

Manual / Schedule / Webhook ─▶ ⚙️ Config ─▶ 📥 Read Products [swap point → Shopify]
  ─▶ 📖 Read Done ─▶ 🚦 Idempotency Gate ─▶ 🔢 Limit ─▶ 🔁 Loop (1 product at a time)
        ─▶ 🤖 A: SEO + Product Page ─▶ 🤖 B: Blog ─▶ 🤖 C: Ads / Social / Email / Image prompt
        ─▶ 🧩 Parse, Validate & Map ─▶ 🧪 Dry run?
              ├─ yes ─▶ 📝 Dry-run log (no write) ─▶ loop
              └─ no  ─▶ 🖼️ Images? ─▶ 🎨 gpt-image-1 ─▶ ☁️ Drive ─▶ 📤 Upsert Review row ─▶ loop
  🔁 done ─▶ 📊 Batch summary ─▶ ✉️ Email (optional)
  (uncaught) ─▶ ⚠️ Error Handler workflow ─▶ alert email

Diagrama Mermaid completo: docs/architecture.mmd. La fuente del producto es hoy una Hoja de Google; 📥 Leer Productos es un punto de intercambio marcado para Shopify → Obtener Productos (title → product_name, body_html → product_description).

Evaluaciones

python -m evals puntúa los kits (filas de la pestaña Revisión) según las reglas que el motor promete cumplir. Las reglas provienen directamente de config/generation.config.yaml y config/brand-voice.yaml, por lo que cambiar un límite en la configuración cambia la evaluación.

Conjunto dorado actual (kit real de una ejecución en vivo, evals/golden/kits.json):

Ese hallazgo es exactamente por qué existe el entorno de evaluación — ahora es un elemento pendiente (ver hoja de ruta). Ejecútalo contra tu propia exportación con python -m evals --input review-export.csv --min-score 0.9; el código de salida distinto de cero bloquea la CI.

Servidor MCP

mcp_server/ expone el motor a través del Protocolo de Contexto de Modelo (stdio):

Recursos: content-engine://columns (mapa de columnas de la hoja de Revisión), content-engine://prompts/{A|B|C}.

Configuración de Claude Desktop / Claude Code:

{
  "mcpServers": {
    "shopify-content-engine": {
      "command": "content-engine-mcp",
      "env": { "N8N_WEBHOOK_URL": "https://<your-instance>/webhook/shopify-content-engine-run" }
    }
  }
}

Estructura del repositorio

workflows/     shopify-content-engine.workflow.json · error-handler.workflow.json   (import these)
prompts/       system prompts A / B / C + prompt library (version-controlled mirror of ⚙️ Config)
config/        brand-voice.yaml · generation.config.yaml                            (limits, flags)
docs/          runbook.md · architecture.mmd · output-sheet-columns.md
test/          product-fixtures.json (5 products) · dry-run checklist · a real generated kit
evals/         checks.py (rules) · judge.py (LLM judge) · golden/ · tests/
mcp_server/    server.py · tests/
scripts/       check_workflows.py — static checks on the exported JSON (runs in CI)

Inicio rápido

Flujo de trabajo

1. Importa workflows/error-handler.workflow.json, luego workflows/shopify-content-engine.workflow.json.

2. Vuelve a seleccionar las credenciales en los nodos de OpenAI / Hojas de Google / Drive / Gmail (nunca almacenadas en el JSON).

3. Apunta 📥 Leer Productos, 📖 Leer Hechos, 📤 Escribir a una hoja con las pestañas Products y Review.

4. Establece Configuración → Flujo de trabajo de error al manejador de errores importado.

5. Ejecuta en seco los cinco elementos de prueba (test/README.md), luego ejecuta de verdad. Las banderas de ejecución se pueden publicar en el cuerpo del webhook: {"dryRun": true, "enableImages": false}.

Evaluaciones + MCP

pip install -e ".[mcp,dev]"
python -m evals                     # score the golden set
python -m evals --input export.csv  # score your own Review-tab export
pytest                              # 27 tests: rules, negative cases, MCP tools in-process
content-engine-mcp                  # start the MCP server (stdio)

Hoja de ruta

• Guardia de longitud mínima + un reintento autocorrectivo en el paso de Análisis (la evaluación actualmente marca el texto corto después del hecho).

• Autenticación de encabezado en el disparador del webhook (credencial de n8n) — hoy depende de la ruta imposible de adivinar.

• API de Administración de Shopify como fuente de productos y una escritura de Producto borrador detrás de la misma puerta de aprobación.

• Conjunto dorado: más kits reales, uno por elemento de prueba, y una ejecución nocturna de --judge.

Licencia

MIT