# max-channel-mcp

MCP-сервер для публикации в каналы мессенджера [MAX](https://max.ru).

Подключается к Claude Desktop, Claude Code и другим клиентам, поддерживающим
Model Context Protocol. После настройки ассистент может публиковать в вашем канале
текст, фотографии, видео, аудио, документы и геометки — просто по вашей просьбе.

```
Вы:  Опубликуй в канале анонс с картинкой из ~/Downloads/banner.png
     и кнопкой на сайт.

ИИ:  [вызывает max_send_photos]
     Опубликовано. Ссылка: https://max.ru/ваш_канал/AaApSIDNYGM
```

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

- Публикация текста с разметкой Markdown или HTML
- Альбомы до 10 фотографий, видео, смешанные альбомы
- Аудио, документы, геометки
- Кнопки под сообщениями — ссылки и callback
- Изменение и закрепление опубликованных сообщений
- Чтение истории канала

Удаление сообщений намеренно не реализовано: ассистент не должен иметь возможности
стереть содержимое канала.

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

- Node.js 18.18 или новее
- Бот, созданный через [MasterBot](https://max.ru/masterbot)
- Права администратора у бота в вашем канале

## Установка

### Claude Code

```sh
claude mcp add max-channel \
  --scope local \
  --env MAX_BOT_TOKEN=ваш_токен \
  --env MAX_CHAT_ID=-10000000000001 \
  -- npx -y max-channel-mcp
```

Область `local` держит токен в вашем личном конфиге, а не в файле проекта.

### Claude Desktop

Добавьте в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "max-channel": {
      "command": "npx",
      "args": ["-y", "max-channel-mcp"],
      "env": {
        "MAX_BOT_TOKEN": "ваш_токен",
        "MAX_CHAT_ID": "-10000000000001"
      }
    }
  }
}
```

Путь к файлу настроек:
- macOS — `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows — `%APPDATA%\Claude\claude_desktop_config.json`

### Из исходников

```sh
git clone https://github.com/eduard256/max-channel-mcp.git
cd max-channel-mcp
npm install
npm run build
```

Затем укажите в конфиге `node /полный/путь/dist/index.js` вместо `npx`.

## Настройка

### Как получить токен

Откройте [MasterBot](https://max.ru/masterbot), создайте бота по инструкции —
в ответ придёт токен.

### Как узнать идентификатор канала

1. Добавьте бота в канал администратором.
2. Выполните запрос:

```sh
curl -H "Authorization: ВАШ_ТОКЕН" https://platform-api2.max.ru/chats
```

3. Возьмите поле `chat_id` нужного канала. Обычно это отрицательное число.

### Переменные окружения

| Переменная | Обязательна | Назначение |
|---|---|---|
| `MAX_BOT_TOKEN` | да | Токен бота от MasterBot |
| `MAX_CHAT_ID` | да | Идентификатор канала для публикации |
| `MAX_CA_CERT_PATH` | нет | Свой корневой сертификат вместо встроенного |
| `MAX_DISABLE_CUSTOM_CA` | нет | `1` — не подключать встроенный сертификат |

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

| Инструмент | Что делает |
|---|---|
| `max_send_text` | Текстовое сообщение |
| `max_send_photos` | От 1 до 10 фотографий с общей подписью |
| `max_send_video` | Одно или несколько видео |
| `max_send_media_group` | Фотографии и видео в одном сообщении |
| `max_send_audio` | Аудиофайл |
| `max_send_file` | Документ |
| `max_send_location` | Точка на карте |
| `max_edit_message` | Изменить текст опубликованного сообщения |
| `max_pin_message` | Закрепить сообщение |
| `max_unpin_message` | Снять закрепление |
| `max_get_messages` | Последние сообщения канала |
| `max_get_channel_info` | Сведения о канале и правах бота |

Файлы передаются путями на диске. Кнопки — необязательный параметр `кнопки`
у всех публикующих инструментов.

## Ограничения MAX

Проверено на практике. В официальной документации эти правила описаны неполно.

| Правило | Подробности |
|---|---|
| Длина текста | не более 4000 символов |
| Фотографии | до 10 в одном сообщении |
| Видео | несколько в одном сообщении допустимо |
| Аудио | ровно одно, ни с чем не сочетается |
| Документ | ровно один, ни с чем не сочетается |
| Геометка | ровно одна, ни с чем не сочетается |
| Фото + видео | единственное разрешённое сочетание разных типов |
| Кнопки | добавляются к любому сообщению |
| Разметка | работает только при явно указанном формате |

Смешивание аудио, документов и геометок с другими вложениями сервер отклоняет
с ошибкой вида `Must be only one audio attachment in message`.

## Сертификаты

Серверы MAX используют сертификат удостоверяющего центра
**«Russian Trusted Root CA»** (Минцифры РФ). Этого корня нет в стандартном
хранилище Node.js, поэтому без дополнительной настройки соединение обрывается
с ошибкой `unable to get local issuer certificate`.

Чтобы сервер работал на любой машине без ручной настройки, корневой сертификат
включён в состав пакета — файл `certs/russian_trusted_root.pem`.

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

- сертификат применяется **только** к доменам `max.ru`, `oneme.ru`, `okcdn.ru`
  и `mycdn.me` — остальной трафик проверяется обычным образом;
- он **добавляется** к системным корням, а не заменяет их;
- при запуске сверяется контрольная сумма SHA-256; если файл подменён,
  сервер не стартует;
- ничего не устанавливается в систему — настройка действует только внутри
  процесса сервера.

Отпечаток встроенного сертификата:

```
d26d2d0231b7c39f92cc738512ba54103519e4405d68b5bd703e9788ca8ecf31
```

Сверить можно с опубликованным на [gosuslugi.ru](https://www.gosuslugi.ru/crt).

Если корень уже установлен в вашей системе, встроенный можно отключить:
`MAX_DISABLE_CUSTOM_CA=1`. Свой сертификат подключается через `MAX_CA_CERT_PATH`.

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

Сервер пишет диагностику в стандартный поток ошибок. При запуске выводится
состояние TLS и результат проверки подключения.

| Сообщение | Причина и решение |
|---|---|
| `не задана переменная MAX_BOT_TOKEN` | Проверьте `env` в конфиге клиента |
| `Токен отклонён` | Токен устарел или скопирован не полностью — перевыпустите через MasterBot |
| `Нет доступа к каналу` | Бот не добавлен в канал или не является администратором |
| `Ошибка проверки сертификата` | Убедитесь, что не задана `MAX_DISABLE_CUSTOM_CA=1` |
| `Не удалось загрузить изображение` | Проверьте путь и формат файла |
| `Файл не найден` | Указывайте абсолютные пути |

## Известная проблема библиотеки

Сервер использует официальную библиотеку
[`@maxhub/max-bot-api`](https://github.com/max-messenger/max-bot-api-client-ts).
В версии 0.2.5 загрузка изображений и документов по пути к файлу или через поток
не работает на Node.js 21 и новее: в `FormData` подставляется объект, который
современный `undici` не распознаёт как файл, и сервер отвечает `NO_IMAGE`.

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

## Лицензия

MIT