omnifocus_mcp 1.0.0

data/lib/omnifocus_mcp/infrastructure/script_runner.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "tempfile"
+
+require_relative "../config"
+require_relative "../result"
+require_relative "../utils/blank"
+require_relative "js_embed"
+
+module OmnifocusMcp
+  module Infrastructure
+    # Runs OmniFocus automation scripts (JXA, OmniJS, AppleScript) via
+    # `osascript`.
+    #
+    # Instances accept an injectable runner so unit specs can supply a fake that
+    # returns canned `[stdout, stderr, status]` triples without invoking
+    # osascript. Class methods delegate to a default singleton for compatibility
+    # with the previous `Utils::ScriptExecution` API.
+    class ScriptRunner
+      OMNIFOCUS_SCRIPTS_DIR = File.expand_path("../utils/omnifocus_scripts", __dir__).freeze
+      STDOUT_PREVIEW_LIMIT = 200
+
+      class << self
+        def default = @default ||= new
+
+        def runner = default.runner
+
+        def runner=(runner)
+          default.runner = runner
+        end
+
+        def reset!
+          @default = new
+        end
+
+        def execute_jxa(script) = default.execute_jxa(script)
+        def execute_omnifocus_source(source, args: nil) = default.execute_omnifocus_source(source, args: args)
+        def execute_omnifocus_script(script_path, args: nil) = default.execute_omnifocus_script(script_path, args: args)
+        def execute_applescript(source) = default.execute_applescript(source)
+        def with_temp_script(content:, prefix:, ext:, &) = default.with_temp_script(content:, prefix:, ext:, &)
+        def escape_content(content) = default.escape_content(content)
+        def resolve_script_path(script_path) = default.resolve_script_path(script_path)
+        def capture_osascript(...) = default.capture_osascript(...)
+      end
+
+      attr_writer :runner
+
+      def initialize(runner: nil)
+        @runner = runner
+      end
+
+      def runner = @runner ||= method(:capture_osascript).to_proc
+
+      # Execute a JXA script (string source) and return {Result} with the parsed
+      # JSON value.
+      def execute_jxa(script)
+        run_jxa_source_result(source: script, prefix: "jxa_script")
+          .and_then { |stdout| parse_jxa_output(stdout) }
+      end
+
+      # Execute an OmniJS script source (string) inside OmniFocus via
+      # `app.evaluateJavascript`. Returns {Result} with the parsed JSON value.
+      #
+      # `args` (Array<String>) is prepended as a `const argv = [...]` block
+      # before the script body.
+      def execute_omnifocus_source(source, args: nil)
+        wrap_omnifocus_source(source:, args:).then do |wrapped|
+          run_jxa_source_result(source: wrapped, prefix: "jxa_wrapper")
+            .and_then { |stdout| parse_omnifocus_output(stdout) }
+        end
+      end
+
+      # Execute an OmniJS script from disk inside OmniFocus.
+      #
+      # `script_path` may be a real filesystem path or an `@scriptName.js`
+      # shorthand that resolves against `OMNIFOCUS_SCRIPTS_DIR`.
+      def execute_omnifocus_script(script_path, args: nil)
+        # Force UTF-8: bundled OmniJS files may contain non-ASCII bytes; the
+        # platform default of US-ASCII would otherwise raise inside the
+        # regex-based escape pass.
+        File.read(resolve_script_path(script_path), encoding: Encoding::UTF_8).then do |source|
+          execute_omnifocus_source(source, args:)
+        end
+      end
+
+      # Execute a raw AppleScript source string via `osascript`.
+      #
+      # Returns the `[stdout, stderr, status]` triple from the runner so callers
+      # can surface stderr/status without re-running the script.
+      def execute_applescript(source)
+        with_temp_script(content: source, prefix: "applescript", ext: "applescript") do |path|
+          runner.call("osascript", path)
+        end
+      end
+
+      # Materialize `content` to a tempfile, yield its path to the block, and
+      # guarantee cleanup (even on exception). Uses `Tempfile.create`, which
+      # removes the file when the block exits.
+      def with_temp_script(content:, prefix:, ext:)
+        Tempfile.create([prefix, ".#{ext}"]) do |file|
+          file.write(content)
+          file.flush
+          yield file.path
+        end
+      end
+
+      # Escape a string for safe embedding in a JXA template literal.
+      def escape_content(content) = JsEmbed.template_literal(content)
+
+      # Resolve `@scriptName.js` to an absolute path inside the gem's bundled
+      # OmniJS directory. Plain paths pass through unchanged.
+      def resolve_script_path(script_path)
+        return script_path unless script_path.start_with?("@")
+
+        File.join(OMNIFOCUS_SCRIPTS_DIR, script_path[1..])
+      end
+
+      # Runs `osascript` (or a test double) with an optional timeout so a hung
+      # automation call cannot block the MCP server indefinitely.
+      def capture_osascript(*argv)
+        timeout_sec = Config.script_timeout_sec
+        return Open3.capture3(*argv) unless timeout_sec
+
+        capture_osascript_with_timeout(*argv, timeout_sec:)
+      end
+
+      private
+
+      FailedStatus = Data.define(:exitstatus) do
+        def success? = false
+      end
+      private_constant :FailedStatus
+
+      SCRIPT_TIMEOUT_STATUS = FailedStatus.new(exitstatus: nil).freeze
+      private_constant :SCRIPT_TIMEOUT_STATUS
+
+      def capture_osascript_with_timeout(*argv, timeout_sec:)
+        Open3.popen3(*argv) do |_stdin, stdout, stderr, wait_thr|
+          out_thread = Thread.new { stdout.read }
+          err_thread = Thread.new { stderr.read }
+
+          unless wait_thr.join(timeout_sec)
+            terminate_osascript(wait_thr)
+            message = stderr_message(err_thread)
+            message = "osascript timed out after #{timeout_sec}s" if message.empty?
+            OmnifocusMcp.logger.warn("[script_execution] #{message}")
+            return ["", message, SCRIPT_TIMEOUT_STATUS]
+          end
+
+          [out_thread.value, err_thread.value, wait_thr.value]
+        end
+      end
+
+      def terminate_osascript(wait_thr)
+        pid = wait_thr.pid
+        Process.kill("TERM", pid)
+        wait_thr.join(2)
+        Process.kill("KILL", pid) unless wait_thr.status == false
+      rescue Errno::ESRCH
+        nil
+      ensure
+        wait_thr.join(1)
+      end
+
+      def stderr_message(err_thread)
+        return "" unless err_thread.join(1)
+
+        err_thread.value.to_s.strip
+      end
+
+      # Runs raw JXA `source` via `osascript -l JavaScript`, returning
+      # {Result.ok(stdout)} on success or {Result.error} when the runner fails
+      # or the process exits non-zero.
+      def run_jxa_source_result(source:, prefix:)
+        with_temp_script(content: source, prefix: prefix, ext: "js") do |path|
+          stdout, stderr, status = runner.call("osascript", "-l", "JavaScript", path)
+          return Result.error(format_run_failure(stderr, status)) unless status.success?
+
+          OmnifocusMcp.logger.warn("[script_execution] Script stderr output: #{stderr}") if stderr && !stderr.empty?
+          Result.ok(stdout)
+        end
+      rescue StandardError => e
+        Result.error("Failed to execute script: #{e.message}")
+      end
+
+      def format_run_failure(stderr, status)
+        exit_code = status.respond_to?(:exitstatus) ? status.exitstatus : status
+        message = "osascript failed (exit #{exit_code})"
+        message += ": #{stderr.strip}" unless stderr.nil? || stderr.empty?
+        message
+      end
+
+      # Build the JXA wrapper that calls `app.evaluateJavascript` with the
+      # OmniJS source embedded inside a backtick template literal.
+      # rubocop:disable Metrics/MethodLength
+      def wrap_omnifocus_source(source:, args:)
+        script_with_args =
+          if Utils::Blank.blank?(args)
+            source
+          else
+            quoted_args = args.map { |a| %("#{escape_content(a)}") }.join(", ")
+            "\n// Set up arguments\nconst argv = [#{quoted_args}];\n\n#{source}"
+          end
+
+        escaped = escape_content(script_with_args)
+
+        <<~JXA
+          function run() {
+            try {
+              const app = Application('OmniFocus');
+              app.includeStandardAdditions = true;
+
+              // Run the OmniJS script in OmniFocus and capture the output
+              const result = app.evaluateJavascript(`#{escaped}`);
+
+              // Return the result
+              return result;
+            } catch (e) {
+              return JSON.stringify({ error: e.message });
+            }
+          }
+        JXA
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # JXA stdout -> {Result.ok(parsed)} or {Result.error} on parse failure.
+      def parse_jxa_output(stdout)
+        Result.ok(parse_json_stdout(stdout))
+      rescue JSON::ParserError => e
+        Result.error(parse_failure_message(parse_error: e, stdout:))
+      end
+
+      # OmniJS stdout -> {Result.ok(parsed)} or {Result.error} on parse failure.
+      def parse_omnifocus_output(stdout)
+        Result.ok(parse_json_stdout(stdout))
+      rescue JSON::ParserError => e
+        Result.error(parse_failure_message(parse_error: e, stdout:))
+      end
+
+      # osascript may return US-ASCII-labelled stdout that contains UTF-8 bytes
+      # (e.g. tag names with accents). Treat stdout as UTF-8 before parsing.
+      def parse_json_stdout(stdout)
+        JSON.parse(stdout.to_s.dup.force_encoding(Encoding::UTF_8))
+      end
+
+      def parse_failure_message(parse_error:, stdout:)
+        preview = stdout.to_s[0, STDOUT_PREVIEW_LIMIT]
+        "Failed to parse script output (#{parse_error.message}): #{preview}"
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/infrastructure.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Infrastructure
+  end
+end

