@scardis/omnifocus-mcp 0.1.0

package/dist/tools/moveTask.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { MoveTaskInput, TaskSummary } from "../schemas/index.js";
+export type MoveTaskInputType = z.infer<typeof MoveTaskInput>;
+export declare function moveTaskHandler(input: MoveTaskInputType): Promise<z.infer<typeof TaskSummary>>;
+export declare const moveTaskTool: {
+    readonly name: "move_task";
+    readonly description: "Move a task to a different project (making it a top-level task) or make it a subtask of another task. Exactly one of projectId or parentTaskId must be provided. Throws a not-found error if any ID does not exist.";
+    readonly inputSchema: z.ZodEffects<z.ZodObject<{
+        id: z.ZodString;
+        projectId: z.ZodOptional<z.ZodString>;
+        parentTaskId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        parentTaskId?: string | undefined;
+        projectId?: string | undefined;
+    }, {
+        id: string;
+        parentTaskId?: string | undefined;
+        projectId?: string | undefined;
+    }>, {
+        id: string;
+        parentTaskId?: string | undefined;
+        projectId?: string | undefined;
+    }, {
+        id: string;
+        parentTaskId?: string | undefined;
+        projectId?: string | undefined;
+    }>;
+    readonly handler: typeof moveTaskHandler;
+};
+//# sourceMappingURL=moveTask.d.ts.map

package/dist/tools/moveTask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moveTask.d.ts","sourceRoot":"","sources":["../../src/tools/moveTask.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE9D,wBAAsB,eAAe,CACnC,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC,CAGtC;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;CAMf,CAAC"}

package/dist/tools/moveTask.js

@@ -0,0 +1,13 @@
+import { runSnippet } from "../runtime/index.js";
+import { MoveTaskInput, TaskSummary } from "../schemas/index.js";
+export async function moveTaskHandler(input) {
+    const raw = await runSnippet("move_task", input);
+    return TaskSummary.parse(raw);
+}
+export const moveTaskTool = {
+    name: "move_task",
+    description: "Move a task to a different project (making it a top-level task) or make it a subtask of another task. Exactly one of projectId or parentTaskId must be provided. Throws a not-found error if any ID does not exist.",
+    inputSchema: MoveTaskInput,
+    handler: moveTaskHandler,
+};
+//# sourceMappingURL=moveTask.js.map

package/dist/tools/moveTask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moveTask.js","sourceRoot":"","sources":["../../src/tools/moveTask.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIjE,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAwB;IAExB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;IACjD,OAAO,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,WAAW;IACjB,WAAW,EACT,qNAAqN;IACvN,WAAW,EAAE,aAAa;IAC1B,OAAO,EAAE,eAAe;CAChB,CAAC"}

package/dist/tools/resolveName.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { ResolveCandidate } from "../schemas/index.js";
+export declare const resolveNameSchema: z.ZodObject<{
+    type: z.ZodEnum<["task", "project", "folder", "tag", "perspective"]>;
+    query: z.ZodString;
+    scope: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "task" | "project" | "folder" | "tag" | "perspective";
+    query: string;
+    scope?: string | undefined;
+}, {
+    type: "task" | "project" | "folder" | "tag" | "perspective";
+    query: string;
+    scope?: string | undefined;
+}>;
+export type ResolveNameInput = z.infer<typeof resolveNameSchema>;
+export declare function resolveNameHandler(input: ResolveNameInput): Promise<z.infer<typeof ResolveCandidate>[]>;
+export declare const resolveNameTool: {
+    readonly name: "resolve_name";
+    readonly description: "Resolve an entity name to its stable ID(s). Returns ALL matches — never silently picks one. If multiple candidates are returned, ask the user or caller to disambiguate using the path field before proceeding with a write operation.";
+    readonly inputSchema: z.ZodObject<{
+        type: z.ZodEnum<["task", "project", "folder", "tag", "perspective"]>;
+        query: z.ZodString;
+        scope: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "task" | "project" | "folder" | "tag" | "perspective";
+        query: string;
+        scope?: string | undefined;
+    }, {
+        type: "task" | "project" | "folder" | "tag" | "perspective";
+        query: string;
+        scope?: string | undefined;
+    }>;
+    readonly handler: typeof resolveNameHandler;
+};
+//# sourceMappingURL=resolveName.d.ts.map

package/dist/tools/resolveName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveName.d.ts","sourceRoot":"","sources":["../../src/tools/resolveName.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAc,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAW5B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEjE,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,EAAE,CAAC,CAO7C;AAED,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;CAMlB,CAAC"}

package/dist/tools/resolveName.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import { runSnippet } from "../runtime/index.js";
+import { EntityType, ResolveCandidate } from "../schemas/index.js";
+export const resolveNameSchema = z.object({
+    type: EntityType.describe("The entity type to search: task, project, folder, tag, or perspective"),
+    query: z.string().min(1).describe("Exact name to search for"),
+    scope: z
+        .string()
+        .optional()
+        .describe('Optional path prefix to narrow results, e.g. "Work ▸ Clients"'),
+});
+export async function resolveNameHandler(input) {
+    const raw = await runSnippet("resolve_name", {
+        type: input.type,
+        query: input.query,
+        scope: input.scope ?? null,
+    });
+    return z.array(ResolveCandidate).parse(raw);
+}
+export const resolveNameTool = {
+    name: "resolve_name",
+    description: "Resolve an entity name to its stable ID(s). Returns ALL matches — never silently picks one. If multiple candidates are returned, ask the user or caller to disambiguate using the path field before proceeding with a write operation.",
+    inputSchema: resolveNameSchema,
+    handler: resolveNameHandler,
+};
+//# sourceMappingURL=resolveName.js.map

