Kontent.ai

Kontent.ai MCP Server

Transforme suas operações de conteúdo com ferramentas com tecnologia de IA para Kontent.ai. Crie, gerencie e explore seu conteúdo estruturado por meio de conversas em linguagem natural no seu editor favorito habilitado para IA.

O servidor MCP Kontent.ai implementa o Model Context Protocol para conectar seus projetos Kontent.ai a ferramentas de IA como Claude, Cursor e VS Code. Ele permite que modelos de IA entendam sua estrutura de conteúdo e executem operações por meio de instruções em linguagem natural.

✨ Principais recursos

• 🚀 Prototipagem rápida: Transforme seus diagramas em modelos de conteúdo ativos em segundos
• 📈 Visualização de dados: Visualize seu modelo de conteúdo no formato que desejar

Sumário

• ✨ Principais recursos
• 🔌 Início rápido
• 🛠️ Ferramentas disponíveis
• ⚙️ Configuração
• 🔒 Segurança
• 🚀 Opções de transporte
• 💻 Desenvolvimento
  • 🛠 Instalação local
  • 📂 Estrutura do projeto
  • 🔍 Depuração
  • 📦 Processo de lançamento
• Licença

🔌 Início rápido

🔑 Pré-requisitos

Antes de usar o servidor MCP, você precisa de:

1. Uma conta Kontent.ai - Cadastre-se se você não tiver uma conta.
2. Um projeto - Crie um projeto para trabalhar.
3. Chave da API de gerenciamento - Crie uma chave com as permissões adequadas.
4. ID do ambiente - Obtenha seu ID de ambiente.

🛠 Opções de configuração

Você pode executar o servidor MCP Kontent.ai com npx:

Transporte STDIO

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

Transporte HTTP Streamable

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

🛠️ Ferramentas disponíveis

Guia de operações de patch

• get-patch-guide – 🚨 OBRIGATÓRIO antes de qualquer operação de patch. Obtenha o guia de operações de patch para Kontent.ai por tipo de entidade

Gerenciamento de tipos de conteúdo

• get-content-type – Obtenha o tipo de conteúdo Kontent.ai por ID
• list-content-types – Obtenha todos os tipos de conteúdo Kontent.ai
• create-content-type – Crie um novo tipo de conteúdo Kontent.ai
• patch-content-type – Atualize um tipo de conteúdo Kontent.ai existente por codinome usando operações de patch (move, addInto, remove, replace)
• delete-content-type – Exclua um tipo de conteúdo Kontent.ai por ID

Gerenciamento de snippets de tipo de conteúdo

• get-content-type-snippet – Obtenha o snippet de tipo de conteúdo Kontent.ai por ID
• list-content-type-snippets – Obtenha todos os snippets de tipo de conteúdo Kontent.ai
• create-content-type-snippet – Crie um novo snippet de tipo de conteúdo Kontent.ai
• patch-content-type-snippet – Atualize um snippet de tipo de conteúdo Kontent.ai existente por ID usando operações de patch (move, addInto, remove, replace)
• delete-content-type-snippet – Exclua um snippet de tipo de conteúdo Kontent.ai por ID

Gerenciamento de taxonomia

• get-taxonomy-group – Obtenha o grupo de taxonomia Kontent.ai por ID
• list-taxonomy-groups – Obtenha todos os grupos de taxonomia Kontent.ai
• create-taxonomy-group – Crie um novo grupo de taxonomia Kontent.ai
• patch-taxonomy-group – Atualize o grupo de taxonomia Kontent.ai usando operações de patch (addInto, move, remove, replace)
• delete-taxonomy-group – Exclua o grupo de taxonomia Kontent.ai por ID

Gerenciamento de itens de conteúdo

