mstodo-mcp

Microsoft To Do のタスクを Claude（または任意の MCP クライアント）から自然言語で操作できます。 これは、自分自身の Cloudflare Worker で動かす個人向け・自己ホスト型サーバーで、Claude.ai と自分の Microsoft To Do アカウントを接続します。チャットから離れることなく、Claude に全リストにわたるタスクの発見・作成・更新・完了・検索・整理を指示できます。リストとタスクの高速なローカルミラーを保持するため、全リストにわたる検索やクエリが高速で、リクエストのたびに Microsoft に負荷を掛けません。

設計上 シングルユーザー専用 です。1 つのデプロイが正確に 1 つの Microsoft アカウントにのみ対応し（それ以外は所有者 ID ゲートで拒否されます）、つまり共有・マルチテナントサービスではなく、自分用のプライベートインスタンスとして動かすことを想定しています。

目次

• 要件

• ツール

• 仕組み

• 設定

• リセット

• ID 変更時の自動消去

• 再検討すべき設計判断

• 作者

• 導入ガイド →

• 変更履歴 →

要件

• Microsoft 365 (M365) または Microsoft To Do を使用する個人用 Microsoft アカウント。

• Cloudflare アカウント — 無料プランで小規模アカウントには十分です。タスクが数千件になったら Workers Paid を推奨します（導入ガイドのプランに関する注記を参照）。

• Microsoft Entra アプリ登録 — 無料で、一度だけ作成します（導入ガイドに手順があります）。

• デプロイには Node 18+ と Cloudflare の Wrangler CLI。

• デプロイしたサーバーに接続するための Claude.ai（または別の MCP クライアント）。

➡️ セットアップとデプロイ: 完全なステップバイステップガイド（Microsoft Entra アプリ登録を含む）、カスタムドメイン設定、トラブルシューティングについては DEPLOYMENT.md を参照してください。設定リファレンスは下の 設定 にあります。

ツール

サーバーは MCP 上に Microsoft To Do のツールサーフェスを公開します。主な機能は次のとおりです。

• リストとタスク（CRUD） — list_lists, get_list, create_list, update_list, delete_list; list_tasks, get_task, create_task, update_task, delete_task, move_task。

• サブリソース — チェックリスト項目とリンクされたリソース（それぞれ create/list/get/update/delete）; 添付ファイル（list_attachments, get_attachment, remove_attachment）。

• 添付ファイルのアップロード — create_upload_link は、ユーザーがブラウザーで開いて特定のタスクにファイルを添付するための短命・1回限りの Web リンクを発行します。バイト列はブラウザー → Worker → Microsoft と送られ（各 ≤ 25 MB、インラインまたはチャンクアップロードセッション）、モデルを経由しません。下の Web アップロード を参照してください。

• 添付ファイルのダウンロード — mint_download_link は、サーバー間転送のために 1 つの添付ファイルのバイト列を提供する短命（≤ 5 分）・1回限りの URL を発行します（例: その URL を別の MCP サーバーの URL 取り込みツールに渡す）。バイト列はサーバーサイドで取得され、モデルを経由しません。デフォルトで ON です。無効にするには ENABLE_DOWNLOAD_LINKS="false" を設定します。下の クロスサーバーダウンロード を参照してください。

• リスト横断のクエリと検索（ローカルの TodoIndex ミラーから回答）:

  • query_tasks — リスト、ステータス、日付範囲、重要度、チェックリストの有無、has_open_checklist_item（未チェックの項目があるタスク — 「何かを待っている」フィルター）でフィルタリング; types/exclude_types（リスト分類による包含/除外）; completed 便利オプション（status とは排他）; ページング対応。

  • search_tasks — FTS5（SQLite 組み込みの全文検索エンジン）を使用したタスクのタイトル/本文の全文検索。同じ lists/status/types/exclude_types/completed フィルターに対応。exclude_types:["excluded"] は、何も削除せずに結果からノイズ（例: フラグ付きメールのリスト）を除外します。チェックリストキャッシュが有効な場合、デフォルトでチェックリスト項目（サブタスク/ステップ）のテキストも検索対象になります（include_checklist、タイトル/本文のマッチの後段）。

  • find_task_list, get_pending_across_lists, get_recently_completed。

