MCP Filazero

Filazero MCP Server

Servidor MCP (Model Context Protocol) para integração completa com as APIs do sistema Filazero Express

   ](https://nodejs.org/) 

📸 Screenshots

Consulta de Horários Disponíveis *Consulta de horários disponíveis em tempo real no terminal Vida Plena*

Criação de Agendamento *Criação de agendamento com sucesso para atendimento às 15:00*

Status do Ticket *Consulta detalhada do status do ticket com previsão de atendimento*

🌟 Sobre o Projeto

O Filazero MCP Server é uma solução completa para integração do sistema de gerenciamento de filas Filazero Express com assistentes de IA via Model Context Protocol (MCP). Desenvolvido com TypeScript e Node.js, oferece uma experiência fluida para automação de operações de terminais, tickets e feedback.

✨ Por que usar o Filazero MCP Server?

• 🎨 Integração Nativa: Comunicação direta com APIs Filazero via MCP
• ⚡ Alta Performance: Servidor otimizado com TypeScript para máxima velocidade
• 🔧 Configuração Simples: Setup rápido com Claude Desktop ou qualquer cliente MCP
• 🎯 Tools Completos: 9+ ferramentas MCP para gestão completa de filas
• 📊 Produção Ready: Configurado para ambiente de produção Filazero
• 🔒 Seguro: Sistema de reCAPTCHA integrado com bypass inteligente

🚀 Funcionalidades Principais

📋 Gestão de Terminais

• ✅ Busca de Terminal: Acesso rápido por chave de acesso
• ✅ Informações de Serviço: Detalhes completos de serviços disponíveis
• ✅ Template da Empresa: Visual customizado por organização

🎫 Gestão de Tickets

• ✅ Criação de Tickets: Sistema de booking express com validação
• ✅ Consulta de Tickets: Busca detalhada por ID
• ✅ Posição na Fila: Rastreamento em tempo real
• ✅ Previsão de Atendimento: Estimativa inteligente de tempo
• ✅ Check-in: Sistema de smart code para confirmação
• ✅ Cancelamento: Gestão completa do ciclo de vida do ticket
• ✅ Confirmação de Presença: Validação de comparecimento

📊 Feedback e Avaliações

• ✅ Atualização de Feedback: Coleta de avaliações pós-atendimento
• ✅ Integração N8N Ready: Preparado para automações via webhook

🔐 Segurança

• ✅ reCAPTCHA v3: Proteção contra bots e abuso
• ✅ Bypass Inteligente: Sistema automático para ambientes MCP
• ✅ Validação de Dados: Schemas Zod para todas as operações

🛠️ Tecnologias Utilizadas

Core

• Node.js 18+ - Runtime JavaScript moderno
• TypeScript 5 - Tipagem estática forte
• Model Context Protocol SDK - SDK oficial Anthropic

Bibliotecas

• Axios - Cliente HTTP robusto
• Dotenv - Gerenciamento de variáveis de ambiente

DevOps & Tools

• ts-node - Execução TypeScript direta
• Git - Controle de versão

📦 Estrutura do Projeto

MCP-Filazero/
├── src/
│   ├── index.ts                      # Ponto de entrada MCP Server
│   │
│   ├── config/
│   │   ├── environment.ts           # Configuração de ambiente
│   │   └── providers.ts             # IDs dos providers por ambiente
│   │
│   ├── models/
│   │   ├── filazero.types.ts       # Tipos do Filazero API
│   │   └── mcp.types.ts            # Tipos MCP
│   │
│   └── services/
│       ├── api.service.ts          # Cliente HTTP base
│       ├── terminal.service.ts     # Operações de terminal
│       ├── ticket.service.ts       # Operações de ticket
│       ├── feedback.service.ts     # Operações de feedback
│       ├── recaptcha.service.ts    # Serviço reCAPTCHA principal
│       ├── recaptcha-bypass.service.ts    # Bypass inteligente
│       ├── recaptcha-headless.service.ts  # Headless browser
│       ├── config.service.ts       # Configurações globais
│       └── simple-config.service.ts       # Config simplificada
│
├── assets/                          # Imagens e recursos
├── dist/                           # Build compilado
├── mcp-config.json                # Configuração MCP para Claude
├── package.json                   # Dependências e scripts
├── tsconfig.json                  # Configuração TypeScript
└── README.md                      # Esta documentação

⚙️ Instalação e Configuração

Pré-requisitos

• Node.js 18+ instalado
• Claude Desktop ou outro cliente MCP
• Git

1️⃣ Clone o repositório

git clone https://github.com/victorarielima/MCP---Filazero.git
cd MCP---Filazero

2️⃣ Instale as dependências

npm install

3️⃣ Configure as variáveis de ambiente (opcional)

Crie um arquivo .env se precisar customizar:

# Opcional - o servidor usa produção por padrão
FILAZERO_API_URL=https://api.filazero.net/
NODE_ENV=production

4️⃣ Compile o projeto

npm run build

5️⃣ Configure no Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "filazero": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "C:\\CAMINHO_COMPLETO\\MCP---Filazero",
      "env": {
        "NODE_ENV": "production",
        "FILAZERO_API_URL": "https://api.filazero.net/"
      }
    }
  }
}

