Focus Relay MCP

Focus RelayMCP

macOS上OmniFocus的模型上下文协议（MCP）服务器。通过Claude等人工智能助手使用自然语言查询任务、项目和标签。

Demo: Ask your OmniFocus tasks naturally

*只需询问“我今天应该做什么？”，即可获得即时的筛选结果。*

你能做什么

停止点击无休止的任务列表。只要问：

日计划

• “我今天应该做什么？”-尊重您的时区，今天要完成的任务
• “今天早上怎么样？”-上午6点至中午12点的可用任务
• “今天下午我能做什么？”-下午12点至6点的任务
• “今晚我应该做什么？”-下午6点至10点的任务

项目管理

• “哪些项目没有下一步行动？”-查找停滞的项目
• “显示我停滞的项目”-有任务但没有可用的项目
• “我的\[项目名称\]项目中有哪些任务？”

上下文切换

• “我有哪些可用的上下文？”-查看哪些标签具有可操作的任务
• “显示我可以在Mac上执行的任务”-按上下文筛选
• “我需要打什么电话？”

任务发现

• “我一直在回避什么？”-365天前推迟的任务
• “我在拖延什么？”-最近推迟的任务
• “查找我标记的项目”
• “我这周完成了什么？”

特性

• 基于时间的查询：自然语言时间段过滤
• 项目健康：检测停滞的项目和缺少的下一步行动
• 情境感知：基于标签的过滤和可用性
• 完成日期筛选：按特定日期范围查询已完成的任务/项目
• 智能过滤：按标签、截止日期、推迟日期、完成、持续时间
• 时区感知：自动本地时区检测和处理
• 高性能：单通道滤波，早期退出优化

安装

快速概述： 无论您选择哪种安装方法，都需要完成以下步骤：

1. 安装二进制文件 （通过Homebrew、手动下载或从源代码构建）
2. 安装OmniFocus插件 （以下第2步）
3. 配置MCP 在您的客户中（下面的步骤3）
4. 重新启动OmniFocus （以下第4步）

选项A:Homebrew安装（建议用于macOS）

如果你有 家酿 安装后，这是最简单的方法：

# Add the tap (once)
brew tap deverman/focus-relay

# Install the MCP server and OmniFocus plugin
brew install focusrelay

然后继续 步骤2：安装OmniFocus插件 在......下面

选项B：手动二进制安装

如果你不想使用Homebrew，请下载一个预构建的二进制文件：

1. 从下载最新版本 发布 页
2. 将二进制文件提取到PATH中的某个位置（例如。， ~/bin/ 或 /usr/local/bin/)
3. 下载插件： FocusRelayBridge.omnijs 来自同一版本

然后继续 步骤2：安装OmniFocus插件 在......下面

选项C：开发人员安装（从源代码构建）

先决条件

• 安装了OmniFocus的macOS（建议使用4.x）
• Swift 6.2+工具链
• 这已经过测试 开源代码 但应与Claude Desktop或其他与MCP集成的工具配合使用

步骤1：克隆和构建

git clone 
cd FocusRelayMCP
swift build -c release

二进制文件将位于 .build/release/focusrelay （CLI+MCP服务器）。

然后继续 步骤2：安装OmniFocus插件 在......下面

步骤2：安装OmniFocus插件

Homebrew用户： 从Homebrew安装中复制插件：

cp -r $(brew --prefix focusrelay)/share/focusrelay/Plugin/FocusRelayBridge.omnijs \
  ~/Library/Containers/com.omnigroup.OmniFocus4/Data/Library/Application\ Support/Plug-Ins/

开发人员安装：

./scripts/install-plugin.sh

这将把FocusRelay Bridge插件安装到OmniFocus插件目录中。

⚠️ 重要提示：升级时，您必须重新安装插件！ 插件JavaScript经常更改，必须与二进制文件保持同步。

步骤3：配置MCP

添加到您的opencode.json或Claude Desktop配置中：

对于Homebrew安装（推荐）：

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

对于开发人员安装（从源代码构建）：

{
  "mcp": {
    "focusrelay": {
      "type": "local",
      "command": ["/path/to/FocusRelayMCP/.build/release/focusrelay", "serve"],
      "enabled": true
    }
  }
}

注： focusrelay 没有争论表示帮助；使用 focusrelay serve 以运行MCP服务器。

步骤4：重新启动OmniFocus

⚠️ 重要：安装或更新插件后，您 必须重新启动OmniFocus:

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

或者手动：完全退出OmniFocus并重新打开。

