@chrischall/pickuppatrol-mcp 0.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,35 @@
+{
+  "name": "chrischall",
+  "owner": {
+    "name": "Chris Chall",
+    "email": "chris.c.hall@gmail.com"
+  },
+  "metadata": {
+    "description": "PickUp Patrol school-dismissal tools for Claude Code",
+    "version": "0.0.0"
+  },
+  "plugins": [
+    {
+      "name": "pickuppatrol",
+      "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": "0.0.0",
+      "author": {
+        "name": "Chris Chall"
+      },
+      "homepage": "https://github.com/chrischall/pickuppatrol-mcp",
+      "repository": "https://github.com/chrischall/pickuppatrol-mcp",
+      "license": "MIT",
+      "keywords": [
+        "pickuppatrol",
+        "school",
+        "dismissal",
+        "carpool",
+        "parents",
+        "mcp"
+      ],
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "pickuppatrol",
+  "displayName": "PickUp Patrol",
+  "version": "0.0.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"
+  },
+  "homepage": "https://github.com/chrischall/pickuppatrol-mcp",
+  "repository": "https://github.com/chrischall/pickuppatrol-mcp",
+  "license": "MIT",
+  "keywords": [
+    "pickuppatrol",
+    "school",
+    "dismissal",
+    "carpool",
+    "parents",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcp": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "pickuppatrol": {
+      "command": "npx",
+      "args": ["-y", "@chrischall/pickuppatrol-mcp"]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# pickuppatrol-mcp
+
+An MCP server for [PickUp Patrol](https://www.pickuppatrol.net/) — the school
+dismissal app. Read and change how your children leave school: their weekly
+default plan, one-off changes for specific dates, and the school's dismissal
+options and cutoff times.
+
+> Developed and maintained by AI (Claude Code). Use at your own discretion.
+
+## What it talks to
+
+`app.pickuppatrol.net` runs a [ServiceStack](https://servicestack.net/) JSON API
+behind an Ionic/Vue SPA. There is no published API, but the service is reachable
+server-side with an ordinary HTTPS request — no browser extension, no bot wall,
+no captcha. The server signs in with your own email and password and holds the
+resulting session in memory.
+
+Every request shape is captured in [`docs/PICKUPPATROL-API.md`](docs/PICKUPPATROL-API.md),
+read off the shipped client rather than guessed.
+
+## Install
+
+```jsonc
+// .mcp.json
+{
+  "mcpServers": {
+    "pickuppatrol": {
+      "command": "npx",
+      "args": ["-y", "@chrischall/pickuppatrol-mcp"],
+      "env": {
+        "PICKUPPATROL_USERNAME": "you@example.com",
+        "PICKUPPATROL_PASSWORD": "…"
+      }
+    }
+  }
+}
+```
+
+For local development, copy `.env.example` to `.env` and fill it in.
+
+The server starts without credentials — it answers the host's install-time probe
+and only reports the configuration error on the first tool call.
+
+## Tools
+
+**Reads**
+
+| Tool | What it gives you |
+|---|---|
+| `pup_get_session` | The signed-in account and the students linked to it |
+| `pup_list_students` | Every student with their weekly defaults and review flag |
+| `pup_get_student` | One student in full |
+| `pup_get_default_plans` | A student's weekly default plan, day by day |
+| `pup_list_plans` | Day-by-day plans across a date range |
+| `pup_get_plan` | One student, one date — including whether it is locked |
+| `pup_list_transportations` | A school's dismissal options and the rules each imposes |
+| `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 |
+
+**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.
+
+| Tool | What it changes |
+|---|---|
+| `pup_set_plan` | Dismissal for one or more specific dates, or clears them back to the default |
+| `pup_set_default_plans` | The weekly default plan, or clears every default |
+| `pup_mark_defaults_reviewed` | The school's "defaults need review" prompt |
+
+### Two things the tools do that the API does not
+
+**Rules are enforced before anything is sent.** Each dismissal option carries its
+own requirements — a note, a car number, an early-dismissal time, or a
+restriction to particular students. `pup_set_plan` checks them against the
+school's own list and refuses with the school's wording, so a rejected write is
+a validation message rather than an opaque 400.
+
+**Writes are verified by re-reading.** A 2xx from PickUp Patrol is not proof: a
+change made after the school's cutoff is accepted and silently ignored. Every
+write re-reads the affected dates and compares the transportation id — never
+`ModifiedDate`, which advances on its own and would make every write look
+successful. The result says `verified: true/false`, and names the dates that did
+not move.
+
+## Without the MCP server
+
+`skills/pickuppatrol-api/` is a shell-out skill covering the same API with
+`curl` and `jq`, for scripts or a machine where the server is not installed.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test              # fast
+npm run test:coverage # coverage-enforced at 100%
+```
+
+Tests never touch the network: the transport is injected, and the MCP tools run
+through a real in-memory client/server pair.
+
+## Safety notes
+
+- A rejected sign-in is **never retried**. PickUp Patrol counts failed attempts
+  against the account and a lockout clears only through their support desk, so
+  the error is cached and every later call fails instantly with the same message.
+- The weekly-default write is a read-modify-write of the whole student record,
+  because the API has no default-plans endpoint. The server always reads the
+  student immediately before writing, and changes only `DefaultPlans`.
+- Credentials live in `.env` (gitignored) or the MCP host's config, and are
+  never written to a result or a log.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,72 @@
+import type { ResponseStatus } from './types.js';
+export declare const BASE_URL = "https://app.pickuppatrol.net";
+export declare const BASE_PATH = "/api/json/reply";
+/** Minimal `fetch` seam so tests never open a socket. */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * What a successful login yields. PickUp Patrol's ServiceStack deployment can
+ * authenticate either way and the SPA is built for both: its client reads a
+ * `bearerToken` out of `localStorage` when one is present, and otherwise rides
+ * the `ss-id`/`ss-pid` session cookies it sets `credentials: 'include'` for.
+ * We keep whichever the server actually hands back and send both when we have
+ * them, so the client does not depend on which mode the deployment is in.
+ */
+export interface PupSession {
+    /** `Authorization: Bearer …`, when the deployment issues JWTs. */
+    bearerToken: string | null;
+    /** Exchangeable for a fresh bearer token via `GetAccessToken`. */
+    refreshToken: string | null;
+    /** `Cookie:` header value built from every `Set-Cookie` the login returned. */
+    cookieHeader: string;
+}
+export interface AuthOptions {
+    username?: string;
+    password?: string;
+    fetchImpl?: FetchLike;
+}
+/**
+ * Pull the most useful message out of a ServiceStack error envelope. Field
+ * errors are more specific than the top-level message, so they win.
+ */
+export declare function describeResponseStatus(status: ResponseStatus | null | undefined): string | null;
+/**
+ * Owns the login lifecycle: one lazy, single-flight sign-in; a cached
+ * *permanent* failure for anything that means "these credentials will never
+ * work"; and exactly one re-login + replay when a request comes back 401.
+ */
+export declare class PickUpPatrolAuth {
+    private readonly username;
+    private readonly password;
+    private readonly configError;
+    private readonly fetchImpl;
+    private session;
+    private inFlight;
+    private permanentError;
+    constructor(opts?: AuthOptions);
+    /** True once a login has succeeded — used by the healthcheck tool. */
+    get isAuthenticated(): boolean;
+    /**
+     * A valid session, logging in on first use. Concurrent callers share one
+     * in-flight login rather than racing several sign-ins at the same account.
+     */
+    ensure(): Promise<PupSession>;
+    /** Drop the cached session so the next `ensure()` signs in again. */
+    invalidate(): void;
+    /**
+     * 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
+     * answers 401 unconditionally cannot turn into a login loop against the
+     * account.
+     */
+    withAuth(call: (session: PupSession) => Promise<Response>): Promise<Response>;
+    private login;
+}
+/**
+ * Build a `Cookie:` request header from every `Set-Cookie` on a response.
+ * ServiceStack sets more than one (`ss-id`, `ss-pid`, `ss-opt`) alongside
+ * Azure's `ARRAffinity` pair, and the session needs all of them — so this
+ * keeps the whole jar rather than picking a named cookie out of it. `CookieJar`
+ * also drops the deletion markers a login response mixes in, which some
+ * upstreams reject when echoed back.
+ */
+export declare function collectCookieHeader(res: Response): string;

package/dist/auth.js

@@ -0,0 +1,147 @@
+import { readEnvVar, McpToolError, CookieJar } from '@chrischall/mcp-utils';
+export const BASE_URL = 'https://app.pickuppatrol.net';
+export const BASE_PATH = '/api/json/reply';
+/**
+ * Pull the most useful message out of a ServiceStack error envelope. Field
+ * errors are more specific than the top-level message, so they win.
+ */
+export function describeResponseStatus(status) {
+    if (!status)
+        return null;
+    const fieldError = status.Errors?.find((e) => e?.Message);
+    return fieldError?.Message ?? status.Message ?? status.ErrorCode ?? null;
+}
+/**
+ * Owns the login lifecycle: one lazy, single-flight sign-in; a cached
+ * *permanent* failure for anything that means "these credentials will never
+ * work"; and exactly one re-login + replay when a request comes back 401.
+ */
+export class PickUpPatrolAuth {
+    username;
+    password;
+    configError;
+    fetchImpl;
+    session = null;
+    inFlight = null;
+    permanentError = null;
+    constructor(opts = {}) {
+        const username = opts.username ?? readEnvVar('PICKUPPATROL_USERNAME');
+        const password = opts.password ?? readEnvVar('PICKUPPATROL_PASSWORD');
+        // Deferred config error: the server must still boot (and answer the host's
+        // install-time tools/list probe) with no credentials set. The error is
+        // raised at request time instead.
+        if (!username || !password) {
+            this.username = null;
+            this.password = null;
+            this.configError = new McpToolError('PICKUPPATROL_USERNAME and PICKUPPATROL_PASSWORD are required', {
+                hint: 'Set both in the MCP host config (or a local .env) to the email and password you use at https://app.pickuppatrol.net/.',
+            });
+        }
+        else {
+            this.username = username;
+            this.password = password;
+            this.configError = null;
+        }
+        this.fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, init));
+    }
+    /** True once a login has succeeded — used by the healthcheck tool. */
+    get isAuthenticated() {
+        return this.session !== null;
+    }
+    /**
+     * A valid session, logging in on first use. Concurrent callers share one
+     * in-flight login rather than racing several sign-ins at the same account.
+     */
+    async ensure() {
+        if (this.configError)
+            throw this.configError;
+        if (this.permanentError)
+            throw this.permanentError;
+        if (this.session)
+            return this.session;
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = this.login()
+            .then((session) => {
+            this.session = session;
+            return session;
+        })
+            .finally(() => {
+            this.inFlight = null;
+        });
+        return this.inFlight;
+    }
+    /** Drop the cached session so the next `ensure()` signs in again. */
+    invalidate() {
+        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
+     * answers 401 unconditionally cannot turn into a login loop 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());
+    }
+    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));
+        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/.',
+            });
+            // 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')) {
+                this.permanentError = error;
+            }
+            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.
+        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.',
+            });
+            throw this.permanentError;
+        }
+        return { bearerToken, refreshToken: body?.RefreshToken ?? null, cookieHeader };
+    }
+}
+/**
+ * Build a `Cookie:` request header from every `Set-Cookie` on a response.
+ * ServiceStack sets more than one (`ss-id`, `ss-pid`, `ss-opt`) alongside
+ * Azure's `ARRAffinity` pair, and the session needs all of them — so this
+ * keeps the whole jar rather than picking a named cookie out of it. `CookieJar`
+ * also drops the deletion markers a login response mixes in, which some
+ * upstreams reject when echoed back.
+ */
+export function collectCookieHeader(res) {
+    const jar = new CookieJar();
+    jar.absorb(res.headers);
+    return jar.header();
+}