psquare-mcp: Instructions file for Claude Code

ParentSquare MCP Server

Architecture

MCP server that scrapes ParentSquare's web UI. Runs as stdio transport. While there's no documented public API, ParentSquare has an internal JSON:API at /api/v2/ that some tools use (e.g. directory).

server.py          — MCP tool definitions, inline image/PDF fetching
client.py          — HTTP client with auto-relogin on session expiry
auth.py            — Cookie persistence (~/.parentsquare_cookies.json), credential loading (env vars → 1Password/LastPass), MFA flow
audit.py           — Write-gate (PS_ENABLE_WRITES) + JSONL audit log for admin write tools
config.py          — URL templates and constants (no personal data — auto-discovered at runtime)
models.py          — Dataclasses for all parsed entities
download.py        — File download with conflict handling
parsers/           — One module per page type (feeds, calendar, media, messages, etc.); parsers/admin.py holds roster/edit-form parsing + write-body builders
export_cookies.py  — CLI helper to bootstrap cookies from browser DevTools

Key Patterns

Authentication

• Cookies are lazy-loaded from ~/.parentsquare_cookies.json on startup (no network call)
• On session expiry (detected by redirect to /signin or missing gon.user_id on the root page), credentials are loaded via load_credentials(): first from PS_USERNAME/PS_PASSWORD env vars, then from the provider named by PS_CREDENTIAL_PROVIDER (default 1password). Options:
  • 1password — op item get Parentsquare (item named "Parentsquare" with fields labeled username and password)
  • lastpass — lpass show --json <item> where the item defaults to parentsquare.com and is overridable with PS_LASTPASS_ITEM (exact name or entry ID). Requires a prior lpass login <email>; lpass status --quiet is checked first (short timeout) so requests never hang on an interactive prompt. Credential values are never logged or included in error messages.
• Important: ParentSquare's root page (/) returns HTTP 200 even for unauthenticated users, so /signin redirect alone is not sufficient to detect expired sessions. discover_account() and is_session_valid() also check for gon.user_id in the page content.
• MFA code submission verifies the session is actually authenticated after the code is accepted
• MFA state persists to disk (.parentsquare_mfa_state.json) so it survives server restarts
• The server supports MCP elicitation for inline MFA code entry
• User-Agent must include "Chrome" — ParentSquare returns 403 browser_unsupported otherwise, and (worse) can serve unauthenticated content to a script-looking request that carries valid cookies, which ends in placeholder data rather than an error. make_session() in client.py owns this and is PSClient's default session, so a bare PSClient() is browser-like too; app_lifespan just calls it. Do not re-apply the header at a call site.
• The ps_s session cookie is httpOnly — it can't be read via document.cookie, which is why export_cookies requires the Network tab in DevTools
• ps_s rotates on every request. PSClient calls _save_cookies_if_changed() after each successful request to persist the latest value.
• GraphQL requests (used by list_groups) require a CSRF token extracted from a page's <meta name="csrf-token"> tag. MFA submit also requires a CSRF token from the MFA page.
• The CSRF token is cached on PSClient for the life of the session. Rails derives it from a per-session secret, so it stays valid across requests even though ps_s rotates — verified live. Without the cache every single write paid an extra GET /. _with_csrf() wraps each write and retries once with a force-refreshed token if the response looks like a rejected token or a dead session (_is_csrf_rejection: a bounce to /signin, a 401/419, or a 403/422 whose body names the token). That detection is deliberately narrow — retrying a plain 422 validation error could re-apply a write that had actually landed. Because caching removed the implicit GET / (and its session-expiry check) from every write, this retry path is now the thing that recovers an expired session mid-write. _relogin() and MFA completion both call invalidate_csrf_token().