Fruit Forwarder MCP

Fruit Forwarder

Apple Reminders／CalendarとHome Assistantをつなぐ、macOS上で動作するローカルブリッジです。 読み書きにはAppleのEventKit APIを使用し、小規模なstdio MCP サーバーを公開して、許可リストに登録されたデータをHome Assistantにプッシュします。

初期リリースです。 リマインダーと読み取り専用カレンダーは、HAとローカルMCPに対応しています （カレンダーのセットアップを参照）。バックグラウンドでの EventKit権限と再起動後の復旧については、まだ検証が必要です。リリースロードマップを参照してください。まずは、Home AssistantとローカルMCPの設定について、完全なセットアップガイドをご覧ください。 標準的なLovelaceの例はdocs/dashboard-examples.mdにあります。 現在の対応状況については互換性マトリックスを、モノレポと信頼境界に関する判断についてはアーキテクチャ決定記録を参照してください。 問題報告の範囲と情報の秘匿に関するガイダンスについては、SUPPORT.mdを参照してください。 詳細な脅威モデルとセキュリティ上の制限については、SECURITY.mdを参照してください。 サードパーティへの帰属表示はTHIRD_PARTY_NOTICES.mdに記載されています。 リリース履歴はCHANGELOG.mdで管理されています。 リリースの判定基準はdocs/acceptance-evidence.mdで管理されています。 変更と復旧の動作仕様はdocs/command-lifecycle.mdに記載されています。 リマインダーのフィールド対応状況と更新時の保持ルールは docs/reminder-semantics.mdに記載されています。 Home Assistantの診断情報ダウンロードには、秘匿化された運用上の件数とタイムスタンプのみが含まれ、認証情報や家庭内の情報は含まれません。

セキュリティ境界

• Appleの認証情報がmacOSの外部に出ることはありません。EventKitはMacユーザーのサインイン済みアカウントとmacOSのリマインダー権限を使用します。
• ブリッジは、単一のHome Assistantウェブフックに対してアウトバウンドのHTTPSリクエストを送信します。Home Assistantの長期アクセストークンは保持しません。
• ウェブフックにはランダムな256ビットのパストークンを使用し、local_onlyとして登録します。
• HAとブリッジの両方で、リマインダーリストの許可リストを適用します。ブリッジは読み書きにEventKitのリストIDを完全一致で使用します。
• HAとMCPは、作成、編集、完了、再開を提供します。削除とリスト管理の操作は意図的に提供していません。
• MCPでは、"mcp_read_only": trueを指定することで読み取りツールのみを公開できます。HAでの編集はこれとは独立して利用できます。
• ウェブフックトークンはmacOSのログインキーチェーンに保存されます。LaunchAgentの環境変数、リポジトリ、JSON設定には含まれません。
• ログに記録されるのは件数、コマンドID、エラーであり、リマインダーのタイトルやメモは記録されません。

コンポーネント

• eventkit-helper：Appleの公開EventKit APIのみを使用する、小規模なネイティブSwiftヘルパーです。
• cmd/icloud-reminders-bridge：検出、ペアリング、デーモン、単発同期、stdio MCPのエントリーポイントです。ネイティブヘルパーを30秒のタイムアウト付きで直接呼び出します。macOSは、処理を担当するアプリケーションに対してリマインダーへのアクセスを制御します。
• homeassistant/custom_components/icloud_reminders_bridge：プッシュ駆動型のHA ToDoエンティティと永続コマンドキューです。
• deployment：Mac用のユーザーLaunchAgentです。

クイックスタート

1. リストを所有する iCloud アカウントにサインインした Mac でビルドしてインストールします。

   ./scripts/install-macos.sh --install-only
   

2. macOS のプロンプトが表示されたら、リマインダーへのアクセスを許可します。正確なリスト ID を確認します。

   ~/Library/Application\ Support/icloud-reminders-bridge/bin/icloud-reminders-bridge discover
   

3. ~/.config/icloud-reminders-bridge/config.json を編集し、公開したいリストだけを追加します。pair を実行して永続的なベアラートークンを作成し、そのトークンと同じリスト ID を使って Home Assistant のカスタム統合を設定します。

4. ユーザーごとの LaunchAgent を起動します。

   ./scripts/install-macos.sh
   

