Référence des outils MCP
Chinaski embarque un serveur MCP (Model Context Protocol) qui expose les outils de contenu, de blocks, de media, de build, de thème et de formulaires de votre CMS à Claude Code et aux autres clients MCP.
Connexion
Le serveur MCP communique avec l'API REST de votre CMS, donc le CMS doit tourner. Il vous faut une clé API avec la permission write (Admin → Settings → API Keys), puis définir deux variables pour le serveur :
CHINASKI_API_URL: URL de base de votre CMS (pour l'instance locale 1 :http://localhost:3001)CHINASKI_API_KEY: votre clé API
La version du serveur est 1.1.0 et parle JSON-RPC 2.0 sur stdio. Une unité systemd (chinaski-mcp@1) est incluse dans deploy/ pour l'exécuter avec des redémarrages automatiques et des logs structurés écrits dans logs/mcp-server.log.
Logs : le serveur écrit des logs structurés avec rotation quotidienne et conserve les 7 logs quotidiens les plus récents.
Retries : les appels à l'API REST du CMS retentent jusqu'à 3 fois avec backoff exponentiel (1s, 2s, 4s) quand le CMS répond avec un rate limiting (429), une indisponibilité (503) ou d'autres erreurs 5xx, ou quand la requête expire. ping renvoie le statut du serveur, sa version, son uptime et le résultat du health check du CMS.
Outils de contenu
Énumérés ci-dessous sous forme de tableaux d'outils. Les tableaux listent le nom de chaque outil et ce qu'il fait.
Pages et posts
| Outil | Ce qu'il fait |
|---|---|
list_pages / list_posts | Lister le contenu. Renvoie une liste allégée (le champ body est omis). limit jusqu'à 1000, 50 par défaut ; filtre par language. |
get_page / get_post | Récupérer un élément par ID. Objet complet ou 404. |
create_page / create_post | Créer du contenu. Utilisez {{block:name}} dans le body pour intégrer des blocks. Les pages prennent en charge la surcharge de template (par ex. landing.tt), parent_id pour l'arborescence des pages, et schedule_publish_at / unpublish_at (ISO 8601, heure locale du site). Les posts acceptent un slug category, des tags séparés par des virgules, une surcharge published_at, et la programmation. |
update_page / update_post | Mettre à jour par ID. Seuls les champs que vous fournissez changent. |
delete_page / delete_post | Suppression logique. |
Blocks
| Outil | Ce qu'il fait |
|---|---|
list_blocks / get_block | Parcourir les blocks (le content_json structuré est omis dans les résultats de liste). |
create_block | Créer un block ; le name unique est ce que vous référencez dans les bodies via {{block:name}}. Types valides : accordion, columns, cta, embed, form, gallery, hero, image, newsletter, promo, quote, stat, table, testimonial, text, video. Les options de style incluent les couleurs de fond/texte/bouton, la largeur de bordure, le padding, la margin, et la couleur/opacité de l'overlay (0.0 à 1.0). |
bulk_create_blocks | Créer plusieurs blocks en un seul appel ; les erreurs par élément sont renvoyées avec les succès. |
update_block / delete_block | Modifier ou supprimer logiquement. |
Snippets et catégories
| Outil | Ce qu'il fait |
|---|---|
list_snippets / get_snippet / create_snippet / update_snippet / delete_snippet | Gérer les snippets de code injectés dans le head ou le body du site. Définissez is_global pour injecter sur chaque page ; définissez privacy_sensitive pour marquer un snippet comme nécessitant un consentement avant chargement. |
list_categories | Lister les catégories de posts. |
get_category / create_category / update_category / delete_category | Gérer les catégories par ID (les suppressions sont logiques). |
Build
| Outil | Ce qu'il fait |
|---|---|
trigger_build | Déclencher une reconstruction du site statique. Renvoie dispatched, busy ou missing. |
get_build_status | Renvoie l'heure du dernier build et indique si un build est en cours. |
Le build s'exécute de manière asynchrone : après avoir créé ou mis à jour du contenu, appelez trigger_build, puis interrogez get_build_status : build_in_progress: true signifie qu'il tourne encore.
Formulaires
| Outil | Ce qu'il fait |
|---|---|
list_forms / get_form | Lister et récupérer les formulaires (les points de terminaison de webhook/notification sont exclus de ces résultats). |
create_form | Créer un formulaire avec un nom et un slug (le slug est utilisé dans les intégrations et les références API). |
update_form | Mettre à jour les réglages du formulaire : par exemple notify_email, reply_to_field ou blocked_countries. Remarque : les URL de webhook, l'URL de remerciement et le secret du webhook ne sont pas modifiables via ces outils. |
delete_form | Suppression logique. |
list_form_fields / create_form_field / update_form_field / delete_form_field | Gérer les champs de formulaire. Types de champ : text, email, tel, textarea, select, checkbox, address, radio, checkboxes, file. Les noms de champ sont assainis en lettres minuscules, chiffres et underscores. Les options de select/radio/checkboxes sont séparées par des retours à la ligne. L'affichage conditionnel se définit avec condition_field + condition_value ; la largeur de mise en page est full ou half. |
Navigation
| Outil | Ce qu'il fait |
|---|---|
list_nav_items / create_nav_item / update_nav_item / delete_nav_item | Gérer les menus de navigation. Filtrer par slot (header ou footer) ; is_external ouvre dans un nouvel onglet ; parent_id imbrique les éléments. |
Media et documents
| Outil | Ce qu'il fait |
|---|---|
list_media | Liste paginée de la médiathèque, 50 par page. |
get_media | Détails d'un media : fichier, type MIME, taille, texte alt, dossier, URL, dimensions, légende, crédit et timestamps. |
update_media | Mettre à jour les métadonnées uniquement : texte alt, légende, crédit, dossier. |
list_documents | PDF publiés et fichiers téléchargeables, y compris les compteurs de téléchargements. |
get_document | Récupérer un document par slug. |
Thèmes
| Outil | Ce qu'il fait |
|---|---|
get_theme_guide | Renvoie la référence complète de création de thèmes Chinaski au format Markdown. Lecture recommandée avant de générer des fichiers de thème. |
list_themes / clone_theme | Lister les thèmes, ou en cloner un comme point de départ (source par défaut : sbs). |
list_theme_files / read_theme_file | Parcourir et lire les fichiers de template .tt d'un thème. |
write_theme_file | Créer ou écraser un fichier de template. Le contenu est analysé pour la sécurité et validé syntaxiquement côté serveur avant d'être accepté. |
delete_theme | Supprimer un thème et tous ses fichiers ; seuls les thèmes non actifs peuvent être supprimés. |
Design briefs
| Outil | Ce qu'il fait |
|---|---|
list_design_briefs | Lister les design briefs téléversés (HTML/CSS de référence utilisés pour la direction visuelle). |
read_design_brief_file / list_design_brief_files | Lire les fichiers à l'intérieur d'un brief par son ID. |
Outils de plus haut niveau
Ceux-ci combinent plusieurs opérations du CMS en un seul appel :
| Outil | Ce qu'il fait |
|---|---|
create_post_with_blocks / create_page_with_blocks | Créer du contenu ainsi que ses blocks en un seul appel ; le shortcode {{block:name}} de chaque block est ajouté automatiquement au body. |
append_block_to_page / append_block_to_post | Ajouter {{block:name}} à une page ou un post existant par ID ou slug (l'ID est prioritaire). |
bulk_import | Créer, ou avec upsert: true créer ou mettre à jour, plusieurs pages ou posts à partir d'un tableau, appariés par slug + langue et appliqués de façon atomique par élément. Peut optionnellement déclencher un build. |
bulk_update | Mettre à jour plusieurs pages ou posts par ID. |
bulk_create_and_append_blocks | Créer des blocks et rattacher chacun à une page en un seul appel. |
translate_content | Récupérer une page ou un post et créer une copie traduite dans une langue cible ; vous fournissez le titre et le body traduits, tandis que les champs indépendants de la langue (image mise en avant, auteur, et similaires) sont copiés automatiquement. |
audit_content | Rapporter l'exhaustivité des traductions sur les pages, posts, blocks, snippets, nav items et catégories, en listant les éléments avec des indicateurs MISSING ou STALE. La langue de base est en par défaut. |
auto_create_translations | Créer des stubs de traduction pour un élément de contenu : l'enregistrement source est copié dans chaque langue manquante comme brouillon non publié. |
submit_job / get_job_status | Pour les très grosses opérations (200+ éléments), soumettre un job batch asynchrone (upserts en masse de pages/posts ou création de blocks) et interroger sa progression. |
Découvrir le contenu de votre site
| Outil | Ce qu'il fait |
|---|---|
get_site_context | Configuration du site : langues, thèmes, types de blocks, catégories avec nombre de posts, et compteurs de contenu récent. Mis en cache brièvement (5 minutes) ; passez refresh: true pour forcer une relecture. |
search_content | Recherche par mot-clé dans les pages, posts, blocks, snippets et catégories. |
get_popular_content | Pages et posts récemment mis à jour, les plus récents d'abord. |
get_content_gaps | Auditer les pages/posts pour repérer les meta descriptions manquantes, les bodies vides ou l'absence d'image mise en avant. |
get_pages_missing_block_type | Trouver les pages qui ne référencent aucun block d'un type donné (par ex. cta). |
get_orphaned_blocks | Trouver les blocks non référencés par aucun body de page ou de post. |
list_scheduled_pages / list_scheduled_posts | Contenu en file d'attente pour une publication automatique future, avec les heures de publication locales. |
list_redirects | Toutes les redirections, filtrables par langue. |
Parcourir comme ressources
Outre les outils, le serveur expose un graphe de contenu parcourable via les ressources MCP, qui permet à un client de lire le contenu avant de rien modifier :
page://en/about-us: une page publiée par langue/slugpost://en/blog/my-post: un post de blog par langue/slugblock://en/hero-home: un block par langue/nomtheme://library/page.tt: un fichier de template de thème
Utilisez resources/list, resources/read et resources/templates/list. Les snippets ne peuvent pas être lus par URI ; utilisez les outils de snippets à la place.
Prompts préétablis
prompts/list propose des prompts tout prêts :
- Écrire un post de blog dans le style de l'article le plus récemment mis à jour
- Auditer toutes les pages et tous les posts pour les meta descriptions manquantes
- Lister le contenu sans image mise en avant
- Identifier les pages les plus récemment mises à jour dont les traductions manquent
- Trouver les blocks non référencés par aucun body de page ou de post
- Préparer une nouvelle landing page dans la langue par défaut du site
Historique de session
La plupart des outils de create/update/delete acceptent un argument context optionnel (un ID de session). Quand il est fourni, chaque appel est enregistré et peut être récupéré plus tard avec get_session_history. Les enregistrements de session expirent automatiquement après 24 heures. Les mots de passe, secrets et clés API sont masqués avant tout stockage.
Patterns de travail efficaces
- Pour beaucoup d'éléments d'un coup, préférez les outils en masse :
bulk_import(avecupsert: true),bulk_update, oucreate_post_with_blocks/create_page_with_blocksplutôt que de longues chaînes de créations individuelles. - Utilisez
submit_jobpour les opérations de 200+ éléments, puis interrogezget_job_status. - Après avoir modifié du contenu, rappelez-vous que le site est statique : le rebuild n'a lieu que lorsque vous appelez
trigger_build.