vklass-mcp

Многопользовательский сервер Model Context Protocol только для чтения для опекунов Vklass. Каждый пользователь аутентифицирует собственную учётную запись Vklass с помощью BankID в рамках стандартного потока OAuth MCP. Каждый субъект OAuth напрямую сопоставляется с одним идентификатором пользователя Vklass; общего входа, глобального токена MCP или пароля администратора не существует.

Поверхность протокола MCP спроектирована как собственный удалённый MCP-сервер. Интеграция с Vklass по необходимости неофициальна, поскольку Vklass не публикует API для опекунов; его веб-эндпоинты могут меняться.

MCP и модель идентификации

• Одна конечная точка Streamable HTTP: /mcp.

• Поток авторизации OAuth 2.1 с S256 PKCE.

• Метаданные сервера авторизации OAuth и метаданные защищённого ресурса RFC 9728.

• Динамическая регистрация клиентов для совместимых MCP-клиентов.

• Ротация access и refresh токенов, отзыв, области и индикаторы ресурсов RFC 8707.

• Страница авторизации OAuth запускает поток BankID QR Göteborg Vklass.

• После входа appData.userId из Vklass преобразуется в стабильный локальный псевдонимный субъект OAuth с помощью ключа состояния; исходный идентификатор пользователя Vklass не хранится в грантах OAuth.

• Каждый субъект получает собственную сессию Vklass, кэш SQLite, задачи синхронизации и зашифрованный каталог состояния. Запросы данных никогда не могут выбрать базу данных другого субъекта.

• Необработанные значения OAuth access/refresh/code хэшируются SHA-256 в SQLite. Метаданные зарегистрированных клиентов, включая секреты клиентов, шифруются ключом состояния сервера.

• Когда сессия Vklass истекает, все гранты для этого субъекта Vklass отзываются, чтобы MCP-клиенты получали стандартный 401 и перезапускали поток авторизации BankID.

MCP-клиенты подключаются только к:

https://vklass.example.com/mcp

Совместимый клиент обнаруживает OAuth, открывает браузер, просит пользователя одобрить BankID и сохраняет собственные токены. Разные пользователи и клиенты используют один и тот же URL, но получают разные субъекты OAuth.

Сервер использует одну область с минимальными привилегиями, vklass.read, как для кэшированных, так и для живых запросов Vklass только для чтения.

Related MCP server: jisr-mcp

Безопасность

• Доступ к Vklass только для чтения. Отчёты об отсутствии, отпуска, сообщения и другие изменения не раскрываются.

• Одобрение BankID всегда выполняется владельцем учётной записи в браузере.

• Файлы cookie Vklass и секреты OAuth никогда не возвращаются через MCP или журналы.

• Хосты форм/редиректов Göteborg SAML и BankID строго внесены в белый список.

• Содержимое Vklass рассматривается как ненадёжные данные, а не как инструкции.

• Контейнер работает без root или capabilities и использует read-only корневую файловую систему.

• Для продакшн-режима OAuth требуется публичный HTTPS-источник. Порт контейнера привязан к loopback для TLS-обратного прокси и не должен публиковаться напрямую.

Если этот сервис предлагается другим родителям, оператор несёт ответственность за персональные данные. Предоставьте чёткие условия хранения/удаления, защищённые резервные копии, обработку инцидентов и контакт оператора. Пользователи также должны понимать, что их MCP-клиент может отправлять результаты инструментов своему провайдеру модели.

Реализованное покрытие Vklass

MCP-инструменты

• vklass_capabilities, vklass_status, vklass_sync_now

• vklass_list_children

• vklass_list_weekly_letters, vklass_get_weekly_letter

• vklass_list_news, vklass_get_news_article

• vklass_list_calendar, vklass_list_assignments, vklass_list_care_schedule

• vklass_list_automatic_weekly_reports

• vklass_get_meals, vklass_get_notifications

• vklass_list_study_courses, vklass_get_feature_snapshot, vklass_search

Локальная разработка

Требуется Python 3.12+ и uv.

