Contentful

Contentful MCP Server

Aviso

Este é um servidor conduzido pela comunidade! A Contentful lançou um servidor oficial que você pode encontrar aqui

Uma implementação de servidor MCP que se integra à API de Gerenciamento de Conteúdo da Contentful, fornecendo capacidades abrangentes de gerenciamento de conteúdo.

• Observe *; se você não estiver interessado no código e apenas quiser usar este MCP no Claude Desktop (ou em qualquer outra ferramenta que possa usar servidores MCP), você não precisa clonar este repositório; basta configurá-lo no Claude Desktop. Consulte a seção "Uso com Claude Desktop" para obter instruções sobre como instalá-lo.

Recursos

• Gerenciamento de Conteúdo: Operações CRUD completas para entradas e ativos
• Gerenciamento de Comentários: Crie, recupere e gerencie comentários em entradas com suporte para formatos de texto simples e rich-text, incluindo conversas em tópicos
• Gerenciamento de Espaços: Crie, atualize e gerencie espaços e ambientes
• Tipos de Conteúdo: Gerencie definições de tipos de conteúdo
• Localização: Suporte a múltiplos locais
• Publicação: Controle o fluxo de trabalho de publicação de conteúdo
• Operações em Lote: Execute publicação, despublicação e validação em lote em múltiplas entradas e ativos
• Paginação Inteligente: Operações de listagem retornam no máximo 3 itens por solicitação para evitar estouro da janela de contexto, com suporte integrado a paginação

Paginação

Para evitar estouro da janela de contexto em LLMs, operações de listagem (como search_entries e list_assets) são limitadas a 3 itens por solicitação. Cada resposta inclui:

• Número total de itens disponíveis
• Página atual de itens (máx. 3)
• Número de itens restantes
• Valor de skip para a próxima página
• Mensagem solicitando que o LLM ofereça a recuperação de mais itens

Este sistema de paginação permite que o LLM lide eficientemente com grandes conjuntos de dados, mantendo os limites da janela de contexto.

Operações em Lote

O recurso de operações em lote fornece gerenciamento eficiente de múltiplos itens de conteúdo simultaneamente:

• Processamento Assíncrono: As operações são executadas de forma assíncrona e fornecem atualizações de status
• Gerenciamento Eficiente de Conteúdo: Processe múltiplas entradas ou ativos em uma única chamada de API
• Acompanhamento de Status: Monitore o progresso com contagens de sucesso e falha
• Otimização de Recursos: Reduza chamadas de API e melhore o desempenho para operações em lote

Essas ferramentas de operações em lote são ideais para migrações de conteúdo, atualizações em massa ou fluxos de trabalho de publicação em lote.

Ferramentas

Gerenciamento de Entradas

• search_entries: Pesquise entradas usando parâmetros de consulta
• create_entry: Crie novas entradas
• get_entry: Recupere entradas existentes
• update_entry: Atualize campos de entrada
• delete_entry: Remova entradas
• publish_entry: Publique entradas
• unpublish_entry: Despublique entradas

Gerenciamento de Comentários

• get_comments: Recupere comentários de uma entrada com filtro por status (ativo, resolvido, todos)
• create_comment: Crie novos comentários em entradas com suporte para formatos de texto simples e rich-text. Suporta conversas em tópicos fornecendo um ID de comentário pai para responder a comentários existentes
• get_single_comment: Recupere um comentário específico pelo seu ID para uma entrada
• delete_comment: Exclua um comentário específico de uma entrada
• update_comment: Atualize comentários existentes com novo conteúdo ou alterações de status

Comentários em Tópicos

Os comentários suportam funcionalidade de tópicos para permitir conversas estruturadas e contornar o limite de 512 caracteres:

• Responder a Comentários: Use o parâmetro parent em create_comment para responder a um comentário existente
• Conversas em Tópicos: Construa árvores de conversa respondendo a comentários específicos
• Discussões Estendidas: Contorne o limite de 512 caracteres criando respostas em tópicos para continuar mensagens mais longas
• Contexto da Conversa: Mantenha o contexto nas discussões organizando comentários relacionados em tópicos

Exemplo de uso:

1. Crie um comentário principal: create_comment com entryId, body e status
2. Responda a esse comentário: create_comment com entryId, body, status e parent (o ID do comentário ao qual você está respondendo)
3. Continue o tópico: Responda a qualquer comentário no tópico usando seu ID como o parent

