# 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

```bash
# 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`):

```json
{
  "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`):**

```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**:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

---

## Herramientas disponibles (56)

### 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. |
| `gerent365_update_table` | Actualizar mesa (número, capacidad, ubicación, estado, etc.). |
| `gerent365_delete_table` | Eliminar 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. |
| `gerent365_delete_time_off` | Cancelar una solicitud (solo si sigue en estado PENDING). |

### 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.
- **Cobertura de pruebas (2026-08-09):** las 54 herramientas fueron probadas en vivo contra cuentas reales en dos sesiones, incluida la cadena completa de nómina (`create_payroll_period` → `calculate_payroll` → `approve_payroll` → `pay_payroll`), reparto de propinas, publicación de horario y fichaje de kiosko. Ver historial de commits para el detalle de los bugs reales encontrados y corregidos en el proceso.

---

## 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

PolyForm Shield 1.0.0 — uso libre para cualquier propósito, incluido comercial, excepto para crear un producto o servicio que compita con este. Ver [LICENSE](LICENSE).