prompt.md•7.56 kB
# MCP WPPConnect Server - Corrected & Validated Prompt
## Objetivo
Criar um servidor MCP (Model Context Protocol) em TypeScript que incorpore a lib core `@wppconnect-team/wppconnect` e exponha tools para um agente Claude operar WhatsApp:
- Gerenciamento de sessões (login, QR Code)
- Envio de mensagens
- Operações em grupos (promover/rebaixar participantes)
- Operações em comunidades (criar, adicionar subgrupos, promover/rebaixar participantes)
## Referências Oficiais
- **WPPConnect (lib core)**: https://github.com/wppconnect-team/wppconnect
- **WPPConnect Docs**: https://wppconnect.io
- **WPPConnect API Swagger**: https://wppconnect.io/swagger/wppconnect-server/
- **WPPConnect Whatsapp Class**: https://wppconnect.io/wppconnect/classes/Whatsapp.html
- **MCP SDK TypeScript**: https://github.com/modelcontextprotocol/typescript-sdk
## Correções & Validações Identificadas
### 1. Métodos WPPConnect Validados
✅ **Sessão**: `client.getMe()`, `client.logoutSession()`, `client.closeSession()`
✅ **Mensagens**: `client.sendText(to, text)`
✅ **Grupos**: `client.promoteParticipant(groupId, participantId)`, `client.demoteParticipant(groupId, participantId)`
✅ **Comunidades**: `client.promoteCommunityParticipant(communityId, participantId)`, `client.getCommunityParticipants(communityId)`, `client.demoteCommunityParticipant(communityId, participantId)` (via API)
### 2. Packages Validados (Versões Estáveis)
- `@modelcontextprotocol/sdk`: ^1.0.0 (MCP Protocol SDK)
- `@wppconnect-team/wppconnect`: ^1.37.5 (WPPConnect core)
- `zod`: ^3.23.0 (Validação de schemas)
- `zod-to-json-schema`: ^3.23.0 (Converter Zod → JSON Schema para MCP)
- `typescript`: ^5.6.0
- `@types/node`: ^22.0.0
- `tsx`: ^4.19.0
### 3. Métodos Removidos (Não Existem na Lib)
❌ `createCommunity()` - Comunidades são gerenciadas via WhatsApp Web UI ou API externa
❌ `addSubgroupsCommunity()` - Não existe método direto; gerenciado via UI
---
## PLANO DE PROJETO - MÓDULOS, BLOCOS E TASKS
### **FASE 1: Setup & Scaffolding**
#### Task 1.1: Criar estrutura base do projeto
```bash
mkdir mcp-wppconnect-server && cd mcp-wppconnect-server
npm init -y
```
#### Task 1.2: Instalar dependências
```bash
npm i @modelcontextprotocol/sdk@^1.0.0 @wppconnect-team/wppconnect@^1.37.5 zod@^3.23.0 zod-to-json-schema@^3.23.0
npm i -D typescript@^5.6.0 @types/node@^22.0.0 tsx@^4.19.0
```
#### Task 1.3: Configurar TypeScript
```bash
npx tsc --init --rootDir src --outDir build --esModuleInterop --resolveJsonModule --module NodeNext --moduleResolution NodeNext --target ES2020 --strict
```
#### Task 1.4: Atualizar package.json
```json
{
"name": "mcp-wppconnect-server",
"version": "0.1.0",
"type": "module",
"main": "build/index.js",
"scripts": {
"dev": "tsx src/index.ts",
"build": "tsc",
"start": "node build/index.js",
"lint": "tsc --noEmit"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0",
"@wppconnect-team/wppconnect": "^1.37.5",
"zod": "^3.23.0",
"zod-to-json-schema": "^3.23.0"
},
"devDependencies": {
"@types/node": "^22.0.0",
"tsx": "^4.19.0",
"typescript": "^5.6.0"
}
}
```
#### Task 1.5: Criar estrutura de diretórios
```bash
mkdir -p src/{tools,schemas,utils,types}
```
---
### **FASE 2: Schemas & Validação**
#### Task 2.1: Criar schemas de validação (src/schemas/validations.ts)
- `SessionSchema`: ID da sessão (obrigatório)
- `SendTextSchema`: sessionId, to (jid/phone), text
- `PromoteParticipantSchema`: sessionId, groupId, participantId
- `DemoteParticipantSchema`: sessionId, groupId, participantId
- `GetCommunityParticipantsSchema`: sessionId, communityId
- `PromoteCommunityParticipantSchema`: sessionId, communityId, participantId
- `DemoteCommunityParticipantSchema`: sessionId, communityId, participantId
#### Task 2.2: Criar tipos TypeScript (src/types/index.ts)
- `ToolInput<T>`
- `ToolOutput<T>`
- `SessionConfig`
- `ManagedClient`
---
### **FASE 3: Gerenciamento de Sessão**
#### Task 3.1: Criar Session Manager (src/utils/sessionManager.ts)
- `getOrCreateClient(sessionId)`: Reutiliza ou cria cliente WPPConnect
- `closeSession(sessionId)`: Encerra sessão e limpa memória
- `getAllSessions()`: Lista sessões ativas
- Error handling e logging
#### Task 3.2: Implementar QR Code persistence (src/utils/qrStorage.ts)
- Armazenar QR em memória ou arquivo
- Retornar via `get_qr_snapshot`
- Limpar após login bem-sucedido
#### Task 3.3: Implementar token/session persistence (src/utils/tokenStorage.ts)
- Armazenar tokens em arquivo seguro
- Recuperar na próxima inicialização
- Evitar relogin desnecessário
---
### **FASE 4: Implementação das Tools**
#### Task 4.1: Tools de Sessão (src/tools/sessionTools.ts)
- `initialize_session`: Inicia login e emite QR
- `get_qr_snapshot`: Retorna QR Code atual
- `get_session_status`: Status da sessão
- `close_session`: Encerra sessão
#### Task 4.2: Tools de Mensagem (src/tools/messageTools.ts)
- `send_text`: Envia mensagem de texto
- `send_media`: (Future) Enviar imagem/vídeo/áudio
#### Task 4.3: Tools de Grupo (src/tools/groupTools.ts)
- `promote_group_participant`: Promover admin em grupo
- `demote_group_participant`: Rebaixar admin em grupo
#### Task 4.4: Tools de Comunidade (src/tools/communityTools.ts)
- `get_community_participants`: Listar participantes de comunidade
- `promote_community_participant`: Promover admin em comunidade
- `demote_community_participant`: Rebaixar admin em comunidade
#### Task 4.5: Tools de Utilidade (src/tools/utilityTools.ts)
- `get_contacts`: Listar contatos
- `get_chats`: Listar conversas
---
### **FASE 5: Servidor MCP**
#### Task 5.1: Criar servidor MCP (src/index.ts)
- Instanciar servidor MCP
- Registrar todas as tools
- Converter Zod schemas → JSON Schema via `zod-to-json-schema`
- Implementar validação e tratamento de erros
- Iniciar transporte stdio
#### Task 5.2: Implementar error handling global
- Try-catch em cada tool
- Logging estruturado
- Retorno de erros padronizado
---
### **FASE 6: Integração & Testes**
#### Task 6.1: Testar localmente
```bash
npm run dev
```
#### Task 6.2: Build para produção
```bash
npm run build
npm start
```
#### Task 6.3: Conectar no Claude Desktop
Editar arquivo config do Claude Desktop:
```json
{
"mcpServers": {
"mcp-wppconnect-server": {
"command": "node",
"args": ["path/to/build/index.js"]
}
}
}
```
---
## Próximos Passos Obrigatórios
1. ✅ Validar métodos WPPConnect contra documentação oficial
2. ✅ Implementar Session Manager com error handling
3. ✅ Implementar todas as tools com validação Zod
4. ✅ Converter Zod schemas para JSON Schema
5. ✅ Testar QR Code flow (console → armazenamento)
6. ✅ Testar persistência de token/sessão
7. ✅ Integrar com Claude Desktop
8. ✅ Documentar cada tool com exemplos de uso
---
## Estrutura Final de Arquivos
```
mcp-wppconnect-server/
├── src/
│ ├── tools/
│ │ ├── sessionTools.ts
│ │ ├── messageTools.ts
│ │ ├── groupTools.ts
│ │ ├── communityTools.ts
│ │ └── utilityTools.ts
│ ├── schemas/
│ │ └── validations.ts
│ ├── utils/
│ │ ├── sessionManager.ts
│ │ ├── qrStorage.ts
│ │ └── tokenStorage.ts
│ ├── types/
│ │ └── index.ts
│ └── index.ts (MCP Server)
├── build/ (gerado)
├── package.json
├── tsconfig.json
└── README.md
```