步骤5：首次设置（安全审批）

⚠️ 关键的：第一次查询OmniFocus时，将出现一个安全对话框：

1. 问你的人工智能助手：“我今天应该做什么？”（或任何OmniFocus查询）
2. OmniFocus将显示安全提示： “允许脚本控制OmniFocus吗？”
3. 点击“运行脚本” （不是“取消”）
4. 如果看不到提示，请检查OmniFocus是否位于其他窗口后面

如果你不批准会发生什么：

• 您将看到“Bridge超时”或“插件未响应”错误
• MCP服务器无法与OmniFocus通信
• 查询将自动失败或出现超时错误

要解决审批问题，请执行以下操作：

• 在OmniFocus中： 自动化→ 配置插件。..
• 在列表中找到“FocusSerelay桥”
• 检查它是否已启用，或尝试删除并重新安装它
• 重新启动OmniFocus并重试

安装后快速验证

完成步骤5后，验证端到端的安装路径：

focusrelay bridge-health-check
focusrelay list-tasks --fields id,name --limit 1

预期结果：

• bridge-health-check 报告 ok: true
• 第一 list-tasks 查询可能会触发OmniFocus审批提示
• 在批准之后， list-tasks 返回真实任务数据，而不是超时

命令行用法

这 focusrelay 二进制文件提供了MCP工具的命令行等效工具。 跑 focusrelay --help 查看完整的命令列表。

# List tasks with selected fields
focusrelay list-tasks --fields id,name,completionDate --completed true --completed-after 2026-02-10T00:00:00Z

# List projects with task counts
focusrelay list-projects --status active --include-task-counts

# List completed projects in last 30 days (sorted by completion date)
focusrelay list-projects --completed-after 2026-01-12T00:00:00Z --fields name,completionDate

# Fetch a single task by ID
focusrelay get-task  --fields id,name,note

# Check bridge health
focusrelay bridge-health-check

# List tasks with total count (shows returnedCount and totalCount)
focusrelay list-tasks --fields name --limit 10 --include-total-count

日期应为ISO8601（例如。 2026-02-04T12:00:00Z).

用法示例

日计划

• “我今天应该做什么？”
• “今天早上怎么样？”（早上6点-12点）
• “今天下午我能做什么？”（中午12点至下午6点）
• “今晚我应该做什么？”（下午6点-10点）

项目管理

• “哪些项目没有下一步行动？”
• “显示我停滞的项目”
• “我的Leave DFS项目中有哪些任务？”

上下文切换

• “我有哪些可用的上下文？”
• “显示我可以在Mac上执行的任务”
• “我需要打什么电话？”

任务发现

• “我一直在回避什么？”（任务延期>365天）
• “我在拖延什么？”（最近推迟的任务）
• “查找我标记的项目”

状态查询

• “我本周完成了什么？”（过去7天完成的任务）
• “我今天完成了哪些任务？”
• “在过去的30天里，我完成了哪些项目？”
• “我这个月完成了多少项目？”（不列出）
• “我的收件箱中有多少任务？”
• “显示已完成的任务”

完成视角对等

所有完成查询都与OmniFocus Completed透视图匹配：

• 包含：已完成的行动、行动组和项目
• 不包括：已删除项目（仅状态=已完成）
• 排序：按完成日期降序排列的结果（最近的先到）
• 时间窗口：使用completedAfter/completedBefore进行精确的日期筛选

可用工具

list_tasks

使用各种筛选器查询任务：

• dueBefore, dueAfter：按截止日期筛选
• plannedBefore, plannedAfter：按计划日期筛选
• deferBefore, deferAfter：按推迟日期筛选
• completedBefore, completedAfter：按完成日期筛选（意味着 completed: true)
• tags：按特定标签筛选
• project：按项目筛选
• flagged：仅显示标记的任务
• completed：显示已完成或剩余的任务
• inboxView：查看模式(available/remaining/everything).与...一起使用 inboxOnly: true 用于收件箱范围的查询。
• inboxOnly：仅对收件箱任务进行范围查询
• includeTotalCount：设置为 true 包括所有匹配任务的总数（请参阅下面的响应计数）
• 排序：按完成情况筛选时，结果会自动按以下方式排序 completionDate 降序（最近的一个）以匹配OmniFocus已完成透视图

您可以请求的有用任务日期字段：

• dueDate
• plannedDate
• deferDate
• completionDate

响应计数： 所有列表操作现在都包括自动计数以防止错误：

