urfu-mcp

Локальный MCP-сервер на Python для доступа к расписанию Modeus, балльно-рейтинговой системе iStudent и курсам eLearn УрФУ. Сервер работает через stdio и использует вход пользователя в сервисы университета.

Требования

• Python 3.12 или новее и uv.

• Windows, WSL, Linux или macOS. Вход и запуск сервера должны выполняться в одной ОС: Windows Credential Manager и keyring WSL — разные хранилища.

• Chromium, устанавливаемый Playwright при необходимости браузерного входа.

Проект запускается из клона репозитория; отдельный PyPI-пакет не публикуется.

Related MCP server: ntulearn-mcp

Установка и первый запуск

git clone https://github.com/be1pheg0r/urfu-mcp.git
cd urfu-mcp
uv run urfu-mcp setup

setup подготавливает окружение и конфигурацию, помогает войти и проверяет сессии Modeus и iStudent. Для первичной настройки также доступны отдельные команды init, auth и elearn (см. раздел CLI).

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

Сервер регистрирует семь инструментов.

Для содержимого курса селектор сверяется со списком записанных курсов; произвольный ID отклоняется, неоднозначное название не принимается, а страница курса должна подтвердить тот же ID. Загрузка файла принимает только файл, предварительно перечисленный для этого курса.

Подключение MCP-клиентов

Скрипт регистрирует stdio-сервер в Hermes, Codex или Claude, вызывая штатную команду mcp add выбранного клиента:

bash scripts/install-mcp.sh
bash scripts/install-mcp.sh --client codex
bash scripts/install-mcp.sh --client hermes --dry-run
bash scripts/install-mcp.sh --runtime native

Параметры: --client all|hermes|codex|claude, --runtime auto|windows|native, --name NAME, --dry-run. По умолчанию выбираются все найденные клиенты, а имя сервера — urfu-mcp. Регистрация запускает сервер из текущего клона; скрипт не оставляет фоновый процесс. После регистрации перезапустите клиент.

В WSL или Git Bash режим windows запускает Windows uv через cmd.exe; режим native использует uv текущей ОС. Windows Credential Manager и keyring WSL независимы: выполните uv run urfu-mcp setup и запускайте MCP-сервер в одной и той же ОС.

Команды CLI

Основные команды:

setup поддерживает --no-color и --non-interactive.

Конфигурация

uv run urfu-mcp init создаёт локальный config.yaml; пример всех параметров приведён в config.example.yaml. Конфигурация не содержит секретов или person_id. В ней, в частности, задаются OIDC-параметры, ограничения HTTP-запросов Modeus, часовой пояс и лимиты расписания. Каталог загрузки файлов настраивается через elearn.files_directory; по умолчанию используется ~/.urfu-mcp/files.

Безопасность и сессии

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

• Вход выполняется через SSO/браузер или настроенный OIDC. При недоверенных метаданных, ошибке проверки или неподдерживаемой конфигурации доступ закрывается.

• Доступ к файлу ограничен перечисленными файлами курса и точным HTTPS-origin elearn.urfu.ru. Размер ограничен, небезопасные имена отклоняются, существующие файлы не перезаписываются. Загрузка в Git working tree запрещена.

• Каталог файлов по умолчанию доступен только владельцу. Настроенный каталог также не может находиться внутри Git working tree.

• Локальный срок сессии iStudent ограничен 15 минутами.

• У сессии eLearn нет локального срока истечения; при каждом использовании она повторно проверяется по защищённой странице. Серверная сторона всё равно может отклонить сессию в любой момент.

Архитектура

• urfu_mcp/auth/ — вход через Playwright и OIDC/PKCE, хранение данных в keyring.

• urfu_mcp/modeus/ — HTTP-клиент Modeus, нормализация HAL и чтение расписания.

• urfu_mcp/istudent/ — источник защищённых страниц и парсер БРС.

• urfu_mcp/elearn/ — Moodle-источник курсов, парсер, чтение курса и загрузка файлов.

• urfu_mcp/setup.py, config.py, process_manager.py, html_tree.py — первичная настройка, конфигурация, управление процессом и HTML-структура.

Публичный репозиторий содержит только файлы, необходимые для установки и запуска приложения; разработческие тесты и проверки в него не входят. Поиск человека в retrieve_person_schedule пока проверен только на синтетических данных.

Лицензия

Проект распространяется по лицензии Apache-2.0.

Ограничения

• Срок серверной сессии iStudent не гарантирован: локальная сессия ограничена 15 минутами, и сервер может отказать раньше.

• Поиск людей в Modeus не поддерживает надёжную пагинацию: при очень широком запросе (например, одна буква) сервер возвращает повторяющиеся страницы, поэтому инструмент отказывается, а не отдаёт неполный список. Указывайте полное ФИО или его часть подлиннее.

• Файлы eLearn загружаются только по одному, если они предварительно перечислены; содержимое не возвращается инструментом списка.