things-mcp 0.1.0

data/lib/things_mcp/database.rb

@@ -0,0 +1,500 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+require "pathname"
+require "date"
+require "uri"
+
+module ThingsMcp
+  # Database access layer for Things 3 SQLite database
+  #
+  # This class provides read-only access to the Things 3 database, enabling retrieval of todos, projects, areas, and
+  # tags. It handles dynamic database path resolution and provides formatted data structures.
+  class Database
+
+    class << self
+      def find_database_path
+        group_containers_dir = "#{Dir.home}/Library/Group Containers"
+        
+        # Find Things-specific directories to avoid permission issues
+        things_dirs = Dir.glob("#{group_containers_dir}/*").select do |dir|
+          File.basename(dir).include?("culturedcode.ThingsMac")
+        end
+
+        things_dirs.each do |things_dir|
+          # Try new format first (Things 3.15.16+)
+          new_pattern = "#{things_dir}/ThingsData-*/Things Database.thingsdatabase/main.sqlite"
+          matches = Dir.glob(new_pattern)
+          return matches.first unless matches.empty?
+
+          # Fall back to old format
+          old_pattern = "#{things_dir}/Things Database.thingsdatabase/main.sqlite"
+          return old_pattern if File.exist?(old_pattern)
+        end
+
+        # Check environment variable
+        ENV["THINGSDB"] if ENV["THINGSDB"] && File.exist?(ENV["THINGSDB"])
+      end
+
+      def database_path
+        @database_path ||= find_database_path
+      end
+
+      def things_app_available?
+        system('pgrep -x "Things3" > /dev/null 2>&1')
+      end
+
+      def with_database(&block)
+        db_path = database_path
+        unless db_path
+          $stderr.puts "DEBUG: Database path search failed"
+          $stderr.puts "DEBUG: Home directory: #{Dir.home}"
+          $stderr.puts "DEBUG: Group Containers exists: #{File.exist?("#{Dir.home}/Library/Group Containers")}"
+          if File.exist?("#{Dir.home}/Library/Group Containers")
+            containers = Dir.glob("#{Dir.home}/Library/Group Containers/*")
+            $stderr.puts "DEBUG: Found containers: #{containers.size}"
+            things_containers = containers.select { |c| File.basename(c).include?("culturedcode") }
+            $stderr.puts "DEBUG: Things containers: #{things_containers}"
+          end
+          raise "Things database not found. Please ensure Things 3 is installed and has been launched at least once."
+        end
+
+        db = SQLite3::Database.new(db_path, readonly: true)
+        db.results_as_hash = true
+        yield db
+      ensure
+        db&.close
+      end
+
+      # Get all todos
+      def get_todos(project_uuid: nil, include_items: true)
+        with_database do |db|
+          query = build_todo_query(project_uuid: project_uuid)
+          results = db.execute(query)
+
+          todos = results.map { |row| format_todo(row) }
+
+          if include_items
+            todos.each do |todo|
+              todo[:checklist_items] = get_checklist_items(db, todo[:uuid])
+            end
+          end
+
+          # Always fetch tags for todos
+          todos.each do |todo|
+            todo[:tags] = get_tags_for_task(db, todo[:uuid])
+          end
+
+          todos
+        end
+      end
+
+      # Get todos from specific lists
+      def get_inbox
+        get_todos_by_start(0)
+      end
+
+      def get_today
+        get_todos_by_start(1)
+      end
+
+      def get_upcoming
+        with_database do |db|
+          query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE type = 0
+              AND status = 0
+              AND trashed = 0
+              AND start = 2
+              AND (startDate IS NOT NULL OR deadline IS NOT NULL)
+            ORDER BY COALESCE(startDate, deadline)
+          SQL
+
+          db.execute(query).map { |row| format_todo(row) }
+        end
+      end
+
+      def get_anytime
+        get_todos_by_start(2).reject { |t| t[:start_date] || t[:deadline] }
+      end
+
+      def get_someday
+        get_todos_by_start(3)
+      end
+
+      def get_logbook(period: "7d", limit: 50)
+        days = parse_period(period)
+        cutoff = Date.today - days
+
+        with_database do |db|
+          query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE type = 0
+              AND status IN (3, 2)
+              AND trashed = 0
+              AND stopDate >= julianday('#{cutoff}')
+            ORDER BY stopDate DESC
+            LIMIT #{limit}
+          SQL
+
+          db.execute(query).map { |row| format_todo(row) }
+        end
+      end
+
+      def get_trash
+        with_database do |db|
+          query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE type = 0
+              AND trashed = 1
+            ORDER BY userModificationDate DESC
+          SQL
+
+          db.execute(query).map { |row| format_todo(row) }
+        end
+      end
+
+      # Get projects
+      def get_projects(include_items: false)
+        with_database do |db|
+          query = <<~SQL
+            SELECT uuid, title, notes, status, area, start, startDate, deadline,
+                   creationDate, userModificationDate
+            FROM TMTask
+            WHERE type = 1
+              AND trashed = 0
+            ORDER BY userModificationDate DESC
+          SQL
+
+          projects = db.execute(query).map { |row| format_project(row) }
+
+          if include_items
+            projects.each do |project|
+              project[:todos] = get_todos(project_uuid: project[:uuid])
+            end
+          end
+
+          projects
+        end
+      end
+
+      # Get areas
+      def get_areas(include_items: false)
+        with_database do |db|
+          query = <<~SQL
+            SELECT uuid, title, tags
+            FROM TMArea
+            ORDER BY "index"
+          SQL
+
+          areas = db.execute(query).map { |row| format_area(row) }
+
+          if include_items
+            areas.each do |area|
+              # Get projects in this area
+              project_query = <<~SQL
+                SELECT uuid, title
+                FROM TMTask
+                WHERE type = 1
+                  AND trashed = 0
+                  AND area = '#{area[:uuid]}'
+              SQL
+
+              area[:projects] = db.execute(project_query).map do |proj|
+                { uuid: proj["uuid"], title: proj["title"] }
+              end
+            end
+          end
+
+          areas
+        end
+      end
+
+      # Get tags
+      def get_tags(include_items: false)
+        with_database do |db|
+          query = "SELECT uuid, title FROM TMTag ORDER BY title"
+
+          tags = db.execute(query).map { |row| format_tag(row) }
+
+          if include_items
+            tags.each do |tag|
+              tag[:items] = get_tagged_items(tag[:title])
+            end
+          end
+
+          tags
+        end
+      end
+
+      def get_tagged_items(tag_title)
+        with_database do |db|
+          # Find tag UUID
+          tag_result = db.execute("SELECT uuid FROM TMTag WHERE title = ?", [tag_title]).first
+          return [] unless tag_result
+
+          tag_uuid = tag_result["uuid"]
+
+          query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE type = 0
+              AND status = 0
+              AND trashed = 0
+              AND tags LIKE '%#{tag_uuid}%'
+            ORDER BY userModificationDate DESC
+          SQL
+
+          db.execute(query).map { |row| format_todo(row) }
+        end
+      end
+
+      # Search todos
+      def search_todos(query)
+        with_database do |db|
+          search_query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE type = 0
+              AND trashed = 0
+              AND (title LIKE '%#{query}%' OR notes LIKE '%#{query}%')
+            ORDER BY userModificationDate DESC
+          SQL
+
+          db.execute(search_query).map { |row| format_todo(row) }
+        end
+      end
+
+      def search_advanced(filters = {})
+        with_database do |db|
+          conditions = ["type = 0", "trashed = 0"]
+
+          # Status filter
+          if filters[:status]
+            status_map = { "incomplete" => 0, "completed" => 3, "canceled" => 2 }
+            conditions << "status = #{status_map[filters[:status]]}"
+          end
+
+          # Date filters
+          if filters[:start_date]
+            conditions << "startDate >= julianday('#{filters[:start_date]}')"
+          end
+
+          if filters[:deadline]
+            conditions << "deadline <= julianday('#{filters[:deadline]}')"
+          end
+
+          # Tag filter
+          if filters[:tag]
+            tag_result = db.execute("SELECT uuid FROM TMTag WHERE title = ?", [filters[:tag]]).first
+            conditions << "tags LIKE '%#{tag_result["uuid"]}%'" if tag_result
+          end
+
+          # Area filter
+          if filters[:area]
+            conditions << "area = '#{filters[:area]}'"
+          end
+
+          # Type filter
+          if filters[:type]
+            type_map = { "to-do" => 0, "project" => 1, "heading" => 2 }
+            conditions << "type = #{type_map[filters[:type]]}"
+          end
+
+          query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE #{conditions.join(" AND ")}
+            ORDER BY userModificationDate DESC
+          SQL
+
+          db.execute(query).map { |row| format_todo(row) }
+        end
+      end
+
+      def get_recent(period)
+        days = parse_period(period)
+        cutoff = Date.today - days
+
+        with_database do |db|
+          query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE type = 0
+              AND trashed = 0
+              AND creationDate >= julianday('#{cutoff}')
+            ORDER BY creationDate DESC
+          SQL
+
+          db.execute(query).map { |row| format_todo(row) }
+        end
+      end
+
+      private
+
+      def todo_columns
+        "uuid, title, notes, status, project, area, start, startDate, " \
+          "deadline, creationDate, userModificationDate"
+      end
+
+      def build_todo_query(project_uuid: nil)
+        base_query = <<~SQL
+          SELECT #{todo_columns}
+          FROM TMTask
+          WHERE type = 0
+            AND trashed = 0
+        SQL
+
+        base_query += " AND project = '#{project_uuid}'" if project_uuid
+        base_query + ' ORDER BY "index"'
+      end
+
+      def get_todos_by_start(start_value)
+        with_database do |db|
+          query = <<~SQL
+            SELECT #{todo_columns}
+            FROM TMTask
+            WHERE type = 0
+              AND status = 0
+              AND trashed = 0
+              AND start = #{start_value}
+            ORDER BY "index"
+          SQL
+
+          db.execute(query).map { |row| format_todo(row) }
+        end
+      end
+
+      def get_checklist_items(db, task_uuid)
+        query = <<~SQL
+          SELECT uuid, title, status
+          FROM TMChecklistItem
+          WHERE task = '#{task_uuid}'
+          ORDER BY "index"
+        SQL
+
+        db.execute(query).map do |item|
+          {
+            uuid: item["uuid"],
+            title: item["title"],
+            completed: item["status"] == 3,
+          }
+        end
+      end
+
+      def get_tags_for_task(db, task_uuid)
+        query = <<~SQL
+          SELECT TAG.title
+          FROM TMTaskTag AS TASK_TAG
+          LEFT OUTER JOIN TMTag TAG ON TAG.uuid = TASK_TAG.tags
+          WHERE TASK_TAG.tasks = ?
+          ORDER BY TAG."index"
+        SQL
+
+        db.execute(query, [task_uuid]).map { |row| row["title"] }.compact
+      end
+
+      def format_todo(row)
+        {
+          uuid: row["uuid"],
+          title: decode_title(row["title"]),
+          notes: decode_title(row["notes"]),
+          status: format_status(row["status"]),
+          project: row["project"],
+          area: row["area"],
+          tags: [],  # Tags will be populated separately
+          when: format_when(row["start"]),
+          start_date: julian_to_date(row["startDate"]),
+          deadline: julian_to_date(row["deadline"]),
+          created: julian_to_date(row["creationDate"]),
+          modified: julian_to_date(row["userModificationDate"]),
+        }
+      end
+
+      def format_project(row)
+        {
+          uuid: row["uuid"],
+          title: decode_title(row["title"]),
+          notes: decode_title(row["notes"]),
+          status: format_status(row["status"]),
+          area: row["area"],
+          tags: [],  # Tags will be populated separately for projects too
+          when: format_when(row["start"]),
+          start_date: julian_to_date(row["startDate"]),
+          deadline: julian_to_date(row["deadline"]),
+          created: julian_to_date(row["creationDate"]),
+          modified: julian_to_date(row["userModificationDate"]),
+        }
+      end
+
+      def format_area(row)
+        {
+          uuid: row["uuid"],
+          title: row["title"],
+          tags: [], # Areas can have tags but we'll implement that separately if needed
+        }
+      end
+
+      def format_tag(row)
+        {
+          uuid: row["uuid"],
+          title: row["title"],
+        }
+      end
+
+      def format_status(status)
+        case status
+        when 0 then "incomplete"
+        when 2 then "canceled"
+        when 3 then "completed"
+        else "unknown"
+        end
+      end
+
+      def format_when(start)
+        case start
+        when 0 then "inbox"
+        when 1 then "today"
+        when 2 then "anytime"
+        when 3 then "someday"
+        else "unknown"
+        end
+      end
+
+      def julian_to_date(julian_days)
+        return unless julian_days
+
+        # SQLite Julian day starts from noon on November 24, 4714 BC
+        Date.jd(julian_days.to_i + 2400001).to_s
+      end
+
+      def parse_period(period)
+        match = period.match(/^(\d+)([dwmy])$/)
+        raise ArgumentError, "Invalid period format: #{period}" unless match
+
+        number = match[1].to_i
+        unit = match[2]
+
+        case unit
+        when "d" then number
+        when "w" then number * 7
+        when "m" then number * 30
+        when "y" then number * 365
+        end
+      end
+
+      def decode_title(title)
+        return unless title
+
+        # Decode URL-encoded titles that may come from URL scheme operations
+        URI.decode_www_form_component(title.to_s)
+      rescue
+        # If decoding fails, return original title
+        title
+      end
+    end
+  end
+end

