Fruit Forwarder MCP

Fruit Forwarder

在 macOS 上连接 Apple 提醒事项／日历与 Home Assistant 的本地桥接工具。它使用 Apple 的 EventKit API 进行读取和写入，提供一个精简的 stdio MCP 服务，并将允许列表中的数据推送到 Home Assistant。

早期版本。 提醒事项和只读日历支持 Home Assistant 与本地 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 webhook 发起出站 HTTPS 请求。它不持有 Home Assistant 长期访问令牌。
• webhook 使用随机的 256 位路径令牌，并注册为 local_only。
• Home Assistant 和桥接工具都会强制执行提醒事项列表允许列表。桥接工具使用精确的 EventKit 列表 ID 进行读取和写入。
• Home Assistant 和 MCP 提供创建、编辑、完成和重新打开操作。刻意不提供删除和列表管理操作。
• MCP 可以仅公开带有 "mcp_read_only": true 的只读工具；Home Assistant 的编辑功能独立可用。
• webhook 令牌存储在 macOS 登录钥匙串中，不会放入 LaunchAgent 环境、代码库或 JSON 配置中。
• 日志包含计数、命令 ID 和错误，不包含提醒事项标题或备注。

组件

• eventkit-helper：仅使用 Apple 公共 EventKit API 的轻量原生 Swift 辅助程序。
• cmd/icloud-reminders-bridge：发现、配对、守护进程、单次同步和 stdio MCP 入口点。它会直接调用原生辅助程序，超时时间为 30 秒；macOS 会对发起调用的应用强制执行提醒事项访问权限。
• homeassistant/custom_components/icloud_reminders_bridge：由推送驱动的 Home Assistant 待办实体和持久化命令队列。
• deployment：适用于 Mac 的用户 LaunchAgent。

快速开始

1. 在已登录拥有这些列表的 iCloud 账户的 Mac 上构建并安装：

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

2. macOS 提示时授予 Reminders 访问权限。查找准确的列表 ID：

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

3. 编辑 ~/.config/icloud-reminders-bridge/config.json，只添加 你想要公开的列表。运行 pair 创建持久的 bearer token，并使用该 token 和相同的列表 ID 配置 Home Assistant 自定义集成。

4. 启动每用户 LaunchAgent：

   ./scripts/install-macos.sh
   

重启或升级后，icloud-reminders-bridge doctor --json 会检查已配置的 helper，以及（启用 HA 同步时）配对用的 Keychain 项目，但不会读取提醒内容。 如果写入操作的 EventKit 结果不确定，doctor 会报告正在执行的命令，并暂停同步，直到明确解决此问题；请参阅 docs/setup.md 中的恢复步骤。 如果 Home Assistant 在恢复后显示了不同的持久化命令队列 epoch，bridge 也会暂停，并要求在应用排队的变更前明确审核 reset-queue-epoch。

配对 token 存储在 macOS 登录 Keychain 中。请勿提交运行时配置、状态文件、日志或 token。

打包版本使用稳定的反向 DNS 服务标识符 com.pdfowler.fruitforwarder。 现有明确使用 com.example.icloud-reminders-bridge 的原型配置仍然有效；在确认替换安装正常之前，请勿删除旧的 Keychain 项目。

配置

completed_retention 控制已完成提醒在 bridge 快照中保留的时长。默认值为 30 天（720h）；这样可以避免较早的 iCloud 历史记录填满 Home Assistant，同时保留近期已完成的项目。

bridge 有意不公开删除或列表管理操作。 在将此服务部署到与不受信任的客户端共享的网络之前，请检查允许列表和 Home Assistant webhook 路径。

开发

此仓库是一个小型多语言单体仓库：Go 负责 bridge/MCP 进程， Swift 负责 EventKit helper，而 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 操作。它会先验证已打包的 归档文件及其校验和，再将其解压到临时目录并运行软件包安装程序。添加 INSTALL_ONLY=true 可暂存二进制文件而不激活 launchd；有意准备已知的旧配置迁移时，可添加 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 ./...

原生 helper 需要 macOS 和 EventKit 权限提示。有关本地构建详情，请参阅 CONTRIBUTING.md；有关漏洞披露指南，请参阅 SECURITY.md。