artsonia-mcp 0.1.0

package/dist/src/auth.js

@@ -0,0 +1,73 @@
+import { readEnvVar, McpToolError } from '@chrischall/mcp-utils';
+import { CookieJar } from './cookies.js';
+const LOGIN_PATH = '/members/login.asp';
+const TARGET_URL = '/members/';
+// Owns the username/password login and the resulting cookie session. Deferred
+// config: constructing with no creds is fine; the error surfaces at ensureLogin.
+// Single-flight: concurrent ensureLogin() calls share one in-flight login.
+export class AuthManager {
+    transport;
+    jar = new CookieJar();
+    username;
+    password;
+    configError;
+    loggedIn = false;
+    inflight = null;
+    constructor(transport, opts) {
+        this.transport = transport;
+        const username = opts.username ?? readEnvVar('ARTSONIA_USERNAME') ?? null;
+        const password = opts.password ?? readEnvVar('ARTSONIA_PASSWORD') ?? null;
+        this.username = username;
+        this.password = password;
+        this.configError = username && password ? null : new Error('ARTSONIA_USERNAME and ARTSONIA_PASSWORD environment variables are required');
+    }
+    cookieHeader() {
+        return this.jar.header();
+    }
+    hasSession() {
+        return this.loggedIn && this.jar.size > 0;
+    }
+    async ensureLogin() {
+        if (this.hasSession())
+            return;
+        await this.forceRelogin();
+    }
+    async forceRelogin() {
+        if (this.configError)
+            throw this.configError;
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.doLogin().finally(() => { this.inflight = null; });
+        return this.inflight;
+    }
+    async doLogin() {
+        const body = new URLSearchParams({
+            Username: this.username,
+            Password: this.password,
+            TargetUrl: TARGET_URL,
+            Action: 'login',
+        }).toString();
+        const res = await this.transport.request({
+            method: 'POST',
+            path: LOGIN_PATH,
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Cookie: this.jar.header() },
+            body,
+            redirect: 'manual',
+        });
+        this.jar.setFromHeaders(res.setCookie);
+        const redirectedToDest = (res.status === 301 || res.status === 302) && !!res.location && !/login\.asp/i.test(res.location);
+        if (!redirectedToDest || this.jar.size === 0) {
+            throw new McpToolError('Artsonia login failed — check your ARTSONIA_USERNAME / ARTSONIA_PASSWORD credentials.', { hint: 'Verify the email/password are correct. Magic-link-only accounts are not supported by this server.' });
+        }
+        this.loggedIn = true;
+    }
+    /** Absorb refreshed cookies from a normal response (post-redirect Set-Cookie). */
+    absorb(setCookie) {
+        if (setCookie.length)
+            this.jar.setFromHeaders(setCookie);
+    }
+    /** Mark the session dead so the next ensureLogin re-authenticates. */
+    invalidate() {
+        this.loggedIn = false;
+    }
+}

package/dist/src/client.js

