Read the timetable from WebUntis
Schulcloud holds the material for a lesson but not the lesson: this school's course `times` are empty and it publishes the schedule in WebUntis. So "what do I have today, and has anything been cancelled" was unanswerable, and the timetable cannot be typed into a prompt either — it changes daily. core/untis.ts talks to the API the Untis Mobile app uses, and three tools sit on it: untis_timetable (a day or a range, Entfall, Vertretung, room changes, the notes on each period, inline homework, the period id), untis_homework (the class register's list, which is not Schulcloud's tasks) and untis_lesson_topics (what earlier lessons of a series actually covered, which is what says where a subject got to). Read-only, but not by the Schulcloud client's rule: this API is JSON-RPC, so every call is a POST, reads included. READ_METHODS is the guarantee instead, enforced at the single choke point and asserted by a test. It matters because the key can do what the app can — the live account holds W_OWN_ABSENCE, so the same key could report the user absent. What the live instance taught us, all recorded in docs/API.md: - `startDateTime` ends in Z and is local time. The 08:00 lesson reports 08:00Z, so new Date() would move every lesson by an hour or two. - A substitution is two periods, the original CANCELLED and the replacement IRREGULAR beside it, not one period with a changed teacher. - Announced tests live in the period's info text. The exam module is unused here, so getExams2017 is always empty and that field carries the tests. - A day with no lessons is not a holiday: the weeks this account spends in the company simply have no periods. - `?v=i3.2` is required, or the call fails with a Java NPE reported as -8998. Errors arrive with HTTP 200 and an error member. -8504 is a rejected key and -8524 a drifting clock; the tools name both, because no retry fixes either. Configuration is all four UNTIS_* values or none — three are identifiers and the fourth is a credential, so a half-filled block is a paste that went wrong. Without them the tools are not registered at all, since a tool that can only fail is worse than a missing one. whoami reports the WebUntis identity and survives a dead Schulcloud session, so "is the server reachable" no longer gets a misleadingly total no. mcp-env.sh switches WebUntis off for a fixture run: that key belongs to the real school. 224 tests. All 10 WebUntis smoke checks pass, with a key and without one; the Schulcloud checks in those runs answer 401 because this machine's session is logged out. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
MechaCat02
@@ -75,7 +75,10 @@ async function main(): Promise<void> {
|
||||
`token from ${token.source}${token.daysLeft === undefined ? '' : `, ${token.daysLeft} day(s) left`}` +
|
||||
`${token.persistent ? '' : ' (replacements not saved: STATE_DIR unset)'}, ` +
|
||||
`keepalive ${keepalive ? `every ${Math.round(config.keepaliveIntervalMs / 60_000)}min` : 'off'}, ` +
|
||||
`index ${services.store ? (config.crawlIntervalMs > 0 ? `every ${Math.round(config.crawlIntervalMs / 3_600_000)}h` : 'on demand') : 'off'}`,
|
||||
`index ${services.store ? (config.crawlIntervalMs > 0 ? `every ${Math.round(config.crawlIntervalMs / 3_600_000)}h` : 'on demand') : 'off'}, ` +
|
||||
// The origin, never the key: this is the line that says whether the
|
||||
// timetable tools exist at all in this deployment.
|
||||
`untis ${services.untis ? services.untis.origin : 'off'}`,
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
*/
|
||||
|
||||
import { resolve } from 'node:path';
|
||||
import type { UntisConfig } from './core/untis.ts';
|
||||
|
||||
export interface Config {
|
||||
/** Instance base URL, no trailing slash, e.g. `https://schulcloud-thueringen.de`. */
|
||||
@@ -61,6 +62,13 @@ export interface Config {
|
||||
indexFileManager: boolean;
|
||||
/** How often to re-crawl on a timer. Zero = only on demand. */
|
||||
crawlIntervalMs: number;
|
||||
|
||||
/**
|
||||
* WebUntis, where the school keeps the timetable. Unset = the untis_* tools
|
||||
* are not offered at all, which is the right answer for a school that does
|
||||
* not use it — Schulcloud alone cannot say what happens when.
|
||||
*/
|
||||
untis: UntisConfig | undefined;
|
||||
}
|
||||
|
||||
function required(name: string): string {
|
||||
@@ -114,6 +122,46 @@ function secretToken(name: string): string | undefined {
|
||||
return value;
|
||||
}
|
||||
|
||||
/**
|
||||
* The four WebUntis values, or undefined when none is set.
|
||||
*
|
||||
* All four or nothing: three of them are harmless identifiers and the fourth is
|
||||
* a credential, so a half-filled block is a copy-paste that went wrong, not a
|
||||
* configuration to guess at. They come from one dialog — WebUntis → Profil →
|
||||
* Freigaben → Untis Mobile → QR-Code — and the error says so, because that is
|
||||
* the only place to find them.
|
||||
*/
|
||||
function untisConfig(): UntisConfig | undefined {
|
||||
const server = process.env.UNTIS_SERVER?.trim();
|
||||
const school = process.env.UNTIS_SCHOOL?.trim();
|
||||
const user = process.env.UNTIS_USER?.trim();
|
||||
const secret = process.env.UNTIS_SECRET?.trim();
|
||||
const missing = Object.entries({ UNTIS_SERVER: server, UNTIS_SCHOOL: school, UNTIS_USER: user, UNTIS_SECRET: secret })
|
||||
.filter(([, value]) => !value)
|
||||
.map(([name]) => name);
|
||||
if (missing.length === 4) return undefined;
|
||||
if (!server || !school || !user || !secret) {
|
||||
throw new Error(
|
||||
`WebUntis needs all four of UNTIS_SERVER, UNTIS_SCHOOL, UNTIS_USER and UNTIS_SECRET — missing: ` +
|
||||
`${missing.join(', ')}. All four are in WebUntis → Profil → Freigaben → Untis Mobile → QR-Code.`,
|
||||
);
|
||||
}
|
||||
if (!/^[a-z0-9][a-z0-9.-]*\.[a-z]{2,}$/i.test(server)) {
|
||||
throw new Error(
|
||||
`UNTIS_SERVER must be the bare host from the QR dialog's "Url" field, e.g. "ags-erfurt.webuntis.com" — ` +
|
||||
`no scheme and no path, got "${server}".`,
|
||||
);
|
||||
}
|
||||
// A credential: the error states the rule and never echoes the value.
|
||||
if (!/^[A-Za-z2-7]{8,}$/.test(secret)) {
|
||||
throw new Error(
|
||||
'UNTIS_SECRET must be the key from the Untis Mobile QR dialog: at least 8 characters of A-Z and 2-7 ' +
|
||||
'(base32), no spaces.',
|
||||
);
|
||||
}
|
||||
return { server, school, user, secret };
|
||||
}
|
||||
|
||||
/** Like `int`, but 0 is meaningful (it disables the feature) rather than invalid. */
|
||||
function intAllowingZero(name: string, fallback: number): number {
|
||||
const raw = process.env[name]?.trim();
|
||||
@@ -162,5 +210,6 @@ export function loadConfig(): Config {
|
||||
// so an index without it misses whole courses. One page load per folder.
|
||||
indexFileManager: bool('INDEX_FILE_MANAGER', true),
|
||||
crawlIntervalMs: intAllowingZero('CRAWL_INTERVAL_MS', 6 * 60 * 60_000),
|
||||
untis: untisConfig(),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -2,6 +2,7 @@ import type { Config } from './config.ts';
|
||||
import { SchulcloudClient } from './core/client.ts';
|
||||
import { FileManager } from './core/legacy-files.ts';
|
||||
import type { LegacyUser, MeResponse } from './core/types.ts';
|
||||
import { UntisClient } from './core/untis.ts';
|
||||
import type { Indexer } from './indexer/indexer.ts';
|
||||
import type { Store } from './store/store.ts';
|
||||
|
||||
@@ -20,6 +21,8 @@ export class ServerContext {
|
||||
/** Shared across sessions; undefined when running without an index. */
|
||||
readonly store: Store | undefined;
|
||||
readonly indexer: Indexer | undefined;
|
||||
/** WebUntis — the timetable — or undefined when the server has no key for it. */
|
||||
readonly untis: UntisClient | undefined;
|
||||
private identity: Promise<MeResponse> | undefined;
|
||||
/**
|
||||
* id -> display name, for the whole session.
|
||||
@@ -35,13 +38,20 @@ export class ServerContext {
|
||||
|
||||
constructor(
|
||||
config: Config,
|
||||
shared?: { client?: SchulcloudClient; files?: FileManager; store?: Store; indexer?: Indexer },
|
||||
shared?: {
|
||||
client?: SchulcloudClient;
|
||||
files?: FileManager;
|
||||
store?: Store;
|
||||
indexer?: Indexer;
|
||||
untis?: UntisClient;
|
||||
},
|
||||
) {
|
||||
this.config = config;
|
||||
this.client = shared?.client ?? new SchulcloudClient(config);
|
||||
this.files = shared?.files ?? new FileManager(this.client);
|
||||
this.store = shared?.store;
|
||||
this.indexer = shared?.indexer;
|
||||
this.untis = shared?.untis ?? (config.untis ? new UntisClient(config.untis, config.requestTimeoutMs) : undefined);
|
||||
}
|
||||
|
||||
/** Cached `/me`. Shared promise, so concurrent first calls make one request. */
|
||||
|
||||
555
src/core/untis.ts
Normal file
555
src/core/untis.ts
Normal file
@@ -0,0 +1,555 @@
|
||||
/**
|
||||
* WebUntis: the timetable, its changes, homework and what was taught.
|
||||
*
|
||||
* The school keeps its timetable in WebUntis, not in Schulcloud — Schulcloud's
|
||||
* course `times` are empty here — so "what do I have today, and has anything
|
||||
* been cancelled" is a question only this API can answer. It is the other half
|
||||
* of a school day: Schulcloud holds the material, WebUntis holds the schedule.
|
||||
*
|
||||
* **Read-only, but not by the Schulcloud client's rule.** This is JSON-RPC:
|
||||
* every call is a POST, reads included, so "GET only" cannot be the guarantee.
|
||||
* `READ_METHODS` is: `call` refuses any method outside it. That matters because
|
||||
* the key is the mobile app's credential and can do what the app can — this
|
||||
* account holds `W_OWN_ABSENCE`, so the same key could report the user absent.
|
||||
*
|
||||
* Authentication is a one-time code derived from the base32 key behind the QR
|
||||
* code in WebUntis → Profil → Freigaben (see core/totp.ts). Each request signs
|
||||
* itself, so unlike the Schulcloud session there is nothing to hold open and
|
||||
* nothing to refresh — but the server's clock has to be right, which is what
|
||||
* error -8524 means.
|
||||
*/
|
||||
|
||||
import { compactDate } from './dates.ts';
|
||||
import { totp } from './totp.ts';
|
||||
|
||||
export interface UntisConfig {
|
||||
/** Bare host from the QR dialog's "Url" field, e.g. `ags-erfurt.webuntis.com`. */
|
||||
server: string;
|
||||
/** The school's login name, e.g. `ags-erfurt`. */
|
||||
school: string;
|
||||
user: string;
|
||||
/** The base32 key from the QR dialog. A credential: never log it. */
|
||||
secret: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* The methods this client may call. Everything here reads; nothing writes.
|
||||
*
|
||||
* Verified against the live instance — `getClassregEvents2017` and
|
||||
* `getSchoolyears2017` answer "Method not found" and are deliberately absent.
|
||||
*/
|
||||
const READ_METHODS = new Set([
|
||||
'getUserData2017',
|
||||
'getTimetable2017',
|
||||
'getLessonTopic2017',
|
||||
'getHomeWork2017',
|
||||
'getMessagesOfDay2017',
|
||||
]);
|
||||
|
||||
/**
|
||||
* The read-only guarantee for this API, at its single choke point.
|
||||
*
|
||||
* Exported so a test can hold it to it: this is the line that keeps a key which
|
||||
* *can* write from being used to write.
|
||||
*/
|
||||
export function assertReadMethod(method: string): void {
|
||||
if (!READ_METHODS.has(method)) {
|
||||
throw new Error(`Refusing to call WebUntis method ${method}: not in the read-only allowlist.`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The client version the mobile API expects as `?v=`.
|
||||
*
|
||||
* Not optional: `jsonrpc_intern.do` reads the parameter without checking it,
|
||||
* so omitting it fails with a Java NullPointerException reported as -8998.
|
||||
*/
|
||||
const API_VERSION = 'i3.2';
|
||||
|
||||
/** How long master data (subjects, teachers, rooms, holidays) is reused. */
|
||||
const MASTER_DATA_TTL_MS = 6 * 60 * 60_000;
|
||||
|
||||
/** A JSON-RPC error from WebUntis. They arrive with HTTP 200 and an `error` body. */
|
||||
export class UntisApiError extends Error {
|
||||
readonly code: number;
|
||||
readonly method: string;
|
||||
|
||||
constructor(code: number, method: string, message: string) {
|
||||
super(`WebUntis ${method} failed (${code}): ${message}`);
|
||||
this.name = 'UntisApiError';
|
||||
this.code = code;
|
||||
this.method = method;
|
||||
}
|
||||
|
||||
/** -8504: the key or user name is wrong, or the key has been regenerated. */
|
||||
get isAuthFailure(): boolean {
|
||||
return this.code === -8504;
|
||||
}
|
||||
|
||||
/** -8524: our clock is too far from the school server's. */
|
||||
get isClockSkew(): boolean {
|
||||
return this.code === -8524;
|
||||
}
|
||||
}
|
||||
|
||||
// --- what callers get ----------------------------------------------------
|
||||
|
||||
/** A subject, teacher, room or class: a short code plus, where known, a full name. */
|
||||
export interface UntisName {
|
||||
name: string;
|
||||
longName?: string;
|
||||
}
|
||||
|
||||
export interface UntisHomework {
|
||||
id: number;
|
||||
lessonId: number;
|
||||
/** When it was set, `YYYY-MM-DD`. */
|
||||
assigned: string;
|
||||
/** When it is due, `YYYY-MM-DD`. */
|
||||
due: string;
|
||||
text: string;
|
||||
remark?: string;
|
||||
completed: boolean;
|
||||
subject?: UntisName;
|
||||
attachments: number;
|
||||
}
|
||||
|
||||
export interface UntisLesson {
|
||||
/** The period id, which `getLessonTopic2017` takes. */
|
||||
periodId: number;
|
||||
/** The lesson (series) id: the same weekly slot shares it. */
|
||||
lessonId: number;
|
||||
date: string;
|
||||
/** `HH:MM` in the school's local time. */
|
||||
start: string;
|
||||
end: string;
|
||||
/** Raw status words, e.g. `REGULAR`, `CANCELLED`, `IRREGULAR`. */
|
||||
statuses: string[];
|
||||
cancelled: boolean;
|
||||
/** A substitution, a moved lesson or anything else Untis calls irregular. */
|
||||
changed: boolean;
|
||||
subjects: UntisName[];
|
||||
teachers: UntisName[];
|
||||
rooms: UntisName[];
|
||||
classes: UntisName[];
|
||||
/** What each kind of element replaced, when Untis says so (its `orgId`). */
|
||||
replaced: { subjects: UntisName[]; teachers: UntisName[]; rooms: UntisName[] };
|
||||
/** The three free-text fields a teacher can attach to a period. */
|
||||
notes: { lesson?: string; substitution?: string; info?: string };
|
||||
homework: UntisHomework[];
|
||||
/** The exam module's title, when the school uses it. */
|
||||
exam?: string;
|
||||
online: boolean;
|
||||
}
|
||||
|
||||
export interface UntisHoliday {
|
||||
name: string;
|
||||
longName: string;
|
||||
start: string;
|
||||
end: string;
|
||||
}
|
||||
|
||||
export interface UntisDay {
|
||||
date: string;
|
||||
lessons: UntisLesson[];
|
||||
/** Holidays and single free days covering this date. */
|
||||
holidays: UntisHoliday[];
|
||||
}
|
||||
|
||||
export interface UntisTimetable {
|
||||
from: string;
|
||||
to: string;
|
||||
/** Every date in the range, including the ones without lessons. */
|
||||
days: UntisDay[];
|
||||
}
|
||||
|
||||
export interface UntisIdentity {
|
||||
displayName: string;
|
||||
elementId: number;
|
||||
elementType: string;
|
||||
schoolName: string;
|
||||
/** Untis' own permission words, e.g. `R_MY_ABSENCES`, `W_OWN_ABSENCE`. */
|
||||
rights: string[];
|
||||
}
|
||||
|
||||
/** One class-register entry: what was taught in a lesson of this series. */
|
||||
export interface UntisTopic {
|
||||
text: string;
|
||||
periodId: number;
|
||||
date: string;
|
||||
start: string;
|
||||
end: string;
|
||||
}
|
||||
|
||||
export interface UntisMessage {
|
||||
subject: string;
|
||||
text: string;
|
||||
}
|
||||
|
||||
// --- raw shapes ----------------------------------------------------------
|
||||
|
||||
interface RawElement {
|
||||
type: string;
|
||||
id: number;
|
||||
orgId?: number;
|
||||
}
|
||||
|
||||
interface RawPeriod {
|
||||
id: number;
|
||||
lessonId: number;
|
||||
startDateTime: string;
|
||||
endDateTime: string;
|
||||
text?: { lesson?: string; substitution?: string; info?: string; attachments?: unknown[] };
|
||||
elements?: RawElement[];
|
||||
is?: string[];
|
||||
homeWorks?: RawHomework[];
|
||||
exam?: { name?: string; text?: string } | null;
|
||||
isOnlinePeriod?: boolean;
|
||||
}
|
||||
|
||||
interface RawHomework {
|
||||
id: number;
|
||||
lessonId: number;
|
||||
startDate: string;
|
||||
endDate: string;
|
||||
text: string;
|
||||
remark?: string | null;
|
||||
completed?: boolean;
|
||||
attachments?: unknown[];
|
||||
}
|
||||
|
||||
interface RawNamed {
|
||||
id: number;
|
||||
name: string;
|
||||
longName?: string;
|
||||
firstName?: string;
|
||||
lastName?: string;
|
||||
}
|
||||
|
||||
interface RawMasterData {
|
||||
timeStamp?: number;
|
||||
subjects?: RawNamed[];
|
||||
teachers?: RawNamed[];
|
||||
rooms?: RawNamed[];
|
||||
klassen?: RawNamed[];
|
||||
holidays?: { name: string; longName: string; startDate: string; endDate: string }[];
|
||||
}
|
||||
|
||||
interface RawUserData {
|
||||
userData?: {
|
||||
displayName?: string;
|
||||
elemId?: number;
|
||||
elemType?: string;
|
||||
schoolName?: string;
|
||||
rights?: string[];
|
||||
};
|
||||
masterData?: RawMasterData;
|
||||
}
|
||||
|
||||
interface RawTimetable {
|
||||
timetable?: { periods?: RawPeriod[] };
|
||||
masterData?: RawMasterData;
|
||||
}
|
||||
|
||||
// --- client --------------------------------------------------------------
|
||||
|
||||
export class UntisClient {
|
||||
private readonly config: UntisConfig;
|
||||
private readonly timeoutMs: number;
|
||||
private identityPromise: Promise<UntisIdentity> | undefined;
|
||||
private masterData: { data: RawMasterData; at: number } | undefined;
|
||||
|
||||
constructor(config: UntisConfig, timeoutMs = 30_000) {
|
||||
this.config = config;
|
||||
this.timeoutMs = timeoutMs;
|
||||
}
|
||||
|
||||
/** For status lines: where this client is pointed, never how it authenticates. */
|
||||
get origin(): string {
|
||||
return `${this.config.server}/${this.config.school}`;
|
||||
}
|
||||
|
||||
private async call<T>(method: string, params: Record<string, unknown>): Promise<T> {
|
||||
// The allowlist is the read-only guarantee for this API; widening it is a
|
||||
// deliberate act, not something a caller can do by passing a string.
|
||||
assertReadMethod(method);
|
||||
const url =
|
||||
`https://${this.config.server}/WebUntis/jsonrpc_intern.do` +
|
||||
`?m=${encodeURIComponent(method)}&school=${encodeURIComponent(this.config.school)}&v=${API_VERSION}`;
|
||||
const response = await fetch(url, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'content-type': 'application/json',
|
||||
// Honest, and accepted: the endpoint does not check for the app's own
|
||||
// user agent.
|
||||
'user-agent': 'schulcloud-mcp',
|
||||
},
|
||||
body: JSON.stringify({
|
||||
id: 'schulcloud-mcp',
|
||||
jsonrpc: '2.0',
|
||||
method,
|
||||
params: [
|
||||
{
|
||||
...params,
|
||||
// The code is a string: one in ten starts with a zero, which a
|
||||
// JSON number would drop.
|
||||
auth: { user: this.config.user, otp: totp(this.config.secret), clientTime: Date.now() },
|
||||
},
|
||||
],
|
||||
}),
|
||||
signal: AbortSignal.timeout(this.timeoutMs),
|
||||
});
|
||||
|
||||
const body = (await response.json().catch(() => undefined)) as
|
||||
| { result?: T; error?: { code?: number; message?: string } }
|
||||
| undefined;
|
||||
// Failures come back as HTTP 200 with an `error` member, so the body is
|
||||
// the thing to check first.
|
||||
if (body?.error) {
|
||||
throw new UntisApiError(body.error.code ?? 0, method, body.error.message ?? 'no message');
|
||||
}
|
||||
if (!response.ok) throw new UntisApiError(0, method, `HTTP ${response.status}`);
|
||||
if (body?.result === undefined) throw new UntisApiError(0, method, 'response carried no result');
|
||||
return body.result;
|
||||
}
|
||||
|
||||
/** Who the key belongs to. Cached; a failure is not, so a fixed key recovers. */
|
||||
identity(): Promise<UntisIdentity> {
|
||||
this.identityPromise ??= this.call<RawUserData>('getUserData2017', {})
|
||||
.then((raw) => {
|
||||
if (raw.masterData) this.masterData = { data: raw.masterData, at: Date.now() };
|
||||
const user = raw.userData ?? {};
|
||||
if (user.elemId === undefined || !user.elemType) {
|
||||
throw new UntisApiError(0, 'getUserData2017', 'response carried no user element');
|
||||
}
|
||||
return {
|
||||
displayName: user.displayName ?? '(unnamed)',
|
||||
elementId: user.elemId,
|
||||
elementType: user.elemType,
|
||||
schoolName: user.schoolName ?? this.config.school,
|
||||
rights: user.rights ?? [],
|
||||
};
|
||||
})
|
||||
.catch((error: unknown) => {
|
||||
this.identityPromise = undefined;
|
||||
throw error;
|
||||
});
|
||||
return this.identityPromise;
|
||||
}
|
||||
|
||||
/**
|
||||
* The timetable for a date range, with every day in it — including the ones
|
||||
* with no lessons, because "no school today" is an answer and an empty list
|
||||
* is not.
|
||||
*/
|
||||
async timetable(from: string, to: string): Promise<UntisTimetable> {
|
||||
const me = await this.identity();
|
||||
const raw = await this.call<RawTimetable>('getTimetable2017', {
|
||||
id: me.elementId,
|
||||
type: me.elementType,
|
||||
startDate: compactDate(from),
|
||||
endDate: compactDate(to),
|
||||
// Always ask for full master data rather than a delta against a cached
|
||||
// timestamp: the delta's removal semantics are unverified, and the whole
|
||||
// set is one payload of a few hundred kilobytes a handful of times a day.
|
||||
masterDataTimestamp: 0,
|
||||
timetableTimestamp: 0,
|
||||
timetableTimestamps: [],
|
||||
});
|
||||
if (raw.masterData?.subjects) this.masterData = { data: raw.masterData, at: Date.now() };
|
||||
const master = raw.masterData ?? (await this.master());
|
||||
|
||||
const lessons = (raw.timetable?.periods ?? []).map((period) => this.toLesson(period, master));
|
||||
const days: UntisDay[] = [];
|
||||
for (let date = from; date <= to; date = nextDate(date)) {
|
||||
days.push({
|
||||
date,
|
||||
lessons: lessons.filter((lesson) => lesson.date === date).sort(byStart),
|
||||
holidays: holidaysOn(master, date),
|
||||
});
|
||||
}
|
||||
return { from, to, days };
|
||||
}
|
||||
|
||||
/**
|
||||
* Homework set for a date range.
|
||||
*
|
||||
* The range filters by the homework's own dates, not by when it was set, so
|
||||
* a window that ends today shows nothing that is due tomorrow.
|
||||
*/
|
||||
async homework(from: string, to: string): Promise<UntisHomework[]> {
|
||||
const me = await this.identity();
|
||||
const raw = await this.call<{
|
||||
homeWorks?: RawHomework[];
|
||||
lessonsById?: Record<string, { subjectId?: number }>;
|
||||
}>('getHomeWork2017', {
|
||||
id: me.elementId,
|
||||
type: me.elementType,
|
||||
startDate: compactDate(from),
|
||||
endDate: compactDate(to),
|
||||
});
|
||||
const master = await this.master();
|
||||
const subjects = index(master.subjects);
|
||||
return (raw.homeWorks ?? [])
|
||||
.map((item) => {
|
||||
const subjectId = raw.lessonsById?.[String(item.lessonId)]?.subjectId;
|
||||
return toHomework(item, subjectId === undefined ? undefined : named(subjects.get(subjectId)));
|
||||
})
|
||||
.sort((a, b) => a.due.localeCompare(b.due));
|
||||
}
|
||||
|
||||
/**
|
||||
* What was taught in the previous lessons of a period's series — the class
|
||||
* register's "Unterrichtsinhalt", newest first.
|
||||
*
|
||||
* The parameter is a single `periodId`; a list is rejected as "period 0 not
|
||||
* found".
|
||||
*/
|
||||
async lessonTopics(periodId: number): Promise<UntisTopic[]> {
|
||||
const raw = await this.call<{
|
||||
previousTopics?: { text?: string; periodId?: number; startDateTime?: string; endDateTime?: string }[];
|
||||
}>('getLessonTopic2017', { periodId });
|
||||
return (raw.previousTopics ?? [])
|
||||
.filter((topic) => topic.text?.trim())
|
||||
.map((topic) => {
|
||||
const start = splitLocal(topic.startDateTime ?? '');
|
||||
const end = splitLocal(topic.endDateTime ?? '');
|
||||
return {
|
||||
text: topic.text!.trim(),
|
||||
periodId: topic.periodId ?? periodId,
|
||||
date: start.date,
|
||||
start: start.time,
|
||||
end: end.time,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
/** The school's "Nachrichten des Tages" for one date. Often empty. */
|
||||
async messagesOfDay(date: string): Promise<UntisMessage[]> {
|
||||
const raw = await this.call<{ messages?: { subject?: string; text?: string }[] }>('getMessagesOfDay2017', {
|
||||
date: compactDate(date),
|
||||
});
|
||||
return (raw.messages ?? []).map((message) => ({
|
||||
subject: message.subject?.trim() ?? '',
|
||||
text: message.text?.trim() ?? '',
|
||||
}));
|
||||
}
|
||||
|
||||
/** Master data, refreshed at most every few hours: it changes with the school year. */
|
||||
private async master(): Promise<RawMasterData> {
|
||||
if (this.masterData && Date.now() - this.masterData.at < MASTER_DATA_TTL_MS) return this.masterData.data;
|
||||
const raw = await this.call<RawUserData>('getUserData2017', {});
|
||||
const data = raw.masterData ?? {};
|
||||
this.masterData = { data, at: Date.now() };
|
||||
return data;
|
||||
}
|
||||
|
||||
private toLesson(period: RawPeriod, master: RawMasterData): UntisLesson {
|
||||
const start = splitLocal(period.startDateTime);
|
||||
const end = splitLocal(period.endDateTime);
|
||||
const maps = {
|
||||
SUBJECT: index(master.subjects),
|
||||
TEACHER: index(master.teachers),
|
||||
ROOM: index(master.rooms),
|
||||
CLASS: index(master.klassen),
|
||||
};
|
||||
const of = (type: keyof typeof maps): RawElement[] => (period.elements ?? []).filter((e) => e.type === type);
|
||||
const resolve = (type: keyof typeof maps): UntisName[] =>
|
||||
of(type).map((element) => named(maps[type].get(element.id)) ?? { name: `${type.toLowerCase()} #${element.id}` });
|
||||
// Untis expresses "X instead of Y" by keeping the original in orgId.
|
||||
const replacedBy = (type: keyof typeof maps): UntisName[] =>
|
||||
of(type)
|
||||
.filter((element) => element.orgId !== undefined && element.orgId !== element.id)
|
||||
.map((element) => named(maps[type].get(element.orgId!)) ?? { name: `${type.toLowerCase()} #${element.orgId}` });
|
||||
|
||||
const statuses = period.is ?? [];
|
||||
const note = (value: string | undefined): string | undefined => value?.trim() || undefined;
|
||||
return {
|
||||
periodId: period.id,
|
||||
lessonId: period.lessonId,
|
||||
date: start.date,
|
||||
start: start.time,
|
||||
end: end.time,
|
||||
statuses,
|
||||
cancelled: statuses.includes('CANCELLED'),
|
||||
changed: statuses.includes('IRREGULAR') || statuses.includes('SUBSTITUTION'),
|
||||
subjects: resolve('SUBJECT'),
|
||||
teachers: resolve('TEACHER'),
|
||||
rooms: resolve('ROOM'),
|
||||
classes: resolve('CLASS'),
|
||||
replaced: { subjects: replacedBy('SUBJECT'), teachers: replacedBy('TEACHER'), rooms: replacedBy('ROOM') },
|
||||
notes: {
|
||||
lesson: note(period.text?.lesson),
|
||||
substitution: note(period.text?.substitution),
|
||||
info: note(period.text?.info),
|
||||
},
|
||||
homework: (period.homeWorks ?? []).map((item) => toHomework(item, undefined)),
|
||||
exam: note(period.exam?.name) ?? note(period.exam?.text),
|
||||
online: period.isOnlinePeriod === true,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
// --- helpers -------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* Splits `2026-09-21T11:45Z` into date and time — **as local school time**.
|
||||
*
|
||||
* The `Z` is a lie: the school's time grid starts lessons at 08:00 and the API
|
||||
* reports exactly `08:00Z` for them. Parsing these as UTC would shift every
|
||||
* lesson by an hour or two, so the string is taken apart rather than given to
|
||||
* `new Date`.
|
||||
*/
|
||||
export function splitLocal(value: string): { date: string; time: string } {
|
||||
const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(value);
|
||||
if (!match) {
|
||||
// Dropping an unparsable lesson would silently shorten a school day; a
|
||||
// changed format has to be visible.
|
||||
throw new Error(`WebUntis returned a timestamp in an unexpected format: ${value}`);
|
||||
}
|
||||
return { date: match[1]!, time: match[2]! };
|
||||
}
|
||||
|
||||
function index(list: RawNamed[] | undefined): Map<number, RawNamed> {
|
||||
return new Map((list ?? []).map((entry) => [entry.id, entry]));
|
||||
}
|
||||
|
||||
function named(entry: RawNamed | undefined): UntisName | undefined {
|
||||
if (!entry) return undefined;
|
||||
const full = [entry.firstName, entry.lastName].filter(Boolean).join(' ').trim();
|
||||
const longName = entry.longName?.trim() || full || undefined;
|
||||
return { name: entry.name, ...(longName ? { longName } : {}) };
|
||||
}
|
||||
|
||||
function toHomework(item: RawHomework, subject: UntisName | undefined): UntisHomework {
|
||||
return {
|
||||
id: item.id,
|
||||
lessonId: item.lessonId,
|
||||
assigned: item.startDate,
|
||||
due: item.endDate,
|
||||
text: item.text?.trim() ?? '',
|
||||
...(item.remark?.trim() ? { remark: item.remark.trim() } : {}),
|
||||
completed: item.completed === true,
|
||||
...(subject ? { subject } : {}),
|
||||
attachments: item.attachments?.length ?? 0,
|
||||
};
|
||||
}
|
||||
|
||||
function holidaysOn(master: RawMasterData, date: string): UntisHoliday[] {
|
||||
return (master.holidays ?? [])
|
||||
.filter((holiday) => holiday.startDate <= date && date <= holiday.endDate)
|
||||
.map((holiday) => ({
|
||||
name: holiday.name.trim(),
|
||||
longName: holiday.longName.trim(),
|
||||
start: holiday.startDate,
|
||||
end: holiday.endDate,
|
||||
}));
|
||||
}
|
||||
|
||||
function nextDate(date: string): string {
|
||||
return new Date(Date.parse(`${date}T12:00:00Z`) + 86_400_000).toISOString().slice(0, 10);
|
||||
}
|
||||
|
||||
function byStart(a: UntisLesson, b: UntisLesson): number {
|
||||
return a.start.localeCompare(b.start) || a.periodId - b.periodId;
|
||||
}
|
||||
@@ -13,6 +13,7 @@ import { registerIndexTools } from './tools/index-tools.ts';
|
||||
import { registerSearchTool } from './tools/search.ts';
|
||||
import { registerRoomTools } from './tools/rooms.ts';
|
||||
import { registerSubmissionTools } from './tools/submissions.ts';
|
||||
import { registerUntisTools } from './tools/untis.ts';
|
||||
|
||||
export const SERVER_NAME = 'schulcloud-mcp';
|
||||
export const SERVER_VERSION = '0.1.0';
|
||||
@@ -43,6 +44,14 @@ How the content is organised, and the usual path through it:
|
||||
graded submission, say it was not found rather than that none was given. On a teacher account these
|
||||
tools report other people's submissions too.
|
||||
|
||||
**The timetable is not in Schulcloud.** When the untis_* tools are listed, the school's schedule lives in
|
||||
WebUntis and they are the only way to it: untis_timetable says which lessons a day actually holds, what was
|
||||
cancelled ("Entfall"), what is a substitution ("Vertretung") and what a teacher noted on a period — announced
|
||||
tests are usually in those notes. Schulcloud holds the material for those lessons, so the two go together:
|
||||
take the subject from untis_timetable, then find its course with list_courses. untis_homework is the class
|
||||
register's homework, which is a different list from Schulcloud's tasks; check both. untis_lesson_topics says
|
||||
what previous lessons of a subject actually covered.
|
||||
|
||||
When the user names a topic rather than a course, use search — the API has no search endpoint, so it walks the
|
||||
courses and matches client-side, which takes a few seconds but covers board text and file names.
|
||||
|
||||
@@ -66,6 +75,8 @@ export function createServer(config: Config, services?: Services): { server: Mcp
|
||||
registerSearchTool(server, context);
|
||||
registerSubmissionTools(server, context);
|
||||
registerIndexTools(server, context);
|
||||
// Only when a key is configured: the tools are not offered at all otherwise.
|
||||
registerUntisTools(server, context);
|
||||
registerRawTool(server, context);
|
||||
registerResources(server, context);
|
||||
registerPrompts(server, context);
|
||||
|
||||
@@ -21,6 +21,8 @@ export function registerOverviewTools(server: McpServer, context: ServerContext)
|
||||
annotations: READ_ONLY,
|
||||
},
|
||||
async () => {
|
||||
// Never fails, so the WebUntis half survives a dead Schulcloud session.
|
||||
const untis = await untisLine(context);
|
||||
try {
|
||||
const me = await context.me();
|
||||
return text(
|
||||
@@ -33,13 +35,19 @@ export function registerOverviewTools(server: McpServer, context: ServerContext)
|
||||
`- Instance: ${context.config.baseUrl}`,
|
||||
`- Permissions: ${me.permissions.length}`,
|
||||
tokenExpiryLine(context.config.jwt),
|
||||
untis,
|
||||
]
|
||||
.filter(Boolean)
|
||||
.join('\n'),
|
||||
]),
|
||||
);
|
||||
} catch (error) {
|
||||
return toToolError(error, 'read the current user');
|
||||
const problem = toToolError(error, 'read the current user');
|
||||
// One identity tool now answers for two systems: an expired Schulcloud
|
||||
// token must not hide a working WebUntis key, or "is the server
|
||||
// reachable?" gets a misleadingly total no.
|
||||
if (!untis) return problem;
|
||||
return { ...problem, content: [...problem.content, { type: 'text' as const, text: untis }] };
|
||||
}
|
||||
},
|
||||
);
|
||||
@@ -188,6 +196,26 @@ export function registerOverviewTools(server: McpServer, context: ServerContext)
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The WebUntis side of the account, when configured.
|
||||
*
|
||||
* Never throws: whoami is the connectivity check, so a rejected Untis key has
|
||||
* to be reported *in* the answer rather than replace it — the Schulcloud half
|
||||
* of the report is still true and still useful.
|
||||
*/
|
||||
async function untisLine(context: ServerContext): Promise<string | undefined> {
|
||||
if (!context.untis) return undefined;
|
||||
try {
|
||||
const me = await context.untis.identity();
|
||||
return (
|
||||
`- WebUntis: ${me.displayName} (${me.elementType.toLowerCase()}) at ${me.schoolName}` +
|
||||
` — timetable via untis_timetable`
|
||||
);
|
||||
} catch (error) {
|
||||
return `- WebUntis: **not reachable** — ${error instanceof Error ? error.message : String(error)}`;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* When the server's Schulcloud token runs out. Only a person can renew it, so
|
||||
* the week before is worth saying out loud wherever the account is shown.
|
||||
|
||||
335
src/mcp/tools/untis.ts
Normal file
335
src/mcp/tools/untis.ts
Normal file
@@ -0,0 +1,335 @@
|
||||
/**
|
||||
* The WebUntis tools: the school day itself.
|
||||
*
|
||||
* Registered only when the server is configured for WebUntis, so a deployment
|
||||
* without a key does not offer the model tools that can only fail.
|
||||
*/
|
||||
|
||||
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
||||
import { z } from 'zod';
|
||||
import type { ServerContext } from '../../context.ts';
|
||||
import { addDays, daysBetween, germanDay, germanWeekday, isCalendarDate, schoolToday } from '../../core/dates.ts';
|
||||
import { heading, joinSections } from '../../core/text.ts';
|
||||
import {
|
||||
UntisApiError,
|
||||
type UntisClient,
|
||||
type UntisDay,
|
||||
type UntisHomework,
|
||||
type UntisLesson,
|
||||
} from '../../core/untis.ts';
|
||||
import { failure, text, toToolError } from './result.ts';
|
||||
|
||||
const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
|
||||
|
||||
/** How far past the requested range to look when it turns out to be empty. */
|
||||
const LOOKAHEAD_DAYS = 14;
|
||||
|
||||
/**
|
||||
* Longest range either tool will fetch.
|
||||
*
|
||||
* A school week is about 40 periods, so a term's worth of timetable is
|
||||
* thousands of lines of Markdown — past the point where it helps anyone, and
|
||||
* the answer to "what do I have" is never three months of it.
|
||||
*/
|
||||
const MAX_RANGE_DAYS = 92;
|
||||
|
||||
const dateArgument = z
|
||||
.string()
|
||||
.regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD.')
|
||||
.describe('A date as YYYY-MM-DD.');
|
||||
|
||||
export function registerUntisTools(server: McpServer, context: ServerContext): void {
|
||||
const untis = context.untis;
|
||||
if (!untis) return;
|
||||
|
||||
server.registerTool(
|
||||
'untis_timetable',
|
||||
{
|
||||
title: 'Timetable (WebUntis)',
|
||||
description:
|
||||
'The lessons of a school day or a date range from WebUntis ("Stundenplan"), with cancellations ' +
|
||||
'("Entfall"), substitutions ("Vertretung"), room changes, the notes teachers attach to a period — ' +
|
||||
'announced tests are usually in there — plus homework due and any exam. This is the tool for "what ' +
|
||||
'do I have today/tomorrow", "has anything been cancelled" and for finding which subjects to prepare. ' +
|
||||
'Omit both dates for today. The material for those lessons is in Schulcloud, not here: match the ' +
|
||||
'subject to a course with list_courses. Every lesson line carries its period id for untis_lesson_topics.',
|
||||
inputSchema: {
|
||||
from: dateArgument.optional().describe('First day. Omit for today.'),
|
||||
to: dateArgument.optional().describe('Last day, inclusive. Omit for a single day.'),
|
||||
changesOnly: z
|
||||
.boolean()
|
||||
.default(false)
|
||||
.describe('Only lessons that are cancelled or changed, for "what is different this week".'),
|
||||
},
|
||||
annotations: READ_ONLY,
|
||||
},
|
||||
async ({ from, to, changesOnly }) => {
|
||||
const start = from ?? schoolToday();
|
||||
const end = to ?? start;
|
||||
const unreal = [...new Set([start, end])].filter((value) => !isCalendarDate(value));
|
||||
if (unreal.length > 0) return failure(`Not a date in the calendar: ${unreal.join(', ')}. Use YYYY-MM-DD.`);
|
||||
if (end < start) return failure(`The range ends before it starts: ${start} to ${end}.`);
|
||||
if (daysBetween(start, end) > MAX_RANGE_DAYS) {
|
||||
return failure(
|
||||
`That is ${daysBetween(start, end)} days. Ask for at most ${MAX_RANGE_DAYS} at a time — a term of ` +
|
||||
'timetable is thousands of lines.',
|
||||
);
|
||||
}
|
||||
try {
|
||||
return text(await readTimetable(untis, { from: start, to: end, changesOnly }));
|
||||
} catch (error) {
|
||||
return untisError(error, `read the timetable for ${start}${start === end ? '' : ` to ${end}`}`);
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
server.registerTool(
|
||||
'untis_homework',
|
||||
{
|
||||
title: 'Homework (WebUntis)',
|
||||
description:
|
||||
'Homework recorded in WebUntis\' class register ("Hausaufgaben"), with the day it was set and the day ' +
|
||||
'it is due. Separate from Schulcloud tasks ("Aufgaben") — a teacher uses one or the other, so check ' +
|
||||
'both when the user asks what they have to do: list_tasks covers the Schulcloud side. Defaults to the ' +
|
||||
'next two weeks.',
|
||||
inputSchema: {
|
||||
from: dateArgument.optional().describe('Earliest date to include. Omit for today.'),
|
||||
to: dateArgument.optional().describe('Latest date to include. Omit for two weeks ahead.'),
|
||||
includeCompleted: z.boolean().default(false).describe('Also list homework already ticked off.'),
|
||||
},
|
||||
annotations: READ_ONLY,
|
||||
},
|
||||
async ({ from, to, includeCompleted }) => {
|
||||
const start = from ?? schoolToday();
|
||||
const end = to ?? addDays(start, 14);
|
||||
const unreal = [...new Set([start, end])].filter((value) => !isCalendarDate(value));
|
||||
if (unreal.length > 0) return failure(`Not a date in the calendar: ${unreal.join(', ')}. Use YYYY-MM-DD.`);
|
||||
if (end < start) return failure(`The range ends before it starts: ${start} to ${end}.`);
|
||||
if (daysBetween(start, end) > MAX_RANGE_DAYS) {
|
||||
return failure(
|
||||
`That is ${daysBetween(start, end)} days. Ask for at most ${MAX_RANGE_DAYS} at a time — a term of ` +
|
||||
'timetable is thousands of lines.',
|
||||
);
|
||||
}
|
||||
try {
|
||||
const all = await untis.homework(start, end);
|
||||
const items = includeCompleted ? all : all.filter((item) => !item.completed);
|
||||
if (items.length === 0) {
|
||||
return text(
|
||||
`No homework in WebUntis between ${germanDay(start)} and ${germanDay(end)}` +
|
||||
`${includeCompleted ? '' : ' that is still open'}. Schulcloud tasks are separate — try list_tasks.`,
|
||||
);
|
||||
}
|
||||
return text(
|
||||
joinSections([
|
||||
heading(2, `Hausaufgaben ${germanDay(start)} – ${germanDay(end)} (${items.length})`),
|
||||
items.map(formatHomework).join('\n'),
|
||||
]),
|
||||
);
|
||||
} catch (error) {
|
||||
return untisError(error, 'read homework from WebUntis');
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
server.registerTool(
|
||||
'untis_lesson_topics',
|
||||
{
|
||||
title: 'What was taught (WebUntis)',
|
||||
description:
|
||||
'The class register\'s record of what previous lessons of one series actually covered ' +
|
||||
'("Unterrichtsinhalt"), newest first. Use it to prepare for the next lesson of a subject: pass the ' +
|
||||
'period id of an upcoming lesson from untis_timetable and it answers "where did we get to". Says ' +
|
||||
'nothing about material or homework — that is Schulcloud and untis_homework.',
|
||||
inputSchema: {
|
||||
periodId: z
|
||||
.number()
|
||||
.int()
|
||||
.describe('The period id of a lesson, as untis_timetable prints it in backticks.'),
|
||||
limit: z.number().int().min(1).max(50).default(10).describe('How many previous lessons to list.'),
|
||||
},
|
||||
annotations: READ_ONLY,
|
||||
},
|
||||
async ({ periodId, limit }) => {
|
||||
try {
|
||||
const topics = await untis.lessonTopics(periodId);
|
||||
if (topics.length === 0) {
|
||||
return text(
|
||||
`No lesson contents recorded for period ${periodId}. Either the class register is empty for this ` +
|
||||
'series or the teacher does not fill it in.',
|
||||
);
|
||||
}
|
||||
return text(
|
||||
joinSections([
|
||||
heading(2, `Unterrichtsinhalte (${Math.min(limit, topics.length)} of ${topics.length})`),
|
||||
topics
|
||||
.slice(0, limit)
|
||||
.map((topic) => `- ${germanDay(topic.date)} ${topic.start}–${topic.end}: ${topic.text}`)
|
||||
.join('\n'),
|
||||
]),
|
||||
);
|
||||
} catch (error) {
|
||||
return untisError(error, `read what was taught before period ${periodId}`);
|
||||
}
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* The timetable for a range as Markdown: what `untis_timetable` returns, and
|
||||
* what the Tagesvorbereitung prompt attaches, so an attached day reads exactly
|
||||
* like a fetched one.
|
||||
*/
|
||||
export async function readTimetable(
|
||||
untis: UntisClient,
|
||||
options: { from: string; to: string; changesOnly?: boolean },
|
||||
): Promise<string> {
|
||||
const { from: start, to: end, changesOnly = false } = options;
|
||||
// One request covers the range plus a lookahead, so an empty range can still
|
||||
// answer "your next lessons are on …" without a second call.
|
||||
const table = await untis.timetable(start, addDays(end, LOOKAHEAD_DAYS));
|
||||
const asked = table.days.filter((day) => day.date <= end);
|
||||
// With changesOnly a week of untouched days is noise, so only the days that
|
||||
// changed are listed at all.
|
||||
const shown = changesOnly
|
||||
? asked
|
||||
.map((day) => ({ ...day, lessons: day.lessons.filter((l) => l.cancelled || l.changed) }))
|
||||
.filter((day) => day.lessons.length > 0)
|
||||
: asked;
|
||||
const total = shown.reduce((sum, day) => sum + day.lessons.length, 0);
|
||||
|
||||
// The Nachrichten des Tages belong to a single date; skip the call for a
|
||||
// range, and never let it cost the timetable.
|
||||
const messages = start === end && !changesOnly ? await untis.messagesOfDay(start).catch(() => []) : [];
|
||||
|
||||
const nextWithLessons = table.days.find((day) => day.date > end && day.lessons.length > 0);
|
||||
return joinSections([
|
||||
heading(2, start === end ? `${germanWeekday(start)}, ${germanDay(start)}` : `${germanDay(start)} – ${germanDay(end)}`),
|
||||
changesOnly && total > 0 ? '_Only cancellations and changes._' : undefined,
|
||||
changesOnly && total === 0
|
||||
? `_Nothing cancelled or changed${start === end ? '' : ' on any day of this range'}._`
|
||||
: undefined,
|
||||
...shown.map((day) => formatDay(day, start !== end)),
|
||||
// Only about lessons: "your next change is on Friday" would be an odd thing
|
||||
// to say, and misleading when nothing has changed.
|
||||
total === 0 && !changesOnly && nextWithLessons
|
||||
? `**Next lessons:** ${germanWeekday(nextWithLessons.date)}, ${germanDay(nextWithLessons.date)} ` +
|
||||
`(${nextWithLessons.lessons.length} lesson(s)) — ask again with from="${nextWithLessons.date}".`
|
||||
: undefined,
|
||||
messages.length > 0
|
||||
? joinSections([
|
||||
heading(3, 'Nachrichten des Tages'),
|
||||
messages.map((message) => `- ${[message.subject, message.text].filter(Boolean).join(': ')}`).join('\n'),
|
||||
])
|
||||
: undefined,
|
||||
]);
|
||||
}
|
||||
|
||||
// --- formatting ----------------------------------------------------------
|
||||
|
||||
function formatDay(day: UntisDay, withHeading: boolean): string {
|
||||
const holidays = day.holidays.map((holiday) => `_${holiday.longName || holiday.name}_`).join(', ');
|
||||
// A day with no lessons and no holiday is normal at a vocational school —
|
||||
// the weeks in the company have no timetable — so say that rather than
|
||||
// leaving a bare "nothing", which reads like a failed lookup.
|
||||
const body =
|
||||
day.lessons.length > 0
|
||||
? day.lessons.map((lesson) => formatLesson(lesson, day.lessons)).join('\n')
|
||||
: holidays
|
||||
? '_No lessons._'
|
||||
: '_No lessons. Not a holiday either — a company phase or a free day._';
|
||||
return joinSections([
|
||||
withHeading ? heading(3, `${germanWeekday(day.date)}, ${germanDay(day.date)}`) : undefined,
|
||||
holidays || undefined,
|
||||
body,
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* One lesson as a line.
|
||||
*
|
||||
* A substitution arrives as two periods in the same slot — the original marked
|
||||
* CANCELLED and the replacement marked IRREGULAR — rather than as one period
|
||||
* with a changed teacher, so the replacement names what it stands in for by
|
||||
* looking at what was cancelled beside it.
|
||||
*/
|
||||
function formatLesson(lesson: UntisLesson, sameDay: UntisLesson[]): string {
|
||||
const names = (list: { name: string; longName?: string }[]): string => list.map((entry) => entry.name).join(', ');
|
||||
const subject = lesson.subjects[0];
|
||||
const subjectLabel = subject
|
||||
? `**${subject.name}**${subject.longName ? ` (${subject.longName})` : ''}`
|
||||
: '**(no subject)**';
|
||||
|
||||
const instead = [
|
||||
...lesson.replaced.teachers.map((entry) => entry.name),
|
||||
...(lesson.changed ? replacedBeside(lesson, sameDay) : []),
|
||||
];
|
||||
const status = lesson.cancelled
|
||||
? ' — **Entfall**'
|
||||
: lesson.changed
|
||||
? ` — **Vertretung**${instead.length > 0 ? ` (statt ${[...new Set(instead)].join(', ')})` : ''}`
|
||||
: '';
|
||||
const room = lesson.rooms.length > 0 ? ` · Raum ${names(lesson.rooms)}` : '';
|
||||
const replacedRoom = lesson.replaced.rooms.length > 0 ? ` (statt ${names(lesson.replaced.rooms)})` : '';
|
||||
const teachers = lesson.teachers.length > 0 ? ` · ${lesson.teachers.map(withFullName).join(', ')}` : '';
|
||||
const unknownStatus = lesson.statuses.filter((value) => !['REGULAR', 'CANCELLED', 'IRREGULAR'].includes(value));
|
||||
|
||||
const notes = [
|
||||
lesson.exam ? `**Prüfung:** ${lesson.exam}` : undefined,
|
||||
lesson.notes.info,
|
||||
lesson.notes.substitution ? `Vertretungstext: ${lesson.notes.substitution}` : undefined,
|
||||
lesson.notes.lesson,
|
||||
...lesson.homework.map((item) => `Hausaufgabe bis ${germanDay(item.due)}: ${item.text}`),
|
||||
unknownStatus.length > 0 ? `Status: ${unknownStatus.join(', ')}` : undefined,
|
||||
lesson.online ? 'Online' : undefined,
|
||||
].filter((note): note is string => Boolean(note));
|
||||
|
||||
const head =
|
||||
`- ${lesson.start}–${lesson.end} ${subjectLabel}${room}${replacedRoom}${teachers}${status} ` +
|
||||
`\`${lesson.periodId}\``;
|
||||
return notes.length > 0 ? `${head}\n${notes.map((note) => ` - ${note}`).join('\n')}` : head;
|
||||
}
|
||||
|
||||
/** The teachers of a cancelled lesson in the same slot: who this one stands in for. */
|
||||
function replacedBeside(lesson: UntisLesson, sameDay: UntisLesson[]): string[] {
|
||||
return sameDay
|
||||
.filter((other) => other.cancelled && other.start === lesson.start && other.periodId !== lesson.periodId)
|
||||
.flatMap((other) => other.teachers.map((teacher) => teacher.name));
|
||||
}
|
||||
|
||||
function withFullName(entry: { name: string; longName?: string }): string {
|
||||
return entry.longName ? `${entry.name} (${entry.longName})` : entry.name;
|
||||
}
|
||||
|
||||
function formatHomework(item: UntisHomework): string {
|
||||
const subject = item.subject ? ` — ${item.subject.name}${item.subject.longName ? ` (${item.subject.longName})` : ''}` : '';
|
||||
const done = item.completed ? ' [erledigt]' : '';
|
||||
const remark = item.remark ? ` — ${item.remark}` : '';
|
||||
const attachments = item.attachments > 0 ? ` (${item.attachments} attachment(s))` : '';
|
||||
return `- **bis ${germanDay(item.due)}**${subject}: ${item.text}${remark}${attachments}${done} (set ${germanDay(item.assigned)})`;
|
||||
}
|
||||
|
||||
/**
|
||||
* WebUntis failures the user has to act on, separated from the rest.
|
||||
*
|
||||
* A rejected key and a wrong clock are the two that no retry fixes, and they
|
||||
* are indistinguishable from "no lessons" unless they are named.
|
||||
*/
|
||||
function untisError(error: unknown, action: string) {
|
||||
if (error instanceof UntisApiError) {
|
||||
if (error.isAuthFailure) {
|
||||
return failure(
|
||||
`WebUntis rejected the server's key while trying to ${action}.\n\n` +
|
||||
'The key from WebUntis → Profil → Freigaben → Untis Mobile has been regenerated or revoked. ' +
|
||||
'Put the current one in UNTIS_SECRET and restart the server.',
|
||||
);
|
||||
}
|
||||
if (error.isClockSkew) {
|
||||
return failure(
|
||||
`WebUntis refused the one-time code while trying to ${action}: the server's clock is too far off.\n\n` +
|
||||
'The code is time-based, so the host needs a working NTP sync.',
|
||||
);
|
||||
}
|
||||
}
|
||||
return toToolError(error, action);
|
||||
}
|
||||
@@ -3,6 +3,7 @@ import { SchulcloudClient } from './core/client.ts';
|
||||
import type { SessionKeepalive } from './core/keepalive.ts';
|
||||
import { FileManager } from './core/legacy-files.ts';
|
||||
import { SessionToken } from './core/session-token.ts';
|
||||
import { UntisClient } from './core/untis.ts';
|
||||
import { Indexer } from './indexer/indexer.ts';
|
||||
import { Store } from './store/store.ts';
|
||||
|
||||
@@ -27,6 +28,12 @@ export interface Services {
|
||||
indexer: Indexer | undefined;
|
||||
/** The Schulcloud token, which `/api/token` can replace without a restart. */
|
||||
session: SessionToken;
|
||||
/**
|
||||
* WebUntis, when configured. Process-wide so its master data — 140 subjects,
|
||||
* 216 teachers, every holiday of the school year — is fetched once rather
|
||||
* than per MCP session.
|
||||
*/
|
||||
untis: UntisClient | undefined;
|
||||
/**
|
||||
* Set by the entry point that runs one, for status reports. Created there
|
||||
* rather than here because each entry point logs to a different stream.
|
||||
@@ -44,6 +51,7 @@ export async function createServices(config: Config): Promise<Services> {
|
||||
const files = new FileManager(client);
|
||||
const store = await Store.open(config.databaseUrl);
|
||||
const indexer = store ? new Indexer(client, store, config) : undefined;
|
||||
const untis = config.untis ? new UntisClient(config.untis, config.requestTimeoutMs) : undefined;
|
||||
|
||||
if (!store) {
|
||||
console.warn(
|
||||
@@ -51,7 +59,7 @@ export async function createServices(config: Config): Promise<Services> {
|
||||
'/files, /manifest and refresh_index are unavailable. Set DATABASE_URL to enable them.',
|
||||
);
|
||||
}
|
||||
return { config, client, files, store, indexer, session };
|
||||
return { config, client, files, store, indexer, session, untis };
|
||||
}
|
||||
|
||||
export async function closeServices(services: Services): Promise<void> {
|
||||
|
||||
Reference in New Issue
Block a user