HSE SmartLMS and personal account

hse-mcp

Локальный MCP-сервер (stdio) для инфраструктуры НИУ ВШЭ: SmartLMS (edu.hse.ru) и Единый личный кабинет (lk.hse.ru). Расписание RUZ (ruz.hse.ru) вынесено в отдельный сервер hse-ruz-mcp (claude mcp add hse-ruz-mcp -- npx -y hse-ruz-mcp).

Дисклеймер

• Неофициальный проект: не связан с НИУ ВШЭ и не одобрен ею.
• Правила ВШЭ об автоматизированном доступе к SmartLMS и ЕЛК не проверялись; за их соблюдение отвечает пользователь.
• Использование на свой риск, без гарантий (см. лицензию).
• Тулы записи отправляют данные от вашего имени и необратимы: сдача может уйти на оценку сразу, заказ справки отменить нельзя. По умолчанию они выключены (HSE_ENABLE_WRITES).
• Авторы не хранят и не получают ничьих учётных данных: пароль, сессия и журнал остаются на вашей машине (подробности ниже и в SECURITY.md).

Установка и запуск

Нужен аккаунт ВШЭ. Каждый пользователь ставит сервер у себя со своими данными.

Claude Desktop — без терминала

1. Скачайте hse-mcp-<версия>.mcpb из последнего релиза.
2. Откройте файл двойным щелчком (или перетащите в окно Claude Desktop, или Настройки → Расширения → Дополнительно → Установить расширение…).
3. Введите email и пароль ВШЭ и нажмите «Установить». Пароль Claude Desktop хранит в системной связке ключей и передаёт серверу при запуске.

Node.js ставить не нужно: он входит в Claude Desktop для Windows и macOS. Для входа нужен браузер: сервер берёт Microsoft Edge (есть на любой Windows) или Google Chrome, а если их нет, при первом запросе сам скачивает Chromium (около 100 МБ, один раз) — тогда первый запрос попросит повторить его через пару минут. Галочка «Разрешить отправку данных» включает тулы записи (см. «Тулы записи»); по умолчанию она выключена. Файлы для сдачи заданий кладутся в папку из настроек расширения (по умолчанию Документы/hse-mcp-outbox, создаётся сама).

Через npx (нужен Node.js 22+)

npx -y hse-mcp credentials set   # email и пароль ВШЭ → системное хранилище
claude mcp add hse-mcp -e [email protected] -- npx -y hse-mcp

Для Claude Desktop, Cursor и других клиентов — в их конфигурацию MCP:

{
  "mcpServers": {
    "hse-mcp": {
      "command": "npx",
      "args": ["-y", "hse-mcp"],
      "env": { "HSE_EMAIL": "[email protected]" }
    }
  }
}

Пароль в этот файл не пишите: он хранится открытым текстом. npx -y hse-mcp install-browser скачивает Chromium заранее (иначе — как выше: Edge, Chrome или скачивание при первом запросе).

Из исходников (для разработки)

Нужен Node.js 22 или новее.

npm ci
npx playwright install chromium
cp .env.example .env      # заполнить HSE_EMAIL
npm run credentials:set   # пароль в системное хранилище (рекомендуется)
npm run build
claude mcp add hse-mcp -- node <путь-к-проекту>/dist/index.js

HSE_PASSWORD в .env необязателен: это запасной путь, если системное хранилище недоступно (см. «Учётные данные»). .env и storage/ в .gitignore — не коммитятся, локальны для установки и никуда не отправляются, кроме как в сами сервисы ВШЭ при логине.

Каталог данных

Сессия браузера, ключ и журнал записей, снимки hse_changes и папка «исходящих» по умолчанию лежат в каталоге данных:

