Fresha

Accede al Conector de Datos de Fresha a través de Snowflake.

GitHub

Documentación

mcp-fresha

Servidor MCP (Model Context Protocol) para acceder al Conector de Datos de Fresha a través de Snowflake. Consulta los datos de tu negocio de Fresha directamente mediante asistentes de IA como Claude.

Autor: Boris Djordjevic

Inicio Rápido

npm install -g mcp-fresha

Configuración

Claude Desktop

Añadir a ~/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: Si tu contraseña contiene #, envuélvela entre comillas: "password#123"

Obtén estas credenciales desde la configuración de tu Conector de Datos de Fresha.

Características

  • Acceso a datos en tiempo real: Conexión directa a los datos de tu negocio de Fresha a través de Snowflake
  • Consultas flexibles: Soporte para rangos de fechas, filtros personalizados, ordenamiento y paginación
  • Análisis inteligente de fechas: Entradas de fechas en lenguaje natural como "ayer", "la semana pasada", "este mes"
  • Descubrimiento completo de esquemas: Descubrimiento automático de todas las tablas disponibles y sus estructuras
  • Operaciones seguras de tipos: Construido con TypeScript para fiabilidad y mantenibilidad
  • Modo simulado: Modo de desarrollo con datos de ejemplo cuando no hay credenciales de Snowflake disponibles
  • Registro estructurado: Registro detallado con Pino para depuración y monitoreo

Herramientas Disponibles

list_fresha_reports

Lista todas las tablas y vistas disponibles en tu base de datos de Fresha.

Ejemplo: "Muéstrame todas las tablas"

get_fresha_report

Obtén datos de cualquier informe/tabla de Fresha con opciones de filtrado flexibles.

Parámetros:

  • report_name (obligatorio) - Nombre de la tabla (p. ej., CASH_FLOW, SALES, BOOKINGS)
  • start_date (opcional) - Filtro de fecha de inicio (YYYY-MM-DD)
  • end_date (opcional) - Filtro de fecha de fin (YYYY-MM-DD)
  • limit (opcional) - Máximo de registros a devolver (por defecto: 1000)
  • order_by (opcional) - Columna para ordenar (p. ej., "SALE_DATE DESC")
  • filters (opcional) - Filtros adicionales como pares clave-valor

Ejemplos:

  • "Obtén el flujo de caja de ayer"
  • "Muéstrame los 10 mejores clientes por número de citas"
  • "Obtén todas las reservas de esta semana"
  • "Muestra las ventas de la ubicación 123"

Tablas Disponibles

Tu base de datos de Fresha incluye:

  • CASH_FLOW - Datos de flujo de caja a nivel de transacción
  • BOOKINGS - Reservas de servicios y citas
  • CLIENTS - Información e historial de clientes
  • PAYMENTS - Transacciones de pago
  • SALES - Registros de ventas
  • LOCATIONS - Ubicaciones de negocio
  • TEAM_MEMBERS - Información del personal
  • Y más...

Solución de Problemas

Autenticación Fallida

  • Asegúrate de que las credenciales coincidan exactamente con las del Conector de Datos de Fresha
  • Verifica si hay caracteres especiales en la contraseña (especialmente #)
  • Elimina https:// de la URL de la cuenta si está presente

No Se Devuelven Datos

  • Verifica que tengas los nombres correctos de base de datos y esquema
  • Comprueba que el Conector de Datos de Fresha esté activo (límite diario de 8 horas)

Seguridad

Mejores Prácticas

  • Variables de Entorno: Todas las credenciales sensibles se almacenan como variables de entorno, nunca en el código
  • Sin Registro de Credenciales: El servidor enmascara automáticamente las credenciales de Snowflake en los registros
  • Acceso de Solo Lectura: Diseñado para operaciones de solo lectura para prevenir modificaciones accidentales de datos
  • Validación de Entradas: Todas las entradas de herramientas se validan con esquemas Zod para prevenir ataques de inyección
  • Consultas Parametrizadas: Todas las consultas a la base de datos usan sentencias parametrizadas para prevenir inyección SQL
  • Gestión de Sesiones: Cada conexión se gestiona adecuadamente con limpieza automática

Protección de Datos

  • Las credenciales nunca se exponen en mensajes de error o registros
  • El modo simulado previene el acceso accidental a datos de producción durante el desarrollo
  • Todas las conexiones a la base de datos están cifradas usando los protocolos seguros de Snowflake

Desarrollo

# 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

Arquitectura

El proyecto sigue un patrón de arquitectura limpia:

  • Controladores: Lógica de negocio para manejar consultas y transformaciones de datos
  • Servicios: Capa de acceso a datos con gestión de conexión a Snowflake
  • Herramientas: Definiciones de herramientas MCP que exponen funcionalidad a los asistentes de IA
  • Utilidades: Utilidades compartidas para registro, análisis de fechas y manejo de errores

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, asegúrate de que:

  • Todo el código pase el linting (npm run lint)
  • Los tipos de TypeScript estén definidos correctamente
  • Las nuevas características incluyan manejo de errores apropiado
  • Se sigan las mejores prácticas de seguridad

Licencia

MIT