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 HSE_EMAIL=login@edu.hse.ru -- npx -y hse-mcp

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

{
  "mcpServers": {
    "hse-mcp": {
      "command": "npx",
      "args": ["-y", "hse-mcp"],
      "env": { "HSE_EMAIL": "login@edu.hse.ru" }
    }
  }
}

Пароль в этот файл не пишите: он хранится открытым текстом. 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. HSE_PASSWORD в .env — запасной путь.

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), без значений и без email;
• 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/ сервер ограничивает владельцем (0o700 на POSIX, icacls с наследованием на Windows, чтобы новые файлы сразу создавались с ограниченными правами), а файлы hse-session.json и writes/key — 0o600 / icacls (ошибки при этом не выводятся).

Системное хранилище можно отключить целиком: HSE_DISABLE_KEYCHAIN=true (в окружении или .env) — для CI, серверов без графической сессии и Linux без Secret Service. npm test задаёт её сам, поэтому тесты не трогают настоящее хранилище.

Оговорки:

• Если @napi-rs/keyring не установился (npm ci --omit=optional, нет бинарника под платформу) или хранилище недоступно, проект молча работает дальше с .env, установка не падает.
• На Linux нужен запущенный Secret Service (GNOME Keyring, KWallet и т.п.; в сессии без графики часто его нет). Без него пакет ушёл бы в хранилище ядра keyutils, которое не переживает перезагрузку, поэтому в таком случае хранилище считается недоступным и остаётся .env. Эта проверка — синхронный вызов при старте; при заблокированной связке ключей или без D-Bus он может надолго задержать запуск, тогда задайте HSE_DISABLE_KEYCHAIN=true. Таймаута у вызова нет. Работа на Linux не проверялась.
• Защита рассчитана на случайную утечку и на чтение файлов другим пользователем системы, но не на вредоносную программу под вашим пользователем.

Если пароль или файлы каталога данных могли утечь: смените пароль ВШЭ (в .mcpb — и в настройках расширения), удалите hse-session.json и writes/key в каталоге данных (папка outbox/ и журнал записей — ваши данные), выполните npm run credentials:clear. Подробности и контакт для сообщений об уязвимостях — в SECURITY.md. Для публичного репозитория включите на GitHub secret scanning и push protection (по желанию — gitleaks в pre-commit; в зависимости проекта он не входит).

Тулы

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

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

Три тула записи (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