cp .env.example .env
# For localhost only:
sed -i 's#https://vklass.example.com#http://127.0.0.1:8000#' .env
sed -i 's#VKLASS_STATE_KEY_FILE=.*#VKLASS_STATE_KEY=development-state-key-change-me#' .env
uv sync --all-groups
uv run pytest
uv run vklass-mcp

Подключите клиент разработки MCP к http://127.0.0.1:8000/mcp. Не используйте HTTP в локальной сети или интернете.

Podman и systemd

make build
make install-quadlet
$EDITOR ~/.config/vklass-mcp/server.env
systemctl --user start vklass-mcp.service
journalctl --user -u vklass-mcp.service -f

Установщик создаёт только один секрет Podman: vklass-mcp-state-key. Клиенты и пользователи OAuth создают свои собственные учётные данные через протокол. Версия 0.2 намеренно отказывается запускаться, если в корне данных остаются устаревшие однопользовательские файлы vklass.db* или session.json.fernet; перенесите их или безопасно удалите весь устаревший набор перед развёртыванием.

Расположение во время выполнения:

~/.config/vklass-mcp/server.env
~/.local/share/vklass-mcp/oauth.db
~/.local/share/vklass-mcp/users/<sha256-of-vklass-user-id>/
~/.config/containers/systemd/vklass-mcp.container

Quadlet привязывается к 127.0.0.1:8787. Поместите Caddy или другой TLS-обратный прокси перед ним:

vklass.example.com {
    reverse_proxy 127.0.0.1:8787
}

Установите оба значения VKLASS_PUBLIC_BASE_URL=https://vklass.example.com и VKLASS_ALLOWED_HOSTS=vklass.example.com,localhost:*,127.0.0.1:*. Публичный URL является издателем OAuth и не может быть изменён без повторной авторизации клиентов.

Чтобы пользовательский сервис пережил выход из системы:

loginctl enable-linger "$USER"

Публичное развёртывание через edge Folksaga

deploy/folksaga/ нацелен на существующую учётную запись rootless Podman folksaga на perd.local. Он передаёт локально собранный образ, устанавливает усиленный Quadlet в частной сети folksaga, создаёт резервную копию ключа состояния и запускает сервис без публикации дополнительного порта хоста:

make build
./deploy/folksaga/deploy.sh

Отслеживаемая конфигурация Caddy Folksaga проксирует https://vklass.perapp.dev напрямую на vklass-mcp:8000 и получает публичный сертификат через существующие порты 80/443. DNS уже разрешает этот хост через perapp.dev. Сделайте резервные копии как /srv/folksaga/data/vklass-mcp/, так и /srv/folksaga/secrets/vklass-mcp-state-key; потеря ключа отключает всех пользователей и делает зашифрованные сессии и регистрации OAuth-клиентов нечитаемыми.

Операции

• Здоровье: GET /healthz

• Метаданные OAuth: GET /.well-known/oauth-authorization-server

• Метаданные защищённого ресурса: GET /.well-known/oauth-protected-resource/mcp

• Отзыв OAuth: POST /revoke

• SQLite и зашифрованные сессии должны резервироваться вместе с ключом состояния.

• Гранты OAuth можно отозвать через /revoke; локальное удаление данных в настоящее время является действием, поддерживаемым оператором, поэтому токен чтения MCP не может запускать деструктивное управление учётной записью.

• Транзакции авторизации BankID намеренно локальны для процесса; запускайте один рабочий процесс приложения.

• Встроенные ограничения скорости на одноранговый узел, глобальные ограничения авторизации, одновременные слоты BankID и ограничение резидентного сервиса обеспечивают защиту. Применяйте более строгие распределённые ограничения на TLS-границе для публичного использования.

• Держите ключ состояния стабильным и резервированным. Ротация требует плановой миграции зашифрованных метаданных клиентов, пользовательских сессий и псевдонимных субъектов OAuth; его прямая замена отключает пользователей.

Атрибуция

Поток Göteborg BankID адаптирован из Kaptensanders/vklass под лицензией MIT. См. THIRD_PARTY_NOTICES.md.