eXpress MCP connector

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

Возможности

• проверка состояния подключения;

• поиск корпоративных и личных чатов;

• чтение доступной истории сообщений;

• отправка простого текста после показа получателя и текста пользователю;

• защита от повторной отправки при перезапуске или неопределённом ответе сервера;

• удаление локальной сессии и ключей.

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

Related MCP server: WhatsApp MCP

Требования

• Node.js 22 или новее;

• мобильное приложение eXpress с уже выполненным входом;

• разрешение организации на добавление пользовательского устройства;

• Codex или другой MCP-клиент с поддержкой локальных STDIO-серверов.

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

Установка

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

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

npm test

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

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

npm run auth:qr

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

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

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

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

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

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

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

Codex на macOS или Linux

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

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

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

codex mcp get express

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

Codex на Windows 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:

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

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

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-подключение завершилось, но корпоративный профиль ожидает повторного подтверждения:

npm run auth:cts-retry

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

npm run auth:doctor

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

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

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

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

npm run auth:repair

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

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

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

Отключение

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

codex mcp remove express

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

npm run auth:logout

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

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

• доступны только чаты и история, разрешённые подключённому пользователю;

• глубина истории зависит от хранения на сервере, даты вступления в чат и доступных ключей;

• поддерживаются чтение и отправка простого текста; вложения, реакции, редактирование, удаление, пересылка и управление участниками не реализованы;

• за один вызов возвращается не более 100 событий;

• коннектор использует пользовательские интерфейсы eXpress, совместимость которых может измениться после обновления сервера или клиента.