# MCP WPPConnect Server

Um servidor MCP (Model Context Protocol) que expõe operações do WhatsApp via protocolo padronizado para integração com Claude Desktop e outros clientes MCP.

## 🚀 Visão Geral

Este servidor permite que você:
- Gerencie sessões do WhatsApp (inicializar, verificar status, QR codes, fechar)
- Envie mensagens de texto
- Gerencie participantes de grupos e comunidades
- Obtenha listas de contatos e chats

Além disso, o servidor é compatível com qualquer cliente MCP, permitindo integração com diversos agentes de IA além do Claude Desktop.

## 📋 Pré-requisitos

- Node.js 18+ 
- npm ou yarn
- Uma conta do WhatsApp para autenticação

## 🔧 Instalação

```bash
# Clone o repositório
git clone <url-do-repositório>
cd mcp-wppconnect-server

# Instale as dependências
npm install

# Compile o projeto
npm run build
```

## 🏃‍♂️ Uso Rápido

### Desenvolvimento
```bash
npm run dev
```

### Produção
```bash
npm run build
npm start
```

## 🤖 Integração com Claude Desktop e Outros Agentes MCP

Este servidor segue o padrão Model Context Protocol (MCP) e pode ser integrado com qualquer cliente MCP compatível. Além do Claude Desktop, suportamos diversos agentes de IA.

### 🎯 Clientes MCP Suportados

| Cliente | Status | Configuração |
|---------|--------|--------------|
| **Claude Desktop** | ✅ Oficial | `claude_desktop_config.json` |
| **OpenAI Codex CLI** | ✅ Testado | `mcp-codex-config.json` |
| **Google Gemini CLI** | ✅ Testado | `mcp-gemini-config.json` |
| **Cline** | ✅ Compatível | `mcp-generic-config.json` |
| **Roo Code** | ✅ Compatível | `mcp-generic-config.json` |
| **Outros clientes MCP** | ✅ Genérico | `mcp-generic-config.json` |

### 📁 Arquivos de Configuração Prontos

Todas as configurações estão disponíveis no diretório `mcp-configs/`:

```bash
# Ver todas as configurações disponíveis
ls mcp-configs/*.json

# Usar o configurador automático
./setup-mcp-agents.sh
```

### 🔧 Configuração Rápida para Qualquer Agente

1. **Localize o arquivo de configuração do seu agente**
2. **Copie a configuração apropriada**:
   ```json
   {
     "mcpServers": {
       "whatsapp-mcp": {
         "command": "node",
         "args": ["/caminho/completo/para/mcp-wppconnect-server/build/index.js"],
         "env": {
           "NODE_ENV": "production",
           "MAX_SESSIONS": "10",
           "QR_EXPIRY_MINUTES": "5"
         }
       }
     }
   }
   ```

3. **Reinicie seu agente**
4. **Teste a integração**:
   ```
   "Inicialize uma sessão WhatsApp com ID meu-teste"
   ```

#### 🤖 OpenAI Codex CLI
```bash
# Inicializar sessão
codex 'Inicialize uma sessão WhatsApp com ID codex-teste'

# Enviar mensagem
codex 'Envie uma mensagem para +551234567890 dizendo Olá do Codex'

# Verificar status
codex 'Verifique o status da sessão codex-teste'
```

#### 💎 Google Gemini CLI
```bash
# Criar sessão
gemini-cli 'Crie uma sessão WhatsApp com ID gemini-teste'

# Listar contatos
gemini-cli 'Liste todos os meus contatos WhatsApp'

# Obter QR code
gemini-cli 'Obtenha o QR code da sessão gemini-teste'
```

#### 📝 Anthropic Claude
```bash
# Inicializar sessão
claude 'Inicialize uma sessão WhatsApp com ID claude-teste'

# Obter QR code
claude 'Obtenha o QR code da sessão claude-teste'

# Enviar mensagem
claude 'Envie mensagem para +551234567890 com Olá do Claude'
```

#### 🔧 Agente Genérico
```bash
# Comandos genéricos funcionam com qualquer cliente MCP
[seu-agente] 'Inicialize uma sessão WhatsApp com ID generico-teste'
[seu-agente] 'Envie mensagem para +551234567890 com Olá'
[seu-agente] 'Liste meus grupos do WhatsApp'
```

### 📋 Testando a Integração

Use nosso script de teste para verificar tudo está funcionando:

```bash
# Executar testes completos
./test-mcp-agents.sh

# Verificar se servidor está rodando
./test-mcp-quick.sh
```

### 🛠️ Configuração Automática

Execute nosso configurador automático:

```bash
# Configurar para todos os agentes
./setup-mcp-agents.sh

# Configurar para um agente específico
./setup-mcp-agents.sh codex
```

### 🎯 Dicas de Uso

1. **Sempre use IDs únicos** para cada sessão
2. **Aguarde o QR code** antes de escanear
3. **Teste comandos simples** primeiro
4. **Verifique logs** em caso de erro
5. **Use números válidos** com código do país

### 📚 Recursos Adicionais

- [Documentação de Configurações](mcp-configs/README.md)
- [Guia de Deploy](DEPLOYMENT.md)
- [Solução de Problemas](TROUBLESHOOTING.md)
- [Exemplos de Uso](src/tools/README.md)

Configure o Claude Desktop para usar o servidor MCP:

### 1. Preparação
```bash
# Certifique-se de que o build foi executado com sucesso
npm run build

# Teste o servidor antes de configurar
npm start
# Você deve ver: "MCP WPPConnect Server connected and ready for requests"
```

### 2. Localize o arquivo de configuração do Claude Desktop
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### 3. Configure o arquivo de configuração

