mstodo-mcp

Используйте свои задачи Microsoft To Do из Claude (или любого MCP-клиента) на естественном языке. Это личный сервер, размещаемый самостоятельно, который вы запускаете на собственном Cloudflare Worker и который подключает Claude.ai к вашей учетной записи Microsoft To Do, — так что вы можете просить Claude находить, создавать, обновлять, завершать, искать и организовывать задачи во всех ваших списках, не покидая чат. Он поддерживает быстрое локальное зеркало ваших списков и задач, поэтому поиск и запросы по всем спискам выполняются быстро и не создают избыточной нагрузки на Microsoft при каждом запросе.

Он однопользовательский по замыслу: одно развертывание обслуживает ровно одну учетную запись Microsoft (все остальные отклоняются шлюзом контроля личности владельца), поэтому он предназначен для запуска вашего собственного частного экземпляра, а не общего/мультитенантного сервиса.

Содержание

• Требования

• Инструменты

• Как это работает

• Конфигурация

• Сброс

• Автоочистка при смене личности

• Проектные решения, которые стоит пересмотреть

• Автор

• Руководство по развертыванию →

• Журнал изменений →

Требования

• Учетная запись Microsoft 365 (M365) или личная учетная запись Microsoft, использующая Microsoft To Do.

• Учетная запись Cloudflare — бесплатного плана достаточно для небольших аккаунтов; Workers Paid рекомендуется, как только у вас появляются тысячи задач (см. примечание о тарифном плане в руководстве по развертыванию).

• Регистрация приложения Microsoft Entra — бесплатно, создается один раз (пошаговая инструкция в руководстве по развертыванию).

• Node 18+ и Cloudflare Wrangler CLI для развертывания.

• Claude.ai (или другой MCP-клиент) для подключения к развернутому серверу.

➡️ Настройка и развертывание: полное пошаговое руководство (включая регистрацию приложения Microsoft Entra), настройку пользовательского домена и устранение неполадок см. в DEPLOYMENT.md. Справочник по конфигурации приведен ниже.

Инструменты

Сервер предоставляет набор инструментов Microsoft To Do через MCP. Основные возможности:

• Списки и задачи (CRUD) — list_lists, get_list, create_list, update_list, delete_list; list_tasks, get_task, create_task, update_task, delete_task, move_task.

• Подресурсы — элементы контрольных списков и связанные ресурсы (создание/получение/обновление/удаление каждого); вложения (list_attachments, get_attachment, remove_attachment).

• Загрузка вложений — create_upload_link создает кратковременную, одноразовую веб-ссылку, которую пользователь открывает в браузере, чтобы прикрепить файл(ы) к конкретной задаче. Байты идут браузер → Worker → Microsoft (≤ 25 МБ каждый, встроенно или через фрагментированную сессию загрузки) и никогда не проходят через модель. См. Веб-загрузка ниже.

• Скачивание вложений — mint_download_link создает кратковременный (≤ 5 мин), одноразовый URL, который отдает байты одного вложения для серверной передачи (например, передача URL инструменту приема URL другого MCP-сервера). Байты получаются на стороне сервера и никогда не проходят через модель. Включено по умолчанию; установите ENABLE_DOWNLOAD_LINKS="false", чтобы отключить. См. Межсерверное скачивание ниже.

• Межсписковые запросы и поиск (ответ берется из локального зеркала TodoIndex):

  • query_tasks — фильтр по спискам, статусу, диапазонам дат, важности, has-checklist, 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 выполняет полнотекстовый поиск по тексту контрольного списка или — без запроса — выводит ожидающие элементы сначала старые (то, что вы ждали дольше всего), сгруппированные по задачам. Работает в паре с фильтром has_open_checklist_item из query_tasks. Выключено по умолчанию (добавляет разовое первичное заполнение по каждой задаче); затем кэш остается свежим в обычном цикле дельта-синхронизации. Охватывает только открытые задачи — завершенные задачи намеренно исключены из межзадачных запросов по контрольным спискам (get_task по-прежнему показывает элементы любой задачи в реальном времени), а пропущенные списки (no_sync/Flagged Emails) не кэшируются.