• в клоне репозитория (есть .git) или если storage/ уже есть — storage/ в корне проекта;
• иначе (.mcpb, npx) — %LOCALAPPDATA%\hse-mcp на Windows, ~/Library/Application Support/hse-mcp на macOS, ~/.local/share/hse-mcp на Linux: папку установки хост может пересоздать при обновлении;
• HSE_DATA_DIR задаёт каталог явно (абсолютный путь или относительно корня проекта).

Необязательные переменные (.env или окружение): HSE_ENABLE_WRITES=true включает тулы записи (по умолчанию выключены; см. «Тулы записи»), HSE_OUTBOX_DIR задаёт папку «исходящих», HSE_BROWSER_CHANNEL — браузер: auto (по умолчанию: скачанный Chromium, затем Edge и Chrome, затем скачивание), chromium, chrome или msedge. Проверка, что защита записи цела: npm test (ожидается fail 0; тесты не ходят в сеть и не читают учётные данные).

認証情報

パスワードは次の順に検索され、最初に見つかったものが使われます。

1. プロセスの環境変数 HSE_PASSWORD（MCP クライアントによって設定されたものを含みます）。
2. システムの認証情報ストア：Windows Credential Manager、macOS Keychain、Linux Secret Service（サービス hse-mcp、アカウントは HSE_EMAIL の値）。オプションの依存関係 @napi-rs/keyring を使用します。
3. .env の HSE_PASSWORD（フォールバック）。

HSE_EMAIL はシークレットではなく、環境または .env から取得されます。

コマンド：

• npm run credentials:set（または npx hse-mcp credentials set）— 画面に表示せずにパスワードを尋ね、 システムの認証情報ストアに保存します。
• npm run credentials:status（npx hse-mcp credentials status）— パスワードの取得元 （env、keychain、dotenv、none）のみを表示し、値やメールアドレスは表示しません。
• npm run credentials:clear（npx hse-mcp credentials clear）— 認証情報ストアのエントリを削除します。

.mcpb パッケージでは、パスワードは拡張機能の設定から環境変数（HSE_PASSWORD）を通じて渡されます。 この場合、hse-mcp のシステム認証情報ストアは使用されません。

パスワードを .env から取得した場合、サーバーは stderr に値を含めず、警告を一度だけ出力します。 Linux と macOS では、.env のアクセス権でグループまたは他のユーザーによる読み取りが許可されている場合にも 警告します（修正方法：chmod 600 .env）。Windows ではサーバーは .env のアクセス権を確認しません。 ユーザー名を自分のものに置き換えて、手動でアクセス権を制限してください。

icacls .env /inheritance:r /grant:r "$($env:USERNAME):(F)"

データディレクトリ（クローン内の storage/）とその writes/ は、サーバーによって所有者のみに制限されます （POSIX では 0o700、Windows では icacls と継承を使用し、新しいファイルもすぐに制限されたアクセス権で作成されます）。 また、ファイル hse-session.json と writes/key は 0o600 / icacls で制限されます（エラーは出力されません）。

システムの認証情報ストアは、完全に無効化できます。HSE_DISABLE_KEYCHAIN=true（環境または .env）を設定してください。 CI、グラフィカルセッションのないサーバー、Secret Service のない Linux に適しています。npm test はこの設定を自動で行うため、 テストで実際の認証情報ストアが使用されることはありません。

注意事項：

• @napi-rs/keyring をインストールできなかった場合（npm ci --omit=optional、プラットフォーム用のバイナリがないなど）や 認証情報ストアを利用できない場合、プロジェクトは何も通知せず .env を使って動作を続けます。インストールは失敗しません。
• Linux では Secret Service が起動している必要があります（GNOME Keyring、KWallet など。グラフィカル環境のないセッションでは 利用できないことがよくあります）。Secret Service がない場合、パッケージは再起動後も保持されないカーネルの keyutils 認証情報ストアを使うことになります。そのため、この場合は認証情報ストアを利用できないものとみなし、 .env を使います。この確認は起動時に同期的に呼び出されます。キーリングがロックされている場合や D-Bus がない場合は、 起動が大幅に遅れることがあります。その場合は HSE_DISABLE_KEYCHAIN=true を設定してください。この呼び出しにタイムアウトはありません。 Linux での動作は検証されていません。
• この保護は、偶発的な漏えいや、システム上の別のユーザーによるファイルの読み取りを想定したものであり、 自分のユーザー権限で動作する悪意あるプログラムへの対策ではありません。

