vklass-mcp

複数ユーザー対応の読み取り専用 Model Context Protocol サーバー。Vklass の保護者向け機能を提供します。各ユーザーは標準の MCP OAuth フローを通じて、自身の Vklass アカウントで BankID 認証を行います。各 OAuth サブジェクトは 1 つの Vklass ユーザー ID に直接対応します。共有ログイン、 グローバルな MCP トークン、管理者パスワードは存在しません。

MCP プロトコル面は、ファーストパーティのリモート MCP サーバーとして設計されています。Vklass 連携は 非公式です。Vklass は保護者向け API を公開していないため、その Web エンドポイントは変更される可能性があります。

MCP と ID モデル

• ストリーミング HTTP エンドポイント: /mcp。

• OAuth 2.1 認可コード フロー + S256 PKCE。

• OAuth 認可サーバーメタデータと RFC 9728 保護リソースメタデータ。

• 互換性のある MCP クライアント向け動的クライアント登録。

• ローテーション付きアクセストークン / リフレッシュトークン、失効、スコープ、RFC 8707 リソースインジケータ。

• OAuth 認可ページで Göteborg の Vklass BankID QR フローが開始されます。

• ログイン後、Vklass の appData.userId は、state キーを用いて安定したサーバーローカルな仮名 OAuth サブジェクトに変換されます。生の Vklass ユーザー ID は OAuth 認可情報として保存されません。

• 各サブジェクトは独自の Vklass セッション、SQLite キャッシュ、暗号化された state ディレクトリを持ちます。データクエリが他のサブジェクトのデータベースにアクセスすることはできません。

• 生の OAuth アクセストークン / リフレッシュトークン / 認可コードは SQLite 内で SHA-256 ハッシュ化されます。 登録済みクライアントメタデータ（クライアントシークレットを含む）は、サーバーの state キーで暗号化されます。

• 上流の Vklass セッションが期限切れになると、その Vklass サブジェクトに関連するすべての認可情報が失効し、 MCP クライアントは標準の 401 応答を受け取り、BankID 認可フローを再開します。

MCP クライアントは以下にのみ接続します:

https://vklass.example.com/mcp

互換性のあるクライアントは OAuth を検出し、ブラウザを開き、ユーザーに BankID の承認を求め、自身の トークンを保存します。異なるユーザーやクライアントは同じ URL を使用しますが、異なる OAuth サブジェクトを受け取ります。

サーバーは、キャッシュおよびライブの読み取り専用 Vklass クエリの両方に対して、最小権限のスコープ vklass.read を 1 つだけ使用します。

Related MCP server: jisr-mcp

セキュリティ

• Vklass アクセスは読み取り専用です。欠席報告、連絡、メッセージ、その他の変更操作は公開されません。

• BankID の承認は、常にアカウント所有者がブラウザ上で行います。

• Vklass の Cookie や OAuth シークレットが MCP やログを通じて返されることはありません。

• Göteborg SAML および BankID のフォーム / リダイレクトホストは、厳密に許可リスト方式で管理されます。

• Vklass のコンテンツは信頼できないデータとして扱われ、命令としては決して解釈されません。

• コンテナは root なし、ケーパビリティなしで実行され、読み取り専用のルートファイルシステムを使用します。

• 本番環境の OAuth には公開 HTTPS が必要です。コンテナのポートはループバックにバインドされ、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 に接続します。LAN や インターネット上では 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 シークレットを 1 つだけ作成します: 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 issuer であり、クライアントが再認可を要求されることなく変更することはできません。

ユーザーサービスがログアウト後も存続するために:

loginctl enable-linger "$USER"

Folksaga エッジを通じた公開展開

deploy/folksaga/ は、perd.local 上の既存の folksaga rootless Podman アカウントを対象としています。これは ローカルでビルドされたイメージを転送し、プライベートな folksaga ネットワーク上に強化された Quadlet をインストールし、 バックアップされた state キーを作成し、別のホストポートを公開せずにサービスを開始します:

make build
./deploy/folksaga/deploy.sh

追跡対象の Folksaga Caddy 設定は、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 と暗号化されたセッションは、state キーと一緒にバックアップする必要があります。

• OAuth 認可情報は /revoke を通じて失効させることができます。ローカルデータの削除は現在、運営者による操作が必要です。 MCP 読み取りトークンが破壊的なアカウント管理を引き起こすことはありません。

• BankID 認可トランザクションは意図的にプロセスローカルです。アプリケーションワーカーは 1 つだけ実行してください。

• 組み込みのピアごとのレート制限、グローバルな認可制限、同時 BankID スロット、および常駐 サービス上限が抑止策を提供します。公開利用時は、TLS エッジでより厳格な分散制限を適用してください。

• state キーは安定させ、バックアップしてください。ローテーションには、暗号化されたクライアント メタデータ、ユーザーセッション、仮名 OAuth サブジェクトの計画的な移行が必要です。直接置き換えるとユーザーが切断されます。

帰属

Göteborg BankID フローは、MIT ライセンスの Kaptensanders/vklass から改作されています。詳細は THIRD_PARTY_NOTICES.md を参照してください。