mirror of
https://github.com/EDeev/mospolytech-mcp.git
synced 2026-10-08 04:59:47 +03:00
169 lines
9.5 KiB
Markdown
169 lines
9.5 KiB
Markdown
# 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 минут.
|
||
|
||
### HTTP-режим
|
||
|
||
Если сервер крутится в VM или на другой машине, stdio не подходит —
|
||
есть HTTP-режим (streamable HTTP, эндпоинт `/mcp`):
|
||
|
||
```bash
|
||
make run-http # 0.0.0.0:8000
|
||
make run-http PORT=9000 # HOST и PORT можно переопределить
|
||
```
|
||
|
||
Без make: `python -m mospolytech_mcp.server --http --host 0.0.0.0 --port 8000`.
|
||
|
||
В Postman: New → MCP, транспорт HTTP, URL `http://<адрес VM>:8000/mcp`,
|
||
Connect — в списке инструментов появится `list_groups`, его можно вызвать
|
||
прямо оттуда. Авторизации на сервере нет, так что наружу (`0.0.0.0`)
|
||
открывать только на тестовой машине.
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
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/ — ручные проверочные скрипты (против реального ЛК)
|
||
```
|