shortcuts-bridge

ShortcutsBridgeは、ChatGPTでAppleショートカットを一覧表示、検索し、実行できるModel Context Protocol（MCP）コネクターです。読み取り操作はローカルで実行され、要求された結果は認証済みのリレーを経由して受け渡されます。すべての操作は、小さなローカルエージェントを通じてご自身のMac上で実行されます。クラウド側は、ChatGPTとMacの間でリクエストを中継するだけのステートレスなリレーです。

  ChatGPT  ──OAuth──►  ShortcutsBridge relay  ──job queue──►  shortcuts-agent  ──►  Shortcuts.app
 (connector)          (Vercel, stateless)      (your Mac, polls & executes)     (via the shortcuts CLI)

ショートカットの一覧表示や実行が行われる場所は、常にご自身のMacだけです。リレーに保存されるのは、短時間だけ有効なジョブのペイロードとアカウント情報だけです。ジョブの処理中を除き、ショートカットの内容がリレーから見えることはなく、ジョブは数秒で期限切れになります。

ショートカットはMacやiPhone上でほぼ何でも実行できます。HomeKitの制御、アプリの操作、スクリプトの実行、Web APIの呼び出しなどが可能なため、run_shortcutを使えば、ChatGPTからすでに作成済みのあらゆる自動化を起動できます。

---

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

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

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

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

各ショートカットを初めて実行するとき、macOSから許可を求められる場合があります。その場合はOKをクリックしてください（ショートカットごとに一度だけ）。これはショートカットごとの許可であり、自動化全般への包括的な許可ではありません。

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

これで完了です。新しいチャットで、*「集中に関するAppleショートカットを検索して」や「Morning Briefingショートカットを実行して」*と依頼できます。

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

エージェントの管理

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

---

ChatGPTでできること

ツール	操作
list_shortcuts	Mac上のすべてのショートカットを一覧表示（読み取り専用）
search_shortcuts	キーワードでショートカットを検索（読み取り専用）
list_folders	ショートカットのフォルダを一覧表示（読み取り専用）
run_shortcut	名前を指定してショートカットを実行。任意のテキスト入力を渡し、出力を返す

最初の3つは読み取り専用のカタログ検索です。実際に処理を行うツールはrun_shortcutだけです。これはオープンワールド型であり（ショートカットから現実世界での操作を実行できるため）、ChatGPTは実行前にユーザーへ確認します。また、実行できるのは、すでに作成済みのショートカットだけです。

---

セルフホスト

ホスト版に依存しないよう、ご自身でリレーを実行できます。

前提条件：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とservice-roleキー
   • JWT_SECRET — openssl rand -hex 32
4. 確認：curl https://YOUR-APP.vercel.app/api/healthを実行し、redisConfigured、redisOk、jwtSecretSetがすべてtrueになっていることを確認します。
5. エージェントの接続先を設定します：npx shortcuts-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

仕組み

• 認証 — PKCE と Dynamic Client Registration（RFC 7591）を使用した OAuth 2.1 です。ChatGPT が自身を登録し、ユーザーが ShortcutsBridge の同意ページでサインインすると、ChatGPT はスコープが設定された MCP アクセストークンを取得します。JWT は HMAC で署名されます。権限が異なる 3 種類（session、agent、mcp）があります。Resend（RESEND_API_KEY）によるメールアドレス確認は任意です。設定しない場合は無効で、適用はオプトイン方式です（REQUIRE_EMAIL_VERIFICATION）。
• リレー — MCP ツールの呼び出し → ジョブを jobs:<user> にプッシュ（TTL は呼び出し元の待機時間以下に設定されるため、放棄されたジョブが後から実行されることはありません） → 待機状態のロングポールを保持している Mac エージェントに約 200 ms 以内にジョブが渡され、実行後に結果をプッシュ → MCP ハンドラーが結果を返します。ロングポールにより、ジョブは固定間隔ではなく到着時に配信されるため、リレーのオーバーヘッドは約 1 秒ではなく約 300 ms です。エージェントは、接続がアクティブな間のみ「オンライン」と見なされます。
• エージェント — 依存関係のない Node CLI です。ツールは macOS の shortcuts コマンドラインツール（shortcuts list、shortcuts run）をシェルから呼び出します。引数は argv として渡され、シェル文字列への埋め込みは行われません。macOS の LaunchAgent が、ログイン後もクラッシュ後もエージェントを起動状態に保ちます。

リポジトリの構成

server/    Vercel functions: OAuth + MCP endpoint + relay        (deploy this)
agent/     shortcuts-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 上でのみ行われます。リレーは要求されたコンテンツを一時的に、短期間有効なジョブ／結果キューに保存します。ジョブのペイロードは短い TTL が設定された Redis 形式のストレージに保存され、配信後に削除されます。
• エージェントトークンは ~/.shortcutsbridge-agent.json（モード 600）に保存されます。
• シークレットはコミットされません。.gitignore と .env.example ファイルを参照してください。
• run_shortcut はオープンワールドとしてマークされています。ショートカットは現実世界での操作を実行できるため、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 の外部に保管してください。