FocusRelay

FocusRelay — 适用于 macOS 的高速 Swift OmniFocus MCP 服务和 CLI

用 AI 规划每日安排并让 OmniFocus 保持最新

FocusRelay 是一款高速原生 Swift MCP 服务和 CLI，可帮助 AI 助手通过 OmniFocus 的官方 API 读取并安全更新 OmniFocus。

通过 Homebrew 安装 · 了解它的功能 · 为 FocusRelay 点星 · 参与塑造 FocusRelay

询问 OmniFocus 中已有的工作，检查答案，然后批准所做的更改，无需逐项点击浏览冗长的任务列表。

询问、检查、更新

FocusRelay 专为有针对性的问题和精简的回答而设计，因此助手处理常规请求时无需读取整个 OmniFocus 数据库。

试试这些提示词：

• “帮我分批处理 OmniFocus 收件箱中的事项。”
• “我有多少个已标记事项？”
• “显示收件箱中最先出现的三个可用任务。”
• “找到名为 [task name] 的任务，为其添加标记，并确认更改。”
• “将 [task name] 的到期时间设为明天下午 5 点（我的本地时区），并确认更改。”

在提供 MCP 服务提示词的客户端中，选择 process_inbox。在 OpenCode 中，运行 /focusrelay:process_inbox 即可启动引导式工作流。 基于 CLI 的 Agent 可通过 focusrelay workflow get process_inbox 获取完全相同的说明；使用 focusrelay workflow list 可查看可用工作流，而无需加载其完整文本。

这些工作流已使用多个支持 MCP 的模型在 OpenCode 中进行测试。更新针对稳定的 OmniFocus ID，并可验证保存结果。如果名称重复，请先要求查看匹配项，再进行任何更改。

当前版本可以：

• 引导受支持的 MCP 客户端和基于 CLI 的 Agent，按有界范围、优先审批的方式处理收件箱；
• 使用日期、标记、标签、项目、可用状态、收件箱状态、完成状态、预估时长和文本搜索查找并统计任务；
• 查看项目、文件夹、标签、任务计数和停滞工作；
• 更新名称、备注、标记、日期、预估时长、标签、项目设置和复查间隔；
• 使用 OmniFocus 原生的复查时间戳和下次复查语义，将进行中和暂停中的项目标记为已复查；
• 放入收件箱、恢复、完成、重新激活和移动现有任务；
• 完成、重新激活、更改状态和移动现有项目；
• 预览拟议的更改并验证保存结果。

当前版本可以更新现有任务和项目。不支持创建或删除项目；创建功能的开发进度见 #82 和 #83。

为什么选择 FocusRelay？

在开发分支中，Forecast 问题支持显式的仅限部分任务的范围。范围包括过去和今天安排的操作、已标记事项以及配置的 Forecast 标签；它不是原生 Forecast 总数，也不包括日历事件和原生可见性偏好。此功能需要匹配的开发版二进制文件和桥接程序，当前 Homebrew 版本不包含此功能。

让助手专注于重点

FocusRelay 向模型公开 9 个工具：7 个读取工具，以及用于支持的更改操作的 edit_tasks 和 edit_projects。将 7 个编辑工具合并为 2 个后，完整工具目录从 14 个缩减到 9 个；在受控模型测试中，上下文用量减少了 7–13%，为用户的实际工作留出了更多空间。内部诊断保留在 CLI 中，计数命令不会返回冗长的项目列表，字段选择也能让响应更精简。

原生 Swift 速度，适应真实库规模

FocusRelay 编译为原生 Swift 程序，并通过 Homebrew 安装，请求处理路径中无需 Node.js 或 Python 运行时。单次遍历筛选和提前停止的分页机制，让收件箱的定向读取在数千个任务规模下的测试中接近一秒完成。同一核心也支持 CLI，用于执行精确且低上下文用量的查询。

在 OmniFocus 能理解其数据的环境中运行

Swift 服务会将工作分派给轻量级桥接插件，该插件在 OmniFocus 的 Omni Automation 环境中运行。它使用有文档说明的 API 和原生状态，使结果与 OmniFocus 保持一致，而不会读取其私有数据库。

进行可验证的更改

