Skip to main content
Glama
GlassyWorld

OmniFocus MCP Server

by GlassyWorld
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

OmniFocus-Agent-MCP v1.0-personalized

基于 upstream OmniFocus MCP v1.9.2 构建的个人管理语义层，用于向 GPT 和其他 MCP 客户端提供稳定、只读优先的 OmniFocus Domain View，以及两个受控的 request-scoped mutation。

Release status: v1.0-personalized — current frozen personalized architecture

Current production surface

当前生产代码基线在 V4 create_task 之上已完成 S5B：personal-production 注册五个 read Tools（get_task、get_project、get_completed_since、get_lean_snapshot、 search_tags）和两个受控 mutation（create_task、create_project_skeleton），不注册 Resources 或 Prompts。

create_task 是仅在用户明确请求时调用的 request-scoped assisted mutation；它不是由 AI 分析、建议、计划或推断出的未来意图触发的自动写入。它支持 Inbox、exact Active Project、fresh exact eligible ordinary Action Group，以及可选的既有 Active Tag canonical IDs。严格 schema、canonical identity、无 fuzzy/fallback、feature gates、Ledger、lock、 exact readback 与保守错误语义都是 V4 的生产不变量。

create_project_skeleton 是另一条独立的 request-scoped assisted mutation：只在已有、符合资格的 Folder 下创建固定 Project + 1–5 个 Action Groups（每组一个 starter），总对象数上限为 11。 它不是 Folder 创建器、create_tasks、任意 Project tree 或 generic CRUD。完整 AI 调用合同见 docs/integration/CREATE_PROJECT_SKELETON_AI_CALL_GUIDE.md。

Tree V5、Project P2/P3 和 P5 Canary 不属于当前生产能力。它们的本地实验历史与重新开启 条件见 docs/history/TREE_V5_EXPERIMENT_ARCHIVE.md。

Related MCP server: OmniFocus MCP Server

1. Overview

本项目最初提供 OmniFocus 数据访问、通用查询和对象操作能力。个人化版本在该基础上增加了明确的 Domain Semantic Layer，使 AI 不必直接解释 OmniFocus Raw Object、继承日期或 Project root 的底层表示。

当前架构目标是：

OmniFocus
    ↓
Domain Semantic Model
    ↓
MCP Tools
    ↓
AI Analysis

该版本的目标不是让 AI 自动管理任务，也不是让模型替用户做出执行决策，而是提供可验证、来源明确、结构稳定的事实视图，辅助用户分析个人执行系统。

核心原则：

  • 默认只读：个性化工作流以读取和分析为默认模式。

  • 事实先于解释：Domain 层表达 OmniFocus facts，不生成健康度、风险、优先级或行动建议。

  • AI 负责分析：AI 可以归纳、比较和识别模式，但不自动修改 OmniFocus。

  • 用户最终决策：任何确认、调整和执行都由用户本人控制。

Version identity

项目

当前值

个性化版本

v1.0-personalized

Upstream 基础版本

v1.9.2

MCP transport

stdio

运行平台

macOS + OmniFocus

个性化 read models 基线

get_task、get_project、get_completed_since、get_lean_snapshot

v1.0-personalized 是个性化语义层的 release label；npm/package 基础版本仍保留 upstream 1.9.2。

2. v1.0-personalized Release Notes

v1.0-personalized 是当前已冻结的个人化架构基线。后续评审和演进应以本版本已经建立的 Domain Contract 和语义规则为起点。

Completed

Task Domain

  • 严格的 Raw Task Adapter。

  • 稳定的 TaskView。

  • action、action_group、project_root 三种 TaskKind。

  • Due、Planned、Defer 的 direct/effective/source 表达。

  • Completion、Drop、Flag 的 direct/inherited/none 表达。

Project Domain

  • 严格的 Raw Project Adapter。

  • 稳定的 ProjectView。

  • canonical Project ID。

  • standard 与 single-actions Project 分类。

  • Folder、状态、Task aggregate 和日期语义。

