omnifocus_mcp 1.0.0

data/lib/omnifocus_mcp/resources/project_resource.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../tools/operations/query_omnifocus"
+
+module OmnifocusMcp
+  module Resources
+    # Tasks in a specific OmniFocus project, addressed by name.
+    #
+    # `#content` (via `#payload`) is the sole entry point.
+    class ProjectResource < Base
+      uri "omnifocus://project/{name}"
+      resource_name "project"
+      description "Tasks in a specific OmniFocus project"
+
+      FIELDS = %w[
+        id name flagged dueDate deferDate taskStatus
+        tagNames parentId note estimatedMinutes
+      ].freeze
+
+      def payload
+        name = params[:name].to_s
+        OmnifocusMcp.logger.warn("[resource:project] Reading project: #{name}")
+
+        params = Tools::Params::QueryOmnifocusParams.from_hash(
+          entity: "tasks",
+          filters: { project_name: name },
+          fields: FIELDS
+        )
+        Tools::Operations::QueryOmnifocus.call(params).fold(
+          on_ok: ->(match) { snake_case_keys(match.items || []) },
+          on_error: ->(err) { { error: err } }
+        )
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/resources/stats_resource.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../tools/operations/database_stats"
+
+module OmnifocusMcp
+  module Resources
+    # Quick OmniFocus database statistics overview.
+    class StatsResource < Base
+      uri "omnifocus://stats"
+      resource_name "stats"
+      description "Quick OmniFocus database statistics overview"
+
+      def payload
+        Tools::Operations::DatabaseStats.get_database_stats.fold(
+          on_ok: ->(stats) { snake_case_keys(stats || {}) },
+          on_error: ->(err) { { error: err } }
+        )
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/resources/today_resource.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../tools/operations/query_omnifocus"
+
+module OmnifocusMcp
+  module Resources
+    class TodayResource < Base
+      uri "omnifocus://today"
+      resource_name "today"
+      description "Today's agenda — tasks due today, planned for today, and overdue items"
+
+      DUE_FIELDS     = %w[id name flagged dueDate projectName tagNames taskStatus].freeze
+      PLANNED_FIELDS = %w[id name flagged plannedDate projectName tagNames taskStatus].freeze
+      OVERDUE_FIELDS = DUE_FIELDS
+
+      def payload
+        OmnifocusMcp.logger.warn("[resource:today] Reading today's agenda")
+
+        {
+          due_today: items_or_empty(query(filters: { due_on: 0 }, fields: DUE_FIELDS)),
+          planned_today: items_or_empty(query(filters: { planned_on: 0 }, fields: PLANNED_FIELDS)),
+          overdue: items_or_empty(query(filters: { status: ["Overdue"] }, fields: OVERDUE_FIELDS))
+        }
+      end
+
+      private
+
+      def query(filters:, fields:)
+        params = Tools::Params::QueryOmnifocusParams.from_hash(
+          entity: "tasks", filters: filters, fields: fields
+        )
+        Tools::Operations::QueryOmnifocus.call(params)
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/result.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  # Success/disjoint-error ADT. {#and_then} does not rescue: the block must return another Result and
+  # should not raise for domain failures (use {#map} or return Result.error).
+  # Programmer bugs and invariant violations should use +raise+, not Result.error.
+  Result = Data.define(:value, :error_message, :creation_location) do
+    def self.ok(value)
+      new(value: value, error_message: nil, creation_location: caller_locations(1, 1).first)
+    end
+
+    # @param message [Object] user-facing String or other user-facing error payload.
+    def self.error(message)
+      new(value: nil, error_message: message, creation_location: caller_locations(1, 1).first)
+    end
+
+    # Pair two results; first error wins. Values become a two-element Array on success.
+    def self.zip(left, right)
+      return left if left.error?
+      return right if right.error?
+
+      Result.ok([left.ok, right.ok])
+    end
+
+    # Sequence a +Hash+ or +Array+ of Results into a single Result. Fail-fast: the first error in
+    # iteration order wins (insertion order for Hashes). On success the wrapped value mirrors the
+    # input container's shape: array-in → array-of-values-out, hash-in → hash-of-values-out.
+    def self.all(results)
+      case results
+      when Array
+        first_error = results.find(&:error?)
+        first_error || Result.ok(results.map(&:ok))
+      when Hash
+        first_error = results.each_value.find(&:error?)
+        first_error || Result.ok(results.transform_values(&:ok))
+      else
+        raise ArgumentError, "Result.all expects an Array or Hash, got #{results.class}"
+      end
+    end
+
+    def ok? = !value.nil?
+
+    def error? = !error_message.nil?
+
+    def ok
+      raise "Cannot get value from error result: #{error_message}, #{creation_location}" if error?
+
+      value
+    end
+
+    def ok_or(default_value) = ok? ? value : default_value
+
+    def error
+      raise "Cannot get error from ok result" if ok?
+
+      error_message
+    end
+
+    def map
+      return self if error?
+
+      Result.ok(yield(ok))
+    rescue StandardError => e
+      Result.error(e.message)
+    end
+
+    def and_then
+      return self if error?
+
+      yield(ok)
+    end
+
+    def or_else
+      return self if ok?
+
+      yield(error)
+    end
+
+    # Collapses the +if ok? ... else ... end+ shape into a single expression. The chosen branch is
+    # called with the wrapped value (or error message) and its return value is passed through verbatim;
+    # this is a terminator, not a chainable Result-returning combinator.
+    def fold(on_ok:, on_error:) = ok? ? on_ok.call(ok) : on_error.call(error)
+
+    def where = creation_location
+
+    def deconstruct = [value, error_message]
+
+    def deconstruct_keys(keys)
+      if keys.nil?
+        return error? ? { error_message: error_message } : { value: value }
+      end
+
+      keys.filter_map do |key|
+        val = public_send(key)
+        [key, val] unless val.nil?
+      end.to_h
+    end
+
+    private
+
+    def initialize(value:, error_message:, creation_location:)
+      raise ArgumentError, "Cannot have both value and error" unless value.nil? || error_message.nil?
+      raise ArgumentError, "Must provide either value or error" if value.nil? && error_message.nil?
+
+      super
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/batch_report.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "presenters/batch_report"
+
+module OmnifocusMcp
+  module Tools
+    BatchReport = Presenters::BatchReport
+  end
+end

