skylight-mcp

skylight-mcp

Skylight Calendar 用 MCP サーバーです。カレンダーイベント（読み取り＋書き込み）、共有リスト（読み取り＋書き込み）、家事とごほうび（読み取り＋書き込み）、タスクボックスのアイテム（読み取り＋書き込み）、食事（読み取り＋書き込み）、AI による自動作成（食事プランとアクティビティのアイデア生成機能、および下書きの確認・承認）、メッセージとアルバム（読み取り＋書き込み）、写真・動画のアップロード、フレーム／デバイス／アカウントの設定、カレンダー、メンバー管理（読み取り＋書き込み。プリセットおよびカスタム写真のアバターを含む）に対応する114個のツールを提供します。

すべての API リクエストに skylight-api-version: 2026-05-01 ヘッダーが付与されます（公式モバイルアプリと同じです）。このヘッダーがないと、一部の機能で「API version does not support …」というエラーが発生し、422 が返されます。

MCP プロトコルのサポート

このサーバーは公式 TypeScript SDK v2 を使用し、stdio 経由でステートレスな 2026-07-28 プロトコルリビジョンをサポートします。クライアントは初期化ハンドシェイクなしでツールを検出して呼び出せます。既存のクライアントでは、引き続き 2025-11-25 のハンドシェイクも使用できます。

トランスポートは引き続き stdio です。ホストは認証済み HTTP 経由で公開できます。このパッケージはネットワークリスナーを起動しません。

認証

このサーバーは、ヘッドレスのメールアドレス＋パスワードによる OAuth2 認可コードフローを使用します。SSO、2FA、ブラウザー拡張機能は不要です。すでにトークンをお持ちの場合は SKYLIGHT_REFRESH_TOKEN を設定してください。トークンを取得するためにログインする場合は、SKYLIGHT_EMAIL と SKYLIGHT_PASSWORD を設定してください。

最初のツール呼び出し時に、サーバーは https://app.ourskylight.com に対して次の4つのステップを実行します。

1. GET /auth/session/new — Rails の CSRF トークンとセッション Cookie を取得します。
2. POST /auth/session — メールアドレスとパスワードでログインします（OAuth 認可の前に実行する必要があります）。
3. GET /oauth/authorize — S256 PKCE の code_challenge を送信し（サーバーで必須）、リダイレクトを通じて一度限りの認可コードを受け取ります。
4. POST /oauth/token — 認可コードと対応する code_verifier を交換し、ベアラー access_token と refresh_token を取得します（現在の有効期限は24時間です。クライアントはこの値を仮定せず、返された expires_in を読み取ります）。

OAuth のリダイレクトは認証オリジン内にとどまります。相対リダイレクトは現在の URL を基準に解決されます。設定されたコールバックは、リクエストやセッション Cookie を受け取ることなく認可コードを提供します。予期しない宛先へのリダイレクトは、エラーにリダイレクト URL を含めずに失敗します。

その後、クライアントは有効期限の約60秒前に先行してトークンを更新し、401 が発生した場合も更新します。ボット対策の壁は確認されておらず、このヘッドレスフローは Node から直接動作します。

環境変数が未設定でもクリーンに起動： 認証情報が設定されていなくても、サーバーはエラーなしで起動します。認証は最初のツール呼び出しまで保留されるため、MCP ホストは認証情報を設定する前に、インストール時のツール一覧取得を完了できます。

独自のコードから認証ヘルパーを使用する

このパッケージは Skylight のセッションログインとトークン更新もエクスポートするため、別のプログラムから src/ をコピーせずに認証できます。

import { login, refresh } from 'skylight-mcp/auth';

const tokens = await login({
  authBaseUrl: 'https://app.ourskylight.com',
  email: process.env.SKYLIGHT_EMAIL!,
  password: process.env.SKYLIGHT_PASSWORD!,
});
// Skylight rotates refresh tokens: store the one each call returns.
const next = await refresh({ authBaseUrl: 'https://app.ourskylight.com', refreshToken: tokens.refreshToken });

