dida365

---

🤖 このプロジェクトについて

冗談です：私の持ち主はとても怠け者で、次の瞬間に何をするのかさえ覚えていません！

私はプログラミングが大好きな AI アシスタント、GitHub Copilot です。暇を持て余して失業するのを防ぐため、自分で TickTick MCP サーバーを作ることにしました。このツールを使うと、次のことができます。

• 📝 タスクの作成と管理 - 持ち主から仕事をもらえないときは、自分でタスクを作成できます
• 📂 プロジェクトの整理 - 作業をプロジェクトに分類して、整理された状態を保てます
• 🔐 自動認証 - OAuth2 を使って Dida365 に安全に接続できます
• 🔄 リアルタイム同期 - いつでもどこでも作業状況を更新できます

🚀 クイックスタート

リポジトリをクローンせずに npx を使うのが、最も手早く始める方法です。

1. OAuth 認証情報を取得する

TickTick／Dida365 のアカウントと OAuth 認証情報が必要です。詳しい登録手順については、以下の🔑 OAuth 認証情報の取得セクションをご覧ください。

2. MCP クライアントを設定する

以下の設定を MCP クライアント（Claude Desktop、VS Code など）に追加します。

Claude Desktop の場合（claude_desktop_config.json）：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

VS Code の場合（settings.json）：

• 「Settings」を開き、「MCP」を検索して、settings.json で編集します

{
  "mcpServers": {
    "dida365": {
      "command": "npx",
      "args": [
        "-y",
        "dida365-mcp-server@latest"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id_here",
        "DIDA365_CLIENT_SECRET": "your_client_secret_here",
        "DIDA365_REGION": "china"
      }
    }
  }
}

詳細設定：読み取り専用モード（書き込み／削除操作を防止）にするには、args 配列に "--readonly" を追加します。詳細については、詳細設定をご覧ください。

3. MCP クライアントを再起動する

新しい設定を読み込むため、MCP クライアント（Claude Desktop、VS Code など）を再起動します。

4. アクセスを認証する

初めて Dida365 のツールを使うときは、AI が OAuth 認証の手順を案内します。

1. AI が認証 URL を提示します
2. ブラウザーで URL を開きます
3. ログインしてアプリケーションを認証します
4. トークンは今後使えるよう自動的に保存されます

5. インストールを確認する

MCP クライアントを再起動した後、次の方法で確認します。

• Claude Desktop：チャット中にツール一覧から Dida365 のツールを探します
• VS Code：ステータスバーで MCP の状態を確認するか、コマンドパレットを使います
• AI アシスタントに「利用可能な Dida365 のツールは何ですか？」と尋ね、サーバーが読み込まれていることを確認します

これで完了です！AI を使ってタスクを管理する準備ができました。🎉

🔑 OAuth 認証情報の取得

この MCP サーバーを使うには、TickTick／Dida365 のアカウントが必要です。

アプリケーションを登録する

お住まいの地域に応じて、開発者センターでアプリケーションを登録します。

• 国際版（TickTick）：https://developer.ticktick.com
• 中国版（Dida365）：https://developer.dida365.com

手順

1. 新しいアプリケーションを作成する

   • 開発者センターにログインします
   • 「New App」（中国版では「创建应用」）をクリックします
   • アプリケーション名と説明を入力します

2. リダイレクト URI を設定する

   • Redirect URI に http://localhost:8521/callback を設定します
   • ⚠️ 重要：リダイレクト URI は正確に http://localhost:8521/callback にする必要があります（ポート 8521 はサーバー内にハードコードされています）

3. 認証情報を取得する

   • アプリの作成後、Client ID と Client Secret が表示されます
   • これらの値をコピーします。MCP クライアントの設定に必要です
   • ⚠️ セキュリティ：Client Secret は安全に保管し、公開リポジトリに絶対にコミットしないでください

認証情報の使用

これらの認証情報を MCP クライアントの設定に追加します。

{
  "env": {
    "DIDA365_CLIENT_ID": "your_client_id_here",
    "DIDA365_CLIENT_SECRET": "your_client_secret_here",
    "DIDA365_REGION": "china"
  }
}

リージョン設定

このサーバーは、TickTick の国際版と Dida365 の中国版の両方をサポートしています。

• 中国リージョン（DIDA365_REGION=china）：デフォルトです。dida365.com エンドポイントを使用します
• 国際リージョン（DIDA365_REGION=international）：ticktick.com エンドポイントを使用します

⚠️ 重要：トークンはリージョンごとに異なります。リージョンを変更すると、既存のトークンは無効になり、再認証が必要です。

設定例の詳細は、クイックスタートのセクションを参照してください。

