Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://zapo.to/llms.txt

Use this file to discover all available pages before exploring further.

O zapo traz dois pacotes opcionais voltados puramente a desenvolvimento e testes — nenhum é para produção:
  • Servidor MCP (@zapo-js/mcp-server) — expõe um WaClient ao vivo a um agente de IA (Claude Code, Cursor) para conectar, parear, enviar e inspecionar o estado de forma interativa.
  • Fake server (@zapo-js/fake-server) — um servidor WhatsApp Web falso in-process que dirige o WaClient real ponta-a-ponta, para você testar de forma determinística sem tocar nos servidores do WhatsApp.

​
Servidor MCP

Apenas desenvolvimento e testes. O @zapo-js/mcp-server é um auxílio de depuração, não um servidor de protocolo de produção. Ele expõe um WaClient ao vivo — e todo o módulo zapo-js — a um agente de IA que pode enviar mensagens, ler estado e executar chamadas arbitrárias da biblioteca em uma conta real do WhatsApp. Use-o apenas com contas que você controla.
Ele expõe uma instância de WaClient ao vivo e o namespace do módulo zapo-js como ferramentas MCP. Um agente LLM pode então conduzir fluxos completos do WhatsApp — conectar, parear, enviar, consultar grupos/newsletters, inspecionar eventos, percorrer o estado SQL — sem você escrever scripts descartáveis.

​
Superfície de ferramentas

FerramentaO que faz
call / inspectPercorre caminhos pontilhados em client (o WaClient) ou lib (o namespace zapo-js, incluindo proto.* e helpers como parsePhoneJid). call invoca funções; inspect lista membros.
events / events_clearRing buffer limitado de todo evento de WaClientEventMap — filtre por types / since / limit / drain.
logs / logs_clearBuffer consultável espelhando cada linha de log do runtime + lib (também stderr; JSONL para MCP_LOG_FILE se definido).
lifecyclestatus / start / destroy para o client.
restartsoft (descarta o client + limpa buffers) ou process_exit (também sai do processo para um supervisor reiniciá-lo).
Cada ferramenta embute seu próprio schema e exemplos — o agente os lê em tempo de execução, em vez de memorizar flags.

​
Instalar e registrar

npm install @zapo-js/mcp-server
# peers: zapo-js, @zapo-js/store-sqlite, @zapo-js/media-utils (better-sqlite3 opcional, para persistência SQLite)
Registre no Claude Code em escopo de usuário (faça o build primeiro), para funcionar de qualquer diretório: 
npm run build --workspace @zapo-js/mcp-server
claude mcp add zapo --scope user -- node <abs-path>/packages/mcp-server/dist/bin.js
Para iteração rápida na própria biblioteca, registre o código-fonte via tsx — sem build, e o zapo-js resolve direto de src/: 
claude mcp add zapo --scope user -- node --import tsx <abs-path>/packages/mcp-server/src/bin.ts
Um transporte HTTP com node --watch dá o loop de dev mais suave: edite um .ts → o processo reinicia → a próxima chamada de ferramenta reconecta automaticamente, sem reconexão manual de /mcp. Veja o README do pacote para o script dev e a configuração HTTP.

​
Detalhe do pareamento

client.connect() bloqueia até o pareamento terminar, então sempre inicie sem aguardar (await) e depois consulte o buffer de eventos: 
call({ path: 'connect', noAwait: true })
events({ types: ['auth_qr', 'auth_pairing_code', 'auth_paired', 'connection'] })
Mostre a string de auth_qr ao usuário, espere por auth_paired e continue.

​
Variáveis de ambiente principais