编辑工具以稳定 ID 为目标，并支持预览、逐项结果、精简返回字段和可选验证。保存、更新或验证失败时会报告失败，而不是成功。

FocusRelay 会按顺序处理 OmniFocus 任务，告知助手等待每次更新完成，并在过载时明确报告，而不是让请求相互冲突。当 MCP 客户端断开连接时，其 FocusRelay 进程会正常退出，而不会继续在后台运行。

有关面向用户的更改和升级要求，请参阅最新发行说明。

隐私与安全

FocusRelay 在你的 Mac 上本地运行。其 Swift 服务会在设备上与桥接插件通信，由后者通过有文档说明的 API 访问 OmniFocus。FocusRelay 没有托管云服务，也不会将你的 OmniFocus 数据发送到 FocusRelay 运营的服务。

你的 MCP 客户端和所选 AI 模型可能会根据各自的隐私条款传输工具输入和结果。使用 FocusRelay 处理敏感数据前，请先查看相关设置。

使用 Homebrew 安装 OmniFocus MCP 服务

要求：

• Apple 芯片 Mac，运行 macOS 26 或更高版本；
• OmniFocus 4；
• Homebrew；
• 兼容 MCP 的助手或支持 Shell 的 AI Agent。

1. 安装并信任 formula

Homebrew 6 要求对来自非官方 tap 的 formula 明确授予信任。仅信任 FocusRelay formula，然后安装：

brew tap deverman/focus-relay
brew trust --formula deverman/focus-relay/focusrelay
brew install focusrelay

针对 formula 的信任授权可让 FocusRelay 运行，而无需信任 tap 中当前或未来的所有 formula。详情请参阅 Homebrew 的 Tap Trust 文档。

2. 运行引导式设置

运行已安装的设置命令：

focusrelay setup

该命令会查找 Homebrew 随附的插件，验证其版本与二进制文件是否匹配，检测所有受支持的 OmniFocus 插件文件夹，并在请求复制许可前预览源文件和目标位置。只有在替换插件成功复制后，现有插件才会被替换。重新运行设置时，会报告已是最新版本的副本。

设置过程还会输出与客户端无关的 MCP 命令及参数。为指定客户端示例添加 --client claude-code、--client codex 或 --client opencode；FocusRelay 会打印配置信息，但不会修改配置。

对于自动化，请先查看同一计划，然后明确选择加入：

focusrelay setup --dry-run
focusrelay setup --non-interactive

从源代码构建？请继续使用 ./scripts/install-plugin.sh；这是用于调用同一 Swift 设置实现的轻量开发入口。

3. 重启 OmniFocus

完全退出 OmniFocus 并重新打开，以加载更新后的插件：

osascript -e 'tell application "OmniFocus" to quit'
sleep 2
open -a "OmniFocus"

4. 检查就绪状态并将 FocusRelay 添加到你的 AI 助手

FocusRelay 目前支持基于终端的 MCP 客户端：Claude Code、 OpenCode、Codex CLI，以及从终端启动的其他客户端。Claude Desktop 和 ChatGPT 桌面应用等桌面应用尚不受支持：macOS 会限制它们访问 FocusRelay 所依赖的 OmniFocus 数据。桌面应用支持的进展可在 #196 中跟踪。

使用以下配置设置本地 stdio MCP 服务：

• 命令：/opt/homebrew/bin/focusrelay
• 参数：serve

claude mcp add --scope user focusrelay -- /opt/homebrew/bin/focusrelay serve

claude mcp list

{
  "mcp": {
    "focusrelay": {
      "type": "local",
      "command": ["/opt/homebrew/bin/focusrelay", "serve"],
      "enabled": true
    }
  }
}

首次查询时，OmniFocus 会询问是否允许自动化操作。选择 运行脚本。如果提示被隐藏，请将 OmniFocus 切换到前台。

重新启动 OmniFocus 后，验证其加载的插件与二进制文件匹配：

focusrelay setup --check-readiness
focusrelay list-tasks --fields id,name --limit 1

然后询问：

我在 OmniFocus 中有多少个已标记的项目？

git clone https://github.com/deverman/FocusRelayMCP.git
cd FocusRelayMCP
swift build -c release
./scripts/install-plugin.sh

