Kontent.ai

Serveur MCP Kontent.ai

Transformez vos opérations de contenu avec des outils alimentés par l'IA pour Kontent.ai. Créez, gérez et explorez votre contenu structuré via 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 opérationnels 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. Une clé API de gestion - Créez une clé avec les autorisations appropriées.
4. Un 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 patch

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

Gestion des types de contenu

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

Gestion des snippets de type de contenu

• get-content-type-snippet – Obtenir un snippet de type de contenu Kontent.ai par ID
• list-content-type-snippets – Obtenir tous les snippets de type de contenu Kontent.ai
• create-content-type-snippet – Créer un nouveau snippet de type de contenu Kontent.ai
• patch-content-type-snippet – Mettre à jour un snippet de type de contenu Kontent.ai existant par ID en utilisant des opérations de patch (move, addInto, remove, replace)
• delete-content-type-snippet – Supprimer un snippet de type de contenu Kontent.ai par ID

Gestion des taxonomies

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

Gestion des éléments de contenu

• get-content-item – Obtenir un élément de contenu Kontent.ai par ID
• get-content-item-variant – Récupérer une variante d'élément de contenu Kontent.ai (version linguistique/traduction). Renvoie la version actuelle — brouillon s'il en existe un, sinon publiée
• get-published-content-item-variant-version – Récupérer 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 direct)
• get-content-item-translations – Obtenir toutes les traductions d'un élément de contenu Kontent.ai — chaque version linguistique (variante) d'un élément de contenu spécifique
• list-content-item-variants – Lister, filtrer, rechercher des éléments de contenu Kontent.ai avec leurs variantes (versions linguistiques/traductions)
• create-content-item – Créer un nouvel élément de contenu Kontent.ai (crée le conteneur uniquement, utilisez create-content-item-variant pour ajouter des versions linguistiques/traductions)
• update-content-item – Mettre à jour un élément de contenu Kontent.ai existant par ID. L'élément de contenu doit déjà exister - cet outil ne créera pas de nouveaux éléments
• delete-content-item – Supprimer un élément de contenu Kontent.ai par ID
• create-content-item-variant – Créer une variante d'élément de contenu Kontent.ai en attribuant l'utilisateur actuel comme contributeur. Les valeurs des éléments doivent respecter les limitations et directives définies dans le type de contenu. Envoyez uniquement les éléments que vous souhaitez définir ; les éléments omis sont initialisés vides
• update-content-item-variant – Mettre à jour une variante d'élément de contenu Kontent.ai d'un élément de contenu. Les valeurs des éléments doivent respecter les limitations et directives définies dans le type de contenu. Envoyez uniquement les éléments que vous souhaitez modifier — les éléments omis ne sont pas modifiés. Pour les éléments de texte enrichi avec des composants, soumettez l'élément complet (valeur plus le tableau complet des composants, y compris les composants non modifiés)
• create-new-content-item-variant-version – Créer une nouvelle version d'une 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 de contenu et la création de nouveaux brouillons à partir de contenu publié
• delete-content-item-variant – Supprimer une variante d'élément de contenu Kontent.ai
• bulk-get-content-item-variants – Obtenir en masse des éléments de contenu Kontent.ai avec leurs variantes par paires de référence élément et langue. À utiliser après list-content-item-variants pour récupérer les données complètes de paires élément+langue spécifiques. Les éléments sans variante dans la langue demandée sont renvoyés sans la propriété de variante. Renvoie des résultats paginés avec un jeton de continuation
• search-content-item-variants – Recherche sémantique alimenté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 – Obtenir une ressource Kontent.ai spécifique par ID
• list-assets – Obtenir toutes les ressources Kontent.ai
• update-asset – Mettre à jour une ressource Kontent.ai par ID

Gestion des dossiers de ressources

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

Gestion des langues

• list-languages – Obtenir toutes les langues Kontent.ai (inclut les langues actives et inactives - vérifiez la propriété is_active)
• create-language – Créer une nouvelle langue Kontent.ai (les langues sont toujours créées comme actives)
• patch-language – Mettre à jour une 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 – Obtenir 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 – Mettre à jour les collections Kontent.ai en utilisant des opérations de patch (addInto pour ajouter de nouvelles collections, move pour réorganiser, remove pour supprimer des collections vides, replace pour renommer)

Gestion des espaces

• list-spaces – Obtenir tous les espaces Kontent.ai
• create-space – Créer un nouvel espace Kontent.ai pour gérer un site web ou un canal
• patch-space – Modifier un espace Kontent.ai en utilisant des opérations replace
• delete-space – Supprimer un espace Kontent.ai

Gestion des rôles

• list-roles – Obtenir tous les rôles Kontent.ai. Nécessite un plan Enterprise ou Flex avec la permission "Gérer les rôles personnalisés"

Gestion des flux de travail

• list-workflows – Obtenir tous les flux de travail Kontent.ai. Les flux de travail définissent les étapes du cycle de vie du contenu et les transitions entre elles
• create-workflow – Créer un nouveau flux de travail Kontent.ai avec des étapes, transitions, portées et permissions de rôle personnalisées
• update-workflow – Mettre à jour un flux de travail Kontent.ai existant par ID. Modifier les étapes, transitions, portées et permissions de rôle. Impossible de supprimer les étapes en cours d'utilisation
• delete-workflow – Supprimer un flux de travail Kontent.ai par ID. Le flux de travail ne doit pas être utilisé par des éléments de contenu
• change-content-item-variant-workflow-step – Changer l'étape du flux de travail 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 étape différente du flux de travail, permettant la gestion du cycle de vie du contenu comme le passage de brouillon à révision, de révision à publié, etc.
• publish-content-item-variant – Publier ou planifier la publication d'une variante d'élément de contenu dans Kontent.ai. Cette opération peut soit publier immédiatement la variante, soit la planifier pour publication à une date et heure future spécifique avec une spécification optionnelle de fuseau horaire
• unpublish-content-item-variant – Dépublier ou planifier 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 la planifier pour dépublication à une date et heure future spécifique avec une spécification optionnelle de fuseau horaire

⚙️ Configuration

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

Mode mono-tenant (STDIO)

Configurez les informations d'identification via les 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 le jeton Bearer dans l'en-tête Authorization : Authorization: Bearer <api-key>

Cela permet à une seule instance de serveur de gérer les requêtes pour plusieurs environnements Kontent.ai sans nécessiter de variables d'environnement 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 multicouche :

• Utilisez une clé API de gestion avec le moindre privilège. 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 à la frontière de l’API — le contrôle le plus fort, car il tient indépendamment du 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 seule 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 surveillance avec une clé disposant de droits d’écriture.
• Ajoutez une barrière côté client si votre client le permet. Certains clients (par exemple, les hooks Claude Code) vous permettent de demander confirmation de manière déterministe avant l’exécution d’un outil destructeur, indépendamment du modèle. Cela se configure localement ; un serveur ne peut pas l’imposer.

Ce sont des conseils, pas des garanties. Signalez les problèmes de sécurité de manière privée à [email protected].

🚀 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 diffusable (multi-tenant)

Le transport HTTP diffusable dessert plusieurs environnements Kontent.ai à partir d’une seule instance de serveur. Chaque requête fournit les informations d’identification 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 standardisée des erreurs pour les outils MCP
    • throwError.ts - Utilitaire générique de levée d’erreur
  • server.ts - Configuration principale du serveur et enregistrement des outils
  • bin.ts - Point d’entrée unique gérant les deux types de transport

🔍 Débogage

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

Licence

MIT