mospolytech-mcp/README.md

# Mospolytech MCP

Наш учебный проект по дисциплине «Автоматизация процессов жизненного цикла
программных средств» (Московский Политех, гр. 241–327). Делаем MCP-сервер,
который даёт LLM-агенту (например, Claude) доступ к данным университета —
и к открытому справочнику (группы, расписание), и к личному кабинету
конкретного авторизованного пользователя (расписание, оценки, уведомления,
платежи, заявки, сообщения).

Команда — три человека:

- Деев Егор Викторович
- Шмыговский Никита Сергеевич
- Старков Руслан Владимирович

Официальное техническое задание, которое сдавали на лаб. №1 —
[`docs/official/lab01-tech-spec.pdf`](docs/official/lab01-tech-spec.pdf).
Наш рабочий план по всем 8 лабораторным (архитектура, черновая схема БД,
открытые риски) — [`docs/working/plan.md`](docs/working/plan.md). Подробнее
про то, как мы делим документацию на официальную и рабочую — в
[`docs/README.md`](docs/README.md).

## Что уже есть

Мы собрали обе половины университетского API в этот репозиторий и
объединили их в один объект `UniversityAPI`, чтобы MCP-серверу (и нам
самим) не приходилось таскать два клиента порознь:

```python
from mospolytech_mcp import UniversityAPI

async with UniversityAPI() as uni:
    groups = await uni.open.get_groups()          # открытые данные, без авторизации
    await uni.lk.login(login, password)             # а тут уже личный кабинет
    my_schedule = await uni.lk.get_my_schedule()
```

- **`open_api`** — открытые справочные данные университета. По ТЗ (ТПО-004)
  здесь используется готовая библиотека
  [mospolytech_api](https://github.com/r4nd0lph-c/mospolytech_api), а не
  наша реализация — мы завендорили её код как есть в `open_api/_vendor/` и
  сверху накрутили тонкую async-обёртку (`asyncio.to_thread`), чтобы она не
  блокировала event loop рядом с остальным асинхронным кодом.
- **`lk_api`** — личный кабинет. Тут по ТЗ (ТПО-005) наоборот: логику
  авторизации и работы с API переносим с существующей Go-библиотеки
  [MPU_LK_API](https://github.com/GODIMONGO/MPU_LK_API) на Python, своими
  руками. Сделали: логин/логаут/обновление токенов (обе системы — легаси
  token и JWT+refresh), расписание, успеваемость, платежи и договоры,
  заявки, уведомления и объявления, диалоги и (осторожно,
  неподтверждено — см. `docs/working/plan.md`) отправку сообщений.

Сам MCP-сервер (`server.py`) уже запускается и отвечает на первый
инструмент — `list_groups` (ФОД-001), через полный стек: протокол MCP →
`UniversityAPI.open` → кэш в PostgreSQL (`cache.py` + `db/`, миграции
Alembic в `alembic/`). Живьём проверяли: 592 группы забрались с
rasp.dmami.ru, записались в БД, второй вызов уже идёт из кэша. Остальные
инструменты (ФЛК-*, оставшиеся ФХД) дописываем по плану в
`docs/working/plan.md`, раздел 3.1.

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

- Python 3.14 (у нас работает через `py -3.14`)
- Доступ к PostgreSQL — свой пользователь `mospolytech_mcp` на общем сервере
  команды (не `postgres`/admin), спросите данные в чате, если не сохранили

## Быстрый старт

Если стоит GNU Make (на Windows — `choco install make`), всё поднимается
одной командой:

```powershell
make up
```

Она создаёт `.venv`, ставит зависимости, копирует `.env.example` в `.env`,
накатывает миграции и запускает сервер. На свежем клоне первый запуск
остановится с просьбой вписать `DATABASE_URL` в `.env` — впишите и
запустите `make up` ещё раз. Остальные команды (`make test`, `make migrate`,
`make run`, `make check-lk`, `make clean`) — в `make help`. Работает из
PowerShell, cmd и Git Bash, а также на Linux/macOS.

Ниже — то же самое руками, без make.

## Установка

```powershell
py -3.14 -m venv .venv
.venv\Scripts\pip install -e ".[dev]"
copy .env.example .env
# впишите DATABASE_URL (и MPU_LOGIN/MPU_PASSWORD, если нужен check_lk_api.py)
.venv\Scripts\alembic upgrade head
```

## Тесты

Всё, что не требует реального логина, покрыто офлайн-тестами — сеть не
трогаем, HTTP подменяем (`httpx.MockTransport` для `lk_api`, подмена
`requests.get` для `open_api`):

```powershell
.venv\Scripts\python -m pytest -q
```

## Проверка на реальном аккаунте

`open_api` не требует авторизации, поэтому его можно проверить вживую хоть
прямо сейчас (реальный запрос к rasp.dmami.ru, без секретов):

```powershell
.venv\Scripts\python -c "import asyncio; from mospolytech_mcp.open_api import OpenDataClient; asyncio.run(OpenDataClient().get_groups())"
```

Для `lk_api` нужен свой логин/пароль от e.mospolytech.ru — впишите
MPU_LOGIN и MPU_PASSWORD в свой `.env`, дальше `scripts/check_lk_api.py`
логинится и читает профиль, расписание, успеваемость, уведомления,
платежи, заявки и диалоги (ничего не меняет):

```powershell
.venv\Scripts\python scripts\check_lk_api.py
```

Пароль используется один раз при вызове `login()` и нигде не сохраняется.
`.env` в `.gitignore`, в репозиторий не попадёт.

## Запуск сервера

```powershell
.venv\Scripts\python -m mospolytech_mcp.server
```

Поднимается на stdio-транспорте — так подключается локальный MCP-клиент
(например, Claude Desktop/Code). Пока один инструмент, `list_groups`
(ФОД-001) — список групп с кэшем в БД на 15 минут.

## Структура репозитория

```
docs/
  official/       — официальные документы для сдачи (ТЗ и т.д.), PDF, не правим задним числом
  working/        — наш рабочий план, заметки, черновики — правим постоянно
  sdo/            — методички по всем 8 лабораторным и справочные ГОСТ/IEEE из СДО
src/mospolytech_mcp/
  api.py          — UniversityAPI, точка входа: держит open_api + lk_api вместе
  server.py       — сам MCP-сервер (регистрация tools)
  cache.py        — кэширующие обёртки над UniversityAPI, пишут в БД (ФХД-003)
  open_api/       — открытые данные (вендор mospolytech_api + наша async-обёртка)
  lk_api/         — личный кабинет (наш порт MPU_LK_API с Go на Python)
  db/             — модели SQLAlchemy (схема версионируется в alembic/)
alembic/          — миграции БД (alembic upgrade head накатывает схему)
tests/            — офлайн-тесты (pytest, без сети)
scripts/          — ручные проверочные скрипты (против реального ЛК)
```