@chrischall/pickuppatrol-mcp 0.0.0

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types for the PickUp Patrol ServiceStack API.
+ *
+ * Every field here was read off the shipped SPA's own request/response DTO
+ * classes or observed on a live response — see `docs/PICKUPPATROL-API.md` for
+ * the capture. Responses are typed loosely on purpose: the API is
+ * undocumented, so an unexpected extra field must not break a read.
+ */
+export {};

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Single source of truth for the server's self-reported version.
+ *
+ * The literal on the VERSION line below is rewritten by release-please (it is
+ * registered in `release-please-config.json` under `extra-files`). Everything
+ * that needs a version imports this constant rather than repeating the
+ * annotation, so there is exactly one line to keep in sync and
+ * `versionSyncTest` has exactly one line to check.
+ */
+export declare const VERSION = "0.0.0";

package/dist/version.js

@@ -0,0 +1,10 @@
+/**
+ * Single source of truth for the server's self-reported version.
+ *
+ * The literal on the VERSION line below is rewritten by release-please (it is
+ * registered in `release-please-config.json` under `extra-files`). Everything
+ * that needs a version imports this constant rather than repeating the
+ * annotation, so there is exactly one line to keep in sync and
+ * `versionSyncTest` has exactly one line to check.
+ */
+export const VERSION = '0.0.0'; // x-release-please-version

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@chrischall/pickuppatrol-mcp",
+  "version": "0.0.0",
+  "license": "MIT",
+  "mcpName": "io.github.chrischall/pickuppatrol-mcp",
+  "description": "PickUp Patrol MCP server for Claude — developed and maintained by AI (Claude Code)",
+  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischall/pickuppatrol-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "pickuppatrol",
+    "school",
+    "dismissal",
+    "carpool",
+    "parents"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "pickuppatrol-mcp": "dist/index.js"
+  },
+  "main": "dist/lib.js",
+  "types": "dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib.d.ts",
+      "import": "./dist/lib.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "skills",
+    ".mcp.json",
+    "server.json"
+  ],
+  "scripts": {
+    "build": "tsc && npm run bundle",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
+    "dev": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@chrischall/mcp-utils": "^0.14.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "esbuild": "^0.28.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.7"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.chrischall/pickuppatrol-mcp",
+  "description": "Read and change your children's school dismissal plans in PickUp Patrol",
+  "repository": {
+    "url": "https://github.com/chrischall/pickuppatrol-mcp",
+    "source": "github"
+  },
+  "version": "0.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@chrischall/pickuppatrol-mcp",
+      "version": "0.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/skills/pickuppatrol-api/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: pickuppatrol-api
+description: "Read and change your children's school dismissal plans on PickUp Patrol (app.pickuppatrol.net) from a shell with curl — students, weekly defaults, day-by-day changes, school cutoff times."
+---
+
+# PickUp Patrol from a shell
+
+`app.pickuppatrol.net` is a ServiceStack JSON API behind an Ionic/Vue SPA. It is
+reachable **server-side with plain `curl`** — no bot wall, no captcha, no
+browser bridge. Use this when you want PickUp Patrol data in a script or on a
+machine without the `pickuppatrol-mcp` server.
+
+Full captured shapes: `references/api.md`.
+
+## Sign in once per shell
+
+```bash
+export PUP_USER='you@example.com'
+read -rs PUP_PASS && export PUP_PASS      # never put the password in a command line
+export PUP=https://app.pickuppatrol.net/api/json/reply
+
+pup_login() {
+  local jar; jar=$(mktemp -t pupjar)
+  curl -sS -c "$jar" -X POST "$PUP/Authenticate" \
+    -H 'Content-Type: application/json' \
+    -d "$(jq -nc --arg u "$PUP_USER" --arg p "$PUP_PASS" \
+          '{provider:"credentials",UserName:$u,Password:$p,RememberMe:true}')" \
+    -o /tmp/pup_auth.json -w '%{http_code}' >/tmp/pup_code
+  [ "$(cat /tmp/pup_code)" = 200 ] || { jq -r '.ResponseStatus.Message' /tmp/pup_auth.json >&2; return 1; }
+  export PUP_JAR="$jar"
+  PUP_TOKEN=$(jq -r '.BearerToken // empty' /tmp/pup_auth.json); export PUP_TOKEN
+}
+
+# Every call goes through this: it sends the session cookies, and the bearer
+# token as well when the deployment issued one.
+pup() {
+  local method=$1 dto=$2; shift 2
+  local -a auth=(-b "$PUP_JAR")
+  [ -n "$PUP_TOKEN" ] && auth+=(-H "Authorization: Bearer $PUP_TOKEN")
+  curl -sS -X "$method" "$PUP/$dto" -H 'Content-Type: application/json' "${auth[@]}" "$@"
+}
+```
+
+**Never re-run a rejected login.** PickUp Patrol answers bad credentials with
+`ResponseStatus.ErrorCode` starting `LOGIN-ERROR`, counts the attempt against
+the account, and a lockout clears only through their support desk. One failure
+= stop and fix the credentials.
+
+## Reads
+
+```bash
+pup GET GetSession | jq '{name:.DisplayName, email:.Email, kids:[.Children[].StudentId]}'
+pup GET GetChildren | jq -r '.[] | "\(.StudentId)  \(.FirstName) — \(.SchoolName)"'
+
+# Weekly default plan for one student. DayId is 1-based, SUNDAY = 1.
+pup GET GetChildren | jq '.[] | select(.StudentId==1050046) | .DefaultPlans
+  | sort_by(.DayId) | map({day:.WeekDayName, option:.TransportationName, note:.Note})'
+
+# The dismissal options a school offers, with the rules each imposes.
+pup GET "GetTransportations?SchoolId=1703" | jq -r '.[] | select(.IsActive)
+  | "\(.TransportationId)\t\(.Name)\tnote=\(.IsNoteRequired)\tcar=\(.UseCarNumbers)\tearly=\(.IsEarlyDismissal)"'
+
+pup GET "GetPlanEdit?PlanDate=2026-08-17&StudentId=1050046" | jq '{TransportationName,Note,IsLocked}'
+pup GET "GetInvalidPlanDates?SchoolId=1703" | jq 'length'   # non-school days
+```
+
+## Writes
+
+Writes change how a child actually leaves school. Read
+`GetTransportations` first and obey the option's rules, or the request is
+rejected (or worse, silently ignored):
+
+- `IsNoteRequired` → `Note` must be non-empty
+- `UseCarNumbers` → send `CarNumber`; otherwise omit the key
+- `IsEarlyDismissal` → send `EarlyDismissalTime` as `HH:MM:SS`; otherwise omit it
+- `IsLimited` → only usable if the id is in the student's `LimitedIds`
+
+**Change specific dates** — `Plans` is an array, one entry per date:
+
+```bash
+pup PUT UpdatePlans -d '{"Plans":[{
+  "StudentId":1050046,"SchoolId":1703,"PlanDate":"2026-08-17",
+  "TransportationId":41246,"TransportationName":"PickUp","Note":"Chris Hall"}]}'
+```
+
+**Clear a date back to the weekly default** — a null transportation:
+
+```bash
+pup PUT UpdatePlans -d '{"Plans":[{
+  "StudentId":1050046,"SchoolId":1703,"PlanDate":"2026-08-17",
+  "TransportationId":null,"TransportationName":"Default plan","Note":null}]}'
+```
+
+**Change the weekly defaults** — there is no default-plans endpoint. Read the
+whole student, edit `DefaultPlans`, PUT the whole record back
+(`references/api.md` has the read-modify-write recipe).
+
+### Always re-read to verify
+
+A 2xx is not proof. The school silently ignores a change past its cutoff time.
+
+```bash
+pup GET "GetPlanEdit?PlanDate=2026-08-17&StudentId=1050046" | jq '.TransportationId'
+```
+
+Compare `TransportationId` — **not** `ModifiedDate`, which advances on its own
+and would make every write look successful.

package/skills/pickuppatrol-api/references/api.md

@@ -0,0 +1,168 @@
+# PickUp Patrol API reference
+
+Every shape here was read off the shipped SPA's own request DTO classes or
+observed on a live signed-in session (2026-08-16). No credential, cookie or
+token value is recorded.
+
+- Base: `https://app.pickuppatrol.net/api/json/reply/<DtoName>`
+- GET args on the query string; POST/PUT/PATCH args in a JSON body
+- Auth: session cookies from `Authenticate`, plus `Authorization: Bearer <jwt>`
+  when the deployment issues one
+- Errors: ServiceStack `{"ResponseStatus":{"ErrorCode","Message","Errors":[…]}}`;
+  an unauthenticated call to any authorised DTO is a bare `401`
+
+Assumes the `pup` / `pup_login` shell functions from `SKILL.md`.
+
+## Authentication
+
+```bash
+curl -sS -c jar -X POST "$PUP/Authenticate" -H 'Content-Type: application/json' \
+  -d '{"provider":"credentials","UserName":"…","Password":"…","RememberMe":true}'
+```
+
+Response: `{UserId, SessionId, UserName, DisplayName, BearerToken, RefreshToken,
+Roles, Permissions, ResponseStatus}`.
+
+Two-factor accounts (`User.OtpTypeId` set) need `POST /CreateOtp {OtpTypeId}`
+then `PUT /VerifyOtp {Otp, RememberMe}`. Token refresh is
+`POST /GetAccessToken {refreshToken}` or `GET /RequestNewtoken?OldToken=…`.
+
+## Read DTOs
+
+| DTO | Args |
+|---|---|
+| `GetSession` | — |
+| `GetSessionInfo` | — |
+| `GetChildren` | — |
+| `GetStudent` | `StudentId`, `MergeTimeWithNote?` |
+| `GetDefaultPlansReviewNeeded` | — |
+| `GetParentPlans` | `StartDate`, `EndDate` |
+| `GetPlanEdit` | `PlanDate`, `StudentId` |
+| `GetBoldedDates` | `StartDate`, `EndDate` (dates differing from the default) |
+| `GetInvalidPlanDates` | `SchoolId` (non-school days) |
+| `GetTransportations` | `SchoolId` |
+| `GetCarNumbers` | `SchoolId` |
+| `GetSchool` | `SchoolId` |
+| `GetSchoolNotifyTimes` | `SchoolId` |
+| `GetSchoolSettings` | `SchoolId` |
+| `GetMiddayPlan` | `StudentId`, `PlanDate`, `TypeId?` |
+| `GetParentHealthScreenAudits` | `ScreenDate` |
+| `GetTermsOfUse` | — |
+
+### Student
+
+```
+StudentId SchoolId SchoolName FirstName LastName IsActive SASId TeacherId
+AllowPlans CreateDate CreatedBy ModifiedDate ModifiedBy DefaultsModifiedDate
+DefaultPlanModifiedBy DefaultsReviewedDate DefaultsReviewedBy DefaultPlans
+SafetyFlag DefaultCarNumber LimitedIds
+```
+
+`DefaultPlans[]`:
+
+```json
+{"StudentId":1050046,"DayId":2,"TransportationId":41246,"Note":"Chris Hall",
+ "TransportationName":"PickUp","WeekDayName":"Monday","EarlyDismissalTime":null,
+ "CarNumber":null,"UseCarNumbers":false}
+```
+
+`DayId` is 1-based with **Sunday = 1** — verified from a live record where
+`DayId: 2` carried `WeekDayName: "Monday"`.
+
+### Transportation
+
+```
+TransportationId SchoolId Name NoteHint IsNoteRequired UseCarNumbers
+IsNotePrivate IsActive Sequence IsEarlyDismissal IsLimited CutoffTime
+CutoffTime{Sunday…Saturday} AllowParentCheck
+```
+
+### GetPlanEdit
+
+```
+PlanDate StudentId FirstName LastName SchoolId TransportationId Note IsLocked
+TransportationName SchoolName BusRouteUrl ValidationErrors EarlyDismissalTime
+CarNumber LimitedIds IsNotePrivate
+```
+
+## Write DTOs
+
+| DTO | Verb | Body |
+|---|---|---|
+| `UpdatePlans` | PUT | `{Plans:[…]}` |
+| `Student` | PUT | the whole student record |
+| `SetDefaultsReviewed` | PUT | `{StudentId, Reviewed}` |
+| `UpdateMiddayPlanCheck` | PUT | `{StudentId, PlanDate, TypeId, Action}` |
+| `MiddayPlan` | PUT | full midday-plan record |
+| `UpdateSendPlanConfirmationEmail` | PUT | `{Send}` |
+| `UpdateUserLanguage` | PATCH | `{Language}` |
+| `AcceptTerms` | PUT | — |
+| `ChangePassword` | PUT | `{CurrentPassword, NewPassword, ConfirmPassword}` |
+
+### UpdatePlans element
+
+```json
+{"StudentId":1050046,"SchoolId":1703,"PlanDate":"2026-08-17",
+ "TransportationId":41246,"TransportationName":"PickUp","Note":"Chris Hall",
+ "EarlyDismissalTime":"13:00:00","CarNumber":"12"}
+```
+
+Omit `EarlyDismissalTime` unless the option has `IsEarlyDismissal`, and
+`CarNumber` unless it has `UseCarNumbers` — the web app leaves both keys off
+otherwise.
+
+Build several dates at once:
+
+```bash
+jq -nc --argjson dates '["2026-08-17","2026-08-18"]' '
+  {Plans: ($dates | map({
+    StudentId:1050046, SchoolId:1703, PlanDate:.,
+    TransportationId:41246, TransportationName:"PickUp", Note:"Chris Hall"}))}' \
+| xargs -0 -I{} sh -c 'pup PUT UpdatePlans -d "$1"' _ {}
+```
+
+### Weekly defaults: read-modify-write the whole student
+
+There is no default-plans endpoint. Read the student, replace only
+`DefaultPlans`, PUT the whole record to the `Student` DTO.
+
+```bash
+STUDENT=1050046
+pup GET "GetStudent?StudentId=$STUDENT" > /tmp/pup_student.json
+
+# Set Monday (DayId 2) and Tuesday (3) to Bus (41245).
+jq '.DefaultPlans = (
+      (.DefaultPlans // []) as $p
+      | [2,3] as $days
+      | ($p | map(select(.DayId as $d | $days | index($d) | not)))
+        + ($days | map({DayId:., TransportationId:41245, TransportationName:"Bus", Note:null}))
+      | sort_by(.DayId))' /tmp/pup_student.json > /tmp/pup_student_new.json
+
+pup PUT Student -d @/tmp/pup_student_new.json
+
+# Verify: compare TransportationId per DayId, never DefaultsModifiedDate.
+pup GET "GetStudent?StudentId=$STUDENT" \
+  | jq '.DefaultPlans | sort_by(.DayId) | map({DayId, TransportationId})'
+```
+
+Clear every default with `jq '.DefaultPlans = []'`.
+
+Send every other field back verbatim — the whole record round-trips, so a
+dropped field is a field cleared.
+
+## Gates
+
+- `GetSchoolSettings(...).General.AllowDefaultPlans` — school allows default plans
+- `Student.AllowPlans` — this student's plans may be changed
+- `GetSchoolNotifyTimes` — a weekday with no `NotifyTime<Day>` is not a school day
+- `GetPlanEdit(...).IsLocked` — the cutoff for that date has passed
+
+## Verifying a write
+
+Re-read and compare the field that proves the change:
+
+- one-off plan → `GetPlanEdit(PlanDate, StudentId).TransportationId`
+- weekly defaults → `GetStudent(StudentId).DefaultPlans[].TransportationId`
+
+Exclude `ModifiedDate` and `DefaultsModifiedDate`: they advance on their own, so
+including them makes every write look successful.