# Evolution MCP Server

Servidor MCP (Model Context Protocol) para integração com Evolution API WhatsApp.

## 📋 Descrição

Este servidor expõe ferramentas MCP para gerenciar instâncias WhatsApp e enviar mensagens através da Evolution API.

## 🚀 Funcionalidades

O servidor oferece as seguintes ferramentas MCP:

### 1. **create_instance**
Cria uma nova instância WhatsApp.

**Parâmetros:**
- `instanceName` (obrigatório): Nome único da instância
- `qrcode` (opcional): Gerar QR Code (padrão: true)
- `integration` (opcional): Tipo de integração (padrão: "WHATSAPP-BAILEYS")

**Exemplo:**
```json
{
  "instanceName": "minha_instancia",
  "qrcode": true,
  "integration": "WHATSAPP-BAILEYS"
}
```

### 2. **delete_instance**
Deleta uma instância existente.

**Parâmetros:**
- `instanceName` (obrigatório): Nome da instância a ser deletada

**Exemplo:**
```json
{
  "instanceName": "minha_instancia"
}
```

### 3. **check_whatsapp_numbers**
Verifica quais números são válidos no WhatsApp.

**Parâmetros:**
- `instanceName` (obrigatório): Nome da instância
- `numbers` (obrigatório): Lista de números para verificar

**Exemplo:**
```json
{
  "instanceName": "minha_instancia",
  "numbers": ["5511999999999", "5511888888888"]
}
```

### 4. **send_text**
Envia uma mensagem de texto.

**Parâmetros:**
- `instanceName` (obrigatório): Nome da instância
- `number` (obrigatório): Número do destinatário
- `text` (obrigatório): Texto da mensagem

**Exemplo:**
```json
{
  "instanceName": "minha_instancia",
  "number": "5511999999999",
  "text": "Olá! Esta é uma mensagem de teste."
}
```

### 5. **send_media**
Envia mídia (imagem/vídeo/documento/áudio).

**Parâmetros:**
- `instanceName` (obrigatório): Nome da instância
- `number` (obrigatório): Número do destinatário
- `mediatype` (obrigatório): Tipo de mídia (image, video, document, audio)
- `media` (obrigatório): URL da mídia ou base64
- `mimetype` (obrigatório): MIME type (ex: image/png, video/mp4)
- `caption` (opcional): Legenda da mídia
- `fileName` (opcional): Nome do arquivo

**Exemplo:**
```json
{
  "instanceName": "minha_instancia",
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://exemplo.com/imagem.png",
  "mimetype": "image/png",
  "caption": "Confira esta imagem!",
  "fileName": "imagem.png"
}
```

### 6. **fetch_profile**
Busca informações do perfil de um contato.

**Parâmetros:**
- `instanceName` (obrigatório): Nome da instância
- `number` (obrigatório): Número do contato

**Exemplo:**
```json
{
  "instanceName": "minha_instancia",
  "number": "5511999999999"
}
```

### 7. **connection_state**
Verifica o estado da conexão da instância.

**Parâmetros:**
- `instanceName` (obrigatório): Nome da instância

**Exemplo:**
```json
{
  "instanceName": "minha_instancia"
}
```

### 8. **logout_instance**
Faz logout/desconecta uma instância WhatsApp.

**Parâmetros:**
- `instanceName` (obrigatório): Nome da instância para desconectar

**Exemplo:**
```json
{
  "instanceName": "minha_instancia"
}
```

## 🛠️ Requisitos

- Python 3.11.11
- Docker e Docker Compose
- Evolution API em execução
- Claude Desktop (para usar o servidor MCP)

## 📦 Instalação

### Com Docker Compose (Recomendado)

1. Clone o repositório:
```bash
git clone <repo-url>
cd evolution_mcp
```

2. Copie o arquivo de exemplo de variáveis de ambiente:
```bash
copy .env.example .env
```

3. Edite o arquivo `.env` e configure suas credenciais:
```env
EVOLUTION_API_KEY=sua_api_key_aqui
EVOLUTION_BASE_URL=http://evolution-api:8080
LOG_LEVEL=INFO
```

4. Construa e inicie o container:
```bash
docker-compose up -d --build
```

5. Configure o Claude Desktop editando o arquivo:
`%APPDATA%\Claude\claude_desktop_config.json`

Adicione:
```json
{
  "mcpServers": {
    "evolution-api": {
      "command": "docker",
      "args": ["exec", "-i", "evolution-mcp", "python", "-m", "mcp_server"]
    }
  }
}
```

6. Reinicie o Claude Desktop

### Desenvolvimento Local com Conda

1. Crie o ambiente conda:
```bash
conda create -n evolution_mcp python=3.11.11
conda activate evolution_mcp
```

2. Instale as dependências:
```bash
pip install -r requirements.txt
```

3. Configure as variáveis de ambiente:
```bash
set EVOLUTION_API_KEY=sua_api_key_aqui
set EVOLUTION_BASE_URL=http://localhost:8080
set LOG_LEVEL=DEBUG
```

4. Execute o servidor:
```bash
python -m mcp_server
```

## 🔧 Configuração

### Variáveis de Ambiente

| Variável | Descrição | Padrão |
|----------|-----------|--------|
| `EVOLUTION_API_KEY` | API Key da Evolution API | (obrigatório) |
| `EVOLUTION_BASE_URL` | URL base da Evolution API | http://evolution-api:8080 |
| `LOG_LEVEL` | Nível de log (DEBUG, INFO, WARNING, ERROR) | INFO |

### Portas

- **5020**: Porta do servidor MCP

## 🐳 Docker

### Dockerfile

O projeto inclui um Dockerfile otimizado para Python 3.11.11.

### Docker Compose

