MCP WPPConnect Server

# Guia de Troubleshooting - MCP WPPConnect Server Este guia fornece soluções para problemas comuns encontrados durante a instalação, configuração e uso do MCP WPPConnect Server. ## 📋 Índice 1. [Erros de Instalação](#erros-de-instalação) 2. [Erros de Build](#erros-de-build) 3. [Erros de Execução](#erros-de-execução) 4. [Erros de Conexão WhatsApp](#erros-de-conexão-whatsapp) 5. [Erros de Sessão](#erros-de-sessão) 6. [Erros de Mensagens](#erros-de-mensagens) 7. [Erros de Grupos/Comunidades](#erros-de-gruposcomunidades) 8. [Erros de Claude Desktop](#erros-de-claude-desktop) 9. [Erros de Performance](#erros-de-performance) 10. [Problemas de Token/Segurança](#problemas-de-tokensegurança) 11. [Logs e Debugging](#logs-e-debugging) 12. [Problemas Conhecidos](#problemas-conhecidos) --- ## 🔧 Erros de Instalação ### Erro: "npm install falha com erros de dependência" **Sintoma:** ``` npm ERR! code ERESOLVE npm ERR! ERESOLVE unable to resolve dependency tree ``` **Solução:** ```bash # Limpar cache do npm npm cache clean --force # Deletar node_modules e package-lock.json rm -rf node_modules package-lock.json # Instalar com flag --legacy-peer-deps npm install --legacy-peer-deps ``` ### Erro: "node-gyp rebuild falha" **Sintoma:** ``` gyp ERR! build error ``` **Solução:** ```bash # Ubuntu/Debian sudo apt-get install build-essential python3 # macOS xcode-select --install # Windows (como administrador) npm install --global windows-build-tools ``` ### Erro: "ERESOLVE unable to resolve dependency tree" **Solução:** ```bash # Verificar versão do Node.js (precisa ser 18+) node --version # Atualizar npm npm install -g npm@latest # Instalar com flag --force npm install --force ``` --- ## 🔨 Erros de Build ### Erro: "TypeScript compilation errors" **Sintoma:** ``` src/index.ts:160:9 - error TS2345: Argument of type 'Record<string, unknown>' is not assignable to parameter of type 'never'. ``` **Solução:** ```bash # Limpar build anterior rm -rf build/ # Verificar tsconfig.json cat tsconfig.json # Build com verbose npm run build -- --verbose # Se persistir, verificar tipos no código npm run build 2>&1 | grep "error TS" ``` ### Erro: "Cannot find module" após build **Solução:** ```bash # Verificar se build foi completo ls -la build/ # Verificar imports (precisam ter extensão .js) grep -r "from.*\.ts" build/ || echo "OK: No .ts imports found" # Rebuild npm run build ``` --- ## ⚡ Erros de Execução ### Erro: "server does not support tools" **Sintoma:** ``` Error: server does not support tools at Client._onresponse (node_modules/@modelcontextprotocol/sdk/src/client/index.ts:270:23) ``` **Solução:** ```typescript // Em src/index.ts, adicionar capabilities ao servidor const server = new Server( { name: "mcp-wppconnect-server", version: "0.1.0", }, { capabilities: { tools: {}, // ADICIONE ESTA LINHA }, } ); ``` ### Erro: "Cannot read property 'getClient' of undefined" **Solução:** ```typescript // Verificar se SessionManager está importado corretamente import { SessionManager } from "./utils/sessionManager.js"; // Verificar instância const sessionManager = SessionManager.getInstance(); ``` ### Erro: "ToolResponse type mismatch" **Sintoma:** ``` Type 'ToolResponse' is not assignable to type '{ ok: boolean; error?: string; }' ``` **Solução:** ```typescript // Verificar interface ToolResponse em types/index.ts export interface ToolResponse { ok: boolean; error?: string; data?: any; } // Usar consistentemente return { ok: false, error: "Mensagem de erro" }; ``` --- ## 📱 Erros de Conexão WhatsApp ### Erro: "QR Code não é gerado" **Sintoma:** - `get_qr_snapshot` retorna vazio - Nenhum QR code aparece **Solução:** ```bash # Verificar logs DEBUG=mcp-wppconnect:* npm run dev # Verificar sessão anterior ls -la ~/.mcp-wppconnect/tokens/ # Limpar sessão corrompida rm -rf ~/.mcp-wppconnect/tokens/<sessionId>.json # Reiniciar servidor npm run dev ``` ### Erro: "Autenticação falha após scan QR" **Solução:** ```bash # Verificar conexão de internet ping google.com # Verificar se número está bloqueado no WhatsApp # (tentar scan com outro número) # Limpar todos os tokens rm -rf ~/.mcp-wppconnect/tokens/* # Verificar versão do WPPConnect npm list @wppconnect-team/wppconnect ``` ### Erro: "Client not authenticated" **Solução:** ```typescript // Antes de usar cliente, verificar autenticação const client = await sessionManager.getClient(sessionId); if (!client) { return { ok: false, error: "Session not found" }; } // Verificar se está autenticado try { const me = await client.getMe(); if (!me) { return { ok: false, error: "Client not authenticated" }; } } catch (error) { return { ok: false, error: "Failed to verify authentication" }; } ``` --- ## 🔑 Erros de Sessão ### Erro: "Session ID inválido" **Solução:** ```typescript // Validar sessionId (deve ser UUID v4) const { v4: uuidv4 } = require('uuid'); function isValidSessionId(sessionId) { const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; return uuidRegex.test(sessionId); } ``` ### Erro: "Máximo de sessões atingido" **Solução:** ```bash # Verificar sessões ativas DEBUG=mcp-wppconnect:* npm run dev # Aumentar limite em src/utils/sessionManager.ts private readonly MAX_SESSIONS = 20; // Aumentar de 10 para 20 # Ou configurar via variável de ambiente export MAX_SESSIONS=20 ``` ### Erro: "Sessão expirando frequentemente" **Solução:** ```bash # Verificar timeout de sessão # Em src/utils/sessionManager.ts, ajustar: private readonly SESSION_TIMEOUT = 48 * 60 * 60 * 1000; // 48 horas # Verificar se há limpeza automática desnecessária # Desabilitar limpeza para debug ``` --- ## 💬 Erros de Mensagens ### Erro: "Número de telefone inválido" **Solução:** ```typescript // Validar formato do número function validatePhoneNumber(phone) { // Remove tudo que não é dígito const cleaned = phone.replace(/\D/g, ''); // Verificar se tem entre 10-15 dígitos if (cleaned.length < 10 || cleaned.length > 15) { return false; } // Adicionar código do país se necessário if (cleaned.length === 10) { return '55' + cleaned; // Exemplo para Brasil } return cleaned; } ``` ### Erro: "Mensagem não enviada - timeout" **Solução:** ```bash # Verificar conexão de internet ping google.com # Verificar se WhatsApp Web está funcionando # Abrir https://web.whatsapp.com no navegador # Aumentar timeout # Em src/tools/messageTools.ts: const timeout = 30000; // 30 segundos ``` ### Erro: "Contato não encontrado" **Solução:** ```typescript // Verificar se contato existe na lista const contacts = await client.getContacts(); const contact = contacts.find(c => c.number === phoneNumber); if (!contact) { // Tentar enviar mesmo assim (WhatsApp busca automaticamente) try { await client.sendText(phoneNumber + '@c.us', message); } catch (error) { return { ok: false, error: "Contact not found or invalid" }; } } ``` --- ## 👥 Erros de Grupos/Comunidades ### Erro: "Group ID inválido" **Solução:** ```typescript // Validar formato do Group ID function isValidGroupId(groupId) { // WhatsApp group IDs terminam com @g.us return groupId.endsWith('@g.us') || groupId.length >= 20; } // Buscar grupos se ID não for fornecido const chats = await client.getAllChats(); const groups = chats.filter(chat => chat.isGroup); ``` ### Erro: "Participante não encontrado no grupo" **Solução:** ```typescript // Verificar participantes antes de promover/demover const participants = await client.getGroupParticipants(groupId); const participant = participants.find(p => p.id === participantId); if (!participant) { return { ok: false, error: "Participant not found in group" }; } // Verificar se já é admin const isAdmin = participant.isAdmin || participant.isSuperAdmin; ``` ### Erro: "Community não encontrada" **Solução:** ```typescript // Comunidades terminam com @newsletter function isValidCommunityId(communityId) { return communityId.endsWith('@newsletter') || communityId.length >= 25; } // Listar comunidades disponíveis const communities = await client.getCommunities(); ``` --- ## 🤖 Erros de Claude Desktop ### Erro: "Server not responding in Claude Desktop" **Solução:** ```bash # Verificar configuração do Claude Desktop # Arquivo: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) # ou %APPDATA%\Claude\claude_desktop_config.json (Windows) # Verificar se caminho está correto { "mcpServers": { "mcp-wppconnect-server": { "command": "node", "args": ["/caminho/completo/para/build/index.js"] } } } # Verificar permissões do arquivo ls -la /caminho/completo/para/build/index.js # Testar comando manualmente node /caminho/completo/para/build/index.js ``` ### Erro: "Tools não aparecem no Claude Desktop" **Solução:** ```bash # Verificar se servidor está rodando com capacidades DEBUG=mcp-wppconnect:* node build/index.js # Verificar se tools estão registradas # No código, verificar se tools array tem os tool objects # Reiniciar Claude Desktop após mudanças # Fechar completamente e reabrir ``` ### Erro: "Timeout ao chamar ferramentas" **Solução:** ```bash # Verificar logs do servidor DEBUG=mcp-wppconnect:* npm run dev # Aumentar timeout do MCP # Verificar documentação do SDK para timeout configuration # Verificar se operação WhatsApp está lenta # Testar manualmente no código ``` --- ## ⚡ Erros de Performance ### Erro: "Alta utilização de CPU/Memória" **Solução:** ```bash # Verificar uso de recursos pm2 monit # Limitar número de sessões export MAX_SESSIONS=5 # Implementar rate limiting # Adicionar delays entre operações # Verificar memory leaks node --inspect build/index.js ``` ### Erro: "Servidor lento para responder" **Solução:** ```bash # Verificar número de sessões ativas debug=mcp-wppconnect:* npm run dev # Implementar caching // Para getContacts, getChats, etc. const cache = new Map(); const CACHE_TTL = 5 * 60 * 1000; // 5 minutos # Otimizar queries WhatsApp // Buscar apenas dados necessários // Usar filtros quando disponíveis ``` ### Erro: "Vazamento de memória (Memory Leak)" **Solução:** ```typescript // Implementar cleanup adequado class SessionManager { private cleanupInterval: NodeJS.Timeout; constructor() { // Limpar sessões inativas a cada 30 minutos this.cleanupInterval = setInterval(() => { this.cleanupInactiveSessions(); }, 30 * 60 * 1000); } private cleanupInactiveSessions() { for (const [sessionId, client] of this._sessionMap.entries()) { if (this.isSessionInactive(sessionId)) { this.closeSession(sessionId); } } } } ``` --- ## 🔒 Problemas de Token/Segurança ### Erro: "Token não salvo/apagado" **Solução:** ```bash # Verificar permissões do diretório ls -la ~/.mcp-wppconnect/tokens/ # Criar diretório se necessário mkdir -p ~/.mcp-wppconnect/tokens chmod 700 ~/.mcp-wppconnect/tokens # Verificar espaço em disco df -h ``` ### Erro: "Token corrompido" **Solução:** ```bash # Remover token corrompido rm ~/.mcp-wppconnect/tokens/<sessionId>.json # Reinicializar sessão # Chamar initialize_session novamente ``` ### Erro: "Erro de criptografia (se implementado)" **Solução:** ```bash # Verificar chave de criptografia # Verificar se arquivo está corrompido # Restaurar de backup se disponível ``` --- ## 📝 Logs e Debugging ### Habilitar Debug Completo ```bash # Habilitar todos os logs de debug DEBUG=mcp-wppconnect:* npm run dev # Logs específicos DEBUG=mcp-wppconnect:session* npm run dev DEBUG=mcp-wppconnect:message* npm run dev DEBUG=mcp-wppconnect:error* npm run dev ``` ### Verificar Logs do Sistema ```bash # Logs PM2 pm2 logs mcp-wppconnect-server --lines 100 # Logs systemd (se usando) journalctl -u mcp-wppconnect -f # Logs de erro recentes tail -f logs/error.log ``` ### Criar Debug Script ```bash #!/bin/bash # debug.sh echo "=== MCP WPPConnect Debug Info ===" echo "Date: $(date)" echo "Node Version: $(node --version)" echo "NPM Version: $(npm --version)" echo "" echo "=== Process Status ===" pm2 status echo "" echo "=== Recent Errors ===" pm2 logs mcp-wppconnect-server --lines 20 | grep -i error echo "" echo "=== Disk Usage ===" df -h echo "" echo "=== Memory Usage ===" free -h echo "" echo "=== Token Files ===" ls -la ~/.mcp-wppconnect/tokens/ 2>/dev/null || echo "No token directory found" ``` --- ## ⚠️ Problemas Conhecidos ### 1. WPPConnect Limitações - **Problema**: Nem todos os métodos do WhatsApp estão disponíveis - **Solução**: Verificar [documentação WPPConnect](https://wppconnect.io/swagger/wppconnect-server/) para métodos suportados ### 2. WhatsApp Web Bloqueios - **Problema**: WhatsApp pode bloquear números por uso excessivo - **Solução**: - Implementar rate limiting - Usar intervalos entre mensagens - Evitar spam ### 3. Limite de Sessões - **Problema**: WhatsApp limita número de dispositivos - **Solução**: - Usar no máximo 4 dispositivos por número - Implementar fila de sessões ### 4. Atualizações do WhatsApp - **Problema**: WhatsApp atualiza frequentemente, quebrando integrações - **Solução**: - Manter WPPConnect atualizado - Testar após atualizações - Ter plano de rollback ### 5. MCP SDK Mudanças - **Problema**: SDK pode mudar interface - **Solução**: - Fixar versões no package.json - Testar antes de atualizar - Seguir changelog do MCP --- ## 🆘 Obtendo Ajuda ### Informações Necessárias Ao reportar um problema, inclua: 1. **Versões**: ```bash node --version npm --version npm list @wppconnect-team/wppconnect npm list @modelcontextprotocol/sdk ``` 2. **Logs de erro completos** 3. **Passos para reproduzir** 4. **Configuração do ambiente** 5. **Sistema operacional** ### Canais de Suporte 1. **GitHub Issues**: Reportar bugs 2. **Documentação**: Verificar README.md 3. **Logs**: Analisar mensagens de erro 4. **Comunidade**: Fóruns e grupos --- ## 📚 Referências Úteis - [WPPConnect Documentation](https://wppconnect.io/) - [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk) - [Node.js Debugging Guide](https://nodejs.org/en/docs/guides/debugging-getting-started/) - [PM2 Troubleshooting](https://pm2.keymetrics.io/docs/usage/quick-start/#troubleshooting)