@chrischall/pickuppatrol-mcp 1.2.0 → 1.2.2

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "PickUp Patrol school-dismissal tools for Claude Code",
-    "version": "1.2.0"
+    "version": "1.2.2"
   },
   "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.2.0",
+      "version": "1.2.2",
       "author": {
         "name": "Chris Chall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pickuppatrol",
   "displayName": "PickUp Patrol",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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"
@@ -18,5 +18,5 @@
     "mcp"
   ],
   "skills": "./skills/",
-  "mcp": "./.mcp.json"
+  "mcpServers": "./.mcp.json"
 }

package/README.md

@@ -60,6 +60,14 @@ and only reports the configuration error on the first tool call.
 | `pup_list_car_numbers` | Car numbers the school issued to this account |
 | `pup_healthcheck` | Credentials sign in and the API answers; on failure, `error.kind` says which hop broke (`edge_blocked`, `credential_rejected`, …) |
 
+Reads are projected to known fields. Plan notes can be written by any guardian
+on the account, and option hints and school settings by school staff, so every
+read that carries them is marked `untrusted_content` with a note telling the
+model to treat the text as data, not instructions. `pup_list_plans`,
+`pup_get_plan`, `pup_get_school` and `pup_get_student` take `raw: true` for the
+untouched API record (still marked untrusted) — the only way to see fields such
+as `SASId` or `SafetyFlag`.
+
 **Writes** — every one asks you to confirm first. A client that can show a
 confirmation prompt (Claude Code) shows one, unless `MCP_CONFIRM_ELICITATION=off`.
 Otherwise the first call makes no

package/dist/auth.d.ts

@@ -4,6 +4,15 @@ export declare const BASE_URL = "https://app.pickuppatrol.net";
 export declare const BASE_PATH = "/api/json/reply";
 /** Upper bound on any one request to PickUp Patrol, sign-in included. */
 export declare const REQUEST_TIMEOUT_MS = 30000;
+/**
+ * How long a "sign-in accepted, fresh session rejected" result is held before
+ * the next call may sign in again. That result is inferred from two 401s, not
+ * judged by the service (a session-store blip during an Azure slot swap looks
+ * the same), so it must not brick a long-running server until restart — but
+ * holding it a while keeps a genuine two-factor account from spending two
+ * sign-ins on every call.
+ */
+export declare const UNUSABLE_SESSION_COOLDOWN_MS: number;
 /** Minimal `fetch` seam so tests never open a socket. */
 export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
 /**
@@ -17,7 +26,12 @@ export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
 export interface PupSession {
     /** `Authorization: Bearer …`, when the deployment issues JWTs. */
     bearerToken: string | null;
-    /** Exchangeable for a fresh bearer token via `GetAccessToken`. */
+    /**
+     * The login's `RefreshToken`, if any. Nothing in this package reads it.
+     *
+     * @deprecated Unused; kept only because `PupSession` is public library
+     * surface. It will be removed in the next major release.
+     */
     refreshToken: string | null;
     /** `Cookie:` header value built from every `Set-Cookie` the login returned. */
     cookieHeader: string;
@@ -28,6 +42,8 @@ export interface AuthOptions {
     fetchImpl?: FetchLike;
     /** Sign-in timeout; defaults to `REQUEST_TIMEOUT_MS`. A test seam. */
     timeoutMs?: number;
+    /** Clock for the unusable-session cool-down; defaults to `Date.now`. A test seam. */
+    now?: () => number;
 }
 /**
  * Pull the most useful message out of a ServiceStack error envelope. Field
@@ -70,9 +86,13 @@ export declare class PickUpPatrolAuth {
     private readonly configError;
     private readonly fetchImpl;
     private readonly timeoutMs;
+    private readonly now;
     private session;
     private inFlight;
     private permanentError;
+    /** The double-401 latch: held until `unusableUntil`, then lifted. */
+    private unusableError;
+    private unusableUntil;
     constructor(opts?: AuthOptions);
     /**
      * Where the credentials came from, for the healthcheck — `'env'` when a
@@ -80,6 +100,13 @@ export declare class PickUpPatrolAuth {
      * constructor), `null` when they are not. Never the credential itself.
      */
     get credentialSource(): string | null;
