# Uazapi MCP Server

MCP Server para integração com a API Uazapi WhatsApp v2.0

## Visão Geral

Este servidor MCP (Model Context Protocol) permite que LLMs interajam com a API do Uazapi para enviar e gerenciar mensagens no WhatsApp. Ele fornece ferramentas para:

- ✉️ Enviar mensagens de texto
- 📎 Enviar mídia (imagens, vídeos, áudios, documentos)
- 👥 Gerenciar contatos
- 💬 Listar conversas
- 🔄 E mais funcionalidades conforme documentação da API

## Instalação

### 1. Instalar Dependências

```bash
# Usando uv (recomendado)
uv pip install -r requirements.txt

# Ou usando pip
pip install -r requirements.txt
```

### 2. Configurar Variáveis de Ambiente

Você precisa configurar suas credenciais da Uazapi:

```bash
export UAZAPI_API_KEY="sua_chave_api_aqui"
export UAZAPI_INSTANCE_ID="seu_instance_id_aqui"
```

**Como obter suas credenciais:**
1. Acesse https://uazapi.com/
2. Faça login na sua conta
3. Vá para a seção de API
4. Copie seu API Key e Instance ID

### 3. Testar o Servidor

```bash
# Verificar sintaxe
python -m py_compile uazapi_mcp.py

# Testar execução com timeout
timeout 5s python uazapi_mcp.py || echo "Server started successfully"
```

### 4. Instalar no Claude Desktop

```bash
# Usando uv
uv run mcp install uazapi_mcp.py --name "Uazapi WhatsApp"

# Ou adicionar manualmente ao claude_desktop_config.json
```

**Configuração manual no `claude_desktop_config.json`:**

```json
{
  "mcpServers": {
    "uazapi": {
      "command": "python",
      "args": ["/caminho/completo/para/uazapi_mcp.py"],
      "env": {
        "UAZAPI_API_KEY": "sua_chave_aqui",
        "UAZAPI_INSTANCE_ID": "seu_instance_id_aqui"
      }
    }
  }
}
```

## Ferramentas Disponíveis

### 1. `uazapi_send_text_message`
Envia mensagem de texto para um contato do WhatsApp.

**Parâmetros:**
- `phone` (string): Número do destinatário com código do país (ex: "5511999999999")
- `message` (string): Conteúdo da mensagem (1-4096 caracteres)

**Exemplo de uso:**
```
Envie "Olá, tudo bem?" para +55 11 99999-9999
```

### 2. `uazapi_send_media_message`
Envia mídia (imagem, vídeo, áudio ou documento) para um contato.

**Parâmetros:**
- `phone` (string): Número do destinatário
- `media_url` (string): URL pública do arquivo (HTTPS)
- `media_type` (enum): Tipo da mídia (image/video/audio/document)
- `caption` (string, opcional): Legenda para a mídia
- `filename` (string, opcional): Nome do arquivo para documentos

**Exemplo de uso:**
```
Envie a imagem https://example.com/foto.jpg com legenda "Confira!" para 5511999999999
```

### 3. `uazapi_get_contacts`
Recupera lista de contatos do WhatsApp.

**Parâmetros:**
- `limit` (int, opcional): Máximo de contatos (1-100, padrão: 20)
- `offset` (int, opcional): Número de contatos para pular (padrão: 0)
- `response_format` (enum, opcional): Formato da resposta (markdown/json, padrão: markdown)

**Exemplo de uso:**
```
Liste meus contatos do WhatsApp
Mostre os primeiros 50 contatos em formato JSON
```

### 4. `uazapi_get_chats`
Recupera lista de conversas recentes.

**Parâmetros:**
- `limit` (int, opcional): Máximo de conversas (1-100, padrão: 20)
- `offset` (int, opcional): Número de conversas para pular (padrão: 0)
- `response_format` (enum, opcional): Formato da resposta (markdown/json)

**Exemplo de uso:**
```
Mostre minhas conversas recentes no WhatsApp
Liste os últimos 30 chats
```

## Características e Boas Práticas

### Validação de Entrada
- ✅ Todos os parâmetros são validados usando Pydantic v2
- ✅ Números de telefone são formatados automaticamente
- ✅ URLs são validadas antes do envio
- ✅ Limites de caracteres são aplicados

### Tratamento de Erros
- ✅ Mensagens de erro claras e acionáveis
- ✅ Orientação sobre como resolver problemas
- ✅ Tratamento específico para cada código de status HTTP

### Paginação
- ✅ Suporte para grandes conjuntos de dados
- ✅ Metadados de paginação (`has_more`, `next_offset`, `total_count`)
- ✅ Limites padrão razoáveis (20 itens)