data/lib/omnifocus_mcp/json_rpc_compat.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Cursor's MCP client rejects JSON-RPC error responses with `"id": null`
+# (fast-mcp 1.6 emits null when the request id is unknown). Coerce those to 0
+# and ignore blank stdin lines so empty writes do not produce invalid responses.
+module OmnifocusMcp
+  module JsonRpcCompat
+    UNKNOWN_REQUEST_ID = 0
+
+    module_function
+
+    def apply!
+      patch_server_send_error!
+      patch_stdio_transport!
+    end
+
+    def normalize_id(id) = id.nil? ? UNKNOWN_REQUEST_ID : id
+
+    def patch_server_send_error!
+      return if server_send_error_patched?
+
+      FastMcp::Server.class_eval do
+        alias_method :send_error_without_json_rpc_compat, :send_error
+
+        def send_error(code, message, id = nil)
+          send_error_without_json_rpc_compat(code, message, OmnifocusMcp::JsonRpcCompat.normalize_id(id))
+        end
+      end
+    end
+    private_class_method :patch_server_send_error!
+
+    def patch_stdio_transport!
+      return if stdio_transport_patched?
+
+      FastMcp::Transports::StdioTransport.class_eval do
+        alias_method :start_without_json_rpc_compat, :start
+
+        def start
+          @logger.info("Starting STDIO transport")
+          @running = true
+
+          while @running && (line = $stdin.gets)
+            stripped = line.strip
+            next if stripped.empty?
+
+            begin
+              process_message(stripped)
+            rescue StandardError => e
+              @logger.error("Error processing message: #{e.message}")
+              @logger.error(e.backtrace.join("\n"))
+              send_error(-32_000, "Internal error: #{e.message}")
+            end
+          end
+        end
+
+        alias_method :send_error_without_json_rpc_compat, :send_error
+
+        def send_error(code, message, id = nil)
+          send_error_without_json_rpc_compat(code, message, OmnifocusMcp::JsonRpcCompat.normalize_id(id))
+        end
+      end
+    end
+    private_class_method :patch_stdio_transport!
+
+    def server_send_error_patched?
+      FastMcp::Server.private_method_defined?(:send_error_without_json_rpc_compat)
+    end
+    private_class_method :server_send_error_patched?
+
+    def stdio_transport_patched?
+      FastMcp::Transports::StdioTransport.private_method_defined?(:start_without_json_rpc_compat)
+    end
+    private_class_method :stdio_transport_patched?
+  end
+end

