Kontent.ai

Servidor MCP Kontent.ai

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

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 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 funcionais em segundos
• 📈 Visualização de dados: Visualize seu modelo de conteúdo em qualquer formato desejado

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:

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 apropriadas.
4. ID do Ambiente - Obtenha o ID do seu 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 – Obter tipo de conteúdo Kontent.ai por ID
• list-content-types – Obter todos os tipos de conteúdo Kontent.ai
• list-content-type-usages – Listar onde um tipo de conteúdo Kontent.ai é usado
• create-content-type – Criar novo tipo de conteúdo Kontent.ai
• patch-content-type – Atualizar um tipo de conteúdo Kontent.ai existente por codinome usando operações de patch (mover, adicionarEm, remover, substituir)
• delete-content-type – Excluir um tipo de conteúdo Kontent.ai por ID

Gerenciamento de Snippets de Tipos de Conteúdo

• get-content-type-snippet – Obter snippet de tipo de conteúdo Kontent.ai por ID
• list-content-type-snippets – Obter todos os snippets de tipos de conteúdo Kontent.ai
• create-content-type-snippet – Criar novo snippet de tipo de conteúdo Kontent.ai
• patch-content-type-snippet – Atualizar um snippet de tipo de conteúdo Kontent.ai existente por ID usando operações de patch (mover, adicionarEm, remover, substituir)
• delete-content-type-snippet – Excluir um snippet de tipo de conteúdo Kontent.ai por ID

Gerenciamento de Taxonomia

• get-taxonomy-group – Obter grupo de taxonomia Kontent.ai por ID
• list-taxonomy-groups – Obter todos os grupos de taxonomia Kontent.ai
• create-taxonomy-group – Criar novo grupo de taxonomia Kontent.ai
• patch-taxonomy-group – Atualizar grupo de taxonomia Kontent.ai usando operações de patch (adicionarEm, mover, remover, substituir)
• delete-taxonomy-group – Excluir grupo de taxonomia Kontent.ai por ID

Gerenciamento de Itens de Conteúdo

• get-content-item – Obter item de conteúdo Kontent.ai por ID
• get-content-item-variant – Recuperar variante de item de conteúdo Kontent.ai (versão de idioma/tradução). Retorna a versão atual — rascunho se existir, caso contrário, publicado
• get-published-content-item-variant-version – Recuperar 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 – Obter todas as traduções de item de conteúdo Kontent.ai — cada versão de idioma (variante) de um item de conteúdo específico
• list-content-item-variants – Listar, filtrar, pesquisar itens de conteúdo Kontent.ai com variantes de itens de conteúdo (versões de idioma/traduções)
• create-content-item – Criar 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 – Atualizar item de conteúdo Kontent.ai existente por ID. O item de conteúdo deve já existir — esta ferramenta não criará novos itens
• delete-content-item – Excluir item de conteúdo Kontent.ai por ID
• create-content-item-variant – Criar variante de item de conteú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 são inicializados vazios
• update-content-item-variant – Atualizar 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 rich text 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 – Criar nova versão de 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 – Excluir variante de item de conteúdo Kontent.ai
• bulk-get-content-item-variants – Obter em lote itens de conteúdo Kontent.ai com suas variantes de itens 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 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 alimentada por 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 (somente ID de variante)

Gerenciamento de Ativos

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

Gerenciamento de Pastas de Ativos

• list-asset-folders – Listar todas as pastas de ativos Kontent.ai
• patch-asset-folders – Modificar pastas de ativos Kontent.ai usando operações de patch (adicionarEm para adicionar novas pastas, renomear para alterar nomes, remover para excluir pastas)

Gerenciamento de Idiomas

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

Gerenciamento de Coleções

• list-collections – Obter 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 – Atualizar coleções Kontent.ai usando operações de patch (adicionarEm para adicionar novas coleções, mover para reordenar, remover para excluir coleções vazias, substituir para renomear)

Gerenciamento de Espaços

• list-spaces – Obter todos os espaços Kontent.ai
• create-space – Criar novo espaço Kontent.ai para gerenciar um site ou canal
• patch-space – Aplicar patch em espaço Kontent.ai usando operações de substituição
• delete-space – Excluir espaço Kontent.ai

Gerenciamento de Funções

• list-roles – Obter 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 – Obter 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 – Criar novo fluxo de trabalho Kontent.ai com etapas, transições, escopos e permissões de função personalizados
• update-workflow – Atualizar 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 – Excluir 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 – Alterar 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, de revisão para publicado, etc.
• publish-content-item-variant – Publicar ou agendar 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 por meio 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
• cancel-scheduled-publishing-content-item-variant – Cancelar 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 (HTTP Streamable)

Para o transporte HTTP Streamable, as credenciais são fornecidas por solicitaçã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 do servidor lide com solicitações para múltiplos ambientes Kontent.ai sem exigir variáveis de ambiente de credenciais.

KONTENT_API_KEY e KONTENT_ENVIRONMENT_ID são ignorados neste transporte, mesmo que estejam definidos no ambiente do servidor. Cada solicitação deve carregar suas próprias credenciais; uma solicitação sem elas é rejeitada em vez de ser atendida com as do servidor.

🔒 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 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 age com a chave que recebe. Com uma chave somente leitura, a 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 processo. 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 tal 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 que você solicite confirmação de forma determinística antes de uma ferramenta destrutiva ser executada, independentemente do modelo. Isso é configurado localmente; um 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 múltiplos ambientes Kontent.ai a partir de uma única instância do servidor. Cada requisição fornece credenciais por meio de parâmetros de caminho de 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 de lançamento de erros
  • app.ts - Fábrica de aplicativos Express para o transporte HTTP Streamable
  • 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 Lançamento

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 o seu branch e crie um pull request
3. Mescle o 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. Publicar o lançamento aciona um fluxo de trabalho automatizado que publica no npm e no registro MCP do GitHub

Licença

MIT