Kontent.ai

Servidor MCP de Kontent.ai

Transforme sus operaciones de contenido con herramientas impulsadas por IA para Kontent.ai. Cree, gestione y explore su contenido estructurado mediante conversaciones en lenguaje natural en su editor favorito con IA.

El Servidor MCP de Kontent.ai implementa el Protocolo de Contexto de Modelo para conectar sus proyectos de Kontent.ai con herramientas de IA como Claude, Cursor y VS Code. Permite que los modelos de IA comprendan la estructura de su contenido y realicen operaciones mediante instrucciones en lenguaje natural.

✨ Características Principales

• 🚀 Prototipado rápido: Transforme sus diagramas en modelos de contenido funcionales en segundos
• 📈 Visualización de Datos: Visualice su modelo de contenido en el formato que desee

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, necesita:

1. Una cuenta de Kontent.ai - Regístrese si no tiene una cuenta.
2. Un proyecto - Cree un proyecto con el que trabajar.
3. Clave de API de Gestión - Cree una clave con los permisos adecuados.
4. ID de Entorno - Obtenga su ID de entorno.

🛠 Opciones de Configuración

Puede 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 – 🚨 OBLIGATORIO antes de cualquier operación de parche. Obtenga la guía de operaciones de parche para Kontent.ai por tipo de entidad

Gestión de Tipos de Contenido

• get-content-type – Obtener tipo de contenido de Kontent.ai por ID
• list-content-types – Obtener todos los tipos de contenido de Kontent.ai
• create-content-type – Crear nuevo tipo de contenido de Kontent.ai
• patch-content-type – Actualizar un tipo de contenido de Kontent.ai existente por nombre en código usando operaciones de parche (mover, añadir, eliminar, reemplazar)
• delete-content-type – Eliminar un tipo de contenido de Kontent.ai por ID

Gestión de Fragmentos de Tipo de Contenido

• get-content-type-snippet – Obtener fragmento de tipo de contenido de Kontent.ai por ID
• list-content-type-snippets – Obtener todos los fragmentos de tipo de contenido de Kontent.ai
• create-content-type-snippet – Crear nuevo fragmento de tipo de contenido de Kontent.ai
• patch-content-type-snippet – Actualizar un fragmento de tipo de contenido de Kontent.ai existente por ID usando operaciones de parche (mover, añadir, eliminar, reemplazar)
• delete-content-type-snippet – Eliminar un fragmento de tipo de contenido de Kontent.ai por ID

Gestión de Taxonomías

• get-taxonomy-group – Obtener grupo de taxonomía de Kontent.ai por ID
• list-taxonomy-groups – Obtener todos los grupos de taxonomía de Kontent.ai
• create-taxonomy-group – Crear nuevo grupo de taxonomía de Kontent.ai
• patch-taxonomy-group – Actualizar grupo de taxonomía de Kontent.ai usando operaciones de parche (añadir, mover, eliminar, reemplazar)
• delete-taxonomy-group – Eliminar grupo de taxonomía de Kontent.ai por ID

Gestión de Elementos de Contenido

• get-content-item – Obtener elemento de contenido de Kontent.ai por ID
• get-content-item-variant – Recuperar 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 – Recuperar la versión publicada de una variante de elemento de contenido de Kontent.ai. Úselo cuando exista una versión de borrador más reciente pero necesite el contenido actualmente publicado (en vivo)
• get-content-item-translations – Obtener 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 – Listar, filtrar, buscar elementos de contenido de Kontent.ai con variantes de elementos de contenido (versiones de idioma/traducciones)
• create-content-item – Crear nuevo elemento de contenido de Kontent.ai (crea solo el contenedor, use create-content-item-variant para añadir versiones de idioma/traducciones)
• update-content-item – Actualizar elemento de contenido de Kontent.ai existente por ID. El elemento de contenido ya debe existir - esta herramienta no creará nuevos elementos
• delete-content-item – Eliminar elemento de contenido de Kontent.ai por ID
• create-content-item-variant – Crear variante de elemento de contenido de Kontent.ai asignando al usuario actual como colaborador. Los valores de los elementos deben cumplir con las limitaciones y directrices definidas en el tipo de contenido. Envíe solo los elementos que desea establecer; los omitidos se inicializan vacíos
• update-content-item-variant – Actualizar variante de elemento de contenido de Kontent.ai de un elemento de contenido. Los valores de los elementos deben cumplir con las limitaciones y directrices definidas en el tipo de contenido. Envíe solo los elementos que desea cambiar — los elementos omitidos se dejan intactos. Para elementos de texto enriquecido con componentes, envíe el elemento completo (valor más el array completo de componentes, incluyendo los componentes que se dejan intactos)
• create-new-content-item-variant-version – Crear nueva versión de variante de elemento de contenido de Kontent.ai. Esta operación crea una nueva versión de una variante de elemento de contenido existente, útil para el versionado de contenido y la creación de nuevos borradores a partir de contenido publicado
• delete-content-item-variant – Eliminar variante de elemento de contenido de Kontent.ai
• bulk-get-content-item-variants – Obtener en lote elementos de contenido de Kontent.ai con sus variantes por pares de referencia de elemento e idioma. Úselo después de list-content-item-variants para recuperar datos completos de contenido para pares específicos de elemento+idioma. Los elementos sin una 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 de elemento de contenido específica. Úselo para: búsquedas conceptuales cuando no conoce las palabras clave exactas. Opciones de filtrado limitadas (solo ID de variante)

