Skylight MCP server

Pebble Index リングが音声で Skylight のファミリーカレンダーにイベントを追加できるようにします。Pebble のクラウドエージェントが MCP クライアントとなり、このサーバーが Skylight の非公式 API に対する HTTP 処理を行います。Pebble が Skylight と直接通信することはなく、Skylight があなたの Pebble アカウントを見ることもありません。

公開されているツールは create_event のみです（書き込み専用 — Pebble がカレンダーを読み戻す必要はなく、list_events を省くことでツールの用途が明確になります）。既定の家族メンバーのプロフィールを自動タグ付けでき、「me」/「myself」をその人として解釈し、名前で他のメンバーも指定できます。

トランスポート: Streamable HTTP。認証: Authorization ヘッダー内の静的ベアラートークン（Pebble はカスタム MCP サーバー向けの OAuth ログインフローをサポートしておらず、固定ヘッダーのみです）。

これは他の人の Pebble + Skylight でも再利用できますか？

はい — コード内の何も特定の個人に結びついていません。アカウント固有の値（Skylight へのログイン情報、フレーム ID、タイムゾーン、既定の家族メンバー、ベアラートークン）はすべて環境変数から取得され、家族メンバー名はハードコードではなく、あなたの Skylight カテゴリに対してライブで解決されます。独自の Skylight アカウント、Pebble Index、そして小さな Python HTTP サービスをホストできる場所があれば、誰でも自分のコピーを実行できます。下の デプロイ を参照してください — 手作業でのコード編集ではなく、いくつかの CLI コマンドで完了します。

Related MCP server: Google Calendar AutoAuth MCP Server

環境変数

ローカルセットアップ

python3 -m venv .venv && source .venv/bin/activate   # needs Python 3.10+
pip install -r requirements.txt

cp .env.example .env   # then fill in real values
export $(grep -v '^#' .env | xargs)   # or use your own env loader
export MCP_BEARER_TOKEN=$(openssl rand -hex 32)

python skylight_mcp_server.py

サーバーは http://0.0.0.0:8000（設定されていれば $PORT）で待ち受け、MCP エンドポイントは /mcp、ヘルスチェックは /healthz（認証不要）です。

MCP Inspector でのテスト

npx @modelcontextprotocol/inspector

Inspector UI では:

1. トランスポート: Streamable HTTP

2. URL: http://localhost:8000/mcp

3. Authentication の下で、ヘッダー Authorization: Bearer <your MCP_BEARER_TOKEN> を追加します。

4. 接続してから、create_event をテスト用のタイトルで呼び出し、Skylight アプリの正しいプロフィールに登録されたことを確認します。

Railway へのデプロイ

オプション A: deploy.sh ヘルパー

export SKYLIGHT_EMAIL=you@example.com
export SKYLIGHT_PASSWORD=...
export SKYLIGHT_FRAME_ID=1234567
export MCP_BEARER_TOKEN=$(openssl rand -hex 32)
# optional:
export SKYLIGHT_TIMEZONE=America/Chicago
export SKYLIGHT_DEFAULT_MEMBER=YourName

./deploy.sh

このスクリプトは、Railway CLI がなければインストールし、ログインを促し（ブラウザ OAuth — この部分はスクリプト化できません）、初回実行時にプロジェクトを作成し、すべての環境変数を設定してデプロイし、公開 URL を表示します。skylight_mcp_server.py を編集して新しいビルドをプッシュする際は、いつでも再実行できます。プロジェクトのリンクはリポジトリ内ではなく、このディレクトリをキーとして ~/.railway/config.json に保存されるため、Railway 固有のものが git に入ることはありません。

オプション B: 手動で行う

railway login                                  # browser OAuth
railway init --name skylight-mcp               # first time only
railway variable set SKYLIGHT_EMAIL=you@example.com --service skylight-mcp --skip-deploys
railway variable set SKYLIGHT_PASSWORD=... --service skylight-mcp --skip-deploys
railway variable set SKYLIGHT_FRAME_ID=1234567 --service skylight-mcp --skip-deploys
railway variable set MCP_BEARER_TOKEN=$(openssl rand -hex 32) --service skylight-mcp
railway up -c -y --service skylight-mcp        # builds the Dockerfile, deploys
railway domain --service skylight-mcp          # public HTTPS URL, real cert

後で再デプロイする場合（コード変更後の自分でも、すでに一度セットアップを実行している他の誰でも）は、次のコマンドだけです:

railway up -c -y --service skylight-mcp

再デプロイの手順はこれだけです — このリポジトリに既にある Dockerfile 以外の設定ファイルも、CI パイプラインも不要です。railway logs --service skylight-mcp でライブログを追跡できます。create_event の引数はすべての呼び出しでログに記録されるため、これは便利です（トラブルシューティング を参照）。

Pebble の MCP クライアント設定では、セットアップ時に発行されたベアラートークンを使って https://<your-railway-domain>/mcp を指定してください。

Pebble アプリの設定

Pebble アプリの MCP サーバー設定で:

• Name: 任意ですが、スペースや特殊文字は使用不可 — トラブルシューティング を参照してください。SkylightCalendar または skylight-calendar はどちらでも動作します。

• URL: https://<your-railway-domain>/mcp

• Transport: Streamable（ドロップダウンは文字通り "SSE/Streamable" と表示されます — SSE ではなく Streamable を選択してください）

• Authorization: Bearer <your MCP_BEARER_TOKEN> — Bearer プレフィックスを含む完全な文字列

カスタム MCP ツールは、Pebble の ダブルクリック 録音モードでのみ実行されます（シングルクリックは Pebble 自身の組み込みアクションを使用します）。このサーバーが、ダブルクリックで使用するサンドボックスグループに割り当てられていることを確認してください。

