Servidor MCP Contentful

Una implementación de servidor MCP que se integra con la API de gestión de contenidos de Contentful, proporcionando capacidades completas de gestión de contenidos.

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

Características

• Gestión de contenidos: Operaciones CRUD completas para entradas y activos
• Gestión deespacios: Crea, actualiza y gestiona espacios y entornos
• Tipos de contenido: Gestión de definiciones de tipos de contenido
• Localización: Soporte para múltiples idiomas
• Publicación: Controle el flujo de trabajo de publicación de contenidos
• Operaciones masivas: Ejecute la publicación, anulación de la publicación y validación masivas en varias 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) están limitadas a 3 elementos por solicitud. Cada respuesta incluye

• Número total de elementos disponibles
• Página actual de elementos (máx. 3)
• Número de elementos restantes
• Valor de salto para la página siguiente
• Mensaje indicando al LLM que ofrezca la recuperación de más elementos

Este sistema de paginación permite a la LLM manejar eficazmente grandes conjuntos de datos manteniendo los límites de la ventana contextual.

Operaciones masivas

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

• Procesamiento asíncrono: Las operaciones se ejecutan de forma asíncrona y proporcionan actualizaciones de estado
• Gestión eficaz de contenidos: Procese múltiples entradas o activos en una sola llamada a la 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 operaciones por lotes son ideales para migraciones de contenidos, actualizaciones masivas o flujos de trabajo de publicación por lotes.

Herramientas

Gestión de entradas

• search_entries: Búsqueda de entradas mediante parámetros de consulta
• create_entry: Crear nuevas entradas
• get_entry: Recuperar entradas existentes
• update_entry: Actualizar campos de entrada
• delete_entry: Eliminar entradas
• publicar_entrada: Publicar entradas
• unpublish_entry: Despublicar entradas

Operaciones masivas

• bulk_publish: Publica múltiples entradas y activos en una sola operación. Acepta una matriz de entidades (entradas y activos) y procesa su publicación como un lote.
• bulk_unpublish: Anula la publicación de varias entradas y activos en una sola operación. Similar a bulk_publish pero elimina el contenido de la API de entrega.
• bulk_validate: valida varias entradas para comprobar la coherencia 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 activos con paginación (3 elementos por página)
• upload_asset: Subir nuevos activos con metadatos
• get_asset: Recuperar detalles e información de activos
• 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 de espacios y entornos

• list_spaces: Listar espacios disponibles
• get_space: Obtener detalles del espacio
• list_environments: Lista los entornos de un espacio
• create_environment: Crear nuevo entorno
• eliminar_entorno: Eliminar entorno

Gestión de tipos de contenido

• list_content_types: Listar los tipos de contenido disponibles
• get_content_type: Obtener detalles del tipo de contenido
• create_content_type: Crear un nuevo tipo de contenido
• update_content_type: Actualizar tipo de contenido
• delete_content_type: Eliminar tipo de contenido
• publicar_tipo_contenido: Publicar un tipo de contenido

Herramientas de desarrollo

Inspector MCP

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

• Modo Inspección: Ejecuta npm run inspect para iniciar el inspector, puedes abrir el inspector entrando en http://localhost:5173
• Modo Watch: Utilice npm run inspect:watch para reiniciar automáticamente el inspector cuando los archivos cambian
• Interfaz visual: El inspector proporciona una interfaz web para probar y depurar las herramientas MCP
• Pruebas en tiempo real: Pruebe herramientas y vea sus respuestas inmediatamente
• Pruebas deoperaciones masivas: Pruebe y supervise operaciones masivas con información visual 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

Requisitos previos

1. Crear una cuenta Contentful en Contentful
2. Generar un token de la API de gestión de contenidos a partir de la configuración de la cuenta

Variables de entorno

Estas variables también se pueden establecer como argumentos

• CONTENTFUL_HOST / --host: Contentful Management API Endpoint (por defecto https://api.contentful.com)
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Su token de la API de gestión de contenidos
• ENABLE_HTTP_SERVER / --http: Establézcalo como "true" para habilitar el modo HTTP/SSE
• HTTP_PORT / --port: Puerto para el servidor HTTP (por defecto: 3000)
• HTTP_HOST / --http-host: Host para el servidor HTTP (por defecto: localhost)

Alcance de espacio y entorno

Puedes delimitar el spaceId y el EnvironmentId para asegurarte de que el LLM sólo realizará operaciones en los ID de espacio/entorno definidos. Esto es principalmente para dar soporte a agentes que deben operar dentro de espacios específicos. Si tanto SPACE_ID como ENVIRONMENT_ID están configurados, las herramientas no informarán de la necesidad de estos valores y los manejadores utilizarán las variables de entorno para realizar operaciones CMA. También perderás el acceso a las herramientas en el manejador de espacio, ya que estas herramientas están en todos los espacios. También puedes añadir SPACE_ID y ENVIRONMENT_ID utilizando los argumentos --space-id y --environment-id

Uso de App Identity

En lugar de proporcionar un token de gestión, también puede utilizar App Identitypara gestionar la autenticación. Tendría que configurar e instalar una aplicación Contentful y establecer 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 creaste en la interfaz de usuario con tu app, 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/entorno-id definido. Esto es especialmente útil cuando se utiliza este servidor MCP en sistemas backend que actúan como cliente MCP (como agentes de chat)

Uso con Claude Desktop

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

Añade o edita ~/Library/Application Support/Claude/claude_desktop_config.json y añade las siguientes líneas:

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

Si tu MCPClient no soporta establecer variables de entorno también puedes establecer el token de gestión usando un argumento como este:

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

Instalación a través de Smithery

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

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

Desarrollar y utilizar Claude desktop

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

• ejecuta npm run dev, esto iniciará el vigilante que reconstruye el servidor MCP en cada cambio
• actualiza claude_desktop_config.json para hacer referencia al proyecto directamente, es decir

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

Esto te permitirá probar cualquier modificación en el servidor MCP con Claude directamente, sin embargo; si añades nuevas herramientas/recursos necesitarás reiniciar Claude Desktop

Modos de transporte

El servidor MCP soporta dos modos de transporte:

transporte stdio

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

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

npx -y contentful-mcp --management-token YOUR_TOKEN # o alternativamente npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

Transporte StreamableHTTP

El servidor también soporta el transporte StreamableHTTP definido en el protocolo MCP. Este modo es útil para integraciones basadas en web o cuando se ejecuta el servidor como un servicio independiente.

Para utilizar el modo StreamableHTTP, ejecútelo con el indicador --http:

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

Detalles de StreamableHTTP

• Utiliza el transporte oficial MCP StreamableHTTP
• Soporta las operaciones estándar del protocolo MCP
• Incluye gestión de sesiones para mantener el estado
• Maneja correctamente los patrones de inicialización/notificación
• Compatible con clientes MCP estándar
• Sustituye el transporte SSE obsoleto por el enfoque moderno

La implementación sigue la especificación estándar del protocolo MCP, permitiendo a cualquier cliente MCP conectarse al servidor sin necesidad de un manejo especial.

Gestión de errores

El servidor implementa un completo tratamiento de errores para:

• Fallos de autenticación
• Limitación de velocidad
• Peticiones no válidas
• Problemas de red
• Errores específicos de la API

Licencia

Licencia MIT

Impresión

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

Este servidor MCP no está soportado oficialmente por Contentful (todavía)