✨ O que é este projeto?

Este é um servidor MCP (Model Context Protocol) que conecta seu WhatsApp a qualquer LLM através da API WAHA, permitindo que modelos de IA interajam diretamente com o WhatsApp para:

• 📱 Enviar mensagens automaticamente
• 👥 Gerenciar grupos e contatos
• 🖼️ Compartilhar mídia
• 📊 Automatizar workflows de comunicação
• 🤖 Criar assistentes conversacionais

🎯 Por que usar?

🛠️ Funcionalidades Épicas

# Controle total sobre suas sessões WhatsApp
list_sessions()                    # 📋 Lista todas as sessões
get_session_info(session)          # ℹ️  Status detalhado
start_session(session)             # ▶️  Iniciar conexão
stop_session(session)              # ⏹️  Parar sessão
get_qr_code(session)               # 📱 QR para autenticação
get_my_profile(session)            # 👤 Dados do perfil

# Envie qualquer tipo de conteúdo
send_text_message(chat_id, text)                    # 💬 Texto simples
send_image_from_url(chat_id, url, caption)          # 🖼️ Imagem da web
send_image_base64(chat_id, data, filename)          # 📸 Imagem local
send_file_from_url(chat_id, url, filename)          # 📎 Qualquer arquivo
mark_as_read(chat_id)                               # ✅ Marcar como lido
start_typing(chat_id)                               # ⌨️  Indicador de digitação
stop_typing(chat_id)                                # ⏸️  Parar digitação
check_number_status(phone)                          # 🔍 Verificar número

# Controle total sobre conversas
get_chats()                                         # 📜 Lista de chats
get_chat_messages(chat_id, limit)                   # 💭 Histórico de mensagens
archive_chat(chat_id)                               # 📦 Arquivar conversa
unarchive_chat(chat_id)                             # 📤 Desarquivar

# Gestão completa de contatos
get_all_contacts()                                  # 📇 Lista completa
get_contact_info(contact_id)                        # ℹ️  Detalhes do contato
get_contact_profile_picture(contact_id)             # 🖼️ Foto de perfil
block_contact(contact_id)                           # 🚫 Bloquear
unblock_contact(contact_id)                         # ✅ Desbloquear
check_number_status(phone)                          # 📱 Status no WhatsApp

# Poder total sobre grupos
create_group(name, participants)                    # ➕ Criar grupo
get_groups()                                        # 📋 Lista de grupos
get_group_info(group_id)                           # ℹ️  Detalhes do grupo
add_group_participants(group_id, participants)      # 👥 Adicionar membros
remove_group_participants(group_id, participants)   # ➖ Remover membros
get_group_invite_code(group_id)                     # 🔗 Código de convite
leave_group(group_id)                               # 🚪 Sair do grupo

# Mantenha tudo sob controle
ping_server()                                       # 🏓 Status do servidor
get_server_version()                                # 📋 Versão atual
get_server_status()                                 # 📊 Métricas detalhadas

⚡ Setup Ultra-Rápido

Installing via Smithery

To install FastMCP for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @fellipesaraiva88/fastmcp --client claude

1️⃣ Clone e Instale

# Clone o projeto
git clone <repository>
cd fastmcp/examples

# Instale dependências
pip install fastmcp httpx pydantic pydantic-settings

2️⃣ Execute o WAHA

# Opção 1: Docker (Recomendado)
docker run -it --rm -p 3000:3000/tcp devlikeapro/waha

# Opção 2: Docker Compose
# Crie um docker-compose.yml (veja exemplo abaixo)
docker-compose up -d

3️⃣ Configure (Opcional)

# Copie o arquivo de exemplo
cp .env.waha.example .env

# Edite suas configurações
nano .env

4️⃣ Execute o MCP

# Versão simples (6 ferramentas)
python waha_simple.py

# Versão completa (40+ ferramentas)  
python waha_whatsapp.py

5️⃣ Teste Tudo

# Teste básico de conexão
python demo_waha.py test

# Demo completa
python demo_waha.py

🎨 Configuração Flexível

WAHA_BASE_URL=http://localhost:3000
WAHA_API_KEY=sua_chave_secreta
WAHA_DEFAULT_SESSION=producao

# Edite no início dos arquivos
BASE_URL = "http://localhost:3000"
DEFAULT_SESSION = "minha_sessao"

🎯 Fluxo de Trabalho Mágico

graph LR
    A[🚀 Iniciar WAHA] --> B[📱 Criar Sessão]
    B --> C[📋 Obter QR Code]
    C --> D[📷 Escanear QR]
    D --> E[✅ Sessão Ativa]
    E --> F[💬 Enviar Mensagens]
    E --> G[👥 Gerenciar Grupos]
    E --> H[📊 Automatizar]

💡 Exemplos Práticos