data/lib/things_mcp/formatters.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ThingsMcp
+  # Output formatters for Things 3 data
+  #
+  # This module provides formatting methods to convert raw database records into human-readable text for MCP responses.
+  module Formatters
+    extend self
+
+    def format_todo(todo)
+      lines = []
+
+      # Status indicator
+      status_icon = case todo[:status]
+      when "completed" then "✅"
+      when "canceled" then "❌"
+      else "⭕"
+      end
+
+      lines << "#{status_icon} **#{todo[:title]}**"
+      lines << "   UUID: #{todo[:uuid]}" if todo[:uuid]
+
+      # Notes
+      if todo[:notes] && !todo[:notes].empty?
+        lines << "   Notes: #{todo[:notes].gsub("\n", " ")}"
+      end
+
+      # When/scheduling
+      if todo[:when] && todo[:when] != "unknown"
+        lines << "   When: #{todo[:when]}"
+      end
+
+      if todo[:start_date]
+        lines << "   Start: #{todo[:start_date]}"
+      end
+
+      if todo[:deadline]
+        lines << "   Deadline: #{todo[:deadline]}"
+      end
+
+      # Tags
+      if todo[:tags] && !todo[:tags].empty?
+        lines << "   Tags: #{todo[:tags].join(", ")}"
+      end
+
+      # Checklist items
+      if todo[:checklist_items] && !todo[:checklist_items].empty?
+        lines << "   Checklist:"
+        todo[:checklist_items].each do |item|
+          check = item[:completed] ? "✓" : "○"
+          lines << "     #{check} #{item[:title]}"
+        end
+      end
+
+      # Metadata
+      if todo[:created]
+        lines << "   Created: #{todo[:created]}"
+      end
+
+      if todo[:modified]
+        lines << "   Modified: #{todo[:modified]}"
+      end
+
+      lines.join("\n")
+    end
+
+    def format_project(project)
+      lines = []
+
+      # Status indicator
+      status_icon = case project[:status]
+      when "completed" then "✅"
+      when "canceled" then "❌"
+      else "📁"
+      end
+
+      lines << "#{status_icon} **#{project[:title]}** (Project)"
+      lines << "   UUID: #{project[:uuid]}" if project[:uuid]
+
+      # Notes
+      if project[:notes] && !project[:notes].empty?
+        lines << "   Notes: #{project[:notes].gsub("\n", " ")}"
+      end
+
+      # When/scheduling
+      if project[:when] && project[:when] != "unknown"
+        lines << "   When: #{project[:when]}"
+      end
+
+      if project[:start_date]
+        lines << "   Start: #{project[:start_date]}"
+      end
+
+      if project[:deadline]
+        lines << "   Deadline: #{project[:deadline]}"
+      end
+
+      # Tags
+      if project[:tags] && !project[:tags].empty?
+        lines << "   Tags: #{project[:tags].join(", ")}"
+      end
+
+      # Todos within project
+      if project[:todos] && !project[:todos].empty?
+        lines << "   Todos:"
+        project[:todos].each do |todo|
+          status = todo[:status] == "completed" ? "✓" : "○"
+          lines << "     #{status} #{todo[:title]}"
+        end
+      end
+
+      lines.join("\n")
+    end
+
+    def format_area(area)
+      lines = []
+
+      lines << "🏷️ **#{area[:title]}** (Area)"
+      lines << "   UUID: #{area[:uuid]}" if area[:uuid]
+
+      # Tags
+      if area[:tags] && !area[:tags].empty?
+        lines << "   Tags: #{area[:tags].join(", ")}"
+      end
+
+      # Projects within area
+      if area[:projects] && !area[:projects].empty?
+        lines << "   Projects:"
+        area[:projects].each do |project|
+          lines << "     📁 #{project[:title]}"
+        end
+      end
+
+      lines.join("\n")
+    end
+
+    def format_tag(tag)
+      lines = []
+
+      lines << "🏷️ #{tag[:title]}"
+
+      if tag[:items] && !tag[:items].empty?
+        lines << "   Items: #{tag[:items].size}"
+      end
+
+      lines.join("\n")
+    end
+
+  end
+end