rotacloud-mcp-node

Ein MCP-Server, der die RotaCloud-API für Claude und andere MCP-Clients bereitstellt. Er deckt alle 129 dokumentierten v1-Operationen über 36 Ressourcen ab – Schichten, Anwesenheit, Abwesenheit, Benutzer, Standorte, Rollen, Stundenzettel und den Rest.

Die Tools werden aus der veröffentlichten OpenAPI-Spezifikation von RotaCloud (vendor/openapi.json) generiert, sodass Parameternamen, Typen und Beschreibungen direkt aus der Dokumentation stammen.

Installation

Als Claude-Desktop-Erweiterung

Laden Sie rotacloud-mcp-node.mcpb herunter und öffnen Sie es mit Claude Desktop. Sie werden nach Ihrem RotaCloud-API-Schlüssel gefragt, den Sie in Ihrem RotaCloud-Konto erstellen können.

Manuell / Entwicklung

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

Fügen Sie es zu claude_desktop_config.json hinzu:

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

Konfiguration

Standardmäßig werden Anfragen als anonymer Benutzer mit Administratorrechten gestellt. Durch Setzen von ROTACLOUD_USER_ID werden alle Anfragen stattdessen als dieser Benutzer ausgeführt. Tools, deren Verhalten vom handelnden Benutzer abhängt – me_*, messages_*, leave_requests_*, swap_requests_* und unavailability_requests_* – akzeptieren außerdem ein as_user-Argument, um dies pro Aufruf zu überschreiben.

Tools

Die Tools sind nach dem Schema {resource}_{action} benannt, z. B. shifts_list, shifts_create, users_retrieve, leave_requests_approve.

Die Namen werden aus der Zusammenfassung jeder Operation in der API-Dokumentation abgeleitet und nicht aus der HTTP-Methode, da diese in dieser API oft nicht übereinstimmen – DELETE /users_clocked_in/{id} stempelt einen Benutzer aus, und POST /swap_requests/{id} lehnt einen Tausch ab. Die Toolnamen spiegeln wider, was die Operation tatsächlich tut: users_clocked_in_clock_out, swap_requests_deny_shift_admin.

Datum und Uhrzeit

RotaCloud mischt drei Formate, und die Tools folgen exakt der API:

• Unix-Epochensekunden für Schicht- und Anwesenheitszeiten (start_time, in_time und die start/end-Bereichsfilter bei /shifts, /attendance, /availability, /pay_periods …). Diese Tools akzeptieren auch einen ISO-8601-String und konvertieren ihn für Sie.

• YYYY-MM-DD-Strings für Abwesenheiten, Tagesnotizen, TOIL und Benutzerdaten (start_date, end_date, dob …).

• HH:MM-Strings für Logbuch-Ereigniszeiten und Verfügbarkeitsfenster.

Paginierung

Listen-Endpunkte akzeptieren limit und offset. Paginierte Antworten werden wie folgt zurückgegeben:

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

Die Ergebnisse werden nicht automatisch paginiert – jeder Aufruf gibt eine Seite zurück, sodass ein großer Datumsbereich den Kontext nicht überfluten kann. Folgen Sie meta.links.next oder erhöhen Sie offset, um zu blättern.

Anforderungskörper

Schreib-Tools listen jedes für den Endpunkt dokumentierte Feld auf, akzeptieren aber auch unbekannte Felder. Die veröffentlichten Body-Schemas von RotaCloud sind aus Beispiel-Payloads abgeleitet und beschreiben die Realität unzureichend (z. B. wird role_rates mit den wörtlichen Rollen-IDs des Beispiels als Schlüsseln dokumentiert), sodass das Zurückweisen nicht dokumentierter Felder gültige Schreibvorgänge blockieren würde. Die Beschreibung jedes Schreib-Tools enthält den dokumentierten Beispiel-Payload.

Ressourcen

• 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)

Umfang

Dieser Server deckt die v1-API ab, wie unter https://rotacloud-api-docs.netlify.app/ veröffentlicht. Das offizielle Node-SDK von RotaCloud stellt einige zusätzliche v2-Endpunkte bereit (Rechnungen, v2-Logbuch, Benutzer-Onboarding), die nicht Teil der öffentlichen Dokumentation sind und hier nicht enthalten sind.

Neu generieren

server/tools.js wird generiert und eingecheckt. Um eine neuere Version der API zu übernehmen:

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

Der Generator bricht mit einer deutlichen Fehlermeldung ab, wenn zwei Operationen denselben Toolnamen erzeugen würden.

Erstellen

npm run build   # mcpb pack

Überprüfen Sie den Inhalt der resultierenden .mcpb-Datei, bevor Sie sie verteilen – mcpb pack übernimmt lokale Dotfiles in das Bundle.

Lizenz

MIT