@chrischall/pickuppatrol-mcp 1.1.2 → 1.1.4

package/dist/client.d.ts

@@ -17,6 +17,8 @@ export declare class PickUpPatrolClient {
     private readonly auth;
     private readonly fetchImpl;
     constructor(opts?: ClientOptions);
+    /** Where the credentials came from (`'env'`), or `null` — for the healthcheck. */
+    credentialSource(): string | null;
     /** 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;

package/dist/client.js

@@ -1,7 +1,7 @@
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { loadDotenvSafely, McpToolError, buildQueryString } from '@chrischall/mcp-utils';
-import { PickUpPatrolAuth, BASE_URL, BASE_PATH, REQUEST_TIMEOUT_MS, describeResponseStatus, } from './auth.js';
+import { loadDotenvSafely, McpToolError, buildQueryString, EdgeBlockedError, detectEdgeBlock, } from '@chrischall/mcp-utils';
+import { PickUpPatrolAuth, BASE_URL, BASE_PATH, REQUEST_TIMEOUT_MS, SERVICE, 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
@@ -29,6 +29,10 @@ export class PickUpPatrolClient {
         this.auth = opts.auth ?? new PickUpPatrolAuth(opts);
         this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
     }
+    /** Where the credentials came from (`'env'`), or `null` — for the healthcheck. */
+    credentialSource() {
+        return this.auth.credentialSource;
+    }
     /** 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) : '';
@@ -39,7 +43,7 @@ export class PickUpPatrolClient {
             body: method === 'GET' || args === undefined ? undefined : JSON.stringify(args),
             signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         }));
-        return this.parse(res, dto);
+        return this.parse(res, method, dto);
     }
     headers(session) {
         const headers = {
@@ -52,9 +56,19 @@ export class PickUpPatrolClient {
             headers['Cookie'] = session.cookieHeader;
         return headers;
     }
-    async parse(res, dto) {
+    async parse(res, method, dto) {
         const text = await res.text();
         if (!res.ok) {
+            // A CDN/WAF refusal page never reached PickUp Patrol: say so, rather than
+            // blaming the credentials (chrischall/mcp-host#1015).
+            const edge = detectEdgeBlock({ body: text, status: res.status, headers: res.headers });
+            if (edge !== null) {
+                throw new EdgeBlockedError(res.status, edge.vendor, {
+                    service: SERVICE,
+                    method,
+                    path: `${BASE_PATH}/${dto}`,
+                });
+            }
             // 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.

package/dist/tools/account.d.ts

@@ -6,3 +6,12 @@ export declare function summarizeStudent(student: Student): Record<string, unkno
 /** Order the weekly defaults Sunday→Saturday and label each day. */
 export declare function summarizeDefaultPlans(plans: DefaultPlan[] | null | undefined): unknown[];
 export declare function registerAccountTools(server: McpServer, client: PickUpPatrolClient): void;
+/**
+ * Name the PickUp Patrol failures the shared status ladder cannot see: its
+ * sign-in rejection and two-factor errors carry no HTTP status. Anything else
+ * (an edge block, a timeout, a 5xx) falls through to the shared ladder.
+ */
+export declare function classifyPupError(err: unknown): {
+    kind: string;
+    hint?: string;
+} | undefined;

package/dist/tools/account.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
-import { messageOf, minifiedResult } from '@chrischall/mcp-utils';
+import { minifiedResult } from '@chrischall/mcp-utils';
+import { runCredentialHealthcheck } from '@chrischall/mcp-utils/healthcheck';
+import { SignInRejectedError, UnusableSessionError } from '../auth.js';
 import { dayIdToName } from '../dates.js';
 import { VERSION } from '../version.js';
 /** Project a student down to the fields a parent actually asks about. */
@@ -75,23 +77,47 @@ export function registerAccountTools(server, client) {
         return minifiedResult(raw === true ? student : summarizeStudent(student));
     });
     server.registerTool('pup_healthcheck', {
-        description: 'Verify the configured credentials sign in and the PickUp Patrol API answers. Reports the server version and the students the account can see.',
+        description: "Verify the configured credentials sign in and the PickUp Patrol API answers. Reports the server version, the students the account can see, and — when it fails — an error.kind saying which hop broke: no_credential (nothing configured), credential_rejected (PickUp Patrol refused the username/password), verification_pending (a two-factor account), edge_blocked (a CDN/WAF refused the request before PickUp Patrol saw it, so the credentials were never judged), timeout, transport or http. Read-only; never returns the credentials.",
         annotations: { readOnlyHint: true },
     }, async () => {
-        try {
-            const session = await client.getSession();
-            return minifiedResult({
-                ok: true,
-                version: VERSION,
-                signedInAs: session.Email ?? session.PrimaryEmail ?? session.DisplayName ?? null,
-                studentCount: session.Children?.length ?? 0,
-            });
-        }
-        catch (err) {
-            // A healthcheck reports rather than throws: the whole point is to say
-            // what is wrong, and an exception here reads to the host as the tool
-            // itself being broken.
-            return minifiedResult({ ok: false, version: VERSION, error: messageOf(err) });
-        }
+        let session;
+        // A healthcheck reports rather than throws: the whole point is to say
+        // what is wrong, and an exception here reads to the host as the tool
+        // itself being broken. The shared ladder supplies the `kind`
+        // (chrischall/mcp-host#1015); the account facts ride beside it.
+        const shared = await runCredentialHealthcheck({
+            server,
+            prefix: 'pup',
+            hostLabel: 'app.pickuppatrol.net',
+            probePath: '/api/json/reply/GetSession',
+            resolveCredential: async () => ({ source: client.credentialSource() }),
+            probeFn: async () => {
+                session = await client.getSession();
+            },
+            classifyThrown: classifyPupError,
+        });
+        const result = JSON.parse(shared.content[0].text);
+        return minifiedResult({
+            ...result,
+            version: VERSION,
+            ...(session !== undefined
+                ? {
+                    signedInAs: session.Email ?? session.PrimaryEmail ?? session.DisplayName ?? null,
+                    studentCount: session.Children?.length ?? 0,
+                }
+                : {}),
+        });
     });
 }
