Servidor MCP de Contentful

Una implementación de servidor MCP que se integra con la API de administración de contenido de Contentful, proporcionando capacidades integrales de administración de contenido.

• Tenga en cuenta *; si no está interesado en el código y solo desea usar este MCP en Claude Desktop (o cualquier otra herramienta que pueda usar servidores MCP), no tiene que clonar este repositorio, simplemente puede configurarlo en Claude Desktop, consulte la sección "Uso con Claude Desktop" para obtener instrucciones sobre cómo instalarlo.

Características

• Gestión de contenido : Operaciones CRUD completas para entradas y activos

• Gestión de espacios : crear, actualizar y gestionar espacios y entornos

• Tipos de contenido : Administrar definiciones de tipos de contenido

• Localización : Compatibilidad con múltiples configuraciones regionales

• Publicación : Controlar el flujo de trabajo de publicación de contenido

• Operaciones masivas : ejecute publicaciones, cancelaciones de publicaciones y validaciones masivas en múltiples entradas y activos

• Paginación inteligente : las operaciones de lista devuelven un máximo de 3 elementos por solicitud para evitar el desbordamiento de la ventana de contexto, con soporte de paginación integrado

Paginación

Para evitar el desbordamiento de la ventana de contexto en los LLM, las operaciones de lista (como search_entries y list_assets) se limitan a 3 elementos por solicitud. Cada respuesta incluye:

• Número total de artículos disponibles

• Página actual de artículos (máximo 3)

• Número de artículos restantes

• Saltar valor para la página siguiente

• Mensaje que solicita al LLM que ofrezca recuperar más elementos

Este sistema de paginación permite al LLM gestionar de manera eficiente grandes conjuntos de datos manteniendo los límites de la ventana de contexto.

Operaciones a granel

La función de operaciones masivas proporciona una gestión eficiente de varios elementos de contenido simultáneamente:

• Procesamiento asincrónico : las operaciones se ejecutan de forma asincrónica y proporcionan actualizaciones de estado

• Gestión eficiente de contenido : procese múltiples entradas o activos en una sola llamada API

• Seguimiento del estado : supervise el progreso con recuentos de éxitos y fracasos

• Optimización de recursos : reduzca las llamadas a la API y mejore el rendimiento de las operaciones por lotes

Estas herramientas de operación masiva son ideales para migraciones de contenido, actualizaciones masivas o flujos de trabajo de publicación por lotes.

Herramientas

Gestión de entradas

• search_entries : busca entradas utilizando parámetros de consulta

• create_entry : Crea nuevas entradas

• get_entry : Recuperar entradas existentes

• update_entry : Actualizar campos de entrada

• delete_entry : Eliminar entradas

• publish_entry : Publicar entradas

• unpublish_entry : Anular la publicación de entradas

Operaciones a granel

• bulk_publish : Publica varias entradas y recursos en una sola operación. Acepta un conjunto de entidades (entradas y recursos) y procesa su publicación por lotes.

• bulk_unpublish : Anula la publicación de varias entradas y recursos en una sola operación. Similar a bulk_publish, pero elimina el contenido de la API de entrega.

• bulk_validate : Valida múltiples entradas para verificar la consistencia del contenido, las referencias y los campos obligatorios. Devuelve los resultados de la validación sin modificar el contenido.

Gestión de activos

• list_assets : Lista de activos con paginación (3 elementos por página)

• upload_asset : Cargar nuevos activos con metadatos

• get_asset : recupera detalles e información del activo

• update_asset : Actualizar metadatos y archivos de activos

• delete_asset : Eliminar activos del espacio

• publish_asset : Publicar activos en la API de entrega

• unpublish_asset : Anular la publicación de activos de la API de entrega

Gestión del espacio y el medio ambiente

• list_spaces : Lista de espacios disponibles

• get_space : Obtener detalles del espacio

• list_environments : Lista de entornos en un espacio

• create_environment : Crear nuevo entorno

• delete_environment : Eliminar entorno

Gestión de tipos de contenido

• list_content_types : Lista de tipos de contenido disponibles

• get_content_type : Obtener detalles del tipo de contenido

• create_content_type : Crea un nuevo tipo de contenido

• update_content_type : Actualizar el tipo de contenido

• delete_content_type : Eliminar el tipo de contenido

• publish_content_type : Publicar un tipo de contenido

Herramientas de desarrollo

Inspector de MCP

El proyecto incluye una herramienta MCP Inspector que ayuda con el desarrollo y la depuración:

• Modo de inspección : ejecute npm run inspect para iniciar el inspector. Puede abrirlo yendo a http://localhost:5173

• Modo de observación : use npm run inspect:watch para reiniciar automáticamente el inspector cuando cambien los archivos

• Interfaz visual : el inspector proporciona una interfaz web para probar y depurar herramientas MCP

• Pruebas en tiempo real : Pruebe las herramientas y vea sus respuestas inmediatamente

• Pruebas de operaciones masivas : pruebe y supervise las operaciones masivas con comentarios visuales sobre el progreso y los resultados.