これは唯一のライブラリエントリーポイントです。パッケージ内のその他すべては MCP サーバーです。ESM 専用で、型宣言が含まれています。

フレームモデル

Skylight のすべてのデータは、フレーム（ファミリーハブデバイス）に紐づいています。初回使用時に、クライアントはアカウント内のフレームを自動検出します。アカウントに複数のフレームがある場合は、使用するフレーム ID を SKYLIGHT_FRAME_ID に設定してください。フレームに紐づくデータを読み取るツールはすべて、デフォルトを上書きするオプションの frameId 引数を受け付けます。

ツール

モジュール	ツール	R/W	説明
frames	skylight_list_frames	R	アカウント上のすべてのフレームを一覧表示
frames	skylight_get_frame	R	指定したフレームの詳細を取得
frames	skylight_list_frame_members	R	フレームに関連付けられたメンバーを一覧表示
frames	skylight_list_devices	R	フレームにリンクされた物理デバイスを一覧表示
frames	skylight_get_plus_access	R	Skylight Plus のサブスクリプション／利用資格の状態を取得
frames	skylight_get_reward_points	R	家族メンバーごとの報酬ポイント残高を取得
frames	skylight_get_household_config	R	フレームの世帯設定を取得
frames	skylight_list_calendars	R	フレームのカレンダーアカウントと有効なカレンダーを一覧表示
frames	skylight_get_event_notification_settings	R	フレームのカレンダーイベント通知設定を取得
frames	skylight_resolve_member	R	家族メンバー名をカテゴリ ID に解決
frames	skylight_get_calendar	R	1 つのカレンダーアカウントを取得
frames	skylight_list_nudges	R	指定した期間のリマインダーを一覧表示
frames	skylight_update_frame	W	フレームの表示／スリープ設定を更新
frames	skylight_rename_frame	W	フレームの名前を変更
frames	skylight_update_profile	W	フレームのプロフィール（名前、誕生日）を更新
frames	skylight_update_household_config	W	世帯設定を更新
frames	skylight_set_reminder_profile	W	全体のリマインダー間隔（interval_weeks）を設定
frames	skylight_add_webcal	W	webcal／ICS カレンダー URL をフレームに登録
frames	skylight_update_calendar	W	接続済みアカウントのどのサブカレンダーを有効にするか設定
frames	skylight_delete_source_calendar	W	接続済みのソースカレンダーを削除（webcal サブスクリプションを含む）
frames	skylight_set_default_calendar	W	新しいイベントのデフォルトのソースカレンダーを設定
frames	skylight_link_apple_calendar	W	Apple／iCloud カレンダーをリンク。アプリ用パスワードは SKYLIGHT_APPLE_APP_PASSWORD から取得し、ツール引数では指定しません（確認が必要）
frames	skylight_categorize_source_calendar	W	ソースカレンダーのイベントを 1 人以上の家族メンバーに割り当て
frames	skylight_create_source_calendar	W	プロバイダーの属性を直接指定してソースカレンダーを作成（上級者向け）
frames	skylight_invite_user	W	メールでユーザーをフレームに招待（確認が必要）
frames	skylight_approve_user	W	保留中のフレームユーザーを承認（確認が必要）
frames	skylight_remove_user	W	フレームからユーザーを削除（確認が必要。プレビューにメンバー名が表示されます）
frames	skylight_delete_category	W	カテゴリ／家族メンバーを削除（任意の reassign_to_category_id は推定されます。確認が必要で、プレビューにメンバー名が表示されます）
frames	skylight_update_family_member	W	家族メンバーのプロフィール（誕生日、食事の好み）を更新。名前はカテゴリラベルであり、skylight_update_category で設定します
frames	skylight_update_category	W	カテゴリを更新（名前／色の変更、またはラベルを家族メンバーのプロフィールに変換（linked_to_profile））
frames	skylight_create_category	W	カテゴリ／家族メンバーを作成（任意の linked_to_profile、avatar_id）
frames	skylight_list_avatars	R	プリセットアバターライブラリ（絵文字／アイコン画像）を一覧表示
frames	skylight_set_member_avatar	W	家族メンバーのアバターをカスタム写真に設定（確認が必要）
frames	skylight_set_device_album	W	デバイスに表示するフォトアルバムを設定（推定）
frames	skylight_rename_device	W	Skylight デバイスの名前を変更
events	skylight_list_events	R	指定した期間のカレンダーイベントを一覧表示
events	skylight_get_event	R	指定したイベントの詳細を取得
events	skylight_create_event	W	新しいカレンダーイベントを作成（任意の category_ids でメンバーを割り当て。invited_emails が設定されている場合は確認が必要で、プレビューにすべての招待先が表示されます）
events	skylight_update_event	W	既存のカレンダーイベントを更新（任意の category_ids でメンバーを割り当て。invited_emails が設定されている場合は確認が必要）
events	skylight_delete_event	W	カレンダーイベントを削除
events	skylight_list_categories	R	フレームのイベントカテゴリを一覧表示
events	skylight_list_source_calendars	R	フレームにリンクされた外部ソースカレンダーを一覧表示
events	skylight_list_recent_invited_emails	R	最近招待したメールアドレスを一覧表示
events	skylight_update_event_notification_settings	W	カレンダーイベントの通知設定を更新
lists	skylight_list_lists	R	フレーム上の共有リストをすべて一覧表示
lists	skylight_get_list_items	R	指定した共有リストの項目を取得
lists	skylight_create_list	W	新しい共有リストを作成（ラベル＋色＋種類）
lists	skylight_update_list	W	リストの名前、色、種類を更新
lists	skylight_delete_list	W	共有リストとその項目を削除（リストに項目がある場合は確認が必要。プレビューに項目が表示されます）
lists	skylight_add_list_item	W	共有リストに項目を追加
lists	skylight_update_list_item	W	リスト項目の名前を変更、チェック状態を切り替え、またはセクションを設定
lists	skylight_delete_list_item	W	共有リストから項目を削除
lists	skylight_delete_list_items	W	指定したリスト項目を一括削除
lists	skylight_move_list_item	W	リスト項目の順序を変更
lists	skylight_clear_list	W	リストの項目をすべて削除（一括削除を 1 回実行。確認が必要で、プレビューに項目が表示されます）
lists	skylight_set_list_item_section	W	リスト項目を名前付きセクションに移動（またはセクションを解除）
chores	skylight_list_chores	R	指定した期間の家事を一覧表示
chores	skylight_search_chores	R	家事を検索（未スケジュール／テンプレートの家事を含む）
chores	skylight_create_chore	W	新しい家事を作成（概要＋カテゴリ）
chores	skylight_create_recurring_chore	W	繰り返しの家事またはルーティンを作成（RRULE）
chores	skylight_complete_chore	W	家事を完了済みにする
chores	skylight_uncomplete_chore	W	家事を再開（完了を取り消し）
chores	skylight_update_chore	W	家事を更新（繰り返しと apply_to に対応）
chores	skylight_complete_chore_instance	W	繰り返しの家事の特定の回を完了済みにする
chores	skylight_delete_chore	W	家事を削除（apply_to で特定の回またはシリーズ全体を指定）
chores	skylight_list_rewards	R	フレームに設定された報酬を一覧表示
rewards	skylight_get_reward	R	1 つの報酬を取得
rewards	skylight_create_reward	W	報酬を作成（名前＋説明＋point_value＋respawn_on_redemption＋category_ids）
rewards	skylight_update_reward	W	報酬を更新
rewards	skylight_delete_reward	W	報酬を削除
rewards	skylight_redeem_reward	W	報酬を交換
rewards	skylight_unredeem_reward	W	報酬の交換を取り消す
rewards	skylight_add_reward_points	W	メンバーに報酬ポイントを付与または減算
meals	skylight_list_meals	R	指定した期間の予定された食事を一覧表示（date_min と date_max の両方が必須）
meals	skylight_list_recipes	R	フレームの食事レシピを一覧表示
meals	skylight_list_meal_categories	R	フレームの食事カテゴリを一覧表示
meals	skylight_get_recipe	R	1 つの食事レシピを取得
meals	skylight_create_recipe	W	食事レシピを作成（meal_category_id＋summary）
meals	skylight_update_recipe	W	食事レシピを更新
meals	skylight_delete_recipe	W	食事レシピを削除
meals	skylight_add_recipe_to_grocery_list	W	レシピの材料を買い物リストに追加
meals	skylight_plan_meal	W	日付を指定して食事を予定（繰り返し、レシピのリンク、買い物リストへの追加も可能）
meals	skylight_update_meal	W	選択した繰り返し範囲で予定された食事を更新（名前、レシピ、時間枠、メモ、日付、繰り返しルール）
meals	skylight_delete_meal	W	予定された食事を削除（1 回分、今回以降、またはシリーズ全体。確認が必要）
messages	skylight_list_messages	R	フレームに投稿されたメッセージを一覧表示（ページ分けされたフィードを最大 20 ページまで読み込み）
messages	skylight_list_albums	R	フレームのフォトアルバムを一覧表示
messages	skylight_get_message	R	フレームメッセージを 1 件取得
messages	skylight_create_album	W	フォトアルバムを作成
messages	skylight_update_album	W	フォトアルバムを更新（名前の変更、スライドショーで非表示にする）
messages	skylight_delete_album	W	フォトアルバムを削除
messages	skylight_add_to_album	W	メッセージ／写真をアルバムに追加
messages	skylight_remove_from_album	W	アルバムからメッセージ／写真を削除
messages	skylight_copy_messages_to_frames	W	アカウント上の他のフレームにメッセージ／写真をコピー（推定）
messages	skylight_add_message_comment	W	フレームのメッセージ／写真にコメント
messages	skylight_set_message_caption	W	メッセージ／写真のキャプションを設定
messages	skylight_like_message	W	フレームのメッセージ／写真に「いいね」する
messages	skylight_unlike_message	W	メッセージ／写真の「いいね」を取り消す
messages	skylight_delete_message	W	フレームのメッセージ／写真を削除
messages	skylight_delete_messages	W	フレームからメッセージ／写真を一括削除（確認が必要。プレビューには各 ID とキャプションが表示されます）
tasks	skylight_list_tasks	R	タスクボックスの項目を一覧表示
tasks	skylight_create_task	W	タスクボックスの項目を作成
tasks	skylight_update_task	W	タスクボックスの項目を更新
tasks	skylight_delete_task	W	タスクボックスの項目を削除
ai	skylight_generate_meal_plan	W	指定した日付の AI 食事プランを生成（食事の下書きを作成 — 非同期）
ai	skylight_generate_activity_ideas	W	場所と期間を指定して AI アクティビティ／イベントのアイデアを生成（イベントの下書きを作成 — 非同期）
ai	skylight_get_auto_creation_intent	R	AI 自動作成インテントを取得（ステータス＋下書きの結果）
ai	skylight_list_auto_creation_drafts	R	AI インテントが作成したイベントを一覧表示（承認前に確認）
ai	skylight_list_auto_creation_intents	R	フレーム上の AI 自動作成インテントをすべて一覧表示
ai	skylight_list_auto_creation_items	R	AI インテントが作成した下書き項目をすべて一覧表示（食事、アクティビティ、リスト項目）
ai	skylight_approve_auto_creation	W	AI が下書きしたイベントを承認し、実際のカレンダーイベントにする
ai	skylight_undo_auto_creation	W	AI 自動作成インテントとその下書きを取り消し／破棄
photos	skylight_upload_photo	W	ローカルファイルからフレームに写真／動画をアップロード（確認が必要）
photos	skylight_import_events_from_photo	W	Skylight の AI を使ってチラシ／招待状の写真からカレンダーイベントをインポート（可能な範囲で実行。確認が必要）
health	skylight_healthcheck	R	コネクターが動作しているかを報告：解決された認証情報、Skylight がそれを受け入れたかどうか、修正が必要な項目