@@ -0,0 +1,74 @@
+import { loadDotenvSafely, readEnvVar, McpToolError } from '@chrischall/mcp-utils';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AuthManager } from './auth.js';
+import { makeTransport } from './transport.js';
+const LOGIN_RE = /\/members\/login\.asp/i;
+const LOGIN_BODY_RE = /You need to log in|Parent \(or Fan\) Login/i;
+function looksUnauthenticated(res) {
+    return LOGIN_RE.test(res.url) || LOGIN_BODY_RE.test(res.body) || (res.location ? LOGIN_RE.test(res.location) : false);
+}
+// Thin, tool-facing API over a transport + AuthManager. Reads go through
+// fetchHtml(); writes through write(). Both ensure a live session and retry
+// once across a re-login if the response looks unauthenticated.
+export class ArtsoniaClient {
+    transport;
+    auth;
+    constructor(opts) {
+        this.transport = opts.transport;
+        this.auth = opts.auth;
+    }
+    async fetchHtml(path) {
+        return (await this.requestWithSession('GET', path)).body;
+    }
+    async write(path, body) {
+        return this.requestWithSession('POST', path, body);
+    }
+    async requestWithSession(method, path, body) {
+        await this.auth.ensureLogin();
+        let res = await this.send(method, path, body);
+        if (looksUnauthenticated(res)) {
+            this.auth.invalidate();
+            try {
+                await this.auth.forceRelogin();
+            }
+            catch {
+                throw new McpToolError('Artsonia session could not be re-established: login failed after session expired.', {
+                    hint: 'Your ARTSONIA_USERNAME / ARTSONIA_PASSWORD may be wrong, or the session keeps expiring. Verify the credentials.',
+                });
+            }
+            res = await this.send(method, path, body);
+            if (looksUnauthenticated(res)) {
+                throw new McpToolError('Artsonia session could not be (re)established after re-login.', {
+                    hint: 'Your ARTSONIA_USERNAME / ARTSONIA_PASSWORD may be wrong, or the session keeps expiring. Verify the credentials.',
+                });
+            }
+        }
+        this.auth.absorb(res.setCookie);
+        if (res.status >= 400) {
+            throw new McpToolError(`Artsonia request failed: ${method} ${path} -> HTTP ${res.status}`, {
+                hint: 'Retry; if it persists the page may have moved or requires a different account.',
+            });
+        }
+        return res;
+    }
+    send(method, path, body) {
+        const headers = { Cookie: this.auth.cookieHeader() };
+        if (method === 'POST')
+            headers['Content-Type'] = 'application/x-www-form-urlencoded';
+        return this.transport.request({ method, path, headers, body, redirect: method === 'POST' ? 'manual' : 'follow' });
+    }
+}
+// Module singleton, constructed in this module (not index.ts) so the
+// deferred-config-error pattern holds: the server boots and answers tools/list
+// even with no creds; the error surfaces on the first tool call.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
+const transport = await makeTransport();
+export const client = new ArtsoniaClient({
+    transport,
+    auth: new AuthManager(transport, {
+        username: readEnvVar('ARTSONIA_USERNAME'),
+        password: readEnvVar('ARTSONIA_PASSWORD'),
+    }),
+});

package/dist/src/cookies.js

