Kontent.ai

Serveur MCP Kontent.ai

Transformez vos opérations de contenu avec des outils propulsés par l'IA pour Kontent.ai. Créez, gérez et explorez votre contenu structuré grâce à des conversations en langage naturel dans votre éditeur compatible IA préféré.

Le serveur MCP Kontent.ai implémente le Model Context Protocol pour connecter vos projets Kontent.ai à des outils d'IA comme Claude, Cursor et VS Code. Il permet aux modèles d'IA de comprendre votre structure de contenu et d'effectuer des opérations via des instructions en langage naturel.

✨ Fonctionnalités clés

• 🚀 Prototypage rapide : Transformez vos diagrammes en modèles de contenu fonctionnels en quelques secondes
• 📈 Visualisation des données : Visualisez votre modèle de contenu dans le format de votre choix

Table des matières

• ✨ Fonctionnalités clés
• 🔌 Démarrage rapide
• 🛠️ Outils disponibles
• ⚙️ Configuration
• 🔒 Sécurité
• 🚀 Options de transport
• 💻 Développement
  • 🛠 Installation locale
  • 📂 Structure du projet
  • 🔍 Débogage
  • 📦 Processus de publication
• Licence

🔌 Démarrage rapide

🔑 Prérequis

Avant de pouvoir utiliser le serveur MCP, vous avez besoin de :

1. Un compte Kontent.ai - Inscrivez-vous si vous n'avez pas de compte.
2. Un projet - Créez un projet avec lequel travailler.
3. Clé API de gestion - Créez une clé avec les autorisations appropriées.
4. ID d'environnement - Obtenez votre ID d'environnement.

🛠 Options de configuration

Vous pouvez exécuter le serveur MCP Kontent.ai avec npx :

Transport STDIO

npx @kontent-ai/mcp-server@latest stdio

Transport HTTP Streamable

npx @kontent-ai/mcp-server@latest shttp

🛠️ Outils disponibles

Guide des opérations de correctif (patch)

• get-patch-guide – 🚨 OBLIGATOIRE avant toute opération de correctif. Obtenez le guide des opérations de correctif pour Kontent.ai par type d'entité

Gestion des types de contenu

• get-content-type – Obtenez le type de contenu Kontent.ai par ID
• list-content-types – Obtenez tous les types de contenu Kontent.ai
• create-content-type – Créez un nouveau type de contenu Kontent.ai
• patch-content-type – Mettez à jour un type de contenu Kontent.ai existant par nom de code en utilisant des opérations de correctif (move, addInto, remove, replace)
• delete-content-type – Supprimez un type de contenu Kontent.ai par ID

Gestion des extraits de type de contenu

• get-content-type-snippet – Obtenez l'extrait de type de contenu Kontent.ai par ID
• list-content-type-snippets – Obtenez tous les extraits de types de contenu Kontent.ai
• create-content-type-snippet – Créez un nouvel extrait de type de contenu Kontent.ai
• patch-content-type-snippet – Mettez à jour un extrait de type de contenu Kontent.ai existant par ID en utilisant des opérations de correctif (move, addInto, remove, replace)
• delete-content-type-snippet – Supprimez un extrait de type de contenu Kontent.ai par ID

Gestion de la taxonomie

• get-taxonomy-group – Obtenez le groupe de taxonomie Kontent.ai par ID
• list-taxonomy-groups – Obtenez tous les groupes de taxonomie Kontent.ai
• create-taxonomy-group – Créez un nouveau groupe de taxonomie Kontent.ai
• patch-taxonomy-group – Mettez à jour le groupe de taxonomie Kontent.ai en utilisant des opérations de correctif (addInto, move, remove, replace)
• delete-taxonomy-group – Supprimez le groupe de taxonomie Kontent.ai par ID

Gestion des éléments de contenu