家族メンバーのタグ付けの仕組み

家族メンバーはこのサーバーでは一切設定されません。create_event は実際の Skylight アカウントに対して GET /frames/{id}/categories を呼び出し（プロセスごとにメモリにキャッシュされます）、who 引数をそれらのラベルに大文字小文字を区別せず照合します。「me」/「myself」/「i」は SKYLIGHT_DEFAULT_MEMBER に解決されます。完全一致が失敗した場合は、同じラベルに対するファジー一致（difflib）にフォールバックします。Pebble の音声認識はあまり一般的でない名前をゆがめることがあるためです（例: "Metree" や "May Tree" はどちらも "Maitree" に解決されます — ライブで検証済み）。それでも一致しない名前はイベントをブロックせず、プロフィールタグなしで作成され、確認メッセージにもその旨が表示されるため、聞き間違いが黙って誤った結果になる代わりに可視化されます。

試すべきフレーズ例

それぞれがツールの異なる部分をテストします。フレーズを1つ話したら（リングをダブルクリック）、Skylight で日付/時刻、終日 vs. 時刻指定、どのプロフィールにタグが付いたかを確認してください:

• "Add a dentist appointment tomorrow at 2pm." 時刻指定イベント。デフォルトで SKYLIGHT_DEFAULT_MEMBER のプロフィールにタグ付けされ、場所はありません。

• "Block off next Monday as a vacation day." 時刻を話さないため、終日 イベントとして登録されます（日付のみから自動検出されるため、「all day」と言う必要はありません）。

• "Add a trip to Chicago from the 2nd to the 3rd of September." 複数日にわたる終日イベント — 両日を含む期間として登録されます。

• "Add Maitree's haircut next Tuesday at 10am." 明示的な who — デフォルトではなくその人のプロフィールにタグ付けされます。

• "Add family movie night Friday at 7pm for Maitree and me." 複数人へのタグ付け — 両方のプロフィールにタグ付けされます。

• "Add a dentist appointment at Dr. Smith's office next Wednesday at 3pm." location フィールドが取得されることをテストします。

検証済みと想定の比較

Skylight API は非公式で、リバースエンジニアリングされたものです。このサーバーの認証フローとペイロードの構造は、2026-08-26/27 に実アカウントに対してライブテスト済み です（正確なログイン手順については skylight_mcp_server.py のモジュール docstring を参照してください）。2025年12月の OpenAPI キャプチャから得た初期の想定に反した注目すべき発見は以下のとおりです:

• 古い POST /api/sessions（メール/パスワード → Basic 認証）ログインは廃止されました。現在は 401 "This version of Skylight is no longer supported." を返します。ライブのフローは 4 ステップの OAuth2 認可コード交換です（このフローが成功するのに PKCE は不要ですが、PKCE バリアントも世の中に存在します）。

• すべての API 呼び出しで skylight-api-version: 2026-05-01 が必要です。

• GET .../calendar_events の date_max は排他的な上限です。

• 終日イベントの ends_at も排他的です — 1日だけの終日イベントでは、ends_at を翌日の午前0時に設定する必要があります（または同等に、starts_at と同じ値でも機能します）。N日間のイベントでは、ends_at を最後の含まれる日の翌日まで延長する必要があります。create_event はこの延長を内部で処理するため、呼び出し側にとって end 引数は引き続き両端を含みます。

• 家族メンバーは、作成ペイロードの category_ids（配列）を介してタグ付けされます。カテゴリ ID は GET .../categories から取得され、プロセスごとにキャッシュされます。

Skylight が再び API を変更した場合、最も壊れやすいのはこれらの箇所です: _login()（OAuth のステップ）と create_event 内の calendar_events ペイロードの形です。

トラブルシューティング

Pebble が "invalid tool call, action failed" と表示し、カレンダーに何も登録されない。 まず railway logs --service skylight-mcp を確認してください。create_event の呼び出しは毎回その生の引数をログに記録し、Skylight API の失敗も捕捉されてログに記録されます。このプロジェクトがすでに遭遇した2つの問題があります:

• Pebble アプリの設定で MCP サーバー名にスペースまたは特殊文字が含まれている。 Pebble フォーラム で確認済み: サーバーの Name フィールドにスペースがあると、エージェントが誤った複合ツール名を構築し、呼び出しはエラーもなくサーバーに到達しません（ログには ListToolsRequest が見えますが CallToolRequest はありません）。英数字とハイフンのみに変更してください。

• オプションのツール引数が nullable（str | None）として型指定されている。 一部の厳格な関数呼び出しバリデーターは、リクエストを送信する前に anyOf: [string, null] を含む JSON スキーマを拒否します。このサーバーでは、それを避けるために代わりにプレーンな str = ""（空文字列 = 「未指定」）を使用しています。

日付/時刻を解析できなかった。 create_event はこれを捕捉し、クラッシュする代わりに、解析できなかった内容を正確に示す説明的なエラー文字列を返します（Pebble がツールの結果を表示する場所ならどこでも表示されます）。

イベントが間違った時刻（例: 午前2時）に登録された。 ほぼ確実に、ナイーブ時刻と UTC の混同です。create_event のナイーブ時刻の処理は常に SKYLIGHT_TIMEZONE を前提とし、UTC は使用しません — この問題が発生する場合は、Pebble が誤って UTC 時刻をそのまま送信していないか確認してください（ログに記録された生の start 引数を確認）。

ベアラーチェックの検証

# No token -> 401
curl -i https://<your-railway-domain>/healthz    # should be 200, no auth needed
curl -i https://<your-railway-domain>/mcp         # should be 401

# With token -> reaches the MCP layer
curl -i https://<your-railway-domain>/mcp \
  -H "Authorization: Bearer <your MCP_BEARER_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'