O `docker-compose.yml` está configurado com:
- Rede isolada (`evolution-network`)
- Volume para desenvolvimento em tempo real (`./src:/app/src`)
- Reinício automático (`restart: unless-stopped`)
- Variáveis de ambiente configuráveis

## 📝 Estrutura do Projeto

```
evolution_mcp/
├── mcp_server.py          # Servidor MCP principal
├── Dockerfile             # Imagem Docker
├── docker-compose.yml     # Orquestração Docker
├── requirements.txt       # Dependências Python
├── .env.example          # Exemplo de variáveis de ambiente
├── SECURITY.md           # Guia de segurança
└── README.md             # Esta documentação
```

## 🔍 Logs e Debug

Para ativar logs detalhados:

```bash
set LOG_LEVEL=DEBUG
```

Ou no `.env`:
```env
LOG_LEVEL=DEBUG
```

## 🤝 Integração com Evolution API

O servidor se comunica com a Evolution API através de requisições HTTP, incluindo automaticamente o header `apikey` em todas as requisições.

### Endpoints da Evolution API Utilizados

- `POST /instance/create` - Criar instância
- `DELETE /instance/delete/{instanceName}` - Deletar instância
- `POST /chat/whatsappNumbers/{instanceName}` - Verificar números
- `POST /message/sendText/{instanceName}` - Enviar texto
- `POST /message/sendMedia/{instanceName}` - Enviar mídia
- `GET /chat/fetchProfile/{instanceName}` - Buscar perfil

## 🔌 Integração com Claude Desktop

O servidor MCP foi projetado para ser usado com o Claude Desktop via Docker:

1. O container fica rodando em modo daemon (não executa o servidor automaticamente)
2. O Claude Desktop conecta via `docker exec -i` quando precisa usar as ferramentas
3. A comunicação acontece via STDIO (stdin/stdout)

### Configuração do Claude Desktop

Edite: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "evolution-api": {
      "command": "docker",
      "args": ["exec", "-i", "evolution-mcp", "python", "-m", "mcp_server"]
    }
  }
}
```

**Importante**: O container precisa estar rodando antes de usar as ferramentas no Claude Desktop.

## 🚨 Tratamento de Erros

O servidor trata os seguintes tipos de erros:

- **Erros HTTP**: Retorna status code e mensagem da Evolution API
- **Erros de validação**: Valida parâmetros antes de enviar
- **Erros de conexão**: Timeout de 30 segundos por requisição
- **Erros desconhecidos**: Logs detalhados para debug

## 📄 Licença

Este projeto é fornecido como está, sem garantias.

## 🆘 Suporte

Para problemas com:
- **Evolution API**: Consulte a documentação oficial da Evolution API
- **MCP**: Consulte a documentação do Model Context Protocol
- **Este servidor**: Abra uma issue no repositório

## 🔄 Atualizações

Para atualizar o servidor:

```bash
docker-compose down
docker-compose pull
docker-compose up -d
```

## 🐛 Troubleshooting

### Container em loop de restart
Se o container ficar reiniciando continuamente:
```bash
# Pare o container
docker-compose down

# Reconstrua com as mudanças
docker-compose up -d --build

# Verifique que o container está rodando
docker ps | findstr evolution-mcp
```

### Claude Desktop não encontra as ferramentas
1. Verifique se o container está rodando: `docker ps`
2. Teste a conexão manualmente:
```bash
docker exec -i evolution-mcp python -m mcp_server
```
3. Reinicie o Claude Desktop completamente
4. Verifique os logs do Claude Desktop em:
`%APPDATA%\Claude\logs\mcp-server-evolution-api.log`

### Erro de API Key
Se receber erros de autenticação:
1. Verifique o arquivo `.env`
2. Recrie o container:
```bash
docker-compose down
docker-compose up -d
```

### Teste manual das ferramentas
Para testar se o servidor está funcionando:
```bash
docker exec -it evolution-mcp python -c "from mcp_server import evolution_client; print(evolution_client.base_url)"
```

## 🔒 Segurança

### Níveis de Proteção

O servidor MCP tem múltiplas camadas de segurança:

1. **STDIO (não HTTP)**: Servidor usa stdin/stdout, não expõe porta HTTP pública
2. **Docker Isolation**: Requer acesso ao Docker para executar `docker exec`
3. **Evolution API Key**: Toda comunicação requer chave válida
4. **Token MCP** (Opcional): Autenticação adicional ao servidor MCP
5. **Audit Logging**: Registra todas as operações

### Configuração de Segurança Recomendada

Para ambientes de produção (VPS):

```bash
# 1. Gerar token de segurança
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 2. Adicionar ao .env
echo "MCP_SERVER_TOKEN=seu_token_aqui" >> .env

# 3. Habilitar logs de auditoria
echo "ENABLE_AUDIT_LOG=true" >> .env
```

**Importante**: Em VPS, configure também:
- Firewall (UFW/iptables)
- SSH com chaves (sem senha)
- Acesso limitado ao Docker daemon

📖 **Guia completo**: Veja `SECURITY.md` para detalhes completos

## ⚠️ Notas Importantes

1. Certifique-se de que a Evolution API está acessível na URL configurada
2. Use números no formato internacional sem '+' (ex: 5511999999999)
3. Para desenvolvimento, use volumes montados para hot-reload
4. Em **produção (VPS)**, configure `MCP_SERVER_TOKEN` e firewall
5. Mantenha suas chaves seguras e não commite no Git
6. O container precisa estar **rodando** para o Claude Desktop conectar
7. Após editar `claude_desktop_config.json`, sempre reinicie o Claude Desktop
8. Monitore logs de auditoria regularmente: `docker-compose logs -f | findstr AUDIT`