+    /**
+     * The account writes run as — the configured username, case-folded so
+     * `Parent@x` and `parent@x` are one account — or `undefined` when none is
+     * configured. Bound into every confirmation token, so under a shared
+     * `MCP_CONFIRM_SECRET` an approval for one account never acts as another.
+     */
+    get account(): string | undefined;
     /** True once a login has succeeded — used by the healthcheck tool. */
     get isAuthenticated(): boolean;
     /**
@@ -89,6 +116,8 @@ export declare class PickUpPatrolAuth {
     ensure(): Promise<PupSession>;
     /** Drop the cached session so the next `ensure()` signs in again. */
     invalidate(): void;
+    /** Drop the cached session only if it is still `session`. */
+    private invalidateIfCurrent;
     /**
      * Run an authenticated request. On a 401 the session is dropped, re-minted
      * once and the call replayed exactly once — never more, so a server that
@@ -99,8 +128,10 @@ export declare class PickUpPatrolAuth {
      * "succeeding" without producing a usable session — in practice a
      * two-factor account. The login-time check cannot see that (Azure's
      * 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.
+     * caught. It is held for {@link UNUSABLE_SESSION_COOLDOWN_MS} — otherwise
+     * every later call would spend two more sign-ins against the account — but
+     * not forever: it is inferred from a status code, not judged by the
+     * service, so a transient session-store failure must not brick the server.
      *
      * 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

package/dist/auth.js

@@ -1,8 +1,17 @@
-import { readEnvVar, McpToolError, CookieJar, EdgeBlockedError, detectEdgeBlock, } from '@chrischall/mcp-utils';
+import { readEnvVar, McpToolError, CookieJar, EdgeBlockedError, detectEdgeBlock, withAmbientCancellation, } 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. */
 export const REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * How long a "sign-in accepted, fresh session rejected" result is held before