package/dist/tools/resolveName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveName.js","sourceRoot":"","sources":["../../src/tools/resolveName.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,IAAI,EAAE,UAAU,CAAC,QAAQ,CACvB,uEAAuE,CACxE;IACD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IAC7D,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,+DAA+D,CAChE;CACJ,CAAC,CAAC;AAIH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAuB;IAEvB,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,cAAc,EAAE;QAC3C,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;KAC3B,CAAC,CAAC;IACH,OAAO,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,IAAI,EAAE,cAAc;IACpB,WAAW,EACT,wOAAwO;IAC1O,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE,kBAAkB;CACnB,CAAC"}

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-09

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/design.md

@@ -0,0 +1,162 @@
+## Context
+
+OmniFocus exposes two distinct automation surfaces on macOS:
+
+1. **The scripting dictionary**, reachable from AppleScript and JXA (`osascript -l JavaScript`). This is the legacy surface the prior MCP server targeted by generating AppleScript source strings. It lacks folder creation, Single Actions list type, task moves, stable IDs, and recurrence-rule construction. It also requires string-concatenation of arguments, which is the root cause of the apostrophe and name-ambiguity bug classes.
+
+2. **OmniJS**, the modern Omni Automation JavaScript runtime that lives *inside* the OmniFocus process. This is the API documented at omni-automation.com. It exposes `Task`, `Project`, `Folder`, `Tag`, `Task.RepetitionRule`, `Perspective`, `id.primaryKey`, `moveTasks`, `new Folder`, and everything else the prior server couldn't reach. It is reachable from outside OmniFocus *only* via the `evaluateJavascript` method on the scripting-dictionary application object.
+
+The two are not interchangeable. The scripting dictionary is a capability-limited facade over the same underlying database; OmniJS is the authoritative modern API. Every "cannot do X" limitation in the prior server is a limitation of the scripting dictionary, not of JXA or macOS automation generally.
+
+The project starts from a clean slate: no legacy code, no prior specs, no backwards-compatibility constraints. The only inputs are the Omni Automation API surface, the MCP protocol, and the enumerated failure modes of the prior server.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Expose the full Omni Automation API surface through an MCP server, eventually reaching 1:1 coverage. This change establishes the foundation; subsequent changes fill in capabilities.
+- Eliminate by construction the bug classes of the prior server: apostrophe-breaking, name-ambiguity routing, parse-error-on-success, type-coercion failures in batch parameters, missing capability coverage.
+- Make every domain operation authored as a static, standalone `.js` snippet that can be pasted into OmniFocus's Automation Console for manual verification.
+- Provide stable, id-based addressing for every OmniFocus entity, with name/path resolution as a separate, explicit, ambiguity-reporting step.
+- Establish an integration-test harness that exercises a real OmniFocus instance without polluting the user's data or leaking fixtures across sync.
+- Name every target capability up front so future changes have a landing place and the scope of "full API coverage" is visible from the first commit.
+
+**Non-Goals:**
+
+- Cross-platform support. Omni Automation is macOS-only; the server is macOS-only.
+- Compatibility with the prior AppleScript-based MCP server. Tool names, parameter shapes, and result envelopes are all new.
+- Interactive UI automation: `Form`, `Alert`, `FilePicker`, `FileSaver`. These APIs require a human to click in the OmniFocus app while the script blocks; they cannot cross an MCP boundary without changing semantics.
+- Device-local side effects unrelated to OmniFocus data: `Speech`, `Device`, clipboard mutation.
+- Window mutation (resize, close, focus). Window *state* is exposed read-only; mutation is low-value and fragile.
+- User-visible notifications posted from scripts. Out by default; reconsiderable if a concrete use case emerges.
+- Custom perspective *creation and editing*. Listing and activation are in scope; programmatic definition of perspective rules is likely not scriptable even in OmniFocus Pro and is marked non-goal pending verification when the perspective-management change is drafted.
+- CI coverage for integration tests. CI runs unit tests only; integration tests are local-developer-only by the nature of requiring a running OmniFocus instance.
+- Transactional semantics across batch operations. OmniFocus does not expose transactions; batch tools return per-item result arrays with partial-success semantics.
+
+## Decisions
+
+### Decision 1: JXA is a thin shim; all domain logic runs inside OmniJS via `evaluateJavascript`.
+
+**Choice:** Every tool invocation spawns `osascript -l JavaScript` running a minimal JXA wrapper whose only job is to call `Application('OmniFocus').evaluateJavascript(snippet)`, catch exceptions, and print one line of JSON to stdout. All domain logic — creating folders, setting project types, constructing repetition rules, reading IDs, walking hierarchies — lives in OmniJS snippets and runs inside the OmniFocus process.
+
+**Rationale:** The capability gap between the scripting dictionary and OmniJS is the *entire* reason the prior server failed to cover critical features. Targeting OmniJS directly is the only path to feature parity with the Omni Automation API. JXA's only value here is as the carrier that reaches `evaluateJavascript`; nothing else in the JXA scripting-dictionary surface is used.
+
+**Alternatives considered:**
+
+- *Pure AppleScript, better escaping.* Rejected: the capability gap is structural; no amount of escaping fixes the missing folder, type, move, ID, and recurrence capabilities.
+- *`omnifocus://` URL automation.* Rejected: URL schemes support a narrow slice of operations (add to inbox, open document, complete task) and provide no return channel for IDs or query results.
+- *OmniFocus plug-in bundles installed into the user's library.* Rejected: requires out-of-band user setup, complicates distribution, and still requires an IPC channel back to the MCP server.
+- *Shortcuts.app automation.* Rejected: similar return-channel and capability limitations, and adds a dependency on Shortcuts being configured.
+
+**Bugs this kills:** "cannot create folders," "cannot create Single Actions list," "cannot move tasks between projects," "no project IDs returned," "cannot set recurrence," "folder name ambiguity" (because paths can be resolved via `flattenedFolders` inside OmniJS rather than scripting-dictionary `whose` clauses).
+
+### Decision 2: Arguments are embedded as JSON literals; no string interpolation anywhere.
+
+**Choice:** Snippet files are static `.js` files containing exactly one placeholder token: `__ARGS__`. At runtime, the TypeScript side constructs the script to execute via `template.replace("__ARGS__", JSON.stringify(args))`. The snippet reads `const args = __ARGS__;` as its first line. No other interpolation of user-supplied data into script source is permitted anywhere in the codebase.
+
+**Rationale:** JSON is a syntactic subset of JavaScript. `JSON.stringify` of any JavaScript value produces a string that is both valid JSON and a valid JavaScript expression literal. Embedding it directly into source is injection-safe for arbitrary strings, including apostrophes, quotes, backslashes, newlines, unicode, and emoji — precisely the inputs that broke the prior server. It also has the useful property that the generated script is a standalone, paste-ready snippet: a developer can hand-edit `__ARGS__` in the template and paste it into OmniFocus's Automation Console to reproduce any operation.
+
+**Alternatives considered:**
+
+- *Passing arguments via environment variables.* Rejected: `evaluateJavascript` runs inside OmniFocus's process, which does not inherit the `osascript` environment. The snippet could not read them.
+- *Writing arguments to a temp file and having the snippet read it.* Rejected: OmniJS has no general filesystem read primitive; `FileWrapper` is attachment-scoped. Adds a cleanup burden and a failure mode.
+- *String-escape templating (Handlebars, Mustache, manual backslash escaping).* Rejected: every escape scheme has edge cases. The JSON-literal approach has none because JSON is closed under JavaScript expression syntax.
+
+**Bugs this kills:** "apostrophes in task/project names break AppleScript string generation," plus the entire class of unicode and escape-sequence bugs that haven't been hit yet but would eventually surface under string concatenation.
+
+### Decision 3: Results flow as exactly one line of JSON on stdout.
+
+**Choice:** Every snippet's last expression is `JSON.stringify({ok: true, data: <result>})` or throws. The JXA shim wraps the `evaluateJavascript` call in try/catch. On success, it prints the returned string verbatim followed by a single newline. On failure, it prints `JSON.stringify({ok: false, error: {name, message, stack}})` followed by a single newline. The TypeScript runtime reads stdout, takes the first JSON-parseable line, and asserts `ok`.
+
+**Rationale:** A strict protocol eliminates ambiguity about whether an operation succeeded. The prior server's "parse error on success" bug was a direct consequence of treating incidental AppleScript output as part of the result payload. With a one-line JSON contract, success and failure are trivially distinguishable and the protocol is easy to test in isolation.
+
+**Alternatives considered:**
+
+- *Multi-line JSON with framing.* Rejected: unnecessary complexity for the single-operation-per-invocation model.
+- *Exit code as the success signal.* Rejected: `osascript` exit codes are unreliable across JXA error modes, and an exit code doesn't carry error details.
+- *Writing results to a temp file.* Rejected: adds a cleanup burden and a filesystem round-trip with no benefit.
+
+**Bugs this kills:** "`remove_item` returns parse error on success even when operation succeeded."
+
+### Decision 4: `id.primaryKey` is the canonical address for every entity; name resolution is a separate, explicit, ambiguity-reporting step.
+
+**Choice:** Every read tool returns `{id, ...}` where `id` is `obj.id.primaryKey`. Every write tool (in this and future changes) accepts `id` as the primary addressing parameter. Name and path resolution is a dedicated `resolve_name` tool that takes `{type, query, scope?}` and returns a list of candidate `{id, name, path, ...}` entries. When more than one candidate matches, the tool returns all of them and the caller must decide; it never silently picks.
+
+**Rationale:** The prior server's duplicate-name and folder-ambiguity bugs are consequences of name-based addressing with silent disambiguation. IDs are stable across sessions within OmniFocus. Making ID the canonical address and forcing callers (including LLMs) to resolve ambiguity explicitly is the only way to produce deterministic behavior in a database where names are user-chosen and frequently collide.
+
+**Alternatives considered:**
+
+- *Name-based addressing with a "pick the first match" default.* Rejected: this is exactly what the prior server did, and it routed to the wrong target.
+- *Path-only addressing.* Rejected: paths are fragile to user renames and still ambiguous when the same path exists under different roots (e.g., the same tag name under different parents).
+- *Auto-disambiguation via fuzzy scoring.* Rejected: silent selection is precisely the failure mode being fixed.
+
+**Open question:** Whether `id.primaryKey` values survive OmniFocus sync across devices and across database rebuilds. This is believed to be true but will be verified during the execution-runtime implementation and documented in the runtime README. If IDs turn out not to survive sync, the contract still holds within a single session; callers re-resolving after a sync event is an acceptable fallback.
+
+**Bugs this kills:** "duplicate project names cause wrong-target routing," "folder name ambiguity — same folder name under different parents routes incorrectly," "no project IDs returned — projects only addressable by name."
+
+### Decision 5: Tool parameters are validated with zod at the TS boundary; enums are strict; no type coercion.
+
+**Choice:** Every MCP tool handler defines its input schema as a zod object. Handlers receive already-parsed, already-validated arguments. Enums like project type are `z.enum(["parallel", "sequential", "singleActions"])`. Batch arrays are `z.array(z.object({...}))` — never strings that look like JSON. Invalid inputs are rejected at the TS boundary with structured error messages before any snippet runs.
+
+**Rationale:** The prior server had `sequential` parameters that arrived as strings and were treated as booleans with broken coercion, and `batch_remove_items` parameters that arrived as serialized JSON strings instead of arrays. These are the bug pattern you get when tool schemas are loose and the handler does ad-hoc type massaging. zod at the boundary makes the schema the contract.
+
+**Alternatives considered:**
+
+- *Ad-hoc `typeof` checks in handlers.* Rejected: this is what produced the original bugs.
+- *JSON Schema validation via ajv.* Considered and deferred: zod is TypeScript-native, produces better type inference, and integrates naturally with the MCP SDK's expected schema surface. ajv is fine but adds a second schema language.
+
+**Bugs this kills:** "`sequential` parameter must be a true boolean, not string," "`batch_remove_items` items parameter must be a JSON array, not serialized string."
+
+### Decision 6: Integration tests scope all fixtures under a disposable folder and refuse to run under sync by default.
+
+**Choice:** Every integration test run generates a UUID and creates a top-level folder named `__MCP_TEST_<uuid>__` in the user's OmniFocus database. All fixture projects, folders, tasks, and tags are created inside it. Teardown deletes the folder and everything under it. A preflight check inspects the database's sync configuration and refuses to run if sync is enabled, unless `MCP_TEST_ALLOW_SYNC=1` is set in the environment. Integration tests run serially (OmniFocus is a singleton). CI runs unit tests only.
+
+**Rationale:** Integration tests against a real OmniFocus instance are the only way to validate the OmniJS API contract — mocks would drift. But real-database testing has a failure mode where fixtures leak into the user's actual workflow or, worse, sync to other devices. Fixture-folder scoping contains the blast radius; the sync preflight prevents cross-device leakage by default with an explicit opt-out for users who understand the tradeoff.
+
+**Alternatives considered:**
+
+- *Mocking the OmniJS API.* Rejected: this is the path to building something that passes tests and fails in production.
+- *Dedicated test OmniFocus document.* Rejected: OmniFocus does not support multiple documents in a way that's ergonomic for automated switching.
+- *Snapshot-and-restore the database.* Rejected: there is no supported API for this; copying the sqlite file behind OmniFocus's back is unsafe.
+
+## Risks / Trade-offs
+
+- **Risk:** `id.primaryKey` may not survive OmniFocus sync or database rebuilds. → **Mitigation:** Verify during runtime implementation and document findings. If IDs don't survive sync, document the session-scope guarantee and update `resolve_name` guidance accordingly. This is an open question, not a blocker.
+
+- **Risk:** `evaluateJavascript` may have undocumented size limits on the script argument. → **Mitigation:** Keep snippets small and focused (one operation per file). For batch operations (future change), the snippet iterates over an args array; it does not inline per-item code.
+
+- **Risk:** OmniJS error messages inside `evaluateJavascript` may be lossy when surfaced through JXA. → **Mitigation:** The snippet catches its own errors and constructs the error envelope itself before returning, so error details never cross the OmniJS→JXA boundary as a raw exception.
+
+- **Risk:** Integration tests running against a real OmniFocus instance can still pollute the user's data if teardown fails mid-run. → **Mitigation:** Fixture folders are prefixed with `__MCP_TEST_` and include a UUID; a `clean-test-fixtures` dev script scans for and removes any stragglers. README documents the manual cleanup command.
+
+- **Risk:** OmniFocus sync conflicts from concurrent modifications during a test run. → **Mitigation:** Serial test execution plus the sync preflight. Under the opt-in sync-allowed mode, users accept the risk explicitly.
+
+- **Trade-off:** The MCP server is macOS-only. This is an inherent property of Omni Automation and not negotiable without abandoning the capability goals.
+
+- **Trade-off:** Every tool invocation spawns an `osascript` process, which has startup cost. For single operations this is fine; for high-frequency batch operations it would be noticeable. Batch tools (future change) will therefore execute as a single snippet that iterates internally, not as a loop of tool calls from the caller side.
+
+- **Trade-off:** Snippet files live outside the TypeScript compilation unit. Refactoring a shared OmniJS helper means editing `.js` files that tsc doesn't type-check. Accepted because testability-by-paste is more valuable than type-checking across the boundary; the JS side is small and exercised by integration tests.
+
+## Bug-to-decision traceability
+
+Every documented failure mode of the prior server is mapped to the decision that eliminates it, so the rationale survives archival:
+
+| Prior-server bug | Killed by |
+|---|---|
+| Cannot create folders | Decision 1 (OmniJS exposes `new Folder`) |
+| Cannot create Single Actions list | Decision 1 (OmniJS exposes `containsSingletonActions`) |
+| Cannot move tasks between projects | Decision 1 (OmniJS exposes `moveTasks`) |
+| No project IDs returned | Decisions 1 + 4 (`id.primaryKey` exists in OmniJS and is the canonical address) |
+| Cannot set recurrence/repeat | Decision 1 (OmniJS exposes `Task.RepetitionRule`) |
+| Apostrophes break script generation | Decision 2 (JSON-literal argument embedding) |
+| Duplicate project names cause wrong-target routing | Decision 4 (ID addressing + ambiguity-reporting resolution) |
+| Folder name ambiguity under different parents | Decision 4 (ID addressing + path-based resolution with ambiguity reporting) |
+| `sequential` parameter must be a true boolean, not string | Decision 5 (zod enum validation at TS boundary) |
+| `batch_remove_items` items parameter must be a JSON array | Decision 5 (zod array validation at TS boundary) |
+| `remove_item` returns parse error on success | Decision 3 (strict one-line JSON result protocol) |
+
+## Open Questions
+
+- Do `id.primaryKey` values survive OmniFocus sync across devices and database rebuilds? To be verified during runtime implementation.
+- Does `evaluateJavascript` have a practical size limit on the script argument? To be measured during runtime implementation and documented as an upper bound for future batch snippet design.
+- Does OmniJS expose a reliable way to detect whether sync is enabled without mutating state? Needed for the integration-test preflight check. If not, the preflight falls back to reading the user's OmniFocus preferences via JXA before entering the OmniJS bridge.

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/proposal.md

