Fresha

Acesse o Fresha Data Connector através do Snowflake.

GitHubExperimente este MCPPatrocinado

Documentação

mcp-fresha

Servidor MCP (Model Context Protocol) para acessar o Fresha Data Connector via Snowflake. Consulte seus dados de negócios do Fresha diretamente por meio de assistentes de IA como o Claude.

Autor: Boris Djordjevic

Início Rápido

npm install -g mcp-fresha

Configuração

Claude Desktop

Adicione ao ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fresha": {
      "command": "mcp-fresha",
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account.snowflakecomputing.com",
        "SNOWFLAKE_USER": "FRESHA_DATA_XXX_XXX",
        "SNOWFLAKE_PASSWORD": "your-password",
        "SNOWFLAKE_DATABASE": "FRESHA_DATA_CONNECTOR",
        "SNOWFLAKE_SCHEMA": "FRESHA_DATA_XXX",
        "SNOWFLAKE_WAREHOUSE": "FRESHA_DATA_XXX"
      }
    }
  }
}

Importante: Se sua senha contiver #, coloque-a entre aspas: "password#123"

Obtenha essas credenciais nas configurações do seu Fresha Data Connector.

Recursos

  • Acesso a Dados em Tempo Real: Conexão direta aos seus dados de negócios do Fresha via Snowflake
  • Consultas Flexíveis: Suporte para intervalos de datas, filtros personalizados, ordenação e paginação
  • Análise Inteligente de Datas: Entradas de datas em linguagem natural como "ontem", "semana passada", "este mês"
  • Descoberta Abrangente de Esquemas: Descoberta automática de todas as tabelas disponíveis e suas estruturas
  • Operações Type-safe: Construído com TypeScript para confiabilidade e facilidade de manutenção
  • Modo Mock: Modo de desenvolvimento com dados de exemplo quando as credenciais do Snowflake não estão disponíveis
  • Registro Estruturado: Logs detalhados com Pino para depuração e monitoramento

Ferramentas Disponíveis

list_fresha_reports

Lista todas as tabelas e visualizações disponíveis no seu banco de dados Fresha.

Exemplo: "Mostre-me todas as tabelas"

get_fresha_report

Obtenha dados de qualquer relatório/tabela Fresha com opções flexíveis de filtragem.

Parâmetros:

  • report_name (obrigatório) - Nome da tabela (ex.: CASH_FLOW, SALES, BOOKINGS)
  • start_date (opcional) - Filtro de data inicial (YYYY-MM-DD)
  • end_date (opcional) - Filtro de data final (YYYY-MM-DD)
  • limit (opcional) - Número máximo de registros a retornar (padrão: 1000)
  • order_by (opcional) - Coluna para ordenação (ex.: "SALE_DATE DESC")
  • filters (opcional) - Filtros adicionais como pares chave-valor

Exemplos:

  • "Obtenha o fluxo de caixa de ontem"
  • "Mostre-me os 10 principais clientes por número de agendamentos"
  • "Obtenha todos os agendamentos desta semana"
  • "Mostre as vendas da localização 123"

Tabelas Disponíveis

Seu banco de dados Fresha inclui:

  • CASH_FLOW - Dados de fluxo de caixa em nível de transação
  • BOOKINGS - Agendamentos e reservas de serviços
  • CLIENTS - Informações e histórico de clientes
  • PAYMENTS - Transações de pagamento
  • SALES - Registros de vendas
  • LOCATIONS - Localizações de negócios
  • TEAM_MEMBERS - Informações da equipe
  • E mais...

Solução de Problemas

Falha na Autenticação

  • Certifique-se de que as credenciais correspondam exatamente às do Fresha Data Connector
  • Verifique caracteres especiais na senha (especialmente #)
  • Remova https:// da URL da conta, se presente

Nenhum Dado Retornado

  • Verifique se você tem os nomes corretos de banco de dados e esquema
  • Confirme se o Fresha Data Connector está ativo (limite diário de 8 horas)

Segurança

Melhores Práticas

  • Variáveis de Ambiente: Todas as credenciais sensíveis são armazenadas como variáveis de ambiente, nunca no código
  • Sem Registro de Credenciais: O servidor mascara automaticamente as credenciais do Snowflake nos logs
  • Acesso Somente Leitura: Projetado para operações somente leitura para evitar modificações acidentais de dados
  • Validação de Entrada: Todas as entradas das ferramentas são validadas usando esquemas Zod para prevenir ataques de injeção
  • Consultas Parametrizadas: Todas as consultas ao banco de dados usam declarações parametrizadas para prevenir injeção de SQL
  • Gerenciamento de Sessão: Cada conexão é gerenciada adequadamente com limpeza automática

Proteção de Dados

  • As credenciais nunca são expostas em mensagens de erro ou logs
  • O modo mock previne acesso acidental a dados de produção durante o desenvolvimento
  • Todas as conexões com o banco de dados são criptografadas usando os protocolos seguros do Snowflake

Desenvolvimento

# Clone and install
git clone https://github.com/199-biotechnologies/mcp-fresha.git
cd mcp-fresha/fresha-mcp-server
npm install

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
npm test

# Development mode with mock data
npm run dev

# Watch mode for development
npm run watch

# Lint and type check
npm run lint
npm run typecheck

Arquitetura

O projeto segue um padrão de arquitetura limpa:

  • Controllers: Lógica de negócio para lidar com consultas de dados e transformações
  • Services: Camada de acesso a dados com gerenciamento de conexão com o Snowflake
  • Tools: Definições de ferramentas MCP que expõem funcionalidades aos assistentes de IA
  • Utils: Utilitários compartilhados para registro, análise de datas e tratamento de erros

Contribuição

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

  • Todo o código passe na verificação de lint (npm run lint)
  • Os tipos TypeScript estejam definidos corretamente
  • Novos recursos incluam tratamento de erros adequado
  • As melhores práticas de segurança sejam seguidas

Licença

MIT