calendar-bridge

CalendarBridge は、ChatGPT が Apple Calendar を操作できるようにする Model Context Protocol（MCP）コネクターです。読み取りはローカルで実行され、要求された結果は認証済みのリレーを経由します。すべての操作は、小さなローカルエージェントを通じてあなた自身の Mac 上で実行されます。クラウド側にあるのは、ChatGPT と Mac の間でリクエストを中継するだけの、ステートレスなリレーです。

  ChatGPT  ──OAuth──►  CalendarBridge relay  ──job queue──►  calendar-agent  ──►  Calendar.app
 (connector)          (Vercel, stateless)      (your Mac, polls & executes)     (on your Mac)

イベントが読み取られたり書き込まれたりする場所は、あなたの Mac だけです。リレーが保存するのは、有効期間の短いジョブのペイロードとアカウント情報のみです。ジョブの処理中でない限り、イベントがリレーに見えることはなく、ジョブは数秒で期限切れになります。

---

ユーザー向け — 3 ステップ

1. アカウントを作成します。calendarbridge.vercel.app にアクセスして、ペアリングコードを生成してください。

2. Mac エージェントをインストールします（Node 18+ が必要です）。

npx calendar-agent pair <YOUR-CODE>   # link this Mac to your account
npx calendar-agent install            # keep it running on every restart

Calendar に初めてアクセスすると、macOS に 「Terminal がカレンダーを制御しようとしています」 と表示されます。「OK」 をクリックしてください（初回のみ）。

3. ChatGPT に接続します：設定 → プラグイン → 開発者モード（セキュリティとログイン）をオン → カスタムプラグインを作成 → MCP サーバーの URL https://calendarbridge.vercel.app/mcp を貼り付け → 認証で OAuth を選択 → サインインして 「許可」 をクリックします。

これで完了です。新しいチャットで、「Apple Calendar から歯医者の予約を検索して」 や 「明日の午前 9 時に、仕事のカレンダーにチームスタンドアップを追加して」 と頼んでみましょう。

Mac の電源が入っていて、エージェントが実行されている必要があります。npx calendar-agent install を実行すると、ログイン時に自動起動し、クラッシュした場合も再起動します。

エージェントの管理

npx calendar-agent status      # is it paired & reachable?
npx calendar-agent logs        # recent activity
npx calendar-agent uninstall   # stop auto-start

---

ChatGPT でできること

ツール	操作
list_calendars	すべてのカレンダー（仕事、個人、家族など）を一覧表示します
list_events	指定した日付範囲内の今後のイベント（デフォルトは今後 7 日間）を一覧表示します。カレンダーを 1 つ指定することもできます
search_events	タイトルにキーワードを含むイベントを検索します
get_event	ID を指定してイベントを 1 件読み取ります
create_event	イベントを作成します（タイトル、開始、終了、場所、メモ、カレンダー、終日設定は任意）
update_event	イベントの項目を編集します（指定した項目は上書きされるため、先に読み取ってください）

---

セルフホスト

自分のリレーを実行すれば、ホストされたインスタンスに依存せずに利用できます。

前提条件： Vercel アカウントと Supabase プロジェクト（無料プランで問題ありません）。

1. ストレージ — Supabase プロジェクトの SQL エディターで supabase/schema.sql を実行します。RLS が有効な、Redis に似た小規模な KV とキューの機能（nb_* 関数）が作成されます。
2. デプロイ — server/ ディレクトリを Vercel にデプロイします。
3. 環境変数を設定します（server/.env.example を参照）。
   • SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY — プロジェクトの URL とサービスロールキー
   • JWT_SECRET — openssl rand -hex 32
4. 確認： curl https://YOUR-APP.vercel.app/api/health を実行し、redisConfigured、redisOk、jwtSecretSet がすべて true であることを確認します。
5. エージェントの接続先を設定します：npx calendar-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

仕組み