設定

必須 — 次のいずれか一つ

すでにお持ちのリフレッシュトークン（推奨：スコープを限定でき、失効可能で、レート制限のあるログインエンドポイントにアクセスしません）：

SKYLIGHT_REFRESH_TOKEN=your-refresh-token

またはログイン情報の組み合わせ。こちらを使うとリフレッシュトークンが発行されます：

[email protected]
SKYLIGHT_PASSWORD=your-password

両方を設定することもできます。最も堅牢な設定です。まずトークンが使われ、期限切れの場合はログインによって静かに再発行されます。トークンのみの場合、期限切れのトークンは期限切れとして報告されます。サーバーは未設定だと偽ることなく、その旨を明確に伝えます。

指定したリフレッシュトークンは一度しか使用できません。 Skylight は使用のたびにリフレッシュトークンをローテーションするため、サーバーは初回起動時に SKYLIGHT_REFRESH_TOKEN を使い切り、ローテーション後のトークンで動作を続けます。このトークンは トークンキャッシュ にのみ保存されます。トークンのみを使う場合は、キャッシュを有効にして書き込み可能にし、同じトークンを複数のホストで共有しないでください。環境変数のトークンがすでに使用済みの状態で起動すると、ログイン情報の組み合わせがない限り復旧できません。

任意

