Kontent.ai

Kontent.ai MCP Server

Transforma tus operaciones de contenido con herramientas impulsadas por IA para Kontent.ai. Crea, gestiona y explora tu contenido estructurado mediante conversaciones en lenguaje natural en tu editor favorito con capacidades de IA.

El servidor MCP de Kontent.ai implementa el Protocolo de Contexto de Modelo (Model Context Protocol) para conectar tus proyectos de Kontent.ai con herramientas de IA como Claude, Cursor y VS Code. Permite que los modelos de IA comprendan tu estructura de contenido y realicen operaciones mediante instrucciones en lenguaje natural.

✨ Características principales

• 🚀 Prototipado rápido: Transforma tus diagramas en modelos de contenido funcionales en segundos
• 📈 Visualización de datos: Visualiza tu modelo de contenido en cualquier formato que desees

Tabla de contenidos

• ✨ Características principales
• 🔌 Inicio rápido
• 🛠️ Herramientas disponibles
• ⚙️ Configuración
• 🔒 Seguridad
• 🚀 Opciones de transporte
• 💻 Desarrollo
  • 🛠 Instalación local
  • 📂 Estructura del proyecto
  • 🔍 Depuración
  • 📦 Proceso de publicación
• Licencia

🔌 Inicio rápido

🔑 Requisitos previos

Antes de poder usar el servidor MCP, necesitas:

1. Una cuenta de Kontent.ai - Regístrate si no tienes una cuenta.
2. Un proyecto - Crea un proyecto con el que trabajar.
3. Clave de API de gestión - Crea una clave con los permisos adecuados.
4. ID de entorno - Obtén tu ID de entorno.

🛠 Opciones de configuración

Puedes ejecutar el servidor MCP de Kontent.ai con npx:

Transporte STDIO

npx @kontent-ai/mcp-server@latest stdio

Transporte HTTP transmisible

npx @kontent-ai/mcp-server@latest shttp

🛠️ Herramientas disponibles

Guía de operaciones de parcheo

• get-patch-guide – 🚨 REQUERIDO antes de cualquier operación de parcheo. Obtén la guía de operaciones de parcheo para Kontent.ai por tipo de entidad

Gestión de tipos de contenido

• get-content-type – Obtén el tipo de contenido de Kontent.ai por ID
• list-content-types – Obtén todos los tipos de contenido de Kontent.ai
• create-content-type – Crea un nuevo tipo de contenido de Kontent.ai
• patch-content-type – Actualiza un tipo de contenido existente de Kontent.ai por codename usando operaciones de parcheo (move, addInto, remove, replace)
• delete-content-type – Elimina un tipo de contenido de Kontent.ai por ID

Gestión de snippets de tipos de contenido

• get-content-type-snippet – Obtén el snippet de tipo de contenido de Kontent.ai por ID
• list-content-type-snippets – Obtén todos los snippets de tipos de contenido de Kontent.ai
• create-content-type-snippet – Crea un nuevo snippet de tipo de contenido de Kontent.ai
• patch-content-type-snippet – Actualiza un snippet de tipo de contenido existente de Kontent.ai por ID usando operaciones de parcheo (move, addInto, remove, replace)
• delete-content-type-snippet – Elimina un snippet de tipo de contenido de Kontent.ai por ID

Gestión de taxonomías

• get-taxonomy-group – Obtén el grupo de taxonomía de Kontent.ai por ID
• list-taxonomy-groups – Obtén todos los grupos de taxonomía de Kontent.ai
• create-taxonomy-group – Crea un nuevo grupo de taxonomía de Kontent.ai
• patch-taxonomy-group – Actualiza el grupo de taxonomía de Kontent.ai usando operaciones de parcheo (addInto, move, remove, replace)
• delete-taxonomy-group – Elimina el grupo de taxonomía de Kontent.ai por ID

Gestión de elementos de contenido

