Headlesshost MCP

CMS headless com foco em agentic first

Documentação

Headlesshost MCP Server

Um servidor Model Context Protocol (MCP) que fornece comunicação completa com a API da plataforma Headlesshost. Este servidor permite que assistentes de IA gerenciem sites de conteúdo, sites de staging, páginas, seções, públicos, usuários e uploads de arquivos por meio da plataforma Headlesshost.

Construído com @modelcontextprotocol/sdk v1.26 e inclui anotações de ferramentas, registro estruturado e validação de entrada via Zod.

Demonstração

https://www.youtube.com/watch?v=xGGwcrI7gSo&feature=youtu.be

Instalação

Clone este repositório
Instale as dependências:
```
npm install
```
Compile o servidor:
```
npm run build
```

Configuração

O servidor requer uma chave de API do Headlesshost definida por meio da variável de ambiente HEADLESSHOST_API_KEY.

Uso

Com Claude Desktop

Adicione esta configuração ao arquivo de configuração do Claude Desktop:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Desenvolvimento local

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "node",
      "args": ["/path/to/kapiti.mcp/build/index.js"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

Via npx

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "npx",
      "args": ["headlesshost-mcp-server@latest"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

Com Claude Code

Adicione ao seu .claude/settings.json:

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "node",
      "args": ["/path/to/kapiti.mcp/build/index.js"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

Com Outros Clientes MCP

Este servidor é compatível com qualquer cliente MCP, incluindo VS Code, Zed Editor, Continue.dev e implementações MCP personalizadas.

Configure seu cliente para usar:

Comando: node
Args: ["/path/to/kapiti.mcp/build/index.js"]
Ambiente: Defina HEADLESSHOST_API_KEY

Ferramentas (53)

Todas as ferramentas incluem anotações MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) para ajudar os clientes a apresentar UI e prompts de confirmação apropriados.

Gerais (3)

Ferramenta	Descrição
`ping`	Testa autenticação e conexão
`health`	Verifica o status de saúde da API
`get_ref_data`	Obtém dados de referência do sistema e consultas

Gerenciamento de Usuários (4)

Ferramenta	Descrição
`create_user`	Cria um novo usuário na conta atual
`get_user`	Obtém detalhes do usuário por ID
`update_user`	Atualiza informações e claims do usuário
`delete_user`	Exclui um usuário do sistema

Gerenciamento de Conta (3)

Ferramenta	Descrição
`create_account`	Cria uma nova conta de usuário
`get_account`	Obtém informações da conta atual
`update_account`	Atualiza informações da conta

Uploads de Arquivos (3)

Ferramenta	Descrição
`upload_user_profile_image`	Envia uma imagem de perfil para um usuário
`upload_staging_site_file`	Envia um arquivo para um site de staging
`upload_staging_site_image`	Envia uma imagem para um site de staging

Sites de Conteúdo (5)

Ferramenta	Descrição
`create_content_site`	Cria um novo site de conteúdo
`get_content_sites`	Obtém todos os sites de conteúdo da conta
`get_content_site`	Obtém detalhes do site de conteúdo por ID
`update_content_site`	Atualiza informações do site de conteúdo
`delete_content_site`	Exclui um site de conteúdo

Sites de Staging (9)

Ferramenta	Descrição
`update_staging_site`	Atualiza informações do site de staging
`delete_staging_site`	Exclui um site de staging
`publish_staging_site`	Publica um site de staging para colocá-lo no ar
`get_staging_site`	Obtém detalhes do site de staging
`get_staging_site_pages`	Obtém páginas do site de staging
`get_staging_site_configuration`	Obtém a configuração do site de staging, incluindo tipos de seção
`get_staging_site_logs`	Obtém logs de alterações desde a última publicação
`get_published_sites`	Obtém sites publicados para um site de conteúdo
`revert_staging_site`	Reverte um site de staging para um estado anterior
`clone_staging_site`	Clona um site de staging

Páginas (6)

Ferramenta	Descrição
`create_staging_site_page`	Cria uma nova página
`get_staging_site_page`	Obtém detalhes da página (com seções opcionais)
`update_staging_site_page`	Atualiza uma página
`delete_staging_site_page`	Exclui uma página
`revert_staging_site_page`	Reverte uma página para um estado anterior
`get_staging_site_page_logs`	Obtém logs de alterações da página desde a última publicação

Seções (7)

Ferramenta	Descrição
`create_staging_site_section`	Cria uma nova seção em uma página
`get_staging_site_section`	Obtém detalhes da seção
`update_staging_site_section`	Atualiza uma seção
`delete_staging_site_section`	Exclui uma seção
`publish_staging_site_section`	Publica uma única seção
`revert_staging_site_section`	Reverte uma seção para um estado anterior
`get_staging_site_section_logs`	Obtém logs de alterações da seção desde a última publicação

Públicos do Site (4)

Ferramenta	Descrição
`create_staging_site_audience`	Cria um público (combinação de localidade/segmento) para um site
`get_staging_site_audience`	Obtém detalhes do público
`update_staging_site_audience`	Atualiza um público
`delete_staging_site_audience`	Exclui um público (o público base não pode ser excluído)

Públicos de Seção (4)

Ferramenta	Descrição
`create_staging_site_section_audience`	Cria uma substituição de público para uma seção
`get_staging_site_section_audience`	Obtém detalhes do público da seção
`update_staging_site_section_audience`	Atualiza uma substituição de público da seção
`delete_staging_site_section_audience`	Exclui uma substituição de público da seção

Analytics (4)

Ferramenta	Descrição
`get_content_site_logs`	Obtém os últimos 15 logs de atividade
`get_content_site_hits`	Obtém análises diárias de acessos
`get_content_site_accounts`	Obtém contas associadas
`get_content_site_claims`	Obtém claims do usuário atual

Recursos

O servidor fornece 2 recursos para configuração e monitoramento:

Configuração da API (config://api) — Endpoints disponíveis e configurações atuais
Status de Saúde da API (health://api) — Conectividade em tempo real e tempo de resposta

Desenvolvimento

Compile o servidor:

npm run build

Execute em modo de desenvolvimento:

npm run dev

Monitore alterações:

npm run watch

Execute o inspetor MCP para depuração:

npm run inspector

Tratamento de Erros

O servidor inclui tratamento estruturado de erros:

Validação de autenticação da API
Verificações de conectividade de rede
Registro estruturado via capacidade de logging do MCP (erros são enviados ao cliente)
Fallbacks suaves para timeouts da API

Segurança

Autenticação por chave de API exigida para todas as operações
Tratamento seguro de variáveis de ambiente
Validação de entrada via schemas Zod em todas as entradas das ferramentas
Anotações de ferramentas sinalizam operações destrutivas aos clientes