Documento

Conteúdo

docs/ARQUITETURA.md

Arquitetura no Google Cloud (VM e2-micro, Caddy+sslip.io, IP estático, systemd), auth, deploy e custo.

docs/FERRAMENTAS.md

As 15 ferramentas MCP em detalhe (parâmetros, recomendadas × extras, confirmação de entrega).

docs/TROUBLESHOOTING.md

A saga de bugs e seus fixes (405, git ownership, 9º dígito, OAuth, timing de deploy…).

Ferramenta

O que faz

enviar_mensagem_whatsapp(texto)

Texto (aceita markdown do WhatsApp: *negrito*, _itálico_, ```mono```).

enviar_imagem_whatsapp(url|base64, legenda?)

Imagem — gráficos de payoff/curva de capital/IV Rank/print do cockpit.

enviar_documento_whatsapp(url|base64, nome_arquivo, legenda?)

PDF/CSV/XLSX — relatórios, auditoria, posições.

ler_mensagens_recebidas(limite?)

Two-way: lê as mensagens recebidas pelo robô (o operador comanda pelo WhatsApp; o assistente lê e age).

verificar_status_envio(id)

Reconfere entrega/leitura de um envio anterior.

verificar_status_conexao()

Observabilidade do canal (online? desde quando? última entrega OK?).

enviar_alerta_falado(texto, voz?)

Alerta falado: gera a fala do texto (Google TTS Neural pt-BR) e envia como nota de voz. Só aparece com GOOGLE_TTS_API_KEY configurada — ver setup em docs/FERRAMENTAS.md.

guia_de_uso(topico?)

Guia para a LLM: como usar as ferramentas complexas, com exemplos e boas práticas. A própria IA chama quando tem dúvida.

Ferramenta

O que faz

enviar_audio_whatsapp(url|base64, nota_de_voz?)

Envia áudio; com nota_de_voz=true manda como mensagem de voz (PTT — requer ogg/opus p/ tocar bem).

enviar_video_whatsapp(url|base64, legenda?)

Envia vídeo com legenda opcional.

enviar_sticker_whatsapp(url|base64)

Envia um sticker (idealmente webp).

responder_mensagem_whatsapp(id_recebida, texto)

Responde citando (reply/quote) uma mensagem recebida, pelo id de ler_mensagens_recebidas.

editar_mensagem_whatsapp(id, novo_texto)

Edita uma mensagem já enviada por este servidor (ex: marcar alerta como "resolvido").

apagar_mensagem_whatsapp(id)

Apaga para todos uma mensagem já enviada (retratar alerta falso).

reagir_mensagem_whatsapp(id, emoji)

Reage com emoji a uma mensagem (recebida ou enviada).

marcar_como_lida_whatsapp(id_recebida?)

Marca mensagens recebidas como lidas (uma específica, ou as últimas).

enviar_presenca_whatsapp(tipo)

Envia presença ao destino: composing (digitando), recording (gravando), paused, available, unavailable.

Método/rota

Descrição

POST /mcp/:key

MCP autenticado pela chave no path — é esta a URL usada no conector do claude.ai: https://<host>/mcp/<MCP_API_KEY>.

POST /mcp

MCP autenticado pelo header x-api-key (curl/testes).

GET /health

Público: { "status": "ok", "whatsapp": "conectado" | "reconectando" | "aguardando_qr" | "deslogado_precisa_novo_qr" }.

Variável

Descrição

MCP_API_KEY

Chave exigida em /mcp (header) e /mcp/:key (path). Gerada no deploy.

WHATSAPP_DESTINO

Número de destino, só dígitos ou JID (5511999999999 ou ...@s.whatsapp.net). O código resolve o JID canônico via onWhatsApp() (trata o "9º dígito" do Brasil).

PORT

Porta interna do Node (padrão 8080; Caddy faz o HTTPS na frente).

HABILITAR_FERRAMENTAS_EXTRAS

true liga as ferramentas extras (áudio, vídeo, sticker, editar, apagar, reagir, responder, marcar_lida, presença). Padrão: desligado.