FitSlot MCP Server

# Integração FitSlot x OpenAI Este guia descreve como habilitar as novas integrações com a OpenAI adicionadas ao **FitSlot MCP Server** e como consumi-las a partir do backend `fitslot-api`. O objetivo é entregar respostas inteligentes para o chatbot e análises personalizadas de bioimpedância com o menor custo operacional possível. ## Visão Geral As seguintes funcionalidades passaram a utilizar modelos OpenAI (com fallback local caso a API não esteja configurada): - **Chatbot de suporte**: respostas contextualizadas às dúvidas dos usuários com base nas FAQs e ações sugeridas no aplicativo. - **Análise de PDFs de bioimpedância**: síntese personalizada das medições extraídas do PDF e recomendações práticas. Para reduzir custos, o serviço utiliza o modelo `gpt-4o-mini` por padrão, limitado a saídas curtas e objetivas. É possível ajustar o modelo e os limites de tokens via variáveis de ambiente. ## Configuração de Ambiente Defina as variáveis abaixo tanto no MCP server quanto no backend `fitslot-api` (quando precisar chamar a OpenAI diretamente): | Variável | Obrigatória | Descrição | | --- | --- | --- | | `OPENAI_API_KEY` | Sim | Chave de API obtida no painel da OpenAI. | | `OPENAI_MODEL` | Não (default `gpt-4o-mini`) | Modelo a ser utilizado. Prefira modelos "mini" para menor custo. | | `OPENAI_ORG` | Não | ID de organização (se aplicável). | | `OPENAI_PROJECT` | Não | ID de projeto (se aplicável). | | `OPENAI_TEMPERATURE` | Não | Ajuste da criatividade. Valores baixos (0.2) reduzem variação e tokens. | | `OPENAI_MAX_TOKENS` | Não | Limite máximo de tokens de saída. O padrão é 400. | Exemplo de configuração `.env`: ```bash OPENAI_API_KEY=sk-xxxx OPENAI_MODEL=gpt-4o-mini OPENAI_TEMPERATURE=0.2 OPENAI_MAX_TOKENS=400 ``` ## Como o MCP Server usa a OpenAI No arquivo `src/index.ts`, o servidor instancia `OpenAIService` com base nas variáveis de ambiente e injeta o serviço nos componentes: - `ChatbotService` usa `generateSupportAnswer` para enriquecer as respostas. Sem API key, o comportamento anterior (respostas baseadas em FAQ) é mantido. - `PDFAnalysisService` usa `generateBioimpedanceInsights` para produzir análises e recomendações personalizadas. Sem API key, permanece a lógica heurística pré-existente. ## Consumindo a partir do backend `fitslot-api` O backend pode aproveitar os mesmos serviços utilizando a biblioteca `fitslot-mcp` como dependência (ou replicando a chamada HTTP para o MCP via MCP/LLM). Abaixo, um exemplo em TypeScript de uso direto dos serviços: ```ts import { OpenAIService } from 'fitslot-mcp/dist/services/openai.service.js'; import { ChatbotService } from 'fitslot-mcp/dist/services/chatbot.service.js'; import { PDFAnalysisService } from 'fitslot-mcp/dist/services/pdf-analysis.service.js'; const openAIService = new OpenAIService({ apiKey: process.env.OPENAI_API_KEY, model: process.env.OPENAI_MODEL ?? 'gpt-4o-mini', temperature: Number(process.env.OPENAI_TEMPERATURE ?? 0.2), maxTokens: Number(process.env.OPENAI_MAX_TOKENS ?? 400) }); const chatbotService = new ChatbotService(openAIService); const pdfService = new PDFAnalysisService(openAIService); // 1) Endpoint para suporte export async function postSupportAssistant(req, res) { const { question } = req.body; const response = await chatbotService.getChatbotResponse(question); res.json({ success: true, data: response }); } // 2) Endpoint para análise de bioimpedância export async function postBioimpedanceAnalysis(req, res) { const { base64Pdf } = req.body; const report = await pdfService.analyzeBioimpedancePDFFromBase64(base64Pdf); res.json({ success: true, data: report }); } ``` ### Fluxo sugerido de integração 1. **Controller HTTP** (`fitslot-api`): recebe a requisição do app e delega para os serviços acima. 2. **Serviços de domínio**: utilizam `ChatbotService` ou `PDFAnalysisService`, que automaticamente chamam a OpenAI (se configurada) para enriquecer as respostas. 3. **Retorno para o App**: envie para o cliente o objeto retornado pelo serviço, que já contém mensagens em português e recomendações estruturadas. > Caso o backend prefira consumir o MCP via LLM Client/Protocol, exponha os tools `ask_support` e `analyze_pdf` do `fitslot-mcp`. A configuração da OpenAI no servidor garante que a resposta virá enriquecida com IA, sem ajustes adicionais no cliente MCP. ## Boas práticas para manter o custo baixo - Use modelos "mini" (`gpt-4o-mini`, `o4-mini`) e mantenha `maxTokens` ≤ 400. - Cacheie respostas de FAQs comuns no backend para reduzir chamadas repetidas. - Valide entradas no backend para evitar perguntas vazias ou PDFs inválidos, evitando requisições desnecessárias. - Monitore a taxa de erros e quedas de fallback para identificar problemas de configuração. ## Troubleshooting - **Respostas sem IA**: confirme se `OPENAI_API_KEY` está definido e válido. O log do MCP exibirá um aviso quando a chave estiver ausente. - **Erros de JSON na análise**: o serviço retorna ao fallback heurístico automaticamente; cheque os logs para detalhes. - **Custos elevados**: reduza `OPENAI_MAX_TOKENS`, utilize caching ou degrade o modelo para uma opção ainda mais econômica. Seguindo estas orientações, o backend `fitslot-api` consegue oferecer experiências inteligentes aos usuários mantendo controle sobre custo e confiabilidade.