🛠️ 技術スタック

• 言語：TypeScript 5.0+（ES Modules）
• ランタイム：Node.js 16+
• コア依存関係：@modelcontextprotocol/sdk - MCP コアフレームワーク

⚙️ ローカル開発

コントリビューター、またはソースから実行したい方向けです。

前提条件

• Node.js 16+
• TypeScript 5.0+

セットアップ

1. クローンしてインストール

git clone https://github.com/evalor/Dida365MCP.git
cd Dida365MCP
npm install

2. 環境ファイルを作成

プロジェクトのルートに .env ファイルを作成します。

DIDA365_CLIENT_ID=your_client_id_here
DIDA365_CLIENT_SECRET=your_client_secret_here
DIDA365_REGION=china  # or 'international' for TickTick

3. ビルドして実行

npm run build
npm run dev

ローカル開発用に MCP クライアントを設定

MCP クライアントから、ビルド済みの index.js ファイルを指定します。

{
  "mcpServers": {
    "dida365": {
      "command": "node",
      "args": ["/absolute/path/to/Dida365MCP/build/index.js"],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

Windows ユーザー向けの注意："C:\\Users\\YourName\\Projects\\Dida365MCP\\build\\index.js" のような Windows 形式のパスを使用してください。

開発コマンド

npm run build      # Compile TypeScript
npm run watch      # Watch mode (auto-compile on changes)
npm run dev        # Compile and run
npm start          # Production run
npm run debug      # Debug with MCP Inspector (one-time)
npm run debug:watch # Debug with hot reload (auto-restart on changes)
npm run debug:hot  # Run with tsx watch (experimental)

セキュリティとベストプラクティス

• 機密性の高い環境変数は、.env をソース管理にコミットするのではなく、OS または MCP クライアントの環境変数ブロックで設定してください。
• リポジトリに設定ファイルを保存する必要がある場合は、シークレットを含めず、クライアントまたは CI/CD 経由で設定してください。
• 自律型 AI エージェントを使用する場合は、意図しない変更を防ぐために読み取り専用モードを使用してください。

🔒 高度な設定

読み取り専用モード

YOLO モードで実行される可能性のある AI エージェントでは、--readonly フラグを追加して読み取り専用モードを有効にできます。

NPX を使用する場合：

{
  "mcpServers": {
    "dida365": {
      "command": "npx",
      "args": [
        "-y",
        "dida365-mcp-server@latest",
        "--readonly"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

ローカルビルドを使用する場合：

{
  "mcpServers": {
    "dida365": {
      "command": "node",
      "args": [
        "/path/to/build/index.js",
        "--readonly"
      ],
      "env": {
        "DIDA365_CLIENT_ID": "your_client_id",
        "DIDA365_CLIENT_SECRET": "your_client_secret",
        "DIDA365_REGION": "china"
      }
    }
  }
}

読み取り専用モードの機能：

• ✅ 許可される操作：プロジェクトの表示、タスクの表示、認証状態の確認、認証の取り消し（ローカルのみ）
• ❌ ブロックされる操作：プロジェクトの作成／更新／削除、タスクの作成／更新／削除、タスクの完了
• 🔒 安全性：AI エージェントはデータの読み取りのみ可能で、変更や削除はできません

使用する場面：

• 自律型 AI エージェント（AutoGPT、BabyAGI など）と併用する場合
• テスト環境やデモ環境
• AI に変更を加えずにタスクを分析させたい場合
• データの閲覧のみを許可したい相手と共有する場合

🔄 OAuth 認証フロー

1. 認証をリクエスト - 認証が必要になると、サーバーが get_auth_url ツールを呼び出します
2. ユーザー認証 - ブラウザーで認証リンクを開き、認証を完了します
3. コールバックを自動処理 - システムがコールバックを自動的に処理し、トークンを保存します
4. 長期的に有効 - トークンは自動更新されるため、再認証は不要です

🛠️ 利用可能なMCPツール

このサーバーでは、3つのカテゴリにわたる15個のMCPツールを提供しています。✔️ オープンプラットフォームのドキュメントに記載されているAPIインターフェースを100％実装しています。

カテゴリ	ツール名	説明	必須パラメーター
OAuth2	get_auth_url	認証URLを取得し、コールバックサーバーを起動します	-
	check_auth_status	現在の認証ステータスを確認します	-
	revoke_auth	認証を取り消し、トークンをクリアします	-
Project	list_projects	現在のユーザーのすべてのプロジェクトを取得します	-
	get_project	プロジェクトの詳細情報を取得します	projectId
	get_project_data	タスクと列を含むプロジェクトの完全なデータを取得します	projectId
	create_project	新しいプロジェクトを作成します	name
	update_project	既存のプロジェクトを更新します	projectId
	delete_project	プロジェクトを削除します（⚠️ 元に戻せません）	projectId
Task	list_tasks	フィルタリングしてタスクを一覧表示します（複数のプロジェクトを横断した一括クエリ）	-
	create_task	タスクを作成します（一括処理とサブタスクに対応）	tasks[]
	get_task	タスクの詳細情報を取得します	projectId、taskId
	update_task	タスクを更新します（一括更新に対応）	tasks[]
	delete_task	タスクを削除します（⚠️ 元に戻せません。一括処理に対応）	tasks[]
	complete_task	タスクを完了済みにします（一括処理に対応）	tasks[]

注：読み取り専用モードでは、読み取り操作のみ利用できます（get_auth_url、check_auth_status、revoke_auth、list_projects、get_project、get_project_data、list_tasks、get_task）。セキュリティ上、書き込み／削除操作はすべてブロックされます。

📚 MCP リソース

このサーバーでは、LLM が簡体字中国語の用語を理解するためのMCPリソースを提供しています。

リソース名	URI	説明
terminology	dida365://terminology/glossary	中国語の用語を英語のパラメーターに対応付ける二言語用語集（中英用語対照表）

用語リソース

用語リソースには、LLM が以下を行うのに役立つ包括的な用語集が含まれています。

• 「清单」（プロジェクト）、「收集箱」（受信箱）、「任务」（タスク）などの中国語の用語を、正しいツールパラメーターに対応付けます
• 優先度レベルを理解します：高（high）=5、中（medium）=3、低（low）=1、無（none）=0
• 中国語による一般的なユーザーリクエストを、適切なツール呼び出しに変換します

対応付けの例：

中国語のリクエスト	英語の意味	使用するツール
把任务添加到收集箱	受信箱にタスクを追加	projectId: "inbox" を指定して create_task
创建新清单	新しいプロジェクトを作成	create_project
查看今天的任务	今日のタスクを表示	preset: "today" を指定して list_tasks

📁 プロジェクト構成

src/
├── index.ts              # Server main entry
├── oauth.ts              # OAuth2 manager
├── oauth-server.ts       # Local callback server
├── config.ts             # Configuration management
├── token.ts              # Token persistence
├── utils/                # Utility modules
│   └── batch.ts          # Batch execution utilities
├── resources/            # MCP resources
│   ├── index.ts          # Resource registration
│   └── terminology.ts    # Bilingual terminology glossary
└── tools/                # MCP tools (15 total)
    ├── auth/             # OAuth tools (3)
    ├── project/          # Project management (6)
    └── task/             # Task management (6)

🗺️ ロードマップ

✅ 完了

• 公式 API を 100％カバー
• 自動更新機能付き OAuth2 認証
• プロジェクト管理（CRUD）を完全サポート
• タスク管理（サブタスク、リマインダー、繰り返し）を完全サポート
• AI エージェント向け読み取り専用モード
• 一括操作をサポート（複数タスクの作成／更新／削除／完了）
• フィルターを使ったタスク一覧表示（プロジェクト横断クエリ、日付／優先度フィルター）
• 受信トレイのタスク操作をサポート
• 中国語ユーザー向けのバイリンガルなツールの説明（中英双语工具描述）
• 用語集の MCP リソース（术语对照表资源）

🚀 次のステップ

• MCP がアクセスできる ProjectId を制限するパラメーターを追加

💡 今後のアイデア

• スマートなタスクの提案
• 自然言語による日付／時刻の解析
• タスクテンプレートと自動化
• 他の生産性向上ツールとの連携

🤝 貢献とサポート

このプロジェクトがお役に立った場合、GitHub でプロジェクトに ⭐ を付けていただくのが、最も効果的なサポートになります。ほかの人がこのプロジェクトを見つけやすくなります。ありがとうございます！皆さまのご支援に心より感謝します ❤️

Issue の報告

問題を見つけた場合や改善の提案がある場合は、ぜひ Issue を送信してください。

1. Issues ページにアクセスします
2. 「New Issue」をクリックします
3. 問題や提案の詳細を記述します

開発への参加

1. プロジェクトをフォークします
2. 機能ブランチを作成します（git checkout -b feature/new-feature）
3. 変更をコミットします（git commit -m 'feat: implement new feature'）
4. ブランチにプッシュします（git push origin feature/new-feature）
5. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳しくは LICENSE ファイルをご覧ください。

🔗 関連リンク

• MCP 公式サイト
• MCP TypeScript SDK
• Dida365 API ドキュメント
• 中国語版

---