@@ -0,0 +1,33 @@
+// Minimal cookie jar for Artsonia's session cookies. We only need name=value
+// pairs for the Cookie request header — attributes (path/expires/HttpOnly) are
+// parsed only to detect deletion (empty value + past expiry).
+export class CookieJar {
+    jar = new Map();
+    setFromHeaders(setCookie) {
+        for (const line of setCookie) {
+            const trimmed = (line ?? '').trim();
+            if (!trimmed)
+                continue;
+            const [pair, ...attrs] = trimmed.split(';');
+            const eq = pair.indexOf('=');
+            if (eq < 0)
+                continue;
+            const name = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (!name)
+                continue;
+            const isDeletion = value === '' && attrs.some((a) => /expires=/i.test(a) && /1970/.test(a));
+            if (isDeletion) {
+                this.jar.delete(name);
+                continue;
+            }
+            this.jar.set(name, value);
+        }
+    }
+    header() {
+        return [...this.jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
+    }
+    get size() {
+        return this.jar.size;
+    }
+}

package/dist/src/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { runMcp } from '@chrischall/mcp-utils';
+import { VERSION } from './version.js';
+import { client } from './client.js';
+import { registerHealthcheckTools } from './tools/healthcheck.js';
+import { registerStudentTools } from './tools/students.js';
+import { registerPortfolioTools } from './tools/portfolio.js';
+import { registerFanTools } from './tools/fans.js';
+import { registerWriteTools } from './tools/writes.js';
+// The client is a module-level singleton (constructed in client.ts) so the
+// deferred-config-error pattern holds: the server boots and answers the host's
+// install-time tools/list probe even without ARTSONIA_USERNAME/PASSWORD — the
+// config error only surfaces on the first tool call.
+const tools = [
+    (s) => registerHealthcheckTools(s, client),
+    (s) => registerStudentTools(s, client),
+    (s) => registerPortfolioTools(s, client),
+    (s) => registerFanTools(s, client),
+    (s) => registerWriteTools(s, client),
+];
+await runMcp({
+    name: 'artsonia-mcp',
+    version: VERSION,
+    banner: `[artsonia-mcp] v${VERSION} — parent/fan access to Artsonia via username/password login. This project was developed and is maintained by AI (Claude). Use at your own discretion.`,
+    tools,
+});

package/dist/src/parse.js

@@ -0,0 +1,144 @@
+import { parse, NodeType } from 'node-html-parser';
+const firstIntIn = (s) => {
+    const m = (s ?? '').match(/(\d[\d,]*)/);
+    return m ? Number(m[1].replace(/,/g, '')) : null;
+};
+const text = (el) => (el ? el.text.replace(/\s+/g, ' ').trim() : '');
+const attrId = (href, key) => {
+    const m = (href ?? '').match(new RegExp(`[?&](?:amp;)?${key}=(\\d+)`));
+    return m ? m[1] : null;
+};
+/** Returns the direct text-node content of an element (excludes child element text). */
+const ownText = (el) => el.childNodes
+    .filter((n) => n.nodeType === NodeType.TEXT_NODE)
+    .map((n) => n.rawText)
+    .join('')
+    .replace(/\s+/g, ' ')
+    .trim();
+export function parseStudents(html) {
+    const root = parse(html);
+    return root.querySelectorAll('.artist-card').map((card) => {
+        const link = card.querySelector('a[href*="portfolio.asp"]');
+        const href = link?.getAttribute('href');
+        const artist_id = attrId(href, 'id');
+        if (!artist_id)
+            return null;
+        // Name: first a.lightlink text
+        const name = text(card.querySelector('a.lightlink'));
+        // School/grade: child div whose text matches "Currently at"
+        const schoolDiv = card.querySelectorAll('div').find((d) => d.text.includes('Currently at')) ?? null;
+        const schoolText = text(schoolDiv);
+        const schoolMatch = schoolText.match(/Currently at (.+?) \(Grade/);
+        const gradeMatch = schoolText.match(/\(Grade\s+(\w+)\)/i);
+        const school = schoolMatch?.[1] ?? '';
+        const grade = gradeMatch?.[1] ?? null;
+        // Stats: each .stat text is "<n> <label>"
+        const statMap = {};
+        card.querySelectorAll('.stat').forEach((s) => {
+            const t = s.text.trim();
+            const m = t.match(/^(\d[\d,]*)\s+(\w+)/);
+            if (m)
+                statMap[m[2].toLowerCase()] = Number(m[1].replace(/,/g, ''));
+        });
+        return {
+            artist_id,
+            name,
+            school,
+            grade,
+            artwork_count: statMap['artworks'] ?? null,
+            fan_count: statMap['fans'] ?? null,
+            comment_count: statMap['comments'] ?? null,
+            feedback_count: statMap['feedback'] ?? null,
+            award_count: statMap['awards'] ?? null,
+            portfolio_path: href ?? `/artists/portfolio.asp?id=${artist_id}`,
+        };
+    }).filter((s) => s !== null);
+}
+export function parseNotifications(html) {
+    const root = parse(html);
+    // Count: from .textSubhead whose text contains "Notifications"
+    const subhead = root.querySelectorAll('.textSubhead').find((el) => el.text.includes('Notifications')) ?? null;
+    const count = firstIntIn(text(subhead).match(/\((\d+)\)/)?.[1]) ?? 0;
+    // Items: each div.notice
+    const items = root.querySelectorAll('div.notice').map((notice) => {
+        const anchor = notice.querySelector('a.lightlink');
+        const title = text(anchor);
+        const href = anchor?.getAttribute('href') ?? '';
+        // Body: full notice text minus the title text, trimmed
+        const fullText = notice.text.replace(/\s+/g, ' ').trim();
+        const body = fullText.replace(title, '').replace(/\s+/g, ' ').trim();
+        return { title, body, href };
+    });
+    return { count, items };
+}
+export function parsePortfolio(html) {
+    const root = parse(html);
+    return root.querySelectorAll('.grid-item').map((item) => {
+        const link = item.querySelector('a[href*="art.asp"]');
+        const artwork_id = attrId(link?.getAttribute('href'), 'id');
+        if (!artwork_id)
+            return null;
+        // Thumbnail is derived from artwork_id — tile uses CSS background, no usable img src
+        const thumbnail = `https://images.artsonia.com/art/small/${artwork_id}.jpg`;
+        // Private: tile contains a .private-art element
+        const is_private = item.querySelector('.private-art') !== null;
+        return { artwork_id, is_private, thumbnail };
+    }).filter((a) => a !== null);
+}
+export function parseArtwork(html) {
+    const root = parse(html);
+    // title + screen-name from <title>: `... "<Title>" by <ScreenName>`
+    const rawTitle = text(root.querySelector('title'));
+    const title = rawTitle.match(/"([^"]+)"/)?.[1] ?? '';
+    const artist_screen_name = rawTitle.match(/by\s+(\S+)\s*$/)?.[1] ?? '';
+    // views from .textNormal whose text matches "<n> artwork views"
+    let views = null;
+    for (const el of root.querySelectorAll('.textNormal')) {
+        const m = el.text.match(/(\d+)\s+artwork views?/);
+        if (m) {
+            views = Number(m[1]);
+            break;
+        }
+    }
+    // project from body text: `from school project "<Project>"`
+    const bodyText = root.querySelector('body')?.text ?? '';
+    const project = bodyText.match(/from school project "([^"]+)"/)?.[1] ?? '';
+    // comment entry link
+    const link = root.querySelector('a[href*="comments/enter.asp"]');
+    const href = link?.getAttribute('href');
+    const aId = attrId(href, 'artist');
+    const wId = attrId(href, 'art');
+    const comment_entry = aId && wId ? { artist_id: aId, artwork_id: wId } : null;
+    // NOTE: comment-item markup is UNVERIFIED — 0-comment accounts show no comment elements.
+    // Confirm against an artwork that has comments before trusting this.
+    // See docs/ARTSONIA-API.md.
+    // Using a reasonable selector that degrades to [] on 0-comment pages without throwing.
+    const comments = root.querySelectorAll('.comment').map((c) => ({
+        author: text(c.querySelector('.comment-author')),
+        text: text(c.querySelector('.comment-text')),
+    }));
+    return { title, artist_screen_name, views, project, comment_entry, comments };
+}
+export function parseFans(html) {
+    const root = parse(html);
+    return root.querySelectorAll('.fan-card').map((card) => {
+        // Name: first a.hiddenlink text
+        const nameEl = card.querySelector('a.hiddenlink');
+        const name = text(nameEl);
+        if (!name)
+            return null;
+        // Relationship: find a descendant <div> whose own direct text-node content
+        // is a non-empty string that is not the fan's name and looks like a relationship word.
+        // The real structure: <div>Father<b>Registered</b></div> — own-text is "Father".
+        let relationship = '';
+        for (const div of card.querySelectorAll('div')) {
+            const own = ownText(div);
+            // Must be non-empty, not blank, not equal to the name
+            if (own && own !== name) {
+                relationship = own;
+                break;
+            }
+        }
+        return { name, relationship };
+    }).filter((f) => f !== null);
+}

