Metadata-Version: 2.5
Name: whatsapp-mcp-local
Version: 0.2.3
Summary: MCP server: visão e escrita no WhatsApp nativo do macOS (leitura via banco local read-only + escrita com gate de confirmação)
Project-URL: Homepage, https://github.com/Pl3ntz/whatsapp-mcp
Project-URL: Repository, https://github.com/Pl3ntz/whatsapp-mcp
License: MIT
License-File: LICENSE
Keywords: agent,macos,mcp,model-context-protocol,whatsapp
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Requires-Python: <3.14,>=3.12
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: playwright<2,>=1.62
Requires-Dist: pydantic<3,>=2.7
Description-Content-Type: text/markdown

# whatsapp-mcp-local

MCP server que dá a agentes IA **visão e escrita** no WhatsApp — o paralelo do chrome-devtools MCP para o WhatsApp.

- **Ver**: conversas, mensagens e histórico completo.
- **Escrever**: rascunho pre-preenchido + **Enter com confirmação explícita** (gate). Nada é enviado sem aprovação.
- **Seguro por design**: zero protocolo não-oficial (sem Baileys/whatsmeow → sem risco de banimento), dados locais.

## Plataformas (auto-detect)

| Driver | Onde funciona | Como detecta |
|---|---|---|
| **local** (app nativo) | macOS com o app WhatsApp instalado e logado | Banco `ChatStorage.sqlite` existe |
| **web** (web.whatsapp.com) | **Qualquer SO** com Google Chrome | Banco do macOS não existe (ou `WHATSAPP_DRIVER=web`) |

O server escolhe o driver automaticamente. Force com `WHATSAPP_DRIVER=local|web|auto`.

## Requisitos

- Python 3.12+ e [uv](https://docs.astral.sh/uv/)
- **Driver local (macOS)**: app WhatsApp nativo instalado e logado + permissão de Acessibilidade para o processo (só para o Enter do envio)
- **Driver web (qualquer SO)**: Google Chrome instalado. Na primeira execução, escaneie o QR uma vez (o MCP abre o Chrome com perfil dedicado; depois o login é permanente)

## Instalação

```bash
uvx whatsapp-mcp-local
```

## Integração com opencode

Adicione em `~/.config/opencode/opencode.json` (ou `opencode.json` do projeto):

```json
{
  "mcp": {
    "whatsapp": {
      "type": "local",
      "command": ["uvx", "whatsapp-mcp-local"],
      "enabled": true
    }
  }
}
```

Reinicie o opencode. As tools `send_message` e `confirm_send` são marcadas `destructive` e **pedem confirmação por padrão** no cliente.

## Integração com Claude Code

```bash
claude mcp add whatsapp-mcp -- uvx whatsapp-mcp-local
```

Ou via `.mcp.json`:

```json
{
  "mcpServers": {
    "whatsapp-mcp": {
      "command": "uvx",
      "args": ["whatsapp-mcp-local"]
    }
  }
}
```

## Tools

| Tool | Descrição | Driver | Flag |
|---|---|---|---|
| `list_chats` | Lista conversas (nome, não-lidas, última msg) | local (chat_id) / web (chat_name) | RO |
| `get_messages` | Lê mensagens de uma conversa | local (chat_id) / web (chat_name) | RO |
| `search_messages` | Busca texto nas mensagens | local | RO |
| `get_chat_info` | Metadados da conversa | local | RO |
| `export_chat` | Exporta histórico para JSON/Markdown | local | RO |
| `send_message` | Pre-preenche rascunho (**não envia**) | ambos | ⚠️ destrutiva |
| `confirm_send(draft_id)` | Pressiona Enter (envia) — exige draft_id válido de send_message, expira em 120s | ambos | ⚠️ destrutiva |
| `verify_sent` | Verifica no banco se a mensagem foi enviada | local | RO |

## Modelo de segurança

1. **Leitura**: `mode=ro` sempre; o banco nunca é modificado (testes verificam hash antes/depois).
2. **Escrita em 2 passos**: `send_message` só preenche o campo — sem Enter, sem envio (comportamento do próprio WhatsApp). O envio exige `confirm_send` **ou** Enter manual.
3. **Nunca** grava em `ChatStorage.sqlite`/`Axolotl.sqlite` (cripto) — corrompe o app e não transmite ao servidor.
4. JIDs mascarados nos outputs; textos truncados por config.
5. Dados processados localmente; só o que o proprietário pedir vai para o modelo.

## Testes

```bash
uv run pytest
```

## Roadmap

- [x] Driver local (macOS) — validado E2E
- [x] Driver web (cross-platform via Chrome CDP) — implementado e testado com mocks
- [x] Auto-detecção de driver
- [x] Publicado no PyPI (`uvx whatsapp-mcp-local`) e GitHub
- [ ] Validação E2E do driver web com QR logado (manual, depende de escanear QR 1x)

## Aviso

Ferramenta para uso pessoal com a própria conta. O schema do banco e o DOM do web.whatsapp.com são do WhatsApp e podem mudar entre versões. Não use para enviar mensagens em nome de terceiros ou para fins não autorizados.
