omnifocus-operator 1.4__tar.gz

omnifocus_operator-1.4/.gitignore

@@ -0,0 +1,48 @@
+# Claude Code (personal/auto-generated)
+.claude/settings.local.json
+.claude/keybindings.json
+.claude/projects/
+CLAUDE.local.md
+.mcp.json
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+src/omnifocus_operator/_version.py
+
+# Virtual environments
+.venv/
+venv/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Testing / Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# Node (bridge/ test project)
+node_modules/
+
+# Sandbox (local scratch files)
+.sandbox/
+
+.research/deep-dives/portfolio/working-files/
+
+# Local overrides
+justfile.local
+
+# OS
+.DS_Store
+.claude/worktrees/

omnifocus_operator-1.4/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.4
+    hooks:
+      - id: ruff-check
+        name: ruff check (full repo)
+        args: [--fix]
+        pass_filenames: false
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src/
+        language: system
+        types: [python]
+        require_serial: true
+        pass_filenames: false

omnifocus_operator-1.4/.python-version

@@ -0,0 +1 @@
+3.12

omnifocus_operator-1.4/.vscode/launch.json

@@ -0,0 +1,44 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Current Test File",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "args": [
+        "${file}",
+        "-v",
+        "--no-cov",
+        "--timeout=0"
+      ],
+      "justMyCode": false
+    },
+    {
+      "name": "Debug Current Test (cursor on it)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "args": [
+        "${file}::${selectedText}",
+        "-v",
+        "--no-cov",
+        "--timeout=0"
+      ],
+      "justMyCode": false
+    },
+    {
+      "name": "Debug All Tests",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "pytest",
+      "args": [
+        "tests/",
+        "-v",
+        "--no-cov",
+        "--timeout=0"
+      ],
+      "justMyCode": false
+    }
+  ]
+}

omnifocus_operator-1.4/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to OmniFocus Operator are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/). Versions follow semantic versioning.
+
+## [Unreleased]
+
+### Added
+- PyPI publishing via `uvx omnifocus-operator`
+- Dynamic versioning with `hatch-vcs` (git tags as source of truth)
+- Platform check — non-macOS prints clear error and exits
+
+## [1.3.3] - Ordering & Move Fix
+
+### Added
+- `order` field on task responses — 1-based integer reflecting outline order within parent
+
+### Fixed
+- `moveTo beginning/ending` on same container no longer silently ignored
+- Move no-op warning now checks ordinal position, not just container membership
+
+## [1.3.2] - Date Filtering
+
+### Added
+- Date filters on `list_tasks`: `due`, `defer`, `planned`, `completed`, `dropped`, `added`, `modified`
+- String shortcuts: `"today"`, `"overdue"`, `"soon"`, `"any"`, `"none"`
+- Shorthand periods: `{this: "w"}`, `{last: "3d"}`, `{next: "1m"}`
+- Absolute bounds: `{after: "...", before: "..."}`
+- Configurable due-soon threshold (`OPERATOR_DUE_SOON`)
+
+### Changed
+- `urgency` filter removed — absorbed into `due: "overdue"` and `due: "soon"`
+- `completed` boolean filter replaced by `completed` date filter
+
+## [1.3.1] - First-Class References
+
+### Added
+- `$inbox` system location — explicit inbox representation across all API surfaces
+- Name-based entity resolution: `parent: "My Project"`, `ending: "Work"` (case-insensitive substring match)
+- Rich `{id, name}` references on all output models
+- `project` field on Task output — containing project at any nesting depth
+
+### Changed
+- `parent` field on Task changed from `ParentRef` to tagged `{"project": {...}}` or `{"task": {...}}`
+- Inbox tasks use `ProjectRef(id="$inbox", name="Inbox")` — parent is never null
+- `inInbox` removed from Task output (derivable from `project.id == "$inbox"`)
+
+## [1.3.0] - Read Tools
+
+### Added
+- `list_tasks` — filter by inbox, flagged, project, tags, availability, search, with pagination
+- `list_projects` — filter by status, folder, review schedule, flags
+- `list_tags` — filter by status
+- `list_folders` — filter by status
+- `list_perspectives` — list all perspectives
+- SQL WHERE clause filtering against SQLite cache (<6ms filtered queries)
+
+## [1.2.3] - Repetition Rules
+
+### Added
+- Repetition rule support on `add_tasks` and `edit_tasks`
+- 8 structured frequency types: daily, weekly, monthly variants, yearly
+- Partial update semantics for rule modifications
+
+### Changed
+- Read model returns structured frequency fields instead of raw `ruleString`
+
+## [1.2.2] - FastMCP v3 Migration
+
+### Added
+- Progress reporting for batch operations
+- Dual-handler logging: stderr + `~/Library/Logs/omnifocus-operator.log`
+- `ToolLoggingMiddleware` for automatic tool call logging
+
+### Changed
+- Migrated from `mcp.server.fastmcp` to standalone `fastmcp>=3`
+- Test client simplified via `async with Client(server)`
+
+## [1.2.1] - Architectural Cleanup
+
+### Changed
+- Unified service-repository write interface
+- Service layer decomposed into orchestration + extracted modules
+- Write models reject unknown fields (`extra="forbid"`)
+
+## [1.2.0] - Writes & Lookups
+
+### Added
+- `get_task` — single task lookup by ID with computed fields
+- `get_project` — single project lookup by ID
+- `get_tag` — single tag lookup by ID
+- `add_tasks` — create tasks with full field control
+- `edit_tasks` — patch semantics (omit = no change, null = clear, value = set)
+- Tag editing modes: replace, add, remove
+- Task movement and lifecycle changes (complete/drop/reactivate)
+
+## [1.1.0] - Performance
+
+### Added
+- `HybridRepository` — reads from OmniFocus SQLite cache (~46ms full snapshot, 30–60x faster)
+- WAL-based read-after-write freshness detection
+- Repository protocol with pluggable implementations
+
+### Changed
+- Two-axis status model (Urgency + Availability) replacing single-winner enums
+
+## [1.0.0] - Foundation
+
+### Added
+- `get_all` tool — full OmniFocus database snapshot as structured data
+- Three-layer architecture: MCP Server → Service → Repository
+- Pluggable bridge abstraction: InMemoryBridge, SimulatorBridge, RealBridge
+- File-based IPC engine with OmniJS bridge script
+- Error-serving degraded mode for headless servers