再起動後またはアップグレード後に、icloud-reminders-bridge doctor --json を実行すると、設定済みのヘルパーと（HA 同期が有効な場合は）ペアリング用 Keychain 項目を、リマインダーの内容を読み取らずに確認できます。 書き込みで EventKit の結果が不確定になった場合、doctor は実行中のコマンドを報告し、明示的に解決されるまで同期を一時停止します。復旧手順については、docs/setup.md を参照してください。 復元後に Home Assistant で永続化されたコマンドキューのエポックが異なる場合も、ブリッジは一時停止し、キューにある変更を適用する前に reset-queue-epoch の明示的な確認を求めます。

ペアリングトークンは macOS のログイン Keychain に保存されます。ランタイム設定、状態ファイル、ログ、トークンはコミットしないでください。

パッケージ版ビルドでは、安定した逆 DNS 形式のサービス識別子 com.pdfowler.fruitforwarder を使用します。com.example.icloud-reminders-bridge を明示的に使用する既存のプロトタイプ設定も引き続き有効です。置き換え後のインストールを確認するまでは、古い Keychain 項目を削除しないでください。

設定

completed_retention は、完了したリマインダーをブリッジのスナップショットに保持する期間を指定します。デフォルトは 30 日（720h）です。これにより、最近完了した項目を残しながら、古い iCloud 履歴で Home Assistant がいっぱいになるのを防ぎます。

ブリッジでは、削除操作やリスト管理操作を意図的に公開していません。信頼できないクライアントと共有するネットワーク上にサービスを配置する前に、許可リストと Home Assistant の Webhook パスを確認してください。

開発

このリポジトリは、小規模なポリグロットモノレポです。Go がブリッジ／MCP プロセスを、Swift が EventKit ヘルパーを担当し、Home Assistant 統合は決定論的な HACS ディストリビューションとしてエクスポートされます。ターゲット間で共通のコマンドには Task を使用してください。

task check          # Go, HA, metadata and script checks
task test           # Go, HA, and native EventKit tests when running on macOS
task build:macos    # build staged Go/native outputs on macOS
task package:ha    # build the HACS tree and versioned HA archive
task package:macos # build a versioned macOS tarball on macOS
task package:mcp   # build the macOS MCPB and candidate registry metadata
task install:local PACKAGE=dist/macos/fruit-forwarder-macos-0.1.0.tar.gz
task release:check # build/validate every target available on this host
task release:prepare # record the verified candidate manifest

MCP レジストリのメタデータは、バージョン付き MCPB アーティファクトのビルドとハッシュの計算が完了した後にのみ意図的に生成されます。詳しくは packaging/mcp/README.md を参照してください。ビルドやリリースの確認によって、公開コマンドが暗黙的に実行されることはありません。 メンテナー向けの公開ゲートと、HACS／MCP の後続手順については、docs/publishing.md に記載されています。

task install:local は、明示的な macOS 操作です。一時ディレクトリに展開してパッケージインストーラーを実行する前に、パッケージ化されたアーカイブとそのチェックサムを検証します。launchd を有効にせずにバイナリを配置するには INSTALL_ONLY=true を追加します。既知のレガシー設定の移行を意図的に準備する場合は、MIGRATE_HOME_CTRL=true を追加します。

macOS tarball は自己インストール型です。展開し、同梱の設定ファイルに正確な ID をコピーしてから、scripts/install-package-macos.sh を実行してください。ソースチェックアウトの scripts/install-macos.sh は、引き続き開発者向けのビルド／インストール手段です。 パッケージ版インストーラーは、以前の実行ファイル一式を同じロールバックディレクトリに保持し、同梱の LaunchAgent レンダラーを使用します。既存のランタイム設定や Keychain 項目は上書きしません。 同梱の scripts/uninstall-macos.sh はサービスファイルのみを削除し、後で明示的にクリーンアップするか判断できるよう、ランタイムデータは保持します。

go test -race ./...
go vet ./...

ネイティブヘルパーには macOS と EventKit のアクセス許可プロンプトが必要です。ローカルでのビルド方法については CONTRIBUTING.md を、脆弱性の報告方法については SECURITY.md を参照してください。