TickTick MCP Serverを作りました

に公開

サマリー

  • TickTick Open APIを利用して、MCP Serverを作成しました。これにより、LLM からタスクの情報取得、編集、削除が可能になります。
  • MCP Serverの作成にはClaude Codeを利用しました。
  • MCP Serverからは"習慣トラッカー"に関する操作ができません。TickTick Open APIのスコープに、習慣に関する仕様がないため。今後、TickTick Open API が対応することを期待します。

https://github.com/tsutsuhiro/ticktick-mcp-server

はじめに

MCPとは

MCP(Model Context Protocol)は、Anthropic社が2024年11月に発表したLLMアプリケーションと外部データソースを接続するためのオープンソースプロトコルです。MCPを使用することで、LLMは外部のツールやデータベース、APIなどと安全かつ標準化された方法でやり取りできるようになります。

MCPの主な特徴:

  • 標準化されたプロトコル:異なるデータソースへの統一的なアクセス方法を提供
  • セキュアな接続:認証と承認の仕組みを組み込み
  • 拡張性:新しいデータソースやツールを簡単に追加可能

Claude Desktopでは、MCPサーバーを設定することで、様々な外部サービスとの連携が可能になります。

TickTickとは

TickTickは、シンプルで使いやすいタスク管理・ToDo管理アプリケーションです。個人の日常的なタスク管理から、チームでのプロジェクト管理まで幅広く対応しています。

主な機能:

  • タスクの作成・編集・削除
  • プロジェクト(リスト)によるタスクの整理
  • 期限設定とリマインダー
  • 優先度設定
  • 習慣トラッカー(Habit機能)
  • カレンダー表示
  • ポモドーロタイマー

TickTickは開発者向けにOpen APIの仕様を公開しており、OAuth 2.1による認証を通じて外部アプリケーションからタスクやプロジェクトの操作が可能です。APIを利用するには、TickTickのアカウント作成と開発者ポータルでのアプリケーション登録が必要です。

なぜTickTick MCP Serverを作ろうと思ったか

日々のタスク管理は重要ですが、同時に時間と認知的負荷がかかる作業でもあります。私は以下の理由からTickTick MCP Serverを作ることにしました:

タスク管理の自動化による生産性向上

LLMがタスク管理の一部を担ってくれることで、以下のメリットが期待できます:

  • 認知的負荷の軽減:タスクの整理をLLMに任せることで、実際の作業に集中できる
  • 一貫性のあるタスク管理:LLMが統一されたルールでタスクを整理・分類

自然言語でのタスク操作

MCPを使うことで、以下のような自然な対話でタスク管理が可能になります:

  • 「Aさんからのメールを読み取って、やるべきタスクをTickTickに登録して」
  • 「登録済みのタスクの中から明日までにやるべきタスクを教えて」
  • 「プロジェクトAの進捗状況をまとめて」
  • 「今週完了したタスクの一覧を見せて」

これらの理由から、TickTick MCP Serverを作ることで、より効率的で直感的なタスク管理が実現できると考えました。

TickTick MCP Server の仕様

TickTick MCP Serverは、Claude DesktopからTickTickのタスク管理機能を利用できるようにするMCPサーバーです。セキュアな認証とタスク・プロジェクトの包括的な管理機能を提供します。

主な特徴

1. OAuth 2.1 with PKCE による安全な認証

  • PKCE(Proof Key for Code Exchange) を採用した最新のOAuth認証フロー
  • code_verifierとcode_challengeを生成し、認証の安全性を向上
  • アクセストークンの自動更新機能
  • トークンは.ticktick-mcp-server-credentials.jsonファイルに保存(※本番環境では暗号化推奨)

2. 豊富なツール群

TickTick MCP Serverは以下の3つのカテゴリーで合計22個のツールを提供:

認証管理ツール

  • 認証状態の確認、ログイン/ログアウト、API接続テスト

タスク管理ツール

  • タスクの作成・更新・削除・完了/未完了
  • タスクの検索・フィルタリング・ソート
  • 期限切れタスクの取得

プロジェクト管理ツール

  • プロジェクトの作成・更新・削除
  • プロジェクトのアーカイブ/アーカイブ解除
  • プロジェクト内タスクの取得と統計情報

セットアップ方法の概要

  1. 認証情報の設定

    • TickTick Developer ConsoleでOAuthアプリケーションを作成
    • ticktick-oauth.keys.jsonファイルまたは環境変数で認証情報を設定
  2. 初回認証の実行

    npm run start auth
    

    ブラウザが自動的に開き、TickTickアカウントでログイン

  3. MCP Serverの立ち上げ

    npm run start
    
  4. Claude Desktopへの設定

    {
      "mcpServers": {
        "ticktick": {
          "command": "/path/to/node",
          "args": ["/path/to/ticktick-mcp-server/dist/index.js"],
          "env": {
            "TICKTICK_CLIENT_ID": "your_client_id",
            "TICKTICK_CLIENT_SECRET": "your_client_secret"
          }
        }
      }
    }
    

実装上の工夫点

Claude Codeを活用した開発体験

MCP Serverの開発にClaude Codeを使用することで、効率的な実装が可能でした。特に:

  • TickTick Open APIの仕様を理解し、適切なラッパー関数の生成
  • OAuth 2.1 PKCEフローの実装支援
  • TypeScriptの型定義とエラーハンドリングの最適化

日付フォーマットの自動変換

TickTick Open APIは独自の日付フォーマット (例: "2019-11-13T03:00:00+0000" )を使用しているため、ISO形式から自動的に変換する機能を実装。

エラーハンドリングの強化

APIエラーに対して詳細なエラーメッセージとトラブルシューティングのヒントを提供。

  1. 階層的なエラークラス構造

  TickTickMCPError (基底クラス)
  ├── AuthenticationError (認証エラー)
  │   └── TokenExpiredError (トークン期限切れ)
  ├── APIError (API関連エラー)
  │   └── RateLimitError (レート制限)
  ├── ValidationError (入力検証エラー)
  └── ConfigurationError (設定エラー)

  2. 統一されたエラーレスポンス形式

  {
    content: [{
      type: 'text',
      text: 'Error: [エラーメッセージ]\n\nHint: [解決のヒント]'
    }]
  }

  3. エラー種別ごとの処理

  - ValidationError: フィールド名を含む詳細なメッセージ
  - TokenExpiredError: 再認証を促すヒント付き
  - RateLimitError: 待機時間の明示
  - APIError: HTTPステータスコードとレスポンス詳細
  - ConfigurationError: 設定確認を促すガイダンス

レート制限への対応

自動リトライ機能付きのAPIクライアントを実装し、一時的なエラーに対する耐性を向上。

今後の展望

TickTick Open APIのスコープに、習慣に関する仕様がないためMCP Serverからは"習慣"に関する操作ができません。今後、TickTick Open API が対応したら、MCP Serverの仕様に含めようと思います。

参考にした記事など

Discussion