🤖 Bot de Atendimento

# Resposta automática
def auto_responder():
    chats = get_chats()
    for chat in chats:
        messages = get_chat_messages(chat['id'], 1)
        if messages and not messages[0]['fromMe']:
            send_text_message(chat['id'], 
                "Obrigado pela mensagem! Em breve retornaremos.")

📈 Notificações de Sistema

# Alertas para administradores
def send_alert(message, urgency="normal"):
    admin_group = "123456789-admin@g.us"
    emoji = "🚨" if urgency == "high" else "ℹ️"
    send_text_message(admin_group, f"{emoji} {message}")

👥 Gestão de Grupos em Massa

# Adicionar usuário em múltiplos grupos
def add_to_multiple_groups(user_phone, group_list):
    for group_id in group_list:
        add_group_participants(group_id, [user_phone])
        send_text_message(group_id, f"🎉 Bem-vindo(a), {user_phone}!")

🐳 Docker Compose Setup

Crie um docker-compose.yml para facilitar o deploy:

version: '3.8'
services:
  waha:
    image: devlikeapro/waha
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      WAHA_WEBHOOK_URL: http://localhost:3001/webhook
      WAHA_WEBHOOK_EVENTS: message,session.status
    volumes:
      - ./sessions:/app/sessions

  mcp-server:
    build: .
    restart: unless-stopped
    depends_on:
      - waha
    environment:
      WAHA_BASE_URL: http://waha:3000
    volumes:
      - ./logs:/app/logs

📱 Formatos de Chat ID

🔥 Use Cases Reais

🛡️ Segurança & Boas Práticas

✅ Recomendações

• 🔐 Use HTTPS em produção
• 🔑 Rotacione API keys regularmente
• 📝 Log todas as ações importantes
• 🚫 Rate limiting para evitar spam
• 🔒 Validação de entrada sempre

⚠️ Limitações do WhatsApp

• 📱 1 sessão por número
• ⏱️ Rate limits da API oficial
• 🚫 Números bloqueados podem afetar entrega
• 📋 ToS WhatsApp devem ser respeitados

🐛 Troubleshooting

# Verifique se WAHA está rodando
curl http://localhost:3000/ping

# Verifique logs do Docker
docker logs waha-container

# Teste conectividade
telnet localhost 3000

# Force restart da sessão
stop_session("default")
start_session("default")
get_qr_code("default")

# Verifique status
get_session_info("default")

# 1. Verifique número
status = check_number_status("5511999999999")

# 2. Confirme sessão ativa  
session = get_session_info("default")

# 3. Teste com número conhecido
send_text_message("5511999999999", "Teste")

🎓 Tutoriais Avançados

🔄 Webhook Setup

from fastapi import FastAPI
from fastmcp import FastMCP

app = FastAPI()
mcp = FastMCP("WAHA Advanced")

@app.post("/webhook/message")
async def handle_message(data: dict):
    if not data.get('fromMe'):
        # Processar mensagem recebida
        await process_incoming_message(data)
    
@mcp.tool
async def process_incoming_message(message_data: dict):
    # Sua lógica aqui
    pass

📊 Analytics & Metrics

import time
from collections import defaultdict

class WhatsAppAnalytics:
    def __init__(self):
        self.metrics = defaultdict(int)
        
    def track_message(self, chat_id: str, message_type: str):
        self.metrics[f"messages_{message_type}"] += 1
        self.metrics[f"chat_{chat_id}"] += 1
        
    def get_top_chats(self, limit: int = 10):
        chat_metrics = {k: v for k, v in self.metrics.items() 
                       if k.startswith('chat_')}
        return sorted(chat_metrics.items(), 
                     key=lambda x: x[1], reverse=True)[:limit]

🤝 Contribuindo

Adoramos contribuições! Aqui está como você pode ajudar:

1. 🍴 Fork o repositório
2. 🌟 Crie uma branch para sua feature
3. ✅ Teste tudo thoroughly
4. 📝 Documente suas mudanças
5. 🚀 Envie um Pull Request

📋 Checklist para PRs

• [ ] ✅ Testes passando
• [ ] 📚 Documentação atualizada
• [ ] 🎨 Código formatado (black/flake8)
• [ ] 🔍 Type hints adicionados
• [ ] 📝 Changelog atualizado

📚 Recursos Extras

🔗 Links Úteis

• 📖 Documentação WAHA
• 🐙 WAHA GitHub
• ⚡ FastMCP Docs
• 💬 WhatsApp Business API

🎯 Roadmap

• [ ] 🔊 Suporte a áudio/voz
• [ ] 📋 Polls e interações
• [ ] 🏷️ Labels e tags
• [ ] 📺 Status/Stories
• [ ] 🤖 AI-powered responses
• [ ] 📊 Dashboard web