Gestión de Activos

• get-asset – Obtener un activo específico de Kontent.ai por ID
• list-assets – Obtener todos los activos de Kontent.ai
• update-asset – Actualizar activo de Kontent.ai por ID

Gestión de Carpetas de Activos

• list-asset-folders – Listar todas las carpetas de activos de Kontent.ai
• patch-asset-folders – Modificar carpetas de activos de Kontent.ai usando operaciones de parche (addInto para añadir nuevas carpetas, rename para cambiar nombres, remove para eliminar carpetas)

Gestión de Idiomas

• list-languages – Obtener todos los idiomas de Kontent.ai (incluye tanto activos como inactivos - verifique la propiedad is_active)
• create-language – Crear nuevo idioma de Kontent.ai (los idiomas siempre se crean como activos)
• patch-language – Actualizar idioma de Kontent.ai usando operaciones de reemplazo (solo los idiomas activos pueden modificarse - para activar/desactivar, use la interfaz web de Kontent.ai)

Gestión de Colecciones

• list-collections – Obtener todas las colecciones de Kontent.ai. Las colecciones establecen límites para los elementos de contenido en su entorno y ayudan a organizar el contenido por equipo, marca o proyecto
• patch-collections – Actualizar colecciones de Kontent.ai usando operaciones de parche (addInto para añadir nuevas colecciones, move para reordenar, remove para eliminar colecciones vacías, replace para renombrar)

Gestión de Espacios

• list-spaces – Obtener todos los espacios de Kontent.ai
• create-space – Crear nuevo espacio de Kontent.ai para gestionar un sitio web o canal
• patch-space – Parchear espacio de Kontent.ai usando operaciones de reemplazo
• delete-space – Eliminar espacio de Kontent.ai

Gestión de Roles

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

Gestión de Flujos de Trabajo

• list-workflows – Obtener 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 – Crear nuevo flujo de trabajo de Kontent.ai con pasos, transiciones, ámbitos y permisos de rol personalizados
• update-workflow – Actualizar un flujo de trabajo de Kontent.ai existente por ID. Modificar pasos, transiciones, ámbitos y permisos de rol. No se pueden eliminar pasos que estén en uso
• delete-workflow – Eliminar 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 – Cambiar el paso del flujo de trabajo de una variante de elemento de contenido en Kontent.ai. Esta operación mueve una variante de elemento de contenido a un paso diferente en el flujo de trabajo, permitiendo 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 – Publicar o programar una variante de elemento de contenido de un elemento de contenido en Kontent.ai. Esta operación puede publicar inmediatamente la variante o programarla para su publicación en una fecha y hora futura específica con especificación opcional de zona horaria
• unpublish-content-item-variant – Despublicar o programar la despublicación de una variante de elemento de contenido de un 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 su despublicación en una fecha y hora futura específica con especificación opcional de zona horaria

⚙️ Configuración

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

Modo Single-Tenant (STDIO)

Configure las credenciales mediante variables de entorno:

Modo Multi-Tenant (HTTP Transmisible)

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

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

Esto permite que una única instancia de servidor maneje solicitudes para múltiples entornos de Kontent.ai sin requerir 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 secuestrado podría ser dirigido a realizar llamadas destructivas a herramientas (eliminar / despublicar / sobrescribir) o a filtrar borradores no publicados. Este es un problema no resuelto a nivel de industria que el servidor no puede solucionar de forma fiable transformando el contenido que devuelve, por lo que la defensa se estructura en capas:

• Use una clave de API de gestión con el mínimo privilegio necesario. El servidor actúa con la clave que se le proporcione. Con una clave de solo lectura, una 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.
• Mantenga a un humano al tanto. 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; los clientes compatibles las usan para aprobar automáticamente las lecturas y solicitar confirmación antes de las llamadas destructivas. Ejecute el servidor con un cliente de este tipo y evite configuraciones de aprobación automática sin supervisión con una clave con capacidad de escritura.
• Añada una barrera del lado del cliente si su cliente lo permite. Algunos clientes (por ejemplo, los hooks de Claude Code) le 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.

Estos son consejos, no garantías. Informe los problemas de seguridad de forma privada a [email protected].

🚀 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 Transmisible (Multi-Inquilino)

El transporte HTTP transmisible sirve múltiples entornos de Kontent.ai desde una única instancia de servidor. Cada solicitud proporciona credenciales a través de 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>"

[!IMPORTANT] Reemplace <environment-id> con su ID de 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 de la 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 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, 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 transmisible 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. Incremente la versión usando npm version [patch|minor|major] - esto actualiza package.json, package-lock.json y sincroniza con server.json
2. Haga push del commit a su rama y cree una pull request
3. Fusione la pull request
4. Cree una nueva publicación en GitHub con el número de versión como nombre y etiqueta, usando notas de publicación autogeneradas
5. Publicar la publicación desencadena un flujo de trabajo automatizado que publica en npm y en el registro MCP de GitHub

Licencia

MIT