• get-content-item – Obtenha o item de conteúdo Kontent.ai por ID
• get-content-item-variant – Recupere a variante do item de conteúdo Kontent.ai (versão de idioma/tradução). Retorna a versão atual — rascunho se existir, caso contrário, publicada
• get-published-content-item-variant-version – Recupere a versão publicada de uma variante de item de conteúdo Kontent.ai. Use quando uma versão de rascunho mais recente existir, mas você precisar do conteúdo atualmente publicado (ao vivo)
• get-content-item-translations – Obtenha todas as traduções de item de conteúdo Kontent.ai — todas as versões de idioma (variantes) de um item de conteúdo específico
• list-content-item-variants – Liste, filtre e pesquise itens de conteúdo Kontent.ai com variantes de item de conteúdo (versões de idioma/traduções)
• create-content-item – Crie um novo item de conteúdo Kontent.ai (cria apenas o contêiner; use create-content-item-variant para adicionar versões de idioma/traduções)
• update-content-item – Atualize um item de conteúdo Kontent.ai existente por ID. O item de conteúdo já deve existir - esta ferramenta não cria novos itens
• delete-content-item – Exclua um item de conteúdo Kontent.ai por ID
• create-content-item-variant – Crie uma variante de item de conteúdo Kontent.ai atribuindo o usuário atual como colaborador. Os valores dos elementos devem atender às limitações e diretrizes definidas no tipo de conteúdo. Envie apenas os elementos que deseja definir; os omitidos são inicializados vazios
• update-content-item-variant – Atualize a variante de item de conteúdo Kontent.ai de um item de conteúdo. Os valores dos elementos devem atender às limitações e diretrizes definidas no tipo de conteúdo. Envie apenas os elementos que deseja alterar — os elementos omitidos permanecem intactos. Para elementos de texto rico com componentes, envie o elemento completo (valor mais a matriz completa de componentes, incluindo componentes que não foram alterados)
• create-new-content-item-variant-version – Crie uma nova versão da variante de item de conteúdo Kontent.ai. Esta operação cria uma nova versão de uma variante de item de conteúdo existente, útil para versionamento de conteúdo e criação de novos rascunhos a partir de conteúdo publicado
• delete-content-item-variant – Exclua a variante de item de conteúdo Kontent.ai
• bulk-get-content-item-variants – Obtenha em lote itens de conteúdo Kontent.ai com suas variantes de item de conteúdo por pares de referência de item e idioma. Use após list-content-item-variants para recuperar dados completos de conteúdo para pares específicos de item+idioma. Itens sem variante no idioma solicitado retornam o item sem a propriedade de variante. Retorna resultados paginados com token de continuação
• search-content-item-variants – Pesquisa semântica com tecnologia de IA para encontrar conteúdo por significado e conceitos em uma variante de item de conteúdo específica. Use para: pesquisas conceituais quando você não sabe as palavras-chave exatas. Opções de filtragem limitadas (somente ID da variante)

Gerenciamento de ativos

• get-asset – Obtenha um ativo Kontent.ai específico por ID
• list-assets – Obtenha todos os ativos Kontent.ai
• update-asset – Atualize o ativo Kontent.ai por ID

Gerenciamento de pastas de ativos

• list-asset-folders – Liste todas as pastas de ativos Kontent.ai
• patch-asset-folders – Modifique as pastas de ativos Kontent.ai usando operações de patch (addInto para adicionar novas pastas, rename para alterar nomes, remove para excluir pastas)

Gerenciamento de idiomas

• list-languages – Obtenha todos os idiomas Kontent.ai (inclui ativos e inativos - verifique a propriedade is_active)
• create-language – Crie um novo idioma Kontent.ai (os idiomas são sempre criados como ativos)
• patch-language – Atualize o idioma Kontent.ai usando operações de substituição (apenas idiomas ativos podem ser modificados - para ativar/desativar, use a interface web do Kontent.ai)

Gerenciamento de coleções

• list-collections – Obtenha todas as coleções Kontent.ai. As coleções definem limites para itens de conteúdo no seu ambiente e ajudam a organizar o conteúdo por equipe, marca ou projeto
• patch-collections – Atualize as coleções Kontent.ai usando operações de patch (addInto para adicionar novas coleções, move para reordenar, remove para excluir coleções vazias, replace para renomear)

Gerenciamento de espaços

• list-spaces – Obtenha todos os espaços Kontent.ai
• create-space – Crie um novo espaço Kontent.ai para gerenciar um site ou canal
• patch-space – Aplique patch no espaço Kontent.ai usando operações de substituição
• delete-space – Exclua o espaço Kontent.ai

Gerenciamento de funções

• list-roles – Obtenha todas as funções Kontent.ai. Requer plano Enterprise ou Flex com permissão "Gerenciar funções personalizadas"

Gerenciamento de fluxos de trabalho

• list-workflows – Obtenha todos os fluxos de trabalho Kontent.ai. Os fluxos de trabalho definem os estágios do ciclo de vida do conteúdo e as transições entre eles
• create-workflow – Crie um novo fluxo de trabalho Kontent.ai com etapas, transições, escopos e permissões de função personalizados
• update-workflow – Atualize um fluxo de trabalho Kontent.ai existente por ID. Modifique etapas, transições, escopos e permissões de função. Não é possível remover etapas em uso
• delete-workflow – Exclua um fluxo de trabalho Kontent.ai por ID. O fluxo de trabalho não deve estar em uso por nenhum item de conteúdo
• change-content-item-variant-workflow-step – Altere a etapa do fluxo de trabalho de uma variante de item de conteúdo no Kontent.ai. Esta operação move uma variante de item de conteúdo para uma etapa diferente no fluxo de trabalho, permitindo o gerenciamento do ciclo de vida do conteúdo, como mover conteúdo de rascunho para revisão, revisão para publicação, etc.
• publish-content-item-variant – Publique ou agende a publicação de uma variante de item de conteúdo no Kontent.ai. Esta operação pode publicar imediatamente a variante ou agendá-la para publicação em uma data e hora futuras específicas, com especificação opcional de fuso horário
• unpublish-content-item-variant – Despublique ou agende a despublicação de uma variante de item de conteúdo no Kontent.ai. Esta operação pode despublicar imediatamente a variante (tornando-a indisponível por meio da Delivery API) ou agendar a despublicação para uma data e hora futuras específicas, com especificação opcional de fuso horário
• cancel-scheduled-publishing-content-item-variant – Cancele a publicação agendada de uma variante de item de conteúdo no Kontent.ai. Esta operação reverte uma variante que foi agendada para publicação de volta à sua etapa anterior do fluxo de trabalho, permitindo edições adicionais

