@chrischall/pickuppatrol-mcp 0.0.0

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+import { PickUpPatrolAuth } from './auth.js';
+import type { AuthOptions } from './auth.js';
+import type { DefaultsReviewNeeded, PlanEdit, PlanUpdate, School, SchoolNotifyTimes, SessionResponse, Student, Transportation } from './types.js';
+export interface ClientOptions extends AuthOptions {
+    auth?: PickUpPatrolAuth;
+}
+/**
+ * Thin typed client over PickUp Patrol's ServiceStack API.
+ *
+ * Not `createApiClient`: that helper only emits `Authorization: Bearer …`,
+ * while this deployment may authenticate by session cookie instead (see
+ * `src/auth.ts`). Requests therefore carry whichever of the two the login
+ * produced, and errors are unwrapped from ServiceStack's `ResponseStatus`
+ * envelope rather than a plain status line.
+ */
+export declare class PickUpPatrolClient {
+    private readonly auth;
+    private readonly fetchImpl;
+    constructor(opts?: ClientOptions);
+    /** Request a DTO by name. GET args go on the query string, others in the body. */
+    call<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH', dto: string, args?: Record<string, unknown>): Promise<T>;
+    private headers;
+    private parse;
+    getSession(): Promise<SessionResponse>;
+    getChildren(): Promise<Student[]>;
+    getStudent(studentId: number): Promise<Student>;
+    getDefaultPlansReviewNeeded(): Promise<DefaultsReviewNeeded[]>;
+    getParentPlans(startDate: string, endDate: string): Promise<unknown[]>;
+    getPlanEdit(planDate: string, studentId: number): Promise<PlanEdit>;
+    getTransportations(schoolId: number): Promise<Transportation[]>;
+    getCarNumbers(schoolId: number): Promise<string[]>;
+    getSchool(schoolId: number): Promise<School>;
+    getSchoolNotifyTimes(schoolId: number): Promise<SchoolNotifyTimes>;
+    getSchoolSettings(schoolId: number): Promise<Record<string, unknown>>;
+    getInvalidPlanDates(schoolId: number): Promise<string[]>;
+    getBoldedDates(startDate: string, endDate: string): Promise<string[]>;
+    /**
+     * The one-off (calendar) plan write. One array element per date, so a single
+     * call can set a run of dates. A `null` TransportationId reverts the date to
+     * the student's default plan.
+     */
+    updatePlans(plans: PlanUpdate[]): Promise<void>;
+    /**
+     * The default-plans write. PickUp Patrol has no dedicated endpoint: the SPA
+     * PUTs the WHOLE student record back with `DefaultPlans` replaced, so callers
+     * must pass a `GetStudent` result with only that field changed.
+     */
+    updateStudent(student: Student): Promise<void>;
+    setDefaultsReviewed(studentId: number, reviewed: boolean): Promise<void>;
+}
+/**
+ * Module-level singleton shared by every tool module. Built here (not in
+ * `index.ts`) so the deferred-config-error pattern holds: the server boots and
+ * answers the host's install-time `tools/list` probe with no credentials set,
+ * and the configuration error only surfaces on the first tool call.
+ */
+export declare const client: PickUpPatrolClient;

package/dist/client.js

