Gerent365 MCP Server

Servidor MCP (Model Context Protocol) para Gerent365, el SaaS de gestión de restaurantes y negocios (Puerto Rico). Permite que asistentes de IA como Claude controlen toda tu cuenta de Gerent365 con lenguaje natural: empleados, horarios, nómina, propinas, fichaje (kiosko), clientes, productos, mesas, reservaciones, ausencias, asistencia, reportes y estadísticas.

El servidor se autentica automáticamente en https://app.gerent365.com/api (POST /auth/login) y mantiene la sesión mediante cookies durante toda la ejecución. Para las herramientas de kiosko usa kioskCode + pin.

---

Requisitos

• Node.js 18 o superior (probado en Node 22).
• Una cuenta de Gerent365 con rol admin, manager o superadmin para las operaciones de escritura.

---

Instalación

# 1. Clona o copia el proyecto y entra en la carpeta
cd gerent365-mcp

# 2. Instala las dependencias
npm install

# 3. Compila el TypeScript a JavaScript (genera dist/)
npm run build

Scripts disponibles:

Script	Acción
npm run build	Compila src/ a dist/ con tsc.
npm start	Ejecuta el servidor compilado (node dist/index.js).
npm run dev	Compila en modo watch (recompila al guardar).

---

Configuración (variables de entorno)

Copia .env.example a .env y completa tus datos. El servidor también lee las variables directamente del entorno (útil al configurarlo en un cliente MCP).

Variable	Obligatoria	Descripción	Default
GERENT365_EMAIL	Sí*	Email de tu cuenta de Gerent365.	—
GERENT365_PASSWORD	Sí*	Contraseña de tu cuenta.	—
GERENT365_API_URL	No	URL base de la API.	https://app.gerent365.com/api
GERENT365_KIOSK_CODE	No**	Código único de kiosko del negocio.	—
GERENT365_PIN	No**	PIN de fichaje del empleado.	—
GERENT365_MANAGER_CODE	No	Código de manager (autoriza fichajes tardíos).	—

* Obligatorias para las herramientas de dashboard (empleados, nómina, horarios, etc.). ** Obligatorias solo para las herramientas de kiosko/fichaje (o se pueden pasar como parámetros en cada llamada).

El servidor hace auto-login al arrancar. Si faltan GERENT365_EMAIL/GERENT365_PASSWORD, arranca igual pero solo funcionarán las herramientas de kiosko (o deberás usar gerent365_login manualmente).

---

Configuración en Claude Desktop

Edita el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Añade el servidor (usa la ruta absoluta a dist/index.js):

{
  "mcpServers": {
    "gerent365": {
      "command": "node",
      "args": ["/ruta/absoluta/a/gerent365-mcp/dist/index.js"],
      "env": {
        "GERENT365_EMAIL": "admin@tunegocio.com",
        "GERENT365_PASSWORD": "tu_contrasena",
        "GERENT365_API_URL": "https://app.gerent365.com/api",
        "GERENT365_KIOSK_CODE": "KSK-0000",
        "GERENT365_PIN": "1234"
      }
    }
  }
}

Guarda el archivo y reinicia Claude Desktop. Verás las herramientas de Gerent365 disponibles (icono de herramientas 🔨).

---

Configuración en otros clientes MCP

El servidor habla MCP sobre stdio, por lo que funciona con cualquier cliente compatible (Cline, Continue, Zed, LibreChat, etc.). La idea es siempre la misma:

• Comando: node
• Argumentos: ["/ruta/absoluta/a/gerent365-mcp/dist/index.js"]
• Variables de entorno: las de la tabla anterior.

Ejemplo genérico (formato tipo mcp.json):

{
  "servers": {
    "gerent365": {
      "type": "stdio",
      "command": "node",
      "args": ["/ruta/absoluta/a/gerent365-mcp/dist/index.js"],
      "env": {
        "GERENT365_EMAIL": "admin@tunegocio.com",
        "GERENT365_PASSWORD": "tu_contrasena"
      }
    }
  }
}

También puedes probarlo con el MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

---

Herramientas disponibles (53)

Autenticación y perfil

Herramienta	Descripción
gerent365_login	Inicia sesión (email, password).
gerent365_logout	Cierra la sesión.
gerent365_get_profile	Perfil del usuario actual + negocio.

Negocio

Herramienta	Descripción
gerent365_get_business	Ver información del negocio.
gerent365_update_business	Actualizar negocio (nombre, email, teléfono, dirección, zona horaria, ajustes).

Empleados

Herramienta	Descripción
gerent365_list_employees	Listar empleados.
gerent365_get_employee	Ver empleado por ID.
gerent365_create_employee	Crear empleado.
gerent365_update_employee	Actualizar empleado.
gerent365_delete_employee	Eliminar empleado.
gerent365_update_employee_pin	Cambiar PIN de fichaje.

Puestos de trabajo

Herramienta	Descripción
gerent365_list_job_positions	Listar puestos.
gerent365_create_job_position	Crear puesto (tarifa por hora, color).
gerent365_update_job_position	Actualizar puesto.
gerent365_delete_job_position	Eliminar puesto.

Horarios

Herramienta	Descripción
gerent365_get_schedule	Ver horario de una semana.
gerent365_assign_shift	Asignar/actualizar turno.
gerent365_copy_week	Copiar semana de horarios.
gerent365_publish_schedule	Publicar horario de una semana.
gerent365_get_publish_status	Ver estado de publicación.