パスワードまたはデータディレクトリ内のファイルが漏えいした可能性がある場合は、ВШЭ のパスワードを変更し （.mcpb の場合は拡張機能の設定も変更してください）、データディレクトリ内の hse-session.json と writes/key を削除して、 npm run credentials:clear を実行してください（outbox/ フォルダーと書き込みログはお客様のデータです）。 詳細と脆弱性報告の連絡先については、SECURITY.md を参照してください。 公開リポジトリでは、GitHub の secret scanning と push protection を有効にしてください（任意で、pre-commit に gitleaks を追加できます。 プロジェクトの依存関係には含まれていません）。

Тулы

21 тул чтения и 3 тула записи (только при HSE_ENABLE_WRITES=true). Что из этого покрыто тестами и проверено вживую — в docs/status.md.

Модуль	Тул	Описание
SmartLMS	lms_list_courses	Список курсов
SmartLMS	lms_get_course_materials	Элементы курса (файлы, задания, тесты и т.п.)
SmartLMS	lms_list_assignments	Задания курса со сроками
SmartLMS	lms_get_grades	Оценки по курсу: строки журнала с названием, путём категорий и оценкой; ошибка, если вёрстка журнала курса не распознана
SmartLMS	lms_list_messages	Входящие внутренней почты SmartLMS (переписка с преподавателями в курсах)
SmartLMS	lms_get_message	Полный текст письма внутренней почты SmartLMS с вложениями
SmartLMS	lms_open_page	Открыть произвольную страницу edu.hse.ru
ЕЛК	elk_get_schedule	Расписание через API ЕЛК — работает из любой сети
ЕЛК	elk_get_user_info	Данные аккаунта: ФИО, email, роли
ЕЛК	elk_get_academic_data	Академическая карточка: рейтинг, GPA, кредиты, программа, группа
ЕЛК	elk_search_services	Поиск по каталогу из 254+ сервисов ЕЛК (справки, заявки и т.п.)
ЕЛК	elk_list_requests	История поданных заявок (/claim) со статусами
ЕЛК	elk_get_notifications	Уведомления (колокольчик в шапке)
ЕЛК	elk_get_section	Раздел ЕЛК по имени: profile (страница профиля), login_history (история входов), tasks (задачи), dpo_programs (программы ДПО), antiplagiat, course_evaluation (СОП), thesis (ВКР/КР), portfolio, internships (практики), scholarship_history (повышенная стипендия)
ЕЛК	elk_open_page	Открыть произвольную страницу lk.hse.ru
Сводки	my_today	Что сегодня: занятия, дедлайны, непрочитанные письма LMS и уведомления ЕЛК, активные заявки
Сводки	my_week	План на 7 дней: расписание, дедлайны, экзамены, просроченные несданные работы
Сводки	my_deadlines	Что горит: несданные задания и тесты (в т.ч. просроченные), окна ЕЛК, экзамены за days дней
Изменения	hse_changes	Что изменилось с прошлого раза: дедлайны, расписание, входящее, заявки (и оценки LMS по явной просьбе); ack подтверждает полученное
Изменения	hse_changes_reset	Стереть локальные базы и журнал событий (confirm: true)
Служебное	hse_clear_cache	Сбросить кэш в памяти, чтобы следующий вызов взял свежие данные
SmartLMS (запись)	lms_submit_assignment	Сдать или поправить ответ на задание файлами из папки «исходящих». Только при HSE_ENABLE_WRITES=true
SmartLMS (запись)	lms_delete_submission	Удалить представленный ответ на задание. Только при HSE_ENABLE_WRITES=true
ЕЛК (запись)	elk_order_certificate	Заказать справку через форму сервиса ЕЛК (необратимо). Только при HSE_ENABLE_WRITES=true