data/lib/omnifocus_mcp/logger.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module OmnifocusMcp
+  module_function
+
+  # Application-wide logger writing to the current `$stderr`.
+  #
+  # Rebuilds when `$stderr` changes so test helpers that redirect stderr
+  # (RSpec's `output.to_stderr`, silencing helpers) still capture log lines.
+  def logger
+    reset_logger_if_stderr_changed
+    @logger ||= build_logger
+  end
+
+  def reset_logger!
+    @logger = nil
+    @logger_stderr = nil
+  end
+
+  def build_logger
+    Logger.new($stderr, progname: "omnifocus_mcp").tap { |log| log.level = Logger::WARN }
+  end
+  private :build_logger
+
+  def reset_logger_if_stderr_changed
+    return if @logger_stderr.equal?($stderr)
+
+    @logger = nil
+    @logger_stderr = $stderr
+  end
+  private :reset_logger_if_stderr_changed
+end

data/lib/omnifocus_mcp/mcp.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+
+module OmnifocusMcp
+  module Mcp
+    extend self
+
+    INSTRUCTIONS = <<~INSTRUCTIONS
+      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
+    INSTRUCTIONS
+
+    def server_name = "OmniFocus MCP"
+
+    def server_version = VERSION
+
+    def build_server(logger: FastMcp::Logger.new)
+      FastMcp::Server.new(name: server_name, version: server_version, logger: logger).tap do |server|
+        register_tools(server)
+        register_resources(server)
+      end
+    end
+
+    def start = build_server.start
+
+    private
+
+    def register_tools(server)
+      server.register_tools(
+        Tools::Definitions::AddOmniFocusTaskTool,
+        Tools::Definitions::AddProjectTool,
+        Tools::Definitions::RemoveItemTool,
+        Tools::Definitions::EditItemTool,
+        Tools::Definitions::BatchAddItemsTool,
+        Tools::Definitions::BatchRemoveItemsTool,
+        Tools::Definitions::QueryOmnifocusTool,
+        Tools::Definitions::ListPerspectivesTool,
+        Tools::Definitions::GetPerspectiveViewTool,
+        Tools::Definitions::ListTagsTool
+      )
+    end
+
+    def register_resources(server)
+      server.register_resources(
+        Resources::InboxResource,
+        Resources::TodayResource,
+        Resources::FlaggedResource,
+        Resources::StatsResource,
+        Resources::ProjectResource,
+        Resources::PerspectiveResource
+      )
+    end
+  end
+end

