@botozap/mcp 0.1.0 → 0.2.1

package/README.md

@@ -4,67 +4,107 @@ Servidor **MCP (Model Context Protocol)** para a API pública do **BotoZap** —
 plataforma dev-first sobre a WhatsApp Cloud API oficial (multi-tenant, a "Kapso
 brasileira").
 
-Ele expõe as operações da plataforma (`/api/v1`) como **ferramentas MCP**, para
-que assistentes como **Claude Code**, **Cursor** e **Codex** consigam enviar
-mensagens, gerenciar contatos/clientes/números, criar templates e webhooks etc.
+Ele expõe as operações da plataforma (`/api/v1`) como **ferramentas MCP** e o
+stream durável de Eventos como **resource assinável**, para que assistentes como
+**Claude Code**, **Cursor** e **Codex** consigam operar o canal e receber um
+sinal de baixa latência quando o WhatsApp mudar.
 
 Cada ferramenta MCP mapeia para uma operação do SDK oficial **`@botozap/sdk`**
 (que autentica com a sua chave `bz_...`, monta a requisição e trata o envelope de
-erro). É uma ponte fina: valida os argumentos (zod), delega ao SDK e devolve o
-JSON da API.
+erro). É uma ponte fina: valida os argumentos e resultados (zod), delega ao SDK
+e devolve o JSON da API.
 
-> **Status: em preparação — ainda NÃO publicado no npm.** Use a partir do
-> monorepo (build local), como abaixo.
+Todas as tools anunciam `outputSchema` e devolvem o resultado em
+`structuredContent`, além do `content[].text` em JSON mantido para clientes
+antigos. Isso inclui paginação por cursor/offset, operações de gestão e os
+`DELETE` sem corpo — estes preservam `null` no texto legado e devolvem
+`{ success: true }` na saída estruturada. Erros preservam `isError` e também
+expõem `{ error: { code, message, status } }` em `structuredContent`, sem
+credenciais.
+
+> **Status: preview público `0.x`.** Sem promessa de estabilidade de tools e
+> argumentos até a `1.0`; fixe a versão para integrações reproduzíveis.
 
 ## Requisitos
 
-- **Node.js ≥ 20** (ESM).
+- **Node.js ≥ 20.19** (ESM).
 - Uma chave de API do BotoZap (gere em **/chaves** no painel).
 - **pnpm** (este monorepo usa pnpm exclusivamente).
 
-## Build
+## Instalação
 
-Este pacote vive no monorepo `botozap-js` e depende de `@botozap/sdk`
-(`workspace:*`). Instale as dependências na **raiz** do monorepo e então compile:
+O pacote pode ser executado diretamente do npm:
 
 ```bash
-# na raiz do monorepo botozap-js
-pnpm install
-pnpm --filter @botozap/mcp build
+pnpm dlx @botozap/mcp@0.1.0
 ```
 
-> Não use `--ignore-workspace`: o pacote precisa resolver `@botozap/sdk` pelo
-> workspace.
-
-Smoke test (monta o servidor e lista as ferramentas, **sem** chamar a API real):
+Para desenvolver o monorepo localmente:
 
 ```bash
+pnpm install
+pnpm build
 pnpm --filter @botozap/mcp smoke
-```
-
-Testes (vitest, sem rede):
-
-```bash
 pnpm --filter @botozap/mcp test
 ```
 
 ## Configuração (variáveis de ambiente)
 
-| Variável            | Obrigatória | Default                              | Descrição                                  |
-| ------------------- | ----------- | ------------------------------------ | ------------------------------------------ |
-| `BOTOZAP_API_KEY`   | **Sim**     | —                                    | Sua chave `bz_...` (header `Authorization: Bearer`). |
-| `BOTOZAP_API_URL`   | Não         | `https://botozap.com.br/api/v1`      | Base da API (útil para staging/local).      |
+| Variável | Quando | Default | Descrição |
+| --- | --- | --- | --- |
+| `BOTOZAP_API_KEY` | Obrigatória em stdio | — | Chave `bz_...` usada pelo processo stdio. |
+| `BOTOZAP_API_URL` | Opcional | `https://botozap.com.br/api/v1` | Base da API (útil para staging/local). |
+| `BOTOZAP_MCP_TRANSPORT` | Remoto | `stdio` | Use `streamable-http` para iniciar o endpoint remoto. |
+| `BOTOZAP_MCP_HOST` | Remoto | `127.0.0.1` | Interface TCP do endpoint remoto. |
+| `BOTOZAP_MCP_PORT` | Remoto | `3001` | Porta do endpoint remoto (`0` escolhe uma porta livre). |
+| `BOTOZAP_EVENT_BUS_DATABASE_URL` | Obrigatória no remoto | — | Conexão PostgreSQL de sessão que suporta `LISTEN/NOTIFY`. |
 
