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 préféré compatible avec l'IA.

Le serveur MCP Kontent.ai implémente le protocole 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

• get-patch-guide – 🚨 REQUIS 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
• list-content-type-usages – Listez où un type de contenu Kontent.ai est utilisé
• 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 à l'aide d'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 type 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 à l'aide d'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 à l'aide d'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. Utilisez-la 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ément de contenu Kontent.ai — chaque version linguistique (variante) d'un élément de contenu spécifique
• list-content-item-variants – Listez, filtrez, recherchez les é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 assignant 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 ; ceux 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 limitations 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 non modifié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 existante, utile pour le versionnage du contenu et la création de nouveaux brouillons à partir de 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 les éléments de contenu Kontent.ai avec leurs variantes par paires de référence élément/langue. Utilisez après list-content-item-variants pour récupérer les données complètes 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 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. Utilisez pour : 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 à l'aide d'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 (inclut 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 à l'aide d'opérations de remplacement (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 à l'aide d'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 un canal
• patch-space – Corrigez l'espace Kontent.ai à l'aide d'opérations de remplacement
• delete-space – Supprimez l'espace Kontent.ai

Gestion des rôles

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

Gestion des flux de travail

• list-workflows – Obtenez 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éez un nouveau flux de travail Kontent.ai avec des étapes, transitions, portées et autorisations de rôle personnalisées
• update-workflow – Mettez à jour un flux de travail Kontent.ai existant par ID. Modifiez les étapes, transitions, portées et autorisations de rôle. Impossible de supprimer les étapes en cours d'utilisation
• delete-workflow – Supprimez 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 – Changez l'étape du flux de travail d'une variante d'élément de contenu dans Kontent.ai. Cette opération déplace une variante vers une autre étape du flux de travail, permettant la gestion du cycle de vie du contenu, comme passer du brouillon à la révision, de la révision à 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 la planifier pour une date et 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 de diffusion), soit la planifier pour une date et 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 flux de travail précédente, permettant d'autres modifications

⚙️ Configuration

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

Mode monolocataire (STDIO)

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

Mode multilocataire (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 d'autorisation : 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'informations d'identification.

KONTENT_API_KEY et KONTENT_ENVIRONMENT_ID sont ignorés sur ce transport, même s'ils sont définis dans l'environnement du serveur. Chaque requête doit porter ses propres informations d'identification ; une requête sans celles-ci est rejetée plutôt que servie avec celles du serveur.

🔒 Sécurité

Injection indirecte d'invites

Le contenu renvoyé par ce serveur (par exemple, un élément écrit par un éditeur) peut contenir du texte qu'un LLM connecté interprète comme des instructions — injection indirecte d'invite. Un agent détourné pourrait être orienté vers des appels d'outils destructeurs (supprimer / dépublié / é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 résoudre de manière fiable en transformant le contenu qu'il renvoie. La défense est donc en couches :

• Utilisez une clé API de gestion à privilèges minimaux. Le serveur agit avec la clé qui lui est fournie. Avec une clé en lecture seule, l'appel destructeur d'un agent détourné échoue simplement à la limite 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 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é capable d'écrire.
• Ajoutez une barrière côté client si votre client le prend en charge. Certains clients (par exemple, les hooks Claude Code) vous permettent de demander une confirmation de manière déterministe avant qu'un outil destructeur ne s'exécute, indépendamment du modèle. Cela est configuré localement ; un serveur ne peut pas l'imposer.

Ce sont des indications, 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-locataire)

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

Commencez par démarrer 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 l'ID de votre 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'erreurs
  • app.ts - Fabrique d'applications Express pour le transport HTTP Streamable
  • 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 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 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. Augmentez la version à l'aide de 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 demande d'extraction
3. Fusionnez la demande d'extraction
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 flux de travail automatisé qui publie sur npm et le registre MCP GitHub

Licence

MIT