Completion Domain

  • 稳定的 CompletedTaskView。

  • 基于 direct completionDate 的完成事件流。

  • 明确排除 Project root completion event。

  • 支持 Action 与 Action Group completion。

Lean Snapshot Domain

  • 稳定的 LeanSnapshotView。

  • Active Projects、Planned Projects、Project Deadlines、Attention 和 Inbox sections。

  • Project 与 root Task 的 canonical join。

  • 完整计数、确定性排序和独立截断。

Planned Attention Semantics

  • Direct Planned owner 产生 Planned visibility。

  • inherited Planned facts 被保留，但不会生成重复 Attention。

  • Project-level Planned owner 进入独立的 projects.planned section。

Due Attention Semantics

  • Direct Due owner 产生 deadline signal。

  • inherited Due facts 被保留，但不会生成重复 dueSoon 或 overdue Attention。

  • Project-level Due owner 进入独立的 projects.deadline section。

MCP read tools（个性化基线）

  • get_task

  • get_project

  • get_completed_since

  • get_lean_snapshot

这四个 Tool 返回稳定 Domain JSON，而不是把通用查询结果直接暴露给 AI。当前生产还在 此基线上增加了只读 search_tags；完整 current surface 以本文开头和 src/serverRegistration.test.ts 为准。

Frozen Design Principles

Domain-first architecture

个性化功能首先定义 Domain Contract，再定义 Tool 输出。MCP handler 不承担核心业务语义。

Raw Query
    -> Strict Adapter
    -> Domain Semantics
    -> Mapper / Composer
    -> MCP Response

Semantic projection

Domain View 是对 OmniFocus facts 的明确投影，而不是 Raw Object dump。字段被固定选择、验证和解释，内部 Raw contract 不直接公开。

Direct ownership of management signals

Planned 和 Due 信号按 direct owner 粒度表达。容器继承产生的 effective value 是事实，但不是新的管理信号 owner。

Separation of fact and interpretation

Domain 层负责表达：

  • 对象是什么。

  • 值来自对象自身还是容器继承。

  • 当前 OmniFocus native status 是什么。

  • 对象之间的结构关系是什么。

Domain 层不负责表达：

  • 应该先做什么。

  • Project 是否健康。

  • 哪个对象风险最高。

  • 用户应该采取什么行动。

这些解释属于 AI Analysis 和用户决策层。

3. Architecture Overview

flowchart TD
    RAW["OmniFocus Raw Data<br/>Tasks / Projects / Folders"]
    BRIDGE["Primitive and Bridge Layer<br/>queryOmnifocus + JXA + osascript"]
    ADAPTERS["Strict Adapters<br/>Raw contract validation"]

    TASK["Task Domain<br/>TaskView"]
    PROJECT["Project Domain<br/>ProjectView"]
    COMPLETION["Completion Domain<br/>CompletedTaskView"]
    SNAPSHOT["Snapshot Domain<br/>LeanSnapshotView"]

    TOOLS["Personalized MCP Read Tools<br/>get_task / get_project<br/>get_completed_since / get_lean_snapshot"]
    AI["AI Analysis<br/>comparison, review, pattern recognition"]
    USER["User Decision<br/>final confirmation and execution"]

    RAW -->|读取原始事实| BRIDGE
    BRIDGE -->|固定字段映射| ADAPTERS

    ADAPTERS --> TASK
    ADAPTERS --> PROJECT
    ADAPTERS --> COMPLETION
    ADAPTERS --> SNAPSHOT

    TASK --> TOOLS
    PROJECT --> TOOLS
    COMPLETION --> TOOLS
    SNAPSHOT --> TOOLS

    TOOLS -->|稳定 Domain JSON| AI
    AI -->|分析结果，不自动写入| USER

主要实现路径：

src/tools/primitives/queryOmnifocus.ts
    ↓
src/domain/{task,project,completion,snapshot}/
    ↓
src/tools/primitives/get*.ts
    ↓
src/tools/definitions/get*.ts
    ↓
