vklass-mcp

Ein mehrbenutzerfähiger, schreibgeschützter Model Context Protocol-Server für Vklass-Erziehungsberechtigte. Jeder Benutzer authentifiziert sein eigenes Vklass-Konto mit BankID im Rahmen des standardmäßigen MCP-OAuth-Flows. Jedes OAuth-Subjekt wird direkt auf eine Vklass-Benutzer-ID abgebildet; es gibt kein gemeinsames Login, kein globales MCP-Token und kein Administrator-Passwort.

Die MCP-Protokolloberfläche ist wie ein First-Party-Remote-MCP-Server gestaltet. Die Vklass-Integration ist zwangsläufig inoffiziell, da Vklass keine Vormund-API veröffentlicht; seine Web-Endpunkte können sich ändern.

MCP- und Identitätsmodell

• Ein Streamable-HTTP-Endpunkt: /mcp.

• OAuth-2.1-Autorisierungscode-Flow mit S256-PKCE.

• OAuth-Autorisierungsserver-Metadaten und RFC-9728-Metadaten für geschützte Ressourcen.

• Dynamische Client-Registrierung für kompatible MCP-Clients.

• Rotierende Zugriffs- und Aktualisierungstokens, Widerruf, Bereiche und RFC-8707-Ressourcenindikatoren.

• Die OAuth-Autorisierungsseite startet den Göteborg-Vklass-BankID-QR-Flow.

• Nach dem Login wird appData.userId von Vklass mithilfe des Zustandsschlüssels in ein stabiles, serverlokales pseudonymes OAuth-Subjekt umgewandelt; die rohe Vklass-Benutzer-ID wird nicht in OAuth-Grants gespeichert.

• Jedes Subjekt erhält seine eigene Vklass-Sitzung, seinen eigenen SQLite-Cache, seine eigenen Synchronisierungsaufgaben und sein eigenes verschlüsseltes Zustandsverzeichnis. Datenabfragen können niemals die Datenbank eines anderen Subjekts auswählen.

• Rohe OAuth-Zugriffs-/Aktualisierungs-/Code-Werte werden in SQLite SHA-256-gehasht. Registrierte Client-Metadaten, einschließlich Client-Geheimnissen, werden mit dem Server-Zustandsschlüssel verschlüsselt.

• Wenn die vorgelagerte Vklass-Sitzung abläuft, werden alle Grants für dieses Vklass-Subjekt widerrufen, sodass MCP-Clients einen standardmäßigen 401 erhalten und den BankID-Autorisierungsflow neu starten.

MCP-Clients verbinden sich nur mit:

https://vklass.example.com/mcp

Ein kompatibler Client entdeckt OAuth, öffnet den Browser, bittet den Benutzer, BankID zu genehmigen, und speichert seine eigenen Tokens. Verschiedene Benutzer und Clients verwenden dieselbe URL, erhalten jedoch unterschiedliche OAuth-Subjekte.

Der Server verwendet einen Scope mit geringsten Rechten, vklass.read, sowohl für zwischengespeicherte als auch für Live-schreibgeschützte Vklass-Abfragen.

Related MCP server: aula-mcp

Sicherheit

• Der Vklass-Zugriff ist schreibgeschützt. Abwesenheitsmeldungen, Urlaub, Nachrichten und andere Mutationen werden nicht bereitgestellt.

• Die BankID-Genehmigung wird immer vom Kontoinhaber in einem Browser durchgeführt.

• Vklass-Cookies und OAuth-Geheimnisse werden niemals über MCP oder Protokolle zurückgegeben.

• Göteborg-SAML- und BankID-Formular-/Weiterleitungshosts sind streng auf die Whitelist gesetzt.

• Vklass-Inhalte werden als nicht vertrauenswürdige Daten behandelt, niemals als Anweisungen.

• Der Container läuft ohne Root oder Capabilities und verwendet ein schreibgeschütztes Root-Dateisystem.

• Produktions-OAuth erfordert einen öffentlichen HTTPS-Ursprung. Der Container-Port bindet an Loopback für einen TLS-Reverse-Proxy und darf nicht direkt veröffentlicht werden.

Wenn dieser Dienst anderen Eltern angeboten wird, wird der Betreiber für personenbezogene Daten verantwortlich. Stellen Sie klare Aufbewahrungs-/Löschbedingungen, geschützte Backups, Incident-Handling und einen Betreiberkontakt bereit. Benutzer sollten auch verstehen, dass ihr MCP-Client Tool-Ergebnisse an seinen Modellanbieter senden kann.

