# MyIIS MCP Server

<p align="center">
  <img src="./assets/icon-256.png" alt="MyIIS Logo" width="120" height="120" style="border-radius: 24px;" />
</p>

<p align="center">
  <strong>Официальный Model Context Protocol (MCP) сервер расписания занятий ИИС БГУИР для ChatGPT, Claude и Cursor.</strong>
</p>

<p align="center">
  <a href="https://github.com/OrDinaD/myiis-mcp/actions"><img src="https://img.shields.io/badge/tests-14%20passed-brightgreen.svg" alt="Tests" /></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.13-blue.svg" alt="Python 3.13" /></a>
  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-2024--11--05-purple.svg" alt="MCP Spec" /></a>
  <a href="https://workers.cloudflare.com/"><img src="https://img.shields.io/badge/Cloudflare-Python%20Workers-orange.svg" alt="Cloudflare Workers" /></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License" /></a>
</p>

---

## 🚀 Быстрый старт: подключение в ChatGPT за 30 секунд

Сервер уже задеплоен и круглосуточно работает в **Cloudflare Workers**. Вам не нужно ничего скачивать или запускать локально.

### Пошаговая инструкция:

1. Откройте [chatgpt.com](https://chatgpt.com) (требуется подписка Plus, Team или Pro).
2. Перейдите в **Settings** (Настройки) → **Security and login** → включите тумблер **Developer mode**.
3. Перейдите по ссылке **[chatgpt.com/plugins](https://chatgpt.com/plugins)** и нажмите кнопку **`+`** (Добавить плагин).
4. Заполните поля:
   - **Имя:** `MyIIS`
   - **Описание:** `Расписание занятий, группы и преподаватели БГУИР через официальный API ИИС.`
   - **Тип подключения:** выберите **URL**.
   - **URL сервера:**
     ```text
     https://myiis-mcp.vlad-vasilevskiy-07.workers.dev/mcp
     ```
5. Нажмите **Подключить** (*Connect*).
6. В ChatGPT переключите режим диалога на **Work** (Режим работы), введите символ **`@`**, выберите **`MyIIS`** и задайте любой вопрос по расписанию!

---

## 💬 Примеры запросов к ChatGPT

После подключения вы можете общаться с моделью на естественном русском языке:

- 📅 **Расписание на сегодня / завтра:**
  > «@MyIIS какое расписание у группы 420-603 на сегодня?»  
  > «@MyIIS покажи расписание на завтра для 1-й подгруппы группы 310101»

- 🗓 **Расписание на всю неделю:**
  > «@MyIIS расскажи, какое расписание у группы 420603 на эту неделю?»

- 👨‍🏫 **Расписание и поиск преподавателя в корпусах:**
  > «@MyIIS где я завтра могу найти Лаппо?» *(сервер подскажет пары, аудитории и кабинет кафедры даже при опечатке)*  
  > «@MyIIS покажи расписание занятий преподавателя Васильковой на понедельник»

- 📇 **Контакты и профиль преподавателя:**
  > «@MyIIS какая почта у Герман, которая ведет у нас мобильную разработку?»  
  > «@MyIIS какие предметы ведет Лаппо и в каком кабинете его кафедра?»  
  > «@MyIIS найди научные публикации и страницу в репозитории БГУИР преподавателя Василькова»

- 🔍 **Поиск групп и кафедр:**
  > «@MyIIS найди группы 4 курса факультета ФКП по специальности ИСиТ»  
  > «@MyIIS кто преподает на кафедре ИТАС?»

- ℹ️ **Текущая учебная неделя:**
  > «@MyIIS какая сейчас учебная неделя в БГУИР?»

---

## 🛠 Доступные MCP Tools

Сервер реализует 6 специализированных инструментов (tools) протокола MCP. Все инструменты имеют строгие аннотации безопасности `readOnlyHint: true` (не производят деструктивных действий и изменений данных).

| Инструмент | Описание | Основные параметры |
|------------|----------|-------------------|
| `get_group_schedule` | Получить расписание занятий группы БГУИР на конкретный день, диапазон дней или всю неделю | `group` *(str, обязательный)*: номер группы (например, `'420603'`)<br>`date` *(str, опц.)*: `'today'`, `'tomorrow'` или `'ГГГГ-ММ-ДД'`<br>`days` *(int, опц.)*: кол-во дней (1–14)<br>`subgroup` *(int, опц.)*: номер подгруппы (`1` или `2`) |
| `get_teacher_schedule` | Получить расписание занятий преподавателя (пары, аудитории, корпус, контакты кафедры) с автоисправлением опечаток | `teacher` *(str, обязательный)*: фамилия, ФИО или urlId (например, `'Лаппо'`, `'лапо'`, `'a-lappo'`)<br>`date` *(str, опц.)*: дата фильтрации (`'today'`, `'tomorrow'`)<br>`days` *(int, опц.)*: кол-во дней |
| `get_teacher_profile` | Получить полную карточку преподавателя: email, телефон кафедры, кабинет/аудиторию, читаемые курсы, ссылки на репозиторий публикаций БГУИР | `teacher` *(str, обязательный)*: фамилия, ФИО или urlId (например, `'Герман'`, `'Лаппо'`, `'iu-german'`) |
| `render_schedule_widget` | Явный вызов интерактивного визуального UI-виджета (ChatGPT Apps SDK / MCP Apps) с карточкой расписания или профиля преподавателя | `group` *(str, опц.)*: номер группы<br>`teacher` *(str, опц.)*: фамилия преподавателя<br>`date` *(str, опц.)*: `'today'`, `'tomorrow'` |
| `search_groups` | Поиск учебных групп по номеру, специальности или факультету | `query` *(str, обязательный)*: поисковый запрос (например, `'310101'` или `'ИСиТ'`)<br>`course` *(int, опц.)*: номер курса (1–5)<br>`faculty` *(str, опц.)*: аббревиатура факультета (`'ФКП'`, `'ФКСиС'`) |
| `search_teachers` | Поиск преподавателей по фамилии, имени или названию кафедры | `query` *(str, обязательный)*: фамилия или имя преподавателя (с поддержкой токенов и опечаток)<br>`department` *(str, опц.)*: название или аббревиатура кафедры |
| `get_current_week` | Получить текущую учебную неделю университета (1–4) и дату | *Параметры не требуются* |

> 🎨 **Интерактивный UI-виджет:** Все инструменты расписания и профилей автоматически содержат метаданные `_meta.ui.resourceUri: "ui://bsuir/widget.html"` по спецификации **ChatGPT Apps SDK** (на базе открытого стандарта MCP Apps). В клиентах с поддержкой UI (ChatGPT) прямо внутри чата рендерится аккуратный адаптивный виджет с фото преподавателя, интерактивными ссылками на расписание, телефонными кнопками и статусом учебной недели.


---

## 📋 Структура и формат ответа

Сервер нормализует "сырые" данные ИИС БГУИР в компактную и строго структурированную модель, оптимизированную для контекстного окна LLM:

```json
{
  "target": "Группа 420603",
  "target_type": "group",
  "current_week": 2,
  "summary": "Расписание для Группа 420603 на 2026-09-07: найдено 3 занятия.",
  "query_date": "2026-09-07",
  "days": [
    {
      "day_of_week": "Понедельник",
      "date": "2026-09-07",
      "week_number": 2,
      "lessons": [
        {
          "subject": "СтатМОД",
          "subject_full_name": "Статистическое моделирование",
          "lesson_type": "ЛР",
          "start_time": "17:05",
          "end_time": "18:30",
          "day_of_week": "Понедельник",
          "date": "2026-09-07",
          "week_numbers": [2, 4],
          "subgroup": 2,
          "auditories": ["6016-5 к."],
          "building": "5",
          "teachers": ["Иванов И. И."],
          "groups": ["420603"],
          "note": null
        }
      ]
    }
  ],
  "total_lessons": 3
}
```

### Особенности обработки расписания:
- **4-недельный цикл БГУИР**: сервер автоматически сопоставляет дату и номер учебной недели (1, 2, 3 или 4), отфильтровывая занятия, которых нет на текущей неделе.
- **Подгруппы**: корректно разделяет общие пары (`subgroup: 0`) и пары по подгруппам (`1` или `2`).
- **Аудитории и корпуса**: автоматически извлекает номер корпуса из названия аудитории (например, `'104-3 к.'` → корпус `3`).

---

## 🔌 Подключение в другие MCP-клиенты

### Claude Desktop
Добавьте в ваш `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "myiis": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://myiis-mcp.vlad-vasilevskiy-07.workers.dev/mcp"
      ]
    }
  }
}
```

### Cursor IDE
Создайте файл `.cursor/mcp.json` в вашем проекте:
```json
{
  "mcpServers": {
    "myiis": {
      "url": "https://myiis-mcp.vlad-vasilevskiy-07.workers.dev/mcp"
    }
  }
}
```

---

## 🌐 Публичные эндпоинты

- **MCP Endpoint (Streamable HTTP / SSE):**
  ```text
  POST /mcp — JSON-RPC 2.0 (initialize, tools/list, tools/call)
  GET  /mcp — SSE Handshake (Accept: text/event-stream)
  ```
- **Healthcheck & University Status:**
  ```text
  GET /health — проверяет статус воркера, доступность API БГУИР и текущую неделю
  ```
- **Discovery Root:**
  ```text
  GET / — общая информация о сервере, версия и доступные роуты
  ```

---

## 💻 Локальная разработка и тестирование

```bash
# Клонирование репозитория
git clone https://github.com/OrDinaD/myiis-mcp.git
cd myiis-mcp

# Создание виртуального окружения и установка зависимостей
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Запуск тестов (14 тестов: парсинг, расчет недель, MCP handshake)
uv run pytest

# Локальный запуск dev-сервера через Cloudflare Pyodide runtime
uv run pywrangler dev --port 8787
```

---

## 📄 Лицензия и авторство

- **Лицензия:** [MIT License](./LICENSE). Свободно для использования, модификации и распространения.
- **Автор:** [Vladislav Vasilevskiy](https://github.com/OrDinaD).
- **Источник данных:** открытый API Интегрированной Информационной Системы БГУИР — [iis.bsuir.by/api](https://iis.bsuir.by/api).