omnifocus_mcp 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4eb86aa8048f5b98edf61273ab7936b859663199e2ad6c73bb11ec55605550d8
+  data.tar.gz: 7dc7b4f11e986aa96d8b9d746d75a16e7222f13627577ca3e3c420ee4df21bb1
+SHA512:
+  metadata.gz: d7886bb913d144e269a8d9605a7e09ac18a9cab49742a62b9bd4f8b835fd034e6f4984ed33dbc38df2709f6ea748b0902b69b6e823da5b7cd58548c645e195ef
+  data.tar.gz: 033366a6ead47fccfb29bdb0e0df36a1817a124ecea767977bd7c397d26252884fc4e57a3f3e4d6e8b41dc397ad9e6bd2265bf532f3f55ee127d796a300ab00c

data/AGENTS.md

@@ -0,0 +1,15 @@
+## Testing (RSpec)
+
+We use RSpec with:
+
+- **`context`** — group examples by scenario or setup.
+- **`let`** — define lazy, memoized values used by examples.
+- **`subject`** — name the object under test when it improves clarity.
+- Declare `subject` above any other `let` declarations.
+- Declare `subject` above any other `before` declarations.
+
+We aim for **one `expect` per example** when that keeps failures easy to
+interpret; use multiple expectations in the same example when splitting would be
+artificial or would hide a single behavioural assertion.
+
+After Ruby changes, run **`bundle exec rspec`**. Add specs for new methods and behaviour.

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2026-05-31
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Code of Conduct
+
+"omnifocus_mcp" follows
+[The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in
+all "collaborative space", which is defined as community communications channels
+(such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal
+  attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always
+  assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us
+at ["hmaddocks@me.com"](mailto:"hmaddocks@me.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Henry Maddocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+# omnifocus-mcp (Ruby)
+
+`omnifocus-mcp` is a Ruby MCP server that lets LLM clients (Claude Desktop, MCP
+Inspector, etc.) work with OmniFocus on macOS over stdio. It exposes tools and
+resources for creating, editing, removing, querying, and reporting on OmniFocus
+tasks, projects, perspectives, and tags.
+
+This tool was heavily inspired by [OmniFocus MCP Server](https://github.com/themotionmachine/OmniFocus-MCP).
+
+## Features
+
+- Create, edit, remove, and query OmniFocus tasks.
+- Add and manage projects.
+- List tags and perspectives.
+- Read common OmniFocus views such as inbox, today, flagged, stats, projects,
+  and perspectives.
+
+## Tools and Resources
+
+### Tools
+
+- `add_omnifocus_task` - Adds a new task to OmniFocus, with optional notes,
+  dates, tags, project placement, and parent task placement.
+- `add_project` - Adds a new project to OmniFocus, with optional notes, dates,
+  tags, folder placement, and sequential task ordering.
+- `remove_item` - Removes a task or project by ID, or by name when an ID is not
+  available.
+- `edit_item` - Updates a task or project, including names, notes, dates, flags,
+  estimates, statuses, tags, and location.
+- `batch_add_items` - Adds multiple tasks or projects in one operation,
+  including support for task hierarchy within the batch.
+- `batch_remove_items` - Removes multiple tasks or projects in one operation.
+- `query_omnifocus` - Queries tasks, projects, or folders with filters for
+  project, tag, status, dates, flags, notes, and more.
+- `list_perspectives` - Lists built-in and custom OmniFocus perspectives.
+- `get_perspective_view` - Returns the tasks and projects visible in a named
+  OmniFocus perspective.
+- `list_tags` - Lists OmniFocus tags and their hierarchy, with optional inactive
+  tags.
+
+### Resources
+
+- `omnifocus://inbox` - Returns current OmniFocus inbox tasks.
+- `omnifocus://today` - Returns today's agenda, including tasks due today,
+  planned for today, and overdue tasks.
+- `omnifocus://flagged` - Returns flagged OmniFocus tasks.
+- `omnifocus://stats` - Returns a quick overview of OmniFocus database statistics.
+- `omnifocus://project/{name}` - Returns tasks in the named OmniFocus project.
+- `omnifocus://perspective/{name}` - Returns items visible in the named
+  OmniFocus perspective.
+
+## Requirements
+
+- Ruby 3.4 or later
+- macOS with OmniFocus 4 installed
+
+## Install
+
+```sh
+gem install omnifocus-mcp
+```
+
+## Run
+
+```sh
+omnifocus-mcp
+```
+
+The server speaks MCP over stdio. Test it with the MCP inspector:
+
+```sh
+npx @modelcontextprotocol/inspector omnifocus-mcp
+```
+
+## Configure an MCP Client
+
+After installing the executable, add this server to any MCP client that supports
+stdio servers:
+
+```json
+{
+  "mcpServers": {
+    "omnifocus-mcp": {
+      "command": "omnifocus-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+## Client Instructions
+
+This server uses [fast-mcp](https://github.com/yjacquin/fast-mcp) 1.6, which
+does not currently expose MCP server instructions during client initialization.
+To give an MCP client better guidance, copy the instructions below into a skill,
+rule, your project's `AGENTS.md`, or another client-specific instruction file.
+
+```text
+OmniFocus MCP server for macOS task management.
+
+TOOL GUIDANCE:
+- Use query_omnifocus for targeted lookups; the "fields" parameter requests only
+  needed fields
+- Use "summary: true" for quick counts without full data
+- For batch operations, prefer batch_add_items/batch_remove_items over repeated
+  single calls
+
+RESOURCES:
+- omnifocus://inbox - current inbox items
+- omnifocus://today - today's agenda (due, planned, overdue)
+- omnifocus://flagged - all flagged items
+- omnifocus://stats - quick database statistics
+- omnifocus://project/{name} - tasks in a specific project
+- omnifocus://perspective/{name} - items in a named perspective
+
+QUERY FILTER TIPS:
+- Tags filter is case-sensitive and exact match
+- projectName filter is case-insensitive partial match
+- Status values for tasks: Next, Available, Blocked, DueSoon, Overdue
+- Status values for projects: Active, OnHold, Done, Dropped
+- Combine filters with AND logic; within arrays, OR logic applies
+```
+
+## Tests
+
+```sh
+bundle exec rspec
+```
+
+Integration specs that hit the real OmniFocus app are tagged
+`:requires_omnifocus` and skipped by default. Run them with:
+
+```sh
+INTEGRATION=1 bundle exec rspec
+```
+
+OmniFocus must be running and macOS must allow the terminal app to send Apple
+Events to OmniFocus. If macOS reports
+`Not authorised to send Apple events to OmniFocus (-1743)`, grant the terminal
+permission in System Settings > Privacy & Security > Automation.
+
+Integration tests create items prefixed `TEST:` and clean them up at teardown.
+If a run is killed mid-flight, you can sweep leftover items with:
+
+```sh
+bundle exec ruby spec/integration/cleanup.rb
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/omnifocus-mcp

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "omnifocus_mcp"
+
+OmnifocusMcp::Mcp.start

data/lib/omnifocus_mcp/config.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  # Runtime configuration read from the environment.
+  module Config
+    DEFAULT_SCRIPT_TIMEOUT_SEC = 180
+
+    class << self
+      # Seconds to wait for an `osascript` invocation before terminating it.
+      # Set to 0 to disable (wait indefinitely). Default: 180.
+      def script_timeout_sec
+        raw = ENV.fetch("OMNIFOCUS_MCP_SCRIPT_TIMEOUT_SEC", DEFAULT_SCRIPT_TIMEOUT_SEC.to_s)
+        sec = Float(raw, exception: false)
+        sec&.positive? ? sec : nil
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/infrastructure/.keep

@@ -0,0 +1 @@
+

data/lib/omnifocus_mcp/infrastructure/apple_script.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Infrastructure
+    # Composable AppleScript fragments for write-side primitives.
+    # rubocop:disable Metrics/ModuleLength
+    module AppleScript
+      ITEM_TYPES = %w[task project].freeze
+      LOOKUP_KINDS = %i[folder project].freeze
+
+      class << self
+        # Prefix every non-empty line of `text` with `prefix`. Lines that are
+        # blank or only-whitespace are passed through unchanged so the result
+        # diffs cleanly.
+        def indent(text:, prefix:)
+          text.each_line
+              .map { |line| line.strip.empty? ? line : "#{prefix}#{line}" }
+              .join
+        end
+
+        # Escape `"` and `\` so `value` is safe inside an AppleScript
+        # double-quoted string. CR/LF collapse to a single space.
+        def escape(value)
+          value.to_s
+               .gsub(/["\\]/) { |m| "\\#{m}" }
+               .gsub(/[\r\n]/, " ")
+        end
+
+        # Wrap a script `body` in the standard OmniFocus front document
+        # envelope used by write-side primitives.
+        def tell_document(body)
+          <<~APPLESCRIPT
+            try
+              tell application "OmniFocus"
+                tell front document
+            #{indent(text: body.chomp, prefix: "      ")}
+                end tell
+              end tell
+            on error errorMessage
+              return "{\\"success\\":false,\\"error\\":\\"" & errorMessage & "\\"}"
+            end try
+          APPLESCRIPT
+        end
+
+        # Find a task or project, setting `var` to the located object or
+        # `missing value` when not found.
+        def find_item(var:, item_type:, id:, name:)
+          unless ITEM_TYPES.include?(item_type)
+            raise ArgumentError, "item_type must be one of #{ITEM_TYPES.inspect}, got #{item_type.inspect}"
+          end
+
+          collection = "flattened #{item_type}"
+          sections = [
+            ["set #{var} to missing value"],
+            id_lookup_lines(var: var, collection: collection, item_type: item_type, id: id),
+            name_lookup_lines(var: var, collection: collection, item_type: item_type, name: name, fallback: !id.empty?)
+          ]
+
+          "#{sections.flatten.join("\n")}\n"
+        end
+
+        # Add an existing tag to `item_var`, creating it if it does not exist.
+        def tag_assignment(item_var:, tag_name:)
+          <<~APPLESCRIPT.chomp
+            try
+              set theTag to first flattened tag where name = "#{tag_name}"
+              add theTag to tags of #{item_var}
+            on error
+              -- Tag might not exist, try to create it
+              try
+                set theTag to make new tag with properties {name:"#{tag_name}"}
+                add theTag to tags of #{item_var}
+              on error
+                -- Could not create or add tag
+              end try
+            end try
+          APPLESCRIPT
+        end
+
+        # Generate AppleScript that resolves a folder by path or simple name.
+        def generate_folder_lookup_script(raw_folder_path:, var_name:, error_return_json:)
+          generate_lookup_script(
+            kind: :folder,
+            raw_path: raw_folder_path,
+            var_name: var_name,
+            error_return_json: error_return_json
+          )
+        end
+
+        # Generate AppleScript that resolves a project by path or simple name.
+        def generate_project_lookup_script(raw_project_path:, var_name:, error_return_json:)
+          generate_lookup_script(
+            kind: :project,
+            raw_path: raw_project_path,
+            var_name: var_name,
+            error_return_json: error_return_json
+          )
+        end
+
+        # Unified entry point for folder/project lookup scripts.
+        def generate_lookup_script(kind:, raw_path:, var_name:, error_return_json:)
+          unless LOOKUP_KINDS.include?(kind)
+            raise ArgumentError, "kind must be one of #{LOOKUP_KINDS.inspect}, got #{kind.inspect}"
+          end
+
+          components = raw_path.split("/")
+                               .reject(&:empty?)
+          return "set #{var_name} to missing value" if components.empty?
+
+          escaped_components = components.map { |c| escape(c) }
+          builder = components.length == 1 ? :simple : :nested
+          send(:"#{builder}_#{kind}_lookup", var_name:, escaped_components:, error_return_json:)
+        end
+
+        private
+
+        def id_lookup_lines(var:, collection:, item_type:, id:)
+          return [] if id.empty?
+
+          [
+            "",
+            "-- Find #{item_type} by ID",
+            "try",
+            %(  set #{var} to first #{collection} whose id is "#{id}"),
+            "end try"
+          ]
+        end
+
+        def name_lookup_lines(var:, collection:, item_type:, name:, fallback:)
+          return [] if name.empty?
+
+          if fallback
+            [
+              "",
+              "-- Fall back to name search if id missed",
+              "if #{var} is missing value then",
+              "  try",
+              %(    set #{var} to first #{collection} whose name is "#{name}"),
+              "  end try",
+              "end if"
+            ]
+          else
+            [
+              "",
+              "-- Find #{item_type} by name",
+              "try",
+              %(  set #{var} to first #{collection} whose name is "#{name}"),
+              "end try"
+            ]
+          end
+        end
+
+        def applescript_string_list(escaped_strings)
+          escaped_strings.map { |s| %("#{s}") }.join(", ")
+        end
+
+        def simple_folder_lookup(var_name:, escaped_components:, error_return_json:)
+          name = escaped_components.first
+          <<~APPLESCRIPT.chomp
+            set #{var_name} to missing value
+            try
+              set #{var_name} to first flattened folder where name = "#{name}"
+            end try
+            if #{var_name} is missing value then
+              return "#{error_return_json}"
+            end if
+          APPLESCRIPT
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        def nested_folder_lookup(var_name:, escaped_components:, error_return_json:)
+          leaf_name = escaped_components.last
+          list_items = applescript_string_list(escaped_components)
+
+          <<~APPLESCRIPT.chomp
+            set #{var_name} to missing value
+            set pathComponents to {#{list_items}}
+            repeat with aFolder in (flattened folders)
+              if name of aFolder = "#{leaf_name}" then
+                -- Verify ancestor chain matches path
+                set ancestorOk to true
+                set currentItem to aFolder
+                repeat with i from ((count of pathComponents) - 1) to 1 by -1
+                  try
+                    set currentItem to container of currentItem
+                    if class of currentItem is not folder or name of currentItem is not equal to (item i of pathComponents) then
+                      set ancestorOk to false
+                      exit repeat
+                    end if
+                  on error
+                    set ancestorOk to false
+                    exit repeat
+                  end try
+                end repeat
+                if ancestorOk then
+                  set #{var_name} to aFolder
+                  exit repeat
+                end if
+              end if
+            end repeat
+            if #{var_name} is missing value then
+              return "#{error_return_json}"
+            end if
+          APPLESCRIPT
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def simple_project_lookup(var_name:, escaped_components:, error_return_json:)
+          name = escaped_components.first
+          <<~APPLESCRIPT.chomp
+            set #{var_name} to missing value
+            try
+              set #{var_name} to first flattened project whose name is "#{name}"
+            end try
+            if #{var_name} is missing value then
+              return "#{error_return_json}"
+            end if
+          APPLESCRIPT
+        end
+
+        # rubocop:disable Metrics/MethodLength
+        def nested_project_lookup(var_name:, escaped_components:, error_return_json:)
+          project_name = escaped_components.last
+          folder_components = escaped_components[0...-1]
+          folder_items = applescript_string_list(folder_components)
+
+          <<~APPLESCRIPT.chomp
+            set #{var_name} to missing value
+            set folderPath to {#{folder_items}}
+            repeat with aProject in (flattened projects)
+              if (name of aProject as string) = "#{project_name}" then
+                -- Verify folder ancestry matches path
+                set ancestorOk to true
+                set currentItem to container of aProject
+                repeat with i from (count of folderPath) to 1 by -1
+                  try
+                    if class of currentItem is not folder or name of currentItem is not equal to (item i of folderPath) then
+                      set ancestorOk to false
+                      exit repeat
+                    end if
+                    set currentItem to container of currentItem
+                  on error
+                    set ancestorOk to false
+                    exit repeat
+                  end try
+                end repeat
+                if ancestorOk then
+                  set #{var_name} to aProject
+                  exit repeat
+                end if
+              end if
+            end repeat
+            if #{var_name} is missing value then
+              return "#{error_return_json}"
+            end if
+          APPLESCRIPT
+        end
+        # rubocop:enable Metrics/MethodLength
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/omnifocus_mcp/infrastructure/apple_script_date_builder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module OmnifocusMcp
+  module Infrastructure
+    # Builds AppleScript date fragments outside tell blocks so date variables can
+    # be safely referenced inside OmniFocus tell blocks.
+    class AppleScriptDateBuilder
+      ISO_DATE_ONLY_RE = /\A\d{4}-\d{2}-\d{2}\z/
+
+      DateAssignmentParts = Data.define(:pre_script, :assignment_script)
+
+      class << self
+        # Generate AppleScript to construct a date variable outside `tell` blocks.
+        def create_date_outside_tell_block(iso_date_string, var_name)
+          emit_date_assignment(parse_iso(iso_date_string), var_name)
+        end
+
+        # Return the scripts needed to assign or clear a date property.
+        def generate_date_assignment(object_name, property_name, iso_date_string)
+          return nil if iso_date_string.nil?
+
+          if iso_date_string == ""
+            return DateAssignmentParts.new(
+              pre_script: "",
+              assignment_script: "set #{property_name} of #{object_name} to missing value"
+            )
+          end
+
+          var_name = "dateVar#{SecureRandom.hex(5)}"
+
+          DateAssignmentParts.new(
+            pre_script: create_date_outside_tell_block(iso_date_string, var_name),
+            assignment_script: "set #{property_name} of #{object_name} to #{var_name}"
+          )
+        end
+
+        private
+
+        def parse_iso(iso_date_string)
+          # Date-only strings are normalized to local midnight, avoiding timezone
+          # shifts that can happen when JS interprets YYYY-MM-DD as UTC.
+          normalized = ISO_DATE_ONLY_RE.match?(iso_date_string) ? "#{iso_date_string}T00:00:00" : iso_date_string
+          Time.parse(normalized)
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "Invalid date string: #{iso_date_string}"
+        end
+
+        def emit_date_assignment(time, var_name)
+          <<~APPLESCRIPT.chomp
+            copy current date to #{var_name}
+            set year of #{var_name} to #{time.year}
+            set month of #{var_name} to #{time.month}
+            set day of #{var_name} to #{time.day}
+            set hours of #{var_name} to #{time.hour}
+            set minutes of #{var_name} to #{time.min}
+            set seconds of #{var_name} to #{time.sec}
+          APPLESCRIPT
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/infrastructure/js_embed.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Infrastructure
+    # Escapes Ruby strings before embedding them into generated JavaScript/JXA.
+    module JsEmbed
+      DOUBLE_QUOTED_STRING_ESCAPES = {
+        "\\" => "\\\\",
+        '"' => '\\"',
+        "\n" => "\\n",
+        "\r" => "\\r"
+      }.freeze
+      private_constant :DOUBLE_QUOTED_STRING_ESCAPES
+
+      DOUBLE_QUOTED_STRING_ESCAPE_REGEX = /[\\"\n\r]/
+      private_constant :DOUBLE_QUOTED_STRING_ESCAPE_REGEX
+
+      TEMPLATE_LITERAL_ESCAPES = {
+        "\\" => "\\\\",
+        "`" => "\\`",
+        "$" => "\\$"
+      }.freeze
+      private_constant :TEMPLATE_LITERAL_ESCAPES
+
+      TEMPLATE_LITERAL_ESCAPE_REGEX = /[\\`$]/
+      private_constant :TEMPLATE_LITERAL_ESCAPE_REGEX
+
+      class << self
+        def double_quoted_string(value)
+          value.to_s.gsub(DOUBLE_QUOTED_STRING_ESCAPE_REGEX, DOUBLE_QUOTED_STRING_ESCAPES)
+        end
+
+        def template_literal(value)
+          value.to_s.gsub(TEMPLATE_LITERAL_ESCAPE_REGEX, TEMPLATE_LITERAL_ESCAPES)
+        end
+      end
+    end
+  end
+end