things-mcp 0.1.0

data/lib/things_mcp/tools.rb

@@ -0,0 +1,463 @@
+# frozen_string_literal: true
+
+module ThingsMcp
+  # MCP tool definitions for Things 3 integration
+  #
+  # This module defines all available MCP tools with their schemas, descriptions, and parameter definitions for
+  # interaction with Things 3.
+  module Tools
+    class << self
+      # Returns all available MCP tool definitions
+      #
+      # @return [Array<Hash>] Array of tool definition hashes
+      def all
+        [
+          # Basic operations
+          {
+            name: "get-todos",
+            description: "Get todos from Things, optionally filtered by project",
+            inputSchema: {
+              type: "object",
+              properties: {
+                project_uuid: {
+                  type: "string",
+                  description: "Optional UUID of a specific project to get todos from",
+                },
+                include_items: {
+                  type: "boolean",
+                  description: "Include checklist items",
+                  default: true,
+                },
+              },
+              required: [],
+            },
+          },
+          {
+            name: "get-projects",
+            description: "Get all projects from Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                include_items: {
+                  type: "boolean",
+                  description: "Include tasks within projects",
+                  default: false,
+                },
+              },
+              required: [],
+            },
+          },
+          {
+            name: "get-areas",
+            description: "Get all areas from Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                include_items: {
+                  type: "boolean",
+                  description: "Include projects and tasks within areas",
+                  default: false,
+                },
+              },
+              required: [],
+            },
+          },
+
+          # List views
+          {
+            name: "get-inbox",
+            description: "Get todos from Inbox",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+          {
+            name: "get-today",
+            description: "Get todos due today",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+          {
+            name: "get-upcoming",
+            description: "Get upcoming todos",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+          {
+            name: "get-anytime",
+            description: "Get todos from Anytime list",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+          {
+            name: "get-someday",
+            description: "Get todos from Someday list",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+          {
+            name: "get-logbook",
+            description: "Get completed todos from Logbook, defaults to last 7 days",
+            inputSchema: {
+              type: "object",
+              properties: {
+                period: {
+                  type: "string",
+                  description: "Time period to look back (e.g., '3d', '1w', '2m', '1y'). Defaults to '7d'",
+                  pattern: '^\\d+[dwmy]$',
+                },
+                limit: {
+                  type: "integer",
+                  description: "Maximum number of entries to return. Defaults to 50",
+                  minimum: 1,
+                  maximum: 100,
+                },
+              },
+              required: [],
+            },
+          },
+          {
+            name: "get-trash",
+            description: "Get trashed todos",
+            inputSchema: {
+              type: "object",
+              properties: {},
+              required: [],
+            },
+          },
+
+          # Tag operations
+          {
+            name: "get-tags",
+            description: "Get all tags",
+            inputSchema: {
+              type: "object",
+              properties: {
+                include_items: {
+                  type: "boolean",
+                  description: "Include items tagged with each tag",
+                  default: false,
+                },
+              },
+              required: [],
+            },
+          },
+          {
+            name: "get-tagged-items",
+            description: "Get items with a specific tag",
+            inputSchema: {
+              type: "object",
+              properties: {
+                tag: {
+                  type: "string",
+                  description: "Tag title to filter by",
+                },
+              },
+              required: ["tag"],
+            },
+          },
+
+          # Search operations
+          {
+            name: "search-todos",
+            description: "Search todos by title or notes",
+            inputSchema: {
+              type: "object",
+              properties: {
+                query: {
+                  type: "string",
+                  description: "Search term to look for in todo titles and notes",
+                },
+              },
+              required: ["query"],
+            },
+          },
+          {
+            name: "search-advanced",
+            description: "Advanced todo search with multiple filters",
+            inputSchema: {
+              type: "object",
+              properties: {
+                status: {
+                  type: "string",
+                  enum: ["incomplete", "completed", "canceled"],
+                  description: "Filter by todo status",
+                },
+                start_date: {
+                  type: "string",
+                  description: "Filter by start date (YYYY-MM-DD)",
+                },
+                deadline: {
+                  type: "string",
+                  description: "Filter by deadline (YYYY-MM-DD)",
+                },
+                tag: {
+                  type: "string",
+                  description: "Filter by tag",
+                },
+                area: {
+                  type: "string",
+                  description: "Filter by area UUID",
+                },
+                type: {
+                  type: "string",
+                  enum: ["to-do", "project", "heading"],
+                  description: "Filter by item type",
+                },
+              },
+              required: [],
+            },
+          },
+
+          # Recent items
+          {
+            name: "get-recent",
+            description: "Get recently created items",
+            inputSchema: {
+              type: "object",
+              properties: {
+                period: {
+                  type: "string",
+                  description: "Time period (e.g., '3d', '1w', '2m', '1y')",
+                  pattern: '^\\d+[dwmy]$',
+                },
+              },
+              required: ["period"],
+            },
+          },
+
+          # Things URL Scheme tools
+          {
+            name: "add-todo",
+            description: "Create a new todo in Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                title: {
+                  type: "string",
+                  description: "Title of the todo",
+                },
+                notes: {
+                  type: "string",
+                  description: "Notes for the todo",
+                },
+                when: {
+                  type: "string",
+                  description: "When to schedule the todo (today, tomorrow, evening, anytime, someday, or YYYY-MM-DD)",
+                },
+                deadline: {
+                  type: "string",
+                  description: "Deadline for the todo (YYYY-MM-DD)",
+                },
+                tags: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Tags to apply to the todo",
+                },
+                checklist_items: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Checklist items to add",
+                },
+                list_id: {
+                  type: "string",
+                  description: "ID of project/area to add to",
+                },
+                list_title: {
+                  type: "string",
+                  description: "Title of project/area to add to",
+                },
+                heading: {
+                  type: "string",
+                  description: "Heading to add under",
+                },
+              },
+              required: ["title"],
+            },
+          },
+          {
+            name: "add-project",
+            description: "Create a new project in Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                title: {
+                  type: "string",
+                  description: "Title of the project",
+                },
+                notes: {
+                  type: "string",
+                  description: "Notes for the project",
+                },
+                when: {
+                  type: "string",
+                  description: "When to schedule the project",
+                },
+                deadline: {
+                  type: "string",
+                  description: "Deadline for the project",
+                },
+                tags: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Tags to apply to the project",
+                },
+                area_id: {
+                  type: "string",
+                  description: "ID of area to add to",
+                },
+                area_title: {
+                  type: "string",
+                  description: "Title of area to add to",
+                },
+                todos: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Initial todos to create in the project",
+                },
+              },
+              required: ["title"],
+            },
+          },
+          {
+            name: "update-todo",
+            description: "Update an existing todo in Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                id: {
+                  type: "string",
+                  description: "ID of the todo to update",
+                },
+                title: {
+                  type: "string",
+                  description: "New title",
+                },
+                notes: {
+                  type: "string",
+                  description: "New notes",
+                },
+                when: {
+                  type: "string",
+                  description: "New schedule",
+                },
+                deadline: {
+                  type: "string",
+                  description: "New deadline",
+                },
+                tags: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "New tags",
+                },
+                completed: {
+                  type: "boolean",
+                  description: "Mark as completed",
+                },
+                canceled: {
+                  type: "boolean",
+                  description: "Mark as canceled",
+                },
+              },
+              required: ["id"],
+            },
+          },
+          {
+            name: "update-project",
+            description: "Update an existing project in Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                id: {
+                  type: "string",
+                  description: "ID of the project to update",
+                },
+                title: {
+                  type: "string",
+                  description: "New title",
+                },
+                notes: {
+                  type: "string",
+                  description: "New notes",
+                },
+                when: {
+                  type: "string",
+                  description: "New schedule",
+                },
+                deadline: {
+                  type: "string",
+                  description: "New deadline",
+                },
+                tags: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "New tags",
+                },
+                completed: {
+                  type: "boolean",
+                  description: "Mark as completed",
+                },
+                canceled: {
+                  type: "boolean",
+                  description: "Mark as canceled",
+                },
+              },
+              required: ["id"],
+            },
+          },
+          {
+            name: "search-items",
+            description: "Search for items in Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                query: {
+                  type: "string",
+                  description: "Search query",
+                },
+              },
+              required: ["query"],
+            },
+          },
+          {
+            name: "show-item",
+            description: "Show a specific item or list in Things",
+            inputSchema: {
+              type: "object",
+              properties: {
+                id: {
+                  type: "string",
+                  description: "ID of item to show, or one of: inbox, today, upcoming, anytime, someday, logbook",
+                },
+                query: {
+                  type: "string",
+                  description: "Optional query to filter by",
+                },
+                filter_tags: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: "Optional tags to filter by",
+                },
+              },
+              required: ["id"],
+            },
+          },
+        ]
+      end
+    end
+  end
+end

