calendar-bridge

CalendarBridge 是一个 Model Context Protocol（MCP）连接器，可让 ChatGPT 使用你的 Apple Calendar。读取操作在本地执行，请求的结果通过经过身份验证的中继传递——每项操作都通过一个轻量级本地 Agent 在你自己的 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 Agent（需要 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 想要控制 Calendar”——点击 OK（仅需一次）。

**3. 连接 ChatGPT：**设置 → Plugins → 开启 Developer mode（Security & login）→ Create 自定义插件 → 粘贴 MCP 服务 URL https://calendarbridge.vercel.app/mcp → 身份验证选择 OAuth → 登录并点击 Allow。

就这么简单。在新对话中输入：“在我的 Apple Calendar 中搜索牙医预约” 或 “明天上午 9 点在我的 Work 日历中添加团队例会。”

你的 Mac 必须处于唤醒状态，并运行 Agent。npx calendar-agent install 可让它在登录时自动启动，并在崩溃时自动重启。

管理 Agent

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

---

ChatGPT 可以做什么

工具	操作
list_calendars	列出你的所有日历（Work、Personal、Family 等）
list_events	列出指定日期范围内即将发生的事件（默认未来 7 天），可选指定一个日历
search_events	查找标题包含关键词的事件
get_event	按 ID 读取一个事件
create_event	创建事件（标题、开始时间、结束时间、可选的位置、备注、日历、全天）
update_event	编辑事件字段（会覆盖你传入的字段——请先读取事件）

---

自托管

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

**前置条件：**一个 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 calendar-agent pair <CODE> --server https://YOUR-APP.vercel.app。

---

工作原理

• 身份验证 — 使用 PKCE 和动态客户端注册（RFC 7591）的 OAuth 2.1。ChatGPT 会自行注册，用户在 CalendarBridge 同意页面登录，然后 ChatGPT 获取具有特定权限范围的 MCP 访问令牌。JWT 使用 HMAC 签名；有三种类型（session、agent、mcp），权限各不相同。可选通过 Resend 验证电子邮件（RESEND_API_KEY）；未配置时默认关闭，且需主动选择启用强制验证（REQUIRE_EMAIL_VERIFICATION）。
• 中继 — MCP 工具调用 → 作业推送到 jobs:<user>（TTL 不超过调用方的等待时限，因此被放弃的作业不会延迟执行）→ 持有挂起式长轮询的 Mac Agent 在约 200ms 内收到作业并执行，然后推送结果 → MCP 处理程序返回结果。长轮询意味着作业会在到达时立即分发，而非按固定间隔分发，因此中继开销约为 300ms，而不是约 1s。只有在 Agent 处于活动连接状态时，才会被视为“在线”。
• Agent — 一个无依赖的 Node CLI。工具通过 JXA（osascript -l JavaScript）操作 Calendar.app；参数以 JSON 形式通过 argv 传递（绝不通过 shell 插值）。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，并会在交付后删除。
• Agent 令牌存储在 ~/.calendarbridge-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 仓库之外。