@chrischall/pickuppatrol-mcp 1.0.1 → 1.1.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pickuppatrol",
   "displayName": "PickUp Patrol",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "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

@@ -60,8 +60,11 @@ 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 |
 
-**Writes** — every one requires `confirm: true`. Without it the tool makes no
-change and returns a dry-run of the exact payload it would send.
+**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
+change and returns a preview of the exact payload it would send plus a
+`confirmToken`, and only a repeat call with that token makes the change — see
+[Confirmations](#confirmations).
 
 | Tool | What it changes |
 |---|---|
@@ -69,6 +72,20 @@ change and returns a dry-run of the exact payload it would send.
 | `pup_set_default_plans` | The weekly default plan, or clears every default |
 | `pup_mark_defaults_reviewed` | The school's "defaults need review" prompt |
 
+### Confirmations
+
+| variable | default | |
+|---|---|---|
+| `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. |
+
+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
+and the approval — a different date or option, or (for default plans, which
+round-trip the whole student record) a change made to the record meanwhile —
+nothing is sent and you get `DRAFT_CHANGED` with a fresh preview.
+
 ### Two things the tools do that the API does not
 
 **Rules are enforced before anything is sent.** Each dismissal option carries its

package/dist/auth.d.ts

@@ -1,6 +1,8 @@
 import type { ResponseStatus } from './types.js';
 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;
 /** Minimal `fetch` seam so tests never open a socket. */
 export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
 /**
@@ -23,6 +25,8 @@ export interface AuthOptions {
     username?: string;
     password?: string;
     fetchImpl?: FetchLike;
+    /** Sign-in timeout; defaults to `REQUEST_TIMEOUT_MS`. A test seam. */
+    timeoutMs?: number;
 }
 /**
  * Pull the most useful message out of a ServiceStack error envelope. Field
@@ -39,6 +43,7 @@ export declare class PickUpPatrolAuth {
     private readonly password;
     private readonly configError;
     private readonly fetchImpl;
+    private readonly timeoutMs;
     private session;
     private inFlight;
     private permanentError;
@@ -57,6 +62,13 @@ export declare class PickUpPatrolAuth {
      * once and the call replayed exactly once — never more, so a server that
      * answers 401 unconditionally cannot turn into a login loop against the
      * account.
+     *
+     * If the session minted for the replay is rejected too, the sign-in is
+     * "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.
      */
     withAuth(call: (session: PupSession) => Promise<Response>): Promise<Response>;
     private login;

package/dist/auth.js

@@ -1,6 +1,8 @@
 import { readEnvVar, McpToolError, CookieJar } 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;
 /**
  * Pull the most useful message out of a ServiceStack error envelope. Field
  * errors are more specific than the top-level message, so they win.
@@ -21,6 +23,7 @@ export class PickUpPatrolAuth {
     password;
     configError;
     fetchImpl;
+    timeoutMs;
     session = null;
     inFlight = null;
     permanentError = null;
@@ -43,6 +46,7 @@ export class PickUpPatrolAuth {
             this.configError = null;
         }
         this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+        this.timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
     }
     /** True once a login has succeeded — used by the healthcheck tool. */
     get isAuthenticated() {
@@ -80,27 +84,64 @@ export class PickUpPatrolAuth {
      * once and the call replayed exactly once — never more, so a server that
      * answers 401 unconditionally cannot turn into a login loop against the
      * account.
+     *
+     * If the session minted for the replay is rejected too, the sign-in is
+     * "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.
      */
     async withAuth(call) {
         const first = await call(await this.ensure());
         if (first.status !== 401)
             return first;
         this.invalidate();
-        return call(await this.ensure());
+        const replay = await call(await this.ensure());
+        if (replay.status !== 401)
+            return 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.',
+        });
+        throw this.permanentError;
     }
     async login() {
-        const res = await this.fetchImpl(`${BASE_URL}${BASE_PATH}/Authenticate`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-            body: JSON.stringify({
-                provider: 'credentials',
-                UserName: this.username,
-                Password: this.password,
-                RememberMe: true,
-            }),
-            redirect: 'manual',
-        });
-        const body = (await res.json().catch(() => null));
+        // Bounded like every other request. `ensure()` shares this promise with
+        // every concurrent and later caller until it settles, so an unanswered
+        // 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);
+        let res;
+        let body;
+        try {
+            res = await this.fetchImpl(`${BASE_URL}${BASE_PATH}/Authenticate`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                body: JSON.stringify({
+                    provider: 'credentials',
+                    UserName: this.username,
+                    Password: this.password,
+                    RememberMe: true,
+                }),
+                redirect: 'manual',
+                signal,
+            });
+            body = (await res.json().catch((err) => {
+                if (signal.aborted)
+                    throw err;
+                return null;
+            }));
+        }
+        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) {
+                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;
+        }
         if (!res.ok) {
             const detail = describeResponseStatus(body?.ResponseStatus);
             const code = body?.ResponseStatus?.ErrorCode ?? '';
@@ -119,8 +160,9 @@ export class PickUpPatrolAuth {
             throw error;
         }
         // Two-factor accounts return a session that is not yet usable; the SPA
-        // routes them to /two-factor. Surface that plainly rather than letting
-        // every subsequent read fail with an opaque 401.
+        // routes them to /two-factor. A login with no token and no cookie at all
+        // is caught here; the live deployment always sets ARRAffinity, though, so
+        // the usual two-factor signal is the rejected fresh session in withAuth().
         const cookieHeader = collectCookieHeader(res);
         const bearerToken = body?.BearerToken ?? null;
         if (!bearerToken && !cookieHeader) {