6️⃣ Reinicie o Claude Desktop

Após salvar a configuração, reinicie o Claude Desktop para carregar o servidor MCP.

🎯 Tools MCP Disponíveis

📍 Terminal Operations

get_terminal

Busca informações de um terminal por chave de acesso.

Input:

{
  "accessKey": "ABC123"
}

Output: Dados completos do terminal, sessões e configurações.

get_service

Obtém informações detalhadas de um serviço específico.

Input:

{
  "pid": 906,
  "locationId": 123,
  "serviceId": 456
}

get_company_template

Retorna o template visual customizado da empresa.

Input:

{
  "providerId": 906
}

🎫 Ticket Operations

create_ticket

Cria um novo ticket via booking express.

Input:

{
  "terminalSchedule": {
    "id": 123,
    "publicAccessKey": "ABC123",
    "sessions": [...]
  },
  "pid": 906,
  "locationId": 123,
  "serviceId": 456,
  "customer": {
    "name": "João Silva",
    "phone": "11999999999",
    "email": "joao@email.com"
  },
  "priority": 0,
  "metadata": []
}

Output: Ticket criado com smart code e detalhes.

get_ticket

Busca um ticket específico por ID.

Input:

{
  "ticketId": "abc-123-def"
}

get_queue_position

Consulta a posição atual na fila.

Input:

{
  "ticketId": "abc-123-def"
}

Output: Posição, tempo estimado e status.

get_ticket_prevision

Obtém previsão detalhada de atendimento.

Input:

{
  "ticketId": "abc-123-def"
}

cancel_ticket

Cancela um ticket existente.

Input:

{
  "ticketId": "abc-123-def"
}

checkin_ticket

Realiza check-in usando smart code.

Input:

{
  "smartCode": "SC-123456"
}

confirm_presence

Confirma a presença do cliente.

Input:

{
  "ticketId": "abc-123-def"
}

📊 Feedback Operations

update_feedback

Atualiza o feedback de um atendimento.

Input:

{
  "ticketId": "abc-123-def",
  "rating": 5,
  "comment": "Excelente atendimento!"
}

🔧 Configuração Avançada

Providers por Ambiente

O servidor suporta múltiplos ambientes:

Produção (padrão)

{
  artesano: 906,
  boticario: 730,
  nike: 769,
  noel: 777
}

Development/Staging

{
  artesano: 460,
  boticario: 358,
  nike: 356,
  noel: 357
}

🔒 Segurança e Boas Práticas

• ✅ reCAPTCHA v3 integrado com bypass automático para MCP
• ✅ Validação de Schemas com TypeScript strong typing
• ✅ Sanitização de Inputs em todas as operações
• ✅ HTTPS Only para comunicação com APIs Filazero
• ✅ Variáveis de Ambiente para credenciais sensíveis
• ✅ Error Handling robusto com mensagens claras

� Performance