@@ -0,0 +1,168 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { loadDotenvSafely, McpToolError, buildQueryString } from '@chrischall/mcp-utils';
+import { PickUpPatrolAuth, BASE_URL, BASE_PATH, describeResponseStatus } from './auth.js';
+// Load .env for local dev; silently skip when dotenv is unavailable (the mcpb
+// bundle externalises it). The try/catch guards a runtime where
+// `import.meta.url` is undefined and `fileURLToPath` would throw at module
+// init — such a runtime has no filesystem or .env to read anyway.
+try {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    await loadDotenvSafely({ path: join(dir, '..', '.env'), override: false });
+}
+catch {
+    /* non-Node runtime: no .env to load */
+}
+const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Thin typed client over PickUp Patrol's ServiceStack API.
+ *
+ * Not `createApiClient`: that helper only emits `Authorization: Bearer …`,
+ * while this deployment may authenticate by session cookie instead (see
+ * `src/auth.ts`). Requests therefore carry whichever of the two the login
+ * produced, and errors are unwrapped from ServiceStack's `ResponseStatus`
+ * envelope rather than a plain status line.
+ */
+export class PickUpPatrolClient {
+    auth;
+    fetchImpl;
+    constructor(opts = {}) {
+        this.auth = opts.auth ?? new PickUpPatrolAuth(opts);
+        this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+    }
+    /** Request a DTO by name. GET args go on the query string, others in the body. */
+    async call(method, dto, args) {
+        const query = method === 'GET' && args ? buildQueryString(args) : '';
+        const url = `${BASE_URL}${BASE_PATH}/${dto}${query}`;
+        const res = await this.auth.withAuth((session) => this.fetchImpl(url, {
+            method,
+            headers: this.headers(session),
+            body: method === 'GET' || args === undefined ? undefined : JSON.stringify(args),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        }));
+        return this.parse(res, dto);
+    }
+    headers(session) {
+        const headers = {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+        };
+        if (session.bearerToken)
+            headers['Authorization'] = `Bearer ${session.bearerToken}`;
+        if (session.cookieHeader)
+            headers['Cookie'] = session.cookieHeader;
+        return headers;
+    }
+    async parse(res, dto) {
+        const text = await res.text();
+        if (!res.ok) {
+            // ServiceStack returns its error envelope as JSON, but a gateway or an
+            // auth redirect can return HTML — so the parse is best-effort and the
+            // status is always part of the message.
+            let detail = null;
+            try {
+                detail = describeResponseStatus(JSON.parse(text)
+                    .ResponseStatus);
+            }
+            catch {
+                detail = null;
+            }
+            throw new McpToolError(`PickUp Patrol ${dto} failed (HTTP ${res.status})${detail ? `: ${detail}` : ''}`, {
+                hint: res.status === 401 || res.status === 403
+                    ? 'The session was rejected. Check PICKUPPATROL_USERNAME and PICKUPPATROL_PASSWORD.'
+                    : undefined,
+            });
+        }
+        // Several write DTOs (`UpdatePlans`, `SetDefaultsReviewed`) declare no
+        // response and answer with an empty body.
+        if (text.trim() === '')
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new McpToolError(`PickUp Patrol ${dto} returned a non-JSON response`, {
+                hint: 'This usually means the request was redirected to the sign-in page. Check the credentials and try again.',
+            });
+        }
+    }
+    // ---- reads -------------------------------------------------------------
+    getSession() {
+        return this.call('GET', 'GetSession');
+    }
+    getChildren() {
+        return this.call('GET', 'GetChildren');
+    }
+    getStudent(studentId) {
+        return this.call('GET', 'GetStudent', { StudentId: studentId });
+    }
+    getDefaultPlansReviewNeeded() {
+        return this.call('GET', 'GetDefaultPlansReviewNeeded');
+    }
+    getParentPlans(startDate, endDate) {
+        return this.call('GET', 'GetParentPlans', {
+            StartDate: startDate,
+            EndDate: endDate,
+        });
+    }
+    getPlanEdit(planDate, studentId) {
+        return this.call('GET', 'GetPlanEdit', {
+            PlanDate: planDate,
+            StudentId: studentId,
+        });
+    }
+    getTransportations(schoolId) {
+        return this.call('GET', 'GetTransportations', { SchoolId: schoolId });
+    }
+    getCarNumbers(schoolId) {
+        return this.call('GET', 'GetCarNumbers', { SchoolId: schoolId });
+    }
+    getSchool(schoolId) {
+        return this.call('GET', 'GetSchool', { SchoolId: schoolId });
+    }
+    getSchoolNotifyTimes(schoolId) {
+        return this.call('GET', 'GetSchoolNotifyTimes', { SchoolId: schoolId });
+    }
+    getSchoolSettings(schoolId) {
+        return this.call('GET', 'GetSchoolSettings', { SchoolId: schoolId });
+    }
+    getInvalidPlanDates(schoolId) {
+        return this.call('GET', 'GetInvalidPlanDates', { SchoolId: schoolId });
+    }
+    getBoldedDates(startDate, endDate) {
+        return this.call('GET', 'GetBoldedDates', {
+            StartDate: startDate,
+            EndDate: endDate,
+        });
+    }
+    // ---- writes ------------------------------------------------------------
+    /**
+     * The one-off (calendar) plan write. One array element per date, so a single
+     * call can set a run of dates. A `null` TransportationId reverts the date to
+     * the student's default plan.
+     */
+    updatePlans(plans) {
+        return this.call('PUT', 'UpdatePlans', { Plans: plans });
+    }
+    /**
+     * The default-plans write. PickUp Patrol has no dedicated endpoint: the SPA
+     * PUTs the WHOLE student record back with `DefaultPlans` replaced, so callers
+     * must pass a `GetStudent` result with only that field changed.
+     */
+    updateStudent(student) {
+        return this.call('PUT', 'Student', student);
+    }
+    setDefaultsReviewed(studentId, reviewed) {
+        return this.call('PUT', 'SetDefaultsReviewed', {
+            StudentId: studentId,
+            Reviewed: reviewed,
+        });
+    }
+}
+/**
+ * Module-level singleton shared by every tool module. Built here (not in
+ * `index.ts`) so the deferred-config-error pattern holds: the server boots and
+ * answers the host's install-time `tools/list` probe with no credentials set,
+ * and the configuration error only surfaces on the first tool call.
+ */
+export const client = new PickUpPatrolClient();

