Kontent.ai

Servidor MCP de Kontent.ai

Transforma tus operaciones de contenido con herramientas impulsadas por IA para Kontent.ai. Crea, gestiona y explora tu contenido estructurado a través de conversaciones en lenguaje natural en tu editor favorito habilitado para IA.

El Servidor MCP de Kontent.ai implementa el Protocolo de Contexto de Modelo 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 Clave

• 🚀 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 Clave
• 🔌 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 para 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 Parche

• get-patch-guide – 🚨 REQUERIDO antes de cualquier operación de parche. Obtén la guía de operaciones de parche 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
• list-content-type-usages – Lista dónde se utiliza un tipo 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 nombre clave usando operaciones de parche (mover, agregarEn, eliminar, reemplazar)
• delete-content-type – Elimina un tipo de contenido de Kontent.ai por ID

Gestión de Fragmentos de Tipo de Contenido

• get-content-type-snippet – Obtén el fragmento de tipo de contenido de Kontent.ai por ID
• list-content-type-snippets – Obtén todos los fragmentos de tipo de contenido de Kontent.ai
• create-content-type-snippet – Crea un nuevo fragmento de tipo de contenido de Kontent.ai
• patch-content-type-snippet – Actualiza un fragmento de tipo de contenido existente de Kontent.ai por ID usando operaciones de parche (mover, agregarEn, eliminar, reemplazar)
• delete-content-type-snippet – Elimina un fragmento de tipo de contenido de Kontent.ai por ID

Gestión de Taxonomía

• 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 parche (agregarEn, mover, eliminar, reemplazar)
• 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 del elemento de contenido de Kontent.ai (versión de idioma/traducción). Devuelve la versión actual: borrador si existe, de lo contrario 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 del elemento 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 variantes de elemento de contenido (versiones de idioma/traducciones)
• create-content-item – Crea un nuevo elemento de contenido de Kontent.ai (crea solo 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 creará elementos nuevos
• delete-content-item – Elimina el 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 contribuyente. Los valores de los elementos deben cumplir con las limitaciones y pautas definidas en el tipo de contenido. Envía solo los elementos que deseas configurar; los omitidos se inicializan vacíos
• update-content-item-variant – Actualiza la variante del elemento de contenido de Kontent.ai. Los valores de los elementos deben cumplir con las limitaciones y pautas definidas en el tipo de contenido. Envía solo los elementos que deseas cambiar: los omitidos no se modifican. Para elementos de texto enriquecido con componentes, envía el elemento completo (valor más la matriz completa de componentes, incluidos los componentes que no se modifican)
• create-new-content-item-variant-version – Crea una nueva versión de la variante del elemento de contenido de Kontent.ai. Esta operación crea una nueva versión de una variante existente, útil para el control de versiones de contenido y la creación de nuevos borradores a partir de contenido publicado
• delete-content-item-variant – Elimina la variante del elemento de contenido de Kontent.ai
• bulk-get-content-item-variants – Obtiene en masa elementos de contenido de Kontent.ai con sus variantes por pares de referencia de elemento e idioma. Úsalo después de list-content-item-variants para recuperar datos completos de contenido para pares específicos de elemento+idioma. Los elementos sin variante en el idioma solicitado devuelven el elemento 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. Úsalo para: búsquedas conceptuales cuando no conoces palabras clave exactas. Opciones de filtrado limitadas (solo ID de variante)

Gestión de Activos

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

Gestión de Carpetas de Activos

• list-asset-folders – Lista todas las carpetas de activos de Kontent.ai
• patch-asset-folders – Modifica las carpetas de activos de Kontent.ai usando operaciones de parche (agregarEn para agregar nuevas carpetas, renombrar para cambiar nombres, eliminar para borrar carpetas)

Gestión de Idiomas

• list-languages – Obtén todos los idiomas de Kontent.ai (incluye tanto activos como inactivos: verifica la propiedad is_active)
• create-language – Crea un nuevo idioma de Kontent.ai (los idiomas siempre se crean como activos)
• patch-language – Actualiza el 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 parche (agregarEn para agregar nuevas colecciones, mover para reordenar, eliminar para borrar colecciones vacías, reemplazar 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 al espacio de Kontent.ai usando operaciones de reemplazo
• delete-space – Elimina el espacio de Kontent.ai

Gestión de Roles

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

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 del 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 una variante de elemento de contenido en Kontent.ai. Esta operación puede publicar inmediatamente la variante 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 inmediatamente la variante (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 ediciones adicionales

⚙️ 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 (HTTP Transmisible)

Para el transporte HTTP Transmisible, 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 de Autorización: Authorization: Bearer <api-key>

Esto permite que una sola instancia del servidor maneje solicitudes para múltiples entornos de Kontent.ai sin requerir variables de entorno de credenciales.

KONTENT_API_KEY y KONTENT_ENVIRONMENT_ID se ignoran en este transporte, incluso si están configuradas en el entorno del servidor. Cada solicitud debe llevar sus propias credenciales; una que no las tenga es rechazada en lugar de servirse con las del servidor.

🔒 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 secuestrado 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:

• Utilice una clave de API de Management 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 secuestrado simplemente falla en el límite de la API — el control más fuerte, ya que se mantiene independientemente del comportamiento del modelo.
• Mantenga 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 utilizan para aprobar automáticamente lecturas y solicitar confirmación antes de llamadas destructivas. Ejecute el servidor con dicho cliente y evite configuraciones de aprobación automática sin supervisión con una clave con capacidad de escritura.
• Agregue una compuerta del lado del cliente si su cliente lo admite. Algunos clientes (por ejemplo, los hooks de Claude Code) le permiten solicitar confirmación de manera 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. Reporte problemas de seguridad de manera privada a security@kontent.ai.

🚀 Opciones de Transporte

📟 Transporte STDIO

Para ejecutar el servidor con transporte STDIO, configure su 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 Streamable atiende 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 inicie 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] Reemplace <environment-id> con el ID de su entorno de Kontent.ai (GUID) y <management-api-key> con su 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 de utilidad
    • errorHandler.ts - Manejo de errores estandarizado para herramientas MCP
    • throwError.ts - Utilidad genérica de lanzamiento de errores
  • app.ts - Fábrica de aplicaciones Express para el transporte HTTP Streamable
  • 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, puede 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 use el inspector MCP en un servidor HTTP streamable en ejecución:

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. Aumente la versión usando npm version [patch|minor|major] - esto actualiza package.json, package-lock.json, y sincroniza con server.json
2. Envíe el commit a su rama y cree una solicitud de extracción
3. Combine la solicitud de extracción
4. Cree una nueva versión de GitHub con el número de versión como nombre y etiqueta, usando notas de versión generadas automáticamente
5. Publicar la versión activa un flujo de trabajo automatizado que publica en npm y en el registro MCP de GitHub

Licencia

MIT