• My Day и ручной порядок (по желанию, Substrate) — управляется параметром ENABLE_MY_DAY=true (используют недокументированную конечную точку Substrate, которую применяет веб-приложение To Do, поскольку My Day и позиция ручного перетаскивания невидимы для Graph): list_my_day_tasks, add_to_my_day, remove_from_my_day; list_tasks_by_manual_order (один список в ручном порядке приложения) и 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 подключается к Worker через удаленный MCP; Worker выступает посредником для запросов к Microsoft Graph API (поток OAuth с кодом авторизации и PKCE + секрет клиента). Синглтон TodoIndex Durable Object (состоятельный, строго согласованный вычислительный примитив Cloudflare) поддерживает зеркало с дельта-синхронизацией ваших списков и задач во встроенной базе данных SQLite, а также полнотекстовый индекс FTS5 (FTS5 — встроенный полнотекстовый движок SQLite). Межсписковые query_tasks, search_tasks и агрегирующие инструменты читают из этого локального зеркала, а не заново обходят Graph при каждом вызове; cron */15 поддерживает синхронизацию, а шлюз личности владельца обеспечивает приватность.

По умолчанию зеркало также подписывается на уведомления об изменениях Graph (по одному на список), поэтому изменение в любом клиенте To Do попадает в кэш примерно за ~2 минуты — почти мгновенно, как в нативных приложениях, — вместо ожидания следующего цикла таймера. Это триггер для дельта-синхронизации, а не замена: цикл таймера остается страховкой (Graph не гарантирует отсутствие пропущенных уведомлений для задач). Он использует существующую область Tasks.ReadWrite (без дополнительного согласия), требует доступного SERVICE_BASE_URL (Graph отправляет запросы на ${SERVICE_BASE_URL}/webhook) и управляется параметром ENABLE_TASK_SUBSCRIPTIONS ("false" ⇒ только таймер, без публичного вебхука). Уведомление также обновляет только поля My Day измененной задачи через одно целевое чтение Substrate — путь вебхука никогда не пишет обратно в Microsoft, поэтому не может зациклиться.

Небольшое, медленно меняющееся состояние — ваши OAuth-токены, запись о личности владельца и приведенные ниже конфигурационные блобы — живет в Cloudflare KV (хранилище ключ-значение). Большой, часто запрашиваемый корпус задач живет в SQLite Durable Object, а не в KV.

Модель безопасности

Сервер строго однопользовательский по замыслу, и несколько инвариантов являются ключевыми — их стоит сформулировать в одном месте:

• Один владелец, закрыт при сбое. Каждый вход контролируется на OAuth callback: Microsoft /me mail/userPrincipalName должны совпадать с секретом OWNER_EMAIL, и при несовпадении личности возвращается 403 до сохранения любого токена. Отсутствующее или введенное с ошибкой OWNER_EMAIL приводит к сбою проверки для всех — это блокирует доступ владельцу, но никогда не открывает доступ.

• Привязка хоста перед авторизацией. Каждый URL Graph и Substrate привязывается к ожидаемому хосту до добавления Bearer-токена, поэтому вредоносный @odata.nextLink не может перенаправить аутентифицированный запрос и выкрасть токен. Токены передаются только в заголовке Authorization — никогда в URL или строке лога.

• Единственный обновлятель токенов. Синглтон TodoIndex Durable Object — единственный вызывающий конечную точку токенов Microsoft; параллельные сеансы проходят через единую цепочку обновления, поэтому нет «штормов обновления» и логика обработки токенов не дублируется между сеансами.

