feat: adiciona MCP Server para análise de mensagens do PostgreSQL

Implementa um servidor MCP (Model Context Protocol) completo que permite ao Claude analisar mensagens e dados do Evolution API diretamente do PostgreSQL. Funcionalidades incluídas: - list_instances: Lista instâncias WhatsApp - get_messages: Busca mensagens com filtros avançados - search_messages: Busca por conteúdo de texto - get_conversation: Obtém conversas completas - get_message_stats: Estatísticas detalhadas - get_contacts: Lista contatos - get_chats: Lista chats ativos - get_instance_details: Detalhes de instâncias - execute_query: Queries SQL personalizadas (apenas SELECT) Inclui documentação completa, guia rápido e exemplos de configuração para Claude Desktop.
2025-12-10 18:39:38 -06:00 · 2025-11-14 01:39:58 +00:00 · 2025-11-14 01:39:58 +00:00 · dc2f3fe93f
commit dc2f3fe93f
parent df20c5fc93
8 changed files with 1645 additions and 0 deletions
--- a/mcp-server/.env.example
+++ b/mcp-server/.env.example
@ -0,0 +1,6 @@
+# Evolution API MCP Server - Configuração de Ambiente
+
+# URL de conexão com o PostgreSQL
+# Formato: postgresql://usuario:senha@host:porta/database
+# Exemplo: postgresql://postgres:postgres@localhost:5432/evolution
+DATABASE_CONNECTION_URI=postgresql://usuario:senha@localhost:5432/evolution
--- a/mcp-server/.gitignore
+++ b/mcp-server/.gitignore
@ -0,0 +1,28 @@
+# Dependências
+node_modules/
+package-lock.json
+
+# Build
+dist/
+*.tsbuildinfo
+
+# Ambiente
+.env
+.env.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
--- a/mcp-server/QUICKSTART.md
+++ b/mcp-server/QUICKSTART.md
@ -0,0 +1,153 @@
+# 🚀 Guia Rápido - Evolution API MCP Server
+
+Este é um guia rápido para configurar o MCP Server em **5 minutos**.
+
+## Passo 1: Instalar Dependências
+
+```bash
+cd mcp-server
+npm install
+```
+
+## Passo 2: Configurar Banco de Dados
+
+Crie o arquivo `.env`:
+
+```bash
+cp .env.example .env
+```
+
+Edite `.env` e configure sua string de conexão PostgreSQL:
+
+```env
+DATABASE_CONNECTION_URI=postgresql://postgres:senha@localhost:5432/evolution
+```
+
+## Passo 3: Compilar
+
+```bash
+npm run build
+```
+
+## Passo 4: Configurar Claude Desktop
+
+### macOS/Linux
+
+1. Abra o arquivo de configuração:
+   ```bash
+   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
+   ```
+
+2. Cole esta configuração (ajuste o caminho):
+   ```json
+   {
+     "mcpServers": {
+       "evolution-api": {
+         "command": "node",
+         "args": [
+           "/home/user/evolution-api/mcp-server/dist/index.js"
+         ],
+         "env": {
+           "DATABASE_CONNECTION_URI": "postgresql://postgres:senha@localhost:5432/evolution"
+         }
+       }
+     }
+   }
+   ```
+
+### Windows
+
+1. Abra o arquivo de configuração:
+   ```
+   notepad %APPDATA%\Claude\claude_desktop_config.json
+   ```
+
+2. Cole esta configuração (ajuste o caminho):
+   ```json
+   {
+     "mcpServers": {
+       "evolution-api": {
+         "command": "node",
+         "args": [
+           "C:\\Users\\SeuUsuario\\evolution-api\\mcp-server\\dist\\index.js"
+         ],
+         "env": {
+           "DATABASE_CONNECTION_URI": "postgresql://postgres:senha@localhost:5432/evolution"
+         }
+       }
+     }
+   }
+   ```
+
+## Passo 5: Reiniciar Claude Desktop
+
+Feche completamente o Claude Desktop e abra novamente.
+
+## ✅ Testar
+
+Abra o Claude Desktop e digite:
+
+```
+Liste todas as instâncias do Evolution API
+```
+
+Se funcionar, você verá a lista de instâncias! 🎉
+
+## 🔍 Exemplos de Comandos
+
+Experimente estes comandos no Claude Desktop:
+
+```
+Mostre as últimas 10 mensagens da instância "minha-instancia"
+```
+
+```
+Busque mensagens contendo "pedido" nas últimas 24 horas
+```
+
+```
+Mostre estatísticas de mensagens da instância "vendas" agrupadas por dia
+```
+
+```
+Liste os contatos da instância "suporte"
+```
+
+```
+Mostre a conversa completa com o número 5511999999999@s.whatsapp.net
+```
+
+## 🐛 Problemas?
+
+### Claude Desktop não mostra o MCP
+
+1. Verifique se o caminho no `claude_desktop_config.json` está correto (use caminho ABSOLUTO)
+2. Verifique se o arquivo foi compilado: `ls mcp-server/dist/index.js`
+3. Reinicie o Claude Desktop completamente
+4. Veja os logs: Menu > Help > Show Logs
+
+### Erro de conexão com banco
+
+1. Teste a conexão manualmente:
+   ```bash
+   psql "postgresql://postgres:senha@localhost:5432/evolution"
+   ```
+2. Verifique se o PostgreSQL está rodando
+3. Verifique usuário, senha e nome do banco
+
+### Para testar localmente (sem Claude Desktop)
+
+```bash
+cd mcp-server
+npm run dev
+```
+
+Isso iniciará o servidor MCP em modo stdio (você verá uma mensagem no console).
+
+## 📚 Documentação Completa
+
+Para mais detalhes, consulte o [README.md](README.md) completo.
+
+---
+
+**Pronto!** Agora você pode analisar suas mensagens do WhatsApp com o poder do Claude! 🚀
--- a/mcp-server/README.md
+++ b/mcp-server/README.md
@ -0,0 +1,279 @@
+# Evolution API MCP Server
+
+**MCP Server** (Model Context Protocol) para análise de mensagens e dados do Evolution API através do PostgreSQL.
+
+Este servidor permite que o Claude (e outros clientes MCP) consultem e analisem mensagens do WhatsApp armazenadas no banco de dados do Evolution API de forma segura e eficiente.
+
+## 🚀 Funcionalidades
+
+### Ferramentas Disponíveis
+
+1. **`list_instances`** - Lista todas as instâncias WhatsApp cadastradas
+   - Filtra por status de conexão (open, close, connecting)
+   - Retorna informações básicas de cada instância
+
+2. **`get_messages`** - Busca mensagens com filtros avançados
+   - Filtra por instância, período, contato, tipo de mensagem
+   - Suporta paginação e ordenação
+   - Inclui informações de mídia associada
+
+3. **`search_messages`** - Busca mensagens por conteúdo de texto
+   - Pesquisa em mensagens de texto, legendas de mídia
+   - Suporta busca case-sensitive ou case-insensitive
+   - Filtra por instância e contato
+
+4. **`get_conversation`** - Obtém conversa completa entre contatos
+   - Retorna histórico de mensagens ordenado cronologicamente
+   - Suporta paginação para conversas longas
+   - Inclui contexto completo da conversa
+
+5. **`get_message_stats`** - Estatísticas detalhadas de mensagens
+   - Total de mensagens, enviadas vs recebidas
+   - Distribuição por tipo de mensagem
+   - Agrupamento por dia, hora ou tipo
+
+6. **`get_contacts`** - Lista contatos de uma instância
+   - Busca por nome ou número
+   - Inclui foto de perfil e última atualização
+
+7. **`get_chats`** - Lista chats ativos
+   - Filtra chats com mensagens não lidas
+   - Informações de última atividade
+
+8. **`get_instance_details`** - Detalhes completos de uma instância
+   - Configurações, webhooks, integrações
+   - Status de chatbots (Typebot, OpenAI, etc.)
+
+9. **`execute_query`** - Executa query SQL personalizada (avançado)
+   - Apenas queries SELECT (segurança)
+   - Para análises complexas e customizadas
+
+## 📦 Instalação
+
+### Pré-requisitos
+
+- Node.js 18+ ou 20+
+- PostgreSQL com Evolution API rodando
+- Acesso à string de conexão do banco de dados
+
+### Passo 1: Instalar dependências
+
+```bash
+cd mcp-server
+npm install
+```
+
+### Passo 2: Configurar variáveis de ambiente
+
+Copie o arquivo de exemplo e configure:
+
+```bash
+cp .env.example .env
+```
+
+Edite o arquivo `.env` e configure a string de conexão:
+
+```env
+DATABASE_CONNECTION_URI=postgresql://usuario:senha@localhost:5432/evolution
+```
+
+### Passo 3: Compilar o projeto
+
+```bash
+npm run build
+```
+
+### Passo 4: Testar localmente
+
+```bash
+npm run dev
+```
+
+## 🔧 Configuração no Claude Desktop
+
+Para usar este MCP server com o Claude Desktop, adicione a configuração no arquivo de configuração do Claude:
+
+### No macOS/Linux
+
+Edite o arquivo: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "evolution-api": {
+      "command": "node",
+      "args": [
+        "/caminho/completo/para/evolution-api/mcp-server/dist/index.js"
+      ],
+      "env": {
+        "DATABASE_CONNECTION_URI": "postgresql://usuario:senha@localhost:5432/evolution"
+      }
+    }
+  }
+}
+```
+
+### No Windows
+
+Edite o arquivo: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "evolution-api": {
+      "command": "node",
+      "args": [
+        "C:\\caminho\\completo\\para\\evolution-api\\mcp-server\\dist\\index.js"
+      ],
+      "env": {
+        "DATABASE_CONNECTION_URI": "postgresql://usuario:senha@localhost:5432/evolution"
+      }
+    }
+  }
+}
+```
+
+**Importante:** Substitua `/caminho/completo/para` pelo caminho real onde o projeto está instalado.
+
+## 📖 Exemplos de Uso
+
+Depois de configurado, você pode interagir com o Claude Desktop usando comandos naturais:
+
+### Listar instâncias
+
+```
+Mostre todas as instâncias WhatsApp ativas
+```
+
+### Buscar mensagens
+
+```
+Busque as últimas 50 mensagens da instância "minha-instancia" recebidas hoje
+```
+
+### Pesquisar por conteúdo
+
+```
+Procure mensagens que contenham "orçamento" na instância "vendas"
+```
+
+### Obter conversa
+
+```
+Mostre a conversa completa com o contato 5511999999999@s.whatsapp.net
+```
+
+### Estatísticas
+
+```
+Mostre estatísticas de mensagens da instância "suporte" agrupadas por hora
+```
+
+### Análise avançada
+
+```
+Execute uma query para contar mensagens por tipo de mídia na última semana
+```
+
+## 🛠️ Desenvolvimento
+
+### Estrutura do projeto
+
+```
+mcp-server/
+├── src/
+│   └── index.ts          # Código principal do servidor MCP
+├── dist/                 # Código compilado (gerado pelo build)
+├── package.json          # Dependências e scripts
+├── tsconfig.json         # Configuração TypeScript
+├── .env                  # Variáveis de ambiente (não commitar!)
+├── .env.example          # Exemplo de configuração
+└── README.md             # Esta documentação
+```
+
+### Scripts disponíveis
+
+- `npm run build` - Compila o TypeScript para JavaScript
+- `npm run dev` - Roda em modo desenvolvimento com hot reload
+- `npm start` - Executa o servidor compilado
+- `npm run watch` - Modo watch para desenvolvimento
+
+### Adicionando novas ferramentas
+
+1. Adicione a definição da ferramenta no array `TOOLS`
+2. Implemente o método correspondente na classe `EvolutionMCPServer`
+3. Adicione o case no switch do `CallToolRequestSchema` handler
+4. Compile e teste
+
+## 🔒 Segurança
+
+- **Queries SQL**: Apenas queries SELECT são permitidas na ferramenta `execute_query`
+- **Validação**: Palavras-chave perigosas (INSERT, UPDATE, DELETE, etc.) são bloqueadas
+- **Conexão**: Use sempre variáveis de ambiente para credenciais
+- **Pool de conexões**: Limite de 10 conexões simultâneas ao PostgreSQL
+
+## 📊 Schema do Banco de Dados
+
+O servidor trabalha com as seguintes tabelas principais:
+
+- `Instance` - Instâncias WhatsApp
+- `Message` - Mensagens enviadas e recebidas
+- `Contact` - Contatos sincronizados
+- `Chat` - Conversas ativas
+- `Media` - Arquivos de mídia
+- `Webhook` - Configurações de webhook
+- `Setting` - Configurações de instância
+- E outras tabelas de integrações (Chatwoot, Typebot, OpenAI, etc.)
+
+Para mais detalhes, consulte o schema Prisma em `prisma/postgresql-schema.prisma`.
+
+## 🐛 Troubleshooting
+
+### Erro de conexão com o banco
+
+```
+Erro: password authentication failed for user "postgres"
+```
+
+**Solução**: Verifique se a string de conexão está correta no arquivo `.env` ou na configuração do Claude Desktop.
+
+### Servidor não aparece no Claude Desktop
+
+1. Verifique se o arquivo de configuração está no local correto
+2. Certifique-se de que o caminho para o `index.js` está correto (absoluto)
+3. Reinicie o Claude Desktop completamente
+4. Verifique os logs do Claude Desktop (Menu > Help > Show Logs)
+
+### Timeout nas queries
+
+Se as queries estão demorando muito:
+
+1. Crie índices no banco de dados para campos frequentemente consultados
+2. Reduza o `limit` das queries
+3. Use filtros mais específicos (datas, instâncias)
+
+## 📝 Licença
+
+Apache-2.0 - Mesma licença do Evolution API
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor:
+
+1. Faça um fork do projeto
+2. Crie uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
+3. Commit suas mudanças (`git commit -m 'feat: Adiciona nova feature'`)
+4. Push para a branch (`git push origin feature/MinhaFeature`)
+5. Abra um Pull Request
+
+## 📞 Suporte
+
+Para problemas e dúvidas:
+
+- Abra uma issue no repositório do Evolution API
+- Consulte a documentação do MCP: https://modelcontextprotocol.io/
+- Comunidade Evolution API: https://evolution-api.com/
+
+---
+
+**Desenvolvido para o Evolution API** - A melhor API REST para WhatsApp
--- a/mcp-server/claude_desktop_config.example.json
+++ b/mcp-server/claude_desktop_config.example.json
@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "evolution-api": {
+      "command": "node",
+      "args": [
+        "/CAMINHO/COMPLETO/PARA/evolution-api/mcp-server/dist/index.js"
+      ],
+      "env": {
+        "DATABASE_CONNECTION_URI": "postgresql://usuario:senha@localhost:5432/evolution"
+      }
+    }
+  }
+}
--- a/mcp-server/package.json
+++ b/mcp-server/package.json
@ -0,0 +1,37 @@
+{
+  "name": "evolution-api-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP Server para análise de mensagens do Evolution API via PostgreSQL",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "evolution-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "watch": "tsx watch src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "evolution-api",
+    "whatsapp",
+    "database",
+    "postgresql"
+  ],
+  "author": "Evolution API",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "pg": "^8.13.1",
+    "dotenv": "^16.4.7"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@types/pg": "^8.11.10",
+    "tsx": "^4.20.5",
+    "typescript": "^5.7.2"
+  }
+}
--- a/mcp-server/src/index.ts
+++ b/mcp-server/src/index.ts
--- a/mcp-server/tsconfig.json
+++ b/mcp-server/tsconfig.json
@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}