Implementierte Vklass-Abdeckung

MCP-Tools

• 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

Lokale Entwicklung

Erfordert Python 3.12+ und 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

Verbinden Sie einen Entwicklungs-MCP-Client mit http://127.0.0.1:8000/mcp. Verwenden Sie HTTP nicht in einem LAN oder im Internet.

Podman und 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

Das Installationsprogramm erstellt nur ein Podman-Geheimnis: vklass-mcp-state-key. OAuth-Clients und Benutzer erstellen ihre eigenen Anmeldeinformationen über das Protokoll. Version 0.2 weigert sich bewusst zu starten, wenn veraltete Einzelbenutzer-vklass.db*- oder session.json.fernet-Dateien im Datenstamm verbleiben; migrieren Sie sie oder entfernen Sie den vollständigen veralteten Satz vor der Bereitstellung sicher.

Laufzeitpfade:

~/.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

Das Quadlet bindet 127.0.0.1:8787. Setzen Sie Caddy oder einen anderen TLS-Reverse-Proxy davor:

vklass.example.com {
    reverse_proxy 127.0.0.1:8787
}

Setzen Sie sowohl VKLASS_PUBLIC_BASE_URL=https://vklass.example.com als auch VKLASS_ALLOWED_HOSTS=vklass.example.com,localhost:*,127.0.0.1:*. Die öffentliche URL ist der OAuth-Aussteller und kann nicht geändert werden, ohne dass Clients erneut autorisieren müssen.

Damit der Benutzerdienst einen Logout übersteht:

loginctl enable-linger "$USER"

Öffentliche Bereitstellung über die Folksaga-Edge

deploy/folksaga/ zielt auf das vorhandene folksaga-Rootless-Podman-Konto auf perd.local. Es überträgt das lokal erstellte Image, installiert ein gehärtetes Quadlet im privaten folksaga-Netzwerk, erstellt einen gesicherten Zustandsschlüssel und startet den Dienst, ohne einen weiteren Host-Port zu veröffentlichen:

make build
./deploy/folksaga/deploy.sh

Die verfolgte Folksaga-Caddy-Konfiguration proxyt https://vklass.perapp.dev direkt an vklass-mcp:8000 und erhält ihr öffentliches Zertifikat über die vorhandenen Ports 80/443. DNS löst diesen Hostnamen bereits über perapp.dev auf. Sichern Sie sowohl /srv/folksaga/data/vklass-mcp/ als auch /srv/folksaga/secrets/vklass-mcp-state-key; der Verlust des Schlüssels trennt jeden Benutzer und macht verschlüsselte Sitzungen und OAuth-Client-Registrierungen unlesbar.

Betrieb

• Health: GET /healthz

• OAuth-Metadaten: GET /.well-known/oauth-authorization-server

• Metadaten der geschützten Ressource: GET /.well-known/oauth-protected-resource/mcp

• OAuth-Widerruf: POST /revoke

• SQLite- und verschlüsselte Sitzungen müssen zusammen mit dem Zustandsschlüssel gesichert werden.

• OAuth-Grants können über /revoke widerrufen werden; die lokale Datenlöschung ist derzeit eine operatorunterstützte Aktion, sodass ein MCP-Lese-Token keine destruktive Kontoverwaltung auslösen kann.

• BankID-Autorisierungstransaktionen sind absichtlich prozesslokal; führen Sie einen Anwendungs-Worker aus.

• Integrierte Rate-Limits pro Peer, globale Autorisierungslimits, gleichzeitige BankID-Slots und eine residente Dienstobergrenze bieten Sicherheitsnetze. Wenden Sie für die öffentliche Nutzung strengere verteilte Limits an der TLS-Edge an.

• Halten Sie den Zustandsschlüssel stabil und gesichert. Eine Rotation erfordert eine geplante Migration der verschlüsselten Client-Metadaten, Benutzersitzungen und pseudonymen OAuth-Subjekte; ein direkter Austausch trennt Benutzer.

Namensnennung

Der Göteborg-BankID-Flow ist aus dem MIT-lizenzierten Kaptensanders/vklass übernommen. Siehe THIRD_PARTY_NOTICES.md.