ticktick-mcp-server 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cf9d114f051a0ddae817d5e1cc84a622bfbb057ee97cd8a1c68008bba0929833
-  data.tar.gz: 2678932d002e8c15e769fecb194c436fb69f0e7033dedd66fe8e10ccd39ed6b7
+  metadata.gz: 57893a42594197579a7d035f6e2b0f77ccb0de47a8b5eea857ec6d1d8b1f078d
+  data.tar.gz: 11c46a9168ad7edaf65894b347d6669909aa539a201f601b032ff6d40cb7ac3c
 SHA512:
-  metadata.gz: 4610d280cf0ff4c90fe73542abdb1b2960c3ab8ca0c79c87c7e3ad5cdb6cd03518b51a96934a0c4c0f24143757a1a85fea2667eb8032fd41dae587fb701e44be
-  data.tar.gz: 8d972718c6c3f0d12fc028f0a61bccb5c3083e509e35863e9a9cc46877dd9e77832b64bb108c28d73dff8c9ffff7e6be6c2634b169aaee7dee622380a290ff99
+  metadata.gz: 3e254267fa319f2d444826e38a56b5921b1dfaa663856d0430ea49e6efb228ad190dd616fe4019e20a7445e511bbf67a73c640925492dbcf385a009ba11a45ea
+  data.tar.gz: ad77646c2214318b9c8a509de044167203c92db95d33e18c84a3a9b5c5b52456ebd2a5d9a1e7d8672614c076e42dba5aeb953c162c73c5b23cd1268dbfb24104

data/.rubocop.yml

@@ -13,6 +13,7 @@ Style/Documentation:
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*_spec.rb"
+    - "*.gemspec"
 
 Metrics/ParameterLists:
   Exclude:

data/Dockerfile

@@ -0,0 +1,15 @@
+# syntax=docker/dockerfile:1
+FROM ruby:3.4-alpine
+
+RUN apk add --no-cache \
+      build-base \
+      ca-certificates \
+      tzdata
+
+RUN addgroup -S mcp && adduser -S mcp -G mcp
+
+RUN gem install ticktick-mcp-server --no-document
+
+USER mcp
+
+CMD ["ticktick-mcp-server"]

data/Dockerfile.dev

@@ -0,0 +1,8 @@
+FROM ruby:3.4-alpine
+
+RUN apk add --no-cache build-base ca-certificates tzdata
+
+COPY ticktick-mcp-server-*.gem /tmp/
+RUN gem install /tmp/ticktick-mcp-server-*.gem --no-document
+
+CMD ["ticktick-mcp-server"]

data/README.md