Тулы записи — что нужно знать

Три тула записи (lms_submit_assignment, lms_delete_submission, elk_order_certificate) отправляют данные в SmartLMS и ЕЛК, заказ справки в ЕЛК необратим, поэтому по умолчанию тулов записи у сервера нет вообще. Чтобы включить, добавьте в .env строку HSE_ENABLE_WRITES=true (в Claude Desktop — галочка «Разрешить отправку данных» в настройках расширения; значение читается при старте процесса, после правки перезапустите сервер). Остальные тулы только читают.

• lms_submit_assignment — cmid (id модуля задания из lms_get_course_materials), files (имена файлов, не пути), mode: draft (по умолчанию) или submit. Файлы берутся только из папки «исходящих»: outbox/ в каталоге данных или папка из HSE_OUTBOX_DIR (абсолютный путь или относительно корня проекта); если папки нет, а её родитель есть, она создаётся. Не больше 10 файлов, только обычные непустые файлы; папка не может быть корнем проекта или каталогом данных (кроме его outbox/). Файлы не удаляются и не перемещаются. Одноимённый файл ответа перезаписывается, остальные файлы ответа остаются. Онлайн-текст не поддерживается: параметр text отклоняется.
• lms_delete_submission — cmid. Удаляет ответ из системы; файлы в папке «исходящих» остаются.
• elk_order_certificate — serviceId (число components из url результата elk_search_services, не поле id) и fields (подпись поля формы → точный текст варианта выпадающего списка). Сухой прогон с пустым fields откроет форму и вернёт отказ со списком обязательных полей и вариантов (неподдерживаемые варианты помечены) — так узнают, что выбирать; превью и previewToken выдаются, когда все обязательные поля заданы. Значения, которые форма подставила сама из личных данных ЕЛК, показываются только в ответе сухого прогона и уйдут в заявку как есть. Заказ необратим: отмены заявки в ЕЛК нет. Заполняются только выпадающие списки; обязательное поле другого типа, которое форма не заполнила сама, и варианты вида «…в дополнительном поле» отклоняются. За раз выполняется один заказ. Исход проверяется по заявкам «Сервиса Студент» со страницы «Заявки» (в elk_list_requests их нет): confirmed — после заказа появилась ровно одна новая заявка, её номер в ответе; иначе unknown, и newClaims: 0 не означает, что заказ не прошёл. При unknown сверяйте вручную на странице «Заявки» в lk.hse.ru и не повторяйте заказ без этой проверки. Новый источник проверки вживую с заказом ещё не проверялся.

Как пользоваться:

1. Сначала сухой прогон. Вызов без confirm ничего не отправляет: он читает страницу задания (для справки — форму) и показывает, что будет добавлено и заменено, предупреждения и previewToken.
2. Запись — тот же вызов с confirm: true и previewToken из сухого прогона. Токен действует 15 минут, одноразовый и привязан к заданию, режиму, файлам (по содержимому) и состоянию ответа: если что-то изменилось, нужен новый сухой прогон.
3. Не добавляйте тулы записи в автоматические разрешения клиента (в Claude Desktop — не выбирайте для них «Разрешать всегда»). Защита от случайной отправки держится на запросе разрешения клиента MCP перед каждым вызовом: сервер не может проверить, что человек на месте.
4. Исход проверяется чтением и бывает трёх видов: confirmed (подтверждено), rejected (система отказала, состояние не изменилось), unknown (проверить не удалось). После unknown не повторяйте отправку: откройте задание на сайте (для справки — страницу «Заявки» в lk.hse.ru) и посмотрите, что там на самом деле. Повторный вызов с тем же previewToken ничего не отправляет: для заданий он перепроверит результат чтением, а для справки не перепроверяет, а возвращает unknown с подсказкой сверить вручную. Новая запись по этой цели потребует acknowledgeUnknown: true. Для заказа справки rejected не выносится никогда.
5. Сохранение может сразу отправить работу на оценку: у заданий без отдельного шага «Отправить на оценку» draft этого не исключает. Шаг «Отправить на оценку» тул сам не выполняет. Просроченные и закрытые задания тул отклоняет.