package/dist/src/tools/fans.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { parseFans } from '../parse.js';
+export function registerFanTools(server, client) {
+    server.registerTool('artsonia_get_fans', {
+        title: "Get a student's fan club",
+        description: "List the fans (name + relationship) in a student's fan club. Pass the artist_id from artsonia_list_students.",
+        annotations: toolAnnotations({ title: "Get a student's fan club", openWorld: true }),
+        inputSchema: { artist_id: z.string().regex(/^\d+$/, 'must be a numeric id').describe('Student artist_id.') },
+    }, async ({ artist_id }) => textResult({ artist_id, fans: parseFans(await client.fetchHtml(`/members/fanclub/?artist=${artist_id}`)) }));
+}

package/dist/src/tools/healthcheck.js

@@ -0,0 +1,35 @@
+import { textResult, toolAnnotations, readEnvVar, messageOf } from '@chrischall/mcp-utils';
+import { parseStudents } from '../parse.js';
+export function registerHealthcheckTools(server, client) {
+    server.registerTool('artsonia_healthcheck', {
+        title: 'Verify Artsonia auth + connectivity',
+        description: 'Confirm credentials are configured, log in, fetch the dashboard, and report {authenticated, transport, student_count} with a plain-English hint distinguishing "no creds" vs "bad creds" vs "site error". Read-only.',
+        annotations: toolAnnotations({ title: 'Verify Artsonia auth + connectivity', readOnly: true, idempotent: true, openWorld: true }),
+        inputSchema: {},
+    }, async () => {
+        const transport = readEnvVar('ARTSONIA_TRANSPORT') ?? 'fetch';
+        try {
+            const students = parseStudents(await client.fetchHtml('/members/'));
+            return textResult({
+                ok: true,
+                authenticated: true,
+                transport,
+                student_count: students.length,
+                hint: students.length > 0 ? 'Logged in; dashboard parsed successfully.' : 'Logged in, but no students parsed — the dashboard markup may have changed.',
+            });
+        }
+        catch (e) {
+            const msg = messageOf(e);
+            const noCreds = /environment variables are required/.test(msg);
+            return textResult({
+                ok: false,
+                authenticated: false,
+                transport,
+                error: msg,
+                hint: noCreds
+                    ? 'Set ARTSONIA_USERNAME and ARTSONIA_PASSWORD (in .env or the MCP host env), then retry.'
+                    : 'Login or fetch failed — check that your credentials are correct and the account is a parent/fan account (magic-link-only accounts are unsupported).',
+            });
+        }
+    });
+}

