docs: registra MCP Server standalone de mensageria Z-PRO (Z-PRO)

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-11 15:24:45 -03:00
parent 6f3a509df5
commit 637951d6e2
1 changed files with 77 additions and 0 deletions
@@ -559,3 +559,80 @@ persistida em Postgres. Padrão pronto pra replicar em
 Klingo/SysLife/ClinicAll quando esses tiverem workflow de agente — cada
 um com seu próprio banco dentro do mesmo container e sua própria
 credencial.
+
+## 17. MCP Server standalone de Mensageria (Z-PRO) — reusável por qualquer provider
+
+**Data:** 11/08/2026. Ver design completo em
+`docs/superpowers/specs/2026-08-11-mcp-server-mensageria-zpro-design.md`
+e plano em
+`docs/superpowers/plans/2026-08-11-mcp-server-mensageria-zpro.md`.
+
+**Motivação**: a feature de "confirmação de agenda" (Klingo) precisa
+disparar mensagens de WhatsApp de forma proativa — capacidade que ainda
+não existia no projeto (tudo até então era resposta reativa a webhook).
+Decisão explícita do usuário: em vez de acoplar o envio ao MCP de
+agendamento de um provider específico, construir um **MCP Server
+standalone só de mensageria**, já que diferentes clientes usam canais
+diferentes (WABA oficial, não oficial, híbrido) — qualquer workflow
+futuro (confirmação, campanha, o que for, de qualquer provider) pode
+chamar essas tools sem depender de qual sistema de agendamento o
+cliente usa.
+
+**Escopo**: 4 tools, reaproveitando a API de mensageria do Z-PRO (mesmo
+host `apigchat.gtigrupo.com.br`, endpoints diferentes dos de
+agendamento):
+
+| Tool | Endpoint | Uso |
+| --- | --- | --- |
+| `enviar_texto` | `POST /v2/api/external/{ApiID}/` | Texto simples — canal não oficial ou dentro da janela de 24h do WABA oficial |
+| `enviar_template` | `POST .../template` | Template WABA aprovado, sem parâmetros dinâmicos |
+| `enviar_template_com_parametros` | `POST .../templateBody` | Template WABA aprovado, com parâmetros dinâmicos no corpo |
+| `enviar_template_marketing` | `POST .../templateMarketingBody` | Template WABA de marketing, com componente de header (ex.: imagem) |
+
+**Arquitetura**: mesmo padrão de sempre — `MCP Server - Mensageria ZPRO`
+(`WsL4RlSD0hZ34gpB`) + 4 sub-workflows (`enviar_texto`
+`Y4ndG7GuIUrmVRxV`, `enviar_template` `E9lsmu8mlgzKFemk`,
+`enviar_template_com_parametros` `8zj1V7yXOrdCAWVq`,
+`enviar_template_marketing` `WYakJ2GmV6fNW2iq`). ApiID confirmado pelo
+usuário como o mesmo já validado pro agendamento
+(`ab2d51db-54e3-48c2-8b97-114a20340809`, credencial `ZPRO API Token -
+Canal QR - MC AGENDAMENTO`).
+
+**Bug real — `$fromAI` com `==` duplicado no início da expressão**: ao
+mapear manualmente os campos de "Workflow Inputs" nos 4 nodes
+`Call n8n Sub-Workflow Tool` do servidor, os valores foram salvos como
+`"=={{ $fromAI(...) }}"` (dois `=` em vez de um) — a expressão nunca era
+avaliada, então todo argumento chegava `null` no sub-workflow e a API do
+Z-PRO rejeitava com 400 (`body must be a string type... null`).
+**Fix**: reescrever os campos com um único `=` no início
+(`"={{ $fromAI(...) }}"`), via `patchNodeField`/`updateNode`. Depois de
+corrigir, apareceu um segundo erro (`Required → at isClosed`): o
+`$fromAI` do campo opcional `isClosed` (boolean) não tinha valor
+padrão, então o schema da tool o tratava como obrigatório. **Fix**:
+adicionar o 4º argumento de default ao `$fromAI` (ex.:
+`$fromAI('isClosed', '...', 'boolean', false)`), mesma correção
+aplicada ao `headerImageUrl` opcional do template de marketing (default
+`''`). Lição nova: **sempre conferir visualmente o texto final salvo no
+campo depois de colar uma expressão `$fromAI` na UI** — um `=` a mais
+não dá erro de validação estrutural do workflow, só falha silenciosamente
+em runtime com campos `null`.
+
+**Teste real de validação (11/08/2026)**: chamada `tools/call` direta
+via MCP (raw, sem AI Agent) pro tool `enviar_texto`, mandando uma
+mensagem de teste pro número pessoal do usuário
+(`5575999091780`, autorização explícita dada em chat). Resultado:
+`{"success": true, "data": {"message": "Message sent successfully",
+"ticketId": 461590}}` — mensagem confirmada recebida no celular de
+teste. Tools de template (`enviar_template`,
+`enviar_template_com_parametros`, `enviar_template_marketing`) ainda
+**não testadas de verdade** — precisam de um nome de template WABA
+real aprovado, não disponível no momento.
+
+**Fora de escopo desta rodada**: envio de mídia (multipart/URL/Base64),
+busca de mensagem por `wamid`, e a própria feature de "confirmação de
+agenda" do Klingo (que motivou a criação deste MCP) — fica pro usuário
+montar depois, atribuindo estas tools no workflow que ele decidir.
+
+**Resultado**: MCP Server de mensageria standalone, validado e testado
+com envio real, pronto para ser consumido por qualquer workflow futuro
+(confirmação de agenda ou outro), de qualquer provider.