Serveur MCP Contentful

Une implémentation de serveur MCP qui s'intègre avec l'API de gestion de contenu de Contentful, fournissant des capacités complètes de gestion de contenu.

• Veuillez noter * ; si vous n'êtes pas intéressé par le code, et que vous voulez juste utiliser ce MCP dans Claude Desktop (ou tout autre outil capable d'utiliser des serveurs MCP) vous n'avez pas besoin de cloner ce repo, vous pouvez juste l'installer dans Claude desktop, référez-vous à la section "Utilisation avec Claude Desktop" pour les instructions sur la façon de l'installer.

Fonctionnalités

• Gestion du contenu: Opérations CRUD complètes pour les entrées et les actifs
• Gestion des espaces: Créer, mettre à jour et gérer les espaces et les environnements
• Types de contenu: Gestion des définitions des types de contenu
• Localisation: Prise en charge de plusieurs langues
• Publication: contrôle du flux de publication du contenu
• Opérations en masse: Exécution de la publication, de la dépublication et de la validation en masse sur plusieurs entrées et actifs
• Pagination intelligente: Les opérations de liste renvoient au maximum 3 éléments par demande pour éviter le débordement de la fenêtre contextuelle, avec prise en charge intégrée de la pagination

Pagination

Pour éviter un débordement de la fenêtre contextuelle dans les LLM, les opérations de liste (comme search_entries et list_assets) sont limitées à 3 éléments par demande. Chaque réponse comprend

• Le nombre total d'éléments disponibles
• Page actuelle d'éléments (3 au maximum)
• Le nombre d'éléments restants
• Valeur de saut pour la page suivante
• Message invitant le LLM à proposer la récupération d'autres éléments

Ce système de pagination permet au LLM de traiter efficacement de grands ensembles de données tout en respectant les limites de la fenêtre contextuelle.

Opérations en bloc

La fonction d'opérations en bloc permet une gestion efficace de plusieurs éléments de contenu simultanément :

• Traitement asynchrone: Les opérations s'exécutent de manière asynchrone et fournissent des mises à jour d'état
• Gestion efficace du contenu: Traitement de plusieurs entrées ou ressources en un seul appel API
• Suivi de l'état: Suivi de la progression avec décompte des succès et des échecs
• Optimisation des ressources: Réduction des appels d'API et amélioration des performances pour les opérations par lots

Ces outils d'opérations en masse sont idéaux pour les migrations de contenu, les mises à jour de masse ou les flux de travail de publication par lots.

Outils

Gestion des entrées

• search_entries: Recherche d'entrées à l'aide de paramètres de requête
• create_entry: Créer de nouvelles entrées
• get_entry: Récupérer les entrées existantes
• update_entry: Mettre à jour les champs de l'entrée
• delete_entry: Supprimer des entrées
• publish_entry: Publier des entrées
• unpublish_entry: Dépublier des entrées

Opérations en masse

• bulk_publish: Publier plusieurs entrées et actifs en une seule opération. Accepte un tableau d'entités (entrées et actifs) et traite leur publication en tant que lot.
• bulk_unpublish: Dépublier plusieurs entrées et ressources en une seule opération. Similaire à bulk_publish mais supprime le contenu de l'API de livraison.
• bulk_validate: valide plusieurs entrées pour vérifier la cohérence du contenu, les références et les champs obligatoires. Renvoie les résultats de la validation sans modifier le contenu.

Gestion des actifs

• list_assets: Liste des actifs avec pagination (3 éléments par page)
• upload_asset: télécharge de nouveaux actifs avec des métadonnées
• get_asset: Récupération des détails et des informations sur les actifs
• update_asset: met à jour les métadonnées et les fichiers d'un bien
• delete_asset: Supprime les biens de l'espace
• publish_asset: Publier des biens dans l'API de livraison
• unpublish_asset: Dépublier les biens de l'API de livraison

Gestion de l'espace et de l'environnement

• list_spaces: Liste des espaces disponibles
• get_space: Obtenir les détails de l'espace
• list_environments: Liste des environnements d'un espace
• create_environment: Créer un nouvel environnement
• delete_environment: Supprimer un environnement

Gestion des types de contenu

• list_content_types: Liste des types de contenu disponibles
• get_content_type: Obtenir les détails du type de contenu
• create_content_type: Création d'un nouveau type de contenu
• update_content_type: Mise à jour du type de contenu
• delete_content_type: Suppression d'un type de contenu
• publier_type_de_contenu: Publier un type de contenu

Outils de développement

Inspecteur MCP

Le projet comprend un outil MCP Inspector qui facilite le développement et le débogage :

• Mode inspection: Exécutez npm run inspect pour démarrer l'inspecteur, vous pouvez ouvrir l'inspecteur en allant sur http://localhost:5173
• Mode surveillance: Utilisez npm run inspect:watch pour redémarrer automatiquement l'inspecteur lorsque des fichiers sont modifiés
• Interface visuelle: L'inspecteur fournit une interface web pour tester et déboguer les outils MCP
• Test en temps réel: Essayer des outils et voir leurs réponses immédiatement
• Test des opérations en masse: Testez et surveillez les opérations en masse avec un retour visuel sur la progression et les résultats

Le projet contient également une commande npm run dev qui reconstruit et recharge le serveur MCP à chaque changement.

Configuration

Conditions préalables

1. Créer un compte Contentful sur Contentful
2. Générer un jeton d'API de gestion de contenu à partir des paramètres de votre compte

Variables d'environnement

Ces variables peuvent également être définies en tant qu'arguments