package/dist/dates.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Weekday helpers for PickUp Patrol's `DayId`.
+ *
+ * `DayId` is 1-based with **Sunday = 1** — verified against a live record
+ * (`DayId: 2` carrying `WeekDayName: "Monday"`), and matching the SPA, which
+ * renders the label as `dayNamesMin[DayId - 1]`.
+ */
+export declare const WEEKDAY_NAMES: readonly ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+export type WeekdayName = (typeof WEEKDAY_NAMES)[number];
+/** `DayId` → weekday name, or `null` when the id is outside 1–7. */
+export declare function dayIdToName(dayId: number): WeekdayName | null;
+/**
+ * Weekday name → `DayId`. Case-insensitive; returns `null` for anything that
+ * is not a weekday, so a typo surfaces as a validation error rather than
+ * silently writing to Sunday.
+ */
+export declare function nameToDayId(name: string): number | null;
+/** `YYYY-MM-DD` → `DayId`, treating the date as a plain calendar date (UTC). */
+export declare function dateToDayId(isoDate: string): number | null;
+/**
+ * `YYYY-MM-DD` → weekday name, or `null` when the string is not a real date.
+ *
+ * Exists so callers get the name in one expression: folding the two steps
+ * together at each call site leaves a `?? 0` fallback that is unreachable
+ * wherever the date has already been validated, and an unreachable branch is
+ * one nothing can prove the behaviour of.
+ */
+export declare function weekdayOf(isoDate: string): WeekdayName | null;

package/dist/dates.js

