Headlesshost MCP

CMS sin cabeza, primero agentivo

Documentación

Servidor Headlesshost MCP

Un servidor de Model Context Protocol (MCP) que proporciona comunicación completa con la API de la plataforma Headlesshost. Este servidor permite a los asistentes de IA gestionar sitios de contenido, sitios de staging, páginas, secciones, audiencias, usuarios y cargas de archivos a través de la plataforma Headlesshost.

Construido con @modelcontextprotocol/sdk v1.26 e incluye anotaciones de herramientas, registro estructurado y validación de entrada con Zod.

Demo

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

Instalación

Clona este repositorio
Instala las dependencias:
```
npm install
```
Compila el servidor:
```
npm run build
```

Configuración

El servidor requiere una clave de API de Headlesshost configurada mediante la variable de entorno HEADLESSHOST_API_KEY.

Uso

Con Claude Desktop

Añade esta configuración a tu archivo de configuración de Claude Desktop:

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

Desarrollo local

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

Mediante npx

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

Con Claude Code

Añade a tu .claude/settings.json:

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

Con Otros Clientes MCP

Este servidor es compatible con cualquier cliente MCP, incluidos VS Code, Zed Editor, Continue.dev e implementaciones MCP personalizadas.

Configura tu cliente para usar:

Comando: node
Argumentos: ["/path/to/kapiti.mcp/build/index.js"]
Entorno: Establece HEADLESSHOST_API_KEY

Herramientas (53)

Todas las herramientas incluyen anotaciones MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) para ayudar a los clientes a presentar la interfaz de usuario y los avisos de confirmación adecuados.

General (3)

Herramienta	Descripción
`ping`	Prueba la autenticación y la conexión
`health`	Comprueba el estado de salud de la API
`get_ref_data`	Obtén datos de referencia del sistema y búsquedas

Gestión de Usuarios (4)

Herramienta	Descripción
`create_user`	Crea un nuevo usuario en la cuenta actual
`get_user`	Obtén los detalles del usuario por ID
`update_user`	Actualiza la información y los claims del usuario
`delete_user`	Elimina un usuario del sistema

Gestión de Cuentas (3)

Herramienta	Descripción
`create_account`	Crea una nueva cuenta de usuario
`get_account`	Obtén la información de la cuenta actual
`update_account`	Actualiza la información de la cuenta

Cargas de Archivos (3)

Herramienta	Descripción
`upload_user_profile_image`	Sube una imagen de perfil para un usuario
`upload_staging_site_file`	Sube un archivo a un sitio de staging
`upload_staging_site_image`	Sube una imagen a un sitio de staging

Sitios de Contenido (5)

Herramienta	Descripción
`create_content_site`	Crea un nuevo sitio de contenido
`get_content_sites`	Obtén todos los sitios de contenido de la cuenta
`get_content_site`	Obtén los detalles del sitio de contenido por ID
`update_content_site`	Actualiza la información del sitio de contenido
`delete_content_site`	Elimina un sitio de contenido

Sitios de Staging (9)

Herramienta	Descripción
`update_staging_site`	Actualiza la información del sitio de staging
`delete_staging_site`	Elimina un sitio de staging
`publish_staging_site`	Publica un sitio de staging para ponerlo en producción
`get_staging_site`	Obtén los detalles del sitio de staging
`get_staging_site_pages`	Obtén las páginas del sitio de staging
`get_staging_site_configuration`	Obtén la configuración del sitio de staging, incluidos los tipos de sección
`get_staging_site_logs`	Obtén los registros de cambios desde la última publicación
`get_published_sites`	Obtén los sitios publicados de un sitio de contenido
`revert_staging_site`	Revierte un sitio de staging a un estado anterior
`clone_staging_site`	Clona un sitio de staging

Páginas (6)

Herramienta	Descripción
`create_staging_site_page`	Crea una nueva página
`get_staging_site_page`	Obtén los detalles de la página (con secciones opcionales)
`update_staging_site_page`	Actualiza una página
`delete_staging_site_page`	Elimina una página
`revert_staging_site_page`	Revierte una página a un estado anterior
`get_staging_site_page_logs`	Obtén los registros de cambios de la página desde la última publicación

Secciones (7)

Herramienta	Descripción
`create_staging_site_section`	Crea una nueva sección en una página
`get_staging_site_section`	Obtén los detalles de la sección
`update_staging_site_section`	Actualiza una sección
`delete_staging_site_section`	Elimina una sección
`publish_staging_site_section`	Publica una sola sección
`revert_staging_site_section`	Revierte una sección a un estado anterior
`get_staging_site_section_logs`	Obtén los registros de cambios de la sección desde la última publicación

Audiencias de Sitio (4)

Herramienta	Descripción
`create_staging_site_audience`	Crea una audiencia (combinación de idioma/segmento) para un sitio
`get_staging_site_audience`	Obtén los detalles de la audiencia
`update_staging_site_audience`	Actualiza una audiencia
`delete_staging_site_audience`	Elimina una audiencia (la audiencia base no se puede eliminar)

Audiencias de Sección (4)

Herramienta	Descripción
`create_staging_site_section_audience`	Crea una anulación de audiencia para una sección
`get_staging_site_section_audience`	Obtén los detalles de la audiencia de la sección
`update_staging_site_section_audience`	Actualiza una anulación de audiencia de sección
`delete_staging_site_section_audience`	Elimina una anulación de audiencia de sección

Analíticas (4)

Herramienta	Descripción
`get_content_site_logs`	Obtén los últimos 15 registros de actividad
`get_content_site_hits`	Obtén las analíticas de visitas diarias
`get_content_site_accounts`	Obtén las cuentas asociadas
`get_content_site_claims`	Obtén los claims del usuario actual

Recursos

El servidor proporciona 2 recursos para configuración y monitoreo:

Configuración de la API (config://api) — Endpoints disponibles y configuración actual
Estado de salud de la API (health://api) — Conectividad en tiempo real y tiempo de respuesta

Desarrollo

Compila el servidor:

npm run build

Ejecuta en modo de desarrollo:

npm run dev

Observa los cambios:

npm run watch

Ejecuta el inspector MCP para depuración:

npm run inspector

Manejo de Errores

El servidor incluye manejo estructurado de errores:

Validación de autenticación de la API
Comprobaciones de conectividad de red
Registro estructurado mediante la capacidad de registro de MCP (los errores se envían al cliente)
Alternativas elegantes para tiempos de espera de la API

Seguridad

Autenticación con clave de API requerida para todas las operaciones
Manejo seguro de variables de entorno
Validación de entrada mediante esquemas Zod en todas las entradas de herramientas
Las anotaciones de herramientas señalan operaciones destructivas a los clientes