Evolution API MCP Server

# Próximos Passos e Considerações ## ✅ Implementação Concluída ### Estrutura Base - [x] pyproject.toml com todas as dependências - [x] Configuração com Pydantic e validação - [x] Wrapper do EvolutionClient com error handling - [x] Servidor MCP com FastMCP - [x] Todos os tools planejados ### Tools Implementados (17 total) #### Envio de Mensagens (7 tools) - [x] `send_text_message` - Mensagens de texto - [x] `send_image` - Imagens - [x] `send_document` - Documentos - [x] `send_video` - Vídeos - [x] `send_audio` - Áudios - [x] `send_location` - Localização - [x] `send_contact` - Contatos #### Gerenciamento de Chats (5 tools) - [x] `list_chats` - Listar conversas - [x] `get_chat_messages` - Mensagens de uma conversa - [x] `get_chat_by_number` - Obter chat_id do número - [x] `get_unread_messages` - Mensagens não lidas - [x] `mark_chat_as_read` - Marcar como lido #### Status e Presença (3 tools) - [x] `get_connection_status` - Status da conexão - [x] `set_presence` - Definir presença - [x] `get_instance_info` - Info da instância ### Documentação - [x] README.md completo - [x] INSTALL.md com guia de instalação - [x] .env.example - [x] Docstrings em todos os tools - [x] Exemplos de uso ## ⚠️ Verificações Necessárias ### API da evolutionapi v0.1.2 Os métodos a seguir precisam ser **verificados e ajustados** conforme a API real da biblioteca `evolutionapi`: #### Prioridade ALTA (Core Functionality) 1. **send_text** - Verificar parâmetros (mentions, link_preview) 2. **send_media** - Confirmar estrutura de parâmetros 3. **get_connection_state** - Validar formato de retorno #### Prioridade MÉDIA (Extended Features) 4. **send_location** - API exata (latitude, longitude, name, address) 5. **send_contact** - Formato de contato correto 6. **list_chats** - Estrutura de retorno e paginação 7. **get_chat_messages** - Paginação e filtros 8. **get_unread_messages** - Formato de retorno #### Prioridade BAIXA (Nice to Have) 9. **set_presence** - Valores válidos de status 10. **mark_as_read** - Nome do método correto ### Como Verificar ```python # Teste manual da API from evolutionapi.client import EvolutionClient client = EvolutionClient( base_url="https://pevo.ntropy.com.br", api_token="9795FDFBB464-495E-A823-28573A5D39EE" ) # Inspecionar métodos disponíveis print(dir(client)) print(dir(client.messages)) print(dir(client.instance)) # Testar um envio simples response = client.messages.send_text( instance="personal_pablo_bispo_wpp", number="5511999999999", text="Teste" ) print(response) ``` ## 📋 Próximas Ações ### 1. Instalação (Prioridade CRÍTICA) ```bash cd /Users/pablofernando/projects/mcp/evoapi-mcp uv run mcp install src/evoapi_mcp/server.py ``` Ou configurar manualmente (veja INSTALL.md). ### 2. Teste Básico Após instalar, testar no Claude Desktop: ``` Verifique o status da conexão WhatsApp ``` Se funcionar, testar envio: ``` Envie uma mensagem para [seu número] dizendo "Teste MCP" ``` ### 3. Ajustar APIs Conforme Necessário Quando encontrar erros nos tools, ajuste os métodos em: - `src/evoapi_mcp/client.py` (métodos base) - `src/evoapi_mcp/server.py` (chamadas aos métodos) ### 4. Melhorias Futuras (Opcional) #### Features Adicionais - [ ] Webhook listeners para mensagens recebidas - [ ] Busca avançada de mensagens (por texto, data, tipo) - [ ] Suporte a grupos (listar, enviar, gerenciar) - [ ] Envio em massa (múltiplos destinatários) - [ ] Templates de mensagens - [ ] Agendamento de mensagens #### Qualidade de Código - [ ] Testes unitários (pytest) - [ ] Testes de integração - [ ] Type hints completos - [ ] Linting (ruff, mypy) - [ ] CI/CD pipeline #### Documentação - [ ] Vídeo tutorial - [ ] Casos de uso práticos - [ ] FAQ expandido - [ ] Contribuindo (CONTRIBUTING.md) ## 🐛 Debugging ### Logs Detalhados Todos os logs vão para stderr. Para debug intenso, adicione mais logging em `client.py`: ```python self._log(f"DEBUG: Chamando método X com params Y", "DEBUG") ``` ### Testar em Modo Dev ```bash uv run mcp dev src/evoapi_mcp/server.py ``` Interface web em `http://localhost:5173` permite testar cada tool individualmente. ### Verificar Chamadas HTTP Se precisar debugar as chamadas HTTP da Evolution API, pode usar um proxy como mitmproxy: ```bash pip install mitmproxy mitmproxy -p 8888 ``` E configurar proxy no cliente (se a lib suportar). ## 📚 Recursos Úteis ### Documentação - [Evolution API Docs](https://doc.evolution-api.com/) - [MCP Docs](https://modelcontextprotocol.io/) - [FastMCP Docs](https://github.com/modelcontextprotocol/python-sdk) ### Cliente Evolution Python - [GitHub](https://github.com/EvolutionAPI/evolution-client-python) - [PyPI](https://pypi.org/project/evolutionapi/) ### Exemplos - Ver `README.md` para exemplos de uso - Ver `INSTALL.md` para instalação passo a passo ## 🔒 Segurança ### IMPORTANTE - ✅ `.env` está no `.gitignore` - ✅ Token não aparece em logs - ⚠️ Nunca commitar `.env` com credenciais - ⚠️ Usar HTTPS em produção (já configurado) - ⚠️ Não expor servidor MCP publicamente ### Boas Práticas 1. Rotacionar token periodicamente 2. Usar variáveis de ambiente em produção 3. Limitar acesso ao servidor Evolution API 4. Monitorar uso e logs ## 📞 Suporte Se encontrar problemas: 1. Verifique TROUBLESHOOTING no README.md 2. Consulte documentação da Evolution API 3. Verifique logs do Claude Desktop 4. Teste em modo dev (`mcp dev`) ## 🎯 Status do Projeto **Versão:** 0.1.0 **Status:** ✅ MVP Completo - Pronto para Teste **Última Atualização:** 2025-10-23 **Próximo Milestone:** Validar todas as APIs e ajustar conforme necessário --- **Nota:** Este é um MVP funcional. Algumas APIs podem precisar de ajustes conforme a versão 0.1.2 da biblioteca `evolutionapi`. Teste e ajuste conforme necessário.