@chrischall/pickuppatrol-mcp 1.1.2 → 1.1.4

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "PickUp Patrol school-dismissal tools for Claude Code",
-    "version": "1.1.2"
+    "version": "1.1.4"
   },
   "plugins": [
     {
@@ -14,7 +14,7 @@
       "displayName": "PickUp Patrol",
       "source": "./",
       "description": "Read and change your children's school dismissal plans in PickUp Patrol — defaults, day-by-day changes and school cutoff times — via MCP",
-      "version": "1.1.2",
+      "version": "1.1.4",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pickuppatrol",
   "displayName": "PickUp Patrol",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Read and change your children's school dismissal plans in PickUp Patrol — defaults, day-by-day changes and school cutoff times — via MCP",
   "author": {
     "name": "Chris Chall"

package/README.md

@@ -58,7 +58,7 @@ and only reports the configuration error on the first tool call.
 | `pup_get_school` | School profile, notify times, cutoff times, settings |
 | `pup_list_non_school_days` | Dates no plan can be set for, and dates already changed |
 | `pup_list_car_numbers` | Car numbers the school issued to this account |
-| `pup_healthcheck` | Credentials sign in and the API answers |
+| `pup_healthcheck` | Credentials sign in and the API answers; on failure, `error.kind` says which hop broke (`edge_blocked`, `credential_rejected`, …) |
 
 **Writes** — every one asks you to confirm first. A client that can show a
 confirmation prompt (Claude Code) shows one. Otherwise the first call makes no
@@ -78,7 +78,7 @@ change and returns a preview of the exact payload it would send plus a
 |---|---|---|
 | `MCP_CONFIRM_MODE` | `ask-user` | What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). `ask-user`: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. `auto`: the same two steps, but the model may use the token after reviewing the preview itself. `refuse`: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt. An unrecognised value is treated as `refuse`. |
 | `MCP_CONFIRM_TTL_SECONDS` | `600` | How long a token stays valid. |
-| `MCP_CONFIRM_SECRET` | random per process | Signing key; set it only if tokens must survive a server restart. |
+| `MCP_CONFIRM_SECRET` | random per process | Signing key; set it only if tokens must survive a server restart. On mcp-host the host supplies a stable per-child key (`MCP_HOST_CONFIRM_SECRET`) and spent tokens are recorded under `MCP_DATA_DIR`, so an approval survives an idle restart. |
 
 A token is single-use and bound to the exact payload. The second call re-reads
 the student and rebuilds the payload, so if anything moved between the preview

package/dist/auth.d.ts

@@ -1,3 +1,4 @@
+import { McpToolError } from '@chrischall/mcp-utils';
 import type { ResponseStatus } from './types.js';
 export declare const BASE_URL = "https://app.pickuppatrol.net";
 export declare const BASE_PATH = "/api/json/reply";
@@ -33,6 +34,31 @@ export interface AuthOptions {
  * errors are more specific than the top-level message, so they win.
  */
 export declare function describeResponseStatus(status: ResponseStatus | null | undefined): string | null;
+/** The service name {@link EdgeBlockedError} messages carry. */
+export declare const SERVICE = "PickUp Patrol";
+/**
+ * PickUp Patrol JUDGED the username and password and refused them. Its own
+ * class so the healthcheck can say `credential_rejected` without matching
+ * message prose.
+ */
+export declare class SignInRejectedError extends McpToolError {
+    constructor(message: string, hint: string);
+}
+/**
+ * The sign-in "succeeded" but produced no usable session — in practice a
+ * two-factor account, which this server does not complete.
+ */
+export declare class UnusableSessionError extends McpToolError {
+    constructor(message: string, hint: string);
+}
+/**
+ * Was this response refused by a CDN/WAF in front of PickUp Patrol rather than
+ * by PickUp Patrol? Reads a CLONE, so the caller's body stays readable. A JSON
+ * body is never a refusal page, so it is not read.
+ */
+export declare function edgeBlockOfResponse(res: Response): Promise<{
+    vendor: string;
+} | null>;
 /**
  * Owns the login lifecycle: one lazy, single-flight sign-in; a cached
  * *permanent* failure for anything that means "these credentials will never
@@ -48,6 +74,12 @@ export declare class PickUpPatrolAuth {
     private inFlight;
     private permanentError;
     constructor(opts?: AuthOptions);
+    /**
+     * Where the credentials came from, for the healthcheck — `'env'` when a
+     * username and password are configured (from the environment or the
+     * constructor), `null` when they are not. Never the credential itself.
+     */
+    get credentialSource(): string | null;
     /** True once a login has succeeded — used by the healthcheck tool. */
     get isAuthenticated(): boolean;
     /**
@@ -69,8 +101,14 @@ export declare class PickUpPatrolAuth {
      * ARRAffinity cookie means the jar is never empty), so this is where it is
      * caught, and it is cached as permanent: otherwise every later call would
      * spend two more sign-ins against the account.
+     *
+     * A 401 that is a CDN/WAF refusal page is NOT a rejected session: the
+     * request never reached PickUp Patrol, so the session is kept, no sign-in is
+     * spent, and the block is reported as an {@link EdgeBlockedError}
+     * (chrischall/mcp-host#1015).
      */
     withAuth(call: (session: PupSession) => Promise<Response>): Promise<Response>;
+    private throwIfEdgeBlocked;
     private login;
 }
 /**

package/dist/auth.js

@@ -1,4 +1,4 @@
-import { readEnvVar, McpToolError, CookieJar } from '@chrischall/mcp-utils';
+import { readEnvVar, McpToolError, CookieJar, EdgeBlockedError, detectEdgeBlock, } from '@chrischall/mcp-utils';
 export const BASE_URL = 'https://app.pickuppatrol.net';
 export const BASE_PATH = '/api/json/reply';
 /** Upper bound on any one request to PickUp Patrol, sign-in included. */
@@ -13,6 +13,49 @@ export function describeResponseStatus(status) {
     const fieldError = status.Errors?.find((e) => e?.Message);
     return fieldError?.Message ?? status.Message ?? status.ErrorCode ?? null;
 }
+/** The service name {@link EdgeBlockedError} messages carry. */
+export const SERVICE = 'PickUp Patrol';
+/**
+ * PickUp Patrol JUDGED the username and password and refused them. Its own
+ * class so the healthcheck can say `credential_rejected` without matching
+ * message prose.
+ */
+export class SignInRejectedError extends McpToolError {
+    constructor(message, hint) {
+        super(message, { hint });
+        this.name = 'SignInRejectedError';
+    }
+}
+/**
+ * The sign-in "succeeded" but produced no usable session — in practice a
+ * two-factor account, which this server does not complete.
+ */
+export class UnusableSessionError extends McpToolError {
+    constructor(message, hint) {
+        super(message, { hint });
+        this.name = 'UnusableSessionError';
+    }
+}
+/**
+ * Was this response refused by a CDN/WAF in front of PickUp Patrol rather than
+ * by PickUp Patrol? Reads a CLONE, so the caller's body stays readable. A JSON
+ * body is never a refusal page, so it is not read.
+ */
+export async function edgeBlockOfResponse(res) {
+    const byHeaders = detectEdgeBlock({ status: res.status, headers: res.headers });
+    if (byHeaders !== null)
+        return byHeaders;
+    if (/json/i.test(String(res.headers.get('content-type'))))
+        return null;
+    let body;
+    try {
+        body = await res.clone().text();
+    }
+    catch {
+        return null;
+    }
+    return detectEdgeBlock({ body, status: res.status, headers: res.headers });
+}
 /**
  * Owns the login lifecycle: one lazy, single-flight sign-in; a cached
  * *permanent* failure for anything that means "these credentials will never
@@ -48,6 +91,14 @@ export class PickUpPatrolAuth {
         this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
         this.timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
     }
+    /**
+     * Where the credentials came from, for the healthcheck — `'env'` when a
+     * username and password are configured (from the environment or the
+     * constructor), `null` when they are not. Never the credential itself.
+     */
+    get credentialSource() {
+        return this.configError ? null : 'env';
+    }
     /** True once a login has succeeded — used by the healthcheck tool. */
     get isAuthenticated() {
         return this.session !== null;
@@ -91,21 +142,32 @@ export class PickUpPatrolAuth {
      * ARRAffinity cookie means the jar is never empty), so this is where it is
      * caught, and it is cached as permanent: otherwise every later call would
      * spend two more sign-ins against the account.
+     *
+     * A 401 that is a CDN/WAF refusal page is NOT a rejected session: the
+     * request never reached PickUp Patrol, so the session is kept, no sign-in is
+     * spent, and the block is reported as an {@link EdgeBlockedError}
+     * (chrischall/mcp-host#1015).
      */
     async withAuth(call) {
         const first = await call(await this.ensure());
         if (first.status !== 401)
             return first;
+        await this.throwIfEdgeBlocked(first);
         this.invalidate();
         const replay = await call(await this.ensure());
         if (replay.status !== 401)
             return replay;
+        await this.throwIfEdgeBlocked(replay);
         this.invalidate();
-        this.permanentError = new McpToolError('PickUp Patrol accepted the sign-in but rejected the session it just issued', {
-            hint: 'This usually means the account has two-factor authentication enabled, which this server does not yet complete. Sign in at https://app.pickuppatrol.net/ to check, then restart the server.',
-        });
+        this.permanentError = new UnusableSessionError('PickUp Patrol accepted the sign-in but rejected the session it just issued', 'This usually means the account has two-factor authentication enabled, which this server does not yet complete. Sign in at https://app.pickuppatrol.net/ to check, then restart the server.');
         throw this.permanentError;
     }
+    async throwIfEdgeBlocked(res) {
+        const edge = await edgeBlockOfResponse(res);
+        if (edge !== null) {
+            throw new EdgeBlockedError(res.status, edge.vendor, { service: SERVICE });
+        }
+    }
     async login() {
         // Bounded like every other request. `ensure()` shares this promise with
         // every concurrent and later caller until it settles, so an unanswered
@@ -114,7 +176,7 @@ export class PickUpPatrolAuth {
         // body read below.
         const signal = AbortSignal.timeout(this.timeoutMs);
         let res;
-        let body;
+        let text;
         try {
             res = await this.fetchImpl(`${BASE_URL}${BASE_PATH}/Authenticate`, {
                 method: 'POST',
@@ -128,11 +190,11 @@ export class PickUpPatrolAuth {
                 redirect: 'manual',
                 signal,
             });
-            body = (await res.json().catch((err) => {
+            text = await res.text().catch((err) => {
                 if (signal.aborted)
                     throw err;
-                return null;
-            }));
+                return '';
+            });
         }
         catch (err) {
             // Transient: a timeout says nothing about the credentials, so it is
@@ -142,19 +204,41 @@ export class PickUpPatrolAuth {
             }
             throw err;
         }
+        let body = null;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // Not JSON: a gateway page, or a CDN/WAF refusal page. A refusal never
+            // reached PickUp Patrol, so the credentials were not judged — it is
+            // reported as a block and never cached as permanent, so the next call
+            // signs in afresh (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: 'POST',
+                    path: `${BASE_PATH}/Authenticate`,
+                });
+            }
+        }
         if (!res.ok) {
             const detail = describeResponseStatus(body?.ResponseStatus);
             const code = body?.ResponseStatus?.ErrorCode ?? '';
-            const error = new McpToolError(`PickUp Patrol rejected the sign-in${detail ? `: ${detail}` : ` (HTTP ${res.status})`}`, {
-                hint: 'Check PICKUPPATROL_USERNAME and PICKUPPATROL_PASSWORD against https://app.pickuppatrol.net/.',
-            });
+            const message = `PickUp Patrol rejected the sign-in${detail ? `: ${detail}` : ` (HTTP ${res.status})`}`;
+            const hint = 'Check PICKUPPATROL_USERNAME and PICKUPPATROL_PASSWORD against https://app.pickuppatrol.net/.';
+            // Only a credential the service JUDGED is a rejection. A 5xx or an
+            // unexplained 4xx stays a plain error, so the healthcheck reports it by
+            // status rather than sending someone to change a working password.
+            const judged = res.status >= 400 && res.status < 500 && code.startsWith('LOGIN-ERROR');
+            const error = judged ? new SignInRejectedError(message, hint) : new McpToolError(message, { hint });
             // A credential the service has *judged* is never retried. PickUp Patrol
             // counts failures against the account and clearing a lockout goes
             // through their support desk, so a retry loop would destroy the only
             // auth path we have. Caching the error means every later call fails
             // instantly with the same message instead of spending another attempt.
             // A 5xx or a network blip is left transient so the next call retries.
-            if (res.status >= 400 && res.status < 500 && code.startsWith('LOGIN-ERROR')) {
+            if (judged) {
                 this.permanentError = error;
             }
             throw error;
@@ -166,9 +250,7 @@ export class PickUpPatrolAuth {
         const cookieHeader = collectCookieHeader(res);
         const bearerToken = body?.BearerToken ?? null;
         if (!bearerToken && !cookieHeader) {
-            this.permanentError = new McpToolError('PickUp Patrol accepted the sign-in but returned no session token or cookie', {
-                hint: 'This usually means the account has two-factor authentication enabled, which this server does not yet complete. Sign in at https://app.pickuppatrol.net/ to check.',
-            });
+            this.permanentError = new UnusableSessionError('PickUp Patrol accepted the sign-in but returned no session token or cookie', 'This usually means the account has two-factor authentication enabled, which this server does not yet complete. Sign in at https://app.pickuppatrol.net/ to check.');
             throw this.permanentError;
         }
         return { bearerToken, refreshToken: body?.RefreshToken ?? null, cookieHeader };