package/dist/src/tools/portfolio.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { parsePortfolio, parseArtwork } from '../parse.js';
+const NumericId = z.string().regex(/^\d+$/, 'must be a numeric id');
+export function registerPortfolioTools(server, client) {
+    server.registerTool('artsonia_get_portfolio', {
+        title: "Get a student's portfolio",
+        description: "List a student's artworks (artwork_id, is_private flag, thumbnail). Pass the artist_id from artsonia_list_students.",
+        annotations: toolAnnotations({ title: "Get a student's portfolio", openWorld: true }),
+        inputSchema: { artist_id: NumericId.describe('Student artist_id (from artsonia_list_students).') },
+    }, async ({ artist_id }) => textResult({ artist_id, artworks: parsePortfolio(await client.fetchHtml(`/artists/portfolio.asp?id=${artist_id}`)) }));
+    server.registerTool('artsonia_get_artwork', {
+        title: 'Get artwork detail',
+        description: 'Get one artwork: title, artist screen-name, view count, project (assignment name), and the comments on it. Pass an artwork_id from a portfolio.',
+        annotations: toolAnnotations({ title: 'Get artwork detail', openWorld: true }),
+        inputSchema: { artwork_id: NumericId.describe('Artwork id (from artsonia_get_portfolio).') },
+    }, async ({ artwork_id }) => textResult(parseArtwork(await client.fetchHtml(`/museum/art.asp?id=${artwork_id}`))));
+    server.registerTool('artsonia_list_comments', {
+        title: 'List comments on an artwork',
+        description: 'List the comments on a given artwork (author + text). Pass an artwork_id from a portfolio.',
+        annotations: toolAnnotations({ title: 'List comments on an artwork', openWorld: true }),
+        inputSchema: { artwork_id: NumericId.describe('Artwork id (from artsonia_get_portfolio).') },
+    }, async ({ artwork_id }) => {
+        const detail = parseArtwork(await client.fetchHtml(`/museum/art.asp?id=${artwork_id}`));
+        return textResult({ artwork_id, comments: detail.comments });
+    });
+}