data/lib/omnifocus_mcp/parsers/.keep

@@ -0,0 +1 @@
+

data/lib/omnifocus_mcp/parsers/apple_script_envelope.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "../result"
+
+module OmnifocusMcp
+  module Parsers
+    # Parses the `{"success": true|false, ...}` JSON envelope the AppleScript primitives return on stdout.
+    # The block runs only on a +success: true+ envelope; it receives the parsed Hash and must itself
+    # return a {OmnifocusMcp::Result} (typically wrapping a typed +Data+ payload).
+    module AppleScriptEnvelope
+      # Max characters of raw stdout to include in a JSON-parse error message.
+      # Keeps logs/error reporters from being swamped by multi-page AppleScript dumps.
+      STDOUT_PREVIEW_LIMIT = 200
+
+      class << self
+        def parse(stdout:, default_error:, &)
+          parse_json(stdout).and_then { |hash| from_envelope(hash, default_error: default_error) }
+                            .and_then(&)
+        end
+
+        private
+
+        def parse_json(stdout)
+          Result.ok(JSON.parse(stdout))
+        rescue JSON::ParserError => e
+          preview = stdout.to_s[0, STDOUT_PREVIEW_LIMIT]
+          Result.error("Failed to parse AppleScript result (#{e.message}): #{preview}")
+        end
+
+        def from_envelope(parsed, default_error:)
+          return Result.error(default_error) unless parsed.is_a?(Hash)
+
+          if parsed["success"]
+            Result.ok(parsed)
+          else
+            Result.error(parsed["error"] || default_error)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/parsers.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module OmnifocusMcp
+  module Parsers
+  end
+end

