rotacloud-mcp-node

RotaCloud API を Claude や他の MCP クライアントに公開する MCP サーバーです。36 のリソースにわたる 129 件のドキュメント化された v1 オペレーション すべてをカバーしています — シフト、勤怠、休暇、ユーザー、ロケーション、ロール、タイムシートなど。

ツールは RotaCloud が公開している OpenAPI 仕様（vendor/openapi.json）から生成されているため、パラメータ名、型、説明はすべてドキュメントから直接取得されています。

インストール

Claude Desktop 拡張機能として

rotacloud-mcp-node.mcpb をダウンロードし、Claude Desktop で開きます。RotaCloud API キーの入力を求められます。API キーは 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。

名前は HTTP メソッドではなく、API ドキュメントの各オペレーションのサマリーから派生しています。この API では両者がしばしば一致しないためです — DELETE /users_clocked_in/{id} はユーザーを退勤させ、POST /swap_requests/{id} はスワップを拒否します。ツール名はオペレーションが実際に行うことを反映しています: users_clocked_in_clock_out、swap_requests_deny_shift_admin。

日付と時刻

RotaCloud は 3 つの形式を混在させており、ツールは API に正確に従います:

• Unix エポック秒 — シフトと勤怠の時刻用（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": [ … ]
}

結果は自動的にはページネーションされません — 各呼び出しは 1 ページを返すため、広い日付範囲でコンテキストがあふれることはありません。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

2 つのオペレーションが同じツール名を生成する場合、ジェネレーターは明確にエラーを出して失敗します。

ビルド

npm run build   # mcpb pack

配布前に、生成された .mcpb の内容を確認してください — mcpb pack はローカルのドットファイルをバンドルに取り込んでしまいます。

ライセンス

MIT