Serveur MCP
Chinaski embarque un serveur Model Context Protocol (MCP) qui connecte les assistants IA comme Claude Code directement à votre CMS : il expose toute la surface de contenu du CMS comme outils que l'assistant peut appeler. Le serveur parle JSON-RPC sur stdio, si bien que votre assistant le lance comme un processus local ; il n'écoute sur aucun réseau lui-même. Cette page explique sa mise en place, ce qu'il peut faire et comment il se comporte.
Ce qu'il peut faire
CRUD de contenu : list/fetch/create/update/delete pour les pages, posts, blocks, snippets, catégories, documents, formulaires (et leurs champs), media, nav items et thèmes. Le niveau couvert dans le tableau du README est un sous-ensemble cœur ; le serveur inclut aussi des outils pour les nav items, le media, les formulaires, la gestion des documents, le clonage de thème, le nettoyage des blocks orphelins, et plus ; consultez la liste d'outils que votre client affiche après connexion.
Outils de plus haut niveau : créer une page ou un post avec ses blocks intégrés en un seul appel (create_page_with_blocks, create_post_with_blocks), traduire une page/post dans une autre langue, auditer les traductions manquantes, importer en masse de nombreuses pages/posts (avec upsert pour mettre à jour par slug+langue), bulk-update, create-and-append blocks, et soumettre/interroger des jobs asynchrones pour de très grosses opérations.
Découverte et analyse : get_site_context (langues, thèmes, types de blocks, catégories, compteurs récents), recherche par mots-clés sur les types de contenu, rapports popular-content et content gaps (meta descriptions manquantes, body vides, images mises en avant manquantes), plus audit_meta_descriptions et création automatique de traductions.
Ressources : le contenu est parcourable comme ressources telles que page://en/about-us, post://en/blog/my-post, block://en/hero-home, theme://library/page.tt, avant de muter quoi que ce soit.
Prompts : un jeu de prompts préétablis, ex. « 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 ».
Prérequis
- Une instance du CMS en marche (service
chinaski@<N>). - Une clé API avec la permission write, créée sous Admin → Settings → API Keys. Les clés read ne créeront pas de contenu.
Configuration
Pointez le serveur vers votre CMS avec deux variables d'environnement obligatoires :
CHINASKI_API_URL: URL de base du CMS (ex.http://127.0.0.1:3001). Le serveur refuse de démarrer sans elle.CHINASKI_API_KEY: la clé API ci-dessus. Également requise.
Réglages fins optionnels :
| Variable | Défaut | Rôle |
|---|---|---|
CHINASKI_MCP_LOG_DIR | logs | Où vont les logs du serveur |
CHINASKI_MCP_LOG_FILE | <log dir>/mcp-server.log | Nom exact du fichier de log |
CHINASKI_MCP_SESSION_DB | chinaski-mcp/sessions.db | Base de données de l'historique de session |
CHINASKI_MCP_SESSION_TTL | 86400 (24 h) | Durée de vie des enregistrements de session |
CHINASKI_MCP_CONTEXT_TTL | 300 | Durée de vie du cache de site-context (secondes) |
CHINASKI_MCP_MAX_RETRIES | 3 | Tentatives par appel REST |
Vérification sanitaire rapide que le serveur répond à une poignée de main initialize : injectez par echo une requête initialize JSON-RPC dans le processus avec les deux variables env requises définies et vérifiez que vous obtenez un résultat en retour.
Enregistrement auprès de Claude Code
Une configuration d'exemple vit dans le .claude/settings.json du repo : ajoutez votre URL et clé API, puis rechargez Claude Code pour que le serveur s'enregistre. L'enregistrement ressemble à une entrée mcpServers pointant le serveur chinaski vers perl …/chinaski-mcp/chinaski-mcp.pl avec les deux variables env ci-dessus.
Exécution comme service
deploy/chinaski-mcp@.service exécute le serveur sous systemd par instance et le redémarre automatiquement en cas de défaillance. L'unité pointe les logs vers /var/www/chinaski<N>/logs et la DB de session vers /var/www/chinaski<N>/chinaski-mcp/sessions.db et fournit l'URL/la clé depuis /etc/chinaski<N>/mcp-env.
Les logs se rotent eux-mêmes quotidiennement (mcp-server.log.YYYY-MM-DD), les 7 plus récents étant conservés. Sous systemd, tout va aussi vers journald.
Sessions, retries et stabilité
- Les appels d'outils peuvent être étiquetés avec un argument
contextoptionnel (un ID de session). Les appels étiquetés sont stockés dans la base de données de sessions (mots de passe, secrets et clés API masqués) et peuvent être consultés plus tard avecget_session_history; les enregistrements expirent au terme du TTL de session. - Les appels au CMS réessayent automatiquement, jusqu'aux 3 tentatives configurées avec backoff exponentiel (1 s, 2 s, 4 s), uniquement sur les réponses 429, 503 et autres 5xx.
- Les résultats de
get_site_contextsont mis en cache pendant 5 minutes. - La poignée de main
pingrapporte le statut, la version et l'uptime du serveur aux côtés du résultat de/api/healthdu CMS. - Un nom d'outil ou de prompt inconnu renvoie une erreur immédiatement, et les sites inexistants renvoient une réponse « not found » plutôt que de crasher.
Travailler avec le contenu
Notes du README du projet qui s'appliquent heure par heure :
- Intégrez les blocks dans les body de pages et de posts avec les shortcodes
{{block:name}}; le builder statique les résout au moment du build. - Créer du contenu ne touche pas le site en ligne tant que vous ne déclenchez pas un build : appelez
trigger_build, puis interrogezget_build_status. - Préférez les outils en masse (
bulk_importavecupsert,create_*_with_blocks) à de nombreux appels à un seul élément, et utilisezsubmit_jobpour les très gros lots (de l'ordre des centaines d'éléments).