@@ -0,0 +1,49 @@
+## Why
+
+OmniFocus needs an MCP server that exposes the full Omni Automation JavaScript API to LLM callers. A prior AppleScript-string-generating server exists but has structural limitations: it cannot create folders, cannot create Single Actions lists, cannot move tasks between projects, cannot set recurrence rules, returns no stable IDs, breaks on apostrophes in names, silently routes to the wrong target on duplicate names, and mis-parses successful results as errors. These are not bugs to patch — they are consequences of generating AppleScript source as concatenated strings against a scripting dictionary that lacks the needed capabilities.
+
+This change starts from a clean slate with an architecture that kills those bug classes by construction: all operations execute inside OmniFocus's OmniJS runtime (where the modern API lives) via a JXA bridge, arguments are embedded as JSON literals (never concatenated), identity is always `id.primaryKey`, and results flow as a strict one-line JSON protocol. This first change establishes the runtime foundation and names every capability that will eventually exist, so subsequent changes can fill in the API surface incrementally without re-litigating the architecture.
+
+## What Changes
+
+- Establish a TypeScript MCP server scaffold (`@modelcontextprotocol/sdk`, zod for schemas, vitest for tests) with `src/runtime/`, `src/snippets/`, `src/tools/`, `src/schemas/`, `src/server.ts`, `test/unit/`, `test/integration/`, `package.json`, `tsconfig.json`.
+- Implement the execution runtime: a JXA shim that calls `Application('OmniFocus').evaluateJavascript(snippet)`, wraps results in a strict `{ok, data} | {ok: false, error}` envelope, and prints exactly one line of JSON to stdout.
+- Implement the snippet-authoring convention: static `.js` files with a single `__ARGS__` placeholder, injected by `template.replace("__ARGS__", JSON.stringify(args))`. No other interpolation is permitted anywhere in the codebase.
+- Implement the identity model: every read returns `id.primaryKey`; every write will accept `id` as the canonical address. Name/path resolution is a separate `resolve_name` tool that returns candidate lists on ambiguity and never silently picks a winner.
+- Deliver the minimum-viable read surface needed to prove the bridge end-to-end: `list_projects`, `get_project`, `list_folders`, `get_folder`, `list_tasks`, `get_task`, `list_tags`, `get_tag`, `resolve_name`. No mutating tools in this change.
+- Establish the integration-test harness against a real OmniFocus instance, with all fixtures scoped under a disposable `__MCP_TEST_<uuid>__` top-level folder and a preflight that refuses to run when OmniFocus sync is enabled (unless `MCP_TEST_ALLOW_SYNC=1`).
+- Name every target capability as a stub spec so future changes have a landing place: `recurrence`, `perspective-management`, `window-state`, `forecast`, `database-inspection`, `batch-operations`, `attachments`, `url-automation`, `settings`. Stubs declare scope and non-goals without specifying requirements that later changes will own.
+- Document explicit non-goals: interactive UI APIs (`Form`, `Alert`, `FilePicker`, `FileSaver`), `Speech`, `Device`, clipboard mutation, window mutation, notifications, and custom perspective creation/editing. These are recorded as non-goals in design.md so they don't look like oversights.
+
+## Capabilities
+
+### New Capabilities
+
+- `execution-runtime`: The JXA→OmniJS bridge, snippet loader, argument-injection rule, one-line JSON result protocol, and error model. Fully specified in this change.
+- `identity-resolution`: `id.primaryKey` addressing, name/path resolution with ambiguity reporting, and the `resolve_name` tool contract. Fully specified in this change.
+- `task-management`: Task read operations (`list_tasks`, `get_task`) specified in this change; full CRUD, move, completion, and hierarchy operations land in the `core-crud` change.
+- `project-management`: Project read operations (`list_projects`, `get_project`) specified in this change; CRUD, type (parallel/sequential/singleActions), status, and review metadata land in `core-crud`.
+- `folder-management`: Folder read operations (`list_folders`, `get_folder`) specified in this change; CRUD, nesting, rename, and move land in `core-crud`.
+- `tag-management`: Tag read operations (`list_tags`, `get_tag`) specified in this change; CRUD, nesting, assignment, and status land in `core-crud`.
+- `recurrence`: Stub naming the capability for Task.RepetitionRule construction, RepetitionMethod, structured schema plus raw RRULE escape hatch, and clearing recurrence. Requirements land in the `recurrence` change.
+- `perspective-management`: Stub naming the capability for listing built-in and custom perspectives, activating a perspective in a window, and reading perspective details. Custom perspective creation/editing is a non-goal pending API verification.
+- `window-state`: Stub naming the capability for read-only window state (current window, active perspective, sidebar selection, content selection). Window mutation is a non-goal.
+- `forecast`: Stub naming the capability for forecast days, tasks due/deferred on a day, and forecast metadata.
+- `database-inspection`: Stub naming the capability for scoped, paged, filtered database traversal including `dump_database`, inbox contents, and database metadata.
+- `batch-operations`: Stub naming the capability for batch variants of mutating tools with per-item result arrays and partial-success semantics.
+- `attachments`: Stub naming the capability for `FileWrapper`-based attachment listing and round-trip on task notes.
+- `url-automation`: Stub naming the capability for `omnifocus://` URL construction and parsing.
+- `settings`: Stub naming the capability for reading app settings and preferences where exposed.
+
+### Modified Capabilities
+
+None. This is a clean-slate project with no prior specs.
+
+## Impact
+
+- **New repository structure** with TypeScript toolchain, MCP SDK, zod, vitest.
+- **Runtime dependency on macOS** (`osascript`) and a running OmniFocus instance. The server is macOS-only by nature of the Omni Automation platform.
+- **Integration tests mutate a real OmniFocus database.** Mitigated by fixture-folder scoping and a sync-enabled preflight check. Documented loudly in the README.
+- **No CI coverage for integration tests.** CI runs unit tests only (snippet injection, zod schema validation, result-protocol parsing). Integration is local-developer-only.
+- **Replaces a prior AppleScript-based MCP server.** Callers migrating from the old server will encounter breaking changes in tool names, parameter types, and result shapes. This is accepted because the prior server's contract was structurally broken; compatibility is not a goal.
+- **No external network dependencies.** The server runs entirely locally against the user's OmniFocus database.

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/attachments/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `attachments` capability SHALL cover listing, reading, adding, and removing file attachments on task notes via the OmniJS `FileWrapper` API. The on-wire representation of attachment contents across the MCP boundary (inline base64, filesystem path reference, or a hybrid with a size threshold) SHALL be decided when the `attachments` change is drafted. Requirements for individual tools SHALL be added by that change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding attachment tools
+- **THEN** it lands requirements under this capability and makes the on-wire encoding decision explicit

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/batch-operations/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `batch-operations` capability SHALL cover batch variants of every mutating tool (create, update, delete, move, complete, assign). Batch tools SHALL accept strictly typed arrays validated at the TypeScript boundary (never serialized JSON strings) and SHALL return a per-item result array with partial-success semantics: each element is an `{ok, data?, error?}` envelope carrying that item's outcome independent of other items. Batch tools SHALL execute as a single OmniJS snippet that iterates internally, not as a loop of per-item bridge invocations. Requirements for individual batch tools SHALL be added by the `batch-operations` change.
+
+#### Scenario: Capability is named and semantics are fixed
+- **WHEN** a future change proposes adding batch tools
+- **THEN** it lands requirements under this capability with typed-array validation and partial-success result semantics as invariants

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/database-inspection/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `database-inspection` capability SHALL cover scoped, paged, and filtered traversal of the full OmniFocus database, including a `dump_database` tool that accepts `{scope, id?, include, format}` parameters, inbox inspection, and database metadata (name, sync status, object counts). The default behavior of `dump_database` SHALL exclude completed tasks, dropped entities, and task notes to keep payloads manageable; those are opt-in via the `include` parameter. Requirements for individual tools SHALL be added by the `forecast-and-inspection` change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding database-inspection tools
+- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/execution-runtime/spec.md

@@ -0,0 +1,69 @@
+## ADDED Requirements
+
+### Requirement: OmniJS execution via JXA bridge
+
+The system SHALL execute every OmniFocus domain operation inside OmniFocus's OmniJS runtime by invoking `Application('OmniFocus').evaluateJavascript(snippet)` from a JXA host process spawned via `osascript -l JavaScript`. The JXA host SHALL NOT invoke any OmniFocus scripting-dictionary method other than `evaluateJavascript` for domain operations.
+
+#### Scenario: Tool invocation routes through the bridge
+- **WHEN** a tool handler invokes the runtime with a snippet and args
+- **THEN** the runtime spawns `osascript -l JavaScript`, passes a JXA wrapper that calls `Application('OmniFocus').evaluateJavascript` with the prepared snippet, and awaits stdout
+
+#### Scenario: Scripting-dictionary domain methods are forbidden
+- **WHEN** a contributor adds a tool handler that calls e.g. `Application('OmniFocus').defaultDocument.projects` directly
+- **THEN** a unit test (or review) flags the call as a runtime-contract violation and the change is rejected
+
+### Requirement: Snippet argument injection via JSON literal
+
+The system SHALL construct executable scripts by replacing exactly one `__ARGS__` placeholder in a static `.js` snippet template with the result of `JSON.stringify(args)`. No other interpolation of user-supplied data into script source is permitted anywhere in the codebase.
+
+#### Scenario: Apostrophes and quotes survive injection
+- **WHEN** a tool is invoked with `args = {name: "Finn's \"birthday\""}`
+- **THEN** the executed snippet receives `args.name === "Finn's \"birthday\""` and no syntax error occurs
+
+#### Scenario: Unicode and newlines survive injection
+- **WHEN** a tool is invoked with `args = {note: "line1\nline2 — emoji 🎯"}`
+- **THEN** the executed snippet receives the note verbatim including the newline and unicode code points
+
+#### Scenario: Snippets are standalone and paste-ready
+- **WHEN** a developer opens any file under `src/snippets/`
+- **THEN** the file is a valid JavaScript program that can be pasted into OmniFocus's Automation Console after replacing `__ARGS__` with a hand-written object literal, with no additional preprocessing required
+
+### Requirement: One-line JSON result protocol
+
+The system SHALL represent every bridge invocation's result as exactly one line of JSON on the JXA host's stdout, matching the envelope `{ok: true, data: <value>} | {ok: false, error: {name: string, message: string, stack?: string}}`. The TypeScript runtime SHALL read stdout, extract the first JSON-parseable line, and return the parsed envelope to the caller. A result envelope with `ok: false` SHALL be thrown as a structured error with the error details preserved.
+
+#### Scenario: Successful operation returns data envelope
+- **WHEN** a snippet completes without throwing and its final expression is `JSON.stringify({ok: true, data: {id: "abc"}})`
+- **THEN** the TS runtime receives `{ok: true, data: {id: "abc"}}` and returns `{id: "abc"}` to the tool handler
+
+#### Scenario: Snippet exception produces error envelope
+- **WHEN** a snippet throws an `Error` with message "not found"
+- **THEN** the JXA shim catches the exception, prints `{ok: false, error: {name: "Error", message: "not found", ...}}` as one line on stdout, and the TS runtime throws a structured error carrying the name, message, and stack
+
+#### Scenario: Extraneous stdout chatter does not corrupt results
+- **WHEN** any process in the pipeline writes incidental non-JSON output to stdout before the result line
+- **THEN** the TS runtime still parses the result envelope correctly by selecting the first complete JSON-parseable line
+
+### Requirement: Snippet loader
+
+The system SHALL load snippet templates from `src/snippets/<name>.js` relative to the compiled server's known snippet root, caching the file contents in memory after the first read. The loader SHALL reject snippets that do not contain exactly one `__ARGS__` token.
+
+#### Scenario: Snippet is loaded and cached
+- **WHEN** a tool handler invokes the runtime with snippet name `"list_projects"` twice in the same process
+- **THEN** the file `list_projects.js` is read from disk exactly once and the cached content is used for the second invocation
+
+#### Scenario: Snippet with zero placeholders is rejected
+- **WHEN** a snippet file contains no `__ARGS__` token
+- **THEN** the loader throws a contract violation at load time, not at runtime
+
+#### Scenario: Snippet with multiple placeholders is rejected
+- **WHEN** a snippet file contains two or more `__ARGS__` tokens
+- **THEN** the loader throws a contract violation at load time
+
+### Requirement: Script timeout
+
+The system SHALL enforce a configurable per-invocation timeout on `osascript` execution, defaulting to 30 seconds, and SHALL terminate the child process and throw a timeout error when exceeded.
+
+#### Scenario: Long-running snippet is terminated
+- **WHEN** a snippet runs longer than the configured timeout
+- **THEN** the runtime sends SIGTERM to the `osascript` process and throws a timeout error identifying the snippet name and elapsed time

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/folder-management/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: List folders
+
+The system SHALL provide a `list_folders` tool that returns every folder in the OmniFocus database as an array of summaries, each containing at minimum `{id, name, path, parentId, status}`. The `path` field SHALL use the canonical ` ▸ ` separator and SHALL equal the folder's name for top-level folders. The `parentId` field SHALL be `null` for top-level folders. The `status` field SHALL be one of `"active" | "dropped"`.
+
+#### Scenario: All folders are returned with full paths
+- **WHEN** `list_folders` is called with no arguments
+- **THEN** the tool returns every folder in the database including nested folders, each with its full ancestor path
+
+#### Scenario: Top-level folders have null parent
+- **WHEN** a folder exists at the root of the folder hierarchy
+- **THEN** its summary carries `parentId: null` and `path` equal to its name
+
+### Requirement: Get folder by ID
+
+The system SHALL provide a `get_folder` tool that accepts `{id: string}` and returns the full detail record of the named folder, including `{id, name, path, parentId, status, childFolderIds, projectIds}`. If no folder exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing folder returns full detail with children
+- **WHEN** `get_folder` is called with the ID of an existing folder
+- **THEN** the tool returns the folder's full detail including the IDs of its immediate child folders and immediate child projects
+
+#### Scenario: Missing folder returns not-found error
+- **WHEN** `get_folder` is called with an ID that does not correspond to any folder
+- **THEN** the tool returns a structured error with a not-found code

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/forecast/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `forecast` capability SHALL cover OmniFocus Forecast data, including forecast days, tasks due or deferred on a given day, the configured forecast tag, and forecast badge counts. Requirements for individual tools SHALL be added by the `forecast-and-inspection` change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding forecast tools
+- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/identity-resolution/spec.md

@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Canonical ID addressing
+
+The system SHALL use `id.primaryKey` as the canonical identifier for every addressable OmniFocus entity (Task, Project, Folder, Tag, Perspective). Every read tool SHALL return an `id` field carrying this value. Every write tool (in this and future changes) SHALL accept an `id` parameter as its primary addressing mode.
+
+#### Scenario: Read tools return primary key
+- **WHEN** a caller invokes `list_projects`
+- **THEN** every returned element has an `id` field equal to the OmniJS expression `project.id.primaryKey` for that project
+
+#### Scenario: IDs are stable within a session
+- **WHEN** a caller reads a project's ID via `list_projects`, then reads the same project again via `get_project` using that ID
+- **THEN** the second read succeeds and returns the same project, without re-resolving by name
+
+### Requirement: Name and path resolution with ambiguity reporting
+
+The system SHALL provide a `resolve_name` tool that accepts `{type, query, scope?}` and returns a list of candidate entities `[{id, name, path, type, ...}]`. When more than one entity matches the query, the tool SHALL return all matches and SHALL NOT silently pick a winner. The caller is responsible for disambiguating.
+
+#### Scenario: Unique match returns single candidate
+- **WHEN** `resolve_name` is called with `{type: "project", query: "Q4 Planning"}` and exactly one project has that name
+- **THEN** the tool returns a list with one element containing the project's id, name, and full folder path
+
+#### Scenario: Ambiguous match returns all candidates
+- **WHEN** `resolve_name` is called with `{type: "project", query: "Inbox Cleanup"}` and two projects have that name under different folders
+- **THEN** the tool returns a list with both candidates, each carrying a distinct id and distinct folder path
+
+#### Scenario: No match returns empty list
+- **WHEN** `resolve_name` is called with a query that matches no entity of the requested type
+- **THEN** the tool returns an empty list and does not throw an error
+
+#### Scenario: Path-qualified query narrows scope
+- **WHEN** `resolve_name` is called with `{type: "folder", query: "Acme", scope: "Work ▸ Clients"}`
+- **THEN** the tool returns only folders named "Acme" that are direct or transitive children of the folder at path "Work ▸ Clients"
+
+### Requirement: Folder path addressing
+
+The system SHALL represent folder paths as strings using the separator ` ▸ ` (U+25B8 with surrounding spaces) and SHALL support resolving a folder by its full path as an alternative to its ID. When a path is ambiguous (the same path exists under multiple roots, which cannot occur for folders but can for tags), the resolution SHALL report the ambiguity through `resolve_name`.
+
+#### Scenario: Folder resolves by full path
+- **WHEN** `resolve_name` is called with `{type: "folder", query: "Work ▸ Clients ▸ Acme"}`
+- **THEN** the tool returns the folder whose full ancestor chain matches that path exactly
+
+#### Scenario: Returned paths use the canonical separator
+- **WHEN** any read tool returns a folder path or a project's containing folder path
+- **THEN** the path uses ` ▸ ` as the separator between ancestor names

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/perspective-management/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `perspective-management` capability SHALL cover listing built-in and custom perspectives, reading perspective metadata, and activating a perspective in a document window. Custom perspective *creation and editing* are a non-goal pending verification of OmniJS scriptability of `Perspective.Custom` definitions; if a future investigation proves the API is available, the non-goal may be revisited by a later change. Requirements for individual tools SHALL be added by the `perspectives-and-windows` change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding perspective tools
+- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/project-management/spec.md

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: List projects
+
+The system SHALL provide a `list_projects` tool that returns every project in the OmniFocus database as an array of summaries, each containing at minimum `{id, name, folderPath, status, type}`. The `status` field SHALL be one of `"active" | "onHold" | "done" | "dropped"`. The `type` field SHALL be one of `"parallel" | "sequential" | "singleActions"`. The `folderPath` field SHALL use the canonical ` ▸ ` separator and SHALL be an empty string for projects at the top level with no containing folder.
+
+#### Scenario: All projects are returned with canonical fields
+- **WHEN** `list_projects` is called with no arguments
+- **THEN** the tool returns every project in the database, each with id, name, folderPath, status, and type populated using the canonical enum values
+
+#### Scenario: Single Actions list is reported with correct type
+- **WHEN** the database contains a Single Actions list project
+- **THEN** that project appears in the result with `type: "singleActions"`, never as `"parallel"` or `"sequential"`
+
+### Requirement: Get project by ID
+
+The system SHALL provide a `get_project` tool that accepts `{id: string}` and returns the full detail record of the named project, including `{id, name, note, folderPath, status, type, flagged, deferDate, dueDate, completionDate, reviewInterval, nextReviewDate, lastReviewDate, tagIds}`. If no project exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing project returns full detail
+- **WHEN** `get_project` is called with the ID of an existing project
+- **THEN** the tool returns the project's full detail record
+
+#### Scenario: Missing project returns not-found error
+- **WHEN** `get_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured error with a not-found code

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/recurrence/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `recurrence` capability SHALL cover the construction, assignment, reading, and clearing of `Task.RepetitionRule` values on OmniFocus tasks, including the `RepetitionMethod` (`Fixed`, `DueDate`, `Start`, `None`) and the underlying ICS RRULE string. Tools under this capability SHALL expose both a structured schema for common recurrence patterns (frequency, interval, weekday set) and a raw `rrule` escape hatch for patterns the structured schema does not express. Requirements for individual tools SHALL be added by the `recurrence` change. This change only declares the capability and its scope.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding recurrence-related tools
+- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/changes/archive/2026-04-09-bootstrap-omnifocus-mcp/specs/settings/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `settings` capability SHALL cover reading OmniFocus application settings and preferences where the OmniJS API exposes them. Write access SHALL be limited to the subset of settings that OmniJS documents as writable; the specific writable keys SHALL be enumerated when the `settings` change is drafted. Requirements for individual tools SHALL be added by that change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding settings tools
+- **THEN** it lands requirements under this capability, with an explicit enumeration of writable keys vs read-only keys