+/**
+ * Name the PickUp Patrol failures the shared status ladder cannot see: its
+ * sign-in rejection and two-factor errors carry no HTTP status. Anything else
+ * (an edge block, a timeout, a 5xx) falls through to the shared ladder.
+ */
+export function classifyPupError(err) {
+    if (err instanceof SignInRejectedError)
+        return { kind: 'credential_rejected', hint: err.hint };
+    if (err instanceof UnusableSessionError)
+        return { kind: 'verification_pending', hint: err.hint };
+    return undefined;
+}

package/dist/tools/defaults.js

@@ -1,10 +1,10 @@
 import { z } from 'zod';
-import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
+import { CONFIRM_FLOW_SENTENCE, confirmTokenParam, confirmWrite, McpToolError, minifiedResult, } from '@chrischall/mcp-utils';
+import { BASE_PATH } from '../auth.js';
 import { applyDefaultPlans, clearDefaultPlans } from '../plans.js';
 import { dayIdToName, nameToDayId } from '../dates.js';
 import { summarizeDefaultPlans } from './account.js';
 import { proofsMatch, resolveTransportation } from './plans.js';
-import { CONFIRM_FLOW, confirmTokenParam, confirmWrite } from './_confirm.js';
 /**
  * Accept weekdays as names ("Monday") or ids (1 = Sunday … 7 = Saturday).
  * A name that is not a weekday is rejected rather than coerced — silently
@@ -54,7 +54,7 @@ export function registerDefaultPlanTools(server, client) {
         });
     });
     server.registerTool('pup_set_default_plans', {
-        description: `Change a student's weekly default dismissal plan for one or more weekdays, or clear every default. This is how the child leaves school on any date without a specific plan. ${CONFIRM_FLOW} Read pup_list_transportations first.`,
+        description: `Change a student's weekly default dismissal plan for one or more weekdays, or clear every default. This is how the child leaves school on any date without a specific plan. ${CONFIRM_FLOW_SENTENCE} Read pup_list_transportations first.`,
         inputSchema: z.object({
             student_id: z.number().int().describe('Student id, from pup_list_students'),
             days: z
@@ -91,12 +91,12 @@ export function registerDefaultPlanTools(server, client) {
                 tool: 'pup_set_default_plans',
                 action: 'default_plans.clear',
                 summary: `Clear every weekday default for ${student.FirstName ?? 'the student'}`,
-                method: 'PUT',
-                dto: 'Student',
+                account: undefined,
                 target: String(student_id),
                 revision: student.ModifiedDate,
-                payload,
+                request: { method: 'PUT', path: `${BASE_PATH}/Student`, body: payload },
                 willSend: { StudentId: student.StudentId, DefaultPlans: [] },
+                preview: { dto: 'Student' },
                 confirmToken,
             });
             if (gate)
@@ -133,16 +133,16 @@ export function registerDefaultPlanTools(server, client) {
             tool: 'pup_set_default_plans',
             action: 'default_plans.set',
             summary: action,
-            method: 'PUT',
-            dto: 'Student',
+            account: undefined,
             target: String(student_id),
             revision: student.ModifiedDate,
-            payload,
+            request: { method: 'PUT', path: `${BASE_PATH}/Student`, body: payload },
             willSend: {
                 StudentId: student.StudentId,
                 DefaultPlans: payload.DefaultPlans,
                 note: 'The whole student record is sent back with only DefaultPlans changed.',
             },
+            preview: { dto: 'Student' },
             confirmToken,
         });
         if (gate)
@@ -185,7 +185,7 @@ export function registerDefaultPlanTools(server, client) {
         });
     }));
     server.registerTool('pup_mark_defaults_reviewed', {
-        description: `Mark a student's default plans as reviewed, clearing the school's 'needs review' prompt. ${CONFIRM_FLOW}`,
+        description: `Mark a student's default plans as reviewed, clearing the school's 'needs review' prompt. ${CONFIRM_FLOW_SENTENCE}`,
         inputSchema: z.object({
             student_id: z.number().int().describe('Student id, from pup_list_students'),
             reviewed: z.boolean().optional().describe('Defaults to true'),
@@ -197,10 +197,10 @@ export function registerDefaultPlanTools(server, client) {
             tool: 'pup_mark_defaults_reviewed',
             action: 'default_plans.mark_reviewed',
             summary: `Mark student ${student_id}'s defaults as ${value ? 'reviewed' : 'not reviewed'}`,
-            method: 'PUT',
-            dto: 'SetDefaultsReviewed',
+            account: undefined,
             target: String(student_id),
-            payload: { StudentId: student_id, Reviewed: value },
+            request: { method: 'PUT', path: `${BASE_PATH}/SetDefaultsReviewed`, body: { StudentId: student_id, Reviewed: value } },
+            preview: { dto: 'SetDefaultsReviewed' },
             confirmToken,
         });
         if (gate)

package/dist/tools/plans.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
-import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
+import { CONFIRM_FLOW_SENTENCE, confirmTokenParam, confirmWrite, McpToolError, minifiedResult, } from '@chrischall/mcp-utils';
+import { BASE_PATH } from '../auth.js';
 import { buildPlanUpdates } from '../plans.js';
 import { weekdayOf } from '../dates.js';
-import { CONFIRM_FLOW, confirmTokenParam, confirmWrite } from './_confirm.js';
 /**
  * Reduce a time of day to `HH:MM:SS` so a read-back can be compared with what
  * was sent. Accepts `H:MM`, `HH:MM:SS`, an ISO date-time, and the XSD duration
@@ -90,7 +90,7 @@ export function registerPlanTools(server, client) {
         }),
     }, async ({ student_id, date }) => minifiedResult(await client.getPlanEdit(date, student_id)));
     server.registerTool('pup_set_plan', {
-        description: `Change how a student is dismissed on one or more specific dates, or clear those dates back to the student's weekly default. This changes how a child actually leaves school. ${CONFIRM_FLOW} The preview shows the exact payload. Read pup_list_transportations first — options differ in whether they require a note, a car number or an early-dismissal time.`,
+        description: `Change how a student is dismissed on one or more specific dates, or clear those dates back to the student's weekly default. This changes how a child actually leaves school. ${CONFIRM_FLOW_SENTENCE} The preview shows the exact payload. Read pup_list_transportations first — options differ in whether they require a note, a car number or an early-dismissal time.`,
         inputSchema: z.object({
             student_id: z.number().int().describe('Student id, from pup_list_students'),
             dates: z
@@ -139,10 +139,10 @@ export function registerPlanTools(server, client) {
             tool: 'pup_set_plan',
             action: 'plans.set',
             summary: action,
-            method: 'PUT',
-            dto: 'UpdatePlans',
+            account: undefined,
             target: String(student_id),
-            payload: { Plans: plans },
+            request: { method: 'PUT', path: `${BASE_PATH}/UpdatePlans`, body: { Plans: plans } },
+            preview: { dto: 'UpdatePlans' },
             confirmToken,
         });
         if (gate)

package/dist/version.d.ts

@@ -7,4 +7,4 @@
  * annotation, so there is exactly one line to keep in sync and
  * `versionSyncTest` has exactly one line to check.
  */