• get-content-item – Obtén el elemento de contenido de Kontent.ai por ID
• get-content-item-variant – Recupera la variante de elemento de contenido de Kontent.ai (versión de idioma/traducción). Devuelve la versión actual: borrador si existe, de lo contrario la publicada
• get-published-content-item-variant-version – Recupera la versión publicada de una variante de elemento de contenido de Kontent.ai. Úsalo cuando exista una versión de borrador más reciente pero necesites el contenido actualmente publicado (en vivo)
• get-content-item-translations – Obtén todas las traducciones de elementos de contenido de Kontent.ai: cada versión de idioma (variante) de un elemento de contenido específico
• list-content-item-variants – Lista, filtra y busca elementos de contenido de Kontent.ai con sus variantes (versiones de idioma/traducciones)
• create-content-item – Crea un nuevo elemento de contenido de Kontent.ai (solo crea el contenedor; usa create-content-item-variant para agregar versiones de idioma/traducciones)
• update-content-item – Actualiza un elemento de contenido existente de Kontent.ai por ID. El elemento de contenido debe existir: esta herramienta no crea elementos nuevos
• delete-content-item – Elimina un elemento de contenido de Kontent.ai por ID
• create-content-item-variant – Crea una variante de elemento de contenido de Kontent.ai asignando al usuario actual como colaborador. Los valores de los elementos deben cumplir las limitaciones y pautas definidas en el tipo de contenido. Envía solo los elementos que quieras definir; los omitidos se inicializan vacíos
• update-content-item-variant – Actualiza la variante de elemento de contenido de Kontent.ai de un elemento de contenido. Los valores de los elementos deben cumplir las limitaciones y pautas definidas en el tipo de contenido. Envía solo los elementos que quieras cambiar: los omitidos se dejan intactos. Para elementos de texto enriquecido con componentes, envía el elemento completo (valor más la matriz completa de componentes, incluidos los componentes que se dejan intactos)
• create-new-content-item-variant-version – Crea una nueva versión de la variante de elemento de contenido de Kontent.ai. Esta operación crea una nueva versión de una variante existente, útil para el versionado de contenido y la creación de nuevos borradores a partir de contenido publicado
• delete-content-item-variant – Elimina la variante de elemento de contenido de Kontent.ai
• bulk-get-content-item-variants – Obtiene en lote elementos de contenido de Kontent.ai con sus variantes mediante pares de referencia de elemento e idioma. Úsalo después de list-content-item-variants para recuperar los datos completos de pares específicos elemento+idioma. Los elementos sin variante en el idioma solicitado se devuelven sin la propiedad de variante. Devuelve resultados paginados con token de continuación
• search-content-item-variants – Búsqueda semántica impulsada por IA para encontrar contenido por significado y conceptos en una variante específica de elemento de contenido. Úsala para: búsquedas conceptuales cuando no conoces las palabras clave exactas. Opciones de filtrado limitadas (solo ID de variante)

Gestión de recursos

• get-asset – Obtén un recurso específico de Kontent.ai por ID
• list-assets – Obtén todos los recursos de Kontent.ai
• update-asset – Actualiza un recurso de Kontent.ai por ID

Gestión de carpetas de recursos

• list-asset-folders – Lista todas las carpetas de recursos de Kontent.ai
• patch-asset-folders – Modifica las carpetas de recursos de Kontent.ai usando operaciones de parcheo (addInto para agregar carpetas nuevas, rename para cambiar nombres, remove para eliminar carpetas)

Gestión de idiomas

• list-languages – Obtén todos los idiomas de Kontent.ai (incluye tanto activos como inactivos: consulta la propiedad is_active)
• create-language – Crea un nuevo idioma de Kontent.ai (los idiomas siempre se crean como activos)
• patch-language – Actualiza un idioma de Kontent.ai usando operaciones de reemplazo (solo se pueden modificar idiomas activos; para activar/desactivar, usa la interfaz web de Kontent.ai)

Gestión de colecciones

• list-collections – Obtén todas las colecciones de Kontent.ai. Las colecciones establecen límites para los elementos de contenido en tu entorno y ayudan a organizar el contenido por equipo, marca o proyecto
• patch-collections – Actualiza las colecciones de Kontent.ai usando operaciones de parcheo (addInto para agregar colecciones nuevas, move para reordenar, remove para eliminar colecciones vacías, replace para renombrar)

Gestión de espacios

• list-spaces – Obtén todos los espacios de Kontent.ai
• create-space – Crea un nuevo espacio de Kontent.ai para gestionar un sitio web o canal
• patch-space – Aplica parches a un espacio de Kontent.ai usando operaciones de reemplazo
• delete-space – Elimina un espacio de Kontent.ai

Gestión de roles

• list-roles – Obtén todos los roles de Kontent.ai. Requiere plan Enterprise o Flex con el permiso "Manage custom roles"

Gestión de flujos de trabajo

• list-workflows – Obtén todos los flujos de trabajo de Kontent.ai. Los flujos de trabajo definen las etapas del ciclo de vida del contenido y las transiciones entre ellas
• create-workflow – Crea un nuevo flujo de trabajo de Kontent.ai con pasos, transiciones, ámbitos y permisos de rol personalizados
• update-workflow – Actualiza un flujo de trabajo existente de Kontent.ai por ID. Modifica pasos, transiciones, ámbitos y permisos de rol. No se pueden eliminar pasos que estén en uso
• delete-workflow – Elimina un flujo de trabajo de Kontent.ai por ID. El flujo de trabajo no debe estar en uso por ningún elemento de contenido
• change-content-item-variant-workflow-step – Cambia el paso de flujo de trabajo de una variante de elemento de contenido en Kontent.ai. Esta operación mueve una variante a un paso diferente en el flujo de trabajo, lo que permite la gestión del ciclo de vida del contenido, como mover contenido de borrador a revisión, de revisión a publicado, etc.
• publish-content-item-variant – Publica o programa la publicación de una variante de elemento de contenido en Kontent.ai. Esta operación puede publicar la variante inmediatamente o programarla para una fecha y hora futuras específicas, con especificación opcional de zona horaria
• unpublish-content-item-variant – Despublica o programa la despublicación de una variante de elemento de contenido en Kontent.ai. Esta operación puede despublicar la variante inmediatamente (haciéndola no disponible a través de la API de entrega) o programarla para una fecha y hora futuras específicas, con especificación opcional de zona horaria
• cancel-scheduled-publishing-content-item-variant – Cancela la publicación programada de una variante de elemento de contenido en Kontent.ai. Esta operación revierte una variante programada para publicación a su paso de flujo de trabajo anterior, lo que permite realizar más ediciones

