# Hilo MCP

Servidor [MCP](https://modelcontextprotocol.io) 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](#producción).

## Instalar en un comando

**Claude Code:**

```bash
claude mcp add hilo -e HILO_API_KEY=hilo_sbx_TU_KEY -- npx -y @cenzontle/hilo-mcp
```

Después **reinicia Claude Code** (los servidores MCP se cargan al arrancar) y pide:

> Créame la integración con Hilo.

¿Aún no tienes la key? Instálalo igual, sin `-e`: el servidor arranca de todos modos, el agente puede leer el contrato de la API e ir escribiendo el código, y `hilo_diagnose` te dirá exactamente qué pedirle al operador de Hilo.

## 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.

## Instalación manual

Si prefieres versionar la configuración con tu proyecto en vez de usar el comando de arriba. No necesitas instalar nada: `npx` descarga el paquete al vuelo.

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

```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

| Variable | Requerida | Default | Para qué |
|---|---|---|---|
| `HILO_API_KEY` | No (recomendada) | — | Tu API key. `hilo_sbx_…` de pruebas, `hilo_…` productiva. Sin ella el servidor arranca en modo sin credencial. |
| `HILO_ALLOW_PRODUCTION` | Solo en producción | `false` | Debe ser `true` para aceptar una key productiva. |
| `HILO_BASE_URL` | No | `https://api.hilo.cenzontle.cloud` | Solo para apuntar a otro entorno. Debe ser HTTPS (se acepta `http://localhost` para desarrollo). |
| `HILO_TIMEOUT_MS` | No | `30000` | Timeout por request. |

## 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)

| Recurso | Contenido |
|---|---|
| `hilo://api/reference` | Endpoints, cuerpos, respuestas, estados y errores |
| `hilo://api/webhook` | Firma HMAC, ejemplos en Node y Python, reglas de operación |
| `hilo://integration/guide` | Orden recomendado y los errores que se repiten |

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

### Verificación (no necesitan key)

| Herramienta | Para qué |
|---|---|
| `hilo_diagnose` | Estado de la integración y siguiente paso concreto |
| `hilo_webhook_sample` | Evento firmado real para probar **tu** handler sin exponer nada |
| `hilo_verify_webhook_signature` | Depura por qué tu handler rechaza eventos legítimos |
| `hilo_check_webhook_endpoint` | Revisa si tu URL sirve (HTTPS, host público) |

### Contra tu cuenta

| Herramienta | Para qué | Costo |
|---|---|---|
| `hilo_list_templates` / `hilo_get_template` | Qué plantillas existen y qué variables esperan | — |
| `hilo_validate_send` / `hilo_validate_broadcast` | Valida el payload contra la plantilla real, **sin enviar** | — |
| `hilo_get_usage` | Saldo y consumo | — |
| `hilo_get_message` / `hilo_list_messages` | Estados de entrega | — |
| `hilo_get_broadcast` / `hilo_list_broadcasts` | Avance de un envío masivo | — |
| `hilo_send_message` | Envío real de prueba | 1 crédito |
| `hilo_send_broadcast` | Envío masivo (solo producción) | 1 por destinatario |

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:

```json
"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

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

Para probar contra un Hilo local:

```bash
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