src/server.ts

Layer responsibilities

Layer

职责

OmniFocus Raw Data

提供 Task、Project、Folder、日期、状态和层级的原始事实

Primitive / Bridge

生成并执行只读 OmniJS 查询，映射固定字段和 canonical ID

Adapter

严格校验 Raw item；不静默修复 malformed values

Domain

分类、保留来源语义并构建稳定 View

Snapshot Composer

跨 Task/Project 组合当前系统状态

MCP Tool

参数校验、稳定响应和错误分类

AI Analysis

基于事实进行解释，不承担事实生成和自动写入

4. Domain Model

Task Domain

Task Domain 位于 src/domain/task/，对外读模型是 TaskView。

TaskView 包含：

  • identity：id、name、note

  • TaskKind

  • native Task status

  • completion、drop、flag semantics

  • Due、Planned、Defer semantics

  • Project context 与 Inbox location

  • hierarchy、tags、repeat、estimate 和 timestamps

TaskKind

type TaskKind = "action" | "action_group" | "project_root";

分类规则：

isProjectRoot = true  -> project_root
否则 hasChildren      -> action_group
否则                  -> action

  • action：没有 children 的普通执行项。

  • action_group：有 children、但不是 Project root 的 Task。

  • project_root：OmniFocus Project 的 root Task 表示。

Action 当前属于 Task Domain，不是独立 Domain。当前代码没有独立 ActionView、Action aggregate 或 get_action Tool。

Project Domain

Project Domain 位于 src/domain/project/，对外读模型是 ProjectView。

ProjectView 包含：

  • canonical Project identity

  • Project kind：standard | single_actions

  • Active、OnHold、Done、Dropped 状态语义

  • Folder context

  • direct/effective Due 和 Defer

  • direct Task IDs、全部 descendant Task IDs 和 native-status counts

  • timestamps

Project Root semantics

OmniJS Project ID 与 Project root Task ID 属于不同 namespace。个性化 Domain 对外统一使用：

canonical Project ID = project.task.id.primaryKey

因此同一个 canonical ID 可以从两个互补视角读取：

get_project(projectId)
    -> Project aggregate、Folder、Project status、Task summary

get_task(projectId)
    -> 对应 project_root Task 的 Task facts

Snapshot 使用 canonical ID 将 RawLeanProject 与 isProjectRoot = true 的 RawLeanTask 精确连接。Project 是管理聚合；root Task 是它在 OmniFocus Task 模型中的表示。两者不是重复接口。

Completion Domain

Completion Domain 位于 src/domain/completion/，对外读模型是 CompletedTaskView。

CompletedTaskView 表达一次直接完成事件：

  • Action 或 Action Group identity

  • direct completedDate

  • Project/Inbox context

  • tags

  • created/modified timestamps

get_completed_since 读取 direct completionDate 位于指定闭区间内的完成事件，并按完成时间降序返回。

它不会通过以下值推导历史完成：

  • taskStatus

  • modificationDate

  • effectiveCompletedDate

Project root completion event 被排除，Action Group completion 被保留。Completion Domain 是未来 Review Workflow、完成回顾和趋势分析的事实基础，但当前不自动生成 Review 结论。

Snapshot Domain

Snapshot Domain 位于 src/domain/snapshot/，对外读模型是 LeanSnapshotView。

LeanSnapshotView
├── generatedAt
├── scope = all
├── projects
│   ├── active
│   ├── planned
│   └── deadline
├── attention
└── inbox

每个 list section 均提供：

total
returned
truncated
items

Lean Snapshot 不是完整数据库导出。它只读取当前 remaining Tasks 和 Active Projects，并输出当前管理视角需要的 compact facts：

  • 不读取 note 全文，只输出 hasNote。

  • 不包含完成历史；完成历史由 Completion Domain 提供。

  • 不包含 Waiting、health、risk、priority 或 recommendation。

  • 不展开所有 Project Task details，只保留 Task counts 和 native-status aggregate。

  • Project root 在内部用于语义解析，但不进入 Task Attention 或 Inbox。

