somtoday-mcp 0.1.1 → 0.3.0

package/README.md

@@ -17,11 +17,11 @@ It runs locally on your computer over stdio. Nothing is sent anywhere except to
 | Tool                  | What you get                                                                                                                                                                                                                                                             |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `whoami`              | Your school label, the linked children with their numeric ids, and which portal sections are visible to you.                                                                                                                                                             |
-| `lessons`             | The timetable for one day, and whether that day is a school holiday.                                                                                                                                                                                                     |
+| `lessons`             | The timetable for one day, and whether that day is a school holiday. Each lesson has `type` (`ROOSTERTOETS`/`EXAMEN` = test) and `uitgevallen` when cancelled; homework and test topics come from `homework` for the same date.                                          |
 | `homework`            | What to do and learn on which day: every study-planner item for a date range (default today + 6 days, max 42), grouped by day, with description, learning goals, time estimate, test type, attachments (links), external links, hand-in window/status and the done tick. |
 | `grades`              | The most recent results (up to 30) and averages per subject.                                                                                                                                                                                                             |
 | `assignments`         | All hand-in assignments with window, status (upcoming, to do, waiting for review, approved), late flag, description, attachments and links. `status=open` keeps the ones still to do.                                                                                    |
-| `assignment_detail`   | Submissions (date, status, file or link) and teacher reactions for one assignment.                                                                                                                                                                                       |
+| `assignment_detail`   | One assignment as the parent portal shows it: instruction, files, links, hand-in window and status. Submitted files and teacher reactions are only visible in the student's own session.                                                                                 |
 | `study_material`      | Study material per subject: lesson material from the planner by date, year attachments by folder (file links), external links, and methods/publisher links. No arguments lists the subjects; `vak` picks one; `all=true` fetches every subject.                          |
 | `schedule`            | Timetable for a date range (default today + 6 days, max 42): time, lesson hour, subject, room, teachers, type (test, exam, parent evening …), lesson notes, changes and cancellations, attachments, holidays.                                                            |
 | `grades_latest`       | Newest results first with subject, column, description, grade, weight, test type, period, date, remarks and resits; `limit` (default 50, max 1000) and `dossier=examen` for SE results.                                                                                  |
@@ -35,7 +35,8 @@ It runs locally on your computer over stdio. Nothing is sent anywhere except to
 | `children`            | Linked children with profile, class, school data (mentors, year, programme), current placement and visible portal sections.                                                                                                                                              |
 | `school_info`         | School contact data and the school's information pages; `paginaId` opens one page.                                                                                                                                                                                       |
 | `teachers`            | Staff you can message, with the subjects they teach your child.                                                                                                                                                                                                          |
-| `signing_requests`    | Digital signing requests (read-only; nothing is signed).                                                                                                                                                                                                                 |
+| `signing_requests`    | Digital signing requests (read-only; nothing is signed). Each item has `document: {tool: "signing_document", id, available}`.                                                                                                                                            |
+| `signing_document`    | The (signed) PDF of one signing request, as the portal's download button: pass `document.id`; returns extracted text, max 10 MB. Fetched with your login token, so it is not a `fileUrl` for `download_attachment`.                                                      |
 | `parent_evening`      | Parent-evening details (slots, teachers); finds invitations in your messages (read-only; nothing is booked).                                                                                                                                                             |
 | `consents`            | Consents such as use of photos, as set in the portal (read-only).                                                                                                                                                                                                        |
 | `download_attachment` | Read an attachment by `fileUrl`: https Somtoday hosts only (extend with `SOMTODAY_MCP_ATTACHMENT_HOSTS`), max 10 MB, no token sent; text from PDF/text/HTML/CSV/JSON.                                                                                                    |
@@ -43,9 +44,11 @@ It runs locally on your computer over stdio. Nothing is sent anywhere except to
 
 - `lessons` takes an optional `date` (`YYYY-MM-DD`, Europe/Amsterdam) and defaults to **tomorrow**. Range tools take `date`, or `from`/`to`.
 - If more than one child is linked to your account, pass `leerlingId` (the numeric id from `whoami`).
+- `assignments` with `status=open` hides past-due items that expect no digital hand-in (`inleveringenVerwacht: 0`, e.g. handed in on paper) and reports the count in `verborgenZonderInlevering`; pass `includeNoHandIn=true` to see them.
+- `assignments` merges near-duplicates (same subject, topic, hand-in window and status, e.g. one assignment published to two groups) into one item with the other ids in `duplicaatToekenningIds`; pass `dedupe=false` to list them separately.
 - If a section is switched off for your account, the tool says so and does not call that part of the API.
 
