reminders-bridge

RemindersBridge 是一个 Model Context Protocol（MCP）连接器，可让 ChatGPT 使用你的 Apple 提醒事项。读取操作在本地执行，请求的结果通过经过身份验证的中继传递——所有操作都通过一个小型本地 Agent 在你自己的 Mac 上运行。云端部分只是一个无状态中继，用于在 ChatGPT 和你的 Mac 之间传递请求。

  ChatGPT  ──OAuth──►  RemindersBridge relay  ──job queue──►  apple-reminders-agent  ──►  Reminders.app
 (connector)          (Vercel, stateless)      (your Mac, polls & executes)        (on your Mac)

你的 Mac 是唯一会读取或写入提醒事项的地方。中继只存储短暂的任务负载和你的账户记录；除非有任务正在处理中，否则它看不到任何提醒事项，而且任务会在几秒钟内过期。

---

面向用户 — 3 个步骤

1. 创建账户：访问 remindersbridge.vercel.app 并生成配对码。

2. 安装 Mac Agent（需要 Node 18+）：

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

首次访问提醒事项时，macOS 会询问 “Terminal 想要控制提醒事项”——点击 “好”（仅需一次）。

3. 连接 ChatGPT： 设置 → 插件 → 开启开发者模式（安全与登录）→ 创建自定义插件 → 粘贴 MCP 服务 URL https://remindersbridge.vercel.app/mcp → 身份验证选择 OAuth → 登录并点击允许。

就这样。在新聊天中输入：“在我的 Apple 提醒事项中搜索牙医预约”，或 “把燕麦奶添加到我的‘杂货’列表，截止日期为明天。”

你的 Mac 必须保持唤醒状态并运行 Agent。npx apple-reminders-agent install 可让它在登录时自动启动，并在意外崩溃时重新启动。

管理 Agent

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

---

ChatGPT 可以做什么

工具	操作
search	按关键词搜索提醒事项
fetch	按 ID 获取一条提醒事项的完整详情
list_lists	列出所有提醒事项列表及未完成事项数
list_reminders	列出提醒事项（可选筛选某个列表，或包含已完成事项）
get_reminder	按 ID 或名称读取提醒事项
create_reminder	创建提醒事项（名称、可选备注、截止日期、目标列表）
complete_reminder	将提醒事项标记为已完成（或重新打开）
update_reminder	编辑提醒事项的名称、备注或截止日期

---

自托管

你可以运行自己的中继，这样就不必依赖托管实例。

前置条件： 一个 Vercel 账户和一个 Supabase 项目（免费套餐即可）。

1. 存储——在 Supabase 项目的 SQL 编辑器中，运行 supabase/schema.sql。它会创建一个轻量的 Redis 风格 KV 和队列接口（nb_* 函数），并启用 RLS。
2. 部署 server/ 目录到 Vercel。
3. 设置环境变量（参见 server/.env.example）：
   • SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY——你的项目和服务角色密钥
   • JWT_SECRET——openssl rand -hex 32
4. 验证： curl https://YOUR-APP.vercel.app/api/health → redisConfigured、redisOk、jwtSecretSet 均为 true。
5. 将 Agent 指向该服务：npx apple-reminders-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

工作原理

• 身份验证 — 使用 PKCE 和动态客户端注册（RFC 7591）的 OAuth 2.1。ChatGPT 会自行注册，用户在 RemindersBridge 授权页面登录，随后 ChatGPT 会获得受限范围的 MCP 访问令牌。JWT 使用 HMAC 签名；分为三种类型（session、agent、mcp），权限各不相同。可选通过 Resend 验证邮箱（RESEND_API_KEY）；除非配置，否则默认关闭；是否强制验证由用户选择（REQUIRE_EMAIL_VERIFICATION）。
• 中继 — MCP 工具调用 → 将任务推送至 jobs:<user>（TTL 不超过调用方的等待时限，因此被放弃的任务不会延迟执行）→ Mac Agent（保持长轮询连接）在约 200 毫秒内收到任务，执行后推送结果 → MCP 处理程序返回结果。长轮询意味着任务到达时立即送达，而非按固定间隔轮询，因此中继开销约为 300 毫秒，而不是约 1 秒。只有在 Agent 主动连接时，才视为其“在线”。
• Agent — 无依赖的 Node CLI。工具通过 JXA（osascript -l JavaScript）操作 Reminders.app；参数以 JSON 格式通过 argv 传递（绝不通过 Shell 插值）。macOS LaunchAgent 会使其在登录后持续运行，并在崩溃后重新启动。

仓库结构

server/    Vercel functions: OAuth + MCP endpoint + relay        (deploy this)
agent/     apple-reminders-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，并在送达后删除。
• Agent 令牌存储在 ~/.remindersbridge-agent.json（权限模式为 600）。
• 不会提交任何密钥；请参阅 .gitignore 和 .env.example 文件。
• 写入工具会标记为具有破坏性，因此 ChatGPT 会在更改提醒事项前征求确认。

许可证

MIT © Isaiah Dupree

生产环境存储与所有者验证

Relay 1.4 使用配置的共享 Supabase 项目中仅供服务角色访问的隔离表和函数。生产环境在缺少存储配置时会拒绝运行，将 RPC 请求时限限制为十秒，并在存储或签名配置不可用时返回 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 仓库之外。