rotacloud-mcp-node

RotaCloud API를 Claude 및 기타 MCP 클라이언트에 노출하는 MCP 서버입니다. 36개 리소스에 걸쳐 문서화된 v1 작업 129개 전체를 모두 포함합니다 — 근무(shifts), 출퇴근(attendance), 휴가(leave), 사용자(users), 지점(locations), 역할(roles), 시간표(timesheets) 등을 포함합니다.

도구는 RotaCloud가 공개한 OpenAPI 사양(vendor/openapi.json)에서 생성되므로, 매개변수 이름, 타입, 설명은 문서에서 그대로 가져옵니다.

설치

Claude Desktop 확장으로

rotacloud-mcp-node.mcpb를 다운로드하여 Claude Desktop으로 엽니다. RotaCloud 계정에서 생성할 수 있는 RotaCloud API 키를 입력하라는 메시지가 표시됩니다.

수동 / 개발

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.

이름은 HTTP 메서드가 아니라 API 문서의 각 작업 요약에서 파생됩니다. 이 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, /shifts, /attendance, /availability, /pay_periods 등의 start/end 범위 필터). 이 도구들은 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는 예제의 리터럴 역할 ID를 키로 문서화됨). 따라서 문서화되지 않은 필드를 거부하면 유효한 쓰기가 차단됩니다. 각 쓰기 도구의 설명에는 문서화된 예제 페이로드가 포함됩니다.

리소스

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

범위

이 서버는 https://rotacloud-api-docs.netlify.app/에 게시된 v1 API를 다룹니다. RotaCloud의 공식 Node SDK는 공개 문서에 포함되지 않은 일부 추가 v2 엔드포인트(인보이스, v2 로그북, 사용자 온보딩)를 노출하지만 여기에는 포함되지 않습니다.

재생성

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은 로컬 dotfile을 번들에 포함합니다.

라이선스

MIT