omnifocus_operator-1.4/CLAUDE.md

@@ -0,0 +1,60 @@
+# OmniFocus Operator
+
+An MCP server exposing OmniFocus as structured task infrastructure for AI agents.
+
+See @README.md for project overview.
+
+## Naming
+
+- Prose: "OmniFocus Operator"
+- Slug: `omnifocus-operator`
+
+## Repository
+
+- GitHub: https://github.com/HelloThisIsFlo/omnifocus-operator
+- Public repo
+
+## Safety Rules
+
+- **SAFE-01**: No automated test, CI pipeline, or agent execution may touch `RealBridge`. All automated testing MUST use `InMemoryBridge` or `SimulatorBridge` exclusively. The bridge factory (`create_bridge("real")`) raises `RuntimeError` when `PYTEST_CURRENT_TEST` is set. CI enforces this via grep.
+  - In comments and docstrings, write `the real Bridge` (two words) instead of `RealBridge` — CI greps for the literal class name and will flag it.
+- **SAFE-02**: `RealBridge` interaction is manual UAT only, performed by the human user against their live OmniFocus database. UAT scripts live in `uat/` and must NEVER be run by agents or CI. The `uat/` directory is excluded from pytest discovery and CI execution.
+
+## Service Layer Convention
+
+- All service use cases use the **Method Object pattern** — see `docs/architecture.md` "Method Object Pattern" for full details
+- Every use case gets a `_VerbNounPipeline` class inheriting from `_Pipeline`
+- Read delegations (get_task, get_project, etc.) stay inline — one-liner pass-throughs, not pipelines
+- Mutable state on `self` is fine — the pipeline is created, executed, and discarded within a single call
+
+## UAT Guidelines
+
+- **Philosophy**: UAT answers "can I work with this codebase?" — not just "does it work." This means contract consistency, naming clarity, and architectural coherence are all in scope. Specifically:
+  - **Design discussions are first-class UAT outcomes.** When the developer spots an inconsistency (e.g., some filters use names, others use IDs), that's not a tangent — it's the point. Go deep: pros/cons, where it lives architecturally, whether to fix now or capture for later.
+  - **Proactively surface decisions.** Don't wait for the developer to ask "why did you do it this way?" — present each design choice with the alternatives considered. If every UAT step is mechanical ("does it import?", "does it serialize?"), the UAT is wrong. Every phase involves decisions — those decisions are what UAT validates.
+  - **UAT surfaces downstream decisions.** A contract inconsistency in the repo layer affects every layer above it. Catching it during repo UAT prevents locking in the wrong contract for service/server phases. Actively look for decisions that affect downstream phases.
+  - **Every design discussion ends with a concrete outcome**: a todo, a new requirement, a fix now, or a deliberate "this is fine" with reasoning. Never just "noted" and move on.
+  - **Don't rush past concerns.** If the developer wants to discuss, that's the most valuable part. Don't log-and-move-on. Don't defer to "future phases" when the developer says it's relevant now.
+- **Shared rules** (apply to both refactoring and feature UAT):
+  - Every step must include exact file path and line range — the developer jumps straight to the code, no searching.
+  - Adaptive granularity — split or merge steps based on scope. Small change = fewer steps. Large change = one step per semantic block.
+  - **New conventions** get their own step — one per new pattern introduced (base classes, protocols, extracted helpers), with a concrete example.
+- **Structural phases** (refactoring, new foundations, infrastructure — anything without user-facing behavior changes): UAT focuses on **developer experience and design decisions**, not "does it still work" (tests cover that). The overarching question: "does this make sense to the person who'll maintain it?"
+  - **Mechanical checks** (imports, values, serialization, test suite) run automatically. Report results in one line; don't present as interactive steps.
+  - Rooms to cover, as applicable:
+    - **Design decisions** — naming conventions, placement, patterns chosen, trade-offs vs alternatives. Present each for review. These are the core UAT steps.
+    - **Directory structure & public API** — show the final layout. If small, one step. If large, split per module with exports/signatures at each boundary.
+    - **Semantic code walkthrough** — walk through code by semantic block. Point the developer to the code and ask them to explain what it does. If their understanding is correct, pass. If not, the code isn't clear enough — that's a fail.
+    - **Naming audit** — for renamed things, show old → new grouped by domain.
+- **Feature phases**: UAT has two parts, in order:
+  1. **Test walkthrough** — Walk the developer through the tests room by room before running anything. Split by semantic domain, not by test class — e.g., for a filtering feature, separate steps for status/availability filters, join-based filters (tags, projects), date filters, simple filters, and pagination. The question is "do these tests exercise real scenarios, and do you see any gaps?"
+  2. **Run the suite** — Only after the walkthrough. Now `pytest` is meaningful because the developer has seen what's actually being verified.
+
+  End-to-end behavior testing (does the MCP tool work from the agent's perspective?) applies when the feature is wired all the way through. For repository-only or service-only phases, the test walkthrough IS the UAT.
+
+- **Client-side schema validation quirk**: Claude Desktop co-work mode pre-validates tool input against the JSON Schema before sending it to the server. Custom `field_validator` error messages may not appear — the client shows a generic schema error instead. This pre-validation is also depth-limited: shallow fields get caught, deeply nested fields may slip through. Both Claude Desktop (regular) and Claude Code CLI pass input directly to the server, so custom messages always show there. If the developer reports a missing custom error message during UAT, suggest testing via Claude Desktop or Claude Code. See `docs/model-taxonomy.md` for details.
+
+## Model Conventions
+
+- **Before creating any new Pydantic model**: Read `docs/model-taxonomy.md`. Models in `models/` use no suffix (core) or `Read` suffix (output-boundary variant). Models in `contracts/` must use a write-side suffix (`Command`, `Result`, `RepoPayload`, `RepoResult`, `Action`, `Spec`).
+- **After modifying any model that appears in tool output**: Run `uv run pytest tests/test_output_schema.py -x -q` to verify serialized output still validates against MCP outputSchema. This catches `@model_serializer` and `@field_serializer` additions that erase JSON Schema structure.

omnifocus_operator-1.4/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/HelloThisIsFlo/omnifocus-operator.git
+cd omnifocus-operator
+just setup    # installs deps + pre-commit hooks
+```
+
+Requires: Python 3.12+, [uv](https://docs.astral.sh/uv/), [just](https://just.systems/).
+
+## Project Structure
+
+```
+src/omnifocus_operator/
+├── server/          # MCP tool definitions (FastMCP v3)
+├── service/         # Business logic — method object pipelines
+├── repository/      # Data access — SQLite cache + OmniJS bridge
+├── contracts/       # Write-side Pydantic models (Command, Result, etc.)
+├── models/          # Core + read-side Pydantic models
+├── bridge/          # OmniJS IPC engine + bridge.js
+├── simulator/       # In-process OmniJS simulator for integration tests
+└── agent_messages/  # Agent-facing warnings and guidance text
+```
+
+Three-layer architecture: **MCP Server → Service → Repository**. All layers communicate through typed contracts.
+
+## Running Tests
+
+```bash
+just test-python           # Python test suite
+just test-js               # JS bridge tests
+just test-all              # Both
+just test-kw add_task      # Run by keyword (no quotes needed)
+just test-one tests/test_server.py  # Single file, no coverage
+just test-cov              # With HTML coverage report
+```
+
+## Quality Checks
+
+```bash
+just check-all    # test + lint + typecheck (full suite)
+just ci           # replicate CI pipeline locally
+just fix          # auto-fix lint and formatting
+just typecheck    # mypy with Pydantic plugin
+just lint         # ruff check + format (read-only)
+```
+
+Pre-commit hooks run lint, format, and type checks before each commit.
+
+## Key Conventions
+
+- **Service layer**: uses the [Method Object pattern](https://github.com/HelloThisIsFlo/omnifocus-operator/blob/main/docs/architecture.md) — each use case gets a `_VerbNounPipeline` class
+- **Models**: see `docs/model-taxonomy.md` — core models have no suffix, output variants use `Read`, write-side contracts use `Command`/`Result`/`Action`/`Spec`
+- **Testing**: `InMemoryBridge` for unit tests, `SimulatorBridge` for IPC integration. **Never** touch `RealBridge` in automated tests — the factory raises `RuntimeError` under pytest
+- **Extra fields forbidden**: write models use `extra="forbid"` so agents get errors, not silent drops
+
+## PR Process
+
+1. Fork and branch from `main`
+2. Write tests for new behavior
+3. Run `just ci` before pushing
+4. Open a PR — keep the description focused on *what* and *why*
+
+## Useful Commands
+
+| Command | Purpose |
+|---------|---------|
+| `just serve` | Start the MCP server (stdio) |
+| `just inspect` | Open MCP Inspector |
+| `just log` | Tail the operator log |
+| `just schema` | Dump MCP tool schemas to `.sandbox/` |
+| `just safety` | Verify no test references RealBridge |

omnifocus_operator-1.4/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: omnifocus-operator
+Version: 1.4
+Summary: MCP server exposing OmniFocus as structured task infrastructure for AI agents
+Project-URL: Homepage, https://hellothisisflo.github.io/omnifocus-operator
+Project-URL: Repository, https://github.com/HelloThisIsFlo/omnifocus-operator
+Project-URL: Issues, https://github.com/HelloThisIsFlo/omnifocus-operator/issues
+Author-email: Flo Kempenich <flo@kempenich.ai>
+License-Expression: LicenseRef-Proprietary
+Keywords: ai-agent,automation,macos,mcp,model-context-protocol,omnifocus,omnijs,productivity,sqlite,task-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=3.1.1
+Requires-Dist: pydantic-settings>=2.0
+Description-Content-Type: text/markdown
+
+# 🎯 OmniFocus Operator
+
+**The last OmniFocus MCP Server you'll ever need.**
+
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue?logo=python&logoColor=white)
+![Tests 2086](https://img.shields.io/badge/tests-2086-brightgreen)
+![Coverage 97%](https://img.shields.io/badge/coverage-97%25-brightgreen)
+![macOS only](https://img.shields.io/badge/platform-macOS-lightgrey?logo=apple)
+
+Production-grade MCP server exposing OmniFocus as structured task infrastructure for AI agents. Agent-first design, SQLite-cached performance, 2,086 tests.
+
+### [**→ See the full landing page**](https://hellothisisflo.github.io/omnifocus-operator) — features, architecture, benchmarks, and comparison
+
+---
+
+## 🚀 Quick Start
+
+**Prerequisites:** macOS, OmniFocus 4, Python 3.12+
+
+**Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "omnifocus-operator": {
+      "command": "uvx",
+      "args": ["omnifocus-operator"]
+    }
+  }
+}
+```
+
+That's it. No install step — `uvx` downloads, isolates, and runs the server automatically.
+
+**Or just ask your agent:**
+
+> Set up the OmniFocus Operator MCP server for me — uvx omnifocus-operator
+
+<details>
+<summary><strong>Development install (contributors)</strong></summary>
+
+```bash
+git clone https://github.com/HelloThisIsFlo/omnifocus-operator.git
+cd omnifocus-operator
+uv sync
+```
+
+See [CONTRIBUTING.md](https://github.com/HelloThisIsFlo/omnifocus-operator/blob/main/CONTRIBUTING.md) for dev workflow details.
+
+</details>
+
+---
+
+## ✨ Features
+
+- ⚡ **46ms reads** — SQLite caching gives 30–60x faster reads than bridge-only servers
+- 🛠️ **11 MCP tools** — lookups, filtered lists, task creation & editing
+- 🤖 **Agent-first design** — warnings that teach, errors that educate, guidance in every response
+- 🧪 **2,086 tests, 97% coverage** — strict mypy, no corners cut
+- 🛡️ **Graceful degradation** — server stays alive no matter what, always recoverable
+- 🔄 **Automatic fallback** — SQLite → OmniJS bridge when needed
+
+See the [full documentation](https://hellothisisflo.github.io/omnifocus-operator) for architecture details, examples, and deep dives.
+
+---
+
+## 🛠️ Available Tools
+
+### Lookups
+
+| Tool | Description |
+|------|-------------|
+| `get_all` | Full OmniFocus database as structured data (last-resort debugging) |
+| `get_task` | Single task by ID — urgency, availability, dates, tags, parent, project |
+| `get_project` | Single project by ID — status, review interval, next task |
+| `get_tag` | Single tag by ID — availability, parent hierarchy |
+
+### List & Filter
+
+| Tool | Description |
+|------|-------------|
+| `list_tasks` | Filter by date, availability, flags, tags, project, search — with pagination and field selection |
+| `list_projects` | Filter by status, folder, review schedule, flags |
+| `list_tags` | List tags with parent hierarchy |
+| `list_folders` | List folders with parent hierarchy |
+| `list_perspectives` | List custom perspectives |
+
+### Write
+
+| Tool | Description |
+|------|-------------|
+| `add_tasks` | Create tasks with full field control — parent, tags, dates, flags, notes, repetition rules |
+| `edit_tasks` | Patch semantics — update fields, move tasks, complete/drop, manage tags and repetition rules |
+
+All read tools are idempotent. Write tools reference projects and tags by name or ID.
+
+---
+
+## 🔍 Tool Examples
+
+**Filter tasks** (`list_tasks`):
+
+```json
+{
+  "query": {
+    "flagged": true,
+    "due": "soon",
+    "availability": "remaining",
+    "include": ["notes"],
+    "limit": 10
+  }
+}
+```
+
+**Create a task** (`add_tasks`):
+
+```json
+{
+  "items": [{
+    "name": "Review Q3 roadmap",
+    "parent": {"project": {"name": "Work Projects"}},
+    "tags": ["Planning"],
+    "dueDate": "2026-03-15T17:00:00",
+    "flagged": true,
+    "estimatedMinutes": 30,
+    "note": "Focus on v1.3-v1.5 milestones"
+  }]
+}
+```
+
+**Edit with patch semantics** (`edit_tasks`):
+
+```json
+{
+  "items": [{
+    "id": "oRx3bL_UYq7",
+    "addTags": ["Urgent"],
+    "dueDate": null,
+    "moveTo": {"ending": {"project": {"name": "Work Projects"}}}
+  }]
+}
+```
+
+**Patch semantics cheat sheet:**
+
+| Input | Meaning |
+|-------|---------|
+| Field omitted | No change |
+| Field set to `null` | Clear the value |
+| Field set to a value | Update |
+
+---
+
+## 🗺️ Roadmap
+
+| Version | Focus |
+|---------|-------|
+| **v1.0** | Foundation — read tools, three-layer arch, test suite ✅ |
+| **v1.1** | Performance — SQLite caching, 30–60x speedup ✅ |
+| **v1.2** | Writes & Lookups — add/edit tasks, get-by-ID ✅ |
+| **v1.2.1** | Architectural Cleanup — contracts, service refactor, golden master tests ✅ |
+| **v1.2.2** | FastMCP v3 Migration ✅ |
+| **v1.2.3** | Repetition Rule Write Support ✅ |
+| **v1.3** | Read Tools — SQL filtering, list/count, 5 new tools ✅ |
+| **v1.3.1** | First-Class References — name resolution, `$inbox`, rich refs ✅ |
+| **v1.3.2** | Date Filtering — 7 dimensions, shortcuts, calendar math ✅ |
+| **v1.3.3** | Task Ordering — dotted notation, outline order ✅ |
+| **v1.4** | Response Shaping & Batch Processing 🔧 |
+| **v1.5** | UI & Perspectives — perspective switching, deep links |
+| **v1.6** | Production Hardening — retry, crash recovery, serial execution |
+
+---
+
+## 🔗 Links
+
+- 📖 [Full Documentation](https://hellothisisflo.github.io/omnifocus-operator) — features, architecture, examples
+- 📦 [PyPI](https://pypi.org/project/omnifocus-operator/) — package page
+- 🐛 [Issues](https://github.com/HelloThisIsFlo/omnifocus-operator/issues)
+- 💬 [Discussions](https://github.com/HelloThisIsFlo/omnifocus-operator/discussions)
+
+---
+
+## 📄 License
+
+Proprietary — all rights reserved. Free to use, not to redistribute. License under review.
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](https://github.com/HelloThisIsFlo/omnifocus-operator/blob/main/CONTRIBUTING.md) for guidelines. In short: fork, branch, test, PR.