#### Para Desenvolvimento (usando npm run dev):
```json
{
  "mcpServers": {
    "mcp-wppconnect-server": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/Users/jeff/Desktop/MCP CONNECT"
    }
  }
}
```

#### Para Produção (usando build):
```json
{
  "mcpServers": {
    "mcp-wppconnect-server": {
      "command": "node",
      "args": ["/Users/jeff/Desktop/MCP CONNECT/build/index.js"]
    }
  }
}
```

### 4. Validação da Configuração
```bash
# Verifique se o arquivo de configuração é válido JSON
node -e "console.log(JSON.parse(require('fs').readFileSync('/Users/jeff/Library/Application Support/Claude/claude_desktop_config.json', 'utf8')))"
```

### 5. Reinicie o Claude Desktop
- Feche completamente o Claude Desktop
- Aguarde 5 segundos
- Abra novamente
- Verifique os logs do Claude Desktop para confirmar a conexão

### 6. Teste de Integração
No Claude Desktop, você deve conseguir:
- Inicializar uma sessão WhatsApp
- Verificar o status da sessão
- Enviar mensagens
- Gerenciar grupos e comunidades

### 7. Troubleshooting da Integração
Se encontrar problemas:

1. **Verifique os logs do servidor**:
```bash
# Com debug habilitado
DEBUG=mcp-wppconnect:* npm start
```

2. **Verifique os logs do Claude Desktop**:
- Geralmente localizados em `~/Library/Logs/Claude/` (macOS)

3. **Teste manualmente**:
```bash
# Execute o servidor diretamente
node build/index.js
# Deve mostrar "MCP WPPConnect Server connected and ready for requests"
```

4. **Problemas comuns**:
   - **Caminho incorreto**: Use caminho absoluto completo
   - **Permissões**: Certifique-se de que o arquivo é executável
   - **Dependências faltando**: Execute `npm install` novamente
   - **Build quebrado**: Execute `npm run build` novamente

### 8. Configuração Avançada
Para ambientes de produção, considere:
```json
{
  "mcpServers": {
    "mcp-wppconnect-server": {
      "command": "node",
      "args": ["/opt/mcp-wppconnect-server/build/index.js"],
      "env": {
        "NODE_ENV": "production",
        "MAX_SESSIONS": "20",
        "QR_EXPIRY_MINUTES": "10",
        "TOKEN_STORAGE_PATH": "/opt/mcp-wppconnect/tokens"
      }
    }
  }
}
```

## 📚 Ferramentas Disponíveis

### Gerenciamento de Sessão
- `initialize_session` - Inicializa uma nova sessão WhatsApp
- `get_qr_snapshot` - Obtém QR code para autenticação
- `get_session_status` - Verifica status da sessão
- `close_session` - Fecha sessão ativa

### Mensagens
- `send_text` - Envia mensagem de texto

### Grupos
- `promote_group_participant` - Promove participante a admin
- `demote_group_participant` - Remove privilégios de admin

### Comunidades
- `get_community_participants` - Lista participantes da comunidade
- `promote_community_participant` - Promove participante da comunidade
- `demote_community_participant` - Remove privilégios de participante da comunidade

### Utilidades
- `get_contacts` - Lista todos os contatos
- `get_chats` - Lista todas as conversas

## 📝 Exemplos de Uso

### Inicializar uma sessão
```json
{
  "tool": "initialize_session",
  "arguments": {
    "sessionId": "minha-sessao-1"
  }
}
```

### Enviar uma mensagem
```json
{
  "tool": "send_text",
  "arguments": {
    "sessionId": "minha-sessao-1",
    "to": "5511999999999@c.us",
    "text": "Olá! Esta é uma mensagem do MCP WPPConnect Server."
  }
}
```

### Obter participantes de um grupo
```json
{
  "tool": "get_community_participants",
  "arguments": {
    "sessionId": "minha-sessao-1",
    "communityId": "551199999999-1234567890@g.us"
  }
}
```

## ⚙️ Configuração

### Variáveis de Ambiente
```bash
NODE_ENV=production              # Ambiente (development/production)
DEBUG=mcp-wppconnect:*           # Habilitar logs detalhados
MAX_SESSIONS=10                  # Limite de sessões simultâneas
QR_EXPIRY_MINUTES=5              # Tempo de expiração do QR code
TOKEN_STORAGE_PATH=~/.mcp-wppconnect/tokens  # Caminho dos tokens
```

## 🚨 Solução de Problemas

### Servidor não inicia
- Verifique se Node.js 18+ está instalado
- Confirme que todas as dependências foram instaladas
- Verifique as permissões de arquivo

### QR code não aparece
- Certifique-se de que a sessão foi inicializada corretamente
- Verifique o status da sessão
- O QR code expira em 5 minutos - reinicie se necessário

### Erros de autenticação
- Verifique se o número do WhatsApp está correto
- Certifique-se de que a sessão está autenticada
- Tente fechar e reinicializar a sessão

## 🔒 Segurança

- Nunca exponha tokens ou informações sensíveis
- Use HTTPS para comunicações externas
- Implemente rate limiting em produção
- Monitore atividades suspeitas

## 🤝 Contribuindo

1. Faça fork do projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request

## 📄 Licença

Este projeto está licenciado sob a licença MIT. Veja o arquivo `LICENSE` para mais detalhes.

## 🙏 Agradecimentos

- [WPPConnect Team](https://github.com/wppconnect-team) pelo excelente trabalho com a biblioteca WPPConnect
- [Model Context Protocol](https://modelcontextprotocol.io) pela especificação MCP

## 📞 Suporte

Para problemas e dúvidas:
- Abra uma issue no GitHub
- Consulte o guia [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
- Verifique a documentação em [src/tools/README.md](./src/tools/README.md)