它也不是普通查询接口。Snapshot Composer 会执行 Project/root join、ownership classification、完整计数、稳定排序和独立截断，从而形成一次性的系统级 current-state read model。

5. Semantic Rules

Direct, effective, and source

Domain 日期语义统一表达为：

{
  direct: string | null;
  effective: string | null;
  source: "direct" | "inherited" | "none";
}

  • direct：值直接设置在当前对象上。

  • effective：OmniFocus 计算后的实际生效值，可能来自当前对象或上层容器。

  • source = direct：当前对象直接拥有该值。

  • source = inherited：当前对象只有从容器继承的 effective value。

  • source = none：不存在对应事实。

该区分用于保留事实，同时防止把 inherited value 当作新的管理信号。

Planned Attention

冻结规则：

Direct Planned owner produces Planned visibility.

对于 Action 和 Action Group，planned Attention 需要：

planned.source = direct
AND planned.direct <= generatedAt
AND taskStatus != Blocked

对于 Active Project，root Task 的 direct Planned 已到达时，Project 进入 projects.planned。

Inherited Planned values：

  • 继续保留在 Domain dates 中。

  • 不产生独立 planned Attention。

  • 不把一个 Project-level workflow 展开为多个重复 child signals。

Due Attention

冻结规则：

Direct Due owner produces deadline signal.

对于 Action 和 Action Group：

due.source = direct
AND native taskStatus = DueSoon | Overdue

对于 Active Project，root Task 直接拥有 Due 且 native status 为 DueSoon 或 Overdue 时，Project 进入 projects.deadline。

Inherited Due values：

  • 继续保留在 Domain dates 中。

  • 不产生独立 dueSoon 或 overdue Attention。

  • 不因为多个 descendants 继承相同 Due 而产生重复 deadline signals。

系统使用 OmniFocus native taskStatus 判断 DueSoon/Overdue，不定义自有 DueSoon 时间窗口。

Attention aggregation

Attention reasons 的固定顺序为：

overdue -> dueSoon -> planned -> flagged

同一 Task 最多出现一次，但可以同时携带多个 reasons。Inbox 和 Attention 是独立 section，因此同一 Task 可以出现在两者中。

6. Current MCP Tools

本节描述当前生产的五个 read tools。它们不是简单数据查询，而是面向 AI 分析的领域投影。

get_task

按 exact Task ID 或区分大小写的 exact name 读取单个 TaskView。

主要用途：

  • 区分 action、action_group 和 project_root。

  • 检查 direct/effective 日期来源。

  • 检查 completion、drop 和 flag provenance。

  • 获取 Project context、Inbox location 和 hierarchy。

它查询 OmniFocus Task 实体，但返回的是稳定 Task Domain View，而不是通用 Task query result。

get_project

按 canonical Project ID 或区分大小写的 exact name 读取单个 ProjectView。

主要用途：

  • 获取 Project status、kind 和 Folder context。

  • 查看 direct/all Task relationships 和 native-status counts。

  • 查看 Project Due/Defer provenance。

  • 使用统一 canonical ID 连接 Project 和 root Task 视角。

它表达 Project aggregate，不替代选择性 get_task 读取。

get_completed_since

读取 { since, until? } 闭区间内的 direct completion events。

主要用途：

  • 完成回顾。

  • Review Workflow 的事实输入。

  • 后续趋势或节奏分析。

since 和 until 必须是带 Z 或明确 UTC offset 的完整 ISO 8601 datetime；until 缺省为调用时刻。空结果是正常成功。

get_lean_snapshot

读取当前全系统的 compact LeanSnapshotView。

主要用途：

  • 查看全部 Active Projects 的摘要。

  • 查看已经到达的 direct Planned Project owners。

  • 查看 Project-level direct deadline owners。

  • 查看 Task-level Attention reasons。

  • 查看 Inbox 当前状态。

可选 limitPerSection 独立限制各 section，默认 25，允许 1..100。每个 section 在截断前计算完整 total。

