# urfu-mcp

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

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

- Python 3.12 или новее и [`uv`](https://docs.astral.sh/uv/).
- Windows, WSL, Linux или macOS. Вход и запуск сервера должны выполняться в одной ОС: Windows Credential Manager и keyring WSL — разные хранилища.
- Chromium, устанавливаемый Playwright при необходимости браузерного входа.

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

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

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

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

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

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

| Инструмент | Аргументы и результат |
|---|---|
| `retrieve_user_schedule` | `date` либо `period_start` и `period_end` в формате `YYYY-MM-DD`; возвращает расписание текущего пользователя. Период включительный, одновременно передавать дату и период нельзя. |
| `retrieve_person_schedule` | Те же аргументы периода и ровно один из `person` или `persons`; для уточнения выбора доступны `person_selection` и `person_selections`. Возвращает `schedules` или список кандидатов, если требуется выбрать человека. Поиск людей проверен только на синтетических данных. |
| `retrieve_brs` | `subject_name` и обязательный `period`: `YYYY/YYYY — Осенний` либо `YYYY/YYYY — Весенний`. Имя выбирается точно; `subject_name="all"` возвращает все предметы за период. Результат включает разделы, баллы и веса. |
| `retrieve_courses_list` | Без аргументов; возвращает список записей курса с `course_id`, `name`, `short_name` и `progress_group`. |
| `retrieve_course_content` | `course`: числовой ID как строка или точное название курса; возвращает разделы курса с категориями `assignments`, `quizzes`, `materials`, `forums` и `other`. Типизированные поля могут включать срок задания, даты и лимит времени теста, размер материала и число обсуждений. |
| `retrieve_course_files` | `course`: ID или точное название; возвращает список файлов с `display_name`, `file_name`, `mime_type`, `size_bytes`, `modified_date`, `download_url` и `section_name`. Содержимое файлов не читается. |
| `retrieve_course_file` | `course` и `file_name` из списка `retrieve_course_files`; загружает один ранее перечисленный файл и возвращает его метаданные с абсолютным `saved_path`. |

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

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

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

```bash
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

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

| Команда | Назначение |
|---|---|
| `uv run urfu-mcp setup [--no-color] [--non-interactive]` | Настроить и проверить сервисы. |
| `uv run urfu-mcp init` | Создать `config.yaml` с безопасными значениями. |
| `uv run urfu-mcp auth` | Войти в Modeus и iStudent. |
| `uv run urfu-mcp auth login-saved` | Использовать сохранённые учётные данные для входа через SSO. |
| `uv run urfu-mcp auth credentials` | Сохранить почту и пароль в системном keyring. |
| `uv run urfu-mcp auth oidc` | Войти с OIDC-настройками из конфигурации. |
| `uv run urfu-mcp elearn` | Войти в eLearn. |
| `uv run urfu-mcp elearn login-saved` | Войти в eLearn с сохранёнными учётными данными. |
| `uv run urfu-mcp serve` | Запустить MCP-сервер по stdio для MCP-хоста. |
| `uv run urfu-mcp start` | Запустить управляемый серверный процесс. |
| `uv run urfu-mcp stop` | Остановить записанный управляемый процесс. |

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

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

`uv run urfu-mcp init` создаёт локальный `config.yaml`; пример всех параметров приведён в [`config.example.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](LICENSE).

## Ограничения

- Срок серверной сессии iStudent не гарантирован: локальная сессия ограничена 15 минутами, и сервер может отказать раньше.
- Проверка поиска людей для `retrieve_person_schedule` пока ограничена синтетическими данными.
- Файлы eLearn загружаются только по одному, если они предварительно перечислены; содержимое не возвращается инструментом списка.