vklass-mcp

Un servidor de Model Context Protocol multiusuario y de solo lectura para los tutores de Vklass. Cada usuario autentica su propia cuenta de Vklass con BankID como parte del flujo OAuth estándar de MCP. Cada sujeto OAuth se corresponde directamente con un identificador de usuario de Vklass; no hay inicio de sesión compartido, token MCP global ni contraseña de administrador.

La superficie del protocolo MCP está diseñada como la de un servidor MCP remoto de primera parte. La integración con Vklass es necesariamente no oficial porque Vklass no publica una API para tutores; sus endpoints web pueden cambiar.

MCP y modelo de identidad

• Un único endpoint HTTP Streamable: /mcp.

• Flujo de código de autorización OAuth 2.1 con PKCE S256.

• Metadatos del servidor de autorización OAuth y metadatos de recurso protegido RFC 9728.

• Registro dinámico de clientes para clientes MCP compatibles.

• Tokens de acceso y actualización rotativos, revocación, scopes e indicadores de recurso RFC 8707.

• La página de autorización OAuth inicia el flujo QR de BankID de Göteborg de Vklass.

• Tras el inicio de sesión, appData.userId de Vklass se convierte en un sujeto OAuth seudónimo, estable y local al servidor, usando la clave de estado; el identificador de usuario de Vklass en bruto no se almacena en las concesiones OAuth.

• Cada sujeto recibe su propia sesión de Vklass, su caché SQLite, sus tareas de sincronización y su directorio de estado cifrado. Las consultas de datos nunca pueden seleccionar la base de datos de otro sujeto.

• Los valores de acceso/actualización/código OAuth en bruto se almacenan con hash SHA-256 en SQLite. Los metadatos de clientes registrados, incluidos los secretos de cliente, se cifran con la clave de estado del servidor.

• Cuando la sesión de Vklass subyacente caduca, se revocan todas las concesiones de ese sujeto de Vklass para que los clientes MCP reciban un 401 estándar y reinicien el flujo de autorización de BankID.

Los clientes MCP se conectan únicamente a:

https://vklass.example.com/mcp

Un cliente compatible descubre OAuth, abre el navegador, pide al usuario que apruebe BankID y almacena sus propios tokens. Usuarios y clientes distintos usan la misma URL, pero reciben sujetos OAuth diferentes.

El servidor utiliza un único ámbito de privilegio mínimo, vklass.read, tanto para las consultas de solo lectura de Vklass en caché como en vivo.

Related MCP server: aula-mcp

Seguridad

• El acceso a Vklass es de solo lectura. Los partes de ausencia, los permisos, los mensajes y otras mutaciones no están expuestos.

• La aprobación de BankID siempre la realiza el propietario de la cuenta en un navegador.

• Las cookies de Vklass y los secretos OAuth nunca se devuelven a través de MCP ni en los registros.

• Los hosts de formularios/redirecciones SAML y BankID de Göteborg están incluidos estrictamente en la lista de permitidos.

• El contenido de Vklass se trata como datos no confiables, nunca como instrucciones.

• El contenedor se ejecuta sin root ni capabilities y usa un sistema de archivos raíz de solo lectura.

• El OAuth de producción requiere un origen HTTPS público. El puerto del contenedor se enlaza al loopback para Mary proxy inverso TLS y no debe publicarse directamente.

Si este servicio se ofrece a otros padres y madres, el operador se convierte en responsable del tratamiento de datos personales. Hay que ofrecer términos claros de conservación y supresión, copias de seguridad protegidas, gestión de incidents y un contacto del operador. Los usuarios también deben entender que su cliente MCP puede enviar los resultados de las herramientas a su proveedor de modelos.

Cobertura de Vklass implementada

Herramientas 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

Desarrollo local

Requiere Python 3.12+ y 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

Conecta un cliente MCP de desarrollo a http://127.0.0.1:8000/mcp. No uses HTTP en una LAN ni en Internet.

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

El instalador crea un único secreto de Podman: vklass-mcp-state-key. Los clients OAuth y los usuarios crean sus propias credentials mediante el protocolo. La versión 0.2 se niega deliberadamente a arrancar si quedan archivos antiguos de un solo usuario vklass.db* o session.json.fernet en la raíz de datos; migra dichos archivos o elimina por completo el conjunto heredado antes del despliegue.

Ubicaciones en tiempo de ejecución:

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

El Quadlet se enlaza a 127.0.0.1:8787. Coloca Caddy u otro proxy inverso TLS delante:

vklass.example.com {
    reverse_proxy 127.0.0.1:8787
}

Define tanto VKLASS_PUBLIC_BASE_URL=https://vklass.example.com como VKLASS_ALLOWED_HOSTS=vklass.example.com,localhost:*,127.0.0.1:*. La URL pública es el emisor OAuth y no puede cambiarse sin que los clientes tengan que volver a autorizarse.

Para que el servicio de usuario sobreviva al cierre de sesión:

loginctl enable-linger "$USER"

Despliegue público mediante el edge de Folksaga

deploy/folksaga/ apunta a la cuenta existing folksaga de Podman sin privilegios en perd.local. Transfiere la imagen construida localmente, instala un Quadlet reforzado en la red privada folksaga, crea una clave de estado con respaldo e inicia el servicio siguiendo con otro puerto de anfitrión:

make build
./deploy/folksaga/deploy.sh

La configuración de Caddy de Folksaga versionada proxifica https://vklass.perapp.dev directamente a vklass-mcp:8000 y obtiene su certificado público a través de los puertos y/o existentes 80/443. El DNS ya resuelve ese nombre de host a través de perapp.dev. Haz copias de seguridad tanto de /srv/folksaga/data/vklass-mcp/ como de /srv/folksaga/secrets/vklass-mcp-state-key; perder la clave desconecta a todos los usuarios y deja ilegibles las sesiones cifradas y los registros de clientes OAuth.

Operaciones

• Salud: GET /healthz

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

• Metadatos de recurso protegido: GET /.well-known/oauth-protected-resource/mcp

• Revocación OAuth: POST /revoke

• Las sesiones SQLite y las sesiones cifradas deben respaldarse junto con la clave de estado.

• Las concesiones OAuth pueden revocarse mediante /revoke; la eliminación local de datos es ahora, por the moment, an acción asistida por el operador, de modo que un token de lectura MCP no pueda desencadenar una gestión destructiva de la cuenta.

• Las transacciones de autorización BankID son intencionadamente locales al proceso; ejecuta un único trabajador de aplicación.

• Los límites de velocidad por peer integrados, los límites globales de autorización, los 'slots' concurrentes de BankID y un límite de servicio residente actúan como red de seguridad. Aplica límites distribuidos más estrictos en el edge TLS para el uso público.

• Mantén la clave de estado estable y con copia de seguridad. La rotación requiere una migración planificada de los metadatos cifrados de los clientes, las sesiones de los usuarios y los sujetos OAuth seudónimos; sustituirla directamente desconecta a los usuarios.

Atribución

El flujo BankID de Göteborg se ha adaptado a partir del proyecto Kaptensander/vklass con licencia MIT. Consulta THIRD_PARTY_NOTICES.md.