• Конфигурация доступна только владельцу, а не является недоверенной поверхностью. Правила регулярных выражений в config:lists / config:link_rules доступны для записи только аутентифицированному владельцу (через MCP-инструменты за указанным выше шлюзом), поэтому проблемы пользовательских регулярных выражений, такие как ReDoS, не входят в модель угроз. Движок ссылок дополнительно ограничивает работу лимитом тела 8 КБ и бюджетом 50 мс на задачу.

• Веб-поверхности без секретов. /upload и /download авторизуются одноразовыми токенами возможностей — непредсказуемым случайным идентификатором, хранящимся в KV с TTL и ограниченным одной задачей/вложением, — поэтому нет ключа подписи или общего секрета, который нужно настраивать или который можно раскрыть.

• Логи не содержат секретов. Строки запросов (которые могут содержать дельта-токены) редактируются, тела ошибок Microsoft логируются как структурированные поля, а не как сырой текст, и единственная персональная информация в логах — собственный адрес владельца в строке о смене личности.

Конфигурация

Три необязательных конфигурационных блоба находятся в KV под привязкой TODO_CACHE. Готовые к редактированию примеры (с точными командами wrangler kv key put) находятся в config-examples/.

config:lists — классификация, псевдонимы, управление синхронизацией

• patterns — упорядоченные правила регулярных выражений, сопоставляемые с отображаемыми именами списков (emoji удаляются, по умолчанию без учета регистра); первое совпадение побеждает → todo | reference | excluded. Несопоставленные списки получают статус unclassified. Классификация обеспечивает фильтрацию в list_lists и параметры types/exclude_types в query_tasks/search_tasks. excluded исключает список из инструментов с фильтрацией по типам, но не останавливает его синхронизацию — для этого используйте no_sync.

• aliases — короткий идентификатор → Graph ID списка, который можно использовать везде, где принимается список. Автоматически очищается при смене учетной записи Microsoft (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 КиБ, подтвержденный лимит Graph). Для веб-загрузок это точка переключения: файлы размером не более этого предела прикрепляются встроенно, более крупные (до 25 МБ) — через фрагментированную сессию загрузки Graph. См. config-examples/attachments.json.

Веб-загрузка (/upload)

Файловые байты практически невозможно передать через вызов MCP-инструмента (бюджет аргументов модели на один вызов — несколько КБ). Вместо этого create_upload_link создает кратковременную (по умолчанию 15 мин, максимум 30), одноразовую ссылку, привязанную к конкретной задаче; пользователь открывает ее в браузере, и байты идут напрямую из браузера в Worker и далее в Microsoft Graph — никогда через модель. Укажите filename для ссылки на один файл или опустите его для пакетной ссылки (до max_files, 1–10, по умолчанию 5). Одинаковые файлы, уже прикрепленные к задаче, определяются по хешу содержимого и пропускаются как дубликаты.

Ссылка представляет собой токен возможности: непредсказуемый случайный идентификатор (32 байта из CSPRNG). Область назначения (идентификаторы списка/задачи, имя файла, количество файлов) хранится на сервере в OAUTH_KV под этим идентификатором с TTL; сам идентификатор в ссылке ничего не раскрывает. Обладание идентификатором разрешает одну загрузку ровно в указанную задачу — проверяется через KV lookup, истекает по TTL, потребляется (удаляется) при использовании. Никакого ключа подписи или общего секрета настраивать не нужно: идентификатор и есть nonce.

Чтобы включить эту возможность, задайте SERVICE_BASE_URL (var, в wrangler.jsonc) — публичный origin этого Worker (ваш URL workers.dev или собственный домен), используемый для построения ссылки. Если она не задана (или оставлена как заполнитель), create_upload_link возвращает upload_disabled.

Межсерверное скачивание (/download)

