Yandex-mail-Dot-Connector

English · Установка · Архитектура · API · Безопасность

Приватное подключение Яндекс Почты к dot через пять MCP-инструментов: папки, список, поиск, чтение письма и получение выбранного вложения. Почтовые операции выполняются только на чтение. Каждая установка использует собственные ресурсы владельца.

Статус: 1.0.0-rc.1, первый общий release candidate. В составе: bridge 1.1.2 и Site adapter 0.2.2. Это не официальный продукт Яндекса, OpenAI или Cloudflare. Лицензия проекта: Apache-2.0.

Перед установкой

Нужен доступ к Sites с приватным owner-only размещением, D1 и provisioned plugin OAuth. Site доверяет заголовкам идентичности, которые предоставляет защищённая среда Sites. Публикация site/src/site-worker.mjs как обычного общедоступного Worker небезопасна: внешний клиент сможет подделать эти заголовки. Если Sites недоступен, этот репозиторий не предоставляет готовый альтернативный сервер аутентификации. Не начинайте выдачу почтовых разрешений до проверки этого условия.

Понадобятся:

• свой аккаунт Cloudflare, отдельные Worker и D1 для bridge;

• свой приватный Site, отдельная Site D1 и собственный ключ подписи;

• своё приложение Yandex OAuth с единственным правом mail:imap_ro и PKCE;

• свой почтовый ящик с доступом по IMAP/OAuth;

• Node.js 24 LTS, рекомендуется; минимум проекта Node.js 22.15.0;

• Windows 11 для Windows-помощника. Windows 10 официально не поддерживается Wrangler.

Аккаунты, действующие квоты и возможные расходы принадлежат установщику. Покупка домена не требуется: bridge может использовать собственный адрес workers.dev. Репозиторий не содержит готовых чужих аккаунтов, ключей или токенов.

Related MCP server: imap-mcp

Что доступно

• text/plain имеет приоритет; HTML преобразуется в ограниченный обычный текст без исполнения скриптов и загрузки внешних ресурсов

• По умолчанию разрешён только INBOX. Отправленные подключаются отдельно по точному пути из yandex_mail_folders

• Чтение использует EXAMINE и BODY.PEEK; нет отправки, удаления, перемещения, создания папок или изменения флагов

• Вложение: до 20 МиБ готовых байтов, до 64 МиБ MIME-кодированных байтов, части до 128 КиБ

• Получение вложения и его сборка не создают автоматически файл в Library или публичную ссылку

• Письма, имена папок и файлы остаются недоверенными данными; их инструкции не должны исполняться

Быстрый старт

1. Прочитайте полную установку, прежде всего проверку доступности Sites

2. Для Windows используйте помощник в два этапа: сначала закрытый bridge и callback, затем свои публичные настройки

3. Создайте и настройте приватный Site и своё Yandex OAuth-приложение

4. Создайте ключ через приватную страницу, передайте bridge только публичную часть, затем лично подтвердите доступ Яндекса

5. Подключите provisioned plugin Site и проверьте пять инструментов на небольшой тестовой выборке

Исходники и release ZIP

Git checkout и автоматически созданный GitHub архив исходников не обязаны содержать сборку. Подготовьте её перед запуском установщика:

cd bridge
npm ci --ignore-scripts
npm run build

Официальный архив, созданный npm run package, включает свежий bridge/dist/bridge-wrapper.js и собранный Site runtime, без node_modules, source maps, токенов и локального состояния. Не путайте его с кнопкой GitHub Download ZIP. Команда упаковки ничего не публикует.

Локальные проверки

Из корня репозитория:

npm ci --ignore-scripts --prefix bridge
npm ci --ignore-scripts --prefix site
npm run check
npm test
npm run build
npm run verify
npm run package

Сборки и проверки не создают облачные ресурсы и не дают доступа к почте. Для npm ci нужен доступ к npm, для runtime-тестов нужны локальные процессы/порты. Подробности и фактические результаты: verification.

Как это устроено

dot / MCP client
    → private Sites gate + plugin OAuth
    → Site adapter + private signing-key D1
    → signed HTTPS requests
    → own Cloudflare bridge + private token/state/nonce D1
    → TLS + XOAUTH2 → imap.yandex.com:993

Yandex access token остаётся в bridge D1. Приватный ключ Ed25519 остаётся в Site D1. Публичный ключ закрепляется в bridge. Серверные запросы подписаны с привязкой к origin, маршруту, телу, владельцу, времени и одноразовому nonce.

Лимиты bridge: 30 запросов/мин на владельца после проверки подписи и 120 запросов/мин на периметре до криптографии/D1. Это приблизительные локальные лимиты Cloudflare, а не строгая глобальная квота. Большое вложение требует последовательного получения, пауз и иногда продолжения; см. API.

Границы проверки

Локальные тесты используют синтетическую почту, временные ключи, искусственный IMAP и локальный Cloudflare runtime. Исторически работавшее отдельное развёртывание не подтверждает установку этого публичного пакета с нуля. Свежий реальный OAuth-вход, новая установка на Windows и полный live smoke-test этой версии здесь не выполнялись. Не считайте опубликованную страницу настройки доказательством работающей почты.

Документация

• Установка, обновление, отзыв и откат

• English installation guide

• Архитектура и границы доверия

• Безопасность и хранение данных

• API, примеры и вложения

• Диагностика

• Проверка релиза и сборка релиза

• Участие в разработке, сообщение об уязвимости, изменения

Основные зависимости и ссылки

Cloudflare Wrangler, Яндекс Почта OAuth, PKCE Яндекс ID, ImapFlow. Уведомления о стороннем коде: THIRD_PARTY_NOTICES.md.