things-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b5dce71de1e5a5690e3acbf04a39844482fd77a225255e6c0f6ed6174c14746
+  data.tar.gz: 2ae46521ad48efabb5ea24351f9bae9fc36df2ea1017e0f5a3ff4ef1b7ca6362
+SHA512:
+  metadata.gz: cb4149f6a999b9928d25d889a8b0d48f998d76c07573588a6b1dfff94a86ccfa2a4ee75156093c9c22483d7822852cbb2559de0418b58217e229cfb8d2f21cf5
+  data.tar.gz: d919bf9e96b98c7b8e54d69067f8a7aec30d4e53a0f62398fb30c54eadaedce0c18a95c1e12b2878444600356496f4c45a9332a143b8542feb876f81f05be23d

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+# Development dependencies
+group :development do
+  gem "rake"
+  gem "rubocop-shopify", require: false
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Things MCP Ruby Contributors
+
+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,221 @@
+# Things 3 MCP Server (Ruby)
+
+A Model Context Protocol (MCP) server for Things 3, implemented in Ruby.
+
+## Features
+
+- Access Things 3 todos, projects, areas, and tags
+- Create and update todos and projects
+- Search todos with advanced filters
+- Access built-in lists (Inbox, Today, Upcoming, etc.)
+- Complete Things URL scheme support
+
+## Prerequisites
+
+1. **Things 3** must be installed on your Mac
+2. **Ruby 3.2+** installed (required by the MCP gem dependency)
+3. **No authentication required** - the server reads from Things' local database
+
+> **Note for macOS users**: The system Ruby (typically 2.6.x) is too old. Install a modern Ruby version:
+> ```bash
+> # Using Homebrew (recommended)
+> brew install ruby
+> 
+> # Or using rbenv
+> brew install rbenv
+> rbenv install 3.4.1
+> rbenv global 3.4.1
+> ```
+
+## Installation
+
+1. Clone this repository:
+
+```bash
+git clone https://github.com/hakanensari/things-mcp-ruby.git
+cd things-mcp-ruby
+```
+
+2. Install dependencies:
+
+```bash
+bundle install
+```
+
+## Testing the Installation
+
+1. **Basic test** (database + create operations):
+
+```bash
+bin/test_connection
+```
+
+2. **Full test** (including update operations):
+
+```bash
+THINGS_AUTH_TOKEN=your_token_here bin/test_connection
+```
+
+3. **Via Rake:**
+
+```bash
+bundle exec rake test
+```
+
+The test script will:
+
+- ✓ Check if Things app is running
+- ✓ Test database connectivity
+- ✓ Test handler functionality
+- ✓ Create a test todo via URL scheme
+- ✓ Verify the todo in the database
+- ✓ Test update operations by completing the test todo (if auth token provided)
+
+2. Run the MCP server:
+
+```bash
+bundle exec ruby bin/things_mcp_server
+```
+
+## Configuration
+
+This MCP server implements the [Model Context Protocol](https://modelcontextprotocol.io/) and can be used with any MCP-compatible AI system.
+
+### Claude Desktop
+
+### Basic Configuration (Read + Create Operations)
+
+Add to your Claude Desktop configuration file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "things": {
+      "command": "ruby",
+      "args": ["bin/things_mcp_server"],
+      "cwd": "/path/to/things-mcp-ruby"
+    }
+  }
+}
+```
+
+### Full Configuration (Including Update Operations)
+
+For `update-todo` and `update-project` operations, you need to provide a Things authorization token:
+
+1. **Get your authorization token from Things:**
+
+   - Open Things 3
+   - Go to **Things → Settings → General**
+   - Click **Enable Things URLs**
+   - Click **Manage**
+   - Copy the authorization token
+
+2. **Add the token to your configuration:**
+
+```json
+{
+  "mcpServers": {
+    "things": {
+      "command": "ruby",
+      "args": ["bin/things_mcp_server"],
+      "cwd": "/path/to/things-mcp-ruby",
+      "env": {
+        "THINGS_AUTH_TOKEN": "your_authorization_token_here"
+      }
+    }
+  }
+}
+```
+
+⚠️ **Security Note:** Keep your authorization token private. It allows full access to modify your Things data.
+
+### Other MCP Clients
+
+For other MCP-compatible clients, run the server manually and connect via stdio:
+
+```bash
+# Start the MCP server
+bundle exec ruby bin/things_mcp_server
+
+# The server communicates via JSON-RPC over stdio
+# See the MCP specification for integration details:
+# https://modelcontextprotocol.io/specification/
+```
+
+## Usage
+
+Once configured, you can use your MCP-compatible AI client to:
+
+- "Show me my todos from today"
+- "Create a new todo called 'Buy groceries' for tomorrow"
+- "Search for todos containing 'meeting'"
+- "Show all my projects"
+
+## Available Tools
+
+### Basic Operations
+
+- `get-todos` - Get todos from Things, optionally filtered by project
+- `get-projects` - Get all projects from Things
+- `get-areas` - Get all areas from Things
+
+### List Views
+
+- `get-inbox` - Get todos from Inbox
+- `get-today` - Get todos due today
+- `get-upcoming` - Get upcoming todos
+- `get-anytime` - Get todos from Anytime list
+- `get-someday` - Get todos from Someday list
+- `get-logbook` - Get completed todos from Logbook
+- `get-trash` - Get trashed todos
+
+### Tag Operations
+
+- `get-tags` - Get all tags
+- `get-tagged-items` - Get items with a specific tag
+
+### Search Operations
+
+- `search-todos` - Search todos by title or notes
+- `search-advanced` - Advanced todo search with multiple filters
+
+### Recent Items
+
+- `get-recent` - Get recently created items
+
+### Modification Operations
+
+- `add-todo` - Create a new todo in Things
+- `add-project` - Create a new project in Things
+- `update-todo` - Update an existing todo ⚠️ _Requires auth token_
+- `update-project` - Update an existing project ⚠️ _Requires auth token_
+- `show-item` - Show a specific item or list in Things
+- `search-items` - Search for items and open in Things
+
+## Development
+
+Run tests:
+
+```bash
+bundle exec rake test
+```
+
+Run linter:
+
+```bash
+bundle exec rake rubocop
+```
+
+Run both tests and linter:
+
+```bash
+bundle exec rake
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new

