vklass-mcp

一个面向 Vklass 监护人的多用户、只读 Model Context Protocol 服务器。每个用户都通过标准 MCP OAuth 流程，使用 BankID 验证自己的 Vklass 账户。每个 OAuth 主体直接映射到一个 Vklass 用户 ID；没有共享登录、全局 MCP 令牌或管理员密码。

MCP 协议表面设计得像第一方远程 MCP 服务器。Vklass 集成必然是非官方的，因为 Vklass 不发布监护人 API；其 Web 端点可能会变化。

MCP 和身份模型

• 一个 Streamable HTTP 端点：/mcp。

• 使用 S256 PKCE 的 OAuth 2.1 授权码流程。

• OAuth 授权服务器元数据和 RFC 9728 受保护资源元数据。

• 为兼容的 MCP 客户端提供动态客户端注册。

• 轮换访问和刷新令牌、撤销、作用域和 RFC 8707 资源指示符。

• OAuth 授权页面启动哥德堡 Vklass BankID QR 流程。

• 登录后，Vklass appData.userId 使用状态密钥转换为稳定的服务器本地化名 OAuth 主体；原始 Vklass 用户 ID 不会存储在 OAuth 授权中。

• 每个主体都有自己的 Vklass 会话、SQLite 缓存、同步任务和加密状态目录。数据查询永远无法选择另一个主体的数据库。

• 原始 OAuth 访问/刷新/代码值在 SQLite 中进行 SHA-256 哈希处理。已注册的客户端元数据（包括客户端密钥）使用服务器状态密钥加密。

• 当上游 Vklass 会话过期时，该 Vklass 主体的所有授权都会被撤销，以便 MCP 客户端收到标准的 401 并重新启动 BankID 授权流程。

MCP 客户端仅连接到：

https://vklass.example.com/mcp

兼容的客户端发现 OAuth、打开浏览器、要求用户批准 BankID，并存储自己的令牌。不同的用户和客户端使用相同的 URL，但接收不同的 OAuth 主体。

服务器对缓存和实时的只读 Vklass 查询使用一个最小权限作用域 vklass.read。

Related MCP server: jisr-mcp

安全性

• Vklass 访问是只读的。缺勤报告、请假、消息和其他变更操作不会暴露。

• BankID 批准始终由账户所有者在浏览器中执行。

• Vklass cookie 和 OAuth 密钥永远不会通过 MCP 或日志返回。

• 哥德堡 SAML 和 BankID 表单/重定向主机被严格列入白名单。

• Vklass 内容被视为不受信任的数据，而不是指令。

• 容器以非 root 身份运行，没有 capabilities，并使用只读根文件系统。

• 生产 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。不要在局域网或互联网上使用 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"

通过 Folksaga 边缘进行公共部署

deploy/folksaga/ 针对 perd.local 上现有的 folksaga 无根 Podman 账户。它传输本地构建的镜像，在私有 folksaga 网络上安装强化的 Quadlet，创建带备份的状态密钥并启动服务，而无需发布另一个主机端口：

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 和加密会话必须与状态密钥一起备份。

• OAuth 授权可以通过 /revoke 撤销；本地数据删除目前是操作员辅助操作，因此 MCP 读取令牌无法触发破坏性账户管理。

• BankID 授权事务有意保持进程本地；运行一个应用程序工作进程。

• 内置的每对等方速率限制、全局授权限制、并发 BankID 插槽和常驻服务上限提供后备保护。对于公共使用，请在 TLS 边缘应用更严格的分布式限制。

• 保持状态密钥稳定并备份。轮换需要计划迁移加密的客户端元数据、用户会话和化名 OAuth 主体；直接替换会断开用户连接。

归属

哥德堡 BankID 流程改编自 MIT 许可的 Kaptensanders/vklass。请参阅 THIRD_PARTY_NOTICES.md。