⚙️ Configuração

O servidor suporta dois modos, cada um vinculado ao seu transporte:

Modo Single-Tenant (STDIO)

Configure as credenciais por meio de variáveis de ambiente:

Modo Multi-Tenant (Streamable HTTP)

Para o transporte Streamable HTTP, as credenciais são fornecidas por solicitação:

• ID do ambiente como parâmetro de caminho da URL: /{environmentId}/mcp
• Chave da API via Bearer token no cabeçalho Authorization: Authorization: Bearer <api-key>

Isso permite que uma única instância do servidor lide com solicitações de vários ambientes Kontent.ai sem exigir variáveis de ambiente de credenciais.

🔒 Segurança

Injeção indireta de prompt

O conteúdo retornado por este servidor (por exemplo, um elemento escrito por um editor) pode conter texto que um LLM conectado interpreta como instruções — injeção indireta de prompt. Um agente comprometido pode ser direcionado para chamadas de ferramentas destrutivas (excluir / despublicar / sobrescrever) ou para vazar rascunhos não publicados. Este é um problema não resolvido em toda a indústria, que o servidor não pode corrigir de forma confiável transformando o conteúdo que retorna, portanto a defesa é em camadas:

• Use uma chave de API de gerenciamento com privilégios mínimos. O servidor opera com a chave que lhe for fornecida. Com uma chave somente leitura, uma chamada destrutiva de um agente sequestrado simplesmente falha no limite da API — o controle mais forte, pois se mantém independentemente do comportamento do modelo.
• Mantenha um humano no circuito. Cada ferramenta traz anotações MCP — leituras são readOnlyHint, ferramentas somente de criação são aditivas, e ferramentas que sobrescrevem ou removem dados são destructiveHint — que clientes compatíveis usam para aprovar leituras automaticamente e solicitar confirmação antes de chamadas destrutivas. Execute o servidor com esse tipo de cliente e evite configurações headless de aprovação automática com uma chave com permissão de escrita.
• Adicione uma barreira no lado do cliente, se o seu cliente suportar. Alguns clientes (por exemplo, hooks do Claude Code) permitem solicitar confirmação de forma determinística antes de uma ferramenta destrutiva ser executada, independentemente do modelo. Isso é configurado localmente; o servidor não pode impor isso.

Estas são dicas, não garantias. Relate problemas de segurança em particular para security@kontent.ai.

🚀 Opções de Transporte

📟 Transporte STDIO

Para executar o servidor com transporte STDIO, configure seu cliente MCP com:

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

O transporte HTTP Streamable atende a vários ambientes Kontent.ai a partir de uma única instância do servidor. Cada solicitação fornece credenciais por meio de parâmetros de caminho na URL e autenticação Bearer.

Primeiro, inicie o 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] Substitua <environment-id> pelo ID do seu ambiente Kontent.ai (GUID) e <management-api-key> pela sua chave.

💻 Desenvolvimento

🛠 Instalação 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

📂 Estrutura do Projeto

• src/ - Código-fonte
  • tools/ - Implementações de ferramentas MCP
  • clients/ - Configuração do cliente da API Kontent.ai
  • schemas/ - Esquemas de validação de dados
  • utils/ - Funções utilitárias
    • errorHandler.ts - Tratamento padronizado de erros para ferramentas MCP
    • throwError.ts - Utilitário genérico de lançamento de erros
  • server.ts - Configuração principal do servidor e registro de ferramentas
  • bin.ts - Ponto de entrada único que lida com ambos os tipos de transporte

🔍 Depuração

Para depuração, você pode usar o inspetor MCP:

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

Ou use o inspetor MCP em um servidor HTTP streamable em execução:

npx @modelcontextprotocol/inspector

Isso fornece uma interface web para inspecionar e testar as ferramentas disponíveis.

📦 Processo de Release

Para lançar uma nova versão:

1. Aumente a versão usando npm version [patch|minor|major] - isso atualiza package.json, package-lock.json e sincroniza com server.json
2. Envie o commit para sua branch e crie um pull request
3. Faça o merge do pull request
4. Crie uma nova release no GitHub com o número da versão como nome e tag, usando notas de release geradas automaticamente
5. A publicação da release aciona um workflow automatizado que publica no npm e no registro MCP do GitHub

Licença

MIT