search_tags

对既有 OmniFocus Tag 执行结构化只读发现，默认只返回 Active。输出包含 canonical ID、exact native status、完整 root-to-self path、children 与 mutual-exclusion facts；同名 Tag 必须按 完整 path 消歧。该 Tool 不创建或修改 Tag，结果也不是长期 mutation token；tagged creation 必须 在本次明确意图中以完整 path 确认候选，并只向 create_task 提交 canonical IDs。

Upstream compatibility surface

仓库仍保留 upstream v1.9.2 的通用查询、Resource、Perspective、Tag 和 mutation tools。 它们只在显式选择 upstream-full 时由 src/serverRegistration.ts 注册，不属于 v1.0-personalized Domain Contract，也不进入默认 personal-production surface。

因此，仓库保留写入实现不等于默认实例可写；当前边界由 Server-side Profile registration 强制，而不是客户端 allowlist。personal-production 当前公开五个 read tools（含 search_tags）和 两个受控 mutation（create_task、create_project_skeleton），且无 Resources/Prompts；upstream-full 只能显式启用。

7. Current Design Boundaries

v1.0-personalized 当前不包含以下能力。

Full Snapshot MCP

当前只有 Lean Snapshot。仓库中的 dump_database 是 upstream raw/full report 能力，不是一个经过稳定 Domain 建模的 Full Snapshot MCP。

Action independent Domain

Action 与 Action Group 当前属于 Task Domain，通过 TaskKind 表达。不存在独立 Action Domain、ActionView 或 get_action。

AI automatic decision making

Domain Tool 不判断优先级、风险、健康度或“下一步应该做什么”。AI 分析结果不等于系统决策。

OmniFocus write automation

自动写入不是个性化架构的一部分。当前个性化 workflow 不会根据 Snapshot 或 AI 分析自动创建、编辑、完成或删除 OmniFocus 对象；create_task V4 仅响应用户新的、明确的单个 Task 创建请求；create_project_skeleton 仅响应用户明确确认的固定 Project Skeleton 创建请求。两者都绝不按名称解析、自动创建 Tag/Folder，或在目标不明确时 fallback。

Upstream mutation tools 仍存在于仓库中，但不属于个性化默认操作路径。

这些边界是当前冻结范围，不代表对应方向已经确定实现。

8. Future Roadmap

Future Phase

未来评审可能考虑：

  • Full Snapshot：在明确 Contract 和体积边界后，提供比 Lean Snapshot 更完整的 Domain read model。

  • AI Review Workflow：组合 Snapshot 和 Completion facts，支持结构化回顾流程。

  • Better semantic analysis：在不污染事实层的前提下，增强对执行系统模式的分析。

未来演进应继续保持：

  • Raw facts 与解释分离。

  • direct ownership 语义稳定。

  • 写入行为不由分析结果自动触发。

  • 新概念先定义 Domain boundary，再决定是否增加 MCP Tool。

9. Safety Model

Default personal production profile

personal-production 是面向日常 ChatGPT App 的精选生产能力集合。当前精确接口为：

get_task
get_project
get_completed_since
get_lean_snapshot
search_tags
create_task
create_project_skeleton

前五个是稳定 read tools；后两个是分别受 feature gate、显式授权、幂等、锁和 verification 保护的 mutation。该 Profile 不注册 Resources 或 Prompts。Skeleton 的完整调用规范见 docs/integration/CREATE_PROJECT_SKELETON_AI_CALL_GUIDE.md。

No automatic OmniFocus mutation

Snapshot、Attention 和 Completion 结果只作为分析输入，不会自动触发 OmniFocus 写入。AI 不应根据分析结果自行调用创建、编辑、完成、移动或删除操作。

User retains final control

系统责任边界是：

OmniFocus 提供事实
    ↓
Domain Layer 解释事实来源和结构
    ↓
AI 分析事实
    ↓
用户确认、决策并执行

用户始终保持最终控制权。

Deployment profiles

