tickrb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1259ef1c25eaefaeb97799c08b14263216e146fcbbdbcb2ca9402df91efb437e
+  data.tar.gz: 8bb1528dd50101fa6516b8b386e1762125d082f3ac46865d3d50095e1c5107eb
+SHA512:
+  metadata.gz: 69fb625733958656d9fd280ad6096f994008c9d634af87711388c01da7bbb14d4eeb11f86467fe27b82a89ae2c62a70b11190c80d35573c4b9716ca46b735fb1
+  data.tar.gz: 1992e85fa8c9dbdb29c0311ded01ef7a02c6b4cab3785fbd516d8a837bcf95c2f992a269b012e255341f19e4a8e09dc2eb7331897661c14a4f00769ceb2d0855

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,15 @@
+require:
+  - standard
+
+plugins:
+  - standard-custom
+  - standard-performance
+  - rubocop-performance
+
+inherit_gem:
+  standard: config/base.yml
+  standard-custom: config/base.yml
+  standard-performance: config/base.yml
+
+AllCops:
+  SuggestExtensions: false

data/Gemfile

@@ -0,0 +1,17 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in tickrb.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "sorbet-runtime"
+gem "webrick"
+gem "net-http"
+gem "uri"
+
+gem "sorbet", "~> 0.5", group: :development
+gem "tapioca", require: false, group: %i[development test]
+gem "rspec-sorbet-types", group: :development
+gem "standard", group: :development
+gem "dotenv", groups: [:development, :test]

data/Gemfile.lock

