kfu-itis
Retrieves group schedules from a Google Sheets timetable, including class times, instructors, rooms, and merged-cell lectures.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ИТИС Навигатор · MCP Demo
Локальное приложение для вопросов об ИТИС Казанского федерального университета. В чате можно открыть расписание конкретной группы: карточки пар, время, преподаватели, аудитории, выбор группы и переключение дней недели. Поиск по текстовым документам работает через MCP и PostgreSQL. OpenRouter можно подключить для ответов модели и дополнения поиска данными с официальных страниц КФУ.
Быстрый запуск
Нужны Node.js 22.13 или новее и npm. Команды выполняются в терминале:
git clone https://github.com/GreenSLA/MCP-Demo.git
cd MCP-Demo
npm ci
npm run devОткройте http://127.0.0.1:3000. Держите терминал открытым; остановка — Ctrl+C.
npm start запускает то же локальное приложение. Порты 3000, 8788 и 55432
должны быть свободны. Приложение поднимает свой PostgreSQL на loopback. Для уже
работающего PostgreSQL задайте DATABASE_URL перед запуском.
В Windows команды подходят для PowerShell. На macOS после установки зависимостей также
можно открыть Запустить.command двойным щелчком (при необходимости chmod +x Запустить.command).
Аккаунты, диалоги и память
Создайте локальный аккаунт на экране входа. Логин состоит из латинских букв, цифр, точек, дефисов и подчёркиваний. Пароли в учебной версии хранятся открытым текстом. Используйте отдельный демонстрационный пароль.
Истории диалогов остаются в PostgreSQL на семь дней после последней записи. Напишите «Запомни группу 11-401», подтвердите кнопкой «Да», затем в новом диалоге спросите «Какие у меня пары?». Поддерживаются группа, курс и предмет из списка. Подтверждение одноразовое, привязано к исходному диалогу и действует десять минут. Факты хранятся 180 дней. Команда «Забудь» с подтверждением удаляет диалоги и факты аккаунта.
Регистрация создаёт роль студента. Роль преподавателя назначается оператором
PostgreSQL через поле app_users.role. Команда «Вызови инструмент deadlines»
доступна преподавателю и ищет официальные материалы о сроках.
Пять стартовых текстов загружаются в таблицу documents. search_docs использует
полнотекстовый поиск PostgreSQL по одобренным документам и исключает истёкшие
версии. Без ключа чат показывает найденные выдержки со ссылками. Отдельного
индекса эмбеддингов в этой версии нет.
Расписание — без ключа и облачной модели
Работает сразу после запуска, в том числе без интернета. Нажмите «Расписание группы» или напишите:
«Покажи расписание 11-401»;
«Какие пары у 11-402 в понедельник?»;
«Расписание 11-401 на завтра»;
«Расписание» — приложение предложит выбрать группу.
В ответе откроется интерактивная карточка. Выберите другую группу или день недели. Время, названия предметов и остальные сведения отображаются из данных таблицы без пересказа LLM. Общие лекции из объединённых ячеек включаются во все соответствующие группы.
Основной источник — актуальная Google-таблица. При запуске MCP-сервер загружает её через публичный экспорт XLSX, разбирает библиотекой ExcelJS и затем автоматически проверяет обновления с интервалом около 5 минут, даже если никто не задаёт вопросы. Серверный таймер проверяет срок кэша каждые 30 секунд; после сбоя повторяет попытку через 30 секунд. Одновременные запросы используют одну загрузку. Открытые карточки в видимой вкладке запрашивают текущие данные сервера раз в минуту.
Последняя успешная загрузка сохраняется атомарно в data/timetable-cache.json
(файл исключён из Git) и используется после перезапуска. Если интернет недоступен,
показывается эта копия с предупреждением и датой последней успешной загрузки.
server/data/timetable.json используется только как аварийный резерв, если новой
копии на диске ещё нет. Пустая или повреждённая таблица не заменяет рабочие данные.
Дата загрузки не гарантирует, что сам составитель таблицы внёс все изменения.
Кнопка «Обновить из таблицы» запускает принудительную загрузку один раз в день на аккаунт по московскому времени. Повторное нажатие возвращает сохранённое расписание. Фоновый таймер обновляет данные по своему интервалу. Для ручного обновления дискового кэша:
npm run schedule:updateПерезапуск для регулярных обновлений не нужен. Пока приложение закрыто, таймер не работает; при следующем запуске сервер снова проверит источник. Ключ Google API, OpenRouter или нейросеть для загрузки расписания не нужны. Исходная таблица не редактируется.
Чтобы изменить интервал, передайте переменную окружения при запуске (в миллисекундах):
SCHEDULE_REFRESH_INTERVAL_MS=60000 npm run devПосле изменения настроек интервала перезапустите сервер. Минимум — 1000 мс.
Общие вопросы — подключение OpenRouter
Создайте ключ на https://openrouter.ai/settings/keys.
В приложении нажмите «Нужен API-ключ», вставьте ключ, выберите модель и сохраните.
Задайте вопрос, например «Как связаться с ИТИС?» или «Какие компании сотрудничают с ИТИС?».
Ключ сохраняется только в локальном .env. Его значение не возвращается браузеру
при чтении настроек и не включается в Git. Для платной модели нужен баланс OpenRouter;
бесплатный вариант есть в настройках, но возможны ограничения и очереди.
Вместо настройки через интерфейс можно скопировать .env.example в .env и заполнить:
OPENROUTER_API_KEY=YOUR_OPENROUTER_KEY
OPENROUTER_MODEL=google/gemini-2.5-flashНе добавляйте настоящий ключ в README, исходники или коммиты.
Related MCP server: MyIIS MCP Server
Архитектура
React-интерфейс → локальный Node.js API
│
┌────────┴────────┐
│ │
Вопрос о парах Общий вопрос
│ ↕
Разбор группы OpenRouter → LLM
и дня │ tool calling
└────────┬────────┘
↓
MCP-клиент
↕ JSON-RPC / stdio
Отдельный MCP-сервер
┌───────────┼───────────────────┐
search_kfu read_kfu_page get_group_schedule
↓ ↓ ↓
Сайты КФУ Страница КФУ Копия / Google SheetsMCP реализован официальным @modelcontextprotocol/sdk, включая обнаружение инструментов
через listTools, вызовы callTool и ресурс itis://about. Это отдельный процесс,
к которому можно подключить сторонний MCP-клиент. Нейросеть не обучалась.
Файл | Назначение |
| Три MCP-инструмента и ресурс |
| Цикл модели, вызовов инструментов и результатов |
| HTML КФУ, кодировки, лексический поиск, кэш |
| Разбор таблицы, объединённых ячеек и дней |
| Автообновление, срок кэша и восстановление после сбоев |
| Распознавание запросов расписания без LLM |
| Локальный HTTP API и настройка ключа |
| Карточки пар и переключатели |
| Чат, настройки и журнал MCP |
Подключение к другому MCP-клиенту
Установите зависимости и укажите абсолютные пути в конфигурации клиента:
{
"mcpServers": {
"kfu-itis": {
"command": "node",
"args": ["/absolute/path/MCP-Demo/server/mcp-server.mjs"]
}
}
}Самому MCP-серверу ключ OpenRouter не нужен. Модель предоставляет выбранный клиент.
Проверка
npm test # извлечение, объединения, маршрутизация, агентный цикл
npx tsc --noEmit # проверка TypeScript
npm run build # сборка интерфейса
npm run check:mcp # настоящий MCP и поиск по КФУ; нужен интернетДля демонстрации запускайте npm run dev, а не отдельно артефакты сборки:
приложению нужны одновременно интерфейс и Node.js API. Публичное развёртывание не настроено.
Ограничения и источники
«Сегодня/завтра» вычисляются по Москве. Показывается шаблон дня недели; каникулы, чётность учебной недели и отмены автоматически не вычисляются. Все условия из ячеек остаются в тексте занятий.
Расписание охватывает предоставленную таблицу, а не произвольные группы университета. Изменение структуры таблицы может потребовать обновления парсера.
Поиск по КФУ — ограниченный корпус HTML и релевантные ссылки, без векторной базы. PDF, закрытые личные кабинеты и JavaScript-страницы не извлекаются.
Общие ответы модели могут содержать ошибки; проверяйте ссылки. Приложение предназначено для локального использования.
Источники: сайт ИТИС, расписание Google Sheets. Шпаргалка для демонстрации: ЗАЩИТА.md.
Эксперименты с токенами и температурой
Отчёт с результатами: сравнение русского и английского,
переполнение контекста Qwen в Ollama, четыре температуры, расход реального MCP-агента
и прогноз на студента в день. Исходные ответы API — в experiments/results/.
node experiments/run.mjs local # Ollama, установленная qwen3.5:9b
node experiments/run.mjs cloud # OpenRouter, ключ из .env; платные вызовы
node experiments/analyze.mjs # сводка без сетиПовторный запуск перезаписывает результаты выбранного режима. Перед ним сохраните копию результатов, если нужно оставить исходные замеры. Настройки и ограничения эксперимента описаны в отчёте; интерфейс приложения менять не нужно.
Практика E1–E5: качество ответов
Готовые материалы для сдачи:
Системный промпт и три пары примеров находятся в prompts/. Общие ответы
приложения проходят проверку JSON в server/answer.mjs: один повтор при ошибке,
затем честный запасной ответ. Прямое расписание продолжает возвращаться из данных.
Реальные измерения выполнены на локальной qwen3.5:9b через Ollama.
Для повторения с установленной и запущенной Ollama:
node eval/run.mjs v0
node eval/run.mjs v1
node eval/run.mjs system-only
node eval/run.mjs validated
node eval/analyze.mjsСохранённые результаты уже входят в репозиторий. Скрипт продолжает только отсутствующие
записи и не смешивает разные конфигурации. Для нового эксперимента сначала сохраните
копию eval/results/; разметку после нового прогона нужно проверить заново.
Сравнение изолирует формирование ответа по фиксированным результатам MCP,
а не автономный выбор инструментов. Методика и ограничения описаны в отчёте.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote MCP for TehProf Booking: browse resources & availability, create & cancel reservations.
Search and manage your team's knowledge from MCP clients.
Unofficial SerpApi MCP — wraps SerpApi (serpapi.com) search engines
Web and URL utilities over MCP: shorten URLs, screenshot pages, read page metadata, encode URLs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables querying academic data such as subjects, degrees, locations, and schedules from Universitat Jaume I via MCP tools.MIT
- AlicenseAqualityBmaintenanceProvides LLM clients with real-time access to BSUIR class schedules, academic weeks, student groups, and teachers through a read-only MCP interface, enabling natural-language queries about lessons and timetable information.22MIT
- FlicenseNot gradedqualityCmaintenanceEnables users to search for information about the Institute of Fundamental Medicine and Biology at KFU and retrieve academic group schedules. It uses OpenRouter to understand natural-language questions and automatically invoke MCP tools.1-
- AlicenseNot gradedqualityCmaintenanceProvides MCP tools to fetch and filter schedules for groups, teachers, and rooms from VSUET's timetable site, with support for JSON or text output.MIT