<div align="center">

# 📬 yandex-mail-mcp (Docker / Cloud.ru Edition)

**Научите вашего ИИ-агента работать с вашей почтой Яндекс.**

[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Protocol](https://img.shields.io/badge/Protocol-MCP-8A2BE2)](https://modelcontextprotocol.io)
[![Cloud.ru](https://img.shields.io/badge/Cloud.ru-AI%20Factory-blue)](#cloudru)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

</div>

---

> **Об этом проекте**
>
> Этот репозиторий основан на проекте [yandex-mail-mcp](https://github.com/dreamcatchered/yandex-mail-mcp) от **dreamcatchered**. Огромная благодарность автору за проделанную работу: логику работы с IMAP/SMTP, OAuth 2.1 и сами MCP-инструменты.
>
> В этой версии код (`app.py`) адаптирован для развертывания в контейнерах Docker и на облачной платформе **Cloud.ru (AI Factory / AI Agents)**. Добавлены поддержка переменных окружения, логирование в стандартный вывод (`stdout`) для облачных сред и настройка сетевого интерфейса `0.0.0.0`.

---

## ✨ Что внутри

| Возможность | Описание |
| --- | --- |
| 📨 **14 инструментов** | Чтение, поиск, отправка, ответ с сохранением цепочки, пересылка, черновики, метки, перемещение и удаление писем. |
| 🐳 **Docker-контейнер** | Готов к развертыванию в Cloud.ru, локально или на сервере. |
| 🌐 **Поддержка кириллицы** | Папки и поиск по-русски, корректная обработка тем и тел писем. |
| ⚙️ **Конфигурация через ENV** | Передача учетных данных через переменные окружения без изменения кода. |

## 📋 Требования

- **Python 3.11+** — для локального запуска без Docker.
- **Docker** — для запуска в контейнере.
- Аккаунт **Яндекс Почты** с включённым IMAP.
- **Пароль приложения**, созданный в настройках Яндекс ID.

## 🚀 Установка и запуск (Docker)

### 1. Получение пароля приложения в Яндексе

1. Перейдите в [настройки паролей приложений Яндекс ID](https://id.yandex.ru/security/apppasswords).
2. Нажмите **«Создать пароль приложения»**, например для `MCP-Server`.
3. Скопируйте выданный пароль.
4. Убедитесь, что IMAP включён: [Яндекс Почта](https://mail.yandex.ru) → **Настройки** → **Доступ по IMAP**.

### 2. Клонирование репозитория

Склонируйте репозиторий на свой компьютер:
```bash
git clone https://github.com/mariakornet/yandex-mail-mcp.git
cd yandex-mail-mcp
```

сли у вас не установлен Git, вы можете скачать проект как ZIP-архив: нажмите зеленую кнопку Code на странице репозитория и выберите Download ZIP.
### 3. Сборка Docker-образа

Выполните команду в корне проекта:

```bash
docker build -t yandex-mail-mcp:local .
```

### 4. Запуск контейнера

Создайте файл `.env` в корне проекта или передайте переменные через параметр `-e`:

```dotenv
YANDEX_EMAIL=your-mailbox@yandex.ru
YANDEX_APP_PASSWORD=пароль-из-шага-1
ACCESS_CODE=любой-длинный-случайный-код
HOST=0.0.0.0
PORT=5180
```

Запустите контейнер:

```bash
docker run -d -p 5180:5180 --env-file .env --name yandex-mail-mcp yandex-mail-mcp:local
```

### 5. Проверка работоспособности

```bash
curl http://localhost:5180/healthz
```

Ожидаемый ответ содержит поле `"status": "ok"` и время работы сервера в `uptime_s`. Например:

```json
{
  "status": "ok",
  "uptime_s": 42
}
```

<a id="cloudru"></a>

## ☁️ Развертывание в Cloud.ru

Подробная документация Cloud.ru:

- [Создание MCP-сервера](https://cloud.ru/docs/ai-agents/ug/topics/guides__create-mcp-server).
- [Работа с Artifact Registry](https://cloud.ru/docs/artifact-registry-evolution/ug/topics/guides__registry?source-platform=Evolution).

### 1. Загрузка образа в Artifact Registry

В примере используется реестр `yandex-mcp.cr.cloud.ru`. Замените его адрес и значения `<Key_ID>` и `<Key_Secret>` на свои:

```bash
docker login yandex-mcp.cr.cloud.ru -u <Key_ID> -p <Key_Secret>
docker tag yandex-mail-mcp:local yandex-mcp.cr.cloud.ru/yandex-mail-mcp:v1
docker push yandex-mcp.cr.cloud.ru/yandex-mail-mcp:v1
```

### 2. Создание MCP-сервера

1. Перейдите в **AI Factory → AI Agents → MCP-серверы**.
2. Нажмите **«Создать MCP-сервер»** и выберите способ **Artifact Registry**.
3. Укажите порт `5180` и добавьте переменные окружения:
   - `YANDEX_EMAIL`;
   - `YANDEX_APP_PASSWORD`;
   - `ACCESS_CODE`.
4. Дождитесь статуса **«Запущен»**.
5. Проверьте работу на вкладке **«Тестирование»**.

> **Примечание:** если тестирование через интерфейс нестабильно, проверьте логи сервера. Успешные запросы имеют код `200`, ошибки авторизации — `401`.

## 🛠️ Инструменты

| Инструмент | Что делает |
| --- | --- |
| `unread_count` | Возвращает общее количество писем и количество непрочитанных. Подходит для ответа на вопрос «Что нового?». |
| `list_folders` | Возвращает все папки с указанием их назначения. |
| `search_emails` | Ищет письма. Параметр `query` использует синтаксис IMAP: `ALL`, `UNSEEN`, `FROM "a@b.c"`, `SUBJECT "счёт"`, `SINCE 01-Dec-2025`. |
| `read_email` | Возвращает полный текст письма и список вложений. |
| `send_email` | Отправляет письмо. Поддерживает `cc`, `bcc` и `html`. |
| `reply_email` | Отвечает на письмо с сохранением цепочки переписки. |
| `forward_email` | Пересылает письмо. |
| `create_draft` | Создаёт черновик без отправки. |
| `move_email` | Перемещает письмо в другую папку. |
| `mark_email` | Изменяет статус «прочитано / не прочитано», флаги «важное» и «звезда». |
| `delete_email` | Перемещает письмо в Корзину; при `expunge: true` удаляет безвозвратно. Требует `confirm: true`. |
| `search` / `fetch` | Инструменты-обёртки для Deep Research. |
| `verify_connection` | Проверяет подключение к IMAP/SMTP. Рекомендуется вызывать первым при возникновении проблем. |

**Идентификатор письма** — строка вида `папка|uid`, например `INBOX|41703`.

Папки можно называть по-русски или по-английски.

## 🔐 Безопасность

| Аспект | Реализация |
| --- | --- |
| Доступ к MCP | OAuth 2.1: Authorization Code + PKCE (`S256`). Срок действия токенов — 12 часов, refresh-токенов — 90 дней. Применимость к текущей сборке см. в предупреждении ниже. |
| Пароль почты | Хранится в переменных окружения или в `config.json` с правами доступа `600`. Не попадает в ответы и логи. |
| Доступ через облачную платформу | В облаке доступ контролируется платформой Cloud.ru. |
| Опасные действия | Инструмент `delete_email` требует явного подтверждения: `confirm: true`. |

> **⚠️ Важно**
>
> В текущей версии для тестирования в Cloud.ru авторизация может быть отключена: функция `is_authenticated` возвращает `True`.
>
> Перед промышленной эксплуатацией включите строгую проверку токена.

## 🧠 Особенности реализации

Особенности, отмеченные автором оригинального проекта:

- **Кодировка папок.** Имена папок используют modified UTF-7. Реализованы декодер и кодер по RFC 3501.
- **Поиск по кириллице.** Требуется `CHARSET UTF-8`. Без него команда `SEARCH` возвращает `NO`.
- **Повторное использование соединения.** IMAP-соединение переиспользуется, что сокращает задержки при подключении к Яндексу.

## 📄 Лицензия

Проект распространяется под лицензией [MIT](LICENSE). Вы можете свободно использовать и дорабатывать код в соответствии с условиями лицензии.

**Оригинальный проект:** [dreamcatchered/yandex-mail-mcp](https://github.com/dreamcatchered/yandex-mail-mcp).