Операция, обратная загрузке: mint_download_link возвращает короткоживущий (≤ 5 мин) одноразовый URL и метаданные вложения (filename, content_type, size). Предполагаемый потребитель — url-ingest инструмент другого MCP-сервера: он получает URL на стороне сервера, поэтому байты перемещаются с сервера на сервер и никогда не попадают в контекст модели. Механика capability-токена зеркалит загрузку (непредсказуемый идентификатор в OAUTH_KV с префиксом download:, ограниченный одним вложением), а ссылка сжигается при первом достижимом GET независимо от результата — так что её нельзя воспроизвести, если она позже окажется в истории разговора. (Одноразовое использование против честного потребителя; как и /upload, операция не транзакционна — два действительно одновременных GET могут гоняться.) Метаданные читаются при создании (mint) из коллекции вложений, поэтому /download делает один вызов Graph для получения байтов и не доверяет никаким заголовкам запроса.

Возвращаемый size — это метаданные, сообщённые Graph, и он может завышать фактический размер байтов; авторитетный размер — Content-Length из скачивания. Передаваемые байты точны до байта относительно источника (проверено для вложения до 4 МиБ в рамках upload-сессии), так что передача достоверна, даже если size не совпадает. Большие вложения работают (Graph возвращает contentBytes в индивидуальном GET независимо от потолка inline-создания); практический предел — максимальный размер вложения Graph ~25 МБ, поскольку /download буферизует файл в памяти Worker.

Эта функциональность включена по умолчанию; установите ENABLE_DOWNLOAD_LINKS="false" (переменная), чтобы отключить и mint_download_link, и /download и уменьшить поверхность атаки, если она вам не нужна. Она также требует SERVICE_BASE_URL (как и для загрузки); не задано/заполнитель ⇒ download_disabled.

Сброс

Три уровня, от наименьшего к наибольшему. Выполняйте из корня проекта; замените --remote на --local, если хотите работать с локальным KV-хранилищем miniflare, используемым wrangler dev.

1. Мягкий сброс между итерациями тестирования

Самый частый случай: повторно запустить поток OAuth Microsoft, не уничтожая инфраструктуру. Автоматическая очистка при смене учётной записи (встроенная в /auth/microsoft/callback) автоматически очистит кэш для текущей учётной записи при следующей авторизации под другой учётной записью Microsoft 365 (M365), но вы можете также очистить вручную.

# 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 или — когда мы предоставим эту опцию — передайте &prompt=consent в /authorize.

2. Ротация учётных данных

Отредактируйте .dev.vars с новыми значениями, затем отправьте их все в Cloudflare за один раз:

bash scripts/push-secrets.sh

Скрипт читает каждое имя из .dev.vars и передаёт значение через stdin в wrangler secret put, поэтому значения никогда не появляются в argv, окружении, прокрутке терминала или AI-транскриптах. Проверьте с помощью npx wrangler secret list.

Любое значение в .dev.vars вместо этого может быть секретной ссылкой 1Password вида op://<vault>/<item>/<field> — скрипт разрешает её через op CLI во время отправки (требуется op signin или OP_SERVICE_ACCOUNT_TOKEN для headless-режима) и передаёт разрешённое значение через 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 использовал новую учётную запись.

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 разрушителен и необратим.

Автоматическая очистка при смене учётной записи (встроенная)

Когда /auth/microsoft/callback завершается с другим me.id, отличным от ранее сохранённого identity:owner.id, Worker автоматически очищает состояние, относящееся к учётной записи, перед сохранением новых токенов. Это предотвращает незаметное смешивание задач из двух учётных записей M365.

Что очищает автоматическая очистка, по порядку (fail-closed — сброс Durable Object выполняется первым, поэтому если он выбрасывает исключение, ничего другого ещё не произошло, и /authorize прерывается до сохранения новых токенов, никогда не оставляя наполовину очищенную смесь):

1. Сброс DO TodoIndex — удаляет все индексированные задачи, перечень списков и все курсоры дельты sync_state (корпус задач хранится в SQLite DO, а не в KV).