• get-content-item – Obtenez l'élément de contenu Kontent.ai par ID
• get-content-item-variant – Récupérez la variante d'élément de contenu Kontent.ai (version linguistique/traduction). Renvoie la version actuelle — le brouillon s'il existe, sinon la version publiée
• get-published-content-item-variant-version – Récupérez la version publiée d'une variante d'élément de contenu Kontent.ai. À utiliser lorsqu'une version brouillon plus récente existe mais que vous avez besoin du contenu actuellement publié (en ligne)
• get-content-item-translations – Obtenez toutes les traductions d'éléments de contenu Kontent.ai — chaque version linguistique (variante) d'un élément de contenu spécifique
• list-content-item-variants – Listez, filtrez et recherchez des éléments de contenu Kontent.ai avec leurs variantes (versions linguistiques/traductions)
• create-content-item – Créez un nouvel élément de contenu Kontent.ai (crée uniquement le conteneur, utilisez create-content-item-variant pour ajouter des versions linguistiques/traductions)
• update-content-item – Mettez à jour un élément de contenu Kontent.ai existant par ID. L'élément de contenu doit déjà exister - cet outil ne crée pas de nouveaux éléments
• delete-content-item – Supprimez l'élément de contenu Kontent.ai par ID
• create-content-item-variant – Créez une variante d'élément de contenu Kontent.ai en désignant l'utilisateur actuel comme contributeur. Les valeurs des éléments doivent respecter les limites et directives définies dans le type de contenu. Envoyez uniquement les éléments que vous souhaitez définir ; ceux qui sont omis sont initialisés vides
• update-content-item-variant – Mettez à jour la variante d'élément de contenu Kontent.ai d'un élément de contenu. Les valeurs des éléments doivent respecter les limites et directives définies dans le type de contenu. Envoyez uniquement les éléments que vous souhaitez modifier — les éléments omis restent inchangés. Pour les éléments de texte enrichi avec composants, soumettez l'élément complet (valeur plus le tableau complet des composants, y compris les composants qui restent inchangés)
• create-new-content-item-variant-version – Créez une nouvelle version de la variante d'élément de contenu Kontent.ai. Cette opération crée une nouvelle version d'une variante d'élément de contenu existante, utile pour le versionnage du contenu et la création de nouveaux brouillons à partir du contenu publié
• delete-content-item-variant – Supprimez la variante d'élément de contenu Kontent.ai
• bulk-get-content-item-variants – Récupérez en masse des éléments de contenu Kontent.ai avec leurs variantes par paires de référence élément/langue. À utiliser après list-content-item-variants pour récupérer les données complètes du contenu pour des paires élément+langue spécifiques. Les éléments sans variante dans la langue demandée renvoient l'élément sans la propriété de variante. Renvoie des résultats paginés avec un jeton de continuation
• search-content-item-variants – Recherche sémantique propulsée par l'IA pour trouver du contenu par signification et concepts dans une variante d'élément de contenu spécifique. À utiliser pour : les recherches conceptuelles lorsque vous ne connaissez pas les mots-clés exacts. Options de filtrage limitées (ID de variante uniquement)

Gestion des ressources

• get-asset – Obtenez une ressource Kontent.ai spécifique par ID
• list-assets – Obtenez toutes les ressources Kontent.ai
• update-asset – Mettez à jour la ressource Kontent.ai par ID

Gestion des dossiers de ressources

• list-asset-folders – Listez tous les dossiers de ressources Kontent.ai
• patch-asset-folders – Modifiez les dossiers de ressources Kontent.ai en utilisant des opérations de correctif (addInto pour ajouter de nouveaux dossiers, rename pour changer les noms, remove pour supprimer des dossiers)

Gestion des langues

