Hilo MCP

Servidor MCP para integrarse con Hilo, la plataforma de mensajería por WhatsApp de Cenzontle.

Su objetivo es acompañar a tu agente mientras construye la integración: le da el contrato real de la API, herramientas para verificar su propio trabajo y un plan a seguir. Le dices «créame la integración con Hilo» y se pone a construirlo.

Opera en sandbox por defecto. Con una key de pruebas (hilo_sbx_…) los envíos no se cobran y solo llegan al número autorizado. Para operar en producción hace falta un opt-in explícito — ver Producción.

Requisitos

• Node 20 o superior.

• Una API key de sandbox (hilo_sbx_…). No hay registro en autoservicio: el operador de Hilo crea la cuenta y la entrega.

El servidor arranca sin key: el agente puede leer el contrato y avanzar en el código mientras la consigues, y te dirá exactamente qué pedir.

Related MCP server: lingtai-whatsapp

Instalación

No necesitas instalar nada: npx lo descarga al vuelo. Agrega esto a la configuración MCP de tu cliente.

Claude Code (.mcp.json del proyecto, o ~/.claude.json):

{
  "mcpServers": {
    "hilo": {
      "command": "npx",
      "args": ["-y", "@cenzontle/hilo-mcp"],
      "env": { "HILO_API_KEY": "hilo_sbx_tu_key_aqui" }
    }
  }
}

Claude Desktop (claude_desktop_config.json): mismo bloque.

Reinicia el cliente. Deberías ver las herramientas hilo_*, los recursos hilo:// y el prompt integrar_con_hilo.

Variables de entorno

Qué hace

Le da al agente el contrato de la API, herramientas para verificar su propio trabajo y un plan. La idea es que puedas decir "créame la integración con Hilo" y no tener que supervisarlo.

El plan

El prompt integrar_con_hilo le da al agente el orden completo: credencial → plantillas reales → diseño → implementación → verificación → cierre. En Claude Code aparece como /hilo:integrar_con_hilo, o simplemente pídeselo en tus palabras.

El contrato (recursos)

Se leen sin API key: el agente puede avanzar en el código mientras consigues la credencial.

Verificación (no necesitan key)

Contra tu cuenta

Los envíos van marcados como destructivos: tu cliente MCP debería pedirte confirmación.

Dar de alta plantillas no está incluido: se crean en la cuenta real de WhatsApp, las revisa Meta y no tienen ambiente de pruebas. Coordínalas con el operador.

Cómo se usa

Instálalo, ábrelo en tu proyecto y pide la integración:

«Créame la integración con Hilo.»

El agente lee el contrato, corre hilo_diagnose, y si no hay credencial te dice exactamente qué pedirle al operador. Con la key de sandbox puesta, implementa el cliente, el envío y el handler del webhook, y verifica su propio trabajo: valida payloads contra las plantillas reales, manda un mensaje de prueba al número autorizado y comprueba que tu handler acepta un evento firmado y rechaza uno falso.

También sirve suelto:

«¿Por qué mi webhook rechaza los eventos de Hilo?» «Valida este broadcast antes de que lo mande.» «¿Cómo va el broadcast de la boda de Ana?»

Sandbox

Es el modo por defecto. Con una key hilo_sbx_…:

• Los envíos no se cobran.

• Solo llegan al número de prueba que el operador autorizó.

• Hay un tope de mensajes por cuenta.

• hilo_send_broadcast está deshabilitado — usa hilo_send_message para probar.

Todo lo demás —consultar plantillas, estados, broadcasts y saldo— funciona igual que en producción.

Producción

Cuando el operador te entregue tu key productiva, cambia dos cosas en la configuración:

"env": {
  "HILO_API_KEY": "hilo_tu_key_productiva",
  "HILO_ALLOW_PRODUCTION": "true"
}

Las herramientas son exactamente las mismas: lo que construiste y probaste en sandbox sigue funcionando sin tocar una línea. Lo que cambia es que los envíos son reales, se cobran, llegan a cualquier número y se habilita hilo_send_broadcast.

El opt-in existe a propósito: sin él, instalar este servidor nunca puede provocar un envío real por accidente.

Desarrollo

pnpm install
pnpm test         # 43 tests, sin red
pnpm typecheck
pnpm build

Para probar contra un Hilo local:

HILO_API_KEY=hilo_sbx_dev HILO_BASE_URL=http://localhost:3000 node dist/index.js

Estructura

src/
  config.ts          Lectura y validación del entorno
  client.ts          Cliente HTTP de la API v1 (único punto que hace fetch)
  server.ts          Registra recursos, prompt y herramientas
  index.ts           Entrypoint stdio
  reference/         Contrato y guías que se sirven como recursos MCP
  tools/             Una familia de herramientas por archivo

La lógica de herramientas no conoce el transporte, así que añadir un entrypoint HTTP remoto más adelante no obliga a tocarlas.

Licencia

MIT