@@ -0,0 +1,51 @@
+/**
+ * Weekday helpers for PickUp Patrol's `DayId`.
+ *
+ * `DayId` is 1-based with **Sunday = 1** — verified against a live record
+ * (`DayId: 2` carrying `WeekDayName: "Monday"`), and matching the SPA, which
+ * renders the label as `dayNamesMin[DayId - 1]`.
+ */
+export const WEEKDAY_NAMES = [
+    'Sunday',
+    'Monday',
+    'Tuesday',
+    'Wednesday',
+    'Thursday',
+    'Friday',
+    'Saturday',
+];
+/** `DayId` → weekday name, or `null` when the id is outside 1–7. */
+export function dayIdToName(dayId) {
+    return WEEKDAY_NAMES[dayId - 1] ?? null;
+}
+/**
+ * Weekday name → `DayId`. Case-insensitive; returns `null` for anything that
+ * is not a weekday, so a typo surfaces as a validation error rather than
+ * silently writing to Sunday.
+ */
+export function nameToDayId(name) {
+    const index = WEEKDAY_NAMES.findIndex((d) => d.toLowerCase() === name.trim().toLowerCase());
+    return index === -1 ? null : index + 1;
+}
+/** `YYYY-MM-DD` → `DayId`, treating the date as a plain calendar date (UTC). */
+export function dateToDayId(isoDate) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(isoDate);
+    if (!match)
+        return null;
+    const ms = Date.parse(`${isoDate}T00:00:00Z`);
+    if (Number.isNaN(ms))
+        return null;
+    return new Date(ms).getUTCDay() + 1;
+}
+/**
+ * `YYYY-MM-DD` → weekday name, or `null` when the string is not a real date.
+ *
+ * Exists so callers get the name in one expression: folding the two steps
+ * together at each call site leaves a `?? 0` fallback that is unreachable
+ * wherever the date has already been validated, and an unreachable branch is
+ * one nothing can prove the behaviour of.
+ */
+export function weekdayOf(isoDate) {
+    const dayId = dateToDayId(isoDate);
+    return dayId === null ? null : dayIdToName(dayId);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { runMcp } from '@chrischall/mcp-utils';
+import { client } from './client.js';
+import { VERSION } from './version.js';
+import { registerAccountTools } from './tools/account.js';
+import { registerSchoolTools } from './tools/school.js';
+import { registerPlanTools } from './tools/plans.js';
+import { registerDefaultPlanTools } from './tools/defaults.js';
+// The client is a module-level singleton built in ./client.js, not here, so
+// the deferred-config-error pattern holds: the server boots and answers the
+// host's install-time tools/list probe even with no credentials set, and the
+// configuration error only surfaces on the first tool call.
+await runMcp({
+    name: 'pickuppatrol-mcp',
+    version: VERSION,
+    deps: client,
+    banner: '[pickuppatrol-mcp] This project was developed and is maintained by AI. Use at your own discretion.',
+    tools: [
+        registerAccountTools,
+        registerSchoolTools,
+        registerPlanTools,
+        registerDefaultPlanTools,
+    ],
+});

package/dist/lib.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Library surface. Importing `@chrischall/pickuppatrol-mcp` gives the typed
+ * client and the plan-building rules without starting an MCP server, so
+ * another tool can reuse the capture rather than re-deriving it.
+ */
+export { PickUpPatrolClient, type ClientOptions } from './client.js';
+export { PickUpPatrolAuth, describeResponseStatus, collectCookieHeader, BASE_URL, BASE_PATH, type AuthOptions, type PupSession, type FetchLike, } from './auth.js';
+export { buildPlanUpdates, applyDefaultPlans, clearDefaultPlans, assertTransportationAllowed, normalizeNote, normalizeEarlyDismissal, normalizeCarNumber, DEFAULT_PLAN_LABEL, type PlanInput, type DefaultPlanInput, } from './plans.js';
+export { dayIdToName, nameToDayId, dateToDayId, WEEKDAY_NAMES, type WeekdayName } from './dates.js';
+export { VERSION } from './version.js';
+export type * from './types.js';

package/dist/lib.js

@@ -0,0 +1,10 @@
+/**
+ * Library surface. Importing `@chrischall/pickuppatrol-mcp` gives the typed
+ * client and the plan-building rules without starting an MCP server, so
+ * another tool can reuse the capture rather than re-deriving it.
+ */
+export { PickUpPatrolClient } from './client.js';
+export { PickUpPatrolAuth, describeResponseStatus, collectCookieHeader, BASE_URL, BASE_PATH, } from './auth.js';
+export { buildPlanUpdates, applyDefaultPlans, clearDefaultPlans, assertTransportationAllowed, normalizeNote, normalizeEarlyDismissal, normalizeCarNumber, DEFAULT_PLAN_LABEL, } from './plans.js';
+export { dayIdToName, nameToDayId, dateToDayId, WEEKDAY_NAMES } from './dates.js';
+export { VERSION } from './version.js';

package/dist/plans.d.ts

@@ -0,0 +1,57 @@
+import type { PlanUpdate, Student, Transportation } from './types.js';
+/**
+ * Display text the SPA sends when a date is reverted to the student's default
+ * plan. `TransportationId: null` is what the server acts on; the name is
+ * cosmetic, but it is sent, so we send it too.
+ */
+export declare const DEFAULT_PLAN_LABEL = "Default plan";
+export interface PlanInput {
+    student: Student;
+    dates: string[];
+    /** `null` reverts each date to the student's weekly default. */
+    transportation: Transportation | null;
+    note?: string | undefined;
+    earlyDismissalTime?: string | undefined;
+    carNumber?: string | undefined;
+}
+/**
+ * Turn a plan request into the exact `UpdatePlans` array the SPA would send,
+ * enforcing the same rules it enforces client-side. Every rejection is a
+ * `McpToolError` with a hint, because these are all things the caller can fix
+ * by reading `pup_list_transportations` first.
+ */
+export declare function buildPlanUpdates(input: PlanInput): PlanUpdate[];
+/**
+ * A student may be restricted to a subset of the school's options. The SPA
+ * only ever offers those, so sending another one is a request the parent is
+ * not entitled to make.
+ */
+export declare function assertTransportationAllowed(student: Student, transportation: Transportation): void;
+/** Enforce the option's note rule and normalise blank input to `null`. */
+export declare function normalizeNote(transportation: Transportation, note: string | undefined): string | null;
+/**
+ * Early-dismissal options require a time; every other option must NOT carry
+ * one — the SPA clears the field before sending, so a leftover time would be a
+ * value the real client never sends.
+ */
+export declare function normalizeEarlyDismissal(transportation: Transportation, time: string | undefined): string | undefined;
+/** Car numbers are sent only for options that use them. */
+export declare function normalizeCarNumber(transportation: Transportation, carNumber: string | undefined): string | undefined;
+export interface DefaultPlanInput {
+    student: Student;
+    dayIds: number[];
+    transportation: Transportation;
+    note?: string | undefined;
+    earlyDismissalTime?: string | undefined;
+}
+/**
+ * Build the `Student` record to PUT back when changing weekly defaults.
+ *
+ * PickUp Patrol has no default-plans endpoint: the SPA read-modify-writes the
+ * whole student, so this returns a copy of the record it was given with only
+ * `DefaultPlans` changed. Callers must pass a **freshly read** student, or the
+ * PUT will also roll back whatever else changed since.
+ */
+export declare function applyDefaultPlans(input: DefaultPlanInput): Student;
+/** Clear every weekday default, the SPA's "start over" action. */
+export declare function clearDefaultPlans(student: Student): Student;

package/dist/plans.js

@@ -0,0 +1,165 @@
+import { McpToolError } from '@chrischall/mcp-utils';
+import { dateToDayId } from './dates.js';
+/**
+ * Display text the SPA sends when a date is reverted to the student's default
+ * plan. `TransportationId: null` is what the server acts on; the name is
+ * cosmetic, but it is sent, so we send it too.
+ */
+export const DEFAULT_PLAN_LABEL = 'Default plan';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIME_OF_DAY = /^\d{2}:\d{2}(:\d{2})?$/;
+/**
+ * Turn a plan request into the exact `UpdatePlans` array the SPA would send,
+ * enforcing the same rules it enforces client-side. Every rejection is a
+ * `McpToolError` with a hint, because these are all things the caller can fix
+ * by reading `pup_list_transportations` first.
+ */
+export function buildPlanUpdates(input) {
+    const { student, dates, transportation } = input;
+    if (dates.length === 0) {
+        throw new McpToolError('No dates given', { hint: 'Pass at least one YYYY-MM-DD date.' });
+    }
+    for (const date of dates) {
+        // Shape AND reality: `2026-13-45` matches the pattern but is not a date,
+        // and sending it would put an impossible plan in front of the school.
+        if (!ISO_DATE.test(date) || dateToDayId(date) === null) {
+            throw new McpToolError(`"${date}" is not a YYYY-MM-DD date`, {
+                hint: 'Plan dates are plain calendar dates, e.g. 2026-08-17.',
+            });
+        }
+    }
+    const duplicate = dates.find((date, i) => dates.indexOf(date) !== i);
+    if (duplicate !== undefined) {
+        throw new McpToolError(`Date ${duplicate} is listed more than once`, {
+            hint: 'Each date may appear only once per call.',
+        });
+    }
+    // Revert-to-default: a null transportation, no note, nothing else.
+    if (transportation === null) {
+        return dates.map((date) => ({
+            StudentId: student.StudentId,
+            SchoolId: student.SchoolId,
+            PlanDate: date,
+            TransportationId: null,
+            TransportationName: DEFAULT_PLAN_LABEL,
+            Note: null,
+        }));
+    }
+    assertTransportationAllowed(student, transportation);
+    const note = normalizeNote(transportation, input.note);
+    const earlyDismissalTime = normalizeEarlyDismissal(transportation, input.earlyDismissalTime);
+    const carNumber = normalizeCarNumber(transportation, input.carNumber);
+    return dates.map((date) => ({
+        StudentId: student.StudentId,
+        SchoolId: student.SchoolId,
+        PlanDate: date,
+        TransportationId: transportation.TransportationId,
+        TransportationName: transportation.Name,
+        Note: note,
+        // Omit rather than send null: the SPA leaves both keys off when they do
+        // not apply, and an undocumented API is not the place to test whether an
+        // explicit null means "clear" or "invalid".
+        ...(earlyDismissalTime !== undefined ? { EarlyDismissalTime: earlyDismissalTime } : {}),
+        ...(carNumber !== undefined ? { CarNumber: carNumber } : {}),
+    }));
+}
+/**
+ * A student may be restricted to a subset of the school's options. The SPA
+ * only ever offers those, so sending another one is a request the parent is
+ * not entitled to make.
+ */
+export function assertTransportationAllowed(student, transportation) {
+    if (student.AllowPlans === false) {
+        throw new McpToolError(`${student.FirstName ?? 'This student'} is not allowed to have plans changed`, { hint: 'The school has turned off parent plan changes for this student.' });
+    }
+    if (transportation.IsLimited !== true)
+        return;
+    const allowed = student.LimitedIds ?? [];
+    if (!allowed.includes(transportation.TransportationId)) {
+        throw new McpToolError(`"${transportation.Name}" is restricted and not available to this student`, { hint: 'Call pup_list_transportations and pick an option without isLimited, or one the school has granted this student.' });
+    }
+}
+/** Enforce the option's note rule and normalise blank input to `null`. */
+export function normalizeNote(transportation, note) {
+    const trimmed = note?.trim() ?? '';
+    if (transportation.IsNoteRequired === true && trimmed === '') {
+        throw new McpToolError(`"${transportation.Name}" requires a note`, {
+            hint: transportation.NoteHint
+                ? `The school describes it as: ${transportation.NoteHint}`
+                : 'Pass note with the detail the school expects, e.g. who is collecting the student.',
+        });
+    }
+    return trimmed === '' ? null : trimmed;
+}
+/**
+ * Early-dismissal options require a time; every other option must NOT carry
+ * one — the SPA clears the field before sending, so a leftover time would be a
+ * value the real client never sends.
+ */
+export function normalizeEarlyDismissal(transportation, time) {
+    if (transportation.IsEarlyDismissal !== true)
+        return undefined;
+    if (!time) {
+        throw new McpToolError(`"${transportation.Name}" is an early dismissal and needs a time`, {
+            hint: 'Pass early_dismissal_time as HH:MM (24-hour), within the school\'s dismissal window.',
+        });
+    }
+    if (!TIME_OF_DAY.test(time)) {
+        throw new McpToolError(`"${time}" is not an HH:MM time`, {
+            hint: 'Use 24-hour HH:MM, e.g. 14:30.',
+        });
+    }
+    return time.length === 5 ? `${time}:00` : time;
+}
+/** Car numbers are sent only for options that use them. */
+export function normalizeCarNumber(transportation, carNumber) {
+    if (transportation.UseCarNumbers !== true)
+        return undefined;
+    const trimmed = carNumber?.trim() ?? '';
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Build the `Student` record to PUT back when changing weekly defaults.
+ *
+ * PickUp Patrol has no default-plans endpoint: the SPA read-modify-writes the
+ * whole student, so this returns a copy of the record it was given with only
+ * `DefaultPlans` changed. Callers must pass a **freshly read** student, or the
+ * PUT will also roll back whatever else changed since.
+ */
+export function applyDefaultPlans(input) {
+    const { student, dayIds, transportation } = input;
+    if (dayIds.length === 0) {
+        throw new McpToolError('No weekdays given', {
+            hint: 'Pass the weekdays to change, e.g. ["Monday","Tuesday"].',
+        });
+    }
+    for (const dayId of dayIds) {
+        if (!Number.isInteger(dayId) || dayId < 1 || dayId > 7) {
+            throw new McpToolError(`${dayId} is not a weekday id (1 = Sunday … 7 = Saturday)`);
+        }
+    }
+    assertTransportationAllowed(student, transportation);
+    const note = normalizeNote(transportation, input.note);
+    const earlyDismissalTime = normalizeEarlyDismissal(transportation, input.earlyDismissalTime);
+    const plans = [...(student.DefaultPlans ?? [])].map((plan) => ({ ...plan }));
+    for (const dayId of new Set(dayIds)) {
+        const existing = plans.find((plan) => plan.DayId === dayId);
+        const fields = {
+            TransportationId: transportation.TransportationId,
+            TransportationName: transportation.Name,
+            Note: note,
+            EarlyDismissalTime: earlyDismissalTime,
+        };
+        if (existing) {
+            Object.assign(existing, fields);
+        }
+        else {
+            plans.push({ DayId: dayId, ...fields });
+        }
+    }
+    return { ...student, DefaultPlans: plans };
+}
+/** Clear every weekday default, the SPA's "start over" action. */
+export function clearDefaultPlans(student) {
+    return { ...student, DefaultPlans: [] };
+}

package/dist/tools/_confirm.d.ts

@@ -0,0 +1,13 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { schemaConfirm } from '@chrischall/mcp-utils';
+export { schemaConfirm };
+/**
+ * Confirm-gate for a mutating tool (the fleet convention). Without
+ * `confirm: true` the tool makes **no** network call and returns a dry-run
+ * preview of exactly what would be sent.
+ *
+ * The gate matters more here than in most of the fleet: these writes change
+ * how a child leaves school. A hallucinated call must not silently put a
+ * student on a different bus.
+ */
+export declare function previewUnlessConfirmed(confirm: boolean | undefined, action: string, method: string, dto: string, body?: unknown): CallToolResult | null;

package/dist/tools/_confirm.js

@@ -0,0 +1,23 @@
+import { schemaConfirm, textResult } from '@chrischall/mcp-utils';
+export { schemaConfirm };
+/**
+ * Confirm-gate for a mutating tool (the fleet convention). Without
+ * `confirm: true` the tool makes **no** network call and returns a dry-run
+ * preview of exactly what would be sent.
+ *
+ * The gate matters more here than in most of the fleet: these writes change
+ * how a child leaves school. A hallucinated call must not silently put a
+ * student on a different bus.
+ */
+export function previewUnlessConfirmed(confirm, action, method, dto, body) {
+    if (confirm === true)
+        return null;
+    return textResult({
+        dryRun: true,
+        action,
+        method,
+        dto,
+        ...(body !== undefined ? { willSend: body } : {}),
+        note: 'Re-run with confirm: true to execute.',
+    });
+}

package/dist/tools/_errors.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Surface an `McpToolError`'s `hint` to the caller.
+ *
+ * The MCP tool boundary turns a thrown error into a result carrying only
+ * `message`, so a `hint` — which is where the actionable half lives here ("the
+ * available options are …", "the school describes the note as …") — is
+ * otherwise dropped on the floor. Wrapping the handler folds it into the text
+ * the caller actually sees.
+ *
+ * Only `McpToolError` is handled: an unexpected error keeps propagating, so a
+ * genuine bug still reads as one instead of being flattened into advice.
+ */
+export declare function withHints<A>(handler: (args: A) => Promise<CallToolResult>): (args: A) => Promise<CallToolResult>;

package/dist/tools/_errors.js

@@ -0,0 +1,26 @@
+import { McpToolError, errorResult } from '@chrischall/mcp-utils';
+/**
+ * Surface an `McpToolError`'s `hint` to the caller.
+ *
+ * The MCP tool boundary turns a thrown error into a result carrying only
+ * `message`, so a `hint` — which is where the actionable half lives here ("the
+ * available options are …", "the school describes the note as …") — is
+ * otherwise dropped on the floor. Wrapping the handler folds it into the text
+ * the caller actually sees.
+ *
+ * Only `McpToolError` is handled: an unexpected error keeps propagating, so a
+ * genuine bug still reads as one instead of being flattened into advice.
+ */
+export function withHints(handler) {
+    return async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (err) {
+            if (err instanceof McpToolError && err.hint) {
+                return errorResult(`${err.message}\n\nHint: ${err.hint}`);
+            }
+            throw err;
+        }
+    };
+}