@wilm-ai/wilma-cli 2.3.2 → 2.4.0

package/dist/mcp-tools.d.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { FetchedAttachment, WilmaAccess } from "./agent-data.js";
-export declare const INSTRUCTIONS = "Read-only access to Finland's Wilma school system for a parent/guardian, or for a student with their own login.\n- Start with wilma_summary: today's and tomorrow's lessons, upcoming exams, recent homework, news and messages for every child in one call.\n- Tools cover all children by default (a student's own login has just that student); pass \"student\" (name or student number) to narrow to one child.\n- Wilma content is usually in Finnish. Answer in the user's language and translate as needed. Write dates the way that language does: Finnish \"ke 7.10.\" (with the final period), English \"Wed 7 Oct\".\n- Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.\n- Teachers' feedback (\"forgot books\", \"did well\") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook.\n- If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.\n- Wilma allows one session per account, so each WilmAI login logs the user out of Wilma in their browser. If they want to use Wilma in the browser, call wilma_logout and then call Wilma tools only when they ask again.\n- If a result ends with an \"Update note\", answer the question first, then pass the note on in one sentence.";
+import { type FetchedAttachment, type WilmaAccess } from "./agent-data.js";
+export declare const INSTRUCTIONS = "Read-only access to Finland's Wilma school system for a parent/guardian, or for a student with their own login.\n- Start with wilma_summary: today's and tomorrow's lessons, upcoming exams, recent homework, news and messages for every child in one call.\n- Tools cover all children by default (a student's own login has just that student); pass \"student\" (name or student number) to narrow to one child.\n- Wilma content is usually in Finnish. Answer in the user's language and translate as needed. Write dates the way that language does: Finnish \"ke 7.10.\" (with the final period), English \"Wed 7 Oct\".\n- Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.\n- Teachers' feedback (\"forgot books\", \"did well\") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook. The class, class teacher and teachers are in wilma_contacts.\n- If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.\n- Wilma allows one session per account, so each WilmAI login logs the user out of Wilma in their browser. If they want to use Wilma in the browser, call wilma_logout and then call Wilma tools only when they ask again.\n- If a result ends with an \"Update note\", answer the question first, then pass the note on in one sentence.";
 export declare const READ_ONLY: {
     readonly readOnlyHint: true;
     readonly destructiveHint: false;

package/dist/mcp-tools.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { SCHEDULE_MAX_DAYS } from "./agent-data.js";
 import { normalizeResourceId } from "./downloads.js";
 import { toAgentJson } from "./output-json.js";
 /*
@@ -10,7 +11,7 @@ export const INSTRUCTIONS = `Read-only access to Finland's Wilma school system f
 - Tools cover all children by default (a student's own login has just that student); pass "student" (name or student number) to narrow to one child.
 - Wilma content is usually in Finnish. Answer in the user's language and translate as needed. Write dates the way that language does: Finnish "ke 7.10." (with the final period), English "Wed 7 Oct".
 - Message and news lists return ids; use wilma_read_message / wilma_read_news for full text. Bulletins can link attachments; fetch them with wilma_get_news_attachment.
-- Teachers' feedback ("forgot books", "did well") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook.
+- Teachers' feedback ("forgot books", "did well") and absences are lesson notes: wilma_lesson_notes for recent days, wilma_lesson_notes_summary for counts. Course and report-card grades are in wilma_gradebook. The class, class teacher and teachers are in wilma_contacts.
 - If a tool says the user isn't logged in, relay the login link or instructions to the user exactly; never ask the user to type their Wilma password into the chat.
 - Wilma allows one session per account, so each WilmAI login logs the user out of Wilma in their browser. If they want to use Wilma in the browser, call wilma_logout and then call Wilma tools only when they ask again.
 - If a result ends with an "Update note", answer the question first, then pass the note on in one sentence.`;
@@ -74,7 +75,7 @@ function attachmentResult(fetched, savedPath) {
 export function registerWilmaTools(server, ctx) {
     server.registerTool("wilma_summary", {
         title: "School summary",
-        description: "Daily briefing per child: today's and the next school day's lessons, upcoming exams (with start times when given), recent homework, lesson notes since the previous school day (teachers' feedback and absences), recent bulletins, and recent and unread messages (ids, unread, replyCount). What Wilma didn't give is listed in unavailable (\"news\": this Wilma doesn't show this account its bulletins). The best starting point for any question about school.",
+        description: "Daily briefing per child: today's and the next school day's lessons, upcoming exams (with start times when given), recent homework, lesson notes since the previous school day (teachers' feedback and absences), recent bulletins, and recent and unread messages (ids, unread, replyCount; event invitations with invitationStatus, as in wilma_list_messages). What Wilma didn't give is listed in unavailable (\"news\": this Wilma doesn't show this account its bulletins). The best starting point for any question about school.",
         inputSchema: {
             student: studentArg,
             days: z.number().int().min(1).max(60).optional().describe("How many days back to include news and messages (default 7)."),
@@ -87,7 +88,7 @@ export function registerWilmaTools(server, ctx) {
     }, async ({ student, days, since }) => ctx.withAccess(async (a) => json(await a.summary({ student, days, since }))));
     server.registerTool("wilma_schedule", {
         title: "Lesson schedule",
-        description: "Lessons for today, the next school day, this week, a specific date, or the next occurrence of a weekday.",
+        description: "List each child's lessons for one day or a school week: today, the next school day, this or next week (Monday to Friday), a date, or the next given weekday; or any other week or period with from/to (e.g. a week further ahead, or several weeks to see the usual school days). Lessons come in time order with the date, start and end time, subject, teacher and room (when Wilma gives one); a day without school has no lessons. Exams and homework are in wilma_upcoming_exams and wilma_homework.",
         inputSchema: {
             student: studentArg,
             when: z.enum(["today", "tomorrow", "week", "next-week"]).optional().describe("Default: week. 'tomorrow' means the next school day."),
@@ -96,37 +97,61 @@ export function registerWilmaTools(server, ctx) {
                 .string()
                 .optional()
                 .describe("Next occurrence of a weekday: mon..sun (Finnish ma..su also work). Overrides 'when'."),
+            from: z.string().optional().describe("Start of a period, YYYY-MM-DD. Overrides 'when'."),
+            to: z
+                .string()
+                .optional()
+                .describe(`End of the period, YYYY-MM-DD (default: the Friday of from's week). At most ${SCHEDULE_MAX_DAYS} days.`),
         },
         annotations: { title: "Lesson schedule", ...READ_ONLY },
-    }, async ({ student, when, date, weekday }) => ctx.withAccess(async (a) => json(await a.schedule({ student, when, date, weekday }))));
+    }, async ({ student, when, date, weekday, from, to }) => ctx.withAccess(async (a) => json(await a.schedule({ student, when, date, weekday, from, to }))));
     server.registerTool("wilma_homework", {
         title: "Homework",
-        description: "Recent homework entries by lesson, newest first.",
-        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        description: "List the homework teachers have entered for each child, newest first: the date, subject, teacher and what to do. It reads the homework Wilma's front page lists (Wilma decides how far back that goes). wilma_summary already includes the last few days' homework.",
+        inputSchema: {
+            student: studentArg,
+            limit: z.number().int().min(1).max(100).optional().describe("How many entries per child, newest first (default 10)."),
+        },
         annotations: { title: "Homework", ...READ_ONLY },
     }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.homework({ student, limit }))));
     server.registerTool("wilma_upcoming_exams", {
         title: "Upcoming exams",
-        description: "Upcoming exams with subject, date and topic (what to study).",
-        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        description: "List each child's exams from today on that have no grade yet, soonest first: the date, start time (when the school gives one), exam name, subject, topic (what to study) and teacher. Graded exams are in wilma_grades.",
+        inputSchema: {
+            student: studentArg,
+            limit: z.number().int().min(1).max(100).optional().describe("How many exams per child, soonest first (default 20)."),
+        },
         annotations: { title: "Upcoming exams", ...READ_ONLY },
     }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.upcomingExams({ student, limit }))));
     server.registerTool("wilma_grades", {
         title: "Exam grades",
-        description: "Recent exam grades.",
-        inputSchema: { student: studentArg, limit: z.number().int().min(1).max(100).optional() },
+        description: "List each child's graded exams, newest first: the date, exam name, subject, grade as Wilma shows it (e.g. 8+, 9½, S), the teacher's notes and when a guardian marked it seen. It reads the exams Wilma's front page lists (Wilma decides how far back that goes); with from, Wilma's list of past exams for that period instead, as far back as the school keeps them, including exams still waiting for a grade (grade: null). For course, term and report-card grades use wilma_gradebook.",
+        inputSchema: {
+            student: studentArg,
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("How many grades per child, newest first (default 20; with from, every exam of the period)."),
+            from: z.string().optional().describe("YYYY-MM-DD: past exams from this day on, e.g. 1 August for this school year."),
+            to: z.string().optional().describe("YYYY-MM-DD, with from. Default: today."),
+        },
         annotations: { title: "Exam grades", ...READ_ONLY },
-    }, async ({ student, limit }) => ctx.withAccess(async (a) => json(await a.grades({ student, limit }))));
+    }, async ({ student, limit, from, to }) => ctx.withAccess(async (a) => json(await a.grades({ student, limit, from, to }))));
     server.registerTool("wilma_lesson_notes", {
         title: "Lesson notes and absences",
-        description: "Lesson notes (merkinnät) teachers logged: absences, lateness, and feedback such as praise or missing books or homework, with the teacher's own words when given. One day (default today) or the last N days.",
+        description: "Lesson notes (merkinnät) teachers logged: absences, lateness, and feedback such as praise or missing books or homework, with the teacher's own words when given. One day (default today), the last N days, or a period with from/to, which can reach ahead (a teacher may note a make-up exam on a coming lesson).",
         inputSchema: {
             student: studentArg,
             date: z.string().optional().describe("YYYY-MM-DD, default today."),
             days: z.number().int().min(1).max(365).optional().describe("The last N days up to today, instead of one date."),
+            from: z.string().optional().describe("Start of a period, YYYY-MM-DD, instead of a date or days."),
+            to: z.string().optional().describe("End of the period, YYYY-MM-DD (default today; may be after today)."),
         },
         annotations: { title: "Lesson notes and absences", ...READ_ONLY },
-    }, async ({ student, date, days }) => ctx.withAccess(async (a) => json(await a.lessonNotes({ student, date, days }))));
+    }, async ({ student, date, days, from, to }) => ctx.withAccess(async (a) => json(await a.lessonNotes({ student, date, days, from, to }))));
     server.registerTool("wilma_lesson_notes_summary", {
         title: "Absences and feedback summary",
         description: "Lesson notes counted by kind (e.g. absences for health reasons, unexplained absences, lateness, praise, missing study materials): this school year by default, or from a date.",
@@ -139,10 +164,16 @@ export function registerWilmaTools(server, ctx) {
     }, async ({ student, from, to }) => ctx.withAccess(async (a) => json(await a.lessonNotesSummary({ student, from, to }))));
     server.registerTool("wilma_gradebook", {
         title: "Gradebook",
-        description: "Completed courses and grades (Suoritukset) by subject, including term and school-year (report card) grades, with completion dates.",
+        description: "Get each child's gradebook (Suoritukset): completed courses and their grades, grouped by subject (subject > syllabus > course), with course codes, credits and completion dates, plus term and school-year (report card) grades. Use it for course and report-card grades; single exam grades are in wilma_grades.",
         inputSchema: { student: studentArg },
         annotations: { title: "Gradebook", ...READ_ONLY },
     }, async ({ student }) => ctx.withAccess(async (a) => json(await a.gradebook({ student }))));
+    server.registerTool("wilma_contacts", {
+        title: "Class and teachers",
+        description: "Each child's class (e.g. 9A), class teacher and other supervisors with their role as Wilma names it (e.g. Luokanvalvoja), and the child's own teachers as Wilma's message recipients list them, with the subjects each teaches the child in this and next week's timetable (empty when none). Other school staff aren't included. Lessons with times and rooms are in wilma_schedule.",
+        inputSchema: { student: studentArg },
+        annotations: { title: "Class and teachers", ...READ_ONLY },
+    }, async ({ student }) => ctx.withAccess(async (a) => json(await a.contacts({ student }))));
     server.registerTool("wilma_list_printouts", {
         title: "List printouts",
         description: "PDF documents the school offers (Tulosteet), such as report cards or absence reports. Fetch one with wilma_get_printout.",
@@ -172,7 +203,7 @@ export function registerWilmaTools(server, ctx) {
     }));
     server.registerTool("wilma_list_messages", {
         title: "List messages",
-        description: "Wilma messages, newest first (subject, sender, date, id). Use wilma_read_message for the full text.",
+        description: "Wilma messages, newest first (subject, sender, date, id, unread, replyCount). The appointments folder holds event invitations (parents' evenings, learning discussions) with the family's answer as Wilma lists it: invitationStatus (\"Applied\": signed up, the time in invitationInfo; \"ExpiredReg\": sign-up closed; null: no answer shown). Use wilma_read_message for the full text, and for an invitation's time slots.",
         inputSchema: {
             student: studentArg,
             folder: z.enum(["inbox", "archive", "outbox", "drafts", "appointments"]).optional().describe("Default: inbox."),

package/dist/mcp.js

@@ -121,7 +121,7 @@ function createWilmaMcpServer(version) {
     });
     server.registerTool("wilma_account", {
         title: "Wilma account status",
-        description: "Which Wilma logins are connected and which children each one has. Families with children on different Wilmas can connect several (wilma_login adds another).",
+        description: "Which Wilma logins are connected: each one's Wilma, username, role (\"guardian\", or \"student\" for a student's own login) and the children it lists. Families with children on different Wilmas connect one login per Wilma (wilma_login adds another). When two logins on one Wilma list the same child (a parent's and the child's own), tools read that child through the guardian's login, and the other login's entry for the child says readVia. A child unticked on the login page (a profile Wilma lists twice) has hidden: true and isn't read.",
         inputSchema: {},
         annotations: { title: "Wilma account status", ...READ_ONLY },
     }, async () => {
@@ -129,19 +129,7 @@ function createWilmaMcpServer(version) {
         const accounts = await resolveAccounts(config);
         if (!accounts.length)
             return json({ connected: false, hint: "Call wilma_login to connect." });
-        return withAccess(async (a) => {
-            const students = await a.students();
-            return json({
-                connected: true,
-                source: accounts[0].source,
-                wilmas: accounts.map((account, index) => ({
-                    wilma: account.stored?.tenantName ?? account.profile.baseUrl,
-                    username: account.profile.username,
-                    children: students.filter((s) => s.account === index && s.name).map((s) => ({ name: s.name, studentNumber: s.studentNumber })),
-                })),
-                ...(a.problems.length ? { problems: a.problems } : {}),
-            });
-        });
+        return withAccess(async (a) => json({ connected: true, source: accounts[0].source, wilmas: await a.logins() }));
     });
     server.registerTool("wilma_find_school", {
         title: "Find a school's Wilma",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wilm-ai/wilma-cli",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "description": "Read your children's Wilma (Finnish school system) from the terminal or an AI assistant: schedule, homework, exams, messages and news. Students can use their own login too.",
   "mcpName": "ai.wilm/wilma",
   "license": "MIT",
@@ -22,7 +22,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm --filter @wilm-ai/wilma-client build && pnpm run build && node test/news-resources.mjs && node test/mcp-login.mjs && node test/mfa.mjs && node test/logout.mjs && node test/shared-session.mjs && node test/audit.mjs && node test/update-notice.mjs && node test/registry.mjs",
+    "test": "pnpm --filter @wilm-ai/wilma-client build && pnpm run build && node test/news-resources.mjs && node test/mcp-login.mjs && node test/mfa.mjs && node test/logout.mjs && node test/shared-session.mjs && node test/audit.mjs && node test/family.mjs && node test/update-notice.mjs && node test/registry.mjs",
     "start": "node dist/index.js",
     "prepack": "pnpm --filter @wilm-ai/wilma-client build && pnpm --filter @wilm-ai/wilma-cli build",
     "test:live": "tsc -p tsconfig.json && node test/live.spec.mjs",