• list-languages – Obtenez toutes les langues Kontent.ai (comprend les langues actives et inactives - vérifiez la propriété is_active)
• create-language – Créez une nouvelle langue Kontent.ai (les langues sont toujours créées comme actives)
• patch-language – Mettez à jour la langue Kontent.ai en utilisant des opérations replace (seules les langues actives peuvent être modifiées - pour activer/désactiver, utilisez l'interface web Kontent.ai)

Gestion des collections

• list-collections – Obtenez toutes les collections Kontent.ai. Les collections définissent des limites pour les éléments de contenu dans votre environnement et aident à organiser le contenu par équipe, marque ou projet
• patch-collections – Mettez à jour les collections Kontent.ai en utilisant des opérations de correctif (addInto pour ajouter de nouvelles collections, move pour réorganiser, remove pour supprimer les collections vides, replace pour renommer)

Gestion des espaces

• list-spaces – Obtenez tous les espaces Kontent.ai
• create-space – Créez un nouvel espace Kontent.ai pour gérer un site web ou une chaîne
• patch-space – Appliquez un correctif à l'espace Kontent.ai en utilisant des opérations replace
• delete-space – Supprimez l'espace Kontent.ai

Gestion des rôles

• list-roles – Obtenez tous les rôles Kontent.ai. Nécessite un plan Enterprise ou Flex avec l'autorisation « Gérer les rôles personnalisés »

Gestion des workflows

• list-workflows – Obtenez tous les workflows Kontent.ai. Les workflows définissent les étapes du cycle de vie du contenu et les transitions entre elles
• create-workflow – Créez un nouveau workflow Kontent.ai avec des étapes personnalisées, des transitions, des portées et des autorisations de rôle
• update-workflow – Mettez à jour un workflow Kontent.ai existant par ID. Modifiez les étapes, les transitions, les portées et les autorisations de rôle. Impossible de supprimer les étapes en cours d'utilisation
• delete-workflow – Supprimez un workflow Kontent.ai par ID. Le workflow ne doit pas être utilisé par des éléments de contenu
• change-content-item-variant-workflow-step – Modifiez l'étape de workflow d'une variante d'élément de contenu dans Kontent.ai. Cette opération déplace une variante d'élément de contenu vers une autre étape du workflow, permettant la gestion du cycle de vie du contenu, comme le passage du brouillon à la relecture, de la relecture à la publication, etc.
• publish-content-item-variant – Publiez ou planifiez la publication d'une variante d'élément de contenu dans Kontent.ai. Cette opération peut soit publier immédiatement la variante, soit planifier sa publication à une date et une heure futures spécifiques avec indication facultative du fuseau horaire
• unpublish-content-item-variant – Dépubliez ou planifiez la dépublication d'une variante d'élément de contenu dans Kontent.ai. Cette opération peut soit dépublier immédiatement la variante (la rendant indisponible via l'API Delivery), soit planifier sa dépublication à une date et une heure futures spécifiques avec indication facultative du fuseau horaire
• cancel-scheduled-publishing-content-item-variant – Annulez la publication planifiée d'une variante d'élément de contenu dans Kontent.ai. Cette opération ramène une variante planifiée pour publication à son étape de workflow précédente, permettant d'autres modifications

⚙️ Configuration

Le serveur prend en charge deux modes, chacun lié à son transport :

Mode mono-tenant (STDIO)

Configurez les informations d'identification via des variables d'environnement :

Mode multi-tenant (HTTP Streamable)

Pour le transport HTTP Streamable, les informations d'identification sont fournies par requête :

• ID d'environnement comme paramètre de chemin d'URL : /{environmentId}/mcp
• Clé API via jeton Bearer dans l'en-tête Authorization : Authorization: Bearer <api-key>

Cela permet à une seule instance de serveur de traiter les requêtes pour plusieurs environnements Kontent.ai sans nécessiter de variables d'environnement d'informations d'identification.

🔒 Sécurité

Injection indirecte de prompt

Le contenu renvoyé par ce serveur (par exemple, un élément rédigé par un éditeur) peut contenir du texte qu'un LLM connecté interprète comme des instructions — injection indirecte de prompt. Un agent détourné pourrait être orienté vers des appels d'outils destructeurs (supprimer / dépublier / écraser) ou vers la fuite de brouillons non publiés. Il s'agit d'un problème non résolu à l'échelle de l'industrie que le serveur ne peut pas corriger de manière fiable en transformant le contenu qu'il renvoie, la défense est donc en couches :

• Utilisez une clé Management API à privilèges minimaux. Le serveur agit avec la clé qui lui est fournie. Avec une clé en lecture seule, un appel destructeur d'un agent compromis échoue simplement au niveau de la limite de l'API — le contrôle le plus fort, car il s'applique quel que soit le comportement du modèle.
• Gardez un humain dans la boucle. Chaque outil porte des annotations MCP — les lectures sont readOnlyHint, les outils de création uniquement sont additifs, et les outils qui écrasent ou suppriment des données sont destructiveHint — que les clients conformes utilisent pour approuver automatiquement les lectures et demander confirmation avant les appels destructeurs. Exécutez le serveur avec un tel client et évitez les configurations d'approbation automatique sans tête avec une clé pouvant écrire.
• Ajoutez une barrière côté client si votre client le prend en charge. Certains clients (par exemple, les hooks Claude Code) permettent de demander une confirmation de manière déterministe avant l'exécution d'un outil destructeur, indépendamment du modèle. Cela est configuré localement ; un serveur ne peut pas l'imposer.

Ce sont des conseils, pas des garanties. Signalez les problèmes de sécurité en privé à security@kontent.ai.

🚀 Options de transport

📟 Transport STDIO

Pour exécuter le serveur avec le transport STDIO, configurez votre client MCP avec :

{
  "kontent-ai-stdio": {
      "command": "npx",
      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
      "env": {
        "KONTENT_API_KEY": "<management-api-key>",
        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
      }
    }
}

🌊 Transport HTTP streamable (multi-tenant)

Le transport HTTP streamable dessert plusieurs environnements Kontent.ai à partir d'une seule instance de serveur. Chaque requête fournit les identifiants via les paramètres de chemin d'URL et l'authentification Bearer.

Démarrez d'abord le serveur :

npx @kontent-ai/mcp-server@latest shttp

{
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/<environment-id>/mcp",
      "headers": {
        "Authorization": "Bearer <management-api-key>"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "apiKey",
      "type": "password",
      "description": "Kontent.ai API Key"
    },
    {
      "id": "environmentId",
      "type": "text",
      "description": "Environment ID"
    }
  ],
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/${inputs.environmentId}/mcp",
      "headers": {
        "Authorization": "Bearer ${inputs.apiKey}"
      }
    }
  }
}