Nómina

Herramienta	Descripción
gerent365_list_payroll	Listar periodos de nómina.
gerent365_create_payroll_period	Crear periodo.
gerent365_calculate_payroll	Calcular nómina.
gerent365_approve_payroll	Aprobar periodo.
gerent365_pay_payroll	Marcar como pagado.

Propinas

Herramienta	Descripción
gerent365_list_tips	Listar pools de propinas.
gerent365_create_tip_pool	Crear pool de propinas.
gerent365_distribute_tips	Distribuir propinas.

Kiosko / Fichaje

Herramienta	Descripción
gerent365_kiosko_validate	Validar empleado (kioskCode + pin).
gerent365_kiosko_punch	Registrar fichaje (CHECK_IN/OUT, BREAK).
gerent365_kiosko_products	Ver productos desde kiosko.

Clientes

Herramienta	Descripción
gerent365_list_customers	Listar clientes.
gerent365_search_customers	Buscar clientes.
gerent365_create_customer	Crear cliente.
gerent365_update_customer	Actualizar cliente.

Productos y categorías

Herramienta	Descripción
gerent365_list_products	Listar productos.
gerent365_create_product	Crear producto.
gerent365_list_product_categories	Listar categorías.
gerent365_create_product_category	Crear categoría.

Mesas

Herramienta	Descripción
gerent365_list_tables	Listar mesas.
gerent365_create_table	Crear mesa.

Reservaciones

Herramienta	Descripción
gerent365_list_reservations	Listar reservaciones.
gerent365_create_reservation	Crear reservación.
gerent365_update_reservation	Actualizar reservación.

Ausencias

Herramienta	Descripción
gerent365_list_time_off	Listar solicitudes de ausencia.
gerent365_create_time_off	Crear solicitud de ausencia.
gerent365_update_time_off	Aprobar/rechazar solicitud.

Asistencia

Herramienta	Descripción
gerent365_get_attendance	Ver registros de asistencia.
gerent365_get_last_punch	Ver último fichaje de un empleado.

Reportes, dashboard y notificaciones

Herramienta	Descripción
gerent365_report_dashboard	Reporte del dashboard.
gerent365_report_sales	Reporte de ventas.
gerent365_dashboard_stats	Estadísticas del dashboard.
gerent365_get_notifications	Ver notificaciones.

---

Ejemplos de uso en lenguaje natural

Una vez configurado en Claude (o tu cliente MCP), puedes pedir cosas como:

• "Muéstrame todos los empleados de mi restaurante."
• "Crea un empleado llamado María López, mesera, con email maria@bar.com y PIN 4821."
• "¿Cómo va el horario de la semana del 27 de julio? Publícalo cuando esté listo."
• "Asigna a Juan un turno el lunes de 9:00 a 17:00 con descanso de 13:00 a 13:30."
• "Copia el horario de esta semana a la próxima."
• "Crea un periodo de nómina del 1 al 15 de julio incluyendo propinas de tarjeta, calcúlalo y muéstrame el total."
• "Registra un pool de propinas de hoy con $200 en efectivo y $350 en tarjeta, y repártelo entre el equipo por horas trabajadas."
• "Ficha mi entrada en el kiosko." (usa GERENT365_KIOSK_CODE y GERENT365_PIN).
• "Busca al cliente con teléfono 787-555-1234 y márcalo como VIP."
• "Crea una reservación para 4 personas mañana a las 8pm a nombre de Pedro."
• "Dame las estadísticas del dashboard de hoy."

---

Notas técnicas

• Autenticación en dos mundos: las rutas de dashboard usan sesión por cookie (login automático); las de kiosko usan kioskCode + pin.
• Multi-tenant: el businessId se deriva de la sesión; nunca se pasa como parámetro.
• Roles: la mayoría de operaciones de escritura requieren rol admin, manager o superadmin.
• Fechas: usa formato ISO YYYY-MM-DD (y HH:mm para horas). Las comparaciones horarias usan la zona horaria del negocio (default America/Puerto_Rico).
• Overtime: el backend de Gerent365 no calcula horas extra; la nómina es a tiempo simple.
• Los errores de la API se devuelven con un mensaje claro en español, incluyendo el código HTTP.

---

Estructura del proyecto

gerent365-mcp/
├── src/
│   ├── index.ts          # Entry point del servidor MCP
│   ├── auth.ts           # Manejo de sesión (login, cookies)
│   ├── client.ts         # HTTP client con cookie-jar
│   └── tools/
│       ├── types.ts      # Tipos y utilidades compartidas
│       ├── auth.ts       # Autenticación y perfil
│       ├── business.ts   # Negocio
│       ├── employees.ts  # Empleados y puestos
│       ├── schedules.ts  # Horarios
│       ├── payroll.ts    # Nómina
│       ├── tips.ts       # Propinas
│       ├── kiosko.ts     # Kiosko / fichaje
│       ├── customers.ts  # Clientes
│       ├── products.ts   # Productos y categorías
│       ├── tables.ts     # Mesas
│       ├── reservations.ts # Reservaciones
│       ├── timeoff.ts    # Ausencias
│       ├── attendance.ts # Asistencia
│       ├── reports.ts    # Reportes
│       └── dashboard.ts  # Estadísticas y notificaciones
├── package.json
├── tsconfig.json
├── README.md
└── .env.example

Licencia

MIT