Operações em Lote

• bulk_publish: Publique múltiplas entradas e ativos em uma única operação. Aceita uma matriz de entidades (entradas e ativos) e processa sua publicação em lote.
• bulk_unpublish: Despublique múltiplas entradas e ativos em uma única operação. Semelhante ao bulk_publish, mas remove o conteúdo da API de entrega.
• bulk_validate: Valide múltiplas entradas quanto à consistência do conteúdo, referências e campos obrigatórios. Retorna resultados de validação sem modificar o conteúdo.

Gerenciamento de Ativos

• list_assets: Liste ativos com paginação (3 itens por página)
• upload_asset: Envie novos ativos com metadados
• get_asset: Recupere detalhes e informações do ativo
• update_asset: Atualize metadados e arquivos do ativo
• delete_asset: Remova ativos do espaço
• publish_asset: Publique ativos na API de entrega
• unpublish_asset: Despublique ativos da API de entrega

Gerenciamento de Espaços e Ambientes

• list_spaces: Liste espaços disponíveis
• get_space: Obtenha detalhes do espaço
• list_environments: Liste ambientes em um espaço
• create_environment: Crie um novo ambiente
• delete_environment: Remova o ambiente

Gerenciamento de Tipos de Conteúdo

• list_content_types: Liste tipos de conteúdo disponíveis
• get_content_type: Obtenha detalhes do tipo de conteúdo
• create_content_type: Crie um novo tipo de conteúdo
• update_content_type: Atualize o tipo de conteúdo
• delete_content_type: Remova o tipo de conteúdo
• publish_content_type: Publique um tipo de conteúdo

Ferramentas de Desenvolvimento

MCP Inspector

O projeto inclui uma ferramenta MCP Inspector que ajuda no desenvolvimento e depuração:

• Modo Inspeção: Execute npm run inspect para iniciar o inspector; você pode abrir o inspector acessando http://localhost:5173
• Modo de Observação: Use npm run inspect:watch para reiniciar automaticamente o inspector quando os arquivos mudarem
• Interface Visual: O inspector fornece uma interface web para testar e depurar ferramentas MCP
• Testes em Tempo Real: Experimente ferramentas e veja suas respostas imediatamente
• Testes de Operações em Lote: Teste e monitore operações em lote com feedback visual sobre progresso e resultados

O projeto também contém um comando npm run dev que reconstrói e recarrega o servidor MCP a cada alteração.

Configuração

Pré-requisitos

1. Crie uma conta Contentful em Contentful
2. Gere um token da API de Gerenciamento de Conteúdo nas configurações da sua conta

Variáveis de Ambiente

Essas variáveis também podem ser definidas como argumentos