Журнал записей лежит в writes/journal.json каталога данных (90 дней, не более 200 записей) и содержит только технические поля: без содержимого, имён файлов, названий и id курсов и заданий.

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

• SmartLMS и ЕЛК — общий Playwright-браузер (src/auth/browser-session.ts), который проходит единый SSO ВШЭ (Keycloak, saml.hse.ru, realm hse) и переиспользует сессию между вызовами (сохраняется в hse-session.json каталога данных). Браузер — скачанный Playwright Chromium, системный Edge или Chrome (src/auth/browser-launch.ts). ЕЛК даёт и JSON API с Authorization: Bearer <access_token> из localStorage (elk_get_schedule, elk_get_user_info, elk_search_services, elk_list_requests).
• istudy.hse.ru (зачётка) не поддерживается: тулы istudy_* удалены 2026-10-23. Вход проходит без MAX, но данные закрыты двухфакторным подтверждением через MAX (HTTP 412 на GET /api/auth/two-factor/required после клика по «Зачетная книжка»), а эндпоинты после 2FA неизвестны; обход 2FA не предусмотрен. Оценки по курсам — lms_get_grades.
• Сводки (my_today/my_week/my_deadlines) — агрегируют расписание ЕЛК, календарь Moodle, окна и уведомления ЕЛК в один JSON; статус каждого источника — в sources, отказ одного не роняет сводку. Холодный вызов после запуска сервера занимает ≈ 17 с (логин и открытие страниц), затем 3–4 с, повтор из кэша — мгновенно (замеры на одном аккаунте, 2026-10-14).
• Изменения (hse_changes) — «что изменилось», а не «что есть»: тул снимает дедлайны, расписание на 14 дней, входящее (письма LMS, уведомления ЕЛК) и заявки ЕЛК, сравнивает с прошлым снимком и возвращает только события (новое, изменено, пропало, перенесено, просрочено). Базы по источникам и журнал событий лежат в локальном changes/state.json каталога данных; сброс — hse_changes_reset (полный сброс удаляет и копии state.json.corrupt-*). Первый вызов по источнику только создаёт базу, без событий. Курсор двигается не сам, а параметром ack: передайте ackSeq из ответа в следующий вызов, иначе те же события вернутся снова (событие не теряется, даже если ответ не дошёл). Параметры: scopes (по умолчанию без оценок), courses (фильтр курсов для оценок: id или часть названия), fresh (перечитать источники, иначе принимаются данные не старше 60 с), since (журнал за период, например "7d", вместо неподтверждённого; since сам курсор не двигает, ack в том же вызове двигает). Оценки (scopes: ["grades"]) берутся только из журнала LMS и дорогие: страница на курс, десятки секунд. Тул только читает системы ВШЭ. Проверено вживую на одном аккаунте (спека §18); события added/changed/moved — только имитацией правки базы.

Границы применимости

• Селекторы и тексты Moodle (SmartLMS) и ЕЛК проверены на одном аккаунте и одном семестре; у других факультетов и курсов разметка может отличаться.
• Онлайн-текст в ответе на задание не поддерживается.
• Заданий с отдельным шагом «Отправить на оценку» и с классом статуса submissiondraft не наблюдалось: в таких случаях тулы записи отказывают, а не угадывают.
• Заказ справки проверен на форме одной справки.
• Правила ВШЭ об автоматизированном доступе к SmartLMS и ЕЛК не проверялись, пользователь отвечает за их соблюдение сам.