data/lib/omnifocus_mcp/tools/database_stats.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative "../result"
+require_relative "../infrastructure/js_embed"
+require_relative "../infrastructure/script_runner"
+
+module OmnifocusMcp
+  module Tools
+    # Lightweight database overview helpers that don't require pulling the
+    # full OmniFocus dataset.
+    #
+    # Provides:
+    #   * {.get_database_stats} — counts + last-modified timestamp
+    #   * {.get_changes_since}  — incremental change feed since a timestamp
+    # rubocop:disable Metrics/ModuleLength
+    module DatabaseStats
+      # Lightweight database statistics: counts + last-modified timestamp.
+      #
+      # @return [OmnifocusMcp::Result] +ok+ carries the stats Hash; +error+ carries a user-facing message.
+      class << self
+        def get_database_stats
+          require_relative "operations/database_stats"
+
+          Operations::DatabaseStats.get_database_stats
+        end
+
+        # Incremental change feed since `since` (a Time, DateTime, or ISO string).
+        #
+        # @return [OmnifocusMcp::Result] +ok+ carries the changes Hash; +error+ carries a user-facing message.
+        def get_changes_since(since)
+          require_relative "operations/database_stats"
+
+          Operations::DatabaseStats.get_changes_since(since)
+        end
+
+        STATS_SCRIPT = <<~JS
+          (() => {
+            try {
+              const allTasks = flattenedTasks;
+              const activeTasks = allTasks.filter(task =>
+                task.taskStatus !== Task.Status.Completed &&
+                task.taskStatus !== Task.Status.Dropped
+              );
+
+              const allProjects = flattenedProjects;
+              const activeProjects = allProjects.filter(project =>
+                project.status === Project.Status.Active
+              );
+
+              const overdueCount = activeTasks.filter(task =>
+                task.taskStatus === Task.Status.Overdue
+              ).length;
+
+              const nextActionCount = activeTasks.filter(task =>
+                task.taskStatus === Task.Status.Next
+              ).length;
+
+              const flaggedCount = activeTasks.filter(task => task.flagged).length;
+              const inboxCount = activeTasks.filter(task => task.inInbox).length;
+
+              let lastModified = new Date(0);
+              allTasks.forEach(task => {
+                if (task.modificationDate && task.modificationDate > lastModified) {
+                  lastModified = task.modificationDate;
+                }
+              });
+
+              return JSON.stringify({
+                taskCount: allTasks.length,
+                activeTaskCount: activeTasks.length,
+                projectCount: allProjects.length,
+                activeProjectCount: activeProjects.length,
+                folderCount: flattenedFolders.length,
+                tagCount: flattenedTags.filter(tag => tag.active).length,
+                overdueCount: overdueCount,
+                nextActionCount: nextActionCount,
+                flaggedCount: flaggedCount,
+                inboxCount: inboxCount,
+                lastModified: lastModified.toISOString()
+              });
+
+            } catch (error) {
+              return JSON.stringify({
+                error: "Failed to get database stats: " + error.toString()
+              });
+            }
+          })();
+        JS
+
+        # rubocop:disable Metrics/MethodLength
+        def changes_script(since_iso)
+          escaped_since = Infrastructure::JsEmbed.double_quoted_string(since_iso)
+
+          <<~JS
+            (() => {
+              try {
+                const sinceDate = new Date("#{escaped_since}");
+
+                const allTasks = flattenedTasks;
+
+                const newTasks = allTasks.filter(task =>
+                  task.creationDate && task.creationDate > sinceDate
+                ).map(task => ({
+                  id: task.id.primaryKey,
+                  name: task.name,
+                  creationDate: task.creationDate.toISOString()
+                }));
+
+                const updatedTasks = allTasks.filter(task =>
+                  task.modificationDate &&
+                  task.modificationDate > sinceDate &&
+                  task.creationDate &&
+                  task.creationDate <= sinceDate
+                ).map(task => ({
+                  id: task.id.primaryKey,
+                  name: task.name,
+                  modificationDate: task.modificationDate.toISOString()
+                }));
+
+                const completedTasks = allTasks.filter(task =>
+                  task.completionDate &&
+                  task.completionDate > sinceDate
+                ).map(task => ({
+                  id: task.id.primaryKey,
+                  name: task.name,
+                  completionDate: task.completionDate.toISOString()
+                }));
+
+                const allProjects = flattenedProjects;
+
+                const newProjects = allProjects.filter(project =>
+                  project.creationDate && project.creationDate > sinceDate
+                ).map(project => ({
+                  id: project.id.primaryKey,
+                  name: project.name,
+                  creationDate: project.creationDate.toISOString()
+                }));
+
+                const updatedProjects = allProjects.filter(project =>
+                  project.modificationDate &&
+                  project.modificationDate > sinceDate &&
+                  project.creationDate &&
+                  project.creationDate <= sinceDate
+                ).map(project => ({
+                  id: project.id.primaryKey,
+                  name: project.name,
+                  modificationDate: project.modificationDate.toISOString()
+                }));
+
+                return JSON.stringify({
+                  newTasks: newTasks,
+                  updatedTasks: updatedTasks,
+                  completedTasks: completedTasks,
+                  newProjects: newProjects,
+                  updatedProjects: updatedProjects
+                });
+
+              } catch (error) {
+                return JSON.stringify({
+                  error: "Failed to get changes: " + error.toString()
+                });
+              }
+            })();
+          JS
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        private
+
+        # Collapse a {Infrastructure::ScriptRunner} {Result} into a {Result} over the parsed Hash payload.
+        def script_payload_result(execution)
+          execution.and_then do |payload|
+            if payload.is_a?(Hash) && payload["error"]
+              Result.error(payload["error"])
+            else
+              Result.ok(payload)
+            end
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/omnifocus_mcp/tools/definitions/add_omnifocus_task_tool.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+
+require_relative "mcp_envelope"
+require_relative "operation_factory"
+require_relative "../messages/add_omnifocus_task"
+require_relative "../operations/add_omnifocus_task"
+require_relative "../params"
+
+module OmnifocusMcp
+  module Tools
+    module Definitions
+      # `FastMcp::Tool` for `add_omnifocus_task`.
+      class AddOmniFocusTaskTool < FastMcp::Tool
+        tool_name "add_omnifocus_task"
+        description "Add a new task to OmniFocus"
+
+        arguments do
+          required(:name).filled(:string).description("The name of the task")
+          optional(:note).filled(:string).description("Additional notes for the task")
+          optional(:dueDate).filled(:string)
+                            .description("The due date of the task in ISO format (YYYY-MM-DD or full ISO date)")
+          optional(:deferDate).filled(:string)
+                              .description("The defer date of the task in ISO format (YYYY-MM-DD or full ISO date)")
+          optional(:plannedDate).filled(:string).description(
+            "The planned date of the task in ISO format (YYYY-MM-DD or full ISO date) - " \
+            "indicates intention to work on this task on this date"
+          )
+          optional(:flagged).filled(:bool).description("Whether the task is flagged or not")
+          optional(:estimatedMinutes).filled(:integer)
+                                     .description("Estimated time to complete the task, in minutes")
+          optional(:tags).array(:string).description("Tags to assign to the task")
+          optional(:projectName).filled(:string).description(
+            "The name of the project to add the task to (will add to inbox if not specified)"
+          )
+          optional(:parentTaskId).filled(:string).description("ID of the parent task (preferred for accuracy)")
+          optional(:parentTaskName).filled(:string).description(
+            "Name of the parent task (used if ID not provided; matched within project or globally if no project)"
+          )
+          optional(:hierarchyLevel).filled(:integer, gteq?: 0).description(
+            "Explicit level indicator for ordering in batch workflows (0=root) - ignored in single add"
+          )
+        end
+
+        extend OperationFactory
+
+        default_operation_factory { Operations::AddOmniFocusTask.method(:call) }
+
+        def call(**args)
+          McpEnvelope.safely("creating task") do
+            operation.call(Params::AddTaskParams.from_mcp(args)).fold(
+              on_ok: ->(created) { McpEnvelope::ToolReply.success(Messages::AddOmniFocusTask.success(args, created)) },
+              on_error: ->(err) { McpEnvelope::ToolReply.failure(Messages::AddOmniFocusTask.failure(err)) }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/definitions/add_project_tool.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+
+require_relative "mcp_envelope"
+require_relative "operation_factory"
+require_relative "../messages/add_project"
+require_relative "../operations/add_project"
+require_relative "../params"
+
+module OmnifocusMcp
+  module Tools
+    module Definitions
+      # `FastMcp::Tool` for `add_project`.
+      class AddProjectTool < FastMcp::Tool
+        tool_name "add_project"
+        description "Add a new project to OmniFocus"
+
+        arguments do
+          required(:name).filled(:string).description("The name of the project")
+          optional(:note).filled(:string).description("Additional notes for the project")
+          optional(:dueDate).filled(:string)
+                            .description("The due date of the project in ISO format (YYYY-MM-DD or full ISO date)")
+          optional(:deferDate).filled(:string)
+                              .description(
+                                "The defer date of the project in ISO format (YYYY-MM-DD or full ISO date)"
+                              )
+          optional(:flagged).filled(:bool).description("Whether the project is flagged or not")
+          optional(:estimatedMinutes).filled(:integer)
+                                     .description("Estimated time to complete the project, in minutes")
+          optional(:tags).array(:string).description("Tags to assign to the project")
+          optional(:folderName).filled(:string).description(
+            "The name of the folder to add the project to (will add to root if not specified)"
+          )
+          optional(:sequential).filled(:bool)
+                               .description("Whether tasks in the project should be sequential (default: false)")
+        end
+
+        extend OperationFactory
+
+        default_operation_factory { Operations::AddProject.method(:call) }
+
+        def call(**args)
+          McpEnvelope.safely("creating project") do
+            operation.call(Params::AddProjectParams.from_mcp(args)).fold(
+              on_ok: ->(_created) { McpEnvelope::ToolReply.success(Messages::AddProject.success(args)) },
+              on_error: ->(err) { McpEnvelope::ToolReply.failure(Messages::AddProject.failure(err)) }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/tools/definitions/batch_add_items_tool.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+
+require_relative "mcp_envelope"
+require_relative "operation_factory"
+require_relative "../operations/batch_add_items"
+require_relative "../params"
+require_relative "../presenters/batch_report"
+
+module OmnifocusMcp
+  module Tools
+    module Definitions
+      # `FastMcp::Tool` for `batch_add_items`.
+      class BatchAddItemsTool < FastMcp::Tool
+        tool_name "batch_add_items"
+        description "Add multiple tasks or projects to OmniFocus in a single operation"
+
+        # rubocop:disable Metrics/BlockLength
+        arguments do
+          required(:items).array(:hash) do
+            required(:type).filled(included_in?: %w[task project])
+                           .description("Type of item to add ('task' or 'project')")
+            required(:name).filled(:string).description("The name of the item")
+            optional(:note).filled(:string).description("Additional notes for the item")
+            optional(:dueDate).filled(:string)
+                              .description("The due date in ISO format (YYYY-MM-DD or full ISO date)")
+            optional(:deferDate).filled(:string)
+                                .description("The defer date in ISO format (YYYY-MM-DD or full ISO date)")
+            optional(:plannedDate).filled(:string).description(
+              "The planned date in ISO format (YYYY-MM-DD or full ISO date) - tasks only"
+            )
+            optional(:flagged).filled(:bool).description("Whether the item is flagged or not")
+            optional(:estimatedMinutes).filled(:integer)
+                                       .description("Estimated time to complete the item, in minutes")
+            optional(:tags).array(:string).description("Tags to assign to the item")
+
+            optional(:projectName).filled(:string)
+                                  .description("For tasks: The name of the project to add the task to")
+            optional(:parentTaskId).filled(:string).description("For tasks: ID of the parent task")
+            optional(:parentTaskName).filled(:string).description(
+              "For tasks: Name of the parent task (scoped to project when provided)"
+            )
+            optional(:tempId).filled(:string).description("For tasks: Temporary ID for within-batch references")
+            optional(:parentTempId).filled(:string)
+                                   .description("For tasks: Reference to parent's tempId within the batch")
+            optional(:hierarchyLevel).filled(:integer, gteq?: 0)
+                                     .description("Optional ordering hint (0=root, 1=child, ...)")
+
+            optional(:folderName).filled(:string)
+                                 .description("For projects: The name of the folder to add the project to")
+            optional(:sequential).filled(:bool)
+                                 .description("For projects: Whether tasks in the project should be sequential")
+          end.description("Array of items (tasks or projects) to add")
+          optional(:createSequentially).filled(:bool).description(
+            "Process parents before children; when false, best-effort order will still try to resolve parents first"
+          )
+        end
+        # rubocop:enable Metrics/BlockLength
+
+        extend OperationFactory
+
+        default_operation_factory { Operations::BatchAddItems.method(:call) }
+
+        def call(**args)
+          McpEnvelope.safely("processing batch operation") do
+            items = Array(args[:items]).map { |item| Params::BatchAddItemParams.from_mcp(item) }
+            result = operation.call(items)
+
+            result.fold(
+              on_ok: ->(per_item) { success_reply(per_item, items) },
+              on_error: ->(error) { failure_reply(error) }
+            )
+          end
+        end
+
+        private
+
+        def failure_reply(error)
+          OmnifocusMcp.logger.warn("[batch_add_items] failure result: #{error.inspect}")
+
+          McpEnvelope::ToolReply.failure(
+            Presenters::BatchReport.format_failure(
+              error, results: [], items: []
+            ) { |item_result, item| Presenters::BatchReport.add_detail(item_result, item) }
+          )
+        end
+
+        def success_reply(per_item, items)
+          text = Presenters::BatchReport.format_success(
+            past_tense: "added", failure_verb: "add", results: per_item, items: items
+          ) do |item_result, item|
+            Presenters::BatchReport.add_detail(item_result, item)
+          end
+
+          if Presenters::BatchReport.all_failed?(per_item)
+            McpEnvelope::ToolReply.failure(text)
+          else
+            McpEnvelope::ToolReply.success(text)
+          end
+        end
+      end
+    end
+  end
+end