Contentful

Servidor MCP de Contentful

Aviso

¡Este es un servidor impulsado por la comunidad! Contentful ha lanzado un servidor oficial que puedes encontrar aquí

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

• Ten en cuenta *; si no te interesa el código y solo quieres usar este MCP en Claude Desktop (o cualquier otra herramienta que pueda usar servidores MCP), no tienes que clonar este repositorio, puedes configurarlo directamente en Claude Desktop; consulta 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 Comentarios: Crear, recuperar y gestionar comentarios en entradas con soporte para formatos de texto plano y texto enriquecido, incluyendo conversaciones en hilos
• Gestión de Espacios: Crear, actualizar y gestionar espacios y entornos
• Tipos de Contenido: Gestionar definiciones de tipos de contenido
• Localización: Soporte para múltiples idiomas
• Publicación: Controlar el flujo de trabajo de publicación de contenido
• Operaciones Masivas: Ejecutar publicación, despublicación y validación masiva en múltiples entradas y activos
• Paginación Inteligente: Las operaciones de listado 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 listado (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áximo 3)
• Número de elementos restantes
• Valor de salto para la siguiente página
• Mensaje que solicita al LLM ofrecer la recuperación de más elementos

Este sistema de paginación permite al LLM manejar eficientemente grandes conjuntos de datos mientras mantiene los límites de la ventana de contexto.

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 Eficiente de Contenido: Procesar múltiples entradas o activos en una sola llamada a la API
• Seguimiento de Estado: Monitorear el progreso con contadores de éxito y fallo
• Optimización de Recursos: Reducir llamadas a la API y mejorar el rendimiento para operaciones por lotes

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

Herramientas

Gestión de Entradas

• search_entries: Buscar entradas usando parámetros de consulta
• create_entry: Crear nuevas entradas
• get_entry: Recuperar entradas existentes
• update_entry: Actualizar campos de entradas
• delete_entry: Eliminar entradas
• publish_entry: Publicar entradas
• unpublish_entry: Despublicar entradas

Gestión de Comentarios

• get_comments: Recuperar comentarios para una entrada con filtrado por estado (activo, resuelto, todos)
• create_comment: Crear nuevos comentarios en entradas con soporte para formatos de texto plano y texto enriquecido. Soporta conversaciones en hilos proporcionando un ID de comentario padre para responder a comentarios existentes
• get_single_comment: Recuperar un comentario específico por su ID para una entrada
• delete_comment: Eliminar un comentario específico de una entrada
• update_comment: Actualizar comentarios existentes con nuevo contenido o cambios de estado

Comentarios en Hilos

Los comentarios soportan funcionalidad de hilos para permitir conversaciones estructuradas y trabajar alrededor del límite de 512 caracteres:

• Responder a Comentarios: Usa el parámetro parent en create_comment para responder a un comentario existente
• Conversaciones en Hilos: Construir árboles de conversación respondiendo a comentarios específicos
• Discusiones Extendidas: Trabajar alrededor del límite de 512 caracteres creando respuestas en hilos para continuar mensajes más largos
• Contexto de Conversación: Mantener contexto en discusiones organizando comentarios relacionados en hilos

Ejemplo de uso:

1. Crear un comentario principal: create_comment con entryId, body y status
2. Responder a ese comentario: create_comment con entryId, body, status y parent (el ID del comentario al que estás respondiendo)
3. Continuar el hilo: Responder a cualquier comentario en el hilo usando su ID como parent

Operaciones Masivas

• bulk_publish: Publicar múltiples entradas y activos en una sola operación. Acepta un array de entidades (entradas y activos) y procesa su publicación como un lote.
• bulk_unpublish: Despublicar múltiples entradas y activos en una sola operación. Similar a bulk_publish pero elimina contenido de la API de entrega.
• bulk_validate: Validar múltiples entradas para consistencia de contenido, referencias y campos obligatorios. Devuelve resultados de validación sin modificar contenido.

Gestión de Activos

• list_assets: Listar 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: Despublicar 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: Listar entornos en un espacio
• create_environment: Crear nuevo entorno
• delete_environment: Eliminar entorno

