README.md•6.61 kB
# 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
```bash
# 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:
```env
# 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
```bash
npm run dev
```
### Produção
```bash
npm start
```
### Como Servidor MCP
Para usar com Claude Desktop ou outras aplicações MCP, adicione ao arquivo de configuração:
```json
{
"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
```typescript
{
"tool": "create_ticket",
"arguments": {
"title": "Problema no agendamento",
"description": "Não consigo agendar horário para sexta-feira",
"priority": "high",
"userId": "user123"
}
}
```
### Buscar Suporte
```typescript
{
"tool": "ask_support",
"arguments": {
"query": "Como faço para cancelar um agendamento?"
}
}
```
### Analisar PDF
```typescript
{
"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.