Hecho con Chinaski

Servidor MCP

Chinaski incluye un servidor MCP (Model Context Protocol) que conecta asistentes de IA como Claude Code directamente con tu CMS: expone toda la superficie de contenido del CMS como herramientas que el asistente puede llamar. El servidor habla JSON-RPC sobre stdio, así que tu asistente lo lanza como proceso local; no escucha en ninguna red por sí mismo. Esta página explica cómo configurarlo, qué puede hacer y cómo se comporta.

Qué puede hacer

CRUD de contenido; list/fetch/create/update/delete para páginas, posts, blocks, snippets, categorías, documentos, forms (y sus campos), media, nav items y themes. El tier cubierto en la tabla del README es un subconjunto núcleo; el servidor también incluye herramientas para nav items, media, forms, manejo de documentos, clonado de themes, limpieza de orphan blocks y más; revisa la lista de herramientas que tu cliente muestra después de conectar.

Herramientas de nivel superior; crear una página o post junto con sus blocks incrustados en una sola llamada (create_page_with_blocks, create_post_with_blocks), traducir una página/post a otro idioma, auditar por traducciones faltantes, importar en masa muchas páginas/posts (con upsert para actualizar por slug+idioma), bulk-update, crear-y-agregar blocks, y enviar/consultar jobs asíncronos para operaciones muy grandes.

Descubrimiento y análisis; get_site_context (idiomas, themes, tipos de block, categorías, conteos recientes), búsqueda por palabra clave a través de los tipos de contenido, reportes de contenido popular y content-gap (meta descriptions faltantes, bodies vacíos, featured images faltantes), más audit_meta_descriptions y creación automática de traducciones.

Resources; el contenido es navegable como resources como page://en/about-us, post://en/blog/my-post, block://en/hero-home, theme://library/page.tt, antes de mutar cualquier cosa.

Prompts; un conjunto de prompts predefinidos, p. ej. "Write a blog post in the style of my most popular article", "Audit all pages for missing meta descriptions", "Find blocks not referenced by any page or post body".

Prerrequisitos

  • Una instancia de CMS corriendo (servicio chinaski@<N>).
  • Una API key con permiso write, creada bajo Admin → Settings → API Keys. Las keys read no crearán contenido.

Configuración

Apunta el servidor a tu CMS con dos variables de entorno requeridas:

  • CHINASKI_API_URL; URL base del CMS (p. ej. http://127.0.0.1:3001). El servidor se niega a arrancar sin ella.
  • CHINASKI_API_KEY; la API key de arriba. También requerida.

Afinado opcional:

Variable Default Propósito
CHINASKI_MCP_LOG_DIR logs A dónde van los logs del servidor
CHINASKI_MCP_LOG_FILE <log dir>/mcp-server.log Nombre exacto del archivo de log
CHINASKI_MCP_SESSION_DB chinaski-mcp/sessions.db Base de datos del historial de sesiones
CHINASKI_MCP_SESSION_TTL 86400 (24h) Cuánto viven los registros de sesión
CHINASKI_MCP_CONTEXT_TTL 300 Vida de la cache de site-context (segundos)
CHINASKI_MCP_MAX_RETRIES 3 Intentos por llamada REST

Verificación rápida de cordura de que el servidor responde un handshake initialize: haz echo de una petición JSON-RPC initialize al proceso con ambas variables de entorno requeridas establecidas y verifica que recibes un resultado de vuelta.

Registro en Claude Code

Una configuración de ejemplo vive en .claude/settings.json del repo; añade tu API URL y key, y recarga Claude Code para que el servidor se registre. El registro luce como una entrada mcpServers apuntando el servidor chinaski a perl …/chinaski-mcp/chinaski-mcp.pl con las dos variables de env de arriba.

Correr como servicio

deploy/chinaski-mcp@.service corre el servidor bajo systemd por instancia y lo auto-reinicia ante fallos. La unidad apunta los logs a /var/www/chinaski<N>/logs y la DB de sesiones a /var/www/chinaski<N>/chinaski-mcp/sessions.db y suministra la URL/key desde /etc/chinaski<N>/mcp-env.

Los logs rotan solos a diario (mcp-server.log.YYYY-MM-DD), con los 7 más nuevos conservados. Bajo systemd, todo también va a journald.

Sesiones, reintentos y estabilidad

  • Las llamadas a herramientas pueden etiquetarse con un argumento opcional context (un ID de sesión). Las llamadas etiquetadas se almacenan en la base de datos de sesiones (contraseñas, secrets y API keys redactados) y pueden revisarse después con get_session_history; los registros expiran tras el TTL de sesión.
  • Las llamadas al CMS reintentan automáticamente; hasta los 3 intentos configurados con backoff exponencial (1 s, 2 s, 4 s); solo en respuestas 429, 503 y otros 5xx.
  • Los resultados de get_site_context se cachean por 5 minutos.
  • El handshake ping reporta el estado del servidor, versión y uptime junto con el resultado de /api/health del CMS.
  • Nombres de herramienta o prompt desconocidos devuelven un error de inmediato, y los sites que no existen devuelven una respuesta "not found" en lugar de crashear.

Trabajar con contenido

Notas del README del proyecto que aplican de hora a hora:

  • Incrusta blocks en los bodies de páginas y posts con shortcodes {{block:name}​}; el builder estático los resuelve al momento del build.
  • Crear contenido no toca el site vivo hasta que disparas un build; llama a trigger_build, luego consulta get_build_status.
  • Prefiere las herramientas en masa (bulk_import con upsert, create_*_with_blocks) sobre muchas llamadas de un ítem, y usa submit_job para lotes muy grandes (del orden de cientos de ítems).
Lee este sitio en