package/dist/src/tools/students.js

@@ -0,0 +1,14 @@
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { parseStudents, parseNotifications } from '../parse.js';
+export function registerStudentTools(server, client) {
+    server.registerTool('artsonia_list_students', {
+        title: 'List followed students',
+        description: 'List the student(s) on your Artsonia parent/fan account with their artist_id, name, school, grade, and artwork/fan counts. The artist_id is the selector used by the portfolio, comments, and fan tools.',
+        annotations: toolAnnotations({ title: 'List followed students', openWorld: true }),
+    }, async () => textResult({ students: parseStudents(await client.fetchHtml('/members/')) }));
+    server.registerTool('artsonia_get_activity', {
+        title: 'Get account notifications',
+        description: 'Return the notification/activity feed on the parent dashboard (e.g. new teacher feedback, fan-club prompts), with a count and the list of notices.',
+        annotations: toolAnnotations({ title: 'Get account notifications', openWorld: true }),
+    }, async () => textResult(parseNotifications(await client.fetchHtml('/members/'))));
+}

package/dist/src/tools/writes.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { parse } from 'node-html-parser';
+import { textResult, toolAnnotations, schemaConfirm } from '@chrischall/mcp-utils';
+const NumericId = z.string().regex(/^\d+$/, 'must be a numeric id');
+function previewResult(action, wouldSend, caveat) {
+    return textResult({
+        preview: true,
+        action,
+        note: `DRY RUN — nothing was sent. Re-run with confirm: true to perform this write.${caveat ? ` ${caveat}` : ''}`,
+        wouldSend,
+    });
+}
+const OPTIN_FIELDS = { news: 'OptInNews', artist_activity: 'OptInArtistActivity', promos: 'OptInPromos' };
+const PASSWORD_FIELDS = new Set(['OldPassword', 'NewPassword', 'NewPassword2']);
+export function parseProfileForm(html) {
+    const form = parse(html).querySelector('#TheForm');
+    if (!form)
+        throw new Error('Could not find the Artsonia profile form (#TheForm).');
+    const fields = {};
+    const checkboxes = {};
+    for (const el of form.querySelectorAll('input, select')) {
+        const name = el.getAttribute('name');
+        if (!name)
+            continue;
+        const type = (el.getAttribute('type') ?? el.tagName.toLowerCase());
+        if (type === 'checkbox') {
+            checkboxes[name] = el.hasAttribute('checked');
+        }
+        else if (el.tagName.toLowerCase() === 'select') {
+            const sel = el.querySelector('option[selected]') ?? el.querySelector('option');
+            fields[name] = sel?.getAttribute('value') ?? '';
+        }
+        else {
+            fields[name] = el.getAttribute('value') ?? '';
+        }
+    }
+    return { fields, checkboxes };
+}
+export function registerWriteTools(server, client) {
+    server.registerTool('artsonia_post_comment', {
+        title: 'Post a comment on an artwork',
+        description: "Post a comment on a student's artwork. Without confirm:true this is a DRY RUN that returns a preview and makes no network call.",
+        annotations: toolAnnotations({ title: 'Post a comment on an artwork', readOnly: false, openWorld: true }),
+        inputSchema: {
+            artist_id: NumericId.describe('Student artist_id (from artsonia_list_students).'),
+            artwork_id: NumericId.describe('Artwork id (from artsonia_get_portfolio).'),
+            comment: z.string().min(1).describe('The comment text to post.'),
+            confirm: schemaConfirm,
+        },
+    }, async ({ artist_id, artwork_id, comment, confirm }) => {
+        const path = `/museum/enter.asp?artist=${artist_id}&art=${artwork_id}`;
+        if (confirm !== true)
+            return previewResult('post_comment', { path, Comment: comment });
+        const body = new URLSearchParams({ Comment: comment }).toString();
+        const res = await client.write(path, body);
+        return textResult({ posted: true, artist_id, artwork_id, status: res.status });
+    });
+    server.registerTool('artsonia_invite_fan', {
+        title: "Invite a fan to a student's fan club",
+        description: "Invite someone (by name + email) to follow a student's Artsonia portfolio. Sends them an invite email. Without confirm:true this is a DRY RUN. Use only real addresses you're authorized to invite (test with @example.com).",
+        annotations: toolAnnotations({ title: 'Invite a fan', readOnly: false, openWorld: true }),
+        inputSchema: {
+            artist_id: NumericId.describe('Student artist_id (from artsonia_list_students).'),
+            first_name: z.string().min(1).describe("Fan's first name."),
+            last_name: z.string().min(1).describe("Fan's last name."),
+            email: z.string().email().describe("Fan's email address (they receive an invite)."),
+            relationship_id: NumericId.describe('Relationship code (RelationshipID select value from the Add Fans form).'),
+            is_parent: z.boolean().default(false).describe('Whether this fan is also a parent/guardian.'),
+            confirm: schemaConfirm,
+        },
+    }, async ({ artist_id, first_name, last_name, email, relationship_id, is_parent, confirm }) => {
+        const path = `/members/fanclub/add.asp?artist=${artist_id}`;
+        const params = new URLSearchParams({
+            MemberType: 'fan',
+            RelationshipID: relationship_id,
+            FirstName: first_name,
+            LastName: last_name,
+            EmailAddress: email,
+            ArtistID: artist_id,
+        });
+        if (is_parent)
+            params.set('IsParent', 'on');
+        if (confirm !== true) {
+            return previewResult('invite_fan', { path, ...Object.fromEntries(params) }, 'Verify RelationshipID against the live Add Fans form; MemberType is assumed "fan".');
+        }
+        const res = await client.write(path, params.toString());
+        return textResult({ invited: true, artist_id, email, status: res.status });
+    });
+    server.registerTool('artsonia_set_notifications', {
+        title: 'Set notification preferences',
+        description: "Turn the account's email opt-ins on/off (news, artist activity, promos). Reads your profile, changes only the opt-in(s) you specify, and re-saves — leaving your name/email/password untouched. Without confirm:true this is a DRY RUN showing the resulting state.",
+        annotations: toolAnnotations({ title: 'Set notification preferences', readOnly: false, openWorld: true }),
+        inputSchema: {
+            news: z.boolean().optional().describe('OptInNews — general Artsonia news emails.'),
+            artist_activity: z.boolean().optional().describe('OptInArtistActivity — emails about your student(s) activity.'),
+            promos: z.boolean().optional().describe('OptInPromos — promotional/keepsake emails.'),
+            confirm: schemaConfirm,
+        },
+    }, async ({ news, artist_activity, promos, confirm }) => {
+        const desired = { news, artist_activity, promos };
+        if (news === undefined && artist_activity === undefined && promos === undefined) {
+            return textResult({ error: 'Specify at least one of news / artist_activity / promos.' });
+        }
+        const { fields, checkboxes } = parseProfileForm(await client.fetchHtml('/members/profile/'));
+        const nextChecks = { ...checkboxes };
+        for (const [key, fieldName] of Object.entries(OPTIN_FIELDS)) {
+            const want = desired[key];
+            if (want !== undefined)
+                nextChecks[fieldName] = want;
+        }
+        const params = new URLSearchParams();
+        for (const [name, value] of Object.entries(fields)) {
+            if (PASSWORD_FIELDS.has(name)) {
+                params.set(name, '');
+                continue;
+            }
+            if (name === 'DidChangePassword') {
+                params.set(name, '0');
+                continue;
+            }
+            params.set(name, value);
+        }
+        for (const [name, on] of Object.entries(nextChecks)) {
+            if (on)
+                params.set(name, 'on');
+        }
+        const resultingOptIns = {
+            OptInNews: nextChecks['OptInNews'] ?? false,
+            OptInArtistActivity: nextChecks['OptInArtistActivity'] ?? false,
+            OptInPromos: nextChecks['OptInPromos'] ?? false,
+        };
+        if (confirm !== true) {
+            return previewResult('set_notifications', { ...resultingOptIns }, 'Re-sends your full profile (name/email preserved, password blanked) to flip only the opt-in(s).');
+        }
+        const res = await client.write('/members/profile/default.asp', params.toString());
+        return textResult({ updated: true, optIns: resultingOptIns, status: res.status });
+    });
+}