• チェックリストのフォローアップ（オプトイン） — ENABLE_CHECKLIST_CACHE=true の背後にゲートされています。タスクのチェックリスト項目をクエリ可能なテーブルにミラーリングして、チェックリスト項目を軽量なフォローアップシステムとして使えるようにします（「Acme の返信待ち」項目を追加し、まだ未完了のものを探すなど）。search_checklist_items はチェックリストテキストを FTS 検索し、クエリなしの場合は未完了項目を古い順（一番長く待っているもの）でタスクごとにグループ化して一覧表示します。query_tasks の has_open_checklist_item フィルターと組み合わせて使います。デフォルトではオフ（タスクごとに一度だけバックフィルが走ります）。キャッシュは通常のデルタサイクルで最新に保たれます。対象は未完了のタスクのみ — 完了したタスクは意図的にタスク横断のチェックリストクエリから除外され（get_task は引き続き任意のタスクの項目をライブで表示）、スキップされたリスト（no_sync/フラグ付きメール）はキャッシュされません。

• My Day と手動順序（オプトイン、Substrate） — ENABLE_MY_DAY=true の背後にゲートされています（これらは To Do Web アプリが使っている非公開の Substrate エンドポイントを使用します。My Day と手動ドラッグによる並べ替え位置は Graph からは見えないため）: list_my_day_tasks, add_to_my_day, remove_from_my_day; list_tasks_by_manual_order（アプリの手動順での 1 リスト）と reorder_task（タスクを先頭/末尾、別のタスクの前/後、または 1 始まりのスロットに移動）。

• 設定 — get_list_config/set_list_config（分類パターン、no_sync, sync_flagged_emails）、set_list_alias, get_link_rules/set_link_rules, get_attachment_config/set_attachment_config, extract_links。

• 運用 — whoami, sync_status, resync。

仕組み

Claude.ai はリモート MCP 経由で Worker に接続します。Worker は Microsoft Graph API（PKCE + クライアントシークレットを使用した OAuth 承認コードフロー）へのリクエストを仲介します。シングルトンの TodoIndex Durable Object（Cloudflare のステートフルで強い一貫性を持つコンピューティングプリミティブ）は、組み込み SQLite データベース内にリストとタスクのデルタ同期ミラーを保持し、さらに FTS5 全文インデックス（FTS5 は SQLite 組み込みの全文検索エンジン）も保持します。リスト横断の query_tasks, search_tasks、および集計ツールは、呼び出しのたびに Graph を再ウォークするのではなく、このローカルミラーから読み取ります。*/15 cron が同期を維持し、所有者 ID ゲートがプライバシーを守ります。

デフォルトでは、ミラーは Graph 変更通知（リストごとに 1 つ）にもサブスクライブするため、いずれかの To Do クライアントでの編集は、次のタイマーサイクルを待たずに約 2 分以内にキャッシュに反映されます — ネイティブアプリのようにほぼ即時です。これはデルタ同期のトリガーであり、置き換えではありません。タイマーサイクルはバックストップとして残ります（Graph はタスクに対する通知漏れの保証を提供しないため）。これは既存の Tasks.ReadWrite スコープを利用し（追加の同意は不要）、到達可能な SERVICE_BASE_URL が必要で（Graph が ${SERVICE_BASE_URL}/webhook に POST する）、ENABLE_TASK_SUBSCRIPTIONS で切り替えられます（"false" ⇒ タイマーのみ、公開 webhook なし）。通知はさらに、変更されたタスクの My Day フィールドだけを、対象を絞った Substrate 読み取りで更新します — webhook パスは Microsoft に書き戻すことがないため、ループしません。

小さくゆっくり変化する状態（OAuth トークン、所有者 ID レコード、下記の設定ブロブ）は Cloudflare KV（キーバリューストア） に保存されます。大規模で頻繁にクエリされるタスクコーパスは、KV ではなく Durable Object の SQLite に格納されます。

セキュリティモデル

