MCP EVO - Model Context Protocol para Academia EVO

Este projeto implementa um servidor MCP (Model Context Protocol) para integração com a API EVO, permitindo que você use todas as funcionalidades da academia diretamente no n8n ou outros clientes MCP.

🚀 Funcionalidades

Controle de Acesso

• authorize_entry - Autoriza ou nega acesso de usuários à academia
• get_turnstiles - Lista catracas disponíveis

Gestão de Membros

• get_member_profile - Busca perfil de um membro
• get_members - Lista todos os membros ativos
• authenticate_member - Autentica membros com email/senha
• update_member_card - Atualiza número do cartão
• block_unblock_member - Bloqueia/desbloqueia membros

Atividades e Cronograma

• get_activities - Lista atividades disponíveis
• get_activity_schedule - Busca cronograma de atividades
• enroll_member_in_activity - Inscreve membros em atividades
• get_activity_spots - Verifica vagas disponíveis

Vendas e Carrinhos

• get_cart - Busca carrinho por token
• create_cart - Cria novo carrinho
• get_sales - Lista vendas por período
• create_sale - Cria nova venda

Treinos

• get_workouts - Busca treinos de clientes
• link_workout_to_client - Vincula treino ao cliente
• update_workout - Atualiza dados do treino

Utilitários

• health_check - Verifica status da API
• get_configuration - Busca configurações da filial

📋 Pré-requisitos

• Node.js 18+
• npm ou yarn
• Acesso à API EVO com credenciais válidas

🛠️ Instalação

1. Clone o repositório e instale as dependências:

git clone <seu-repositorio>
cd evo-mcp
npm install

2. Configure as variáveis de ambiente:

cp env.example .env

Edite o arquivo .env com suas credenciais:

EVO_API_URL=https://evo-integracao-api.w12app.com.br
EVO_DNS=a2academia
EVO_TOKEN=DA67E8B5-0628-40C2-B586-A20A0462F1E4

3. Compile o projeto:

npm run build

🚀 Como usar

Executar localmente

npm start

Executar em modo desenvolvimento

npm run dev

🔧 Configuração no n8n

1. Adicione a configuração MCP no seu n8n:

{
  "mcpServers": {
    "evo": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/seu/projeto/evo-mcp",
      "env": {
        "EVO_API_URL": "https://evo-integracao-api.w12app.com.br",
        "EVO_DNS": "a2academia",
        "EVO_TOKEN": "DA67E8B5-0628-40C2-B586-A20A0462F1E4"
      }
    }
  }
}

2. Reinicie o n8n

3. Use as ferramentas MCP nos seus workflows:

   • Controle de acesso automático
   • Gestão de membros
   • Agendamento de atividades
   • Relatórios de vendas
   • Gestão de treinos

📖 Exemplos de Uso

Autorizar Entrada de Membro

{
  "tool": "authorize_entry",
  "arguments": {
    "userId": 12345,
    "personType": 1,
    "device": 2,
    "turnstileId": 202,
    "temperature": 36.5,
    "climateId": 1
  }
}

Buscar Perfil de Membro

{
  "tool": "get_member_profile",
  "arguments": {
    "memberId": 12345
  }
}

Listar Atividades

{
  "tool": "get_activities",
  "arguments": {}
}

🔒 Segurança

• Nunca compartilhe seu token EVO
• Use variáveis de ambiente para credenciais
• Mantenha o projeto atualizado
• Monitore logs de acesso

🐛 Troubleshooting

Erro de Conexão

• Verifique se a API EVO está acessível
• Confirme se o DNS e token estão corretos
• Teste com health_check

Erro de Compilação

• Verifique se o Node.js está na versão 18+
• Execute npm install novamente
• Limpe a pasta dist e recompile

Erro no n8n

• Verifique se o caminho do MCP está correto
• Confirme se as variáveis de ambiente estão definidas
• Verifique os logs do n8n

📝 Logs

O MCP registra todas as operações:

• Requisições à API EVO
• Respostas e erros
• Status de conexão
• Operações realizadas

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature
3. Commit suas mudanças
4. Push para a branch
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🆘 Suporte

Para suporte técnico:

• Abra uma issue no GitHub
• Consulte a documentação da API EVO
• Verifique os logs de erro

---

Desenvolvido para integração com a API EVO - Sistema de Gestão para Academias