data/bin/test_connection

@@ -0,0 +1,118 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require_relative "../lib/things_mcp"
+
+puts "Testing Things MCP Ruby Server"
+puts "=" * 40
+
+# Test 1: Things app availability
+puts "\n1. Testing Things app availability..."
+begin
+  if ThingsMcp::Database.things_app_available?
+    puts "✅ Things app is running"
+  else
+    puts "❌ Things app is not running"
+    puts "  Please start Things 3 and try again"
+    @test_failed = true
+  end
+rescue => e
+  puts "❌ Error checking Things app: #{e.message}"
+  @test_failed = true
+end
+
+# Test 2: Database access
+puts "\n2. Testing database access..."
+begin
+  todos = ThingsMcp::Database.get_inbox
+  puts "✅ Database accessible"
+  puts "  Found #{todos.size} todos in Inbox"
+rescue => e
+  puts "❌ Database error: #{e.message}"
+  puts "  #{e.backtrace.first}"
+  @test_failed = true
+end
+
+# Test 3: Handler functionality
+puts "\n3. Testing handler functionality..."
+begin
+  result = ThingsMcp::Handlers.handle_tool_call("get-inbox", {})
+  puts "✅ Handler working"
+  puts "  Result preview: #{result[0..100]}..."
+rescue => e
+  puts "❌ Handler error: #{e.message}"
+  puts "  #{e.backtrace.first}"
+  @test_failed = true
+end
+
+# Test 4: URL Scheme - Create todo
+puts "\n4. Testing URL scheme (create todo)..."
+test_todo_title = "Test MCP server #{Time.now.strftime("%H:%M:%S")}"
+begin
+  result = ThingsMcp::UrlScheme.add_todo({
+    "title" => test_todo_title,
+    "notes" => "This is a test todo created by the MCP server test script",
+  })
+
+  if result[:success]
+    puts "✅ URL scheme working - test todo created"
+    puts "  Todo: '#{test_todo_title}'"
+
+    # Test update operations if auth token is available
+    if ENV["THINGS_AUTH_TOKEN"]
+      puts "\n5. Testing URL scheme (update/cleanup)..."
+      puts "  Using auth token for update operation..."
+
+      # Brief retry to find the created todo (database sync is not immediate)
+      puts "  Searching for created todo in database..."
+      test_todo = nil
+      3.times do |i|
+        inbox_todos = ThingsMcp::Database.get_inbox
+        test_todo = inbox_todos.find { |t| t[:title] == test_todo_title }
+        break if test_todo
+        sleep(1) if i < 2  # Don't sleep after the last attempt
+      end
+
+      if test_todo
+        puts "✅ Todo found in database"
+        complete_result = ThingsMcp::UrlScheme.update_todo({
+          "id" => test_todo[:uuid],
+          "completed" => true,
+        })
+
+        if complete_result[:success]
+          puts "✅ Update operations working - test todo completed and cleaned up"
+        else
+          puts "❌ Could not complete test todo: #{complete_result[:error]}"
+          puts "  You may need to manually complete: '#{test_todo_title}'"
+          @test_failed = true
+        end
+      else
+        puts "❌ Could not find test todo in database after 3 attempts"
+        puts "  Database sync delay longer than expected - please manually complete: '#{test_todo_title}'"
+        @test_failed = true
+      end
+    end
+  else
+    puts "❌ URL scheme failed: #{result[:error]}"
+    @test_failed = true
+  end
+rescue => e
+  puts "❌ URL scheme error: #{e.message}"
+  puts "  #{e.backtrace.first}"
+  @test_failed = true
+end
+
+puts "\n" + "=" * 40
+puts "Test completed!"
+
+if ENV["THINGS_AUTH_TOKEN"]
+  puts "✅ Full testing (with auth token)"
+else
+  puts "⚠️  Partial testing (no auth token for updates)"
+  puts "   Set THINGS_AUTH_TOKEN=your_token to test update operations"
+end
+
+# Exit with error if there were any failures
+exit 1 if defined?(@test_failed)

data/bin/things_mcp_server

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require_relative "../lib/things_mcp/server"
+
+# Run the MCP server
+ThingsMcp::Server.new.run