+ * the next call may sign in again. That result is inferred from two 401s, not
+ * judged by the service (a session-store blip during an Azure slot swap looks
+ * the same), so it must not brick a long-running server until restart — but
+ * holding it a while keeps a genuine two-factor account from spending two
+ * sign-ins on every call.
+ */
+export const UNUSABLE_SESSION_COOLDOWN_MS = 10 * 60_000;
 /**
  * Pull the most useful message out of a ServiceStack error envelope. Field
  * errors are more specific than the top-level message, so they win.
@@ -67,9 +76,13 @@ export class PickUpPatrolAuth {
     configError;
     fetchImpl;
     timeoutMs;
+    now;
     session = null;
     inFlight = null;
     permanentError = null;
+    /** The double-401 latch: held until `unusableUntil`, then lifted. */
+    unusableError = null;
+    unusableUntil = 0;
     constructor(opts = {}) {
         const username = opts.username ?? readEnvVar('PICKUPPATROL_USERNAME');
         const password = opts.password ?? readEnvVar('PICKUPPATROL_PASSWORD');
@@ -90,6 +103,7 @@ export class PickUpPatrolAuth {
         }
         this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
         this.timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
+        this.now = opts.now ?? Date.now;
     }
     /**
      * Where the credentials came from, for the healthcheck — `'env'` when a
@@ -99,6 +113,15 @@ export class PickUpPatrolAuth {
     get credentialSource() {
         return this.configError ? null : 'env';
     }
+    /**
+     * The account writes run as — the configured username, case-folded so
+     * `Parent@x` and `parent@x` are one account — or `undefined` when none is
+     * configured. Bound into every confirmation token, so under a shared
+     * `MCP_CONFIRM_SECRET` an approval for one account never acts as another.
+     */
+    get account() {
+        return this.username === null ? undefined : this.username.trim().toLowerCase();
+    }
     /** True once a login has succeeded — used by the healthcheck tool. */
     get isAuthenticated() {
         return this.session !== null;
@@ -112,6 +135,11 @@ export class PickUpPatrolAuth {
             throw this.configError;
         if (this.permanentError)
             throw this.permanentError;
+        if (this.unusableError) {
+            if (this.now() < this.unusableUntil)
+                throw this.unusableError;
+            this.unusableError = null;
+        }
         if (this.session)
             return this.session;
         if (this.inFlight)
@@ -130,6 +158,11 @@ export class PickUpPatrolAuth {
     invalidate() {
         this.session = null;
     }
+    /** Drop the cached session only if it is still `session`. */
+    invalidateIfCurrent(session) {
+        if (this.session === session)
+            this.session = null;
+    }
     /**
      * Run an authenticated request. On a 401 the session is dropped, re-minted
      * once and the call replayed exactly once — never more, so a server that
@@ -140,8 +173,10 @@ export class PickUpPatrolAuth {
      * "succeeding" without producing a usable session — in practice a
      * two-factor account. The login-time check cannot see that (Azure's
      * 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.
+     * caught. It is held for {@link UNUSABLE_SESSION_COOLDOWN_MS} — otherwise
+     * every later call would spend two more sign-ins against the account — but
+     * not forever: it is inferred from a status code, not judged by the
+     * service, so a transient session-store failure must not brick the server.
      *
      * 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
@@ -149,18 +184,24 @@ export class PickUpPatrolAuth {
      * (chrischall/mcp-host#1015).
      */
     async withAuth(call) {
-        const first = await call(await this.ensure());
+        const used = await this.ensure();
+        const first = await call(used);
         if (first.status !== 401)
             return first;
         await this.throwIfEdgeBlocked(first);
-        this.invalidate();
-        const replay = await call(await this.ensure());
+        // Only drop the session this call actually used. A concurrent caller may
+        // already have re-minted it; throwing that fresh session away would spend
+        // another sign-in against the account for nothing.
+        this.invalidateIfCurrent(used);
+        const replaySession = await this.ensure();
+        const replay = await call(replaySession);
         if (replay.status !== 401)
             return replay;
         await this.throwIfEdgeBlocked(replay);
-        this.invalidate();
-        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;
+        this.invalidateIfCurrent(replaySession);
+        this.unusableError = 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. To spare the account further sign-ins, the server waits ${UNUSABLE_SESSION_COOLDOWN_MS / 60_000} minutes before trying again.`);
+        this.unusableUntil = this.now() + UNUSABLE_SESSION_COOLDOWN_MS;
+        throw this.unusableError;
     }
     async throwIfEdgeBlocked(res) {
         const edge = await edgeBlockOfResponse(res);
@@ -174,7 +215,10 @@ export class PickUpPatrolAuth {
         // sign-in would otherwise stall every tool — the healthcheck included —
         // for as long as undici's own ~300s default. The signal also covers the
         // body read below.
-        const signal = AbortSignal.timeout(this.timeoutMs);
+        // The running call's cancellation is folded in too, so a cancelled call
+        // does not leave the shared sign-in running for the full deadline.
+        const deadline = AbortSignal.timeout(this.timeoutMs);
+        const signal = withAmbientCancellation(deadline);
         let res;
         let text;
         try {
@@ -199,7 +243,7 @@ export class PickUpPatrolAuth {
         catch (err) {
             // Transient: a timeout says nothing about the credentials, so it is
             // never cached as permanentError and the next call signs in afresh.
-            if (signal.aborted) {
+            if (deadline.aborted) {
                 throw new McpToolError(`PickUp Patrol did not answer the sign-in within ${this.timeoutMs / 1000}s`, { hint: 'The service may be slow or down. Try again shortly.' });
             }
             throw err;