package/dist/src/transport-fetch.js

@@ -0,0 +1,30 @@
+import { ARTSONIA_ORIGIN } from './transport.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+// Default transport: node fetch against the user's cookie session. The login
+// POST passes redirect:'manual' so its 302's Set-Cookie is readable; reads use
+// redirect:'follow' and detect login-redirects by the final URL/body.
+export class FetchArtsoniaTransport {
+    async request(req) {
+        const url = req.path.startsWith('http') ? req.path : `${ARTSONIA_ORIGIN}${req.path}`;
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), DEFAULT_TIMEOUT_MS);
+        try {
+            const res = await fetch(url, {
+                method: req.method,
+                headers: req.headers,
+                body: req.body,
+                redirect: req.redirect ?? 'follow',
+                signal: ac.signal,
+            });
+            const body = await res.text();
+            const setCookie = typeof res.headers.getSetCookie === 'function'
+                ? res.headers.getSetCookie()
+                : (res.headers.get('set-cookie') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+            const location = res.headers.get('location') ?? undefined;
+            return { status: res.status, body, url: res.url || url, setCookie, location };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/src/transport-fetchproxy.js

@@ -0,0 +1,36 @@
+import { FetchproxyServer } from '@fetchproxy/server';
+import { ARTSONIA_ORIGIN } from './transport.js';
+import { readEnvVar } from '@chrischall/mcp-utils';
+import { VERSION } from './version.js';
+const DEFAULT_PORT = 37_149; // shared fleet port — do NOT change
+// Optional fallback transport: route requests through the user's signed-in
+// browser tab via @fetchproxy/server. Engaged only when ARTSONIA_TRANSPORT=
+// fetchproxy. Cookies are carried by the browser, so the AuthManager's jar is
+// unused in this mode; login is whatever the browser already holds.
+export class FetchproxyArtsoniaTransport {
+    inner;
+    started = false;
+    constructor() {
+        const portEnv = readEnvVar('ARTSONIA_WS_PORT');
+        const opts = {
+            port: portEnv ? Number(portEnv) : DEFAULT_PORT,
+            serverName: 'artsonia-mcp',
+            version: VERSION,
+            domains: ['artsonia.com'],
+            capabilities: ['fetch'],
+        };
+        this.inner = new FetchproxyServer(opts);
+    }
+    async ensureStarted() {
+        if (this.started)
+            return;
+        await this.inner.listen();
+        this.started = true;
+    }
+    async request(req) {
+        await this.ensureStarted();
+        const url = req.path.startsWith('http') ? req.path : `${ARTSONIA_ORIGIN}${req.path}`;
+        const r = await this.inner.request(req.method, url, { headers: req.headers, body: req.body });
+        return { status: r.status, body: r.body, url: r.url, setCookie: [] };
+    }
+}