2. tokens:owner, затем identity:owner в TODO_CACHE (маркер учётной записи последним, так что сбой в середине очистки повторно запускает очистку при следующем /authorize, а не молча пропускает её).

3. config:lists.aliases — best-effort, поскольку алиасы — это Graph ID, привязанные к учётной записи, которые после переключения будут ссылаться на несуществующие списки. Классификационные patterns, no_sync, sync_flagged_emails, config:link_rules и config:attachments сохраняются (намерения, не зависящие от учётной записи).

Гранты OAUTH_KV не затрагиваются автоматической очисткой — ваша связка с Claude.ai продолжает работать при смене учётной записи Microsoft. Если вы хотите, чтобы клиент Claude.ai также прошёл повторную аутентификацию с нуля, выполните очистку OAUTH_KV в блоке мягкого сброса выше.

Когда срабатывает автоматическая очистка, генерируется структурированная строка журнала:

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

Вы можете использовать wrangler tail, чтобы наблюдать за этим во время тестирования.

Проектные решения, которые стоит пересмотреть

Зафиксировано здесь, чтобы будущие сопровождающие могли пересмотреть их, когда характер использования подскажет иной компромисс.

Пагинация list_tasks — живая выборка постранично, без кэша снимков

Инструмент list_tasks из Phase 2 выполняет пагинацию напрямую через Graph ($top + @odata.nextLink). next_cursor, возвращаемый вызывающим, — это непрозрачный URL nextLink от Graph; последующие вызовы GET используют этот URL через стандартный путь токенов/обновления GraphClient. tasks:{listId} НЕ записывается этим инструментом — дельта-синхронизация Phase 5 является единственным писателем этого ключа кэша.

Это документированное отклонение от указания плана Phase 2 «Кэшировать снимок в tasks:{listId} с использованием ETag». Вариант A (выбран) против Варианта B (загрузить все страницы при первом вызове, кэшировать снимок, затем нарезать страницы из кэша):

Пересмотрите вариант B, если wrangler tail в дальнейшем покажет, что LLM многократно листает глубоко по большим спискам в течение коротких интервалов — предварительная выборка + чтение из кэша сэкономили бы квоту Graph в целом ценой задержки первой страницы. По состоянию на Phase 2 типичное использование To Do — взрывное и неглубокое; живая пагинация в целом дешевле и позволяет отложить выбор структуры кэша до Phase 5, где он станет критичным.

Загрузка вложений — веб-/upload, а не вызов MCP-инструмента

Файловые байты практически не могут проходить через вызов MCP-инструмента: бюджет вывода/токенов Claude на один вызов ограничивает аргументы инструмента несколькими КБ, поэтому все, кроме тривиальных загрузок, завершаются ошибкой ещё до обращения к Graph (подтверждено при разработке родственного проекта obsidian-mcp-cloudflare). Встроенное ограничение Graph в 3072 КиБ никогда не было узким местом — узким местом был транспорт MCP.

Исходный инструмент create_attachment (встроенный base64 в вызове инструмента) был поэтому удалён и заменён веб-загрузкой: create_upload_link + публичная конечная точка /upload (см. Веб-загрузка). Байты идут браузер → Worker → Graph, прикрепляются встроенно для ≤ 3072 КиБ и через фрагментированную upload-сессию для файлов большего размера до 25 МБ. Ссылки — это capability-токены: непредсказуемый случайный идентификатор, область действия которого живёт в OAUTH_KV под TTL — привязаны к задаче, одноразовые и никогда не универсальные (каждая ссылка указывает на одну конкретную задачу). Никакой ключ подписи или общий секрет не задействован. Worker пересылает байты синхронно во время POST, поэтому не нужны ни R2 bucket, ни временное blob-хранилище. Перенесено из obsidian-mcp-cloudflare (его src/upload/*), адаптировано к API вложений To Do и упрощено до capability-токена без секретов.

Автор

Создано David Szpunar. Лицензировано под MIT License. История релизов в changelog.