@@ -0,0 +1,143 @@
+PATH
+  remote: .
+  specs:
+    tickrb (0.1.0)
+      net-http
+      sorbet-runtime
+      uri
+      webrick
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    benchmark (0.4.1)
+    diff-lcs (1.6.2)
+    dotenv (3.1.8)
+    erubi (1.13.1)
+    json (2.12.2)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    net-http (0.6.0)
+      uri
+    netrc (0.11.0)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.4.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    rbi (0.3.3)
+      prism (~> 1.0)
+      rbs (>= 3.4.4)
+      sorbet-runtime (>= 0.5.9204)
+    rbs (3.9.4)
+      logger
+    regexp_parser (2.10.0)
+    rexml (3.4.1)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.4)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-sorbet-types (0.3.0)
+      rspec (~> 3.0)
+      sorbet-runtime
+      tapioca (>= 0.16)
+    rspec-support (3.13.4)
+    rubocop (1.75.8)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.45.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    sorbet (0.5.12149)
+      sorbet-static (= 0.5.12149)
+    sorbet-runtime (0.5.12149)
+    sorbet-static (0.5.12149-universal-darwin)
+    sorbet-static-and-runtime (0.5.12149)
+      sorbet (= 0.5.12149)
+      sorbet-runtime (= 0.5.12149)
+    spoom (1.6.3)
+      erubi (>= 1.10.0)
+      prism (>= 0.28.0)
+      rbi (>= 0.3.3)
+      rexml (>= 3.2.6)
+      sorbet-static-and-runtime (>= 0.5.10187)
+      thor (>= 0.19.2)
+    standard (1.50.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.75.5)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    tapioca (0.16.11)
+      benchmark
+      bundler (>= 2.2.25)
+      netrc (>= 0.11.0)
+      parallel (>= 1.21.0)
+      rbi (~> 0.2)
+      sorbet-static-and-runtime (>= 0.5.11087)
+      spoom (>= 1.2.0)
+      thor (>= 1.2.0)
+      yard-sorbet
+    thor (1.3.2)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+    uri (1.0.3)
+    webrick (1.9.1)
+    yard (0.9.37)
+    yard-sorbet (0.9.0)
+      sorbet-runtime
+      yard
+
+PLATFORMS
+  x86_64-darwin-22
+
+DEPENDENCIES
+  dotenv
+  net-http
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rspec-sorbet-types
+  rubocop (~> 1.21)
+  sorbet (~> 0.5)
+  sorbet-runtime
+  standard
+  tapioca
+  tickrb!
+  uri
+  webrick
+
+BUNDLED WITH
+   2.4.9

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Graham Turner 
+
+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,112 @@
+# TickRb
+
+A Ruby gem that provides TickTick integration through a Model Context Protocol (MCP) server, enabling Claude and other AI assistants to manage your TickTick tasks seamlessly.
+
+## Quick Start
+
+1. **Install the gem**: `gem install tickrb`
+2. **Get TickTick credentials** from [TickTick Developer Console](https://developer.ticktick.com/)
+3. **Configure Claude** with your credentials in MCP config
+4. **Authenticate**: The first time Claude starts TickRb MCP server, it will prompt for OAuth.
+5. **Start chatting** with Claude about your tasks!
+
+## Installation
+
+    $ gem install tickrb
+
+## Setup
+
+Before using TickRb, you need to create a TickTick application to get OAuth credentials:
+
+1. Go to [TickTick Developer Console](https://developer.ticktick.com/)
+2. Create a new application
+3. Note your `Client ID` and `Client Secret`
+4. Set the redirect URI to `http://localhost:8080/callback`
+
+## Usage
+
+After installing the MCP server, the first usage will open a browser window to authenticate with ticktick.
+
+### Claude Desktop Configuration
+
+For Claude Desktop, add this to your MCP settings file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "tickrb": {
+      "command": "tickrb-mcp-server",
+      "args": [
+        "--client-id", "your_ticktick_client_id",
+        "--client-secret", "your_ticktick_client_secret"
+      ]
+    }
+  }
+}
+```
+
+### Claude Code (CLI) Configuration
+
+For Claude Code, add the MCP server to your configuration:
+
+```bash
+# Add the MCP server with credentials
+claude-code mcp install tickrb tickrb-mcp-server --client-id your_ticktick_client_id --client-secret your_ticktick_client_secret
+```
+
+### Available MCP Tools
+
+Once connected to Claude, you can use these natural language commands:
+
+- **"List my tasks"** - Shows all your TickTick tasks
+- **"Create a task called 'Buy groceries'"** - Creates a new task
+- **"Complete the task with ID xyz"** - Marks a task as complete
+- **"Delete the task with ID xyz"** - Removes a task
+- **"Show my projects"** - Lists all your TickTick projects
+
+## Configuration
+
+### Token Storage
+
+Authentication tokens are stored in `~/.config/tickrb/token.json`.
+
+### Command Line Help
+
+To see all available options:
+
+```bash
+tickrb-mcp-server --help
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. 
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run complete pipeline (tests + linting + type checking)
+bundle exec rake ci
+
+# Run individual quality checks
+bundle exec rake test      # Tests only
+bundle exec rake lint      # Linting only  
+bundle exec rake typecheck # Type checking only
+bundle exec rake fix       # Auto-fix linting issues
+```
+
+### Type Checking
+
+This gem uses [Sorbet](https://sorbet.org/) for static type checking. Common Sorbet commands:
+
+- `bundle exec rake typecheck` - Run type checker
+- `bundle exec rake rbi` - Update RBI files
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = "--format progress"
+  t.verbose = false
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+begin
+  require "tapioca/internal"
+rescue LoadError
+  # tapioca tasks won't be available
+end
+
+task default: %i[spec rubocop typecheck]
+
+desc "Run all tests"
+task test: :spec
+
+desc "Run linting"
+task lint: :rubocop
+
+desc "Run type checking"
+task typecheck: "sorbet:tc"
+
+desc "Run type checking"
+task rbi: "sorbet:rbi"
+
+desc "Run all quality checks (tests, lint, typecheck)"
+task ci: [:spec, :rubocop, :rbi, :typecheck]
+
+desc "Auto-fix linting issues"
+task :fix do
+  sh "bundle exec rubocop --auto-correct-all"
+end
+
+namespace :sorbet do
+  desc "Run Sorbet type checker"
+  task :tc do
+    sh "bundle exec srb tc"
+  end
+
+  desc "Update RBI files"
+  task :rbi do
+    sh "bundle exec tapioca gems"
+  end
+end

data/lib/tickrb/auth.rb

@@ -0,0 +1,106 @@
+# typed: true
+# frozen_string_literal: true
+
+require "webrick"
+require "net/http"
+require "uri"
+require "base64"
+require "json"
+
+require_relative "token_store"
+
+AUTH_URL = "https://ticktick.com/oauth/authorize?"
+
+module Tickrb
+  class Auth
+    class << self
+      def run(client_id: nil, client_secret: nil, redirect_uri: nil)
+        auth_client = new(
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri
+        )
+        auth_client.run_oauth_flow
+      end
+    end
+
+    def initialize(client_id: nil, client_secret: nil, redirect_uri: nil, token_store: nil)
+      @client_id = client_id || ENV["CLIENT_ID"]
+      @client_secret = client_secret || ENV["CLIENT_SECRET"]
+      @redirect_uri = redirect_uri || ENV["REDIRECT_URI"]
+      @token_store = token_store || TokenStore
+    end
+
+    def run_oauth_flow
+      # Start local server to receive callback
+      server = WEBrick::HTTPServer.new(Port: 8080, Logger: WEBrick::Log.new(File::NULL))
+
+      # TODO: Generate a random state parameter for CSRF protection
+      auth_params = {
+        client_id: client_id,
+        scope: scope,
+        redirect_uri: redirect_uri,
+        response_type: "code"
+      }
+
+      auth_url_params = build_auth_url_params(auth_params)
+      auth_url = AUTH_URL + auth_url_params
+
+      system("open \"#{auth_url}\"") # macOS, use 'xdg-open' on Linux
+
+      # Handle callback
+      server.mount_proc "/callback", ->(req, res) do
+        code = req.query["code"]
+        # Exchange code for token
+        token_info = exchange_code_for_token(code)
+        token_store.store_token(token_info)
+
+        res.body = "Authentication successful! You can close this window."
+        server.shutdown
+      end
+
+      server.start
+    end
+
+    private
+
+    attr_reader :client_id, :client_secret, :redirect_uri, :token_store
+
+    def exchange_code_for_token(code)
+      uri = URI("https://ticktick.com/oauth/token")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Post.new(uri)
+      token_data = {
+        grant_type: "authorization_code",
+        code: code,
+        redirect_uri: redirect_uri,
+        scope: scope
+      }
+
+      request.body = URI.encode_www_form(token_data)
+
+      request["Content-Type"] = "application/x-www-form-urlencoded"
+      request["Authorization"] = "Basic #{basic_auth}".delete("\n")
+      request["User-Agent"] = "curl/8.7.1"
+      request["Accept-Encoding"] = nil
+
+      response = http.request(request)
+
+      JSON.parse(response.body).slice("access_token", "expires_in")
+    end
+
+    def scope
+      "tasks:write tasks:read"
+    end
+
+    def basic_auth
+      Base64.encode64("#{client_id}:#{client_secret}")
+    end
+
+    def build_auth_url_params(params)
+      URI.encode_www_form(params)
+    end
+  end
+end

data/lib/tickrb/client.rb

@@ -0,0 +1,144 @@
+# typed: true
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "sorbet-runtime"
+
+module Tickrb
+  class Client
+    extend T::Sig
+
+    BASE_URL = "https://api.ticktick.com/open/v1"
+
+    sig { params(token: T.nilable(String)).void }
+    def initialize(token: nil)
+      @token = token || TokenStore.load_token
+      raise Error, "No authentication token available. Please run authentication first." unless @token
+      @projects_cache = T.let(nil, T.nilable(T::Array[T::Hash[String, T.untyped]]))
+      @tasks_cache = T.let(nil, T.nilable(T::Array[T::Hash[String, T.untyped]]))
+      @cache_timestamp = T.let(nil, T.nilable(Time))
+    end
+
+    sig { returns(T::Array[T::Hash[String, T.untyped]]) }
+    def get_tasks
+      return @tasks_cache if cache_valid? && @tasks_cache
+
+      all_tasks = []
+      projects = get_projects
+
+      projects.each do |project|
+        project_tasks = get_tasks_for_project(project["id"])
+        project_tasks.each { |task| task["projectId"] = project["id"] }
+        all_tasks.concat(project_tasks)
+      end
+
+      @tasks_cache = all_tasks
+      @cache_timestamp = Time.now.utc
+      all_tasks
+    end
+
+    sig { params(project_id: String).returns(T::Array[T::Hash[String, T.untyped]]) }
+    def get_tasks_for_project(project_id)
+      response = make_request("GET", "/project/#{project_id}/data")
+      if response.is_a?(Hash) && response["tasks"]
+        response["tasks"]
+      else
+        []
+      end
+    end
+
+    sig { params(title: String, content: T.nilable(String), project_id: T.nilable(String)).returns(T::Hash[String, T.untyped]) }
+    def create_task(title:, content: nil, project_id: nil)
+      task_data = {
+        title: title,
+        content: content,
+        projectId: project_id
+      }.compact
+
+      result = T.cast(make_request("POST", "/task", task_data), T::Hash[String, T.untyped])
+      invalidate_cache
+      result
+    end
+
+    sig { params(task_id: String, project_id: String).returns(T::Hash[String, T.untyped]) }
+    def complete_task(task_id, project_id)
+      result = T.cast(make_request("POST", "/project/#{project_id}/task/#{task_id}/complete"), T::Hash[String, T.untyped])
+      invalidate_cache
+      result
+    end
+
+    sig { params(task_id: String, project_id: String).returns(T::Hash[String, T.untyped]) }
+    def delete_task(task_id, project_id)
+      result = T.cast(make_request("DELETE", "/project/#{project_id}/task/#{task_id}"), T::Hash[String, T.untyped])
+      invalidate_cache
+      result
+    end
+
+    sig { returns(T::Array[T::Hash[String, T.untyped]]) }
+    def get_projects
+      return @projects_cache if cache_valid? && @projects_cache
+
+      response = make_request("GET", "/project")
+      @projects_cache = response.is_a?(Array) ? response : []
+      @cache_timestamp = Time.now.utc
+      @projects_cache
+    end
+
+    private
+
+    attr_reader :token
+
+    sig { returns(T::Boolean) }
+    def cache_valid?
+      return false unless @cache_timestamp
+      Time.now.utc - @cache_timestamp < 100
+    end
+
+    sig { void }
+    def invalidate_cache
+      @projects_cache = nil
+      @tasks_cache = nil
+      @cache_timestamp = nil
+    end
+
+    sig { params(method: String, endpoint: String, data: T.nilable(T::Hash[String, T.untyped])).returns(T.any(T::Hash[String, T.untyped], T::Array[T::Hash[String, T.untyped]])) }
+    def make_request(method, endpoint, data = nil)
+      uri = URI("#{BASE_URL}#{endpoint}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      case method.upcase
+      when "GET"
+        request = Net::HTTP::Get.new(uri)
+      when "POST"
+        request = Net::HTTP::Post.new(uri)
+        if data
+          request.body = data.to_json
+          request["Content-Type"] = "application/json"
+        end
+      when "DELETE"
+        request = Net::HTTP::Delete.new(uri)
+      else
+        raise Error, "Unsupported HTTP method: #{method}"
+      end
+
+      request["Authorization"] = "Bearer #{token}"
+      request["User-Agent"] = "TickRb/1.0.0"
+
+      response = http.request(request)
+
+      case response.code.to_i
+      when 200..299
+        response.body.empty? ? {} : JSON.parse(response.body)
+      when 401
+        raise Error, "Authentication failed. Token may be expired."
+      when 404
+        raise Error, "Resource not found"
+      else
+        raise Error, "API request failed: #{response.code} #{response.message}"
+      end
+    end
+  end
+end