ChatGPT Developer App、ChatGPT Web / iPhone 和 Secure MCP Tunnel 当前使用：

OMNIFOCUS_MCP_PROFILE=personal-production

该 Profile 当前在 Server capability registration 层只公开 get_lean_snapshot、 get_project、get_task、get_completed_since、search_tags、create_task 和 create_project_skeleton，不注册 generic read tools、 其他 mutation tools 或 MCP Resources。因此当前能力边界不依赖客户端 Tool allowlist。 create_task V4 和 create_project_skeleton 只允许各自合同定义的 request-scoped creation；不能从 Profile 名称或任一 Tool 推断、自动获得任何其他写入能力。当前代码的 global、Project、Parent、Tag、Skeleton gates 均为 fail-closed；任何实际 loaded flag 或 Tunnel 状态属于运行时事实，必须单独实时检查，不能由本文断言。Tag creation 仍必须使用 fresh search_tags canonical IDs，并通过写前 Active ancestor、去重和互斥验证。

T2-D tagged Inbox 与 tagged Project Canary 均已通过一次性隔离进程完成单次创建、服务器侧 exact ID-set/placement 验证、用户人工确认/删除与 ID/name 双 not_found；Project 计数恢复到 创建前值，Tag projection、Ledger/audit/lock 终检通过。公开 Tunnel 在 T2-D 期间始终保持 Tag flag=false；T2-E 随后按 fail-closed reload 正式启用，配置过程零 mutation。

环境变量未设置或为空时安全默认进入 personal-production。upstream-full 只能通过 OMNIFOCUS_MCP_PROFILE=upstream-full 显式启用；完整模式继续注册仓库现有的全部 Tool 和 Resources，包括 mutation tools，不作为日常 ChatGPT App 默认 Profile。任何其他 Profile 值（包括旧的 personal-readonly）都会在 Server connect 前导致启动失败，并列出允许值。

Maintenance Reference

当前 Domain 设计与冻结语义主要位于：

src/domain/task/
src/domain/project/
src/domain/completion/
src/domain/snapshot/

engineer_log/GET_TASK_ENGINEERING_LOG.md
engineer_log/GET_PROJECT_ENGINEERING_LOG.md
engineer_log/GET_COMPLETED_SINCE_ENGINEERING_LOG.md
engineer_log/GET_LEAN_SNAPSHOT_ENGINEERING_LOG.md
engineer_log/GET_LEAN_SNAPSHOT_PLANNED_CORRECTION_ENGINEERING_LOG.md
engineer_log/GET_LEAN_SNAPSHOT_DUE_ATTENTION_GRANULARITY_ENGINEERING_LOG.md

后续维护者和 AI Agent 应优先以类型定义、Domain tests 和工程日志中的冻结规则判断当前行为，不应从通用 Tool 文案推断 Domain semantics。

License

MIT

Available Tools

6 tools
create_taskA
Idempotent