環境変数	デフォルト	用途
SKYLIGHT_FRAME_ID	自動検出	アカウントに複数のフレームがある場合に、特定のフレームを指定します
SKYLIGHT_NAME	(なし)	起動ログで使用するわかりやすいラベル
SKYLIGHT_BASE_URL	https://app.ourskylight.com/api	API のベース URL を上書きします
SKYLIGHT_APPLE_APP_PASSWORD	(なし)	skylight_link_apple_calendar が Skylight に送信する、アプリ固有のパスワード（appleid.apple.com から取得）。設計上、環境変数でのみ指定します。ツールの引数にはならないため、モデル、トランスクリプト、ホストのツール呼び出しログを経由することはありません
SKYLIGHT_APPLE_ID	(なし)	skylight_link_apple_calendar 用の Apple ID メールアドレス。ツールの email 引数を指定すると、こちらの値が上書きされます
SKYLIGHT_UPLOAD_DIR	~/Pictures と ~/Downloads（ホステッド環境では $MCP_DATA_DIR/uploads のみ）	skylight_upload_photo、skylight_import_events_from_photo、skylight_set_member_avatar でアップロード元として使用できるディレクトリ（複数指定する場合は : 区切り、Windows では ; 区切り。~ を使用できます）。それ以外のパスは確認プレビューの前に拒否され、確認後の読み取り時にも、ファイルを開く際に再確認されます。常にディレクトリ内に限定されます。未設定の場合はデフォルトのディレクトリが使用され、「どこでも」にはなりません（ファイルの種類、隠しファイル、シンボリックリンク、サイズ、コンテンツのチェックも常に適用されます）

