shortcuts-bridge

ShortcutsBridge 是一个 Model Context Protocol（MCP）连接器，可让 ChatGPT 列出、搜索并运行你的 Apple Shortcuts。读取操作会在本地执行，请求的结果会通过经过身份验证的中继传递 — 每项操作都通过一个小型本地 Agent 在你自己的 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 Agent（需要 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 可能会询问是否允许运行 — 点击 好（每个快捷指令只需操作一次）。这是针对单个快捷指令的授权，不是授予全面的自动化权限。

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

完成。在新聊天中输入：“搜索我的 Apple Shortcuts，找出与专注相关的内容” 或 “运行我的 Morning Briefing 快捷指令。”

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

管理 Agent

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	列出你的 Shortcuts 文件夹（只读）
run_shortcut	按名称运行快捷指令，可选输入文本，并返回其输出

前三项是只读的目录查询。run_shortcut 是唯一会执行操作的工具 — 它面向开放场景（快捷指令可能会执行现实世界中的操作），因此 ChatGPT 会在运行前向你确认，而且只能运行你已构建的快捷指令。

---

自托管

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

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

---

工作原理

• 身份验证 — 使用 PKCE 和动态客户端注册（RFC 7591）的 OAuth 2.1。ChatGPT 会注册自身，用户在 ShortcutsBridge 授权页面登录，随后 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 命令行工具。工具通过 macOS shortcuts 命令行工具执行命令（shortcuts list、shortcuts run）；参数作为 argv 传递（绝不通过 Shell 插值）。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 上列出和运行。中继会在短期任务队列/结果队列中临时存储请求内容——任务负载存储在类似 Redis 的存储中，TTL 较短，并会在投递后删除。
• Agent 令牌存储在 ~/.shortcutsbridge-agent.json（模式 600）。
• 不会提交任何密钥；请参阅 .gitignore 和 .env.example 文件。
• run_shortcut 被标记为开放世界工具——快捷指令可能会执行现实世界中的操作——因此 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 仓库之外。