• ⚡ Build otimizado com TypeScript compiler
• ⚡ Conexões reutilizáveis com Axios
• ⚡ Timeout configurável (30s padrão)
• ⚡ Retry automático em falhas de rede
• ⚡ Cache inteligente de configurações

🤝 Contribuindo

Para contribuir com o projeto:

1. Faça um fork do repositório
2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -m 'feat: adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Padrão de Commits

Seguimos o Conventional Commits:

• feat: Nova funcionalidade
• fix: Correção de bug
• docs: Documentação
• style: Formatação de código
• refactor: Refatoração
• test: Testes
• chore: Manutenção

📄 Licença

Este projeto está sob a licença MIT - veja o arquivo LICENSE para detalhes.

👥 Equipe

Desenvolvido com ❤️ por @victorarielima

🌐 Links Úteis

• Model Context Protocol
• Claude Desktop
• Filazero Express
• Documentação Completa

Status do Projeto: ✅ Pronto para Produção | 🚀 Claude Ready

](https://github.com/victorarielima/MCP---Filazero)

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "filazero": {
      "command": "node",
      "args": ["dist/mcp-sse-index.js"],
      "cwd": "/caminho/para/mcp-filazero",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

Para Desenvolvimento

{
  "mcpServers": {
    "filazero-dev": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/caminho/para/mcp-filazero",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

🚀 Scripts Disponíveis

MCP (Principal)

npm start                # Executar servidor MCP
npm run dev              # Desenvolvimento com reload
npm run dev:mcp          # Build + servidor MCP

HTTP (Alternativo)

npm run start:http       # Servidor HTTP
npm run dev:http         # Desenvolvimento HTTP

Desenvolvimento

npm run build            # Compilar TypeScript
npm run watch            # Watch mode
npm run lint             # Lint do código
npm run format           # Formatar código

Plataformas

npm run replit           # Deploy Replit
npm run railway          # Deploy Railway  
npm run vercel-build     # Build Vercel

📁 Estrutura do Projeto

mcp-filazero/
├── src/
│   ├── config/              # Configurações por ambiente
│   │   ├── environment.ts   # Config principal
│   │   ├── providers.ts     # Provider IDs
│   │   └── *.ts            # Configs específicas
│   ├── models/             # Tipos TypeScript
│   │   ├── filazero.types.ts
│   │   └── mcp.types.ts
│   ├── services/           # Serviços da aplicação
│   │   ├── api.service.ts
│   │   ├── terminal.service.ts
│   │   ├── ticket.service.ts
│   │   ├── feedback.service.ts
│   │   └── recaptcha*.ts
│   ├── index.ts            # Servidor MCP básico
│   ├── mcp-sse-index.ts    # Servidor MCP SSE (principal)
│   ├── mcp-sse-server.ts   # Implementação MCP SSE
│   ├── http-index.ts       # Servidor HTTP
│   └── http-server.ts      # Implementação HTTP
├── config/                 # Configurações de ambiente
├── scripts/               # Scripts de deploy
├── dist/                  # Código compilado
├── package.json
├── tsconfig.json
└── README.md

🧪 Testando o Servidor

1. Teste Local

npm start

Deve exibir:

🚀 Filazero MCP Server iniciado!
📡 Ambiente: development  
🔗 API URL: https://api.dev.filazero.net/
🛠️ Tools disponíveis: 11
💡 Aguardando comandos MCP...

2. Teste com Claude

Exemplos de comandos:

• "Buscar terminal com chave ABC123"
• "Criar ticket para João Silva no terminal ABC123"
• "Consultar posição do ticket 12345"
• "Cancelar ticket 12345"

🚢 Deploy

Railway

npm run railway

Replit

npm run replit

Vercel

npm run vercel-build

🔐 Segurança e Monitoramento

• ✅ Validação TypeScript: Tipagem forte
• ✅ Error Handling: Tratamento robusto de erros
• ✅ Logging: Logs estruturados para debug
• ✅ Timeouts: Timeout de 30s nas requisições
• ✅ Health Checks: Endpoint de saúde disponível

📜 Licença

MIT License - veja arquivo LICENSE para detalhes.

🎯 Servidor MCP otimizado para integração perfeita com Claude Desktop e APIs Filazero!