MCP Server

Aperçu

@cmssy/mcp-server est un serveur Model Context Protocol qui relie les agents IA (Claude Code, Claude Desktop, tout outil compatible MCP) à un workspace Cmssy. Une fois configuré, l'agent peut lister et modifier des pages, ajouter ou retirer des blocs, publier des brouillons, gérer des formulaires et plus encore — sans jamais quitter son éditeur.

Il est distribué sur npm et communique en stdio : vous ne faites donc pas tourner de serveur permanent, l'agent le lance à la demande via npx.

Ce qui le distingue de l'API HTTP

• Limité au workspace — une seule paire token + ID de workspace, tout est appliqué côté serveur
• Outils de haut niveau — add_block_to_page, publish_page, patch_block_content, pas de GraphQL brut
• Isolation des tenants intégrée — chaque requête est filtrée par votre workspace ; impossible de toucher accidentellement un autre tenant

Installation

1. Créez un token API

Workspace Settings → API Tokens → Create token. Copiez la valeur cs_… immédiatement — les tokens ne sont affichés qu'une seule fois. Le scope ne couvre que l'authentification ; ce que le token peut faire dépend de votre rôle et du flag isSuperAdmin.

2. Trouvez l'ID de votre workspace

Workspace Settings → General propose un bouton de copie à côté de l'ID. C'est le même workspace que celui lié à votre token API.

3. Ajoutez-le à la config MCP de votre éditeur

Pour Claude Code, éditez .mcp.json à la racine du projet (ou ~/.claude/mcp.json pour une installation globale) :

{
  "mcpServers": {
    "cmssy": {
      "command": "npx",
      "args": [
        "-y",
        "@cmssy/mcp-server@latest",
        "--token", "cs_your_token_here",
        "--workspace-id", "507f1f77bcf86cd799439011",
        "--api-url", "https://api.cmssy.io/graphql"
      ]
    }
  }
}

Les équivalents en variables d'environnement sont aussi pris en charge : CMSSY_API_TOKEN, CMSSY_WORKSPACE_ID, CMSSY_API_URL. Utile si vous ne voulez pas du token dans un fichier de config commité.

4. Redémarrez l'éditeur

Claude Code charge le serveur au prochain démarrage de session. Vous devriez voir une entrée MCP cmssy avec la liste des outils disponibles.

Outils disponibles

Pages

• list_pages — liste toutes les pages (filtre de recherche optionnel sur name/slug/displayName)
• get_page — page complète avec tous les blocs et le contenu i18n (par slug ou id)
• create_page / update_page_settings / delete_page
• publish_page / unpublish_page / revert_to_published
• update_page_blocks / update_page_layout

Blocs

• add_block_to_page / remove_block_from_page
• update_block_content — réécriture complète du contenu pour toute forme de bloc (chaînes, tableaux, objets imbriqués)
• patch_block_content — patchs HTML chirurgicaux sur les champs de type chaîne (analyse détaillée plus bas)

Formulaires

• list_forms / get_form
• create_form / update_form / delete_form
• list_form_submissions / get_form_submission
• update_form_submission_status / delete_form_submission

Custom Data Models

Définissez des schémas (ModelDefinitions) et faites du CRUD sur leurs enregistrements — les agents IA peuvent provisionner des types d'articles de blog, des catalogues produits, des entrées d'annuaire et plus encore. Les schémas/champs suivent PropertyField de @cmssy/types ; les enregistrements sont validés contre le modèle à chaque écriture. Nécessite les permissions workspace MODELS_VIEW / MODELS_CREATE / MODELS_EDIT / MODELS_DELETE.

Modèles