このサーバーは設計上厳密にシングルユーザーであり、いくつかの不変条件が重要な役割を担っています。ここにまとめておきます。

• 単一の所有者、フェイルクローズ。 すべてのサインインは OAuth コールバックでゲートされます。Microsoft /me の mail/userPrincipalName が OWNER_EMAIL シークレットと一致する必要があり、一致しない ID はトークンが保存される前に 403 が返されます。OWNER_EMAIL が欠落または誤って入力されていると、全員に対してチェックが失敗します — つまり所有者もロックアウトされますが、アクセスが開放されることはありません。

• 認可前のホストピン留め。 すべての Graph および Substrate URL は、Bearer トークンが付与される前に期待されるホストにピン留めされるため、悪意のある @odata.nextLink によって認証済みリクエストがリダイレクトされ、トークンが流出することはありません。トークンは Authorization ヘッダー内のみを移動し、URL やログ行には決して含まれません。

• 単一のトークンリフレッシャー。 シングルトン TodoIndex Durable Object が Microsoft トークンエンドポイントの唯一の呼び出し元です。並行セッションは単一のリフレッシュチェーンに集約されるため、リフレッシュストームは発生せず、トークン処理ロジックがセッション間で重複することもありません。

• 設定は所有者専用であり、信頼できない表面ではありません。 config:lists / config:link_rules 内の正規表現ルールは、認証済みの所有者だけが（上記のゲートの背後にある MCP ツールを介して）書き込めます。したがって、ReDoS のようなユーザー指定正規表現に関する懸念は脅威モデルに含まれません。リンクエンジンはさらに、タスクごとに 8 KB のボディ上限と 50 ms の予算で処理を制限します。

• 秘密情報を使わない Web サーフェス。 /upload と /download は、1回限りの capability トークン で認可されます — TTL 付きで KV に保存される推測不能なランダム ID で、1 つのタスク/添付ファイルにスコープされます。したがって、設定または漏洩する可能性のある署名キーや共有シークレットはありません。

• ログに秘密情報は含まれません。 クエリ文字列（デルタトークンを保持できる）は編集され、Microsoft のエラーボディは生テキストではなく構造化フィールドとしてログに記録され、ログ内の唯一の PII は ID 変更行にある所有者自身のアドレスです。

設定

3 つのオプション設定ブロブが TODO_CACHE バインディング配下の KV に保存されます。編集可能な例（正確な wrangler kv key put コマンド付き）は config-examples/ にあります。

config:lists — 分類、エイリアス、同期制御

• patterns — リスト表示名に対して照合される順序付き正規表現ルール（絵文字は除去され、デフォルトで大文字小文字を区別しません）。最初に一致したルールが採用され、todo | reference | excluded のいずれかに分類されます。一致しないリストは unclassified になります。分類は list_lists のフィルタリングと、query_tasks/search_tasks の types/exclude_types パラメータに機能を提供します。excluded はリストをタイプフィルターツールから除外しますが、同期は停止しません — それには no_sync を使用します。

• aliases — 短いハンドル → Graph リスト ID。リストが受け付けられる場所ならどこでも使用できます。Microsoft ID の切り替え時に自動的にクリアされます（ID はアカウントごとのため）。

• no_sync — wellknownListName または Graph リスト ID で照合され、デルタ同期から除外されるリスト。一覧には表示され、オンデマンドで読み取り可能ですが、インデックス化はされません。set_list_config で会話的に設定可能です。後で追加した場合、同期ループはそのリストの行を自己修復的にパージします。

• sync_flagged_emails — flaggedEmails の既知リストはデフォルトでスキップされます（多くの場合、非常に大きく、実際のタスクリストではないため）。インデックス化するには true に設定します。この組み込みのスキップは no_sync とは独立しています。

config:link_rules — タスクの自動リンク

タスクのタイトル/本文に適用される正規表現 → リンク済みリソースのルール。config-examples/link-rules.json を参照してください。

config:attachments — インラインアップロード上限

