# MAX Personal MCP

[![CI](https://github.com/Uralmans/max-personal-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Uralmans/max-personal-mcp/actions/workflows/ci.yml)

**Личный MAX в вашем AI-ассистенте: чаты, история, сообщения и файлы через MCP.**

[English](README.en.md) · [Установка и эксплуатация](docs/operations.ru.md) · [Передача файлов](docs/file-transfer.ru.md) · [Безопасность](SECURITY.md)

Локальный сервер [Model Context Protocol](https://modelcontextprotocol.io/) для **личной учётной записи MAX**. Работает в Docker, подключается через QR-код и хранит сессию в отдельном томе. Для Codex и других MCP-клиентов предусмотрен stdio-мост: секрет доступа остаётся внутри контейнера.

> Независимый проект, не связанный с MAX и его правообладателями. Используется неофициальный [PyMax](https://github.com/MaxApiTeam/PyMax), а не Bot API. Изменения сервиса могут нарушить совместимость. Проверяйте правила MAX и используйте собственный аккаунт.

## Возможности

| Инструмент | Назначение |
| --- | --- |
| `account_status` | Состояние подключения и адрес локального входа |
| `get_me` | Профиль текущего пользователя |
| `list_chats` | Поиск и список чатов из кеша синхронизации |
| `get_chat` | Информация о чате по ID |
| `read_messages` | История без отдельной команды отметки прочтения |
| `get_user` | Профиль участника по ID |
| `send_message` | Текст, в том числе ответ на сообщение |
| `send_file` | Локальный файл, подпись и ответ на сообщение |
| `download_file` | Скачивание вложения с проверкой размера |

Отправка разрешена только по прямому поручению пользователя. При неизвестном результате сначала проверяется история — автоматических повторов после сетевого сбоя нет. Чат `0` используется для «Избранного»; перед первой отправкой проверьте его через `get_chat`.

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

Нужны Docker Engine с Compose v2 (или Docker Desktop), Python 3.10+ для вспомогательного скрипта и аккаунт MAX на телефоне. Linux-контейнер не зависит от ОС хоста; проверка реального MAX выполнена на Docker Desktop для macOS. Windows и Linux требуют отдельной проверки в вашей среде.

```sh
git clone https://github.com/Uralmans/max-personal-mcp.git
cd max-personal-mcp
python3 scripts/transfer.py status
docker compose up -d --build
```

Откройте [локальную страницу входа](http://127.0.0.1:9030/), запросите QR-код и подтвердите подключение в MAX на телефоне. Если потребуется пароль аккаунта, введите его только на локальной странице. Дождитесь подтверждения подключения.

Папка передачи создаётся командой `status` до запуска Compose. Она подключается только для чтения. Переменные прокси необязательны: при необходимости скопируйте `.env.example` в `.env` и укажите `MAX_PROXY`. Не публикуйте этот файл.

## Подключение к MCP-клиенту

Общая конфигурация клиента с поддержкой stdio:

```json
{
  "mcpServers": {
    "max": {
      "command": "docker",
      "args": ["exec", "-i", "max-mcp", "python", "/app/bridge.py"]
    }
  }
}
```

Убедитесь, что Docker CLI доступен MCP-клиенту. После настройки переподключите сервер или откройте новый чат. Контейнер должен быть запущен и авторизован.

Схема соединения:

```text
MCP-клиент → docker exec / stdio → мост → локальный MCP-сервер → MAX
                                             │
                                  сессия в Docker volume
```

## Отправить файл

```sh
python3 scripts/transfer.py stage /path/to/report.zip
```

Скрипт вернёт путь `/transfer/<job>/000/report.zip`, размер и SHA-256. Передайте путь в `send_file`, затем проверьте имя и размер вложения в истории чата. Только после проверки удалите временную копию через `finish`. Подробности и команды для Windows: [передача файлов](docs/file-transfer.ru.md).

Расширению доступа ко всему диску этот сценарий не требует. Исходники файлов остаются на месте. Лимит допуска файла — 2 ГБ; фактический успех зависит от сервиса, сети, тайм-аутов и свободного места.

## Что защищено

- Порт опубликован только на `127.0.0.1`; MCP требует Bearer-ключ, который читает мост.
- Для браузерного входа проверяются Host и Origin, QR и статус не кешируются.
- Контейнер работает без root, с файловой системой только для чтения и без Linux capabilities.
- У загрузки есть отдельная папка; выход через `..`, ссылки и специальные файлы отклоняются.
- Учётные данные, `.env`, файлы сессий, QR, результаты и временные копии исключены из Git. Docker build использует список разрешённых файлов.

При этом доверенный MCP-клиент получает доступ к личным сообщениям и может выполнять разрешённые отправки. Это локальный сервис для одного владельца, без отдельных ролей и учёта полномочий разных пользователей. Подробнее: [SECURITY.md](SECURITY.md).

## Проверки

```sh
docker compose build
docker run --rm --read-only --tmpfs /tmp -v "$PWD/tests:/tests:ro" \
  local/max-personal-mcp:0.2.0 python -m unittest discover -s /tests -v
docker exec max-mcp python /app/probe.py
python3 scripts/check_public_files.py
```

22 автоматических теста проверяют границы доступа, работу с файлами и ошибки без обращения к MAX. В рабочей среде дополнительно подтверждена отправка ZIP в «Избранное»: сообщение найдено в истории, скачанное вложение совпало с оригиналом по SHA-256. Это не проверка всех форматов файлов и размеров до 2 ГБ. В CI личный аккаунт и секреты не используются.

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

- [Эксплуатация и диагностика](docs/operations.ru.md)
- [Передача файлов](docs/file-transfer.ru.md)
- [Модель безопасности](SECURITY.md)
- [Участие в разработке](CONTRIBUTING.md)
- [Изменения](CHANGELOG.md)

Лицензия: [MIT](LICENSE). PyMax и остальные зависимости распространяются под собственными лицензиями; их исходники и сессии не включены в репозиторий.