• CONTENTFUL_HOST / --host: Point de terminaison de l'API de gestion de Contentful ( https://api.contentful.com par défaut)
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Votre code d'accès à l'API de gestion de contenu
• ENABLE_HTTP_SERVER / --http: Mettre à "true" pour activer le mode HTTP/SSE
• HTTP_PORT / --port: Port du serveur HTTP (par défaut : 3000)
• HTTP_HOST / --http-host: Hôte du serveur HTTP (par défaut : localhost)

Portée de l'espace et de l'environnement

Vous pouvez délimiter l'espaceId et l'environnementId pour vous assurer que le LLM n'effectuera des opérations que sur les espaces/environnements définis. Si les env-vars SPACE_ID et ENVIRONMENT_ID sont toutes deux définies, les outils ne signaleront pas avoir besoin de ces valeurs et les gestionnaires utiliseront les vars d'environnement pour effectuer des opérations CMA. Vous perdrez également l'accès aux outils dans le gestionnaire d'espace, puisque ces outils sont à travers les espaces. Vous pouvez également ajouter les SPACE_ID et ENVIRONMENT_ID en utilisant les arguments --space-id et --environment-id

Utiliser l'identité de l'application

Au lieu de fournir un jeton de gestion, vous pouvez également utiliser App Identitypour gérer l'authentification. Vous devez configurer et installer une application Contentful et définir les paramètres suivants lors de l'appel au serveur MCP :

• --app-id = l'identité de l'application qui fournit l'Apptoken
• --private-key = la clé privée que vous avez créée dans l'interface utilisateur de votre application, liée à app_id
• --space-id = l'identifiant de l'espace dans lequel l'application est installée
• --environment-id = l'identifiant de l'environnement (dans l'espace) dans lequel l'application est installée.

Avec ces valeurs, le serveur MCP demandera un AppToken temporaire pour effectuer une opération de contenu dans l'espace/identifiant d'environnement défini. Ceci est particulièrement utile lors de l'utilisation de ce serveur MCP dans des systèmes backend qui agissent en tant que client MCP (comme les agents de chat)

Utilisation avec Claude Desktop

Vous n'avez pas besoin de cloner ce repo pour utiliser ce MCP, vous pouvez simplement l'ajouter à votre claude_desktop_config.json:

Ajoutez ou éditez ~/Bibliothèque/Application Support/Claude/claude_desktop_config.jsonet ajoutez les lignes suivantes :

{ "mcpServers" : { "contentful" : {"command" : "npx", "args" : ["-y", "@ivotoby/contentful-management-mcp-server"], "env" : {"CONTENTFUL_MANAGEMENT_ACCESS_TOKEN" : "<Votre token CMA>" } } } }

Si votre MCPClient ne prend pas en charge la définition de variables d'environnement, vous pouvez également définir le jeton de gestion à l'aide d'un argument comme celui-ci :

{ "mcpServers" : { "contentful" : {"command" : "npx", "args" : ["-y", "@ivotoby/contentful-management-mcp-server", "--management-token", "<votre token>", "--host", "http://api.contentful.com" ] } } }

Installation via Smithery

Pour installer Contentful Management Server pour Claude Desktop automatiquement via Smithery:

npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude

Développer et utiliser Claude Desktop

Si vous voulez contribuer et tester ce que Claude fait avec vos contributions ;

• exécutez npm run dev, cela lancera l'observateur qui reconstruit le serveur MCP à chaque changement
• mettez à jour claude_desktop_config.json pour faire référence au projet directement, c'est à dire ;

{ "mcpServers" : { "contentful" : { "command" : "node", "args" : ["/Users/ivo/workspace/contentful-mcp/bin/mcp-server.js"], "env" : {"CONTENTFUL_MANAGEMENT_ACCESS_TOKEN" : "<Your CMA Token>" } } } }

Cela vous permettra de tester toute modification du serveur MCP avec Claude directement, cependant, si vous ajoutez de nouveaux outils/ressources, vous devrez redémarrer Claude Desktop

Modes de transport

Le serveur MCP supporte deux modes de transport :

stdio Transport

Le mode de transport par défaut utilise les flux d'entrée/sortie standard pour la communication. Il est idéal pour l'intégration avec les clients MCP qui supportent le transport stdio, comme Claude Desktop.

Pour utiliser le mode stdio, il suffit d'exécuter le serveur sans l'option --http:

npx -y contentful-mcp --management-token YOUR_TOKEN # ou alternativement npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

Transport StreamableHTTP

Le serveur supporte également le transport StreamableHTTP tel que défini dans le protocole MCP. Ce mode est utile pour les intégrations basées sur le web ou lorsque le serveur fonctionne en tant que service autonome.

Pour utiliser le mode StreamableHTTP, exécutez le serveur avec l'option --http:

npx -y contentful-mcp --management-token YOUR_TOKEN --http --port 3000 # ou alternativement npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000

Détails de StreamableHTTP

• Utilise le transport officiel MCP StreamableHTTP
• Prend en charge les opérations standard du protocole MCP
• Inclut la gestion de session pour maintenir l'état
• Gère correctement les modèles d'initialisation/notification
• Compatible avec les clients MCP standard
• Remplace le transport SSE obsolète par une approche moderne

L'implémentation suit la spécification du protocole MCP standard, permettant à n'importe quel client MCP de se connecter au serveur sans traitement particulier.

Gestion des erreurs

Le serveur met en œuvre une gestion complète des erreurs pour :

• Les échecs d'authentification
• Limitation du débit
• Demandes non valides
• Problèmes de réseau
• Erreurs spécifiques à l'API

Licence

Licence MIT

Texte descriptif

Ce serveur MCP permet à Claude (ou à d'autres agents qui peuvent consommer des ressources MCP) de mettre à jour, de supprimer du contenu, des espaces et des modèles de contenu. Faites donc attention à ce que vous permettez à Claude de faire avec vos espaces Contentful !

Ce serveur MCP n'est pas (encore) officiellement supporté par Contentful