Create exactly one new OmniFocus task after an explicit user request. destination is required: Inbox, one exact Active Project canonical ID from a fresh get_project read, or one exact existing ordinary Action Group canonical ID from a fresh get_task read. Parent names, paths, leaf Actions, and Project roots are never accepted as Parent destinations. Optional tagIds accepts 1-5 unique canonical IDs of existing Active Tags selected from fresh search_tags results; names and paths are never mutation identifiers, all requested Tags and ancestors are revalidated immediately before creation, and this Tool never creates Tags. Immediately before a Project, Parent, or tagged call, restate the available target context and every full Tag path so the user can associate each canonical ID with the pending mutation; if any target is not distinguishable, do not call. Generate a fresh UUID idempotencyKey per new creation intent and reuse it only for a transparent retry. This server may return write_disabled without touching OmniFocus. Repeats, notifications, batches, edits, moves, reparenting, completion, deletion, fallback to Inbox/Project, silent Tag omission, and automatic Tag creation are unsupported.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
noteNo
tagIdsNo1-5 unique canonical IDs of existing OmniFocus Tags; names, paths, and automatic Tag creation are not accepted.
dueDateNo
flaggedNo
deferDateNo
destinationYes
plannedDateNo
idempotencyKeyYes
estimatedMinutesNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
createdYes
successYes
warningsYes
idempotencyYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations set idempotentHint=true and destructiveHint=false; the description elaborates on idempotency key reuse, potential write_disabled error, and revalidation. No contradictions. Adds context about server behavior exceeding annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively long but efficient; each sentence adds value. The first sentence immediately states the purpose. Could be slightly tighter but appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 10 parameters, 3 required, and an output schema, the description covers purpose, preconditions, destination rules, unsupported features, and error behavior. It is complete for an agent to correctly select and invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is low (10%), but the description compensates by thoroughly explaining the complex destination parameter, tagIds constraints, and idempotencyKey usage. Other params like note, flagged are not described, but the most critical ones are well covered.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Create' and the resource 'OmniFocus task' with the qualifier 'after an explicit user request'. It distinguishes from sibling tools which are all read-only or search operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use (explicit user request), what destinations are valid (inbox, project ID, action group ID), what is not accepted (names, paths), prerequisites (fresh reads), and unsupported operations. Even instructs the agent to restate context before calling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_completed_sinceB

Read-only. Return directly completed OmniFocus actions and action groups within an inclusive absolute time range. Project root completion events are excluded.

ParametersJSON Schema
NameRequiredDescriptionDefault
sinceNoRequired ISO 8601 datetime with Z or explicit UTC offset. The inclusive lower completion time bound.
untilNoOptional ISO 8601 datetime with Z or explicit UTC offset. Defaults to the current time and is inclusive.

Output Schema

ParametersJSON Schema
NameRequiredDescription
successYes
completedYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It declares 'Read-only' and mentions an exclusion, but does not disclose other behavioral traits such as pagination, ordering, rate limits, or authorization requirements. For a read-only tool, this is minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, consisting of two sentences with zero fluff. It is front-loaded with the core purpose and exclusions, making it efficient for an AI agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (two parameters, output schema exists), the description covers the essential aspects: what is returned, the time range inclusivity, and the exclusion. It does not specify sorting or limits, but the output schema likely covers return structure. Overall, it provides sufficient context for basic usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides descriptions for both parameters (100% coverage). The description adds value by specifying the time range inclusivity and indicating that 'since' is required (though not marked in schema). This clarifies parameter semantics beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Return' and the resource 'directly completed OmniFocus actions and action groups'. It also specifies the exclusion of project root completion events. However, it does not explicitly differentiate from sibling tools, but the tool name and context make it distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus siblings. It neither states explicit contexts for use nor mentions alternatives, leaving the agent to infer usage solely from the tool name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_lean_snapshotA

Read-only. Return a capped all-system current-state OmniFocus snapshot containing active project summaries, factual attention signals, and Inbox task summaries. Waiting, recent completion history, health, risk, priority, and recommendations are not inferred.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitPerSectionNoMaximum items returned independently for active projects, planned projects, project deadlines, attention, and Inbox. Integer from 1 through 100. Defaults to 25.

Output Schema

ParametersJSON Schema
NameRequiredDescription
successYes
snapshotYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. It explicitly declares read-only nature, capped output, and specifically lists what is NOT inferred (waiting, completion, health, etc.). Provides clear behavioral expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: two sentences, front-loaded with 'Read-only', no wasted words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (capped snapshot with multiple sections) and presence of output schema, description adequately explains what is returned and what is omitted. Complete for its purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with description for the single parameter (limitPerSection). Description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it returns a capped all-system OmniFocus snapshot with specific content (active projects, attention signals, Inbox tasks) and explicitly lists what is not inferred. Distinguishes from sibling tools like get_project or get_task by focusing on aggregate snapshot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides context that it is read-only and gives a high-level overview, but does not explicitly state when to use this tool versus alternatives (e.g., get_project for details). No direct comparison or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_projectA

