Skip to main content
Glama
@funnelchat-hq/mcp

@funnelchat-hq/mcp

by Funnelchat20
README.md
# @funnelchat-hq/mcp

El servidor MCP de la API pública de Funnelchat. Con él, tu asistente (Claude Code, Cursor u otro cliente MCP) usa tus números de WhatsApp, tus mensajes, contactos, plantillas, grupos y webhooks con tu clave de API: los mismos permisos, límites y errores que la API.

Cubre todas las llamadas que publica el [portal de desarrolladores](https://developers-portal.funnelchat.app/docs/) con 20 tools, unos 3.100 tokens en total.

## Antes de empezar

- Node 20.11 o más.
- Una clave de API: en el panel, **Desarrolladores → Crear clave**. Dale solo los permisos que necesitas. La clave va en la configuración del servidor MCP, nunca en el chat.

## Instalarlo

### Claude Code

```bash
claude mcp add funnelchat -e FUNNELCHAT_API_KEY=tu_clave -- npx -y @funnelchat-hq/mcp
```

Para que solo pueda leer, agrega `--read-only` al final:

```bash
claude mcp add funnelchat -e FUNNELCHAT_API_KEY=tu_clave -- npx -y @funnelchat-hq/mcp --read-only
```

### Cursor

En `.cursor/mcp.json` (de tu proyecto) o en `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "funnelchat": {
      "command": "npx",
      "args": ["-y", "@funnelchat-hq/mcp"],
      "env": { "FUNNELCHAT_API_KEY": "tu_clave" }
    }
  }
}
```

### Otros clientes MCP

Todos piden lo mismo: el comando `npx -y @funnelchat-hq/mcp` y la variable `FUNNELCHAT_API_KEY`.

- **Claude Desktop**: el mismo bloque `mcpServers` de Cursor, en `claude_desktop_config.json`.
- **VS Code**: en `.vscode/mcp.json`, dentro de `"servers"`, con `"type": "stdio"` y los mismos `command`, `args` y `env`.
- **Codex**: en `~/.codex/config.toml`:

  ```toml
  [mcp_servers.funnelchat]
  command = "npx"
  args = ["-y", "@funnelchat-hq/mcp"]
  env = { FUNNELCHAT_API_KEY = "tu_clave" }
  ```

Si tu cliente solo se conecta por HTTP, mira [Modo HTTP](#modo-http).

## Probarlo con el sandbox

El [sandbox](https://www.npmjs.com/package/@funnelchat-hq/sandbox) imita la API en tu máquina, sin cuenta y sin mandar nada a WhatsApp. Arráncalo en una terminal y déjalo corriendo:

```bash
npx @funnelchat-hq/sandbox
```

Y apunta el MCP a él con `FUNNELCHAT_BASE_URL`. Contra el sandbox sirve cualquier clave bien formada:

```bash
claude mcp add funnelchat-sandbox -e 'FUNNELCHAT_API_KEY=1|fc_live_sandbox' -e FUNNELCHAT_BASE_URL=http://127.0.0.1:4010 -- npx -y @funnelchat-hq/mcp
```

Sin `FUNNELCHAT_BASE_URL`, el MCP va a la API real (`https://api.funnelchat.com`). El tool `status` dice siempre a qué URL está apuntando.

## Cómo se usa

Le pides a tu asistente lo que quieres («manda un WhatsApp a…», «¿cuántas conversaciones sin leer tengo?») y él elige el tool. Empieza por `status`: dice qué números tienes conectados, si tienes webhooks y cuál es el siguiente paso.

Cada tool agrupa las llamadas de un recurso y recibe `action`, `params` y, en lo que no se deshace, `confirm`:

```json
{ "action": "help" }
{ "action": "help", "params": { "action": "send" } }
{ "action": "send", "params": { "device_id": "dev_…", "phone": "5491122334455", "text": "Hola, Ana" } }
```

`help` lista las acciones del tool; con `params.action` da los parámetros de una, con su ejemplo.

<!-- TOOLS:INICIO (lo escribe npm run generate) -->

Generado desde la spec del portal v0.7.0-49-g31766eb (sha256 `766230d4a8ce…`): 253 llamadas en 18 tools por recurso, más `status` y `search_docs`.

| Tool | Qué hace | Acciones | Lecturas | No se deshacen |
| --- | --- | ---: | ---: | ---: |
| `numbers` | Números de WhatsApp: ver, crear por QR, editar, desconectar, salud, cola de mensajes y Conversions API. | 22 | 12 | 5 |
| `connect_links` | Links para conectar un número por QR, tuyo o de un cliente, o para reconectarlo. | 4 | 2 | 1 |
| `messages` | Mandar mensajes y plantillas, ver un mensaje, marcarlo leído, reaccionar, reenviar y mandar formularios. | 11 | 1 | 0 |
| `conversations` | Conversaciones: mensajes con un contacto, listar, contar, marcar leídas y respuestas rápidas. | 13 | 8 | 1 |
| `contacts` | Contactos: ver, crear, editar y borrar, su ventana de 24 h, sus notas y su puntaje. | 16 | 8 | 2 |
| `tags` | Etiquetas: crearlas, editarlas y ponerlas o quitarlas a contactos. | 9 | 4 | 1 |
| `custom_fields` | Campos personalizados y sus valores en cada contacto. | 8 | 3 | 1 |
| `templates` | Plantillas de WhatsApp: ver, crear, editar, traer de Meta, métricas y borrar. | 7 | 3 | 1 |
| `groups` | Grupos de WhatsApp: ver, seguir, mandarles un mensaje, participantes y canales. | 11 | 9 | 0 |
| `group_actions` | Cambiar un grupo: crearlo, participantes, admins, nombre, foto, link y solicitudes. | 16 | 4 | 3 |
| `campaigns` | Campañas de grupos, envíos programados y estadísticas, solo lectura. | 28 | 28 | 0 |
| `broadcasts` | Difusiones: ver, buscar contactos, costo, estadísticas, cancelar y carpetas. | 16 | 10 | 3 |
| `automations` | Flujos: verlos, sus contactos, cancelar una ejecución, pausar a un contacto y carpetas. | 16 | 11 | 2 |
| `forms` | Formularios de WhatsApp: ver, crear, publicar, números, versiones y respuestas. | 18 | 9 | 1 |
| `boards` | Tableros: etapas y mover contactos entre ellas. | 16 | 5 | 2 |
| `tickets` | Tickets: ver, crear, editar, asignar, cerrar y reabrir. | 7 | 2 | 0 |
| `webhooks` | Webhooks: crear, ver, editar, probar y borrar, sus entregas y los tipos de evento. | 8 | 4 | 1 |
| `account` | Tu cuenta: datos, equipo, contactos activos, costos de Meta, ventas, dominios y alertas. | 27 | 20 | 1 |

<!-- TOOLS:FIN -->

`status` y `search_docs` completan los 20: `search_docs` busca en los textos del portal, que van dentro del paquete.

### Antes de llamar a la API

- **Los parámetros se revisan contra la spec**: nombres, obligatorios, tipos y valores permitidos. Si sobra o falta algo, la llamada no sale y el error dice qué corregir, con el `help` de la acción. Un filtro mal escrito nunca devuelve la lista entera.
- **Lo que no se deshace pide `confirm: true`**: borrar contactos, etiquetas o campos, cancelar una difusión, desconectar o borrar un número, sacar personas de un grupo… Sin `confirm`, el MCP no llama a la API y le pide al asistente que te pregunte primero. `help` marca esas acciones con «no se deshace».
- **`--read-only`** deja solo las lecturas: no crea, no cambia ni borra nada, y tampoco da el QR de un número, porque con él se toma el control del número.

### Errores

Un error vuelve marcado como error y con el cuerpo de la API: `status`, `error` (un código estable), `message`, y según el caso `errors` por campo o `retry_after` en segundos. Los errores del propio MCP, antes de llamar, son `unknown_params`, `invalid_params`, `confirmation_required`, `read_only` y `missing_api_key`.

## Modo HTTP

Para hospedarlo o para clientes que solo hablan HTTP:

```bash
npx -y @funnelchat-hq/mcp --http --port 3333
```

- Escucha en `POST http://127.0.0.1:3333/mcp`, sin sesión.
- Cada pedido trae su clave en `Authorization: Bearer <clave>` (o `X-API-Key`). Sin clave responde `401`: en este modo `FUNNELCHAT_API_KEY` no se usa.
- Revisa `Host` y `Origin` de cada pedido, para que una página web no pueda usarlo (DNS rebinding). Por defecto acepta `127.0.0.1`, `localhost` y `[::1]` con su puerto.
- Para escuchar fuera de tu máquina tienes que decir con qué nombre te llegan los pedidos:

  ```bash
  npx -y @funnelchat-hq/mcp --http --host 0.0.0.0 --port 3333 \
    --allowed-hosts mcp.tu-dominio.com --allowed-origins https://app.tu-dominio.com
  ```

  Ponlo detrás de un proxy con HTTPS: la clave viaja en cada pedido.

- `GET /health` responde `{"ok": true}`.

## Opciones

| Opción                    | Variable              | Qué hace                                                                                                                                                                                |
| ------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|                           | `FUNNELCHAT_API_KEY`  | La clave, en stdio.                                                                                                                                                                     |
| `--base-url <url>`        | `FUNNELCHAT_BASE_URL` | El host de la API. Por defecto `https://api.funnelchat.com`; el sandbox, `http://127.0.0.1:4010`. Si termina en `/api/v1`, `/api` o `/v1`, se quita. `FUNNELCHAT_API_URL` también vale. |
| `--read-only`             |                       | Solo lecturas.                                                                                                                                                                          |
| `--http`                  |                       | HTTP en vez de stdio.                                                                                                                                                                   |
| `--host <host>`           |                       | Dónde escucha en HTTP. Por defecto `127.0.0.1`.                                                                                                                                         |
| `--port <n>`              | `PORT`                | El puerto en HTTP. Por defecto `3333`.                                                                                                                                                  |
| `--allowed-hosts <a,b>`   | `MCP_ALLOWED_HOSTS`   | Los `Host` que acepta en HTTP.                                                                                                                                                          |
| `--allowed-origins <a,b>` | `MCP_ALLOWED_ORIGINS` | Los `Origin` que acepta en HTTP.                                                                                                                                                        |
| `--version`, `--help`     |                       | La versión y la ayuda.                                                                                                                                                                  |

## La spec y las versiones

Los tools salen de la spec que publica el portal (`spec/funnelchat.json`). De dónde salió, con su versión del portal y su `sha256`, está en `spec/procedencia.json`, que va dentro del paquete; `status` también la dice. Qué no se deshace, y qué se pierde, lo dice la spec con `x-fc-destructive`. Lo único escrito a mano es `diseno.json`: qué grupos del portal van a cada tool, algunos nombres de acción, lo poco que pide confirmación aunque la spec no lo marque y los ejemplos de las acciones principales.

Una versión nueva de la spec es una versión nueva del paquete. Las acciones no cambian de nombre entre versiones: si una tuviera que cambiar, sale en una versión mayor.

## Desarrollo

```bash
npm ci
npm test                                         # pruebas unitarias, sin red
npx @funnelchat-hq/sandbox --port 4010           # en otra terminal
SANDBOX_URL=http://127.0.0.1:4010 npm run test:e2e   # contra el sandbox: stdio, HTTP, el ejemplo de cada acción y la prueba adversaria
npm run test:pack                                # npm pack, instalarlo en un proyecto vacío y correrlo con npx
npm run measure                                  # cuántos tokens cargan los tools
```

Con una spec nueva del portal:

```bash
npm run generate -- --spec <ruta>/funnelchat.json   # la copia a spec/, anota su procedencia y regenera generated/tabla.json
npm run docs -- --portal <carpeta del portal construido>   # regenera docs/indice.json, lo que busca search_docs
```

Si el archivo no viene de un checkout del portal, di de dónde salió con `--source url=… --source portal_version=…`. `npm run generate:check` y `npm run docs:check` fallan si algo no está al día, si `docs/` ofrece lo que no existe o si la spec y la doc salieron de portales distintos; el CI corre los dos.

Para publicar, sube un tag `vX.Y.Z` igual a la versión de `package.json` sobre un commit de `main`: `publish.yml` corre el CI y publica en npm con provenance.

## Licencia

MIT