vklass-mcp

Vklass 보호자를 위한 다중 사용자, 읽기 전용 Model Context Protocol 서버입니다. 모든 사용자는 표준 MCP OAuth 흐름의 일부로 BankID를 사용하여 자신의 Vklass 계정으로 인증합니다. 각 OAuth 주체는 하나의 Vklass 사용자 ID에 직접 매핑됩니다. 공유 로그인, 전역 MCP 토큰 또는 관리자 비밀번호는 없습니다.

MCP 프로토콜 노출 영역은 퍼스트파티 원격 MCP 서버처럼 설계되었습니다. Vklass는 보호자 API를 공개하지 않기 때문에 Vklass 통합은 필연적으로 비공식적입니다. Vklass 웹 엔드포인트는 변경될 수 있습니다.

MCP 및 ID 모델

• 단일 Streamable HTTP 엔드포인트: /mcp.

• S256 PKCE를 사용하는 OAuth 2.1 인가 코드 흐름.

• OAuth Authorization Server Metadata 및 RFC 9728 Protected Resource Metadata.

• 호환 MCP 클라이언트를 위한 Dynamic Client Registration.

• 순환 액세스 및 리프레시 토큰, 폐기, 스코프 및 RFC 8707 리소스 표시자.

• OAuth 인가 페이지는 Göteborg 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: aula-mcp

보안

• Vklass 액세스는 읽기 전용입니다. 결석 보고서, 휴가, 메시지 및 기타 변경 작업은 노출되지 않습니다.

• BankID 승인은 항상 계정 소유자가 브라우저에서 수행합니다.

• Vklass 쿠키와 OAuth 시크릿은 MCP나 로그를 통해 절대 반환되지 않습니다.

• Göteborg 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에 연결하세요. 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 시크릿을 하나만 생성합니다: 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 주체의 계획된 마이그레이션이 필요합니다. 키를 직접 교체하면 사용자 연결이 끊깁니다.

저작자 표시

Göteborg BankID 흐름은 MIT 라이선스의 Kaptensanders/vklass에서 각색되었습니다. 참고: THIRD_PARTY_NOTICES.md.