max_inline_bytes（ハード上限 3072 KiB、確認済みの Graph 制限）。Web アップロードではこれが切り替えポイントです。この値以下のファイルはインラインで添付され、より大きなファイル（最大 25 MB）はチャンク形式の Graph アップロードセッションで添付されます。config-examples/attachments.json を参照してください。

Web アップロード（/upload）

ファイルのバイト列は MCP ツール呼び出しを実際には通過できません（モデルの呼び出しごとの引数予算は数 KB です）。代わりに、create_upload_link は特定の 1 つのタスクにスコープされた短命（デフォルト 15 分、最大 30）の1回限りリンクを発行します。ユーザーはブラウザーでそれを開き、バイト列はブラウザーから Worker へ、さらに Microsoft Graph へと直接送られ、モデルを経由しません。単一ファイルリンクの場合は filename を指定し、バッチリンクの場合は省略します（最大 max_files、1〜10、デフォルト 5）。タスクに既に添付されている同一ファイルはコンテンツハッシュで検出され、重複としてスキップされます。

リンクはケイパビリティトークンです。推測不可能なランダムID（CSPRNGからの32バイト）です。宛先スコープ（リスト/タスクID、ファイル名、ファイル数）はサーバー側のOAUTH_KVにそのIDの下でTTL付きで保存され、リンク内のIDは何も明かしません。IDを保持していると、スコープされたタスクへのアップロードが1回だけ許可されます。KVルックアップで検証され、TTLで期限切れになり、使用時に消費（削除）されます。設定する署名キーや共有シークレットはありません。ID自体がナンスです。

有効にするには、SERVICE_BASE_URL（wrangler.jsonc内の変数）を設定します。これはこのWorkerの公開オリジン（あなたのworkers.dev URLまたはカスタムドメイン）で、リンクの構築に使用されます。未設定（またはプレースホルダーのまま）の場合、create_upload_linkはupload_disabledを返します。

サーバー間ダウンロード（/download）

アップロードの逆です。mint_download_linkは、短期間（≤5分）の単回使用URLと、添付ファイルのメタデータ（filename、content_type、size）を返します。想定される消費者は別のMCPサーバーのurl-ingestツールです。URLをサーバーサイドでフェッチするため、バイトはサーバー → サーバーで移動し、モデルのコンテキストに入ることはありません。ケイパビリティの仕組みはアップロードを反映しており（download:プレフィックスの下のOAUTH_KVにある推測不可能なID、1つの添付ファイルにスコープ）、リンクは結果に関係なく最初に到達可能なGETで破棄されます。そのため、後で会話履歴に残っても再生できません。（正直な消費者に対する単回使用。/uploadと同様にトランザクションではありません。実際に同時のGETが競合する可能性があります。）メタデータは発行時に添付ファイルコレクションから読み取られるため、/downloadはバイトのためにGraph呼び出しを1回行い、リクエストヘッダーを信頼しません。

返される**sizeはGraphが報告するメタデータであり、実際のバイト数を過大評価する可能性があります**。信頼できるサイズはダウンロードのContent-Lengthです。提供されるバイトはソースとバイト単位で正確です（4 MiBのアップロードセッション添付ファイルまで検証済み）。そのため、sizeが一致しなくても転送は忠実です。大きな添付ファイルも機能します（Graphはインライン作成の上限に関係なく個別のGETでcontentBytesを返します）。実際の制限はGraphの~25 MBの添付ファイル上限です。/downloadはファイルをWorkerメモリにバッファリングするためです。

このサーフェスはデフォルトでONです。ENABLE_DOWNLOAD_LINKS="false"（変数）を設定すると、mint_download_linkと/downloadの両方が無効になり、必要ない場合は攻撃対象領域を縮小できます。また、SERVICE_BASE_URL（アップロードと同じ）が必要です。未設定/プレースホルダーの場合、download_disabledになります。

リセット

スコープは小さいものから大きいものまで3つあります。プロジェクトルートから実行してください。wrangler devが使用するminiflareローカルKVストアを操作したい場合は、--remoteを--localに置き換えてください。

1. テスト反復間のソフトリセット