将 FocusRelay 用作 OmniFocus MCP 服务或 CLI

MCP 让兼容的助手能够发现 FocusRelay 并选择合适的操作。 CLI 适用于脚本、调试，以及已可访问 shell 的 Agent。

以下示例适用于当前的 Homebrew 版本和源码构建版本。

# Discover or retrieve the same workflows exposed as MCP prompts
focusrelay workflow list
focusrelay workflow get process_inbox

# Count without returning every matching task
focusrelay task-counts --flagged true

# Return only three task names
focusrelay list-tasks \
  --inbox-only true \
  --available-only true \
  --limit 3 \
  --fields name

# Preview a change without touching OmniFocus
focusrelay edit-tasks <task-id> \
  --operation update \
  --flagged true \
  --preview-only \
  --return-fields id,name,flagged

运行 focusrelay --help 查看命令列表。有关写入操作示例和安全规则，请参阅 CLI 和 MCP 安全更新工作流。

将 FocusRelay 与其他 OmniFocus MCP 服务进行比较

FocusRelay 将原生 Swift 服务与在 OmniFocus 内部运行的桥接插件结合起来。Swift 让 MCP 保持快速轻巧；桥接插件则能获取最新数据，并通过 OmniFocus 的文档化 API 应用更改。

✅ 已提供 · 🟡 即将推出 · 🟠 待办事项 · ◇ 项目路线图 · — 当前未记录

此比较依据各项目截至 2026 年 7 月 15 日的公开文档；“未记录”并不表示该功能无法实现。其他项目的公开 README 均未描述与逐目标预览和保存后验证相当的契约。

预览会解析 ID 并验证更改，但不会保存。验证会在 OmniFocus 保存后运行，重新读取受影响的值，并将不匹配报告为失败。这些是 MCP 工具参数，因此 Codex、Claude Code、OpenCode 及其他标准 stdio MCP 客户端都可以使用；模型是否会在未收到要求时选择使用它们，则取决于模型和客户端。对于重要更改，请要求它“先预览，再应用并验证”。

帮助完善 FocusRelay

请参阅 GitHub Issues 了解计划中的工作。如果 FocusRelay 值得加入你的工作流， 请为代码仓库点星，让更多 OmniFocus 用户发现它。

想要贡献力量？选择一个问题、提出一种使用场景，或提交一份目标明确的拉取请求。 请参阅 CONTRIBUTING.md 了解如何开始。

故障排除

桥接超时

1. 将 OmniFocus 切换到前台，并接受首次出现的 Run Script 提示。
2. 确认已在 Automation → Configure Plug-ins… 中启用 FocusRelay Bridge。
3. 运行 focusrelay setup，完全退出 OmniFocus，然后重新打开。
4. 运行 focusrelay setup --check-readiness。

升级后结果似乎过时

OmniFocus 会缓存插件 JavaScript。运行 focusrelay setup，彻底重启 OmniFocus，然后运行 focusrelay setup --check-readiness 进行检查。 项目和标签目录会缓存五分钟；任务查询始终是最新的。

插件和二进制版本不一致

升级 Homebrew formula 会替换二进制文件，但不会更改已安装到 OmniFocus 的插件副本，因此跳过步骤 2 可能导致插件版本落后多个版本。

再次运行引导式设置，重启 OmniFocus，然后检查已加载的版本：

focusrelay setup
# Fully restart OmniFocus
focusrelay setup --check-readiness

设置会在更改文件前，检查所有预期副本（包括启用插件同步时首选的 iCloud 位置）是否可用，并在替换副本复制并验证完成前保留每个现有副本。设置会逐个更新目标位置，因此如果后续目标位置失败，较早的位置可能已经更新。修正报告的问题，并在重启 OmniFocus 前重新运行设置。就绪状态正常表示已加载的插件、所有已安装副本和二进制文件版本一致。

出行后基于时间的结果似乎有误

重启 MCP 客户端和 OmniFocus，让 FocusRelay 获取当前 macOS 时区。

开发

swift build
swift test

FocusRelay 使用 Swift 工具链中的 Swift Testing。生产查询方面的更改必须遵循文档所述的 Omni Automation 合约。

许可证

FocusRelay 根据 MIT License 提供。