• returnedCount：始终包含-显示此回复中的实际项目
• totalCount：仅在以下情况下包含 includeTotalCount: true -显示匹配的项目总数

示例响应：

{
  "items": [...],
  "returnedCount": 10,
  "totalCount": 1784,
  "nextCursor": "10"
}

list_项目

查询具有状态和任务计数的项目：

• statusFilter：活动、暂停、放弃、完成、全部
• completed：按完成状态筛选（真/假）
• completedBefore, completedAfter：按完成日期窗口筛选（表示已完成的项目，不包括已删除的项目）
• includeTaskCounts：获取可用/剩余/已完成的任务计数
• completionDate：请求时字段可用
• 返回：hasChildren，isStalled，next项目健康状况任务
• 排序：按完成情况筛选时，结果会自动按以下方式排序 completionDate 降序（最近的一个）以匹配OmniFocus已完成透视图

list_tags

查询带有任务计数的标签：

• statusFilter：活动、保持、已删除、全部
• includeTaskCounts：获取每个标记的任务计数

get_task_counts

获取任何筛选器组合的聚合计数。支持完整的任务筛选，包括：

• 所有任务筛选器：已完成、已完成、后/前、标签、项目、仅可用等。
• 时间窗口计数：获取特定日期范围内已完成任务的计数（例如，“今天完成”、“过去30天完成”）
• 排序：按完成进行筛选时，应用与list_tasks相同的排序
• 演出：尽可能使用本机OmniFocus任务集合，以便在更大的数据库上进行更快/可靠的计数

示例：获取今天完成的任务计数，而不列出它们

get_project_counts

获取项目和行动的计数。支持完成日期过滤：

• 已完成项目计数：使用 completedAfter/completedBefore 在时间窗口内统计已完成的项目
• 退货: projects （已完成项目数）， actions （这些项目中已完成的任务计数）
• 排除项已删除：仅统计状态=已完成项目
• 用例：“我这个月完成了多少项目？”没有列出所有项目

示例：统计过去30天内完成的项目

时区处理

FocusRealyMCP会自动检测您的本地时区，并将其用于基于时间的查询。当你问：

• “今天早上我该做什么？”→ 返回上午6点至中午12点可用的任务 您的当地时间
• 今日到期任务→ 一天结束前应完成的任务 在您的时区

从macOS系统设置中检测时区，并将其传递给OmniFocus进行准确过滤。

演出

• 缓存查询：项目和标签缓存5分钟（重复查询速度更快）
• 单通道滤波：在一次迭代中应用所有过滤器（针对速度进行了优化）
• 提前退出：达到页面限制后停止处理
• 典型响应时间：约1秒（受OmniFocus IPC限制）
• 减少了API调用：使用 includeTotalCount: true 在一次通话中获取计数和列表，而不是两次通话

故障排除

“网桥超时”或“插件无响应”

这是最常见的问题。几个原因：

1. 缺少安全批准 （最常见）

- 解决方案：请参阅上述步骤5（首次设置）。您必须在OmniFocus安全对话框中单击“运行脚本”。

1. 插件需要重新安装

- 解决方案：运行 ./scripts/install-plugin.sh 再次，然后完全重新启动OmniFocus

1. 插件更新后OmniFocus未正确重启

- 解决方案：强制退出OmniFocus并重新打开它

1. 检查插件配置

- 在OmniFocus中： 自动化→ 配置插件。.. - 验证“FocusLelay Bridge”是否出现在列表中并已启用 - 如果您在此处看到错误，请删除插件并重新安装

“错误的时间段结果”

• 原因：旅行后可能需要刷新时区检测
• 解决方案：重新启动OmniFocus和opencode/Claude Desktop

“任务未出现”

• 检查任务是否设置了适当的延迟/到期日期
• 验证任务未标记为已完成或已删除
• 对于收件箱特定的结果，请使用 inboxOnly: true （例如： inboxOnly: true, inboxView: "available")

缓存问题

• 项目/标签缓存5分钟
• 任务查询永远不会被缓存（始终是新鲜的）
• 重新启动opencode/Claude以清除任何客户端缓存

发展

构建

swift build

测试

swift test

软件包插件

./scripts/package-plugin.sh

建筑

• Swift层：MCP服务器、请求处理、缓存
• OmniFocus插件（JavaScript）：在OmniFocus内执行，查询数据库
• IPCSwift与OmniFocus之间基于文件的通信
• 时区：在Swift中检测到，传递给插件进行本地时间计算

许可证

麻省理工学院

贡献

问题和PR欢迎！开发说明见AGENTS.md。