VarPadrãoPropósito
MCP_AUTH_PATH<cwd>/.auth/state.sqliteCaminho da store SQLite de credenciais
MCP_SESSION_IDdefault_2sessionId passado ao WaClient
MCP_LOG_LEVELinfotrace / debug / info / warn / error
MCP_TRANSPORTstdiostdio ou http
MCP_HTTP_HOST / MCP_HTTP_PORT / MCP_HTTP_PATH127.0.0.1 / 3737 / /mcpConfiguração do listener HTTP
MCP_EVENT_BUFFER_SIZE / MCP_LOG_BUFFER_SIZE1000 / 500Tamanhos dos rings em memória
Um WaClient por processo (multi-sessão exige múltiplos servidores com MCP_AUTH_PATH + MCP_SESSION_ID distintos); sem reconexão automática (chame connect de novo em connection: close); o restart soft não aplica mudanças de código, enquanto process_exit + um supervisor aplica. Referência completa: packages/mcp-server/README.md.

​
Fake server

O @zapo-js/fake-server é um servidor WhatsApp Web falso in-process que dirige o WaClient real ponta-a-ponta — handshake Noise XX/IK completo, pareamento por QR, Signal Protocol (X3DH + Double Ratchet), SenderKey de grupo, upload/download de mídia sobre HTTPS auto-assinado e sincronização de app-state — tudo sem tocar nos servidores do WhatsApp. Ele alimenta a própria suíte de testes cross-check e os benchmarks da biblioteca, e você pode usá-lo para testar sua integração de forma determinística.

​
Início rápido

import { FakeWaServer } from '@zapo-js/fake-server'
import { createStore, WaClient } from 'zapo-js'

const server = await FakeWaServer.start()

const client = new WaClient({
  store: createStore({
    providers: { auth: 'memory', signal: 'memory', senderKey: 'memory', appState: 'memory' }
  }),
  sessionId: 'test',
  chatSocketUrls: [server.url],
  testHooks: { noiseRootCa: server.noiseRootCa },
  proxy: { mediaUpload: server.mediaProxyAgent, mediaDownload: server.mediaProxyAgent }
})

await client.connect()
const pipeline = await server.waitForAuthenticatedPipeline()
// conduza o pareamento, crie peers, envie/receba mensagens, valide os dois lados
await server.stop()
A ligação usa três opções do client feitas exatamente para isso: chatSocketUrls (aponta para o WebSocket falso), testHooks.noiseRootCa (confia no certificado do servidor falso sem burlar a verificação — a checagem completa da cadeia ainda roda) e proxy.mediaUpload / proxy.mediaDownload (roteia a mídia para o servidor HTTPS falso).

​
O que ele simula

  • FakeWaServer — o listener WebSocket, o handshake Noise, um roteador de IQ que responde a cada IQ que a lib emite na operação normal (upload/fetch de prekey, usync, media-conn, sincronização de app-state, grupos, privacidade, perfil, blocklist, …), além de registries de estado para peers e grupos.
  • FakePeer — um contato simulado com cripto Signal real: peer.sendConversation(text) / peer.sendGroupConversation(groupJid, text) empurram mensagens para o client, e peer.expectMessage() captura e descriptografa o que o client envia.
  • Pareamento — server.runPairing(pipeline, { deviceJid }, materialFn) conduz o handshake completo de pareamento por QR; depois a lib reconecta com o handshake IK (capture-o via waitForNextAuthenticatedPipeline()).

​
CLI standalone

Rode como um servidor standalone para experimentos manuais: 
npm --workspace=@zapo-js/fake-server run cli -- --port 5222 --peer 5511888@s.whatsapp.net --log

​
Benchmarking

O pacote inclui um profiler de mensagens (send/recv × 1:1/grupo) usado para acompanhar a performance da biblioteca: 
npm --workspace=@zapo-js/fake-server run bench:messaging
Ajuste a carga com variáveis ZAPO_BENCH_* (ZAPO_BENCH_CONTACTS, ZAPO_BENCH_GROUP_MEMBERS, ZAPO_BENCH_MESSAGES, ZAPO_BENCH_SCENARIOS, …) e adicione --cpu / --heap / --separate-process para profiles. Veja packages/fake-server/README.md para a referência completa de flags.
O fake server é um harness de teste in-process, não um runtime que você faz deploy. Combine-o com a store memory para testes rápidos e isolados que resetam a cada execução.
Last modified on May 28, 2026