最も一般的なケース: インフラを破壊せずにMicrosoft OAuthフローを再トリガーします。ID変更時の自動ワイプ（/auth/microsoft/callbackに組み込み）は、次回別のMicrosoft 365 (M365)アカウントとして承認したときにIDごとのキャッシュを自動的にクリアしますが、手動でワイプすることもできます。

# Wipe the stored Microsoft refresh token. Forces the next /authorize to
# re-run the full code-exchange flow.
npx wrangler kv key delete --binding=TODO_CACHE --remote tokens:owner

# Also wipe the stored identity record if you want to "forget" which
# account was last seen (this disables the identity-change wipe trigger
# the next time you sign in — useful when you want to test the wipe).
npx wrangler kv key delete --binding=TODO_CACHE --remote identity:owner

# Wipe all Claude.ai-side OAuth grants (DCR sessions) — forces every
# previously-paired Claude.ai client to re-add this MCP from scratch:
npx wrangler kv key list --binding=OAUTH_KV --remote \
  | jq -r '.[].name' \
  | xargs -I {} npx wrangler kv key delete --binding=OAUTH_KV --remote {}

また、Microsoftに同意を再プロンプトさせたい場合（同意が既に記録されているためにトークンを暗黙的に再発行するのではなく）、M365側のユーザーアカウントのアクセス許可ページからアプリを取り消すか、オプションを公開したら/authorizeに&prompt=consentを渡します。

2. 認証情報のローテーション

.dev.varsを新しい値で編集し、Cloudflareにまとめてプッシュします:

bash scripts/push-secrets.sh

スクリプトは.dev.varsから各名前を読み取り、値をstdin経由でwrangler secret putにパイプするため、値がargv、環境、ターミナルのスクロールバック、AIトランスクリプトに表示されることはありません。npx wrangler secret listで確認できます。

.dev.vars内の任意の値は、op://<vault>/<item>/<field>形式の1Passwordシークレット参照でも構いません。スクリプトはプッシュ時にop CLIを介して解決し（op signin、またはヘッドレス使用の場合はOP_SERVICE_ACCOUNT_TOKENが必要）、解決された値を他のシークレットと同様にstdin経由でパイプします。リテラル値もそのまま機能するため、一部またはすべてのシークレットをファイルから除外できます:

MS_CLIENT_SECRET=op://Private/MS To-Do MCP/credential

代わりに単一のシークレットを手動でプッシュするには:

npx wrangler secret put MS_CLIENT_SECRET     # prompts for value

古いクライアントシークレットは、Azureポータルでも削除するまで有効のままです。wrangler secret putはWorker側のみを更新します。

ローテーション後は、（上記の）ソフトリセットを実行して、次の/authorizeで新しいIDが使用されるようにしてください。

3. 完全なクリーンスレート

ローンチ前の公開可能性チェック、または破損した状態からの回復のために:

npx wrangler delete --name=mstodo-mcp                       # nukes Worker + all DO state
npx wrangler kv namespace delete --binding=OAUTH_KV
npx wrangler kv namespace delete --binding=TODO_CACHE
# Then re-create namespaces + update wrangler.jsonc + redeploy (see DEPLOYMENT.md).

これは「このアカウントを新しいフォークのように見せたい」場合のパスです。wrangler deleteは破壊的で回復できません。

ID変更時の自動ワイプ（組み込み）

/auth/microsoft/callbackが以前に保存されたidentity:owner.idとは異なるme.idに対して完了すると、Workerは新しいトークンを保存する前にIDごとの状態を自動的にワイプします。これにより、2つのM365アカウントのタスクが暗黙的に混在するのを防ぎます。

自動ワイプがクリアするもの（順番、フェイルクローズド。Durable Objectリセットが最初に実行されるため、これがスローした場合は他には何も起こらず、/authorizeは新しいトークンを保存する前に中断し、中途半端にワイプされた混在状態を残しません）:

1. TodoIndex DOリセット — インデックスされたすべてのタスク、リスト一覧、およびすべてのデルタsync_stateカーソルを削除します（タスクの本体はKVではなくDOのSQLiteにあります）。