-Sem `BOTOZAP_API_KEY` o servidor falha imediatamente com uma mensagem clara.
+Sem a configuração obrigatória do transporte escolhido, o servidor falha
+imediatamente com uma mensagem clara e sem imprimir o valor recebido.
+
+### Streamable HTTP (operador da plataforma)
+
+O mesmo binário pode manter sessões remotas stateful em `/mcp`. Nesse modo cada
+cliente envia sua própria chave BotoZap no header `Authorization: Bearer`; a
+sessão fica vinculada a essa credencial e a Conta/ambiente continuam derivados
+pela API. A chave nunca entra na URL do endpoint, URI do resource ou
+notification.
+
+```bash
+BOTOZAP_MCP_TRANSPORT=streamable-http \
+BOTOZAP_MCP_HOST=0.0.0.0 \
+BOTOZAP_MCP_PORT=3001 \
+BOTOZAP_EVENT_BUS_DATABASE_URL=postgresql://... \
+pnpm dlx @botozap/mcp@0.1.0
+```
+
+Use uma conexão PostgreSQL persistente/direta ou pooler em modo de sessão;
+pooler em modo de transação não preserva `LISTEN`. O bus carrega somente um
+sinal vazio. Ao recebê-lo, cada sessão consulta `/events` com sua própria chave
+e só envia `notifications/resources/updated` se houver Evento no cursor
+autorizado. O payload autoritativo permanece no stream durável.
+
+Se o bus cair — inclusive durante o boot — o servidor continua disponível em
+modo degradado, reconecta com backoff de 250 ms a 10 s e mantém um heartbeat de
+reconciliação pelo cursor a cada 15 s. Um sinal que chega enquanto outra leitura
+está em voo fica pendente para um novo probe imediato; não depende do próximo
+heartbeat.
+
+O processo mantém no máximo 1.000 sessões, 5 sessões por chave e 8 resources de
+Eventos por sessão. `resources/unsubscribe` interrompe o consumo daquele
+resource; `DELETE /mcp` encerra a sessão e libera listeners/timers. Uma sessão
+que perde o transporte sem enviar `DELETE` é recolhida após 5 minutos sem
+request ativo (varredura a cada 30 s). Esses limites são conservadores para o
+preview `0.x` e podem mudar antes da `1.0`.
 
 ## Usar com Claude Code
 
-Via CLI (caminho **absoluto** para o `dist/index.js` compilado):
+Via CLI:
 
 ```bash
 claude mcp add botozap \
   --env BOTOZAP_API_KEY=bz_live_suachaveaqui \
-  -- node /caminho/absoluto/para/botozap-js/packages/mcp/dist/index.js
+  -- pnpm dlx @botozap/mcp@0.1.0
 ```
 
 Ou no JSON do MCP (`.mcp.json` do projeto ou config do usuário):