• 認証 — PKCE と Dynamic Client Registration（RFC 7591）を使用する OAuth 2.1 です。ChatGPT が自身を登録し、ユーザーは CalendarBridge の同意ページでサインインすると、ChatGPT はスコープが設定された MCP アクセストークンを取得します。JWT は HMAC で署名されます。権限がそれぞれ異なる 3 種類（session、agent、mcp）があります。Resend（RESEND_API_KEY）によるメールアドレス認証は任意です。設定されていない場合は無効で、必須にするかどうかはオプトインです（REQUIRE_EMAIL_VERIFICATION）。
• リレー — MCP ツール呼び出し → ジョブが jobs:<user> に送信される（TTL は呼び出し元の待機時間以下なので、放置されたジョブが後から実行されることはありません）→ ハング状態のロングポーリングを行っている Mac エージェントに約 200 ミリ秒以内にジョブが渡され、実行後に結果が送信される → MCP ハンドラーが結果を返します。ロングポーリングにより、固定間隔ではなくジョブの到着時に配信されるため、リレーのオーバーヘッドは約 1 秒ではなく約 300 ミリ秒です。エージェントは、アクティブに接続されている間のみ「オンライン」とみなされます。
• エージェント — 依存関係のない Node CLI です。ツールは JXA（osascript -l JavaScript）を介して Calendar.app を操作します。引数は argv 経由で JSON として渡されます（シェル展開は行いません）。macOS の LaunchAgent により、ログイン後もクラッシュ後も動作を継続します。

リポジトリの構成

server/    Vercel functions: OAuth + MCP endpoint + relay        (deploy this)
agent/     calendar-agent — the npm-published Mac CLI                 (users npx this)
kit/       Browser automations: register the dev-mode connector AND
           fill the OpenAI directory submission (see kit/README.md)
supabase/  schema.sql for self-hosting the storage
test/      end-to-end OAuth + MCP integration test

開発

# server
cd server && cp .env.example .env.local   # fill in, then: vercel dev
# end-to-end test against a live deployment (reads ../.env.local)
node test/e2e-oauth.mjs
# agent unit tests
node --test agent/test-agent-unit.mjs

セキュリティとプライバシー

• イベントの読み取りと書き込みはお使いの Mac 上でのみ行われます。リレーは、要求されたコンテンツを短時間だけジョブ／結果キューに一時保存します。ジョブのペイロードは Redis 形式のストレージに短い TTL で保存され、配信後に削除されます。
• エージェントトークンは ~/.calendarbridge-agent.json（モード 600）に保存されます。
• シークレットはコミットされません。.gitignore と .env.example ファイルを参照してください。
• 書き込みツールには破壊的な操作であることが示されるため、ChatGPT はイベントを変更する前に確認を求めます。

ライセンス

MIT © Isaiah Dupree

本番環境のストレージとオーナー検証

Relay 1.4 は、設定済みの共有 Supabase プロジェクトで、サービスロール専用の分離されたテーブル／関数を使用します。本番環境ではストレージ設定がない場合に起動を拒否し、RPC リクエストを 10 秒以内に制限します。また、ストレージまたは署名の設定を利用できない場合は HTTP 503 を返します。このバージョンをデプロイする前に、リポジトリに含まれる分離ストレージ用マイグレーションを適用してください。他のブリッジのアカウントテーブルや関数は置き換えません。

node --env-file=.env.local test/live-storage.mjs は、一時的な統合テストキーを使用して、実際の永続ストア、FIFO、期限切れ処理、カウンターを検証します。BRIDGE_SESSION_FILE=/private/owner-session.json BRIDGE_READ_TOOL=READ_TOOL node test/live-relay.mjs は、実際のオーナーセッション、PKCE OAuth、ホストされた MCP、ペアリング済み Mac からの読み取りを検証します。このブリッジのインベントリツールを選択してください。レビュー担当者のデータは、実環境での受け入れテストとして扱われません。認証情報とセッションは Git リポジトリの外に保管してください。