2. TODO_CACHE内の**tokens:owner、次にidentity:owner**（IDマーカーは最後。そのため、ワイプ途中で失敗した場合は、次回の/authorizeでワイプが再トリガーされ、暗黙的にスキップされません）。

3. config:lists.aliases — ベストエフォート。エイリアスはアカウントごとのGraph IDであり、切り替え後は死んだリストに解決されるためです。分類patterns、no_sync、sync_flagged_emails、config:link_rules、config:attachmentsは保持されます（アカウントに依存しない意図）。

OAUTH_KVのグラントは自動ワイプの影響を受けません。Claude.aiのペアリングはMSアカウントの切り替え後も機能し続けます。Claude.aiクライアントにも最初から再認証させたい場合は、上記のソフトリセットブロックでOAUTH_KVワイプを実行してください。

自動ワイプが発動すると、構造化ログ行が出力されます:

{"level":"warn","event":"identity_change_wipe","prev_id":"…","prev_mail":"…","new_id":"…","new_mail":"…","hint":"…"}

テスト中はwrangler tailでそれを監視できます。

再検討すべき設計判断

将来のメンテナーが、使用パターンが別のトレードオフを示唆したときに再検討できるよう、ここに記録します。

list_tasksのページネーション — ライブのページ単位フェッチ、スナップショットキャッシュなし

Phase 2のlist_tasksツールはGraphに対して直接ページネーションします（$top + @odata.nextLink）。呼び出し元に返されるnext_cursorは不透明なGraphのnextLink URLです。後続の呼び出しは標準のGraphClientトークン/リフレッシュパスを通じてそのURLをGETします。tasks:{listId}はこのツールでは書き込まれません。Phase 5のデルタ同期がそのキャッシュキーの唯一の書き込み元です。

これは、Phase 2計画の「ETagを使ってtasks:{listId}にスナップショットをキャッシュする」という指示からの文書化された逸脱です。オプションA（選択済み）とオプションB（最初の呼び出しで全ページをフェッチし、スナップショットをキャッシュし、その後はキャッシュからページにスライス）の比較:

オプションBを再検討するのは、wrangler tailが後に、LLMが短い時間枠内で大きなリストを繰り返し深くページネーションしていることを示した場合です。事前フェッチ+キャッシュ読み取りは、最初のページのレイテンシを犠牲にして、全体でGraphクォータを節約できます。Phase 2現在、典型的なTo Doの使用はバースト的で浅いため、ライブページネーションが全体的に安価で、キャッシュ形状の決定を、それが重要なPhase 5まで先送りできます。

添付ファイルのアップロード — Web /upload、MCPツール呼び出しではない

ファイルのバイトは実際にはMCPツール呼び出しを通過できません: Claudeの呼び出しごとの出力/トークン予算はツール引数を数KBに制限するため、些細なアップロード以外はGraphに到達する前に失敗します（姉妹プロジェクトobsidian-mcp-cloudflareの構築中に確認済み）。インラインの3072 KiBというGraphの上限は決定的な制約ではなく、MCPトランスポートが制約でした。

元のcreate_attachmentツール（ツール呼び出し内のインラインbase64）は削除され、Webアップロードフロー（create_upload_link + 公開/uploadエンドポイント、Webアップロードを参照）に置き換えられました。バイトはブラウザ → Worker → Graphと移動し、≤3072 KiBの場合はインラインで添付され、25 MBまでの大きなファイルはチャンク化されたアップロードセッションを介して添付されます。リンクはケイパビリティトークンです。タスクスコープがTTL付きでOAUTH_KVに存在する推測不可能なランダムIDで、タスクにスコープされ、単回使用で、決して汎用的ではありません（すべてのリンクは1つの特定のタスクを対象とします）。署名キーや共有シークレットは関与しません。WorkerはPOST中にバイトを同期的に転送するため、R2バケットや一時的なブロブストレージは不要です。obsidian-mcp-cloudflare（そのsrc/upload/*）から移植され、To Do添付ファイルAPIに適合され、シークレット不要のケイパビリティトークンに簡素化されました。

作者

David Szpunarによって構築されました。MIT Licenseの下でライセンスされています。リリース履歴はchangelogにあります。