@@ -73,8 +113,8 @@ Ou no JSON do MCP (`.mcp.json` do projeto ou config do usuário):
 {
   "mcpServers": {
     "botozap": {
-      "command": "node",
-      "args": ["/caminho/absoluto/para/botozap-js/packages/mcp/dist/index.js"],
+      "command": "pnpm",
+      "args": ["dlx", "@botozap/mcp@0.1.0"],
       "env": {
         "BOTOZAP_API_KEY": "bz_live_suachaveaqui"
       }
@@ -91,8 +131,8 @@ Edite `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (no projeto):
 {
   "mcpServers": {
     "botozap": {
-      "command": "node",
-      "args": ["/caminho/absoluto/para/botozap-js/packages/mcp/dist/index.js"],
+      "command": "pnpm",
+      "args": ["dlx", "@botozap/mcp@0.1.0"],
       "env": {
         "BOTOZAP_API_KEY": "bz_live_suachaveaqui"
       }
@@ -103,13 +143,13 @@ Edite `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (no projeto):
 
 ## Ferramentas disponíveis
 
-Transporte: **stdio**. Nomes em inglês (snake_case, melhor para tool-calling);
-descrições em PT-BR.
+Transportes: **stdio** (padrão, local) e **Streamable HTTP** (remoto stateful).
+Nomes em inglês (snake_case, melhor para tool-calling); descrições em PT-BR.
 
 **Mensagens** — `send_message`, `list_messages`, `get_message`
-**Conversas** — `list_conversations`, `get_conversation`, `update_conversation`
+**Conversas** — `reply_to_conversation`, `list_conversations`, `get_conversation`, `update_conversation`
 **Contatos** — `list_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact`
-**Mídia** — `ingest_media`
+**Mídia** — `send_media_message`, `ingest_media`
 **Clientes** — `list_customers`, `get_customer`, `create_customer`, `update_customer`, `delete_customer`
 **Links de setup** — `list_setup_links`, `create_setup_link`, `update_setup_link`
 **Números** — `list_phone_numbers`, `get_phone_number`, `phone_number_health`
@@ -119,16 +159,44 @@ descrições em PT-BR.
 **Logs** — `list_api_logs`
 **Usuários** — `list_users`
 
+## Resource de Eventos
+
+Os dois transportes anunciam `resources.subscribe` e o template
+`botozap://events{?after,limit}`. Um cliente persistente pode assinar, por
+exemplo, `botozap://events?after=42&limit=100` e receber
+`notifications/resources/updated` quando existir um Evento posterior ao cursor
+42. O tail da API existe somente enquanto há assinatura ativa; clientes que usam
+apenas tools não iniciam consultas de Eventos. A chave usada pelo servidor
+precisa incluir o escopo `events:read`.
+
+A notification é deliberadamente só um sinal e não carrega mensagem, Contato
+ou credencial. Ao recebê-la, releia o mesmo resource, processe `data` e persista
+`paging.cursor`. Depois de uma desconexão, leia a partir do último cursor salvo e
+drene todas as páginas de catch-up (`paging.next`). Só então assine uma nova URI
+com o cursor final em `after`; o probe inicial da assinatura fecha a corrida com
+um Evento persistido entre a última leitura e o subscribe. Notifications são
+hints at-least-once e podem se repetir; deduplique por `event.id` antes de
+produzir qualquer resposta. O mesmo Evento conserva `id`, `cursor` e identidade
+de mensagem em retries e replay.
+
+No stdio, o tail usa intervalo padrão de 1,5 segundo e para no `unsubscribe` ou
+no fim da sessão. No remoto, o PostgreSQL acorda o processo MCP mesmo quando o
+Evento foi persistido por outra instância; a consulta escopada continua sendo a
+fonte do payload e o heartbeat cobre sinais perdidos. Receber a notification não
+significa que todo host inicia automaticamente uma nova execução do agente.
+
 Em caso de erro da API, a ferramenta devolve um resultado de erro (`isError`) com
 a mensagem PT-BR do envelope `{ error: { code, message } }` no formato
-`Erro [code]: message`.
+`Erro [code]: message`. `code`, `message` e o status HTTP também ficam
+disponíveis de forma programática em todas as tools.
 
 ## Chaves de sandbox
 
-Uma chave de **sandbox** (prefixo `bz_sandbox_`) só habilita as ferramentas de
-mensagem: `send_message`, `list_messages` e `get_message`. Qualquer outra
-ferramenta responde `403 sandbox_forbidden` (vindo da API) — útil para testar a
-integração de envio sem tocar dados reais.
+Uma chave de **sandbox** (prefixo `bz_sandbox_`) habilita as ferramentas de
+mensagem (`send_message`, `send_media_message`, `list_messages` e `get_message`) e o resource de
+Eventos do próprio Sandbox. Qualquer outra ferramenta responde
+`403 sandbox_forbidden` (vindo da API) — útil para testar a integração sem tocar
+dados reais.
 
 **Números mágicos** (destinatários simulados, sem custo, sem número real):
 

package/dist/event-bus.d.ts

@@ -0,0 +1,14 @@
+import type { EventSignalSource } from "./resources/events.js";
+export interface CloseableEventSignalSource extends EventSignalSource {
+    close(): Promise<void>;
+}
+export interface PostgresEventSignalOptions {
+    maxReconnectDelayMs?: number;
+    reconnectDelayMs?: number;
+}
+/**
+ * Adapter compartilhado de baixa latência. O NOTIFY não carrega payload nem
+ * autoridade: cada sessão acordada relê `/events` com sua própria chave.
+ * Quedas do socket refazem a conexão e o LISTEN com backoff limitado.
+ */
+export declare function connectPostgresEventSignal(connectionString: string, options?: PostgresEventSignalOptions): Promise<CloseableEventSignalSource>;

package/dist/event-bus.js

@@ -0,0 +1,128 @@
+import pg from "pg";
+const CHANNEL = "botozap_account_events";
+/**
+ * Adapter compartilhado de baixa latência. O NOTIFY não carrega payload nem
+ * autoridade: cada sessão acordada relê `/events` com sua própria chave.
+ * Quedas do socket refazem a conexão e o LISTEN com backoff limitado.
+ */
+export async function connectPostgresEventSignal(connectionString, options = {}) {
+    const signal = new PostgresEventSignal(connectionString, options);
+    await signal.start();
+    return signal;
+}
+class PostgresEventSignal {
+    connectionString;
+    active;
+    closed = false;
+    connecting;
+    listeners = new Set();
+    reconnectAttempt = 0;
+    reconnectTimer;
+    reconnectDelayMs;
+    maxReconnectDelayMs;
+    constructor(connectionString, options) {
+        this.connectionString = connectionString;
+        this.reconnectDelayMs = Math.max(1, options.reconnectDelayMs ?? 250);
+        this.maxReconnectDelayMs = Math.max(this.reconnectDelayMs, options.maxReconnectDelayMs ?? 10_000);
+    }
+    async start() {
+        await this.connect().catch(() => this.scheduleReconnect());
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.listeners.clear();
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        const active = this.active;
+        if (active) {
+            this.detach(active);
+            await active.client.end().catch(() => { });
+        }
+        await this.connecting?.catch(() => { });
+    }
+    connect() {
+        if (this.closed)
+            return Promise.resolve();
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.openClient().finally(() => {
+            this.connecting = undefined;
+        });
+        return this.connecting;
+    }
+    async openClient() {
+        const client = new pg.Client({
+            connectionString: this.connectionString,
+            application_name: "botozap-mcp-event-bus",
+        });
+        const active = {
+            client,
+            onEnd: () => this.handleDisconnect(active),
+            onError: () => this.handleDisconnect(active),
+            onNotification: (message) => {
+                if (this.active !== active || message.channel !== CHANNEL)
+                    return;
+                for (const listener of [...this.listeners]) {
+                    try {
+                        listener();
+                    }
+                    catch {
+                        // Uma sessão defeituosa não impede as demais de receber o sinal.
+                    }
+                }
+            },
+        };
+        this.active = active;
+        client.on("error", active.onError);
+        client.on("end", active.onEnd);
+        client.on("notification", active.onNotification);
+        try {
+            await client.connect();
+            await client.query(`LISTEN ${CHANNEL}`);
+            if (this.closed || this.active !== active) {
+                this.detach(active);
+                await client.end().catch(() => { });
+                return;
+            }
+            this.reconnectAttempt = 0;
+        }
+        catch (error) {
+            this.detach(active);
+            await client.end().catch(() => { });
+            throw error;
+        }
+    }
+    handleDisconnect(active) {
+        if (this.closed || this.active !== active)
+            return;
+        this.detach(active);
+        void active.client.end().catch(() => { });
+        this.scheduleReconnect();
+    }
+    detach(active) {
+        active.client.removeListener("error", active.onError);
+        active.client.removeListener("end", active.onEnd);
+        active.client.removeListener("notification", active.onNotification);
+        if (this.active === active)
+            this.active = undefined;
+    }
+    scheduleReconnect() {
+        if (this.closed || this.reconnectTimer)
+            return;
+        const delay = Math.min(this.reconnectDelayMs * 2 ** this.reconnectAttempt, this.maxReconnectDelayMs);
+        this.reconnectAttempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            void this.connect().catch(() => this.scheduleReconnect());
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+}
+//# sourceMappingURL=event-bus.js.map

package/dist/event-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../src/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/http.d.ts

@@ -0,0 +1,31 @@
+import type { EventSignalSource } from "./resources/events.js";
+export type { EventSignalSource } from "./resources/events.js";
+export interface StreamableHttpServerOptions {
+    baseUrl: string;
+    eventSignal: EventSignalSource;
+    /** Reconciliação periódica que cobre sinais perdidos/indisponibilidade do bus. */
+    eventPollIntervalMs?: number;
+    fetch?: typeof fetch;
+    host?: string;
+    /** Teto de resources de Eventos por sessão. */
+    maxEventSubscriptions?: number;
+    /** Teto de sessões stateful mantidas por processo. */
+    maxSessions?: number;
+    /** Teto de sessões simultâneas ligadas à mesma chave. */
+    maxSessionsPerApiKey?: number;
+    port?: number;
+    /** Tempo sem request ativo antes de recolher uma sessão abandonada. */
+    sessionIdleTimeoutMs?: number;
+    /** Frequência da varredura de sessões abandonadas. */
+    sessionSweepIntervalMs?: number;
+}
+export interface RunningStreamableHttpServer {
+    url: URL;
+    close(): Promise<void>;
+}
+/**
+ * Inicia um endpoint MCP remoto stateful. Cada sessão é criada a partir da
+ * chave Bearer do initialize e fica presa ao mesmo fingerprint nos requests
+ * seguintes; a autoridade da Conta continua sendo derivada pela API BotoZap.
+ */
+export declare function startStreamableHttpServer(options: StreamableHttpServerOptions): Promise<RunningStreamableHttpServer>;