{
  "mcpServers": {
    "kontent-ai-multi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/<environment-id>/mcp",
        "--header",
        "Authorization: Bearer <management-api-key>"
      ]
    }
  }
}

claude mcp add --transport http kontent-ai-multi \
  "http://localhost:3001/<environment-id>/mcp" \
  --header "Authorization: Bearer <management-api-key>"

[!IMPORTANT] Remplacez <environment-id> par votre ID d'environnement Kontent.ai (GUID) et <management-api-key> par votre clé.

💻 Développement

🛠 Installation locale

# Clone the repository
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server

# Install dependencies
npm ci

# Build the project
npm run build

# Start the server
npm run start:stdio  # For STDIO transport
npm run start:shttp  # For Streamable HTTP transport

# Start the server with automatic reloading (no need to build first)
npm run dev:stdio  # For STDIO transport
npm run dev:shttp  # For Streamable HTTP transport

📂 Structure du projet

• src/ - Code source
• tools/ - Implémentations des outils MCP
• clients/ - Configuration du client API Kontent.ai
• schemas/ - Schémas de validation des données
• utils/ - Fonctions utilitaires
  • errorHandler.ts - Gestion normalisée des erreurs pour les outils MCP
  • throwError.ts - Utilitaire générique de levée d'erreurs
• server.ts - Configuration principale du serveur et enregistrement des outils
• bin.ts - Point d'entrée unique qui gère les deux types de transport

🔍 Débogage

Pour déboguer, vous pouvez utiliser l'inspecteur MCP :

npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node path/to/build/bin.js

Ou utilisez l'inspecteur MCP sur un serveur HTTP streamable en cours d'exécution :

npx @modelcontextprotocol/inspector

Cela fournit une interface web pour inspecter et tester les outils disponibles.

📦 Processus de publication

Pour publier une nouvelle version :

1. Incrémentez la version en utilisant npm version [patch|minor|major] - cela met à jour package.json, package-lock.json, et synchronise avec server.json
2. Poussez le commit vers votre branche et créez une pull request
3. Fusionnez la pull request
4. Créez une nouvelle version GitHub avec le numéro de version comme nom et tag, en utilisant les notes de version générées automatiquement
5. La publication de la version déclenche un workflow automatisé qui publie sur npm et le registre MCP GitHub

Licence

MIT