FitSlot MCP Server

# Guia de Contribuição Obrigado por considerar contribuir para o FitSlot MCP Server! Este documento fornece diretrizes para contribuir com o projeto. ## 🌟 Como Contribuir ### Reportando Bugs Se você encontrou um bug, por favor: 1. **Verifique se o bug já foi reportado** nas [Issues](https://github.com/osmarsant/fitslot-mcp/issues) 2. Se não, **crie uma nova issue** com: - Título claro e descritivo - Descrição detalhada do problema - Passos para reproduzir - Comportamento esperado vs. comportamento atual - Versão do Node.js e do sistema operacional - Logs relevantes (se disponíveis) ### Sugerindo Melhorias Para sugerir uma nova funcionalidade: 1. **Verifique se já existe uma issue** para a sugestão 2. **Crie uma nova issue** com: - Título descritivo - Descrição detalhada da funcionalidade - Casos de uso - Exemplos de como seria usado - Possíveis implementações (se tiver ideias) ### Pull Requests 1. **Fork o repositório** e crie uma branch a partir de `main` 2. **Faça suas alterações** seguindo as diretrizes de código 3. **Teste suas alterações** completamente 4. **Commit suas mudanças** com mensagens claras 5. **Push para sua branch** no seu fork 6. **Abra um Pull Request** ## 📝 Diretrizes de Código ### Estilo de Código Este projeto usa TypeScript e segue estas convenções: #### Formatação - Use 2 espaços para indentação - Use aspas simples para strings - Sempre use ponto e vírgula - Máximo de 100 caracteres por linha #### Nomenclatura - **Classes**: PascalCase (ex: `FitSlotAPIService`) - **Interfaces/Types**: PascalCase (ex: `Ticket`, `BioimpedanceData`) - **Funções/Métodos**: camelCase (ex: `createTicket`, `analyzePDF`) - **Variáveis**: camelCase (ex: `ticketId`, `userData`) - **Constantes**: UPPER_SNAKE_CASE (ex: `MAX_RETRIES`, `DEFAULT_TIMEOUT`) - **Arquivos**: kebab-case (ex: `fitslot-api.service.ts`) #### Comentários - Use JSDoc para documentar funções públicas - Comentários devem explicar o "porquê", não o "como" - Mantenha comentários atualizados com o código Exemplo: ```typescript /** * Create a new support ticket * @param request - Ticket creation parameters * @returns Created ticket with generated ID * @throws Error if validation fails or API is unavailable */ async createTicket(request: CreateTicketRequest): Promise<Ticket> { // Implementação } ``` ### Estrutura de Arquivos ``` src/ ├── index.ts # Entry point do servidor MCP ├── services/ # Lógica de negócio │ ├── *.service.ts ├── tools/ # Ferramentas MCP │ ├── *.tools.ts ├── types/ # Definições de tipos │ └── index.ts └── utils/ # Funções utilitárias ├── logger.ts └── validation.ts ``` ### Tratamento de Erros - Use try-catch para operações assíncronas - Sempre faça log de erros - Retorne erros estruturados aos usuários - Não exponha detalhes internos sensíveis Exemplo: ```typescript try { const result = await apiService.createTicket(request); return result; } catch (error) { logger.error('Failed to create ticket', error); throw new Error('Unable to create ticket. Please try again later.'); } ``` ### Validação de Entrada - Valide todas as entradas do usuário - Use as funções de validação existentes em `utils/validation.ts` - Sanitize inputs para prevenir injeções ```typescript validateNotEmpty(args.title, 'Title'); validateEnum(args.priority, TicketPriority, 'Priority'); ``` ### Logging Use o sistema de logging estruturado: ```typescript import { logger } from '../utils/logger.js'; logger.debug('Detailed information', { data }); logger.info('General information', { event }); logger.warn('Warning message', { warning }); logger.error('Error occurred', error); ``` ## 🧪 Testes ### Executando Testes ```bash npm test ``` ### Escrevendo Testes - Teste todas as funcionalidades novas - Mantenha cobertura de código acima de 80% - Use nomes descritivos para testes - Organize testes por funcionalidade Estrutura de teste: ```typescript describe('TicketService', () => { describe('createTicket', () => { it('should create a ticket with valid data', async () => { // Arrange const request = { /* ... */ }; // Act const result = await service.createTicket(request); // Assert expect(result.id).toBeDefined(); expect(result.status).toBe('open'); }); it('should throw error with invalid priority', async () => { // Test implementation }); }); }); ``` ## 📦 Dependências ### Adicionando Novas Dependências 1. Avalie se a dependência é realmente necessária 2. Verifique a licença da dependência 3. Verifique se há vulnerabilidades conhecidas 4. Adicione à seção apropriada no `package.json`: - `dependencies`: Necessárias em produção - `devDependencies`: Apenas para desenvolvimento ```bash # Dependência de produção npm install --save nome-da-dependencia # Dependência de desenvolvimento npm install --save-dev nome-da-dependencia ``` ## 🔄 Processo de Review Quando você submeter um PR, revisores irão verificar: 1. **Funcionalidade**: O código faz o que deveria? 2. **Testes**: Há testes adequados? 3. **Documentação**: Está bem documentado? 4. **Estilo**: Segue as convenções do projeto? 5. **Performance**: Há problemas de performance? 6. **Segurança**: Há vulnerabilidades? ### Checklist do PR - [ ] Código compila sem erros (`npm run build`) - [ ] Testes passam (`npm test`) - [ ] Documentação atualizada - [ ] Changelog atualizado (se aplicável) - [ ] Commits seguem padrão de mensagens - [ ] Branch está atualizada com `main` ## 📋 Mensagens de Commit Use commits semânticos: ``` tipo(escopo): descrição curta Descrição mais longa se necessário. Referências: #123 ``` ### Tipos de Commit - **feat**: Nova funcionalidade - **fix**: Correção de bug - **docs**: Apenas documentação - **style**: Formatação, sem mudança de código - **refactor**: Refatoração sem mudança de funcionalidade - **perf**: Melhorias de performance - **test**: Adição ou correção de testes - **chore**: Manutenção geral Exemplos: ``` feat(tickets): add bulk ticket creation fix(chatbot): correct FAQ search algorithm docs(readme): update installation instructions refactor(pdf): simplify data extraction logic ``` ## 🔒 Segurança - **Nunca** commite credenciais ou chaves API - Use variáveis de ambiente para configurações sensíveis - Valide e sanitize todas as entradas - Mantenha dependências atualizadas - Reporte vulnerabilidades de segurança privadamente ## 📞 Contato - **Issues**: Para bugs e sugestões - **Discussions**: Para perguntas e discussões - **Email**: Para questões de segurança (use issues privadas) ## 📜 Licença Ao contribuir, você concorda que suas contribuições serão licenciadas sob a mesma licença do projeto (ISC). --- **Obrigado por contribuir com o FitSlot MCP Server! 🎉**