Известные ограничения

• Расписание в сводках — только из ЕЛК: если ЕЛК не ответил, в my_* будет ошибка источника elk_schedule без занятий (запасного пути через RUZ больше нет, RUZ — в hse-ruz-mcp и только из сети ВШЭ).
• ЕЛК частично разведан вживую (2026-09-15): известны разделы /task, /claim (теперь структурированно доступен через elk_list_requests), /service (поиск — elk_search_services), /schedule, /student-services, /faq. /student-services?section=documents содержит каталог заказа справок (зачётка, подтверждение обучения и т.п.) — форма разведана (Formily-конструктор поверх Element Plus); заказ идёт тулом elk_order_certificate (при HSE_ENABLE_WRITES=true). elk_open_page возвращает сырой текст + ссылки для остальных случаев. Подробные заметки разведки хранятся у автора локально и в репозиторий не входят.
• hse_changes: в ответе не более 200 событий (остаток — omitted: подтвердите ackSeq и вызовите снова); журнал хранит не более 500 событий, при переполнении невыданные теряются — счётчик gap.lostEvents. События считаются только в пересечении старого и нового окон (календарь −180…+60 дней, расписание 14 дней); при усечении календаря «пропало» не вычисляется. Виды событий по областям: дедлайны — новое, изменено, пропало, просрочено; расписание — новое, изменено, пропало, перенесено; входящее — только новое; заявки и оценки — новое и изменено (без «пропало»). «Пропало из календаря» не значит «сдано». «Итого за курс» — обычный элемент оценок: смена итога видна рядом с событием самого элемента.
• ЕЛК: запись только заказом справки (elk_order_certificate, HSE_ENABLE_WRITES=true); подача заявок (практика, стипендия, мобильность и т.п.) не реализована, остальные тулы ЕЛК только читают. Заказ справки выполнен вживую один раз на одном аккаунте: заказ дошёл, но исход тула — unknown (newClaims: 0), история заявок этих справок не видит; ручная проверка на странице «Заявки» подтвердила ровно одну новую заявку. Заказ необратим; свободный текст, даты, файлы и варианты «…в дополнительном поле» не поддерживаются (тул отказывает). Поля, которые форма дорисовывает после выбора варианта, сухой прогон не видит.
• Запись в SmartLMS (HSE_ENABLE_WRITES=true): только файлами, онлайн-текст не поддерживается. У заданий без отдельного шага «Отправить на оценку» сохранение сразу отправляет работу на оценку; сам шаг «Отправить на оценку» тул не выполняет. Просроченные и закрытые задания отклоняются, даже если поздняя сдача, возможно, ещё открыта. Задания с нераспознанным классом статуса сдачи отклоняются (статус «черновик» вживую не наблюдался). Существующий файл ответа и отправляемый файл крупнее 64 МиБ не принимаются: результат нельзя проверить. Проверено на одном аккаунте за один семестр.
• lms_open_page и elk_open_page отклоняют URL с параметром sesskey и страницы /mod/assign/ с параметром action: они читают, но не выполняют действий.

Разработка

• npm run build собирает проект в dist/, npm run dev — в режиме watch.
• npm run lint проверяет код линтером и форматтером Biome, npm run format исправляет то, что можно исправить автоматически.
• npm run pack:mcpb собирает пакет Claude Desktop в build/hse-mcp-<версия>.mcpb (CI делает то же и прикрепляет пакет к релизу).
• npm test собирает проект и запускает тесты node:test (test/*.test.mjs): сеть, браузер и учётные данные им не нужны. Среди них архитектурный тест: импорты должны соблюдать слои.

Как устроен код и куда добавлять новое — docs/architecture.md, правила участия — CONTRIBUTING.md.

Лицензия

MIT