artsonia-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

TL;DR

MCP server for Artsonia (artsonia.com — kids' artwork portfolios). Cookie-session archetype: there is no public API, so the server logs into the parent/fan website with a username + password, harvests the resulting HttpOnly session cookie, and scrapes/POSTs the member pages. 15 tools across students, portfolio/artwork, comments, fans, teacher feedback, awards, account profile, image downloads, and a small set of writes (two of them confirmation-gated).

Two transport modes, selected by ARTSONIA_TRANSPORT:

1. fetch (default, direct) — Node fetch against the site. The server owns the session: AuthManager runs the username/password login (POST /members/login.asp), keeps the cookie jar, and re-logs-in once on expiry.
2. fetchproxy (optional, browser-session) — requests ride the user's already-signed-in browser tab via @fetchproxy/server. The browser carries the session, so the server-side login is skipped entirely (usesBrowserSession = true). No ARTSONIA_USERNAME/PASSWORD needed in this mode.

Auth resolution

src/auth.ts owns the username/password login and the cookie session. It delegates the single-flight login + invalidate/re-login + one-replay-on-expiry to the shared CookieSessionManager from @chrischall/mcp-utils/session, typed over ArtsoniaResponse so the custom transport's response flows through withSession() untouched.

• Env vars: ARTSONIA_USERNAME + ARTSONIA_PASSWORD (required in direct mode), ARTSONIA_TRANSPORT (fetch default | fetchproxy), ARTSONIA_WS_PORT (fetchproxy WebSocket port override; default 37149 — a shared fleet port, do NOT change), ARTSONIA_INLINE_DOWNLOADS (1/true/yes/on ⇒ inline image downloads; unset/false ⇒ disk, except on a hosted deployment, which is always inline — see "Download I/O" below), ARTSONIA_OUTPUT_DIR (folders the disk IO may write dest into; default ~/Downloads + ~/Pictures — downloadRoots() in make-download-io.ts; its $MCP_DATA_DIR/downloads branch is no longer reached, since a hosted deployment never gets the disk IO), ARTSONIA_SESSION_CACHE (false disables the on-disk session cache; default on, direct mode only) and ARTSONIA_SESSION_FILE (override the cache path; defaults to $MCP_DATA_DIR/.artsonia-mcp/session-<user>.json, one file PER USER so createDirectClient callers do not clobber each other).
• Deferred config error: the client is a module singleton constructed in src/client.ts (NOT index.ts), so the server boots and answers the host's install-time tools/list probe even with no creds. The missing-creds error is cached as a permanent error (CONFIG_ERROR_MARKER) and only surfaces on the first tool call — every later ensure() rethrows it rather than retrying a login that can never succeed.
• Login success marker: doLogin() POSTs Username/Password/TargetUrl=/members//Action=login with redirect: 'manual' and treats a 301/302 whose Location is NOT login.asp (plus a non-empty cookie jar) as success. Magic-link-only accounts are unsupported.
• Expiry heuristic (looksUnauthenticated): Artsonia expires by redirecting/rendering back to the login page (NOT a 401). Detected from the final URL, a manual 3xx Location pointing at login.asp, or the login form structure rendered in place (<form action="…login.asp"> plus a name="Password" field), via the shared structural looksLikeLoginPage from @chrischall/mcp-utils/session (no status code counts by itself). Never from body prose — artwork pages carry user-generated text (fan comments, titles), and a comment saying "You need to log in" must not force a re-login or a false bad-credentials error.