Referencia de herramientas MCP
Chinaski incluye un servidor MCP (Model Context Protocol) que expone las herramientas de contenido, blocks, media, build, theme y form de tu CMS a Claude Code y otros clientes MCP.
Conexión
El servidor MCP habla con la API REST de tu CMS, así que el CMS debe estar corriendo. Necesitas una API key con permiso write (Admin → Settings → API Keys), luego establecer dos variables para el servidor:
CHINASKI_API_URL; URL base de tu CMS (para la instancia local 1:http://localhost:3001)CHINASKI_API_KEY; tu API key
La versión del servidor es 1.1.0 y habla JSON-RPC 2.0 sobre stdio. Una unidad systemd (chinaski-mcp@1) está incluida en deploy/ para ejecutarlo con reinicios automáticos y logs estructurados escritos en logs/mcp-server.log.
Logs: el servidor escribe logs estructurados con rotación diaria y conserva los 7 logs diarios más recientes.
Reintentos: las llamadas a la API REST del CMS reintentan hasta 3 veces con backoff exponencial (1s, 2s, 4s) cuando el CMS responde con limitación de tasa (429), no disponible (503), u otros errores 5xx, o cuando la petición expira en tiempo. ping devuelve el estado del servidor, versión, uptime y el resultado del health check del CMS.
Herramientas de contenido
Enumeradas abajo como tablas de herramientas. Las tablas listan el nombre de cada herramienta y qué hace.
Páginas y posts
| Herramienta | Qué hace |
|---|---|
list_pages / list_posts | Lista el contenido. Devuelve una lista ligera (el campo body se omite). limit hasta 1000, por defecto 50; filtra por language. |
get_page / get_post | Obtiene uno por ID. Objeto completo o 404. |
create_page / create_post | Crea contenido. Usa {{block:name}} en el body para incrustar blocks. Las páginas soportan override de template (p. ej. landing.tt), parent_id para el árbol de páginas y schedule_publish_at / unpublish_at (ISO 8601, hora local del site). Los posts aceptan un slug de category, tags separadas por comas, un override de published_at y programación. |
update_page / update_post | Actualiza por ID. Solo cambian los campos que suministres. |
delete_page / delete_post | Borrado suave. |
Blocks
| Herramienta | Qué hace |
|---|---|
list_blocks / get_block | Navega los blocks (el content_json estructurado se omite en los resultados de lista). |
create_block | Crea un block; el name único es lo que referencias en los bodies vía {{block:name}}. Tipos válidos: accordion, columns, cta, embed, form, gallery, hero, image, newsletter, promo, quote, stat, table, testimonial, text, video. Las opciones de estilo incluyen colores de fondo/texto/botón, ancho del borde, padding, margen y color/opacidad de overlay (0.0 a 1.0). |
bulk_create_blocks | Crea muchos blocks en una llamada; los errores por ítem se devuelven junto a los éxitos. |
update_block / delete_block | Modifica o hace borrado suave. |
Snippets y categorías
| Herramienta | Qué hace |
|---|---|
list_snippets / get_snippet / create_snippet / update_snippet / delete_snippet | Gestiona snippets de código inyectados en el head o el body del site. Establece is_global para inyectar en cada página; establece privacy_sensitive para marcar un snippet como que requiere consentimiento antes de cargar. |
list_categories | Lista las categorías de posts. |
get_category / create_category / update_category / delete_category | Gestiona categorías por ID (los borrados son suaves). |
Build
| Herramienta | Qué hace |
|---|---|
trigger_build | Dispara un rebuild del site estático. Devuelve dispatched, busy o missing. |
get_build_status | Devuelve la hora del último build y si un build está corriendo actualmente. |
El build corre de forma asíncrona: después de crear o actualizar contenido, llama a trigger_build, luego hace polling a get_build_status; build_in_progress: true significa que todavía está corriendo.
Forms
| Herramienta | Qué hace |
|---|---|
list_forms / get_form | Lista y obtiene forms (los endpoints de webhook/notificación se excluyen de estos resultados). |
create_form | Crea un form con un nombre y un slug (el slug se usa en embeds y referencias de API). |
update_form | Actualiza la configuración del form; por ejemplo notify_email, reply_to_field o blocked_countries. Nota: las URLs de webhook, la URL de thank-you y el secret de webhook no son escribibles mediante estas herramientas. |
delete_form | Borrado suave. |
list_form_fields / create_form_field / update_form_field / delete_form_field | Gestiona los campos de form. Tipos de campo: text, email, tel, textarea, select, checkbox, address, radio, checkboxes, file. Los nombres de campo se depuran a letras minúsculas, dígitos y subrayados. Las opciones para select/radio/checkboxes se separan por saltos de línea. La visualización condicional se establece con condition_field + condition_value; el ancho de layout es full o half. |
Navegación
| Herramienta | Qué hace |
|---|---|
list_nav_items / create_nav_item / update_nav_item / delete_nav_item | Gestiona los menús de navegación. Filtra por slot (header o footer); is_external abre en una pestaña nueva; parent_id anida ítems. |
Media y documentos
| Herramienta | Qué hace |
|---|---|
list_media | Listado paginado de la biblioteca de media, 50 por página. |
get_media | Detalles del media: archivo, tipo MIME, tamaño, texto alt, carpeta, URL, dimensiones, caption, credit y timestamps. |
update_media | Actualiza solo metadatos: texto alt, caption, credit, carpeta. |
list_documents | PDFs publicados y archivos descargables, incluidos los conteos de descargas. |
get_document | Obtiene un documento por slug. |
Themes
| Herramienta | Qué hace |
|---|---|
get_theme_guide | Devuelve la referencia completa de creación de themes de Chinaski como Markdown. Lectura recomendada antes de generar cualquier archivo de theme. |
list_themes / clone_theme | Lista los themes, o clona uno como punto de partida (fuente por defecto: sbs). |
list_theme_files / read_theme_file | Navega y lee los archivos de template .tt de un theme. |
write_theme_file | Crea o sobrescribe un archivo de template. El contenido se escanea por seguridad y se valida sintácticamente en el servidor antes de aceptarse. |
delete_theme | Borra un theme y todos sus archivos; solo los themes no activos pueden borrarse. |
Design briefs
| Herramienta | Qué hace |
|---|---|
list_design_briefs | Lista los design briefs subidos (HTML/CSS de referencia usados para dirección visual). |
read_design_brief_file / list_design_brief_files | Lee los archivos dentro de un brief por su ID. |
Herramientas de nivel superior
Estas combinan varias operaciones del CMS en una sola llamada:
| Herramienta | Qué hace |
|---|---|
create_post_with_blocks / create_page_with_blocks | Crea contenido más sus blocks en una llamada; el shortcode {{block:name}} de cada block se agrega al body automáticamente. |
append_block_to_page / append_block_to_post | Agrega {{block:name}} a una página o post existente por ID o slug (el ID tiene precedencia). |
bulk_import | Crea, o con upsert: true crea-o-actualiza, muchas páginas o posts desde un array, emparejados por slug + language y aplicados atómicamente por ítem. Opcionalmente dispara un build. |
bulk_update | Actualiza muchas páginas o posts por ID. |
bulk_create_and_append_blocks | Crea blocks y adjunta cada uno a una página en una sola llamada. |
translate_content | Obtiene una página o post y crea una copia traducida en un idioma destino; tú suministras el título y el body traducidos, mientras que los campos agnósticos al idioma (featured image, author y similares) se copian automáticamente. |
audit_content | Reporta la completitud de traducción en páginas, posts, blocks, snippets, nav items y categorías, listando los ítems con indicadores MISSING o STALE. El idioma base por defecto es en. |
auto_create_translations | Crea stubs de traducción para un ítem de contenido: el registro fuente se copia a cada idioma faltante como draft no publicado. |
submit_job / get_job_status | Para operaciones muy grandes (200+ ítems), envía un job por lotes asíncrono (upserts masivos de páginas/posts o creación de blocks) y consulta su progreso. |
Descubrir el contenido de tu site
| Herramienta | Qué hace |
|---|---|
get_site_context | Configuración del site: idiomas, themes, tipos de block, categorías con conteos de posts y conteos de contenido reciente. Cacheada brevemente (5 minutos); pasa refresh: true para forzar una relectura. |
search_content | Búsqueda por palabra clave en páginas, posts, blocks, snippets y categorías. |
get_popular_content | Páginas y posts actualizados recientemente, los más nuevos primero. |
get_content_gaps | Audita páginas/posts por meta descriptions faltantes, bodies vacíos o sin featured image. |
get_pages_missing_block_type | Encuentra páginas que no referencian ningún block de un tipo dado (p. ej. cta). |
get_orphaned_blocks | Encuentra blocks no referenciados por ningún body de página o post. |
list_scheduled_pages / list_scheduled_posts | Contenido en cola para auto-publish futuro, con horas de publish locales. |
list_redirects | Todos los redirects, filtrables por idioma. |
Navegación como resources
Además de las herramientas, el servidor expone un grafo de contenido navegable mediante resources de MCP, lo que permite a un cliente leer el contenido antes de cambiar nada:
page://en/about-us; una página publicada por idioma/slugpost://en/blog/my-post; un post del blog por idioma/slugblock://en/hero-home; un block por idioma/nombretheme://library/page.tt; un archivo de template de theme
Usa resources/list, resources/read y resources/templates/list. Los snippets no se pueden leer por URI; usa las herramientas de snippet en su lugar.
Prompts predefinidos
prompts/list ofrece prompts listos para usar:
- Escribe un post de blog al estilo del artículo actualizado más recientemente
- Audita todas las páginas y posts por meta descriptions faltantes
- Lista el contenido sin featured image
- Identifica las páginas actualizadas más recientemente a las que les faltan traducciones
- Encuentra blocks no referenciados por ningún body de página o post
- Redacta una nueva landing page usando el idioma por defecto del site
Historial de sesión
La mayoría de herramientas de create/update/delete aceptan un argumento opcional context (un ID de sesión). Cuando se suministra, cada llamada se registra y puede recuperarse después con get_session_history. Los registros de sesión expiran automáticamente después de 24 horas. Las contraseñas, secrets y API keys se redactan antes de que algo se almacene.
Patrones de trabajo eficientes
- Para muchos ítems a la vez, prefiere las herramientas en masa:
bulk_import(conupsert: true),bulk_updateocreate_post_with_blocks/create_page_with_blocksen lugar de largas cadenas de creaciones individuales. - Usa
submit_jobpara operaciones de 200+ ítems, luego consultaget_job_status. - Después de cambiar contenido, recuerda que el site es estático: el rebuild solo ocurre cuando llamas a
trigger_build.