{"id":48528334,"url":"https://github.com/hellothisisflo/omnifocus-operator","last_synced_at":"2026-04-25T16:01:10.067Z","repository":{"id":339784931,"uuid":"1163364621","full_name":"HelloThisIsFlo/omnifocus-operator","owner":"HelloThisIsFlo","description":"An MCP server that exposes OmniFocus to AI agents via the Model Context Protocol (MCP).","archived":false,"fork":false,"pushed_at":"2026-04-24T00:16:36.000Z","size":11040,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-24T02:25:21.055Z","etag":null,"topics":["ai-agent","anthropic","automation","claude","llm","mcp","model-context-protocol","omnifocus","task-management"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HelloThisIsFlo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-21T14:18:27.000Z","updated_at":"2026-04-24T00:16:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/HelloThisIsFlo/omnifocus-operator","commit_stats":null,"previous_names":["hellothisisflo/omnifocus-operator"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/HelloThisIsFlo/omnifocus-operator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HelloThisIsFlo%2Fomnifocus-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HelloThisIsFlo%2Fomnifocus-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HelloThisIsFlo%2Fomnifocus-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HelloThisIsFlo%2Fomnifocus-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HelloThisIsFlo","download_url":"https://codeload.github.com/HelloThisIsFlo/omnifocus-operator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HelloThisIsFlo%2Fomnifocus-operator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32267710,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T09:15:33.318Z","status":"ssl_error","status_checked_at":"2026-04-25T09:15:31.997Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","automation","claude","llm","mcp","model-context-protocol","omnifocus","task-management"],"created_at":"2026-04-07T23:03:58.946Z","updated_at":"2026-04-25T16:01:10.061Z","avatar_url":"https://github.com/HelloThisIsFlo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎯 OmniFocus Operator\n\n**The last OmniFocus MCP Server you'll ever need.**\n\n![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue?logo=python\u0026logoColor=white)\n[![PyPI](https://img.shields.io/pypi/v/omnifocus-operator?logo=pypi\u0026logoColor=white\u0026color=blue)](https://pypi.org/project/omnifocus-operator/)\n![Tests 2558](https://img.shields.io/badge/tests-2558-brightgreen)\n![Coverage 97%](https://img.shields.io/badge/coverage-97%25-brightgreen)\n![macOS only](https://img.shields.io/badge/platform-macOS-lightgrey?logo=apple)\n\nProduction-grade MCP server exposing OmniFocus as structured task infrastructure for AI agents. Agent-first design, SQLite-cached performance, 2,558 tests.\n\n### [**→ See the full landing page**](https://hellothisisflo.github.io/omnifocus-operator) — features, architecture, benchmarks, and comparison\n\n---\n\n## 🚀 Quick Start\n\n**Prerequisites:** macOS, OmniFocus 4, Python 3.12+\n\n**Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"omnifocus-operator\": {\n      \"command\": \"uvx\",\n      \"args\": [\"omnifocus-operator\"]\n    }\n  }\n}\n```\n\nThat's it. No install step — `uvx` downloads, isolates, and runs the server automatically.\n\n**Or just ask your agent:**\n\n\u003e Set up the OmniFocus Operator MCP server for me — uvx omnifocus-operator\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDevelopment install (contributors)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/HelloThisIsFlo/omnifocus-operator.git\ncd omnifocus-operator\nuv sync\n```\n\nSee [CONTRIBUTING.md](https://github.com/HelloThisIsFlo/omnifocus-operator/blob/main/CONTRIBUTING.md) for dev workflow details.\n\n\u003c/details\u003e\n\n---\n\n## ✨ Features\n\n- ⚡ **46ms reads** — SQLite caching gives 30–60x faster reads than bridge-only servers\n- 🛠️ **11 MCP tools** — lookups, filtered lists, task creation \u0026 editing\n- 🤖 **Agent-first design** — warnings that teach, errors that educate, guidance in every response\n- 🧪 **2,558 tests, 97% coverage** — strict mypy, no corners cut\n- 🛡️ **Graceful degradation** — server stays alive no matter what, always recoverable\n- 🔄 **Automatic fallback** — SQLite → OmniJS bridge when needed\n\nSee the [full documentation](https://hellothisisflo.github.io/omnifocus-operator) for architecture details, examples, and deep dives.\n\n---\n\n## 🛠️ Available Tools\n\n### Lookups\n\n| Tool | Description |\n|------|-------------|\n| `get_all` | Full OmniFocus database as structured data (last-resort debugging) |\n| `get_task` | Single task by ID — urgency, availability, dates, tags, parent, project |\n| `get_project` | Single project by ID — status, review interval, next task |\n| `get_tag` | Single tag by ID — availability, parent hierarchy |\n\n### List \u0026 Filter\n\n| Tool | Description |\n|------|-------------|\n| `list_tasks` | Filter by date, availability, flags, tags, project, parent subtree, search — with pagination, field selection, and presence-flag derivation |\n| `list_projects` | Filter by status, folder, review schedule, flags |\n| `list_tags` | List tags with parent hierarchy |\n| `list_folders` | List folders with parent hierarchy |\n| `list_perspectives` | List custom perspectives |\n\n### Write\n\n| Tool | Description |\n|------|-------------|\n| `add_tasks` | Create tasks with full field control — parent, tags, dates, flags, notes, repetition rules, parallel/sequential, completes-with-children |\n| `edit_tasks` | Patch semantics — update fields, move tasks, complete/drop, manage tags, repetition rules, and hierarchy properties |\n\nAll read tools are idempotent. Write tools reference projects and tags by name or ID.\n\n---\n\n## 🔍 Tool Examples\n\n**Filter tasks** (`list_tasks`):\n\n```json\n{\n  \"query\": {\n    \"flagged\": true,\n    \"due\": \"soon\",\n    \"availability\": \"remaining\",\n    \"include\": [\"notes\"],\n    \"limit\": 10\n  }\n}\n```\n\n**Create a task** (`add_tasks`):\n\n```json\n{\n  \"items\": [{\n    \"name\": \"Review Q3 roadmap\",\n    \"parent\": \"Work Projects\",\n    \"tags\": [\"Planning\"],\n    \"dueDate\": \"2026-03-15T17:00:00\",\n    \"flagged\": true,\n    \"estimatedMinutes\": 30,\n    \"note\": \"Focus on v1.3-v1.5 milestones\"\n  }]\n}\n```\n\n**Edit with patch semantics** (`edit_tasks`):\n\n```json\n{\n  \"items\": [{\n    \"id\": \"oRx3bL_UYq7\",\n    \"dueDate\": null,\n    \"actions\": {\n      \"tags\": {\"add\": [\"Urgent\"]},\n      \"move\": {\"ending\": \"Work Projects\"}\n    }\n  }]\n}\n```\n\n**Patch semantics cheat sheet:**\n\n| Input | Meaning |\n|-------|---------|\n| Field omitted | No change |\n| Field set to `null` | Clear the value |\n| Field set to a value | Update |\n\n---\n\n## 🗺️ Roadmap\n\n| Version | Focus |\n|---------|-------|\n| **v1.0** | Foundation — read tools, three-layer arch, test suite ✅ |\n| **v1.1** | Performance — SQLite caching, 30–60x speedup ✅ |\n| **v1.2** | Writes \u0026 Lookups — add/edit tasks, get-by-ID ✅ |\n| **v1.2.1** | Architectural Cleanup — contracts, service refactor, golden master tests ✅ |\n| **v1.2.2** | FastMCP v3 Migration ✅ |\n| **v1.2.3** | Repetition Rule Write Support ✅ |\n| **v1.3** | Read Tools — SQL filtering, list/count, 5 new tools ✅ |\n| **v1.3.1** | First-Class References — name resolution, `$inbox`, rich refs ✅ |\n| **v1.3.2** | Date Filtering — 7 dimensions, shortcuts, calendar math ✅ |\n| **v1.3.3** | Task Ordering — dotted notation, outline order ✅ |\n| **v1.4** | Response Shaping \u0026 Batch Processing ✅ |\n| **v1.4.1** | Task Properties \u0026 Subtree — presence flags, auto-complete, parallel/sequential, parent filter ✅ |\n| **v1.5** | Project Writes — add/edit projects, review marking |\n| **v1.6** | UI \u0026 Perspectives — perspective switching, deep links |\n| **v1.7** | Production Hardening — retry, crash recovery, serial execution |\n\n---\n\n## 🔗 Links\n\n- 📖 [Full Documentation](https://hellothisisflo.github.io/omnifocus-operator) — features, architecture, examples\n- 📦 [PyPI](https://pypi.org/project/omnifocus-operator/) — package page\n- 🐛 [Issues](https://github.com/HelloThisIsFlo/omnifocus-operator/issues)\n- 💬 [Discussions](https://github.com/HelloThisIsFlo/omnifocus-operator/discussions)\n\n---\n\n## 📄 License\n\nProprietary — all rights reserved. Free to use, not to redistribute. License under review.\n\n## 🤝 Contributing\n\nSee [CONTRIBUTING.md](https://github.com/HelloThisIsFlo/omnifocus-operator/blob/main/CONTRIBUTING.md) for guidelines. In short: fork, branch, test, PR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellothisisflo%2Fomnifocus-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhellothisisflo%2Fomnifocus-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhellothisisflo%2Fomnifocus-operator/lists"}