-Not included: news, messages, absence reporting, parent-evening scheduling, uploads, or anything that changes data.
+Not included: anything that changes data, such as sending messages, reporting absence, booking parent-evening slots, signing requests, or uploading hand-ins.
 
 ## Read-only and privacy
 
@@ -59,9 +62,9 @@ Timetables, homework, and grades are personal data about children. Keep the outp
 
 ## Install
 
-Requires Node.js 22 or newer.
+Requires Node.js 22 or newer (the PDF text extraction used by `download_attachment` and `signing_document` does not run on Node 20).
 
-> The package is not published to npm yet. Until it is, use the "From a checkout" steps below; `npx somtoday-mcp` will not find it.
+Published on npm as [`somtoday-mcp`](https://www.npmjs.com/package/somtoday-mcp), with [provenance](https://docs.npmjs.com/generating-provenance-statements) from this repository's release workflow.
 
 ```bash
 npx -y somtoday-mcp            # start the MCP server (used by your MCP client)

package/dist/api/assignments.d.ts

@@ -5,11 +5,29 @@ export type AssignmentView = StudiewijzerItemView & {
     categorie?: AssignmentCategory;
     teLaat?: boolean;
 };
-/** Same buckets as the portal's assignment list. */
+/**
+ * Same buckets as the portal's assignment list. `teLaat` is always a boolean
+ * once an item has a window: true only for an open hand-in (IN_TE_LEVEREN)
+ * whose deadline has passed.
+ */
 export declare function categorize(item: StudiewijzerItemView, now: Date): {
     categorie?: AssignmentCategory;
     teLaat?: boolean;
 };
+/**
+ * A past-due open item where Somtoday expects no digital hand-in
+ * (`inleveringenVerwacht: 0`, e.g. handed in on paper or in class). It stays
+ * IN_TE_LEVEREN with teLaat forever, so `status=open` hides it by default.
+ */
+export declare function isPastWithoutHandIn(item: AssignmentView): boolean;
+/**
+ * Collapse near-duplicates: the same assignment published to several groups
+ * shows up with different toekenningIds but the same subject, topic, hand-in
+ * window and category. Keeps the first and lists the others' ids.
+ */
+export declare function dedupeAssignments(items: AssignmentView[]): Array<AssignmentView & {
+    duplicaatToekenningIds?: number[];
+}>;
 export declare function fetchAssignments(client: ApiClient, leerlingId: number, now: Date): Promise<AssignmentView[]>;
 /**
  * One assignment from exactly the list `assignments` returns (same request,

package/dist/api/assignments.js

@@ -3,7 +3,11 @@ import { htmlToPlain } from "../html.js";
 import { handInQuery } from "./homework.js";
 import { linkId } from "./simplify.js";
 import { compact, compactItem, mapAttachment, mapStudiewijzerItem, } from "./studiewijzer.js";
-/** Same buckets as the portal's assignment list. */
+/**
+ * Same buckets as the portal's assignment list. `teLaat` is always a boolean
+ * once an item has a window: true only for an open hand-in (IN_TE_LEVEREN)
+ * whose deadline has passed.
+ */
 export function categorize(item, now) {
     const start = item.inlevermoment?.start
         ? new Date(item.inlevermoment.start)
@@ -14,20 +18,65 @@ export function categorize(item, now) {
     if (!start)
         return {};
     if (start > now)
-        return { categorie: "AANKOMEND" };
+        return { categorie: "AANKOMEND", teLaat: false };
     const status = item.inleverStatus;
     if (!status || status === "HEROPEND") {
         return {
             categorie: "IN_TE_LEVEREN",
-            teLaat: eind ? eind < now : undefined,
+            teLaat: eind ? eind < now : false,
         };
     }
     if (status === "TE_BEOORDELEN" || status === "IN_BEHANDELING") {
-        return { categorie: "IN_AFWACHTING" };
+        return { categorie: "IN_AFWACHTING", teLaat: false };
     }
     if (status === "AKKOORD")
-        return { categorie: "AKKOORD" };
-    return {};
+        return { categorie: "AKKOORD", teLaat: false };
+    return { teLaat: false };
+}
+/**
+ * A past-due open item where Somtoday expects no digital hand-in
+ * (`inleveringenVerwacht: 0`, e.g. handed in on paper or in class). It stays
+ * IN_TE_LEVEREN with teLaat forever, so `status=open` hides it by default.
+ */
+export function isPastWithoutHandIn(item) {
+    return (item.categorie === "IN_TE_LEVEREN" &&
+        item.teLaat === true &&
+        item.inlevermoment?.inleveringenVerwacht === 0);
+}
+/**
+ * Collapse near-duplicates: the same assignment published to several groups
+ * shows up with different toekenningIds but the same subject, topic, hand-in
+ * window and category. Keeps the first and lists the others' ids.
+ */
+export function dedupeAssignments(items) {
+    const kept = new Map();
+    const out = [];
+    for (const item of items) {
+        const key = item.onderwerp
+            ? JSON.stringify([
+                item.vakUuid ?? item.vak ?? "",
+                item.onderwerp.trim().toLowerCase(),
+                item.inlevermoment?.start ?? "",
+                item.inlevermoment?.eind ?? "",
+                item.categorie ?? "",
+            ])
+            : undefined;
+        const first = key ? kept.get(key) : undefined;
+        if (first) {
+            if (item.toekenningId !== undefined) {
+                first.duplicaatToekenningIds = [
+                    ...(first.duplicaatToekenningIds ?? []),
+                    item.toekenningId,
+                ];
+            }
+            continue;
+        }
+        const copy = { ...item };
+        if (key)
+            kept.set(key, copy);
+        out.push(copy);
+    }
+    return out;
 }
 export async function fetchAssignments(client, leerlingId, now) {
     const { items } = await client.getAll("/studiewijzeritemdagtoekenningen", handInQuery(leerlingId));

package/dist/api/client.d.ts

@@ -8,6 +8,8 @@ export type ApiResponse<T> = {
 export type GetOptions = {
     /** `json` for the endpoints that expect plain application/json (news, school info, signing). */
     accept?: "platinum" | "json";
+    /** Raw Accept header; overrides `accept` (binary downloads such as `application/pdf`). */
+    acceptHeader?: string;
     /** Inclusive item range, sent as `Range: items=start-end`. */
     range?: {
         start: number;
@@ -40,6 +42,12 @@ export declare class ApiClient {
     private readonly fetchFn;
     constructor(session: SessionManager, fetchFn?: FetchFn);
     get<T>(path: string, query?: URLSearchParams, options?: GetOptions): Promise<ApiResponse<T>>;
+    /**
+     * Authenticated binary GET (e.g. a signed PDF). Returns the raw response
+     * after the same token-renewal retry as `get`; the caller reads the body.
+     */
+    getRaw(path: string, acceptHeader: string, query?: URLSearchParams): Promise<Response>;
+    private authorizedGet;
     /**
      * Fetch every item of a list endpoint the way the portal does: request
      * `Range: items=a-b` in pages of at most 100 and continue while

package/dist/api/client.js

@@ -25,19 +25,40 @@ export class ApiClient {
         this.fetchFn = fetchFn;
     }
     async get(path, query, options = {}) {
+        const response = await this.authorizedGet(path, query, options);
+        return this.read(response, path);
+    }
+    /**
+     * Authenticated binary GET (e.g. a signed PDF). Returns the raw response
+     * after the same token-renewal retry as `get`; the caller reads the body.
+     */
+    async getRaw(path, acceptHeader, query) {
+        const response = await this.authorizedGet(path, query, { acceptHeader });
+        if (response.status === 403 || response.status === 404) {
+            await response.body?.cancel();
+            throw new ApiNotAvailableError(response.status, path);
+        }
+        if (response.status !== 200) {
+            await response.body?.cancel();
+            throw new Error(`API HTTP ${response.status}`);
+        }
+        return response;
+    }
+    async authorizedGet(path, query, options) {
         const url = await this.url(path, query);
         const first = await this.send(url, options);
         if (!(await shouldRetryWithNewToken(first.response))) {
-            return this.read(first.response, path);
+            return first.response;
         }
         // 401, or a 403 without a body: renew the access token (once) and retry once.
+        await first.response.body?.cancel().catch(() => undefined);
         await this.session.refreshAfterRejection(first.token);
         const retry = await this.send(url, options);
         if (retry.response.status === 401) {
             this.session.clearAccessToken();
             throw new LoginRequiredError("API rejected a freshly renewed token");
         }
-        return this.read(retry.response, path);
+        return retry.response;
     }
     /**
      * Fetch every item of a list endpoint the way the portal does: request
@@ -94,7 +115,8 @@ export class ApiClient {
         const token = await this.session.getAccessToken();
         const headers = {
             Authorization: `Bearer ${token}`,
-            Accept: options.accept === "json" ? ACCEPT_JSON : ACCEPT,
+            Accept: options.acceptHeader ??
+                (options.accept === "json" ? ACCEPT_JSON : ACCEPT),
         };
         if (options.range) {
             headers.Range = `items=${options.range.start}-${options.range.end}`;

package/dist/api/download.d.ts

@@ -19,3 +19,5 @@ export declare function downloadAttachment(fetchFn: typeof fetch, rawUrl: string
     maxBytes?: number;
     env?: string;
 }): Promise<Attachment>;
+/** Read a successful response (size-capped) and extract text where possible. */
+export declare function readFile(response: Response, url: URL, maxBytes?: number, fallbackName?: string): Promise<Attachment>;

package/dist/api/download.js

@@ -26,7 +26,7 @@ export function isAllowedUrl(raw, env = process.env[ATTACHMENT_HOSTS_ENV]) {
         ? host.endsWith(rule) && host.length > rule.length
         : host === rule);
 }
-function fileNameFrom(disposition, url) {
+function fileNameFrom(disposition, url, fromPath = true) {
     const match = disposition?.match(/filename\*?=(?:UTF-8'')?"?([^";]+)"?/i);
     if (match?.[1]) {
         try {
@@ -36,6 +36,8 @@ function fileNameFrom(disposition, url) {
             return match[1];
         }
     }
+    if (!fromPath)
+        return undefined;
     const last = url.pathname.split("/").pop();
     return last ? decodeURIComponent(last) : undefined;
 }
@@ -111,43 +113,49 @@ export async function downloadAttachment(fetchFn, rawUrl, options = {}) {
             await response.body?.cancel();
             throw new AttachmentError(`download failed: HTTP ${response.status}`);
         }
-        const bytes = await readCapped(response, options.maxBytes ?? ATTACHMENT_MAX_BYTES);
-        const contentType = (response.headers.get("content-type") ?? "application/octet-stream")
-            .split(";")[0]
-            .trim()
-            .toLowerCase();
-        const fileName = fileNameFrom(response.headers.get("content-disposition"), url);
-        const base = {
-            host: url.hostname,
-            contentType,
-            fileName,
-            bytes: bytes.byteLength,
-        };
-        const isPdf = contentType === "application/pdf" ||
-            (contentType === "application/octet-stream" &&
-                /\.pdf$/i.test(fileName ?? ""));
-        if (isPdf) {
-            try {
-                const { text, pages } = await extractPdf(bytes);
-                return {
-                    ...base,
-                    pages,
-                    ...truncate(text),
-                    note: text ? undefined : "PDF has no text layer (scanned?)",
-                };
-            }
-            catch {
-                return { ...base, note: "could not read PDF text" };
-            }
+        return readFile(response, url, options.maxBytes);
+    }
+}
+/** Read a successful response (size-capped) and extract text where possible. */
+export async function readFile(response, url, maxBytes = ATTACHMENT_MAX_BYTES, fallbackName) {
+    const bytes = await readCapped(response, maxBytes);
+    const contentType = (response.headers.get("content-type") ?? "application/octet-stream")
+        .split(";")[0]
+        .trim()
+        .toLowerCase();
+    const fileName = fileNameFrom(response.headers.get("content-disposition"), url, false) ??
+        fallbackName ??
+        fileNameFrom(null, url);
+    const base = {
+        host: url.hostname,
+        contentType,
+        fileName,
+        bytes: bytes.byteLength,
+    };
+    const isPdf = contentType === "application/pdf" ||
+        (contentType === "application/octet-stream" &&
+            /\.pdf$/i.test(fileName ?? ""));
+    if (isPdf) {
+        try {
+            const { text, pages } = await extractPdf(bytes);
+            return {
+                ...base,
+                pages,
+                ...truncate(text),
+                note: text ? undefined : "PDF has no text layer (scanned?)",
+            };
         }
-        if (TEXT_TYPES.test(contentType)) {
-            const decoded = new TextDecoder("utf-8").decode(bytes);
-            const text = /html/.test(contentType) ? htmlToPlain(decoded) : decoded;
-            return { ...base, ...truncate(text) };
+        catch {
+            return { ...base, note: "could not read PDF text" };
         }
-        return {
-            ...base,
-            note: "binary file; text extraction not supported for this type",
-        };
     }
+    if (TEXT_TYPES.test(contentType)) {
+        const decoded = new TextDecoder("utf-8").decode(bytes);
+        const text = /html/.test(contentType) ? htmlToPlain(decoded) : decoded;
+        return { ...base, ...truncate(text) };
+    }
+    return {
+        ...base,
+        note: "binary file; text extraction not supported for this type",
+    };
 }

package/dist/api/lessons.d.ts

@@ -12,6 +12,9 @@ export type LessonView = {
         afkorting?: string;
     };
     docentNamen?: string[];
+    /** Appointment type, e.g. LES, ROOSTERTOETS (a test in the timetable), EXAMEN. */
+    type?: string;
+    uitgevallen?: boolean;
 };
 export declare function filterLessonsForDate(items: AfspraakItem[], ymd: string): LessonView[];
 export declare function holidaysOnDate(items: HolidayItem[], ymd: string): HolidayItem[];

package/dist/api/lessons.js

@@ -1,4 +1,5 @@
 import { dateInInclusiveRange, isoWeekParts, sameAmsterdamDate, } from "../dates.js";
+import { CANCELLED_STATUS } from "./schedule.js";
 export function filterLessonsForDate(items, ymd) {
     return items
         .filter((item) => item.beginDatumTijd && sameAmsterdamDate(item.beginDatumTijd, ymd))
@@ -13,6 +14,8 @@ export function filterLessonsForDate(items, ymd) {
             ? { naam: item.vak.naam, afkorting: item.vak.afkorting }
             : undefined,
         docentNamen: item.docentNamen,
+        type: item.afspraakItemType,
+        uitgevallen: item.statusNotifications?.some((note) => note.status === CANCELLED_STATUS) || undefined,
     }));
 }
 export function holidaysOnDate(items, ymd) {

package/dist/api/misc.d.ts

@@ -1,6 +1,22 @@
 import type { ApiClient } from "./client.js";
+import { type Attachment } from "./download.js";
+/**
+ * How to fetch the document behind a signing request. The portal downloads it
+ * from `begeleiden/ondertekenverzoeken/{id}/document` (PDF, needs the login
+ * token), so it is not a public fileUrl: use the `signing_document` tool.
+ */
+export declare function signingDocumentRef(item: unknown): {
+    tool: "signing_document";
+    id: string | number;
+    available: boolean;
+} | undefined;
 /** Digital signing requests (`begeleiden/ondertekenverzoeken`, plain JSON). Read-only: signing is never done here. */
 export declare function fetchSigningRequests(client: ApiClient): Promise<unknown[]>;
+/**
+ * The (signed) document of one signing request, as the portal's
+ * "download document" button fetches it. Read-only GET with the login token.
+ */
+export declare function fetchSigningDocument(client: ApiClient, id: string): Promise<Attachment>;
 /** Consents (photo use etc.) as shown under Voorkeuren → Toestemmingen. Read-only. */
 export declare function fetchConsents(client: ApiClient): Promise<unknown[]>;
 export declare function fetchParentEvening(client: ApiClient, id: string): Promise<unknown>;

package/dist/api/misc.js

@@ -1,5 +1,25 @@
+import { readFile } from "./download.js";
 import { fetchConversations } from "./messages.js";
 import { simplify } from "./simplify.js";
+/** Statuses where the portal shows no document (still to sign, withdrawn, expired). */
+const NO_DOCUMENT_STATUSES = new Set(["OPENSTAAND", "INGETROKKEN", "VERLOPEN"]);
+/**
+ * How to fetch the document behind a signing request. The portal downloads it
+ * from `begeleiden/ondertekenverzoeken/{id}/document` (PDF, needs the login
+ * token), so it is not a public fileUrl: use the `signing_document` tool.
+ */
+export function signingDocumentRef(item) {
+    const source = item;
+    const id = source?.id;
+    if (typeof id !== "string" && typeof id !== "number")
+        return undefined;
+    const status = typeof source?.status === "string" ? source.status : "";
+    return {
+        tool: "signing_document",
+        id,
+        available: !NO_DOCUMENT_STATUSES.has(status.toUpperCase()),
+    };
+}
 /** Digital signing requests (`begeleiden/ondertekenverzoeken`, plain JSON). Read-only: signing is never done here. */
 export async function fetchSigningRequests(client) {
     const { body } = await client.get("/begeleiden/ondertekenverzoeken", undefined, {
@@ -8,7 +28,20 @@ export async function fetchSigningRequests(client) {
     const items = Array.isArray(body)
         ? body
         : (body?.items ?? []);
-    return items.map((item) => simplify(item) ?? {});
+    return items.map((item) => {
+        const out = (simplify(item) ?? {});
+        const document = signingDocumentRef(out);
+        return document ? { ...out, document } : out;
+    });
+}
+/**
+ * The (signed) document of one signing request, as the portal's
+ * "download document" button fetches it. Read-only GET with the login token.
+ */
+export async function fetchSigningDocument(client, id) {
+    const path = `/begeleiden/ondertekenverzoeken/${encodeURIComponent(id)}/document`;
+    const response = await client.getRaw(path, "application/pdf");
+    return readFile(response, new URL(response.url || `https://api.somtoday.nl${path}`), undefined, `ondertekenverzoek-${id}.pdf`);
 }
 /** Consents (photo use etc.) as shown under Voorkeuren → Toestemmingen. Read-only. */
 export async function fetchConsents(client) {

package/dist/api/schedule.d.ts

@@ -32,6 +32,8 @@ type RawAfspraak = {
     inschrijfStatus?: unknown;
     kwtInfo?: unknown;
 };
+/** The portal marks an appointment as cancelled (uitgevallen) with this status. */
+export declare const CANCELLED_STATUS = "4007";
 export type ScheduleItemView = {
     id?: number;
     begin?: string;
@@ -47,6 +49,7 @@ export type ScheduleItemView = {
     omschrijving?: string;
     wijziging?: string;
     meldingen?: RawStatus[];
+    uitgevallen?: boolean;
     online?: boolean;
     bijlagen?: AttachmentView[];
     keuzewerktijd?: unknown;

package/dist/api/schedule.js

@@ -2,6 +2,24 @@ import { amsterdamYmd, dayOf, eachDay, isoWeeksInRange } from "../dates.js";
 import { htmlToPlain } from "../html.js";
 import { linkId, simplify } from "./simplify.js";
 import { compact, mapAttachment, } from "./studiewijzer.js";
+/** "Inschrijving in orde." – informational, repeated on every item; not a warning. */
+const INFO_STATUSES = new Set(["2002"]);
+/** The portal marks an appointment as cancelled (uitgevallen) with this status. */
+export const CANCELLED_STATUS = "4007";
+function realMeldingen(notes) {
+    const seen = new Set();
+    const out = [];
+    for (const note of notes ?? []) {
+        if (note.status && INFO_STATUSES.has(note.status))
+            continue;
+        const key = `${note.status ?? ""}|${note.message ?? ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(compact({ status: note.status, message: note.message }));
+    }
+    return out;
+}
 export function mapScheduleItem(raw) {
     const lesuur = raw.beginLesuur === undefined
         ? undefined
@@ -29,7 +47,8 @@ export function mapScheduleItem(raw) {
             .filter((naam) => Boolean(naam)),
         omschrijving: htmlToPlain(raw.omschrijving) || undefined,
         wijziging: raw.wijzigingOmschrijving || undefined,
-        meldingen: raw.statusNotifications?.map((note) => compact({ status: note.status, message: note.message })),
+        meldingen: realMeldingen(raw.statusNotifications),
+        uitgevallen: raw.statusNotifications?.some((note) => note.status === CANCELLED_STATUS) || undefined,
         online: raw.onlineDeelname || undefined,
         bijlagen: (raw.bijlagen ?? [])
             .map(mapAttachment)
@@ -44,15 +63,14 @@ function holidayBounds(holiday) {
     ];
 }
 export async function fetchSchedule(client, leerlingId, from, to) {
-    const meldingen = [];
+    const notes = [];
     const weeks = await Promise.all(isoWeeksInRange(from, to).map(({ year, week }) => client.getAll(`/afspraakitems/${leerlingId}/jaar/${year}/week/${week}`, undefined, {
         onPage: (body) => {
-            for (const note of body
-                ?.statusNotifications ?? []) {
-                meldingen.push(compact({ status: note.status, message: note.message }));
-            }
+            notes.push(...(body
+                ?.statusNotifications ?? []));
         },
     })));
+    const meldingen = realMeldingen(notes);
     const holidays = (await client.getAll("/vakanties/verzorger"))
         .items;
     const items = weeks
@@ -70,9 +88,12 @@ export async function fetchSchedule(client, leerlingId, from, to) {
         to,
         meldingen,
         vakanties,
-        days: eachDay(from, to).map((datum) => compact({
-            datum,
-            vakantie: vakanties.find((holiday) => holiday.van <= datum && datum <= holiday.tot)?.naam,
+        // Every day keeps `items` (also when empty), like homework.
+        days: eachDay(from, to).map((datum) => ({
+            ...compact({
+                datum,
+                vakantie: vakanties.find((holiday) => holiday.van <= datum && datum <= holiday.tot)?.naam,
+            }),
             items: items.filter((item) => item.begin && amsterdamYmd(item.begin) === datum),
         })),
     };

package/dist/api/types.d.ts

@@ -25,6 +25,11 @@ export type AfspraakItem = {
         afkorting?: string;
     };
     docentNamen?: string[];
+    afspraakItemType?: string;
+    statusNotifications?: Array<{
+        status?: string;
+        message?: string;
+    }>;
 };
 export type HolidayItem = {
     naam?: string;

package/dist/server.js

@@ -16,7 +16,7 @@ import { absenceTool } from "./tools/absence.js";
 import { messagesTool } from "./tools/messages.js";
 import { announcementsTool, newsTool } from "./tools/news.js";
 import { childrenTool, schoolInfoTool, teachersTool } from "./tools/profile.js";
-import { consentsTool, parentEveningTool, signingRequestsTool, } from "./tools/misc.js";
+import { consentsTool, parentEveningTool, signingDocumentTool, signingRequestsTool, } from "./tools/misc.js";
 import { downloadAttachmentTool } from "./tools/download.js";
 import { scheduleTool } from "./tools/schedule.js";
 import { studyMaterialTool } from "./tools/study-material.js";
@@ -59,12 +59,12 @@ export function createServer(session = createDefaultSession()) {
     }, async () => whoamiTool(ctx));
     server.registerTool("lessons", {
         title: "Lessons",
-        description: "Timetable for one Amsterdam date, plus whether that date is a holiday.",
+        description: "Timetable for one Amsterdam date, plus whether that date is a holiday. Each lesson has type (ROOSTERTOETS or EXAMEN marks a test in the timetable) and uitgevallen=true when cancelled. Homework and the test topic per lesson are not here: call homework for the same date.",
         inputSchema: { date: dateArg, leerlingId: leerlingArg() },
     }, async ({ date, leerlingId }) => lessonsTool(ctx, { date, leerlingId }));
     server.registerTool("schedule", {
         title: "Schedule",
-        description: "Timetable for a date range, per day: lessons, tests and other appointments with time, lesson hour, subject, room, teachers, type (e.g. ROOSTERTOETS, EXAMEN, OUDERAVOND), lesson notes, changes and cancellations (meldingen/wijziging), attachments, and holidays. Defaults to today plus 6 days; at most 42 days.",
+        description: "Timetable for a date range, per day: lessons, tests and other appointments with time, lesson hour, subject, room, teachers, type (e.g. ROOSTERTOETS, EXAMEN, OUDERAVOND), lesson notes, changes and cancellations (wijziging, uitgevallen=true, meldingen with real warnings only; the routine 'Inschrijving in orde.' notice is dropped), attachments, and holidays. Every day has items (empty array on a free day). Defaults to today plus 6 days; at most 42 days.",
         inputSchema: {
             ...rangeArgs("Defaults to today."),
             leerlingId: leerlingArg(),
@@ -81,10 +81,18 @@ export function createServer(session = createDefaultSession()) {
     }, async (args) => homeworkTool(ctx, args));
     server.registerTool("assignments", {
         title: "Assignments (hand-ins)",
-        description: "All hand-in assignments with their window, status (AANKOMEND, IN_TE_LEVEREN, IN_AFWACHTING, AKKOORD), late flag, description, attachments and links. status=open keeps upcoming and to-do ones. Use toekenningId with assignment_detail." +
+        description: "All hand-in assignments with their window, status (AANKOMEND, IN_TE_LEVEREN, IN_AFWACHTING, AKKOORD), teLaat (always a boolean: true only for an open hand-in past its deadline), description, attachments and links. status=open keeps upcoming and to-do ones, and by default hides past-due items where no digital hand-in is expected (inleveringenVerwacht 0, e.g. on paper; count in verborgenZonderInlevering); includeNoHandIn=true keeps them. Near-duplicates (same subject, topic, window and status, e.g. published to two groups) are merged by default, with the other ids in duplicaatToekenningIds; dedupe=false lists them separately. Use toekenningId with assignment_detail." +
             " Every item lists bijlagen (fileUrl, readable with download_attachment) and externeMaterialen; empty means the teacher attached nothing (lesmateriaal=true is only a flag, there is no separate material call).",
         inputSchema: {
             status: z.enum(["open", "all"]).optional().describe("Default all."),
+            includeNoHandIn: z
+                .boolean()
+                .optional()
+                .describe("With status=open: also show past-due items without a digital hand-in (inleveringenVerwacht 0). Default false."),
+            dedupe: z
+                .boolean()
+                .optional()
+                .describe("Merge near-duplicate assignments (same subject, topic, window, status). Default true."),
             leerlingId: leerlingArg(),
         },
     }, async (args) => assignmentsTool(ctx, args));
@@ -232,9 +240,18 @@ export function createServer(session = createDefaultSession()) {
     }, async () => teachersTool(ctx));
     server.registerTool("signing_requests", {
         title: "Signing requests",
-        description: "Digital signing requests (ondertekenverzoeken) waiting for you or done. Read-only; nothing is signed.",
+        description: "Digital signing requests (ondertekenverzoeken) waiting for you or done. Each item has document {tool:'signing_document', id, available}: pass id to signing_document to read the (signed) PDF. Read-only; nothing is signed.",
         inputSchema: {},
     }, async () => signingRequestsTool(ctx));
+    server.registerTool("signing_document", {
+        title: "Signing document",
+        description: "Read the document (PDF) of one signing request, as the portal's download button does: pass document.id from signing_requests. Returns extracted text (max 10 MB). The document needs your login, so it is not a fileUrl for download_attachment. Usually available once signed; not for requests still to sign, withdrawn or expired.",
+        inputSchema: {
+            id: textOrNumber()
+                .pipe(z.string().regex(/^[A-Za-z0-9-]+$/))
+                .describe("Signing request id (document.id from signing_requests)."),
+        },
+    }, async (args) => signingDocumentTool(ctx, args));
     server.registerTool("parent_evening", {
         title: "Parent evening",
         description: "Parent-evening (ouderavond) details: invitation, time slots and chosen teachers. Without id, finds invitations linked in your messages. Read-only; nothing is booked.",

package/dist/tools/assignments.d.ts

@@ -2,6 +2,8 @@ import type { ToolContext } from "./context.js";
 import type { ToolResult } from "./result.js";
 export declare function assignmentsTool(ctx: ToolContext, args: {
     status?: "open" | "all";
+    includeNoHandIn?: boolean;
+    dedupe?: boolean;
     leerlingId?: string;
 }, now?: Date): Promise<ToolResult>;
 /**

package/dist/tools/assignments.js

@@ -1,13 +1,24 @@
-import { fetchAssignments, findAssignment } from "../api/assignments.js";
+import { dedupeAssignments, fetchAssignments, findAssignment, isPastWithoutHandIn, } from "../api/assignments.js";
 import { childTool } from "./child-tool.js";
 const OPEN = new Set(["AANKOMEND", "IN_TE_LEVEREN"]);
 export async function assignmentsTool(ctx, args, now = new Date()) {
     return childTool(ctx, args.leerlingId, "huiswerkBekijkenAan", async (child) => {
-        const all = await fetchAssignments(ctx.client, child.leerlingId, now);
-        const items = args.status === "open"
-            ? all.filter((item) => item.categorie && OPEN.has(item.categorie))
-            : all;
-        return { total: all.length, shown: items.length, items };
+        const fetched = await fetchAssignments(ctx.client, child.leerlingId, now);
+        const all = args.dedupe === false ? fetched : dedupeAssignments(fetched);
+        if (args.status !== "open") {
+            return { total: all.length, shown: all.length, items: all };
+        }
+        const open = all.filter((item) => item.categorie && OPEN.has(item.categorie));
+        const items = args.includeNoHandIn
+            ? open
+            : open.filter((item) => !isPastWithoutHandIn(item));
+        const hidden = open.length - items.length;
+        return {
+            total: all.length,
+            shown: items.length,
+            ...(hidden > 0 ? { verborgenZonderInlevering: hidden } : {}),
+            items,
+        };
     });
 }
 /**

package/dist/tools/misc.d.ts

@@ -1,6 +1,9 @@
 import type { ToolContext } from "./context.js";
 import { type ToolResult } from "./result.js";
 export declare function signingRequestsTool(ctx: ToolContext): Promise<ToolResult>;
+export declare function signingDocumentTool(ctx: ToolContext, args: {
+    id: string;
+}): Promise<ToolResult>;
 export declare function consentsTool(ctx: ToolContext): Promise<ToolResult>;
 export declare function parentEveningTool(ctx: ToolContext, args: {
     id?: string;

package/dist/tools/misc.js

@@ -1,4 +1,4 @@
-import { fetchConsents, fetchParentEvening, fetchSigningRequests, findParentEveningIds, } from "../api/misc.js";
+import { fetchConsents, fetchParentEvening, fetchSigningDocument, fetchSigningRequests, findParentEveningIds, } from "../api/misc.js";
 import { accountTool } from "./child-tool.js";
 import { section } from "./result.js";
 export async function signingRequestsTool(ctx) {
@@ -6,6 +6,12 @@ export async function signingRequestsTool(ctx) {
         ondertekenverzoeken: await section(() => fetchSigningRequests(ctx.client)),
     }));
 }
+export async function signingDocumentTool(ctx, args) {
+    return accountTool(ctx, async () => ({
+        id: args.id,
+        ...(await fetchSigningDocument(ctx.client, args.id)),
+    }));
+}
 export async function consentsTool(ctx) {
     return accountTool(ctx, async () => ({
         toestemmingen: await section(() => fetchConsents(ctx.client)),

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "somtoday-mcp",
-  "version": "0.1.1",
+  "version": "0.3.0",
+  "mcpName": "io.github.barzoj/somtoday-mcp",
   "description": "Unofficial read-only MCP server for the Somtoday parent portal",
   "type": "module",
   "bin": {