El proyecto también contiene un comando npm run dev que reconstruye y recarga el servidor MCP en cada cambio.

Configuración

Prerrequisitos

1. Crea una cuenta Contentful en Contentful

2. Genere un token de API de gestión de contenido desde la configuración de su cuenta

Variables de entorno

Estas variables también se pueden configurar como argumentos.

• CONTENTFUL_HOST / --host : Punto final de la API de administración de Contentful (el valor predeterminado es https://api.contentful.com )

• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token : Su token de API de administración de contenido

• ENABLE_HTTP_SERVER / --http : Establézcalo en "verdadero" para habilitar el modo HTTP/SSE

• HTTP_PORT / --port : Puerto para el servidor HTTP (predeterminado: 3000)

• HTTP_HOST / --http-host : Host para el servidor HTTP (predeterminado: localhost)

Alcance del espacio y el medio ambiente

Puede definir el alcance de spaceId y EnvironmentId para garantizar que el LLM solo realice operaciones en los ID de espacio/entorno definidos. Esto se hace principalmente para dar soporte a los agentes que operan en espacios específicos. Si se configuran las variables de entorno SPACE_ID y ENVIRONMENT_ID , las herramientas no informarán que necesitan estos valores y los controladores usarán las variables de entorno para realizar operaciones de CMA. También perderá el acceso a las herramientas del controlador de espacio, ya que estas herramientas se encuentran en diferentes espacios. También puede agregar SPACE_ID y ENVIRONMENT_ID mediante los argumentos --space-id y --environment-id

Uso de la identidad de la aplicación

En lugar de proporcionar un token de administración, también puede usar App Identity para gestionar la autenticación. Deberá configurar e instalar una aplicación Contentful y configurar los siguientes parámetros al llamar al servidor MCP:

• --app-id = el Id. de la aplicación que proporciona el Apptoken

• --private-key = la clave privada que creó en la interfaz de usuario con su aplicación, vinculada a app_id

• --space-id = el spaceId en el que está instalada la aplicación

• --environment-id = el environmentId (dentro del espacio) en el que está instalada la aplicación.

Con estos valores, el servidor MCP solicitará un AppToken temporal para realizar operaciones de contenido en el espacio/ID de entorno definido. Esto resulta especialmente útil al usar este servidor MCP en sistemas backend que actúan como clientes MCP (como agentes de chat).

Uso con Claude Desktop

No necesitas clonar este repositorio para usar este MCP, simplemente puedes agregarlo a tu claude_desktop_config.json :

Agregue o edite ~/Library/Application Support/Claude/claude_desktop_config.json y agregue las siguientes líneas:

Si su MCPClient no admite la configuración de variables de entorno, también puede configurar el token de administración utilizando un argumento como este:

Instalación mediante herrería

Para instalar Contentful Management Server para Claude Desktop automáticamente a través de Smithery :

Desarrollo y uso del escritorio Claude

Si quieres contribuir y probar lo que Claude hace con tus contribuciones;

• Ejecute npm run dev , esto iniciará el observador que reconstruye el servidor MCP en cada cambio

• actualice claude_desktop_config.json para hacer referencia al proyecto directamente, es decir;

Esto le permitirá probar cualquier modificación en el servidor MCP con Claude directamente, sin embargo; si agrega nuevas herramientas/recursos necesitará reiniciar Claude Desktop

Modos de transporte

El servidor MCP admite dos modos de transporte:

Transporte de stdio

El modo de transporte predeterminado utiliza flujos de entrada/salida estándar para la comunicación. Esto es ideal para la integración con clientes MCP compatibles con el transporte stdio, como Claude Desktop.

Para utilizar el modo stdio, simplemente ejecute el servidor sin el indicador --http :

Transporte HTTP Streamable

El servidor también admite el transporte StreamableHTTP, tal como se define en el protocolo MCP. Este modo es útil para integraciones web o al ejecutar el servidor como un servicio independiente.

Para utilizar el modo StreamableHTTP, ejecute con el indicador --http :

Detalles de StreamableHTTP

• Utiliza el transporte oficial MCP StreamableHTTP

• Admite operaciones del protocolo MCP estándar

• Incluye gestión de sesiones para mantener el estado.

• Maneja adecuadamente los patrones de inicialización/notificación

• Compatible con clientes MCP estándar

• Reemplaza el transporte SSE obsoleto con el enfoque moderno

La implementación sigue la especificación del protocolo MCP estándar, lo que permite que cualquier cliente MCP se conecte al servidor sin un manejo especial.

Manejo de errores

El servidor implementa un manejo integral de errores para:

• Errores de autenticación

• Limitación de velocidad

• Solicitudes no válidas

• Problemas de red

• Errores específicos de la API

Licencia

Licencia MIT

Letra pequeña

Este servidor MCP permite a Claude (u otros agentes que puedan consumir recursos MCP) actualizar y eliminar contenido, espacios y modelos de contenido. ¡Así que asegúrese de lo que permite a Claude hacer con sus espacios Contentful!

Este servidor MCP no cuenta con soporte oficial de Contentful (aún)