{"type": "text"}

rotacloud-mcp-node

Un servidor MCP que expone la API de RotaCloud a Claude y otros clientes MCP. Cubre las 129 operaciones v1 documentadas en 36 recursos: turnos, asistencia, vacaciones, usuarios, ubicaciones, roles, hojas de tiempo y el resto.

Las herramientas se generan a partir de la especificación OpenAPI publicada por RotaCloud (vendor/openapi.json), por lo que los nombres de los parámetros, los tipos y las descripciones provienen directamente de la documentación.

Instalación

Como extensión de Claude Desktop

Descargue rotacloud-mcp-node.mcpb y ábralo con Claude Desktop. Se le pedirá su clave de API de RotaCloud, que puede generar desde su cuenta de RotaCloud.

Manual / desarrollo

npm install
export ROTACLOUD_API_KEY="your-api-key-here"
node server/index.js

Añádalo a claude_desktop_config.json:

{
  "mcpServers": {
    "rotacloud": {
      "command": "node",
      "args": ["/absolute/path/to/rotacloud-mcp-node/server/index.js"],
      "env": {
        "ROTACLOUD_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuración

Por defecto, las solicitudes se realizan como usuario anónimo con permisos administrativos. Al establecer ROTACLOUD_USER_ID, cada solicitud actúa como ese usuario en su lugar. Las herramientas cuyo comportamiento depende del usuario que actúa — me_*, messages_*, leave_requests_*, swap_requests_* y unavailability_requests_* — también aceptan un argumento as_user para sobrescribirlo en cada llamada.

Herramientas

Las herramientas se nombran {resource}_{action}, p. ej., shifts_list, shifts_create, users_retrieve, leave_requests_approve.

Los nombres se derivan del resumen de cada operación en la documentación de la API en lugar de su método HTTP, porque en esta API a menudo no coinciden: DELETE /users_clocked_in/{id} registra la salida de un usuario y POST /swap_requests/{id} deniega un intercambio. Los nombres de las herramientas reflejan lo que realmente hace la operación: users_clocked_in_clock_out, swap_requests_deny_shift_admin.

Fechas y horas

RotaCloud combina tres formatos, y las herramientas siguen la API exactamente:

• Segundos de época Unix para los tiempos de turnos y asistencia (start_time, in_time y los filtros de rango start/end en /shifts, /attendance, /availability, /pay_periods …). Estas herramientas también aceptan una cadena ISO 8601 y la convierten por usted.

• Cadenas YYYY-MM-DD para vacaciones, notas del día, TOIL y fechas de usuario (start_date, end_date, dob …).

• Cadenas HH:MM para los tiempos de eventos del cuaderno de bitácora y las ventanas de disponibilidad.

Paginación

Los endpoints de listado aceptan limit y offset. Las respuestas paginadas se devuelven como:

{
  "meta": { "total_count": 137, "links": { "next": "…", "last": "…" } },
  "data": [ … ]
}

Los resultados no se paginan automáticamente: cada llamada devuelve una página, por lo que un rango de fechas amplio no puede saturar el contexto. Siga meta.links.next o incremente offset para paginar.

Cuerpos de solicitud

Las herramientas de escritura enumeran todos los campos documentados para ese endpoint, pero también aceptan campos desconocidos. Los esquemas de cuerpo publicados por RotaCloud se derivan de cargas de ejemplo y subdescriben la realidad (por ejemplo, role_rates se documenta con los IDs de rol literales del ejemplo como claves), por lo que rechazar campos no documentados bloquearía escrituras válidas. La descripción de cada herramienta de escritura incluye la carga de ejemplo documentada.

Recursos

• accounts (1)

• attendance (5)

• attendance_approved (2)

• availability (2)

• day_notes (5)

• days_off (3)

• days_off_patterns (5)

• documents (6)

• groups (5)

• holiday_allowances (2)

• holiday_allowances_custom (3)

• leave (5)

• leave_embargoes (5)

• leave_requests (6)

• leave_types (1)

• locations (5)

• logbook_categories (5)

• logbook_events (5)

• me (2)

• messages (2)

• pay_periods (3)

• pins (1)

• roles (5)

• settings (1)

• shifts (5)

• shifts_acknowledged (1)

• shifts_published (2)

• swap_requests (5)

• terminals (5)

• terminals_active (3)

• timezones (2)

• toil_accruals (4)

• toil_allowance (1)

• unavailability_requests (6)

• users (5)

• users_clocked_in (5)

Alcance

Este servidor cubre la API v1 publicada en https://rotacloud-api-docs.netlify.app/. El SDK oficial de Node de RotaCloud expone algunos endpoints v2 adicionales (facturas, cuaderno de bitácora v2, incorporación de usuarios) que no forman parte de la documentación pública y no se incluyen aquí.

Regeneración

server/tools.js se genera y se confirma. Para recoger una versión más reciente de la API:

curl -o vendor/openapi.json https://rotacloud-api-docs.netlify.app/openapi.json
npm run generate

El generador falla de forma ruidosa si dos operaciones produjeran el mismo nombre de herramienta.

Compilación

npm run build   # mcpb pack

Compruebe el contenido del .mcpb resultante antes de distribuirlo: mcpb pack barre los archivos de puntos locales al paquete.

Licencia

MIT