FocusRelayMCP

使用说明内容（Markdown格式）

• 项目简介

  • FocusRelayMCP 是一个在 macOS 上运行的 MCP（Model Context Protocol）服务器实现，专为 OmniFocus 设计。它通过一个核心服务器（用 Swift 实现的 MCP 服务）与一个 OmniFocus 插件桥接层进行通信，支持资源读取、工具调用、提示模板等 MCP 相关能力，并通过 JSON-RPC 风格的请求/响应与客户端交互。若与 AI 助手集成，将能够基于自然语言查询 OmniFocus 的任务、项目和标签等信息。

• 主要功能点

  • 资源管理与数据访问：提供对任务、项目、标签等数据的读取与过滤能力。
  • 工具注册与执行：支持注册和调用外部功能工具，扩展后端能力。
  • 提示模板渲染：定义并渲染用于与 LLM 交互的提示模板。
  • JSON-RPC 风格通信：通过标准化的请求格式接收指令，返回结构化的响应。
  • 多协议与本地集成：与 macOS 的 OmniFocus 插件桥接共同工作，支持本地化 IPC 机制。
  • 时区与时间处理：自动检测本地时区并在查询中应用，确保时间相关筛选的准确性。
  • 性能优化：单遍历过滤、结果缓存等提升查询性能。

• 安装步骤

  • 使用 Homebrew（推荐在 macOS 上安装）：
    • tap 仓库
    • 安装 MCP 服务器与 OmniFocus 插件
  • 手动安装（二进制+插件）
  • 开发者安装（从源码构建）：
    • 克隆仓库并执行 swift build -c release
    • 将 OmniFocus Bridge 插件安装脚本执行到 OmniFocus 插件目录
  • 配置 MCP 客户端：
    • 将 MCP 服务器的启动信息写入客户端配置，示例以本地执行为例： type: local command: ["/path/to/FocusRelayMCP/.build/release/focusrelay", "serve"] enabled: true
    • 注意：focusrelay 本身在首次运行时会提供帮助信息，实际启动请使用 serve 参数
  • 重启 OmniFocus
  • 第一次使用前的安全授权：
    • 启动 OmniFocus 后，向 AI 助手发起查询请求，系统会弹出安全对话框，选择“Run Script”以允许脚本对 OmniFocus 进行操作
  • 运行时命令提示
    • 服务器：focusrelay serve
    • 客户端（JSON 配置）将提供 serverName、command、args 等信息以建立连接

• 服务器配置（MCP 客户端需要的信息，JSON 格式，示例描述性信息） 服务器名称（serverName）：focusrelay 类型（type）：local 启动命令（command）：["/path/to/FocusRelayMCP/.build/release/focusrelay", "serve"] 启动参数（args）：无额外参数或与 command 一起传递 启用标志（enabled）：true

• 基本使用方法

  • 启动后，LLM 客户端通过 MCP 服务器进行数据查询，例如获取任务、项目、标签等信息，服务器返回结构化的 JSON 数据，便于后续对话处理与决策。
  • 常用查询包括：列出 inbox、列出任务、列出项目、获取任务、获取任务统计、获取项目统计、列出标签等。
  • 查询时请注意时区、完成状态、筛选条件等，以获得准确的结果。

• 运行与调试提示

  • 若遇到桥接或通信超时，请检查 OmniFocus 的安全设置，确保 FocusRelay Bridge 插件被允许运行和访问脚本。
  • 如需更新插件或二进制，请重新执行相应的安装与重启步骤。
  • 日志与调试信息通常会帮助定位权限、路径或数据结构相关的问题。

• 使用示例（简述）

  • 通过 LLM 提问自然语言问题，如“今天我应该做什么？”，MCP 服务器将基于 OmniFocus 数据返回符合条件的任务列表，便于 AI 助手给出行动建议。