Read-only. Get one exact OmniFocus project by canonical ID or exact name.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoExact canonical OmniFocus project root task ID. Provide either id or name, not both.
nameNoExact OmniFocus project name. Case-sensitive. Provide either name or id, not both.

Output Schema

ParametersJSON Schema
NameRequiredDescription
projectYes
successYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden but only states read-only and exact match. Lacks details on error behavior for missing projects or invalid inputs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence packs key info: read-only, verb, resource, identification methods. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values need not be described. Covering tool purpose, identification methods, and read-only property is sufficient for this simple retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. Description adds value by stating read-only and exact retrieval, reinforcing mutex constraint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get one exact OmniFocus project by canonical ID or exact name' with specific verb and resource. It distinguishes from siblings like get_task (task vs project) and search_tags (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Provide either id or name, not both' and labels tool as 'Read-only'. Could mention when not to use (e.g., for tasks) but effectively guides usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_taskA

Read-only. Get one exact OmniFocus task by ID or exact name.

ParametersJSON Schema
NameRequiredDescriptionDefault
idNoExact OmniFocus task ID. Provide either id or name, not both.
nameNoExact OmniFocus task name. Case-sensitive. Provide either name or id, not both.

Output Schema

ParametersJSON Schema
NameRequiredDescription
taskYes
successYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; the description compensates by stating 'Read-only' and specifying exact matching. It does not cover error cases or rate limits, but the behavior is sufficiently transparent for a straightforward retrieval tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It front-loads the read-only nature and task scope.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity, full schema coverage, and an output schema, the description is complete enough. It could mention what happens if not found, but is adequate for its purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds little beyond the schema. It reiterates 'exact name' and 'case-sensitive' already present in the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool is read-only and retrieves one exact task by ID or exact name, which clearly distinguishes it from sibling tools like create_task and search_tags.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for exact retrieval, but lacks explicit guidance on when to choose this tool over alternatives like search_tags or get_lean_snapshot. However, the context is clear for a simple getter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_tagsA

Read-only. Search existing OmniFocus Tags with canonical IDs, exact native status, full hierarchy paths, and mutual-exclusion facts. Defaults to Active Tags. Use full paths to distinguish same-name Tags. Results are discovery facts, not write authorization, and this Tool never creates Tags.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryNo
statusNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
pageYes
tagsYes
successYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It declares read-only, defaults to Active Tags, and clarifies it never creates tags. It explains what the search covers (IDs, status, paths, mutual-exclusion). Missing details on rate limits or pagination, but output schema covers return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with 'Read-only,' and contains no extraneous words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given three parameters and an output schema, the description covers core purpose, read-only nature, default behavior, and nuance about full paths. It lacks explicit parameter descriptions for 'limit', but the output schema handles return values. Moderately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It mentions 'Use full paths' (relates to query) and 'Defaults to Active Tags' (relates to status). However, it doesn't explain the 'limit' parameter or how to construct queries, leaving gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches OmniFocus Tags with specific details (canonical IDs, hierarchy paths, etc.). It distinguishes itself from sibling tools which deal with tasks and projects, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes the tool is read-only and never creates tags, implying when to use it. It advises using full paths for same-name tags, but lacks explicit 'when not to use' guidance. Given sibling tools are for different entities, context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.9.2
    • First observedcreate_task
    • First observedget_completed_since
    • First observedget_lean_snapshot
    • First observedget_project
    • First observedget_task
    • First observedsearch_tags
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: create_task is the only mutation, while read-only tools cover specific retrievals (projects, tasks, tags, completed items) and a broad snapshot. No overlaps exist.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., create_task, get_project). The naming is predictable and well-structured.

Tool Count5/5

With 6 tools covering creation and various read operations, the count is well-scoped for an OmniFocus integration. Each tool earns its place and the set feels neither sparse nor bloated.

Completeness2/5

The tool surface misses critical CRUD operations like update, delete, and complete tasks. The descriptions explicitly unsupport many common actions, leaving significant gaps for a task management server.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers