@scardis/omnifocus-mcp 0.1.0

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

@@ -0,0 +1,25 @@
+## ADDED Requirements
+
+### Requirement: List tags
+
+The system SHALL provide a `list_tags` tool that returns every tag in the OmniFocus database as an array of summaries, each containing at minimum `{id, name, path, parentId, status}`. Tags form a tree in OmniFocus; the `path` field SHALL use the canonical ` ▸ ` separator and represent the full ancestor chain. The `parentId` field SHALL be `null` for top-level tags. The `status` field SHALL be one of `"active" | "onHold" | "dropped"`.
+
+#### Scenario: All tags are returned including nested tags
+- **WHEN** `list_tags` is called with no arguments
+- **THEN** the tool returns every tag in the database, top-level and nested, each with its full path and correct parentId
+
+#### Scenario: On-hold tag is reported with correct status
+- **WHEN** the database contains a tag that has been placed on hold
+- **THEN** that tag appears in the result with `status: "onHold"`
+
+### Requirement: Get tag by ID
+
+The system SHALL provide a `get_tag` tool that accepts `{id: string}` and returns the full detail record of the named tag, including `{id, name, path, parentId, status, childTagIds}`. If no tag exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing tag returns full detail
+- **WHEN** `get_tag` is called with the ID of an existing tag
+- **THEN** the tool returns the tag's full detail including the IDs of its immediate child tags
+
+#### Scenario: Missing tag returns not-found error
+- **WHEN** `get_tag` is called with an ID that does not correspond to any tag
+- **THEN** the tool returns a structured error with a not-found code

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

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: List tasks with scope filter
+
+The system SHALL provide a `list_tasks` tool that returns tasks within a caller-specified scope. The scope SHALL be one of: `{projectId: string}`, `{folderId: string}` (all tasks in projects under that folder, recursively), `{inbox: true}`, or `{all: true}` (the full flattened task list). The tool SHALL return an array of task summaries, each containing at minimum `{id, name, status, flagged, containerId, containerType}`.
+
+#### Scenario: List tasks in a specific project
+- **WHEN** `list_tasks` is called with `{projectId: "abc123"}`
+- **THEN** the tool returns every task directly or transitively contained in that project, with each element carrying the project id as `containerId` and `"project"` as `containerType`
+
+#### Scenario: List inbox tasks
+- **WHEN** `list_tasks` is called with `{inbox: true}`
+- **THEN** the tool returns every task in the OmniFocus inbox with `containerType` set to `"inbox"`
+
+#### Scenario: Invalid scope is rejected at the TS boundary
+- **WHEN** `list_tasks` is called with `{projectId: "abc", inbox: true}` (mutually exclusive scopes)
+- **THEN** the tool returns a validation error before any snippet executes
+
+### Requirement: Get task by ID
+
+The system SHALL provide a `get_task` tool that accepts `{id: string}` and returns the full detail record of the named task, including `{id, name, note, status, flagged, deferDate, dueDate, completionDate, estimatedMinutes, containerId, containerType, tagIds}`. If no task exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing task returns full detail
+- **WHEN** `get_task` is called with the ID of an existing task
+- **THEN** the tool returns the task's full detail record including all scalar fields and the list of tag IDs assigned to it
+
+#### Scenario: Missing task returns not-found error
+- **WHEN** `get_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured error with a not-found code and does not throw an unhandled exception

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

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `url-automation` capability SHALL cover `omnifocus://` URL construction (including task-paste format for bulk creation, add-to-inbox URLs, and deep links to entities by ID) and parsing of incoming `omnifocus://` URLs into structured form. Requirements for individual tools SHALL be added by the `url-automation` change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding URL-automation 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/window-state/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: Capability declared
+
+The `window-state` capability SHALL cover read-only inspection of OmniFocus document window state, including the currently active window, active perspective, sidebar selection, and content selection. Window *mutation* (resize, close, focus, open) is an explicit non-goal. Requirements for individual tools SHALL be added by the `perspectives-and-windows` change.
+
+#### Scenario: Capability is named and read-only scope is fixed
+- **WHEN** a future change proposes adding window-state tools
+- **THEN** it lands read-only requirements under this capability; any mutation proposal requires first revisiting the non-goal in design

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

@@ -0,0 +1,84 @@
+## 1. Repository scaffold
+
+- [x] 1.1 Create `package.json` with dependencies: `@modelcontextprotocol/sdk`, `zod`; devDependencies: `typescript`, `vitest`, `@types/node`, `tsx`
+- [x] 1.2 Create `tsconfig.json` targeting Node 20, strict mode, `moduleResolution: "bundler"`, `outDir: "dist"`, sourcemaps on
+- [x] 1.3 Create directory structure: `src/runtime/`, `src/snippets/`, `src/tools/`, `src/schemas/`, `test/unit/`, `test/integration/`
+- [x] 1.4 Add `.gitignore` covering `node_modules`, `dist`, `*.log`, macOS cruft
+- [x] 1.5 Add root `README.md` stub with macOS-only note and integration-test warning about sync
+
+## 2. Execution runtime (src/runtime/)
+
+- [x] 2.1 Implement `snippetLoader.ts`: reads `src/snippets/<name>.js` from the resolved snippet root, caches in memory, validates exactly one `__ARGS__` token, throws on zero or multiple
+- [x] 2.2 Implement `resultProtocol.ts`: zod schema for the `{ok, data} | {ok: false, error}` envelope, `parseResultLine(stdout: string)` that selects the first JSON-parseable line and validates the envelope, `ExecutionError` class carrying name/message/stack from the error branch
+- [x] 2.3 Implement `jxaShim.ts`: a template string containing the JXA wrapper that calls `Application('OmniFocus').evaluateJavascript(snippet)`, wraps in try/catch, prints the envelope as one JSON line
+- [x] 2.4 Implement `bridge.ts`: `runSnippet(name: string, args: unknown, opts?: {timeoutMs?: number}): Promise<unknown>` — loads the snippet via the loader, injects args via `template.replace("__ARGS__", JSON.stringify(args))`, wraps the result in the JXA shim, spawns `osascript -l JavaScript`, enforces timeout via `AbortController` + SIGTERM, parses stdout via `parseResultLine`, throws `ExecutionError` on `ok: false`, returns `data` on success
+- [x] 2.5 Export a single `runtime` barrel from `src/runtime/index.ts`
+
+## 3. Shared schemas (src/schemas/)
+
+- [x] 3.1 Define zod schemas: `IdSchema` (non-empty string), `EntityType` enum (`"task" | "project" | "folder" | "tag" | "perspective"`), `ProjectType` enum, `ProjectStatus` enum, `TaskStatus` enum, `TagStatus` enum, `FolderStatus` enum
+- [x] 3.2 Define shared return-shape schemas: `TaskSummary`, `TaskDetail`, `ProjectSummary`, `ProjectDetail`, `FolderSummary`, `FolderDetail`, `TagSummary`, `TagDetail`, `ResolveCandidate`
+- [x] 3.3 Export a `schemas` barrel from `src/schemas/index.ts`
+
+## 4. Snippets (src/snippets/*.js) — read-only set for this change
+
+- [x] 4.1 `list_projects.js`: iterate `flattenedProjects`, map to summary shape with `id.primaryKey`, canonical `status`/`type` enum values, folder path via ` ▸ ` separator; return `JSON.stringify({ok: true, data: [...]})`
+- [x] 4.2 `get_project.js`: resolve project by `args.id` via `Project.byIdentifier` (or equivalent), build detail shape including review metadata and tag IDs, return envelope; throw on not-found with a `NotFoundError` constructor defined at the top of the snippet
+- [x] 4.3 `list_folders.js`: iterate `flattenedFolders`, map to summary with full path; return envelope
+- [x] 4.4 `get_folder.js`: resolve folder by ID, return detail including child folder IDs and immediate project IDs
+- [x] 4.5 `list_tasks.js`: accept `args.scope` discriminated union (`projectId` / `folderId` / `inbox` / `all`), iterate the correct source, map to summary; return envelope
+- [x] 4.6 `get_task.js`: resolve task by ID, return full detail including tag IDs
+- [x] 4.7 `list_tags.js`: iterate `flattenedTags`, map to summary with full path, parentId, status
+- [x] 4.8 `get_tag.js`: resolve tag by ID, return detail including child tag IDs
+- [x] 4.9 `resolve_name.js`: accept `args.type`, `args.query`, optional `args.scope`; walk the relevant flat list, match by exact name (and path suffix if scope given), return array of candidates with `{id, name, path, type}`; never throw on zero matches
+- [x] 4.10 Add a shared helper comment block at the top of each snippet documenting the paste-to-console procedure
+
+## 5. MCP tools (src/tools/)
+
+- [x] 5.1 `listProjects.ts`: zod input schema (empty object), handler invokes `runSnippet("list_projects", {})`, validates output against `z.array(ProjectSummary)`, returns
+- [x] 5.2 `getProject.ts`: input `{id}`, handler invokes `runSnippet("get_project", {id})`, validates `ProjectDetail`
+- [x] 5.3 `listFolders.ts`: empty input, returns `z.array(FolderSummary)`
+- [x] 5.4 `getFolder.ts`: input `{id}`, returns `FolderDetail`
+- [x] 5.5 `listTasks.ts`: input discriminated union (`{projectId} | {folderId} | {inbox: true} | {all: true}`) with zod `discriminatedUnion` or refinement rejecting mutual exclusivity, returns `z.array(TaskSummary)`
+- [x] 5.6 `getTask.ts`: input `{id}`, returns `TaskDetail`
+- [x] 5.7 `listTags.ts`: empty input, returns `z.array(TagSummary)`
+- [x] 5.8 `getTag.ts`: input `{id}`, returns `TagDetail`
+- [x] 5.9 `resolveName.ts`: input `{type, query, scope?}`, returns `z.array(ResolveCandidate)`
+- [x] 5.10 Export a `tools` barrel from `src/tools/index.ts` listing all nine tool definitions
+
+## 6. MCP server entrypoint
+
+- [x] 6.1 `src/server.ts`: construct an `@modelcontextprotocol/sdk` server, register all nine tools from the barrel, wire stdio transport, start listening
+- [x] 6.2 Add `bin` field to `package.json` pointing at the compiled entrypoint and a `scripts.start` for development via `tsx`
+
+## 7. Unit tests (test/unit/)
+
+- [x] 7.1 `snippetLoader.test.ts`: golden-file test that loading each snippet in `src/snippets/` succeeds and contains exactly one `__ARGS__`; contract-violation tests for zero/multiple placeholders (using fixture files)
+- [x] 7.2 `resultProtocol.test.ts`: parses well-formed success envelope, parses well-formed error envelope, rejects malformed JSON, selects first parseable line when preceded by chatter
+- [x] 7.3 `bridge.injection.test.ts`: given a snippet template and args containing apostrophes, quotes, backslashes, newlines, and emoji, assert the generated script source is valid JavaScript (parse via `new Function`) and that evaluating it recovers the original args object unchanged — proves Decision 2 structurally
+- [x] 7.4 `schemas.test.ts`: round-trip validation for each shared schema; rejection tests for the `sequential`-as-string and `items`-as-JSON-string regression patterns at the boundary
+- [x] 7.5 `tools.listTasks.test.ts`: rejects mutually exclusive scope combinations at the zod boundary before any bridge call
+
+## 8. Integration test harness (test/integration/)
+
+- [x] 8.1 `fixtures.ts`: `createTestFolder()` generates `__MCP_TEST_<uuid>__` top-level folder via the bridge; `cleanupTestFolder(id)` removes it; `withTestFolder(fn)` helper wraps a test body
+- [x] 8.2 `preflight.ts`: detects OmniFocus sync status (via a read-only snippet that inspects the relevant setting); throws unless `MCP_TEST_ALLOW_SYNC=1` is set; invoked once in the vitest global setup
+- [x] 8.3 `vitest.integration.config.ts`: separate vitest config for integration with `pool: "forks"`, `maxConcurrency: 1`, `globalSetup: ./preflight.ts`, `testMatch: test/integration/**`
+- [x] 8.4 Integration test: `listProjects.int.test.ts` creates a fixture folder with a child project, calls the real bridge, asserts the fixture project appears in the result with the correct folder path
+- [x] 8.5 Integration test: `getTask.int.test.ts` creates a fixture task with an apostrophe and unicode in its name, retrieves by ID, asserts name survives round-trip — proves Decision 2 end-to-end
+- [x] 8.6 Integration test: `resolveName.int.test.ts` creates two fixture projects with identical names under different folders, asserts `resolve_name` returns both candidates with distinct paths
+- [x] 8.7 Add a `scripts.test:integration` in `package.json` guarded by macOS check
+- [x] 8.8 Add a `scripts.test:cleanup-fixtures` that scans for stale `__MCP_TEST_*` folders and removes them
+
+## 9. Documentation
+
+- [x] 9.1 Expand `README.md` with: prerequisites (macOS, OmniFocus running), install, MCP client configuration snippet, the list of tools delivered in this change, the loud warning about integration tests mutating real data and the sync preflight
+- [x] 9.2 Add `CONTRIBUTING.md` documenting the snippet authoring rules (the `__ARGS__` placeholder, no other interpolation, paste-to-console workflow) and the forbidden-scripting-dictionary rule from execution-runtime spec
+
+## 10. Verification
+
+- [x] 10.1 Run `npm run typecheck` (or `tsc --noEmit`) clean
+- [x] 10.2 Run `npm run test` (unit suite) clean
+- [x] 10.3 Manually run integration suite against a real OmniFocus with sync disabled; verify fixture folder is created and torn down
+- [x] 10.4 Manually connect the server to an MCP client (Claude Desktop or equivalent) and invoke each of the nine tools against a real database; verify results match the spec scenarios
+- [x] 10.5 Confirm all spec scenarios in `specs/execution-runtime/spec.md` and `specs/identity-resolution/spec.md` have corresponding test coverage (unit + integration)

package/openspec/changes/archive/2026-04-09-folder-crud/.openspec.yaml

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

package/openspec/changes/archive/2026-04-09-folder-crud/design.md

@@ -0,0 +1,58 @@
+## Context
+
+Folders in OmniJS are simpler than tasks or projects — they have only `name` and `status` as meaningful writable properties, and they nest via parent/child relationships. The main complexity is deletion: `deleteObject(folder)` leaves an empty shell (as discovered during bootstrap integration testing); the snippet must recursively delete contents first.
+
+OmniJS folder write operations:
+- `new Folder(name)` — creates a top-level folder (auto-inserted at root)
+- `new Folder(name, folderObject)` — creates a nested folder inside `folderObject`
+- `folder.name = "..."` — rename
+- `deleteObject(folder)` — removes folder shell but NOT contents; must delete contents first
+- Recursive deletion pattern (established in bootstrap fixtures): delete all projects in folder, recurse child folders, then delete the folder itself
+
+## Goals / Non-Goals
+
+**Goals:**
+- Create top-level and nested folders
+- Rename folders
+- Delete folders with full recursive cascade (projects, tasks, child folders)
+
+**Non-Goals:**
+- Moving a folder to a different parent (separate `move-operations` change)
+- Changing folder status directly (OmniFocus manages active/dropped based on contents)
+
+## Decisions
+
+### Decision 1: Recursive deletion in the snippet
+
+The snippet for `delete_folder` must implement recursive deletion rather than relying on `deleteObject` to cascade. The pattern is:
+
+```
+function deleteFolder(f) {
+  f.flattenedProjects.forEach(p => deleteObject(p));
+  f.folders.forEach(child => deleteFolder(child));
+  deleteObject(f);
+}
+```
+
+This was validated during bootstrap integration testing (`fixtures.ts` uses this exact pattern).
+
+### Decision 2: `create_folder` placement via optional `parentFolderId`
+
+- `parentFolderId` omitted → top-level folder
+- `parentFolderId` provided → nested inside that folder
+
+`new Folder(name)` for top-level; `new Folder(name, parentFolder)` for nested. Snippet resolves the parent by ID.
+
+### Decision 3: No `edit_folder` status field
+
+Folder status (`active` / `dropped`) in OmniFocus reflects whether the folder has active contents — it is not directly user-settable in the same way as project status. `edit_folder` exposes only `name`. If this proves insufficient in practice it can be extended.
+
+### Decision 4: `delete_folder` tool description is the strongest warning in the server
+
+This is the most destructive single operation: one call can delete an entire project hierarchy. The tool description must explicitly state that all child folders, projects, and tasks are permanently deleted, and that the AI must confirm with the user before calling it.
+
+## Risks / Trade-offs
+
+- **`deleteObject` on folder leaves shell** — confirmed behavior; recursive snippet pattern mitigates this fully.
+- **Deleting a folder containing hundreds of projects** — could be slow inside `evaluateJavascript`; the 30s timeout applies. Not worth special-casing in v1.
+- **Race between read and delete** — if the user reads a folder ID then calls delete, OmniFocus has no transaction isolation. Acceptable for a single-user desktop app.

package/openspec/changes/archive/2026-04-09-folder-crud/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+The bootstrap change delivered read-only folder access. Callers can traverse the folder hierarchy but cannot create, rename, or delete folders — blocking any workflow that involves organizing projects into folders.
+
+## What Changes
+
+- Add `create_folder` tool: create a folder at the top level or nested inside an existing folder
+- Add `edit_folder` tool: rename a folder
+- Add `delete_folder` tool: permanently delete a folder and all its contents — projects, tasks, and child folders (tool description instructs the AI to confirm with the user before invoking and calls out the destructive cascade)
+
+## Capabilities
+
+### New Capabilities
+
+- `folder-write`: Create, rename, and permanently delete OmniFocus folders
+
+### Modified Capabilities
+
+_(none — existing `folder-management` read requirements are unchanged)_
+
+## Impact
+
+- 3 new MCP tools registered in `src/server.ts`
+- 3 new tool handler files in `src/tools/`
+- 3 new OmniJS snippets in `src/snippets/`
+- `ALLOWED_SNIPPETS` allowlist in `src/runtime/snippetLoader.ts` must be extended
+- Integration tests will mutate real OmniFocus data (scoped to fixture folder per existing pattern)
+- `delete_folder` is the most destructive single operation in the server — the tool description warrants an explicit warning that the entire subtree (child folders, projects, and all tasks) is permanently removed

package/openspec/changes/archive/2026-04-09-folder-crud/specs/folder-write/spec.md

@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Create folder
+
+The system SHALL provide a `create_folder` tool that creates a new OmniFocus folder and returns its full detail record. The tool SHALL accept `{name: string, parentFolderId?: string}`. If `parentFolderId` is provided the folder SHALL be created nested inside that folder; otherwise it SHALL be created at the top level.
+
+#### Scenario: Create top-level folder
+- **WHEN** `create_folder` is called with `{name: "Work"}` and no `parentFolderId`
+- **THEN** the tool creates the folder at the top level and returns its full detail record including a stable `id`
+
+#### Scenario: Create nested folder
+- **WHEN** `create_folder` is called with `{name: "Active", parentFolderId: "abc123"}`
+- **THEN** the tool creates the folder inside the specified parent folder and returns its full detail record with `path` reflecting the full ancestor chain
+
+#### Scenario: Non-existent parent folder returns not-found error
+- **WHEN** `create_folder` is called with a `parentFolderId` that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Edit folder
+
+The system SHALL provide an `edit_folder` tool that renames an existing folder and returns its updated full detail record. The tool SHALL accept `{id: string, name: string}`.
+
+#### Scenario: Rename a folder
+- **WHEN** `edit_folder` is called with `{id: "abc123", name: "Personal"}`
+- **THEN** the folder's name is updated and the tool returns the updated detail record with the new name reflected in `path`
+
+#### Scenario: Non-existent folder returns not-found error
+- **WHEN** `edit_folder` is called with an ID that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Delete folder
+
+The system SHALL provide a `delete_folder` tool that permanently and recursively deletes a folder, all child folders, all projects within those folders, and all tasks within those projects. The tool description SHALL instruct the AI to confirm with the user before invoking, explicitly stating that the entire subtree — child folders, projects, and all tasks — is permanently deleted and cannot be undone.
+
+#### Scenario: Delete a folder and all its contents
+- **WHEN** `delete_folder` is called with the ID of an existing folder
+- **THEN** the folder, all descendant folders, all projects within those folders, and all tasks within those projects are permanently removed from OmniFocus and the tool returns a confirmation envelope
+
+#### Scenario: Delete empty folder
+- **WHEN** `delete_folder` is called with the ID of a folder that contains no projects or child folders
+- **THEN** the folder is removed and the tool returns a confirmation envelope
+
+#### Scenario: Non-existent folder returns not-found error
+- **WHEN** `delete_folder` is called with an ID that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error

package/openspec/changes/archive/2026-04-09-folder-crud/tasks.md

@@ -0,0 +1,41 @@
+## 1. Snippets (src/snippets/)
+
+- [x] 1.1 `create_folder.js`: accept `{name, parentFolderId?}`; if `parentFolderId` provided resolve parent by ID and throw `NotFoundError` if missing; create `new Folder(name)` or `new Folder(name, parentFolder)`; return full folder detail envelope
+- [x] 1.2 `edit_folder.js`: accept `{id, name}`; resolve folder by ID; assign `folder.name = name`; return updated full folder detail envelope
+- [x] 1.3 `delete_folder.js`: accept `{id}`; resolve folder by ID; recursively delete contents (projects then child folders) then `deleteObject(folder)`; return `{ok: true, data: {id}}`
+
+## 2. Snippet allowlist
+
+- [x] 2.1 Add `create_folder`, `edit_folder`, `delete_folder` to `ALLOWED_SNIPPETS` in `src/runtime/snippetLoader.ts`
+
+## 3. Schemas (src/schemas/shapes.ts)
+
+- [x] 3.1 Define `CreateFolderInput` zod schema: `{name: z.string().min(1), parentFolderId: IdSchema.optional()}`
+- [x] 3.2 Define `EditFolderInput` zod schema: `{id: IdSchema, name: z.string().min(1)}`
+
+## 4. Tool handlers (src/tools/)
+
+- [x] 4.1 `createFolder.ts`: validate input with `CreateFolderInput`; invoke `runSnippet("create_folder", args)`; validate result against `FolderDetail`; return
+- [x] 4.2 `editFolder.ts`: validate input with `EditFolderInput`; invoke `runSnippet("edit_folder", args)`; validate result against `FolderDetail`; return
+- [x] 4.3 `deleteFolder.ts`: input `{id: IdSchema}`; tool description MUST state the AI should confirm with the user before invoking and explicitly note that the entire subtree — child folders, projects, and all tasks — is permanently deleted; invoke `runSnippet("delete_folder", {id})`; return confirmation
+
+## 5. Server registration
+
+- [x] 5.1 Export all three new tool definitions from `src/tools/index.ts`
+
+## 6. Unit tests (test/unit/)
+
+- [x] 6.1 `schemas.createFolder.test.ts`: valid inputs pass; empty name rejected
+
+## 7. Integration tests (test/integration/)
+
+- [x] 7.1 `createFolder.int.test.ts`: create top-level folder; create nested folder; verify `path` and `parentId`
+- [x] 7.2 `editFolder.int.test.ts`: rename a folder; verify `name` and `path` updated
+- [x] 7.3 `deleteFolder.int.test.ts`: create folder with child project and tasks; delete folder; verify `get_folder` returns not-found and projects are gone
+
+## 8. Verification
+
+- [x] 8.1 `npm run typecheck` clean
+- [x] 8.2 `npm test` (unit suite) clean
+- [x] 8.3 Manually run integration suite; verify fixture cleanup
+- [ ] 8.4 Connect to Claude Desktop; exercise all three tools against a real database

package/openspec/changes/archive/2026-04-09-folder-tag-list-filtering/.openspec.yaml

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

package/openspec/changes/archive/2026-04-09-folder-tag-list-filtering/design.md

@@ -0,0 +1,38 @@
+## Context
+
+`list_folders` and `list_tags` are the last two list tools without filtering or limit support. The pattern established by `list_tasks` and `list_projects` — filter inside the OmniJS snippet, expose filter object and limit from the TypeScript handler — applies directly.
+
+Unlike tasks and projects, there is no universally agreed "terminal" status for folders (dropped folders are unusual but valid to show) or tags (onHold tags are actively used). Therefore the default behavior includes all statuses; filtering is opt-in.
+
+## Goals / Non-Goals
+
+**Goals:**
+- `list_folders`: add `limit` (default 200) and optional `status` filter (`active` | `dropped`)
+- `list_tags`: add `limit` (default 200) and optional `status` filter (`active` | `onHold` | `dropped`)
+
+**Non-Goals:**
+- `parentId` / subtree scoping for folders or tags (flat list is sufficient in practice)
+- Filtering by name or path pattern
+- Pagination
+
+## Decisions
+
+### Decision 1: No default status exclusion
+
+Unlike `list_tasks` and `list_projects`, the default returns all statuses. Dropped folders/tags are uncommon enough that including them doesn't overwhelm results, and an LLM may need to see them. Callers can pass `status: ["active"]` to filter.
+
+### Decision 2: Single status value, not array
+
+For `list_folders` and `list_tags`, a single `status` string (not an array) is sufficient — users rarely need "active OR onHold" for tags. Simpler API. If multi-status becomes needed, it's a non-breaking addition later.
+
+### Decision 3: Limit default 200
+
+Folders and tags are fewer than tasks; 200 is generous. Consistent with the spirit of existing defaults (tasks: 200, projects: 100).
+
+### Decision 4: Same filter-in-snippet pattern
+
+All filtering in the OmniJS snippet before data crosses the JXA bridge. TypeScript layer validates and passes through. Consistent with list_tasks and list_projects.
+
+## Risks / Trade-offs
+
+- **Minimal risk** — purely additive. Existing callers passing no args get all items (same as before but now capped at 200, which is a minor behavior change). Acceptable.

package/openspec/changes/archive/2026-04-09-folder-tag-list-filtering/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+`list_folders` and `list_tags` return all items with no way to cap results or filter by status. While folders and tags are typically fewer than tasks or projects, users with large databases may have hundreds of tags (including dropped ones). Adding `limit` and optional `status` filtering completes the filtering pattern applied to `list_tasks` and `list_projects`.
+
+## What Changes
+
+- Add `limit` parameter to `list_folders` (default 200)
+- Add `status` filter to `list_folders`: when provided, restrict to folders with that status (`active` or `dropped`); when omitted, return all folders
+- Add `limit` parameter to `list_tags` (default 200)
+- Add `status` filter to `list_tags`: when provided, restrict to tags with that status (`active`, `onHold`, or `dropped`); when omitted, return all tags
+- All filtering happens inside the OmniJS snippet
+
+## Capabilities
+
+### New Capabilities
+
+_(none)_
+
+### Modified Capabilities
+
+- `folder-management`: `list_folders` gains `limit` and optional `status` filter
+- `tag-management`: `list_tags` gains `limit` and optional `status` filter
+
+## Impact
+
+- `src/schemas/shapes.ts`: add `ListFoldersFilter` and `ListTagsFilter` schemas
+- `src/schemas/index.ts`: export new filter schemas
+- `src/snippets/list_folders.js`, `list_tags.js`: add filter + limit logic
+- `src/tools/listFolders.ts`, `listTags.ts`: add filter + limit params
+- Unit and integration tests for both tools

package/openspec/changes/archive/2026-04-09-folder-tag-list-filtering/specs/folder-management/spec.md

@@ -0,0 +1,21 @@
+## MODIFIED Requirements
+
+### Requirement: List folders
+
+The system SHALL provide a `list_folders` tool that returns folders in the OmniFocus database as an array of summaries, each containing `{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"`. The tool SHALL accept an optional `status` filter string and an optional `limit` integer (default 200). When `status` is omitted, all folders are returned regardless of status. When `limit` is omitted, at most 200 folders are returned.
+
+#### Scenario: All folders returned by default
+- **WHEN** `list_folders` is called with no arguments
+- **THEN** the tool returns all folders (active and dropped) up to the limit
+
+#### 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
+
+#### Scenario: Filter by status returns only matching folders
+- **WHEN** `list_folders` is called with `{ filter: { status: "active" } }`
+- **THEN** only active folders are returned
+
+#### Scenario: Limit caps the number of returned folders
+- **WHEN** `list_folders` is called with `{ limit: 5 }`
+- **THEN** at most 5 folders are returned

package/openspec/changes/archive/2026-04-09-folder-tag-list-filtering/specs/tag-management/spec.md

@@ -0,0 +1,21 @@
+## MODIFIED Requirements
+
+### Requirement: List tags
+
+The system SHALL provide a `list_tags` tool that returns tags in the OmniFocus database as an array of summaries, each containing `{id, name, path, parentId, status}`. Tags form a tree in OmniFocus; the `path` field SHALL use the canonical ` ▸ ` separator and represent the full ancestor chain. The `parentId` field SHALL be `null` for top-level tags. The `status` field SHALL be one of `"active" | "onHold" | "dropped"`. The tool SHALL accept an optional `status` filter string and an optional `limit` integer (default 200). When `status` is omitted, all tags are returned regardless of status. When `limit` is omitted, at most 200 tags are returned.
+
+#### Scenario: All tags returned by default
+- **WHEN** `list_tags` is called with no arguments
+- **THEN** the tool returns all tags (active, onHold, and dropped) up to the limit
+
+#### Scenario: On-hold tag is reported with correct status
+- **WHEN** the database contains a tag that has been placed on hold
+- **THEN** that tag appears in the result with `status: "onHold"`
+
+#### Scenario: Filter by status returns only matching tags
+- **WHEN** `list_tags` is called with `{ filter: { status: "active" } }`
+- **THEN** only active tags are returned
+
+#### Scenario: Limit caps the number of returned tags
+- **WHEN** `list_tags` is called with `{ limit: 5 }`
+- **THEN** at most 5 tags are returned

package/openspec/changes/archive/2026-04-09-folder-tag-list-filtering/tasks.md

@@ -0,0 +1,35 @@
+## 1. Schema changes (src/schemas/)
+
+- [x] 1.1 Define `ListFoldersFilter` zod schema: `{ status: FolderStatus.optional() }` in `shapes.ts`
+- [x] 1.2 Define `ListTagsFilter` zod schema: `{ status: TagStatus.optional() }` in `shapes.ts`
+- [x] 1.3 Export `ListFoldersFilter` and `ListTagsFilter` from `src/schemas/index.ts`
+
+## 2. Snippet updates (src/snippets/)
+
+- [x] 2.1 Update `list_folders.js`: add `filter` and `limit` args; apply status filter when `args.filter?.status` is provided; apply limit (default 200) as slice after filter
+- [x] 2.2 Update `list_tags.js`: add `filter` and `limit` args; apply status filter when `args.filter?.status` is provided; apply limit (default 200) as slice after filter
+
+## 3. Tool handler updates (src/tools/)
+
+- [x] 3.1 Update `listFolders.ts`: add `filter: ListFoldersFilter.optional()` and `limit: z.number().int().positive().optional()` to schema; pass through to `runSnippet`; update description
+- [x] 3.2 Update `listTags.ts`: add `filter: ListTagsFilter.optional()` and `limit: z.number().int().positive().optional()` to schema; pass through to `runSnippet`; update description
+
+## 4. Unit tests (test/unit/)
+
+- [x] 4.1 Add schema tests for `ListFoldersFilter`: valid with status "active"; valid with status "dropped"; valid empty; invalid status value rejected
+- [x] 4.2 Add schema tests for `ListTagsFilter`: valid with status "active"; valid with status "onHold"; valid with status "dropped"; valid empty; invalid status value rejected
+
+## 5. Integration tests (test/integration/)
+
+- [x] 5.1 `listFoldersFiltered.int.test.ts`: verify status filter returns only folders with that status
+- [x] 5.2 `listFoldersFiltered.int.test.ts`: verify limit caps results
+- [x] 5.3 `listFoldersFiltered.int.test.ts`: verify no filter returns all folders (including dropped)
+- [x] 5.4 `listTagsFiltered.int.test.ts`: verify status filter returns only tags with that status
+- [x] 5.5 `listTagsFiltered.int.test.ts`: verify limit caps results
+- [x] 5.6 `listTagsFiltered.int.test.ts`: verify no filter returns all tags
+
+## 6. Verification
+
+- [x] 6.1 `npm run typecheck` clean
+- [x] 6.2 `npm test` (unit suite) clean
+- [x] 6.3 Manually run integration suite

package/openspec/changes/archive/2026-04-09-move-operations/.openspec.yaml

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

package/openspec/changes/archive/2026-04-09-move-operations/design.md

@@ -0,0 +1,43 @@
+## Context
+
+OmniFocus supports moving tasks between containers (projects or parent tasks) and moving projects between folders via the `moveSections` and `append`/`prepend` OmniJS APIs. Currently no MCP tool exposes this capability.
+
+The OmniJS API for moving: `moveTasks([task], destination)` where destination is a `Project` or `Task`. For projects: `moveProjects([project], folder)` where folder is a `Folder` or `null` for top-level. Direct property assignment (`task.containingProject`, `project.parentFolder`) is read-only and does not work.
+
+## Goals / Non-Goals
+
+**Goals:**
+- `move_task`: move a task to a project (top-level) or make it a subtask of another task
+- `move_project`: move a project to a folder or to the top level
+
+**Non-Goals:**
+- Moving folders (rename/reparent of folders — separate concern)
+- Reordering within a container (OmniJS exposes position but it's complex)
+- Moving tags
+
+## Decisions
+
+### Decision 1: move_task requires exactly one destination
+
+`move_task` accepts `{ id, projectId?, parentTaskId? }`. Exactly one of `projectId` or `parentTaskId` must be provided — enforced by Zod `.refine()` at the TypeScript boundary and validated again in the snippet. Returns the updated task summary.
+
+### Decision 2: Moving to a project places task at end of project's task list
+
+OmniJS `task.containingProject = project` places the task at the end. This is the natural default; no position parameter needed.
+
+### Decision 3: move_project accepts folderId as string or null
+
+`null` means move to top level (no parent folder). OmniJS: `project.parentFolder = null` removes the folder assignment.
+
+### Decision 4: Not-found errors for all ID lookups
+
+Same pattern as existing write tools: `NotFoundError` if task, project, folder, or parentTask ID is not found. Snippet throws; bridge catches and wraps as `ExecutionError`.
+
+### Decision 5: Return updated summary, not full detail
+
+`move_task` returns a `TaskSummary`. `move_project` returns a `ProjectSummary`. Consistent with create/edit patterns.
+
+## Risks / Trade-offs
+
+- **OmniJS assignment semantics** — setting `task.containingProject` may behave differently than `task.parentTask`. Both need integration testing to verify the task ends up in the right place.
+- **Inbox tasks** — moving an inbox task to a project is valid and expected to work. Moving a project task to inbox is not supported (OmniJS doesn't expose inbox assignment on tasks directly). Document this limitation.

package/openspec/changes/archive/2026-04-09-move-operations/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+There is no way to move a task to a different project or make it a subtask, and no way to move a project to a different folder. These are common reorganization actions in OmniFocus that an LLM assistant should be able to perform on the user's behalf.
+
+## What Changes
+
+- Add `move_task` tool: moves a task to a project (top-level) or makes it a subtask of another task
+- Add `move_project` tool: moves a project to a folder or to the top level
+
+## Capabilities
+
+### New Capabilities
+
+- `move-operations`: moving tasks between projects/parents and moving projects between folders
+
+### Modified Capabilities
+
+_(none — new tools, no existing requirement changes)_
+
+## Impact
+
+- `src/snippets/move_task.js`, `src/snippets/move_project.js`: new OmniJS snippets
+- `src/tools/moveTask.ts`, `src/tools/moveProject.ts`: new tool handlers
+- `src/tools/index.ts`: register new tools
+- `src/runtime/snippetLoader.ts`: allowlist new snippet names

package/openspec/changes/archive/2026-04-09-move-operations/specs/move-operations/spec.md

@@ -0,0 +1,41 @@
+## Requirements
+
+### Requirement: Move task to a new container
+
+The system SHALL provide a `move_task` tool that accepts `{id: string, projectId?: string, parentTaskId?: string}` and moves the specified task to the given container. Exactly one of `projectId` or `parentTaskId` SHALL be provided; if both or neither are given, the tool SHALL return a validation error. When `projectId` is provided, the task SHALL become a top-level task in that project. When `parentTaskId` is provided, the task SHALL become a direct subtask of that task. The tool SHALL return a structured not-found error if any of the IDs do not correspond to existing objects.
+
+#### Scenario: Move task to a project
+- **WHEN** `move_task` is called with `{id: "t1", projectId: "p2"}`
+- **THEN** the task appears as a top-level task in project p2 and is no longer in its previous container
+
+#### Scenario: Make task a subtask
+- **WHEN** `move_task` is called with `{id: "t1", parentTaskId: "t2"}`
+- **THEN** the task becomes a direct child of task t2
+
+#### Scenario: Both destinations provided is a validation error
+- **WHEN** `move_task` is called with both `projectId` and `parentTaskId`
+- **THEN** the tool returns a validation error before any snippet executes
+
+#### Scenario: Non-existent task ID returns not-found error
+- **WHEN** `move_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Move project to a folder
+
+The system SHALL provide a `move_project` tool that accepts `{id: string, folderId: string | null}` and moves the specified project to the given folder. When `folderId` is `null`, the project SHALL be moved to the top level (no containing folder). The tool SHALL return a structured not-found error if the project ID or folder ID does not correspond to an existing object.
+
+#### Scenario: Move project to a folder
+- **WHEN** `move_project` is called with `{id: "p1", folderId: "f2"}`
+- **THEN** the project is now contained within folder f2
+
+#### Scenario: Move project to top level
+- **WHEN** `move_project` is called with `{id: "p1", folderId: null}`
+- **THEN** the project has no parent folder
+
+#### Scenario: Non-existent project ID returns not-found error
+- **WHEN** `move_project` is called with a project ID that does not exist
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Non-existent folder ID returns not-found error
+- **WHEN** `move_project` is called with a folderId that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error