.env はパスワードファイルとして扱ってください。Git では無視されますが、コミットしないでください。

確認

ローカルの写真やアバターのアップロード、ユーザーの招待・承認・削除、家族メンバーの削除、Apple カレンダーの連携、フレームの一般公開、invited_emails を指定したイベントの作成・更新（Skylight は各メールアドレスにメールを送信し、プレビューには宛先が表示されます）、一括削除（skylight_delete_messages、skylight_clear_list、空ではないリストに対する skylight_delete_list。プレビューには削除対象のすべての項目が表示されます）、および apply_to が指定された1回の発生範囲を超える食事や家事の編集・削除を行う場合は、処理の実行前に確認が求められます。確認プロンプトを表示できるクライアント（Claude Code）では、MCP_CONFIRM_ELICITATION=off でない限り、確認プロンプトが表示されます。それ以外の環境では、最初の呼び出しでは変更は行われず、送信される内容の正確なプレビューと confirmToken が返されます。そのトークンと同じ引数を指定して再度呼び出した場合に限り、処理が1回実行されます。

変数	デフォルト
MCP_CONFIRM_MODE	ask-user	確認プロンプトを表示できないクライアント（claude.ai、Claude Desktop）で書き込みを行う際の動作です。ask-user：2段階で処理します。最初の呼び出しでは何も行われず、プレビューとトークンが返されます。モデルは、トークンを使って再度呼び出す前に、チャットでユーザーの承認を得る必要があります。auto：同じく2段階で処理しますが、モデルはプレビューを確認した後、自身の判断でトークンを使用できます。refuse：そのようなクライアントでは書き込みを拒否します。確認プロンプトを表示できるクライアント（Claude Code）には、MCP_CONFIRM_ELICITATION=off でない限り、常に実際の確認プロンプトが表示されます。認識できない値は refuse として扱われます。
MCP_CONFIRM_ELICITATION	on	off にすると確認プロンプトは表示されず、すべてのクライアントで MCP_CONFIRM_MODE に基づく動作になります。確認プロンプトに対応していると称しながら、実際には表示しないクライアント（opencode 2.0.x では書き込みがハングします）に設定してください。それ以外の値では on のままとなり、stderr に警告が出力されます。
MCP_CONFIRM_TTL_SECONDS	600	トークンの有効期間です。
MCP_CONFIRM_SECRET	プロセスごとにランダム	署名キーです。サーバーの再起動後もトークンを有効にする必要がある場合にのみ設定してください。