• list_models — liste toutes les ModelDefinitions du workspace
• get_model — récupère un modèle par id (ObjectId) ou slug
• create_model — crée un modèle (name, slug, fields, statusField optionnel pour le cycle de vie des enregistrements)
• update_model — met à jour n'importe quel champ d'un modèle (modifier fields déclenche une migration de schéma à la prochaine écriture d'enregistrement)
• delete_model — supprime un modèle — en cascade sur tous ses enregistrements

Enregistrements

• list_records — liste les enregistrements avec filtre de style MongoDB (JSON), tri, pagination, populate optionnel pour les relations
• get_record — récupère un enregistrement par id
• create_record — crée un enregistrement ; data indexé par les clés de champs du modèle
• update_record — met à jour les données d'un enregistrement et/ou fait transitionner son statut (validé contre statusField.transitions)
• delete_record — supprime un enregistrement
• import_records — import en masse jusqu'à 1000 enregistrements ; renvoie { importedCount, errors }

Workspace & médias

• get_workspace_info — nom, plan, limites, utilisation
• get_site_config — langues, navigation, fonctionnalités activées
• list_media — ressources uploadées

patch_block_content — éditions chirurgicales

Pour des modifications ciblées sur du contenu de plusieurs Ko (articles de docs, longs billets de blog), patch_block_content n'envoie que le diff — pas la chaîne complète. Il s'appuie sur MongoDB findOneAndUpdate avec $set + arrayFilters, limité au tenant, atomique. Typiquement ~10× moins cher en tokens que renvoyer tout le HTML via update_block_content.

Trois types d'opérations

insert_before / insert_after

Insérez du HTML juste avant/après un marqueur unique. Le marqueur DOIT correspondre à exactement un emplacement — zéro ou plusieurs occurrences rejettent l'opération avec BAD_USER_INPUT.

{
  "op": "insert_after",
  "marker": "<h2>Pricing</h2>",
  "html": "<p>Plans start at $0/month.</p>"
}

replace_section

Remplace tout depuis startMarker (inclus) jusqu'à endMarker (exclu). Les deux marqueurs doivent se résoudre de façon unique.

{
  "op": "replace_section",
  "startMarker": "<h2>Pricing</h2>",
  "endMarker": "<h2>FAQ</h2>",
  "html": "<h2>Pricing</h2><p>New plans here.</p>"
}

Plusieurs opérations en un appel

Les opérations s'appliquent dans l'ordre sur le résultat courant. Tout échec (marqueur manquant, ambigu, etc.) annule le patch entier — pas d'état à moitié appliqué.

{
  "pageId": "...",
  "blockId": "...",
  "locale": "en",
  "operations": [
    {
      "op": "insert_before",
      "marker": "<h2>Appendix</h2>",
      "html": "<h2>New Section</h2><p>…</p>"
    },
    {
      "op": "replace_section",
      "startMarker": "<h2>Pricing</h2>",
      "endMarker": "<h2>FAQ</h2>",
      "html": "<h2>Pricing</h2><p>Updated.</p>"
    }
  ]
}

Quand une opération échoue

• 0 correspondance — marqueur introuvable. Vérifiez la correspondance exacte au caractère près ; les espaces et l'ordre des attributs comptent.
• 2+ correspondances — le marqueur n'est pas unique. Ajoutez du HTML environnant pour lever l'ambiguïté. Les correspondances qui se chevauchent comptent ("aa" dans "aaa" compte pour 2), évitez donc les marqueurs ultra-courts.
• Le champ n'est pas une chaîne — le fieldPath ciblé résout vers un tableau ou un objet. Utilisez update_block_content pour les champs structurés.
• Blocs de layout non pris en charge — header/footer et autres blocs de layout passent par update_block_content.

patch_block_content vs update_block_content

Règle simple : si vous renvoyiez auparavant tout le HTML pour changer un seul paragraphe, utilisez patch_block_content. Sinon, restez sur update_block_content.

Dépannage

• « Workspace not found » — le token n'appartient pas au --workspace-id fourni. Les tokens sont limités à un seul workspace ; vérifiez la paire dans Workspace Settings.
• « Not authenticated » — token expiré ou révoqué. Créez-en un nouveau depuis Workspace Settings → API Tokens.
• Serveur MCP invisible dans l'éditeur — redémarrez l'éditeur après un changement de config. Dans Claude Code, consultez Settings → MCP → cmssy pour les logs de démarrage.
• Limites de débit / de plan — le serveur MCP respecte les limites du plan du workspace (pages max, stockage, tokens IA). get_workspace_info montre l'utilisation actuelle vs les limites.

Mode de réponse (0.6.0)

Depuis la 0.6.0, chaque outil d'écriture accepte un paramètre optionnel response: "minimal" | "full" (défaut "minimal"). Minimal renvoie un petit ack JSON compact (~100-200 octets) avec juste les IDs et l'état nécessaires pour enchaîner l'appel suivant — pas la ressource mutée complète.

Les sessions d'édition en masse typiques (agents touchant la même page de docs ~6 fois) brûlaient ~170 Ko de HTML renvoyé par page avant la 0.6. Le mode minimal ramène cela à ~1 Ko au total — ~95 % de réduction du coût en tokens de réponse.

Formes d'ack minimal

• Outils de pages (create_page, update_page_blocks, update_page_settings, publish_page, unpublish_page, revert_to_published, update_page_layout) — {id, slug, hasUnpublishedChanges, updatedAt} (+published pour publish/unpublish)
• Outils bloc-sur-page (add_block_to_page, update_block_content, remove_block_from_page) — {pageId, blockId, hasUnpublishedChanges, updatedAt}
• Outils de formulaires (create_form, update_form) — {id, slug, status, updatedAt}
• Outils de modèles (create_model, update_model) — {id, slug, updatedAt}
• Outils d'enregistrements (create_record, update_record) — {id, status, updatedAt}

Quand opter pour full

Passez response: "full" quand vous avez réellement besoin de la ressource mutée complète dans le même appel — p. ex. pour vérifier une transformation complète, lire un champ généré côté serveur ou déboguer. Sinon, enchaînez avec un outil de lecture (get_page / get_form / get_model / get_record).

Outils sans response

Ils renvoient déjà un ack compact et restent inchangés : patch_block_content, tous les delete_*, update_form_submission_status, import_records.

Version

Cette documentation décrit @cmssy/mcp-server 0.6.0. Le mode de réponse minimal (voir ci-dessus) est arrivé en 0.6.0 ; patch_block_content en 0.5.0 ; les versions antérieures n'ont que update_block_content. Épinglez @cmssy/mcp-server@latest dans .mcp.json pour toujours disposer des outils les plus récents.