FitSlot MCP Server

MCP (Model Context Protocol) server para integração com a API FitSlot, fornecendo funcionalidades de:

• 🎫 Gerenciamento de tickets de suporte
• 🤖 Chatbot com FAQs para suporte aos usuários
• 📊 Análise de documentos PDF de bioimpedância

🚀 Características

Gestão de Tickets

• Criar novos tickets de suporte
• Listar tickets por usuário e status
• Atualizar tickets existentes
• Fechar tickets resolvidos

Suporte via Chatbot

• Busca inteligente em base de FAQs
• Respostas contextualizadas com ações sugeridas
• Categorização de perguntas frequentes
• Suporte em português

Análise de Bioimpedância

• Extração automática de dados de PDFs
• Análise de composição corporal
• Cálculo de IMC e métricas de saúde
• Recomendações personalizadas baseadas nos dados

📋 Requisitos

• Node.js 18+ ou superior
• npm ou yarn

🔧 Instalação

# Clonar o repositório
git clone https://github.com/osmarsant/fitslot-mcp.git
cd fitslot-mcp

# Instalar dependências
npm install

# Compilar o projeto
npm run build

⚙️ Configuração

Configure as variáveis de ambiente criando um arquivo .env na raiz do projeto:

# URL da API FitSlot
FITSLOT_API_URL=https://api.fitslot.com

# Chave de API (opcional)
FITSLOT_API_KEY=sua_chave_api_aqui

# Timeout para requisições (em ms)
FITSLOT_API_TIMEOUT=30000

# Nível de log (DEBUG, INFO, WARN, ERROR)
LOG_LEVEL=INFO

🎯 Uso

Desenvolvimento

npm run dev

Produção

npm start

Como Servidor MCP

Para usar com Claude Desktop ou outras aplicações MCP, adicione ao arquivo de configuração:

{
  "mcpServers": {
    "fitslot": {
      "command": "node",
      "args": ["/caminho/para/fitslot-mcp/dist/index.js"],
      "env": {
        "FITSLOT_API_URL": "https://api.fitslot.com",
        "FITSLOT_API_KEY": "sua_chave_aqui"
      }
    }
  }
}

🛠️ Ferramentas Disponíveis

Tickets

create_ticket

Cria um novo ticket de suporte.

Parâmetros:

• title (string): Título do ticket
• description (string): Descrição detalhada do problema
• priority (enum): Prioridade - low, medium, high, urgent
• userId (string): ID do usuário

list_tickets

Lista todos os tickets de um usuário.

Parâmetros:

• userId (string): ID do usuário
• status (enum, opcional): Filtrar por status - open, in_progress, resolved, closed

get_ticket

Obtém detalhes de um ticket específico.

Parâmetros:

• ticketId (string): ID do ticket

update_ticket

Atualiza um ticket existente.

Parâmetros:

• ticketId (string): ID do ticket
• status (enum, opcional): Novo status
• description (string, opcional): Nova descrição
• priority (enum, opcional): Nova prioridade

close_ticket

Fecha um ticket.

Parâmetros:

• ticketId (string): ID do ticket

Chatbot

ask_support

Faz uma pergunta ao suporte e recebe respostas com FAQs relacionadas.

Parâmetros:

• query (string): Pergunta ou consulta do usuário

search_faqs

Busca FAQs por palavras-chave.

Parâmetros:

• query (string): Termo de busca
• limit (number, opcional): Número máximo de resultados (padrão: 5)

get_faq_categories

Lista todas as categorias de FAQs disponíveis.

get_faqs_by_category

Lista FAQs de uma categoria específica.

Parâmetros:

• category (string): Nome da categoria

get_all_faqs

Retorna todas as FAQs disponíveis.

Análise de PDF

analyze_bioimpedance_pdf

Analisa um arquivo PDF de bioimpedância.

Parâmetros:

• filePath (string): Caminho absoluto para o arquivo PDF

analyze_bioimpedance_pdf_base64

Analisa um PDF de bioimpedância a partir de dados base64.

Parâmetros:

• base64Data (string): Dados do PDF codificados em base64
• patientId (string, opcional): ID do paciente para referência

📁 Estrutura do Projeto

fitslot-mcp/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   ├── services/             # Camada de serviços
│   │   ├── fitslot-api.service.ts
│   │   ├── chatbot.service.ts
│   │   └── pdf-analysis.service.ts
│   ├── tools/                # Ferramentas MCP
│   │   ├── ticket.tools.ts
│   │   ├── chatbot.tools.ts
│   │   └── pdf.tools.ts
│   ├── types/                # Definições de tipos TypeScript
│   │   └── index.ts
│   └── utils/                # Utilitários
│       ├── logger.ts
│       └── validation.ts
├── dist/                     # Código compilado
├── package.json
├── tsconfig.json
└── README.md

🏗️ Arquitetura

O projeto segue as melhores práticas de engenharia de software:

• TypeScript: Tipagem forte e segurança em tempo de compilação
• Arquitetura em camadas: Separação clara entre serviços, ferramentas e utilitários
• Logging estruturado: Sistema de logs com níveis configuráveis
• Validação de entrada: Validação rigorosa de todos os inputs
• Tratamento de erros: Gestão robusta de erros em todas as camadas
• Código limpo: Código bem documentado e fácil de manter

🔒 Segurança

• Validação de todas as entradas do usuário
• Sanitização de dados para prevenir injeções
• Gestão segura de credenciais via variáveis de ambiente
• Tratamento adequado de erros sem expor informações sensíveis

📝 Exemplos de Uso

Criar um Ticket

{
  "tool": "create_ticket",
  "arguments": {
    "title": "Problema no agendamento",
    "description": "Não consigo agendar horário para sexta-feira",
    "priority": "high",
    "userId": "user123"
  }
}

Buscar Suporte

{
  "tool": "ask_support",
  "arguments": {
    "query": "Como faço para cancelar um agendamento?"
  }
}

Analisar PDF

{
  "tool": "analyze_bioimpedance_pdf",
  "arguments": {
    "filePath": "/caminho/para/documento.pdf"
  }
}

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

📄 Licença

ISC

📞 Suporte

Para suporte, abra uma issue no repositório ou entre em contato através dos canais oficiais do FitSlot.