data/lib/things_mcp/url_scheme.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+require "open3"
+
+module ThingsMcp
+  # Things 3 URL scheme integration
+  #
+  # This module provides methods for creating and updating todos and projects using Things 3's URL scheme. It handles
+  # authentication tokens for update operations and manages the Things 3 application lifecycle.
+  module UrlScheme
+    extend self
+
+    THINGS_URL_BASE = "things:///"
+
+    def add_todo(params)
+      url_params = {
+        "title" => params["title"],
+      }
+
+      # Optional parameters
+      url_params["notes"] = params["notes"] if params["notes"]
+      url_params["when"] = params["when"] if params["when"]
+      url_params["deadline"] = params["deadline"] if params["deadline"]
+      url_params["tags"] = params["tags"].join(",") if params["tags"]
+      url_params["checklist-items"] = params["checklist_items"].join("\n") if params["checklist_items"]
+      url_params["list-id"] = params["list_id"] if params["list_id"]
+      url_params["list"] = params["list_title"] if params["list_title"]
+      url_params["heading"] = params["heading"] if params["heading"]
+
+      execute_url("#{THINGS_URL_BASE}add", url_params)
+    end
+
+    def add_project(params)
+      url_params = {
+        "title" => params["title"],
+        "type" => "project",
+      }
+
+      # Optional parameters
+      url_params["notes"] = params["notes"] if params["notes"]
+      url_params["when"] = params["when"] if params["when"]
+      url_params["deadline"] = params["deadline"] if params["deadline"]
+      url_params["tags"] = params["tags"].join(",") if params["tags"]
+      url_params["area-id"] = params["area_id"] if params["area_id"]
+      url_params["area"] = params["area_title"] if params["area_title"]
+      url_params["to-dos"] = params["todos"].join("\n") if params["todos"]
+
+      execute_url("#{THINGS_URL_BASE}add-project", url_params)
+    end
+
+    def update_todo(params)
+      url_params = {
+        "id" => params["id"],
+      }
+
+      # Optional update parameters
+      url_params["title"] = params["title"] if params["title"]
+      url_params["notes"] = params["notes"] if params["notes"]
+      url_params["when"] = params["when"] if params["when"]
+      url_params["deadline"] = params["deadline"] if params["deadline"]
+      # Use add-tags to append tags (might work better for new tags)
+      url_params["add-tags"] = params["tags"].join(",") if params["tags"]
+      url_params["completed"] = "true" if params["completed"]
+      url_params["canceled"] = "true" if params["canceled"]
+
+      execute_url("#{THINGS_URL_BASE}update", url_params)
+    end
+
+    def update_project(params)
+      url_params = {
+        "id" => params["id"],
+        "type" => "project",
+      }
+
+      # Optional update parameters
+      url_params["title"] = params["title"] if params["title"]
+      url_params["notes"] = params["notes"] if params["notes"]
+      url_params["when"] = params["when"] if params["when"]
+      url_params["deadline"] = params["deadline"] if params["deadline"]
+      url_params["tags"] = params["tags"].join(",") if params["tags"]
+      url_params["completed"] = "true" if params["completed"]
+      url_params["canceled"] = "true" if params["canceled"]
+
+      execute_url("#{THINGS_URL_BASE}update-project", url_params)
+    end
+
+    def search_items(query)
+      execute_url("#{THINGS_URL_BASE}search", { "query" => query })
+    end
+
+    def show_item(params)
+      url_params = {
+        "id" => params["id"],
+      }
+
+      url_params["query"] = params["query"] if params["query"]
+      url_params["filter"] = params["filter_tags"].join(",") if params["filter_tags"]
+
+      execute_url("#{THINGS_URL_BASE}show", url_params)
+    end
+
+    private
+
+    def execute_url(base_url, params = {})
+      # Add auth token for operations that require it
+      if needs_auth_token?(base_url) && ENV["THINGS_AUTH_TOKEN"]
+        params["auth-token"] = ENV["THINGS_AUTH_TOKEN"]
+      end
+
+      # Build query string and convert + to %20 for spaces
+      query_string = URI.encode_www_form(params)
+      query_string = query_string.gsub("+", "%20") unless query_string.empty?
+      
+      full_url = query_string.empty? ? base_url : "#{base_url}?#{query_string}"
+
+
+      # Ensure Things is running
+      unless things_running?
+        launch_things
+        sleep(2)
+      end
+
+      # Open the URL
+      _, stderr, status = Open3.capture3("open", full_url)
+
+      if status.success?
+        { success: true }
+      else
+        { success: false, error: stderr }
+      end
+    rescue => e
+      { success: false, error: e.message }
+    end
+
+    def things_running?
+      system('pgrep -x "Things3" > /dev/null 2>&1')
+    end
+
+    def launch_things
+      system("open -a Things3")
+    end
+
+    def needs_auth_token?(url)
+      # Operations that require authentication token
+      auth_required_operations = [
+        "things:///update",
+        "things:///update-project",
+      ]
+
+      auth_required_operations.any? { |op| url.start_with?(op) }
+    end
+
+  end
+end

data/lib/things_mcp.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "things_mcp/server"
+require_relative "things_mcp/database"
+require_relative "things_mcp/handlers"
+require_relative "things_mcp/tools"
+require_relative "things_mcp/url_scheme"
+require_relative "things_mcp/formatters"
+
+# ThingsMcp provides a Model Context Protocol (MCP) server for Things 3
+#
+# This module enables integration with Things 3 through both database access and URL scheme operations, providing read
+# access to todos, projects, areas, and tags, as well as create and update operations.
+module ThingsMcp
+  # Base error class for ThingsMcp
+  class Error < StandardError; end
+
+  # Error raised when database operations fail
+  class DatabaseError < Error; end
+
+  # Error raised when URL scheme operations fail
+  class UrlSchemeError < Error; end
+end