### Truncamento
- ✅ Limite de 25.000 caracteres por resposta
- ✅ Truncamento gracioso com mensagens claras
- ✅ Orientação sobre como obter mais dados

### Formatos de Resposta
- ✅ **Markdown**: Para leitura humana, formatado e organizado
- ✅ **JSON**: Para processamento programático, dados completos

## Segurança

- 🔒 API Keys armazenadas em variáveis de ambiente (nunca no código)
- 🔒 Validação de entrada para prevenir injeção
- 🔒 URLs validadas (apenas HTTPS para mídia)
- 🔒 Rate limiting tratado adequadamente
- 🔒 Mensagens de erro não expõem detalhes internos

## Desenvolvimento

### Estrutura do Código

```
uazapi_mcp.py
├── Imports e Configuração
├── Constantes (API_BASE_URL, CHARACTER_LIMIT)
├── Enums (ResponseFormat, MessageType)
├── Funções Utilitárias Compartilhadas
│   ├── _validate_auth()
│   ├── _get_auth_headers()
│   ├── _make_api_request()
│   ├── _handle_api_error()
│   ├── _format_phone_number()
│   └── _truncate_response()
├── Modelos Pydantic para Validação
│   ├── SendTextMessageInput
│   ├── SendMediaMessageInput
│   ├── GetContactsInput
│   └── GetChatsInput
├── Implementações de Ferramentas
│   ├── uazapi_send_text_message
│   ├── uazapi_send_media_message
│   ├── uazapi_get_contacts
│   └── uazapi_get_chats
└── Entry Point (if __name__ == "__main__")
```

### Adicionar Novos Endpoints

Para adicionar novos endpoints da API Uazapi:

1. **Criar Modelo Pydantic** para validação de entrada
2. **Implementar função de ferramenta** com decorador `@mcp.tool()`
3. **Usar funções utilitárias** compartilhadas (`_make_api_request`, `_handle_api_error`)
4. **Adicionar anotações** apropriadas (readOnlyHint, destructiveHint, etc.)
5. **Documentar** com docstring completa e exemplos

**Exemplo de template:**

```python
class NovoEndpointInput(BaseModel):
    """Descrição do modelo."""
    model_config = ConfigDict(
        str_strip_whitespace=True,
        validate_assignment=True,
        extra='forbid'
    )

    param1: str = Field(..., description="Descrição")

@mcp.tool(
    name="uazapi_novo_endpoint",
    annotations={
        "title": "Título Legível",
        "readOnlyHint": True,  # Ajustar conforme necessário
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": True
    }
)
async def uazapi_novo_endpoint(params: NovoEndpointInput) -> str:
    """
    Descrição completa da ferramenta.

    Args:
        params: Documentação dos parâmetros

    Returns:
        Descrição do retorno com exemplos
    """
    try:
        response = await _make_api_request(
            endpoint="caminho/do/endpoint",
            method="GET",
            params={"key": params.param1}
        )
        return format_response(response)
    except Exception as e:
        return _handle_api_error(e)
```

## Próximos Passos

Para expandir este servidor, você pode adicionar:

- [ ] Grupos e Comunidades
  - Criar grupos
  - Adicionar/remover participantes
  - Enviar mensagens para grupos
  - Gerenciar admins

- [ ] Mensagens Avançadas
  - Enviar localização
  - Enviar contatos
  - Enviar stickers
  - Mensagens agendadas
  - Respostas rápidas

- [ ] Status e Presença
  - Atualizar status
  - Ver status de contatos
  - Gerenciar presença (online/offline)

- [ ] Webhooks e Eventos
  - Configurar webhooks
  - Receber mensagens
  - Notificações de status

- [ ] Mensagens e Histórico
  - Buscar mensagens
  - Recuperar histórico de conversas
  - Marcar como lido/não lido

## Documentação da API

Para mais detalhes sobre os endpoints disponíveis, consulte:
- **Documentação oficial**: https://docs.uazapi.com/
- **Enviar Mensagem**: https://docs.uazapi.com/tag/Enviar%20Mensagem
- **Contatos**: https://docs.uazapi.com/tag/Contatos
- **Grupos**: https://docs.uazapi.com/tag/Grupos%20e%20Comunidades

## Suporte e Contribuições

Este é um servidor MCP base com as funcionalidades essenciais. Você pode:

1. **Estender** adicionando novos endpoints
2. **Customizar** ajustando limites e formatos
3. **Integrar** com outros MCP servers
4. **Compartilhar** suas melhorias

## Licença

Este projeto é fornecido como exemplo de implementação de MCP server.

---

**Desenvolvido com ❤️ usando [MCP (Model Context Protocol)](https://modelcontextprotocol.io/)**