data/lib/omnifocus_mcp/resources/base.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "fast_mcp"
+require "json"
+
+module OmnifocusMcp
+  module Resources
+    # Shared superclass for OmniFocus MCP resources.
+    #
+    # All resources serialize a Ruby object as pretty-printed JSON. Subclasses
+    # implement `#payload` to produce that Ruby object.
+    #
+    # MCP resources return:
+    #   { contents: [{ uri, mimeType: "application/json", text: pretty_json }] }
+    # `FastMcp::Server#handle_resources_read` wraps the `#content` string with
+    # the equivalent `contents` envelope (see fast-mcp's resource.rb).
+    class Base < FastMcp::Resource
+      mime_type "application/json"
+
+      def content = JSON.pretty_generate(camelize_keys(safe_payload))
+
+      # Subclasses must implement.
+      # @return [Object] anything `JSON.pretty_generate` can serialize
+      def payload = raise NotImplementedError, "#{self.class} must implement #payload"
+
+      private
+
+      def safe_payload
+        payload
+      rescue StandardError, NotImplementedError => e
+        scope = self.class.resource_name || self.class.name
+        OmnifocusMcp.logger.warn("[resource:#{scope}] #{e.message}")
+        { error: e.message }
+      end
+
+      def snake_case_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), out|
+            out[snake_case_key(key)] = snake_case_keys(value)
+          end
+        when Array
+          obj.map { |item| snake_case_keys(item) }
+        else
+          obj
+        end
+      end
+
+      def camelize_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), out|
+            out[camel_case_key(key)] = camelize_keys(value)
+          end
+        when Array
+          obj.map { |item| camelize_keys(item) }
+        else
+          obj
+        end
+      end
+
+      def snake_case_key(key)
+        return key unless key.is_a?(Symbol) || key.is_a?(String)
+
+        key.to_s.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+      end
+
+      def camel_case_key(key)
+        return key unless key.is_a?(Symbol) || key.is_a?(String)
+
+        parts = key.to_s.split("_")
+        ([parts.first] + parts.drop(1).map(&:capitalize)).join
+      end
+
+      public
+
+      # Swallows failures into an empty array rather than
+      # surfacing an `{ error: ... }` envelope. Used by aggregated resources (e.g.
+      # `TodayResource`) that bundle multiple queries and prefer a missing section to
+      # an inline error.
+      def items_or_empty(result)
+        result.map { |match| snake_case_keys(match.items || []) }
+              .ok_or([])
+      end
+    end
+  end
+end

data/lib/omnifocus_mcp/resources/flagged_resource.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../tools/operations/query_omnifocus"
+
+module OmnifocusMcp
+  module Resources
+    # All flagged OmniFocus items.
+    class FlaggedResource < Base
+      uri "omnifocus://flagged"
+      resource_name "flagged"
+      description "All flagged OmniFocus items"
+
+      FIELDS = %w[id name dueDate projectName tagNames taskStatus].freeze
+
+      def payload
+        OmnifocusMcp.logger.warn("[resource:flagged] Reading flagged items")
+
+        params = Tools::Params::QueryOmnifocusParams.from_hash(
+          entity: "tasks",
+          filters: { flagged: true },
+          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/inbox_resource.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../tools/operations/query_omnifocus"
+
+module OmnifocusMcp
+  module Resources
+    # Current OmniFocus inbox items.
+    class InboxResource < Base
+      uri "omnifocus://inbox"
+      resource_name "inbox"
+      description "Current OmniFocus inbox items"
+
+      FIELDS = %w[id name flagged dueDate deferDate tagNames taskStatus note].freeze
+
+      def payload
+        OmnifocusMcp.logger.warn("[resource:inbox] Reading inbox items")
+
+        params = Tools::Params::QueryOmnifocusParams.from_hash(
+          entity: "tasks",
+          filters: { inbox: true },
+          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/perspective_resource.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../tools/operations/get_perspective_view"
+
+module OmnifocusMcp
+  module Resources
+    # Items visible in a named OmniFocus perspective.
+    #
+    # `#content` (via `#payload`) is the sole entry point.
+    class PerspectiveResource < Base
+      uri "omnifocus://perspective/{name}"
+      resource_name "perspective"
+      description "Items visible in a named OmniFocus perspective"
+
+      def payload
+        name = params[:name].to_s
+        OmnifocusMcp.logger.warn("[resource:perspective] Reading perspective: #{name}")
+
+        params = Tools::Params::GetPerspectiveViewParams.from_hash(perspective_name: name)
+        Tools::Operations::GetPerspectiveView.call(params).fold(
+          on_ok: ->(items) { snake_case_keys(items || []) },
+          on_error: ->(err) { { error: err } }
+        )
+      end
+    end
+  end
+end