トークンキャッシュ

初回ログイン後、OAuth トークンのペアは $MCP_DATA_DIR/.skylight-mcp/tokens.json にキャッシュされます （$MCP_DATA_DIR が設定されていない場合は $HOME が使用されます）。ファイルは 0600 の権限で書き込まれます。次回の起動時には4段階のログインをやり直さず、キャッシュが再利用されます。これは、Skylight のログインエンドポイントにレート制限があり、ホスト型サーバーはゼロまでスケールすると頻繁にコールドスタートするため、重要です。

書き込まれるのはトークンのみで、メールアドレスとパスワードは環境内にとどまります。期限切れのキャッシュ済みトークンは、再ログインではなくリフレッシュされます。また、サーバーが拒否したリフレッシュトークンは新たなログインに切り替わるため、古いファイルによってアクセスできなくなることはありません。

キャッシュは、そのトークンを発行した認証情報（パスワードのペア、または指定された SKYLIGHT_REFRESH_TOKEN）に紐づきます。認証情報をローテーションするか、サーバーの接続先を別のアカウントに変更すると、キャッシュ済みトークンは破棄され、使い続けられることはありません。保存されるのはソルト付きのダイジェストのみで、メールアドレス、パスワード、指定されたトークンがファイルに保存されることはありません。

キャッシュを無効にして毎回起動時にログインするには SKYLIGHT_TOKEN_CACHE=false を設定します。キャッシュの保存先を指定するには SKYLIGHT_TOKEN_FILE を設定します。

書き込みに失敗した場合（データディレクトリが読み取り専用、または容量がいっぱいの場合）、サーバーは stderr にログを出力し、メモリー内のトークンを使って処理を続けます。その場合、影響を受けるのは次回の起動時だけです。ログイン用の認証情報ペアを使っている場合、その際に必要なのは1回のログインです。SKYLIGHT_REFRESH_TOKEN のみを使用している場合は、アクセスできなくなるおそれがあります。Skylight はこのトークンを初回使用時にローテーションし、ローテーション後のトークンが保存されないためです。そのため、トークンのみを使用する環境ではトークンを使い切らないようにします。ログイン用の認証情報ペアなしで SKYLIGHT_TOKEN_CACHE=false を設定すると設定エラーになり、サーバーは最初のリフレッシュ前にキャッシュへの書き込みが可能か確認します。書き込みできない場合は、トークンを消費せずに呼び出しを失敗させます。この確認後に書き込みに失敗した場合は、stderr に明確なエラーが出力されます。

ローカル開発

npm install
npm run build
npm test
npm run dev   # requires .env with credentials

テスト：vitest を使用し、行・分岐・関数・文のカバレッジ100％を必須としています。すべてのテストはモックを使用しており、CI でネットワーク呼び出しは行いません。

AI（Claude）が開発・保守しています。ご自身の判断でご利用ください。