# eXpress MCP connector

Локальный MCP-сервер для работы с чатами пользователя eXpress. Коннектор
регистрируется как отдельное устройство, получает только доступные пользователю
чаты, локально расшифровывает историю и при отдельном разрешении может отправлять
текстовые сообщения.

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

- проверка состояния подключения;
- поиск корпоративных и личных чатов;
- чтение доступной истории сообщений;
- отправка простого текста после показа получателя и текста пользователю;
- защита от повторной отправки при перезапуске или неопределённом ответе сервера;
- удаление локальной сессии и ключей.

По умолчанию коннектор работает только на чтение. Сессия, токены и ключи хранятся
в системном хранилище текущего пользователя: macOS Keychain, Windows Credential
Manager или Linux Secret Service. Они не записываются в репозиторий и не
возвращаются MCP-клиенту.

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

- Node.js 22 или новее;
- мобильное приложение eXpress с уже выполненным входом;
- разрешение организации на добавление пользовательского устройства;
- Codex или другой MCP-клиент с поддержкой локальных STDIO-серверов.

Работа проверена на macOS. Реализация системного хранилища предусмотрена также
для Windows и Linux, но её необходимо проверить в окружении конкретного
пользователя.

## Установка

```bash
git clone https://gitlab.mvs.group/ai/express-mcp-connector.git
cd express-mcp-connector
npm ci
npm run build
```

Для проверки локальной сборки:

```bash
npm test
```

## Подключение устройства eXpress

Запустите авторизацию из каталога проекта:

```bash
npm run auth:qr
```

Команда напечатает путь к временному PNG-файлу с QR-кодом. Откройте изображение,
затем в мобильном eXpress перейдите в список открытых сессий, выберите добавление
устройства и отсканируйте QR-код. Команда дождётся подтверждения и удалит
временный файл после завершения.

Если организация использует другой публичный сервер eXpress:

```bash
npm run auth:qr -- --rts-host express.example.org
```

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

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

Сначала выполните `npm run build`. Локальный MCP-сервер запускается по STDIO
командой:

```bash
node /absolute/path/to/express-mcp-connector/dist/mcp/server.js
```

### Codex на macOS или Linux

Находясь в каталоге проекта, добавьте сервер:

```bash
codex mcp add express -- "$(command -v node)" "$(pwd)/dist/mcp/server.js"
```

Проверьте регистрацию:

```bash
codex mcp get express
```

После добавления перезапустите Codex, если он уже был открыт.

### Codex на Windows PowerShell

```powershell
$node = (Get-Command node).Source
$server = (Resolve-Path .\dist\mcp\server.js).Path
codex mcp add express -- $node $server
codex mcp get express
```

Для другого MCP-клиента создайте локальный STDIO-сервер с командой запуска
`node` и единственным аргументом — абсолютным путём к `dist/mcp/server.js`.

## Проверка подключения

После запуска MCP попросите ассистента:

> Проверь подключение к eXpress.

Затем можно проверить чтение:

> Найди мои чаты eXpress с названием «Поддержка».

> Покажи последние 20 сообщений из выбранного чата. Ничего не отправляй.

Корпоративные чаты используются по умолчанию. Для личного пространства явно
укажите ассистенту, что нужен `personal` scope.

## Разрешение отправки сообщений

Отправка отключена при обычном подключении. Чтобы включить её, удалите текущую
запись MCP и добавьте сервер с переменной `EXPRESS_ENABLE_SEND=1`:

```bash
codex mcp remove express
codex mcp add express --env EXPRESS_ENABLE_SEND=1 -- \
  "$(command -v node)" "$(pwd)/dist/mcp/server.js"
```

На Windows используйте ранее полученные `$node` и `$server`:

```powershell
codex mcp remove express
codex mcp add express --env EXPRESS_ENABLE_SEND=1 -- $node $server
```

Даже при включённой отправке MCP-клиент должен показать точный чат и полный
текст и запросить подтверждение пользователя. Без подтверждения сообщение не
отправляется.

Пример запроса:

> Найди чат «Поддержка», подготовь сообщение «Проверка завершена» и покажи мне
> получателя и текст перед отправкой.

## Доступные MCP-инструменты

- `express_status` — проверяет готовность локальной сессии;
- `express_list_chats` — ищет и перечисляет доступные чаты;
- `express_get_history` — читает одну страницу истории, до 100 событий; для
  расшифрованных сообщений возвращает `senderId` из защищённого payload и
  `senderName` из справочника eXpress. Если имя не найдено, `senderName` равен
  `null` — придумывать или угадывать имя по другим полям нельзя. Для пересылки
  поле `forwardedFrom` отдельно содержит исходного автора и чат; при скрытой
  пересылке эти данные остаются `null`;
- `express_send_message` — отправляет текст после явного подтверждения.

Для старых страниц истории клиент использует курсор `nextBeforeSyncId`,
возвращённый предыдущим запросом.

## Восстановление и диагностика

Если QR-подключение завершилось, но корпоративный профиль ожидает повторного
подтверждения:

```bash
npm run auth:cts-retry
```

Проверить доступность корпоративного контура регистрации:

```bash
npm run auth:doctor
```

Если администратор разрешил вход по корпоративной почте:

```bash
npm run auth:cts-email-start -- --email user@example.org
npm run auth:cts-email-confirm
```

Вторая команда запросит шестизначный код скрытым вводом. Код не сохраняется.

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

```bash
npm run auth:repair
```

Если результат отправки остался неопределённым, сначала проверьте историю чата.
После проверки закройте запись одним из вариантов:

```bash
npm run send:reconcile -- <idempotency-uuid> delivered
npm run send:reconcile -- <idempotency-uuid> not_delivered
```

Для новой попытки после `not_delivered` используйте новый UUID и снова
подтвердите отправку.

## Отключение

Удалите MCP из Codex:

```bash
codex mcp remove express
```

Затем удалите локальную сессию, ключи и журнал отправок:

```bash
npm run auth:logout
```

После этого закройте устройство в списке открытых сессий eXpress, чтобы сервер
также отозвал его токены.

## Текущие ограничения

- доступны только чаты и история, разрешённые подключённому пользователю;
- глубина истории зависит от хранения на сервере, даты вступления в чат и
  доступных ключей;
- поддерживаются чтение и отправка простого текста; вложения, реакции,
  редактирование, удаление, пересылка и управление участниками не реализованы;
- за один вызов возвращается не более 100 событий;
- коннектор использует пользовательские интерфейсы eXpress, совместимость
  которых может измениться после обновления сервера или клиента.