-export declare const VERSION = "1.1.2";
+export declare const VERSION = "1.1.4";

package/dist/version.js

@@ -7,4 +7,4 @@
  * annotation, so there is exactly one line to keep in sync and
  * `versionSyncTest` has exactly one line to check.
  */
-export const VERSION = '1.1.2'; // x-release-please-version
+export const VERSION = '1.1.4'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/pickuppatrol-mcp",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "license": "MIT",
   "mcpName": "io.github.chrischall/pickuppatrol-mcp",
   "description": "PickUp Patrol MCP server for Claude — developed and maintained by AI (Claude Code)",
@@ -57,13 +57,13 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.6.0",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@chrischall/mcp-utils": "^2.14.0",
+    "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.2",
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/client": "^2.3.0",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^5.0.0",
     "esbuild": "^0.28.0",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/pickuppatrol-mcp",
     "source": "github"
   },
-  "version": "1.1.2",
+  "version": "1.1.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/pickuppatrol-mcp",
-      "version": "1.1.2",
+      "version": "1.1.4",
       "transport": {
         "type": "stdio"
       }

package/dist/tools/_confirm.d.ts

@@ -1,37 +0,0 @@
-import type { CallToolResult, InputRequiredResult, ServerContext } from '@modelcontextprotocol/server';
-import { confirmTokenParam } from '@chrischall/mcp-utils';
-export { confirmTokenParam };
-/** What every gated tool's description says about the confirmation step. */
-export declare const CONFIRM_FLOW = "Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).";
-export interface ConfirmWriteOptions {
-    /** The tool name the token is bound to. */
-    tool: string;
-    /** `<service>.<verb>` identifier for the operation. */
-    action: string;
-    /** Human-readable sentence describing what will change. */
-    summary: string;
-    method: string;
-    dto: string;
-    /** The primary id acted on. */
-    target: string;
-    /** A version of the target that rotates on edit, when the API has one. */
-    revision?: string | null | undefined;
-    /** EXACTLY what the write will send — hashed into the token. */
-    payload: unknown;
-    /** What the preview shows as `willSend`; defaults to `payload`. */
-    willSend?: unknown;
-    /** The phase-2 token from the tool's input. */
-    confirmToken: string | undefined;
-}
-/**
- * Confirm-gate for a mutating tool. A client that can show a prompt gets one;
- * one that cannot gets the two-step token flow (MCP_CONFIRM_MODE): phase 1
- * makes **no** write and returns the preview plus a token, phase 2 proceeds
- * only if the freshly rebuilt payload still matches what was previewed.
- * `undefined` means proceed; anything else is the result to return.
- *
- * 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 confirmWrite(ctx: ServerContext, options: ConfirmWriteOptions): Promise<InputRequiredResult | CallToolResult | undefined>;

package/dist/tools/_confirm.js

@@ -1,32 +0,0 @@
-import { confirmationFromEnv, confirmTokenParam, requireConfirmationWithFallback, } from '@chrischall/mcp-utils';
-export { confirmTokenParam };
-/** What every gated tool's description says about the confirmation step. */
-export const CONFIRM_FLOW = 'Asks the user to confirm first: a confirmation prompt where the client supports one; otherwise the first call returns a preview and a confirmToken, and only a repeat call with that token proceeds (see MCP_CONFIRM_MODE).';
-/**
- * Confirm-gate for a mutating tool. A client that can show a prompt gets one;
- * one that cannot gets the two-step token flow (MCP_CONFIRM_MODE): phase 1
- * makes **no** write and returns the preview plus a token, phase 2 proceeds
- * only if the freshly rebuilt payload still matches what was previewed.
- * `undefined` means proceed; anything else is the result to return.
- *
- * 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 confirmWrite(ctx, options) {
-    const { tool, action, summary, method, dto, target, revision, payload, willSend, confirmToken } = options;
-    const preview = { action: summary, method, dto, willSend: willSend ?? payload };
-    return requireConfirmationWithFallback(ctx, confirmationFromEnv({
-        action,
-        message: `Review and confirm this change: ${summary}`,
-        details: preview,
-        tool,
-        confirmToken,
-        subject: () => ({
-            target,
-            ...(revision ? { revision } : {}),
-            payload,
-            preview,
-        }),
-    }));
-}