rotacloud-mcp-node

MCP-сервер, предоставляющий доступ к RotaCloud API для Claude и других MCP-клиентов. Он охватывает все 129 документированных операций v1 по 36 ресурсам — shifts, attendance, leave, users, locations, roles, timesheets и остальные.

Инструменты генерируются из опубликованной спецификации OpenAPI RotaCloud (vendor/openapi.json), поэтому имена параметров, типы и описания берутся прямо из документации.

Установка

Как расширение Claude Desktop

Скачайте rotacloud-mcp-node.mcpb и откройте его в Claude Desktop. Вам будет предложено ввести ваш API-ключ RotaCloud, который можно сгенерировать в вашем аккаунте RotaCloud.

Вручную / для разработки

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

Добавьте его в 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"
      }
    }
  }
}

Конфигурация

По умолчанию запросы выполняются от имени анонимного пользователя с правами администратора. Установка ROTACLOUD_USER_ID заставляет каждый запрос действовать от имени этого пользователя. Инструменты, поведение которых зависит от действующего пользователя — me_*, messages_*, leave_requests_*, swap_requests_* и unavailability_requests_* — также принимают аргумент as_user для переопределения этого поведения при каждом вызове.

Инструменты

Инструменты называются {resource}_{action}, например shifts_list, shifts_create, users_retrieve, leave_requests_approve.

Имена выводятся из сводки каждой операции в документации API, а не из её HTTP-метода, потому что в этом API они часто не совпадают — DELETE /users_clocked_in/{id} отмечает пользователя вышедшим, а POST /swap_requests/{id} отклоняет обмен. Имена инструментов отражают то, что операция фактически делает: users_clocked_in_clock_out, swap_requests_deny_shift_admin.

Даты и время

RotaCloud использует три формата, и инструменты точно следуют API:

• Секунды Unix epoch для времени смен и посещаемости (start_time, in_time, а также фильтры диапазона start/end для /shifts, /attendance, /availability, /pay_periods …). Эти инструменты также принимают строку ISO 8601 и конвертируют её для вас.

• Строки YYYY-MM-DD для отпусков, дневных заметок, TOIL и дат пользователей (start_date, end_date, dob …).

• Строки HH:MM для времени событий журнала и окон доступности.

Пагинация

Конечные точки списков принимают limit и offset. Ответы, которые разбиты на страницы, возвращаются в виде:

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

Результаты не автоматически разбиваются на страницы — каждый вызов возвращает одну страницу, поэтому широкий диапазон дат не может переполнить контекст. Следуйте meta.links.next или увеличивайте offset для перехода по страницам.

Тела запросов

Инструменты записи перечисляют все документированные поля для этой конечной точки, но также принимают неизвестные поля. Опубликованные схемы тел RotaCloud получены из примеров полезных нагрузок и не полностью описывают реальность (например, role_rates документирован с буквальными идентификаторами ролей из примера в качестве ключей), поэтому отклонение недокументированных полей заблокировало бы допустимые записи. Описание каждого инструмента записи включает документированный пример полезной нагрузки.

Ресурсы

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

Область применения

Этот сервер охватывает v1 API, опубликованный на https://rotacloud-api-docs.netlify.app/. Официальный Node SDK RotaCloud предоставляет некоторые дополнительные конечные точки v2 (invoices, v2 logbook, user onboarding), которые не являются частью публичной документации и не включены сюда.

Перегенерация

server/tools.js генерируется и сохраняется в репозитории. Чтобы получить более новую версию API:

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

Генератор громко завершится с ошибкой, если две операции приведут к одному и тому же имени инструмента.

Сборка

npm run build   # mcpb pack

Проверьте содержимое полученного .mcpb перед его распространением — mcpb pack включает локальные dot-файлы в пакет.

Лицензия

MIT