Gestión de Tipos de Contenido

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

Herramientas de Desarrollo

Inspector MCP

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

• Modo Inspección: Ejecuta npm run inspect para iniciar el inspector; puedes abrir el inspector yendo a http://localhost:5173
• Modo Vigilancia: Usa npm run inspect:watch para reiniciar automáticamente el inspector cuando los archivos cambien
• Interfaz Visual: El inspector proporciona una interfaz web para probar y depurar herramientas MCP
• Pruebas en Tiempo Real: Prueba herramientas y ve sus respuestas inmediatamente
• Pruebas de Operaciones Masivas: Prueba y monitorea operaciones masivas con retroalimentación visual sobre progreso y 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. Crea una cuenta de Contentful en Contentful
2. Genera un token de API de Gestión de Contenido desde la configuración de tu cuenta

Variables de Entorno

Estas variables también se pueden establecer como argumentos

• CONTENTFUL_HOST / --host: Endpoint de la API de Gestión de Contenido de Contentful (por defecto https://api.contentful.com)
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Tu token de API de Gestión de Contenido
• ENABLE_HTTP_SERVER / --http: Establecer en "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)
• DISABLE_AI_ACTIONS: Establecer en "true" para deshabilitar la obtención de Acciones de IA al inicio (útil si no tienes acceso a esta función)

Alcance de Espacio y Entorno

Puedes delimitar el spaceId y EnvironmentId para asegurar que el LLM solo realice operaciones en los IDs de espacio/entorno definidos. Esto es principalmente para soportar agentes que deben operar dentro de espacios específicos. Si ambas variables de entorno SPACE_ID y ENVIRONMENT_ID están establecidas, las herramientas no informarán que necesitan estos valores y los manejadores usarán las variables de entorno para realizar operaciones CMA. También perderás acceso a las herramientas en el manejador de espacios, ya que estas herramientas operan entre espacios. También puedes agregar SPACE_ID y ENVIRONMENT_ID usando los argumentos --space-id y --environment-id

Uso de Identidad de Aplicación

En lugar de proporcionar un token de gestión, también puedes aprovechar Identidad de Aplicación para manejar la autenticación. Tendrías que configurar e instalar una Aplicación de 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 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/entorno definido. Esto es especialmente útil cuando se usa 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:

Agrega o edita ~/Library/Application Support/Claude/claude_desktop_config.json y agrega 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",
        "<your token>",
        "--host",
        "http://api.contentful.com"
      ]
    }
  }
}

Instalación vía Smithery

Para instalar Contentful Management Server para Claude Desktop automáticamente vía Smithery:

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

Desarrollo y uso con Claude Desktop

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

• ejecuta npm run dev, esto iniciará el watcher que reconstruye el servidor MCP en cada cambio
• actualiza claude_desktop_config.json para referenciar el 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 directamente con Claude; sin embargo, si agregas 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 predeterminado usa flujos estándar de entrada/salida para la comunicación. Esto es ideal para la integración con clientes MCP que soportan transporte stdio, como Claude Desktop.

Para usar el modo stdio, simplemente ejecuta el servidor sin la bandera --http:

npx -y contentful-mcp --management-token YOUR_TOKEN
# or alternatively
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

Transporte StreamableHTTP

El servidor también soporta el transporte StreamableHTTP según lo 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 usar el modo StreamableHTTP, ejecuta con la bandera --http:

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

Detalles de StreamableHTTP

• Usa el transporte StreamableHTTP oficial de MCP
• Soporta operaciones estándar del protocolo MCP
• Incluye gestión de sesiones para mantener el estado
• Maneja adecuadamente los patrones initialize/notify
• Compatible con clientes MCP estándar
• Reemplaza el transporte SSE obsoleto con el enfoque moderno

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

Manejo de Errores

El servidor implementa manejo integral de errores para:

• Fallos de autenticación
• Limitación de velocidad
• Solicitudes invá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, eliminar contenido, espacios y modelos de contenido. ¡Así que asegúrate de saber qué permites que Claude haga con tus espacios de Contentful!

Este servidor MCP no está soportado oficialmente por Contentful (aún)