@@ -4,12 +4,34 @@ A Ruby gem that exposes the [TickTick Open API](https://developer.ticktick.com/)
 
 ## Requirements
 
-- Ruby >= 3.1.0
 - A TickTick account with an Open API access token
+- One of the following:
+  - Docker (recommended — no Ruby required)
+  - Ruby >= 3.1.0
 
 ## Installation
 
-Clone the repository and install the gem locally:
+### Option 1: Docker (recommended)
+
+No Ruby installation required. Pull the pre-built image from GitHub Container Registry:
+
+```bash
+docker pull ghcr.io/j-o-lantern0422/ticktick-mcp-server:latest
+```
+
+Or build locally from the repository:
+
+```bash
+docker build -t ticktick-mcp-server https://github.com/j-o-lantern0422/ticktick-mcp-server.git#main
+```
+
+### Option 2: RubyGems
+
+```bash
+gem install ticktick-mcp-server
+```
+
+### Option 3: Clone the repository
 
 ```bash
 git clone https://github.com/j-o-lantern0422/ticktick-mcp-server
@@ -26,11 +48,89 @@ Set the following environment variable with your TickTick Open API access token:
 TICKTICK_ACCESS_TOKEN=your_access_token_here
 ```
 
-You can obtain an access token from the TickTick Open API developer settings.
+### Getting an Access Token
+
+Use the built-in `ticktick-auth` tool to obtain a token via OAuth2.
+
+#### Step 1: Register your application
+
+Go to the [TickTick Developer Center](https://developer.ticktick.com/) and create an OAuth2 application.
+Set the redirect URI to:
+
+```
+http://localhost:8585/callback
+```
+
+#### Step 2: Run the authentication tool
+
+**With Docker:**
+
+```bash
+docker run --rm -p 8585:8585 ghcr.io/j-o-lantern0422/ticktick-mcp-server:latest \
+  ticktick-auth --client-id=YOUR_CLIENT_ID --client-secret=YOUR_CLIENT_SECRET
+```
+
+**With the gem installed locally:**
+
+```bash
+ticktick-auth --client-id=YOUR_CLIENT_ID --client-secret=YOUR_CLIENT_SECRET
+```
+
+You can also pass credentials via environment variables instead of flags:
+
+```bash
+export TICKTICK_CLIENT_ID=YOUR_CLIENT_ID
+export TICKTICK_CLIENT_SECRET=YOUR_CLIENT_SECRET
+ticktick-auth
+```
+
+> **Note:** The default callback port is `8585`. Use `--port PORT` (or `TICKTICK_AUTH_PORT`) to change it.
+> If you change the port, update the redirect URI in the developer settings accordingly.
+
+#### Step 3: Authorize in the browser
+
+The tool will print an authorization URL. Open it in your browser and approve the request.
+
+#### Step 4: Copy the token
+
+After authorization, the token is printed to stdout:
+
+```
+TICKTICK_ACCESS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+Copy this value and use it as your `TICKTICK_ACCESS_TOKEN`.
 
 ## Usage
 
-### Claude Desktop Integration
+### Running with Docker
+
+Add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ticktick": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "TICKTICK_ACCESS_TOKEN=your_access_token_here",
+        "ghcr.io/j-o-lantern0422/ticktick-mcp-server:latest"
+      ]
+    }
+  }
+}
+```
+
+> **Note:**
+> - `-i` is required for STDIO communication between Claude Desktop and the MCP server.
+> - Do **not** use `-t` (pseudo-tty). It causes CR/LF conversion that breaks the JSON-RPC protocol.
+> - `--rm` automatically removes the container when the session ends.
+
+### Claude Desktop Integration (gem installed locally)
 
 Add the following to your `claude_desktop_config.json`:
 

data/exe/ticktick-auth

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$stdout.sync = true
+
+require "optparse"
+require "ticktick/auth/oauth_flow"
+
+options = {
+  client_id: ENV["TICKTICK_CLIENT_ID"],
+  client_secret: ENV["TICKTICK_CLIENT_SECRET"],
+  port: (ENV["TICKTICK_AUTH_PORT"] || 8585).to_i
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: ticktick-auth [options]"
+
+  opts.on("--client-id ID", "TickTick OAuth2 client ID") { |v| options[:client_id] = v }
+  opts.on("--client-secret SECRET", "TickTick OAuth2 client secret") { |v| options[:client_secret] = v }
+  opts.on("--port PORT", Integer, "Callback server port (default: 8585)") { |v| options[:port] = v }
+  opts.on("-h", "--help", "Show this help") do
+    puts opts
+    exit 0
+  end
+end.parse!
+
+errors = []
+errors << "client_id is required (--client-id or TICKTICK_CLIENT_ID)" unless options[:client_id]
+errors << "client_secret is required (--client-secret or TICKTICK_CLIENT_SECRET)" unless options[:client_secret]
+
+unless errors.empty?
+  errors.each { |e| warn "Error: #{e}" }
+  exit 1
+end
+
+begin
+  flow = Ticktick::Auth::OauthFlow.new(
+    client_id: options[:client_id],
+    client_secret: options[:client_secret],
+    port: options[:port]
+  )
+  token = flow.run
+  puts "TICKTICK_ACCESS_TOKEN=#{token}"
+rescue Ticktick::Auth::OauthFlow::TimeoutError => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue Ticktick::Auth::OauthFlow::DeniedError => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue Ticktick::Auth::OauthFlow::NetworkError => e
+  warn "Error: #{e.message}"
+  exit 1
+rescue Ticktick::Auth::OauthFlow::Error => e
+  warn "Error: #{e.message}"
+  exit 1
+end

data/lib/ticktick/auth/callback_server.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "webrick"
+
+module Ticktick
+  module Auth
+    class CallbackServer
+      CALLBACK_PATH = "/callback"
+      SUCCESS_HTML = <<~HTML
+        <!DOCTYPE html>
+        <html>
+          <head><meta charset="utf-8"><title>TickTick Authorization</title></head>
+          <body>
+            <h1>Authorization successful!</h1>
+            <p>You can close this browser tab and return to the terminal.</p>
+          </body>
+        </html>
+      HTML
+      ERROR_HTML = <<~HTML
+        <!DOCTYPE html>
+        <html>
+          <head><meta charset="utf-8"><title>TickTick Authorization</title></head>
+          <body>
+            <h1>Authorization failed</h1>
+            <p>Access was denied. Please try again.</p>
+          </body>
+        </html>
+      HTML
+
+      def initialize(port:)
+        @port = port
+        @queue = Queue.new
+      end
+
+      def wait_for_code(timeout: 300)
+        server = build_server
+        server_thread = Thread.new { server.start }
+
+        result = poll_for_result(timeout)
+        server.shutdown
+        server_thread.join(5)
+        result
+      end
+
+      private
+
+      def build_server
+        logger = WEBrick::Log.new(nil, WEBrick::Log::FATAL)
+        access_log = [[nil, ""]]
+
+        server = WEBrick::HTTPServer.new(
+          Port: @port,
+          Logger: logger,
+          AccessLog: access_log
+        )
+        server.mount_proc(CALLBACK_PATH) { |req, res| handle_callback(req, res) }
+        server
+      end
+
+      def handle_callback(req, res)
+        code = req.query["code"]
+        error = req.query["error"]
+        state = req.query["state"]
+
+        if code
+          @queue.push({ code: code, state: state })
+          write_response(res, SUCCESS_HTML)
+        else
+          @queue.push({ error: error || "unknown_error" })
+          write_response(res, ERROR_HTML)
+        end
+      end
+
+      def write_response(res, html)
+        res.status = 200
+        res.content_type = "text/html; charset=utf-8"
+        res.body = html
+      end
+
+      def poll_for_result(timeout)
+        deadline = Time.now + timeout
+        loop do
+          return @queue.pop(true) unless @queue.empty?
+          return nil if Time.now >= deadline
+
+          sleep 0.1
+        end
+      end
+    end
+  end
+end

data/lib/ticktick/auth/oauth_flow.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "securerandom"
+require "base64"
+require_relative "callback_server"
+
+module Ticktick
+  module Auth
+    class OauthFlow
+      AUTHORIZE_URL = "https://ticktick.com/oauth/authorize"
+      TOKEN_URL = "https://ticktick.com/oauth/token"
+      SCOPE = "tasks:read tasks:write"
+
+      Error = Class.new(StandardError)
+      TimeoutError = Class.new(Error)
+      DeniedError = Class.new(Error)
+      NetworkError = Class.new(Error)
+
+      def initialize(client_id:, client_secret:, port: 8585)
+        @client_id = client_id
+        @client_secret = client_secret
+        @port = port
+      end
+
+      def run
+        state = SecureRandom.hex(16)
+        redirect_uri = "http://localhost:#{@port}/callback"
+
+        puts build_authorize_message(state, redirect_uri)
+
+        server = CallbackServer.new(port: @port)
+        result = server.wait_for_code(timeout: 300)
+
+        raise TimeoutError, "Timed out waiting for authorization. Please try again." if result.nil?
+        raise DeniedError, "Authorization was denied: #{result[:error]}" if result[:error]
+        raise Error, "State mismatch. Possible CSRF attack." if result[:state] != state
+
+        exchange_code_for_token(result[:code], redirect_uri)
+      end
+
+      private
+
+      def build_authorize_message(state, redirect_uri)
+        url = build_authorize_url(state, redirect_uri)
+
+        <<~MSG
+          Open the following URL in your browser to authorize TickTick:
+
+            #{url}
+
+          Waiting for authorization (timeout: 5 minutes)...
+        MSG
+      end
+
+      def build_authorize_url(state, redirect_uri)
+        params = URI.encode_www_form(
+          client_id: @client_id,
+          response_type: "code",
+          scope: SCOPE,
+          redirect_uri: redirect_uri,
+          state: state
+        )
+        "#{AUTHORIZE_URL}?#{params}"
+      end
+
+      def exchange_code_for_token(code, redirect_uri)
+        conn = Faraday.new(url: TOKEN_URL)
+        credentials = Base64.strict_encode64("#{@client_id}:#{@client_secret}")
+
+        response = conn.post { |req| configure_token_request(req, credentials, code, redirect_uri) }
+        handle_token_response(response)
+      rescue Faraday::Error => e
+        raise NetworkError, "Network error during token exchange: #{e.message}"
+      end
+
+      def configure_token_request(req, credentials, code, redirect_uri)
+        req.headers["Authorization"] = "Basic #{credentials}"
+        req.headers["Content-Type"] = "application/x-www-form-urlencoded"
+        req.body = URI.encode_www_form(
+          grant_type: "authorization_code",
+          code: code,
+          redirect_uri: redirect_uri
+        )
+      end
+
+      def handle_token_response(response)
+        raise Error, "Token exchange failed (HTTP #{response.status}): #{response.body}" unless response.success?
+
+        data = JSON.parse(response.body)
+        token = data["access_token"]
+        raise Error, "No access_token in response: #{response.body}" unless token
+
+        token
+      end
+    end
+  end
+end

data/lib/ticktick/mcp/server/version.rb

@@ -3,7 +3,7 @@
 module Ticktick
   module Mcp
     module Server
-      VERSION = "0.1.0"
+      VERSION = "0.2.0"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ticktick-mcp-server
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - j-o-lantern0422
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -37,11 +51,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Model Context Protocol (MCP) server that provides tools to interact
   with the TickTick API
 email:
 - j.o.lantern0422@gmail.com
 executables:
+- ticktick-auth
 - ticktick-mcp-server
 extensions: []
 extra_rdoc_files: []
@@ -49,10 +78,15 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - CHANGELOG.md
+- Dockerfile
+- Dockerfile.dev
 - LICENSE.txt
 - README.md
 - Rakefile
+- exe/ticktick-auth
 - exe/ticktick-mcp-server
+- lib/ticktick/auth/callback_server.rb
+- lib/ticktick/auth/oauth_flow.rb
 - lib/ticktick/client.rb
 - lib/ticktick/errors.rb
 - lib/ticktick/http_connection.rb