⚙️ Configuración

El servidor admite dos modos, cada uno vinculado a su transporte:

Modo de un solo inquilino (STDIO)

Configura las credenciales mediante variables de entorno:

Modo multiinquilino (Streamable HTTP)

Para el transporte Streamable HTTP, las credenciales se proporcionan por solicitud:

• ID de entorno como parámetro de ruta de URL: /{environmentId}/mcp
• Clave de API mediante token Bearer en el encabezado Authorization: Authorization: Bearer <api-key>

Esto permite que una única instancia del servidor gestione solicitudes para múltiples entornos de Kontent.ai sin necesidad de variables de entorno de credenciales.

🔒 Seguridad

Inyección indirecta de prompts

El contenido devuelto por este servidor (por ejemplo, un elemento escrito por un editor) puede contener texto que un LLM conectado interprete como instrucciones: inyección indirecta de prompts. Un agente comprometido podría ser dirigido a realizar llamadas destructivas a herramientas (eliminar / despublicar / sobrescribir) o a filtrar borradores no publicados. Este es un problema sin resolver en toda la industria que el servidor no puede solucionar de manera confiable transformando el contenido que devuelve, por lo que la defensa se implementa en capas:

• Usa una clave de API de gestión con privilegios mínimos. El servidor actúa con la clave que se le proporcione. Con una clave de solo lectura, la llamada destructiva de un agente comprometido simplemente falla en el límite de la API — el control más fuerte, ya que se mantiene independientemente del comportamiento del modelo.
• Mantén a un humano en el circuito. Cada herramienta lleva anotaciones MCP — las lecturas son readOnlyHint, las herramientas de solo creación son aditivas, y las herramientas que sobrescriben o eliminan datos son destructiveHint — que los clientes compatibles usan para autoaprobar lecturas y avisar antes de llamadas destructivas. Ejecuta el servidor con un cliente así y evita configuraciones de autoaprobación sin supervisión con una clave con capacidad de escritura.
• Añade una compuerta del lado del cliente si tu cliente lo admite. Algunos clientes (por ejemplo, los hooks de Claude Code) te permiten solicitar confirmación de forma determinista antes de que se ejecute una herramienta destructiva, independientemente del modelo. Esto se configura localmente; un servidor no puede imponerlo.

Estas son sugerencias, no garantías. Informa los problemas de seguridad de forma privada a security@kontent.ai.

🚀 Opciones de transporte

📟 Transporte STDIO

Para ejecutar el servidor con transporte STDIO, configura tu cliente MCP con:

{
  "kontent-ai-stdio": {
      "command": "npx",
      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
      "env": {
        "KONTENT_API_KEY": "<management-api-key>",
        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
      }
    }
}

🌊 Transporte HTTP Streamable (Multi-Tenant)

El transporte HTTP transmisible sirve múltiples entornos de Kontent.ai desde una única instancia del servidor. Cada solicitud proporciona credenciales mediante parámetros de ruta URL y autenticación Bearer.

Primero inicia el servidor:

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>"

[!IMPORTANTE] Reemplaza <environment-id> con tu ID de entorno de Kontent.ai (GUID) y <management-api-key> con tu clave.

💻 Desarrollo

🛠 Instalación local

# 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

📂 Estructura del proyecto

• src/ - Código fuente
  • tools/ - Implementaciones de herramientas MCP
  • clients/ - Configuración del cliente API de Kontent.ai
  • schemas/ - Esquemas de validación de datos
  • utils/ - Funciones utilitarias
    • errorHandler.ts - Manejo estandarizado de errores para herramientas MCP
    • throwError.ts - Utilidad genérica para lanzar errores
  • server.ts - Configuración principal del servidor y registro de herramientas
  • bin.ts - Punto de entrada único que maneja ambos tipos de transporte

🔍 Depuración

Para depurar, puedes usar el inspector MCP:

npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node path/to/build/bin.js

O usa el inspector MCP en un servidor HTTP transmisible en funcionamiento:

npx @modelcontextprotocol/inspector

Esto proporciona una interfaz web para inspeccionar y probar las herramientas disponibles.

📦 Proceso de publicación

Para publicar una nueva versión:

1. Aumenta la versión usando npm version [patch|minor|major] - esto actualiza package.json, package-lock.json, y sincroniza con server.json
2. Sube el commit a tu rama y crea una solicitud de extracción (pull request)
3. Fusiona la solicitud de extracción
4. Crea una nueva versión en GitHub con el número de versión como nombre y etiqueta, usando notas de versión autogeneradas
5. La publicación de la versión activa un flujo de trabajo automatizado que publica en npm y en el registro MCP de GitHub

Licencia

MIT