Kontent.ai

Servidor MCP Kontent.ai

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

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

✨ Principais Funcionalidades

• 🚀 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

Índice

• ✨ Principais Funcionalidades
• 🔌 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 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 apropriadas.
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 Transmissível

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 o Kontent.ai por tipo de entidade

Gerenciamento de Tipos de Conteúdo

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

Gerenciamento de Taxonomia

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

Gerenciamento de Itens de Conteúdo

• get-content-item – Obtenha o item de conteúdo do Kontent.ai por ID
• get-content-item-variant – Recupere a variante do item de conteúdo do Kontent.ai (versão de idioma/tradução). Retorna a versão atual — rascunho se existir, caso contrário, a publicada
• get-published-content-item-variant-version – Recupere a versão publicada de uma variante de item de conteúdo do Kontent.ai. Use quando existir uma versão de rascunho mais recente, mas você precisar do conteúdo atualmente publicado (ao vivo)
• get-content-item-translations – Obtenha todas as traduções do item de conteúdo do Kontent.ai — cada versão de idioma (variante) de um item de conteúdo específico
• list-content-item-variants – Liste, filtre, pesquise itens de conteúdo do Kontent.ai com variantes de itens de conteúdo (versões de idioma/traduções)
• create-content-item – Crie um novo item de conteúdo 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 existente do Kontent.ai por ID. O item de conteúdo já deve existir - esta ferramenta não criará novos itens
• delete-content-item – Exclua um item de conteúdo do Kontent.ai por ID
• create-content-item-variant – Crie uma variante de item de conteúdo do Kontent.ai atribuindo o usuário atual como contribuidor. 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 inicializam vazios
• update-content-item-variant – Atualize a variante de item de conteúdo de um item de conteúdo do Kontent.ai. Os valores dos elementos devem atender às limitações e diretrizes definidas no tipo de conteúdo. Envie apenas os elementos que deseja alterar — elementos omitidos permanecem inalterados. Para elementos rich-text com componentes, envie o elemento completo (valor mais o array completo de componentes, incluindo componentes que permanecem inalterados)
• create-new-content-item-variant-version – Crie uma nova versão da variante de item de conteúdo 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 do Kontent.ai
• bulk-get-content-item-variants – Obtenha em massa itens de conteúdo do Kontent.ai com suas variantes 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 uma 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 baseada em IA para encontrar conteúdo por significado e conceitos em uma variante específica de item de conteúdo. Use para: pesquisas conceituais quando você não conhece palavras-chave exatas. Opções de filtragem limitadas (apenas ID da variante)

Gerenciamento de Ativos

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

Gerenciamento de Pastas de Ativos

• list-asset-folders – Liste todas as pastas de ativos do Kontent.ai
• patch-asset-folders – Modifique as pastas de ativos do 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 do Kontent.ai (inclui ativos e inativos - verifique a propriedade is_active)
• create-language – Crie um novo idioma do Kontent.ai (idiomas são sempre criados como ativos)
• patch-language – Atualize o idioma do Kontent.ai usando operações replace (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 do Kontent.ai. Coleções definem limites para itens de conteúdo em seu ambiente e ajudam a organizar o conteúdo por equipe, marca ou projeto
• patch-collections – Atualize as coleções do 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 do Kontent.ai
• create-space – Crie um novo espaço do Kontent.ai para gerenciar um site ou canal
• patch-space – Aplique patch no espaço do Kontent.ai usando operações replace
• delete-space – Exclua o espaço do Kontent.ai

Gerenciamento de Funções

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

Gerenciamento de Fluxo de Trabalho

• list-workflows – Obtenha todos os fluxos de trabalho do Kontent.ai. 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 do Kontent.ai com etapas, transições, escopos e permissões de função personalizados
• update-workflow – Atualize um fluxo de trabalho existente do Kontent.ai por ID. Modifique etapas, transições, escopos e permissões de função. Não é possível remover etapas que estão em uso
• delete-workflow – Exclua um fluxo de trabalho do 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 publicado, etc.
• publish-content-item-variant – Publique ou agende a publicação de uma variante de item de conteúdo de um 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 – Despublicar ou agendar a despublicação de uma variante de item de conteúdo de um item de conteúdo no Kontent.ai. Esta operação pode despublicar imediatamente a variante (tornando-a indisponível através da API de Entrega) ou agendá-la para despublicação em uma data e hora futuras específicas com especificação opcional de fuso horário

⚙️ Configuração

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

Modo Single-Tenant (STDIO)

Configure as credenciais via variáveis de ambiente:

Modo Multi-Tenant (HTTP Transmissível)

Para o transporte HTTP Transmissível, as credenciais são fornecidas por requisição:

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

Isso permite que uma única instância de servidor lide com requisições para múltiplos 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 sequestrado 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 todo o setor 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égio mínimo. O servidor age com qualquer chave que receber. Com uma chave somente leitura, uma chamada destrutiva de um agente comprometido simplesmente falha na fronteira da API — o controle mais forte, já que se mantém independentemente do comportamento do modelo.
• Mantenha um humano no circuito. Cada ferramenta carrega 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 automaticamente leituras e solicitar confirmação antes de chamadas destrutivas. Execute o servidor com esse tipo de cliente e evite configurações de aprovação automática sem supervisão com uma chave com capacidade de escrita.
• Adicione uma barreira no lado do cliente se o seu cliente oferecer suporte. Alguns clientes (por exemplo, hooks do Claude Code) permitem que você solicite confirmação de forma determinística antes da execução de uma ferramenta destrutiva, independentemente do modelo. Isso é configurado localmente; o servidor não pode impor.

Estas são sugestões, não garantias. Relate problemas de segurança de forma privada para [email protected].

🚀 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 Transmissível (Multi-Tenant)

O transporte HTTP transmissível atende vários ambientes Kontent.ai a partir de uma única instância de servidor. Cada requisição fornece credenciais via parâmetros de caminho da 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 das 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 para 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 transmissível em execução:

npx @modelcontextprotocol/inspector

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

📦 Processo de Lançamento

Para lançar uma nova versão:

1. Incremente 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 um novo lançamento no GitHub com o número da versão como nome e tag, usando notas de lançamento geradas automaticamente
5. A publicação do lançamento aciona um fluxo de trabalho automatizado que publica no npm e no registro MCP do GitHub

Licença

MIT