• CONTENTFUL_HOST / --host: Endpoint da API de Gerenciamento da Contentful (padrão: https://api.contentful.com)
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Seu token da API de Gerenciamento de Conteúdo
• ENABLE_HTTP_SERVER / --http: Defina como "true" para habilitar o modo HTTP/SSE
• HTTP_PORT / --port: Porta para o servidor HTTP (padrão: 3000)
• HTTP_HOST / --http-host: Host para o servidor HTTP (padrão: localhost)
• DISABLE_AI_ACTIONS: Defina como "true" para desabilitar a busca de Ações de IA na inicialização (útil se você não tiver acesso a esse recurso)

Escopo de Espaço e Ambiente

Você pode definir o escopo do spaceId e do EnvironmentId para garantir que o LLM execute apenas operações nos IDs de espaço/ambiente definidos. Isso serve principalmente para apoiar agentes que devem operar em espaços específicos. Se ambas as variáveis de ambiente SPACE_ID e ENVIRONMENT_ID forem definidas, as ferramentas não reportarão a necessidade desses valores e os manipuladores usarão as variáveis de ambiente para realizar operações CMA. Você também perderá o acesso às ferramentas no manipulador de espaços, pois essas ferramentas são entre espaços. Você também pode adicionar SPACE_ID e ENVIRONMENT_ID usando os argumentos --space-id e --environment-id

Usando Identidade de Aplicativo

Em vez de fornecer um token de gerenciamento, você também pode aproveitar a Identidade de Aplicativo para lidar com a autenticação. Você precisará configurar e instalar um Aplicativo Contentful e definir os seguintes parâmetros ao chamar o servidor MCP:

• --app-id = o ID do aplicativo que fornece o Apptoken
• --private-key = a chave privada que você criou na interface do usuário com seu aplicativo, vinculada a app_id
• --space-id = o spaceId no qual o aplicativo está instalado
• --environment-id = o environmentId (dentro do espaço) no qual o aplicativo está instalado.

Com esses valores, o servidor MCP solicitará um AppToken temporário para realizar operações de conteúdo no espaço/ambiente-id definido. Isso é especialmente útil ao usar este servidor MCP em sistemas de backend que atuam como clientes MCP (como agentes de chat)

Uso com Claude Desktop

Você não precisa clonar este repositório para usar este MCP; você pode simplesmente adicioná-lo ao seu claude_desktop_config.json:

Adicione ou edite ~/Library/Application Support/Claude/claude_desktop_config.json e adicione as seguintes linhas:

{
  "mcpServers": {
    "contentful": {
      "command": "npx",
      "args": ["-y", "@ivotoby/contentful-management-mcp-server"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA token>"
      }
    }
  }
}

Se o seu MCPClient não suportar a definição de variáveis de ambiente, você também pode definir o token de gerenciamento usando um argumento como este:

{
  "mcpServers": {
    "contentful": {
      "command": "npx",
      "args": [
        "-y",
        "@ivotoby/contentful-management-mcp-server",
        "--management-token",
        "<your token>",
        "--host",
        "http://api.contentful.com"
      ]
    }
  }
}

Instalação via Smithery

Para instalar o Contentful Management Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude

Desenvolvendo e usando Claude Desktop

Se você quiser contribuir e testar o que o Claude faz com suas contribuições;

• execute npm run dev, isso iniciará o observador que reconstrói o servidor MCP a cada alteração
• atualize claude_desktop_config.json para referenciar o projeto diretamente, ou seja;

{
  "mcpServers": {
    "contentful": {
      "command": "node",
      "args": ["/Users/ivo/workspace/contentful-mcp/bin/mcp-server.js"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA Token>"
      }
    }
  }
}

Isso permitirá que você teste qualquer modificação no servidor MCP diretamente com o Claude; no entanto, se você adicionar novas ferramentas/recursos, precisará reiniciar o Claude Desktop

Modos de Transporte

O servidor MCP suporta dois modos de transporte:

Transporte stdio

O modo de transporte padrão usa fluxos de entrada/saída padrão para comunicação. Isso é ideal para integração com clientes MCP que suportam transporte stdio, como o Claude Desktop.

Para usar o modo stdio, basta executar o servidor sem a flag --http:

npx -y contentful-mcp --management-token YOUR_TOKEN
# or alternatively
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

Transporte StreamableHTTP

O servidor também suporta o transporte StreamableHTTP conforme definido no protocolo MCP. Esse modo é útil para integrações baseadas na web ou quando o servidor é executado como um serviço independente.

Para usar o modo StreamableHTTP, execute com a flag --http:

npx -y contentful-mcp --management-token YOUR_TOKEN --http --port 3000
# or alternatively
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000

Detalhes do StreamableHTTP

• Usa o transporte oficial MCP StreamableHTTP
• Suporta operações padrão do protocolo MCP
• Inclui gerenciamento de sessão para manter o estado
• Lida corretamente com padrões de inicialização/notificação
• Compatível com clientes MCP padrão
• Substitui o transporte SSE obsoleto pela abordagem moderna

A implementação segue a especificação padrão do protocolo MCP, permitindo que qualquer cliente MCP se conecte ao servidor sem tratamento especial.

Tratamento de Erros

O servidor implementa tratamento abrangente de erros para:

• Falhas de autenticação
• Limitação de taxa
• Solicitações inválidas
• Problemas de rede
• Erros específicos da API

Licença

MIT License

Nota final

Este servidor MCP permite que o Claude (ou outros agentes que possam consumir recursos MCP) atualize, exclua conteúdo, espaços e modelos de conteúdo. Portanto, tenha certeza do que você permite que o Claude faça com seus espaços Contentful!

Este servidor MCP não é oficialmente suportado pela Contentful (ainda)