signupgenius-mcp 1.1.6 → 1.2.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for SignUpGenius — read sign-ups, slot reports, and groups; add group members.",
-    "version": "1.1.6"
+    "version": "1.2.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "SignUpGenius",
       "source": "./",
       "description": "SignUpGenius MCP server for Claude — sign-ups, slot reports, and groups via natural language. Free or Pro accounts.",
-      "version": "1.1.6",
+      "version": "1.2.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "signupgenius-mcp",
   "displayName": "SignUpGenius",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "SignUpGenius MCP server for Claude — read sign-ups, slot reports, and groups; add group members. Three auth paths: Pro API key, email/password, or sign in via the fetchproxy browser extension.",
   "author": {
     "name": "Chris Hall",
@@ -15,5 +15,6 @@
     "signups",
     "volunteers",
     "mcp"
-  ]
+  ],
+  "skills": "./skills/"
 }

package/dist/bundle.js

@@ -34948,6 +34948,7 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_request_header",
   "capture_redirect",
   "read_indexed_db",
+  "read_dom",
   "download"
 ]);
 
@@ -35249,6 +35250,44 @@ function assertIndexedDbScopesArray(value, label) {
     }
   }
 }
+var DOM_SELECTOR_RE = /^[^-]{1,512}$/;
+var DOM_ATTRIBUTE_RE = /^[A-Za-z_:][A-Za-z0-9_:.\-]{0,127}$/;
+function assertDomSelectorsArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    assertObject(entry, `${label}[${i}]`);
+    if (entry.name === void 0) {
+      throw new ProtocolError(`${label}[${i}].name: missing`);
+    }
+    if (entry.selector === void 0) {
+      throw new ProtocolError(`${label}[${i}].selector: missing`);
+    }
+    if (typeof entry.name !== "string" || !SCOPE_KEY_RE.test(entry.name)) {
+      throw new ProtocolError(`${label}[${i}].name: invalid ${JSON.stringify(entry.name)}`);
+    }
+    if (typeof entry.selector !== "string" || !DOM_SELECTOR_RE.test(entry.selector)) {
+      throw new ProtocolError(`${label}[${i}].selector: invalid ${JSON.stringify(entry.selector)}`);
+    }
+    if (entry.attribute !== void 0) {
+      if (typeof entry.attribute !== "string" || !DOM_ATTRIBUTE_RE.test(entry.attribute)) {
+        throw new ProtocolError(`${label}[${i}].attribute: invalid ${JSON.stringify(entry.attribute)}`);
+      }
+    }
+    if (seen.has(entry.name)) {
+      throw new ProtocolError(`${label}: duplicate name ${JSON.stringify(entry.name)}`);
+    }
+    seen.add(entry.name);
+    for (const k of Object.keys(entry)) {
+      if (k !== "name" && k !== "selector" && k !== "attribute") {
+        throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
+      }
+    }
+  }
+}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35324,6 +35363,9 @@ function validateHello(raw) {
     if (raw.sessionStoragePointers !== void 0) {
       assertStoragePointersArray(raw.sessionStoragePointers, "hello.sessionStoragePointers", raw.sessionStorageKeys);
     }
+    if (raw.domSelectors !== void 0) {
+      assertDomSelectorsArray(raw.domSelectors, "hello.domSelectors");
+    }
     assertBase64(raw.identityX25519Pub, "hello.identityX25519Pub");
     assertBase64(raw.identityEd25519Pub, "hello.identityEd25519Pub");
     assertBase64(raw.sessionNonce, "hello.sessionNonce");
@@ -35558,6 +35600,21 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
+  if (raw.op === "read_dom") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.origin === void 0)
+      throw new ProtocolError("inner.init.origin: missing");
+    if (raw.init.names === void 0)
+      throw new ProtocolError("inner.init.names: missing");
+    assertHttpsOriginOnly(raw.init.origin, "inner.init.origin");
+    assertNonEmptyKeyArray(raw.init.names, "inner.init.names");
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "origin" && k !== "names") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on read_dom`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "download") {
     assertObject(raw.init, "inner.init");
     if (raw.init.url === void 0) {
@@ -35583,7 +35640,7 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
-  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "download"; got ${JSON.stringify(raw.op)}`);
+  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "read_dom", "download"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35668,6 +35725,13 @@ function validateInnerResponse(raw) {
       assertObject(raw.values, "inner.values");
       return raw;
     }
+    if (op === "read_dom") {
+      if (raw.values === void 0) {
+        throw new ProtocolError("inner.values: missing on read_dom response");
+      }
+      assertStringMap(raw.values, "inner.values");
+      return raw;
+    }
     if (op === "download") {
       assertObject(raw.value, "inner.value");
       assertString(raw.value.path, "inner.value.path");
@@ -36007,6 +36071,13 @@ async function buildServerHello(opts) {
       jsonPointer: d.jsonPointer
     }));
   }
+  if (opts.domSelectors && opts.domSelectors.length > 0) {
+    hello.domSelectors = opts.domSelectors.map((d) => ({
+      name: d.name,
+      selector: d.selector,
+      ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+    }));
+  }
   return hello;
 }
 
@@ -36096,7 +36167,8 @@ async function startHost(opts) {
     captureHeaders: opts.ownCaptureHeaders,
     indexedDbScopes: opts.ownIndexedDbScopes,
     localStoragePointers: opts.ownLocalStoragePointers,
-    sessionStoragePointers: opts.ownSessionStoragePointers
+    sessionStoragePointers: opts.ownSessionStoragePointers,
+    domSelectors: opts.ownDomSelectors
   });
   const ownSessionNonce = fromB64(ownHello.sessionNonce);
   let extensionWs = null;
@@ -36331,6 +36403,7 @@ async function startPeer(opts) {
     sessionStorageKeys: opts.sessionStorageKeys,
     captureHeaders: opts.captureHeaders,
     indexedDbScopes: opts.indexedDbScopes,
+    domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
     sessionStoragePointers: opts.sessionStoragePointers
   });
@@ -36738,6 +36811,11 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      domSelectors: (opts.domSelectors ?? []).map((d) => ({
+        name: d.name,
+        selector: d.selector,
+        ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+      })),
       // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
       // adapter was about to set these to the same numbers anyway; the
       // back-door is `0` (explicit opt-out) if a caller genuinely wants
@@ -36858,6 +36936,7 @@ var FetchproxyServer = class {
         ownIndexedDbScopes: this.opts.indexedDbScopes,
         ownLocalStoragePointers: this.opts.localStoragePointers,
         ownSessionStoragePointers: this.opts.sessionStoragePointers,
+        ownDomSelectors: this.opts.domSelectors,
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
@@ -36885,7 +36964,8 @@ var FetchproxyServer = class {
         captureHeaders: this.opts.captureHeaders,
         indexedDbScopes: this.opts.indexedDbScopes,
         localStoragePointers: this.opts.localStoragePointers,
-        sessionStoragePointers: this.opts.sessionStoragePointers
+        sessionStoragePointers: this.opts.sessionStoragePointers,
+        domSelectors: this.opts.domSelectors
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
       this.peerHandle.onRenegotiate(() => {
@@ -37860,6 +37940,46 @@ var FetchproxyServer = class {
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
   }
+  /**
+   * 1.4.0+: read declared DOM values from the user's signed-in tab.
+   * Requires `'read_dom'` in capabilities AND every requested `name` to
+   * match a declared `domSelectors` entry. The extension reads each
+   * declared selector from the matched tab's DOM (isolated-world
+   * `querySelector`, value or attribute) — no page-JS execution.
+   *
+   * Returns a `Record<string, string>` of `name → value`, with names
+   * whose element (or attribute) was absent omitted. Throws
+   * `FetchproxyProtocolError` on bridge failures and a plain `Error` on
+   * developer mistakes (undeclared capability, undeclared name).
+   */
+  async readDom(opts) {
+    if (!this.opts.capabilities.includes("read_dom")) {
+      throw new Error('FetchproxyServer.readDom(): MCP did not declare "read_dom" in capabilities');
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    if (!Array.isArray(opts.names) || opts.names.length === 0) {
+      throw new Error("FetchproxyServer.readDom: opts.names must be a non-empty array");
+    }
+    this.assertScopeSubset(opts.names, this.opts.domSelectors.map((d) => d.name), "domSelectors");
+    if (opts.subdomain !== void 0)
+      assertSubdomainLabel(opts.subdomain);
+    const baseDomain = this.resolveBaseDomain(opts.domain);
+    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    const origin = `https://${host}`;
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "read_dom",
+      init: { origin, names: [...opts.names] }
+    };
+    const pending = new Promise((resolve, reject) => {
+      this.pendingStorage.set(id, { resolve, reject });
+    });
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
+  }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
     if (undeclared.length > 0) {
@@ -37931,7 +38051,7 @@ var FetchproxyServer = class {
     if (storageCb) {
       this.pendingStorage.delete(inner.id);
       if (inner.ok) {
-        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage") && inner.values) {
+        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage" || inner.op === "read_dom") && inner.values) {
           storageCb.resolve({ ...inner.values });
         } else {
           storageCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on storage awaiter`));
@@ -38326,7 +38446,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "signupgenius-mcp",
-  version: "1.1.6",
+  version: "1.2.0",
   mcpName: "io.github.chrischall/signupgenius-mcp",
   description: "SignUpGenius MCP server \u2014 read sign-ups, reports, and groups; add group members.",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -38363,7 +38483,7 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -38374,7 +38494,7 @@ var package_default = {
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
-    typescript: "^6.0.3",
+    typescript: "^7.0.2",
     vitest: "^4.1.7"
   }
 };
@@ -39387,7 +39507,7 @@ bannerLines.push(
 );
 await runMcp({
   name: "signupgenius",
-  version: "1.1.6",
+  version: "1.2.0",
   // x-release-please-version
   banner: bannerLines.join("\n"),
   deps: client,

package/dist/index.js

@@ -47,7 +47,7 @@ const bannerLines = account
 bannerLines.push('[signupgenius-mcp] Developed and maintained by AI (Claude). Use at your own discretion.');
 await runMcp({
     name: 'signupgenius',
-    version: '1.1.6', // x-release-please-version
+    version: '1.2.0', // x-release-please-version
     banner: bannerLines.join('\n'),
     deps: client,
     tools: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signupgenius-mcp",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "mcpName": "io.github.chrischall/signupgenius-mcp",
   "description": "SignUpGenius MCP server — read sign-ups, reports, and groups; add group members.",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -37,7 +37,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -48,7 +48,7 @@
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.7"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/signupgenius-mcp",
     "source": "github"
   },
-  "version": "1.1.6",
+  "version": "1.2.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "signupgenius-mcp",
-      "version": "1.1.6",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       },

package/skills/signupgenius/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: signupgenius-mcp
+description: Read sign-up sheets, slot reports, and groups on SignUpGenius — and add members to your groups. Triggers on phrases like "check SignUpGenius", "what am I signed up for", "what slots are left for [event]", "available slots", "list my SignUpGenius groups", "add [person] to my [group] group", or any request involving SignUpGenius sign-ups, RSVPs, volunteer slots, potlucks, carpools, classroom helpers, or PTA/HOA/Scout/team sign-ups. Works against your own signed-in account; supports Pro key for full slot reports.
+---
+
+# signupgenius-mcp
+
+MCP server for [SignUpGenius](https://www.signupgenius.com) — 14 read tools + 2 write across profile, groups, sign-ups, and reports.
+
+- **npm:** [npmjs.com/package/signupgenius-mcp](https://www.npmjs.com/package/signupgenius-mcp)
+- **Source:** [github.com/chrischall/signupgenius-mcp](https://github.com/chrischall/signupgenius-mcp)
+
+## Setup
+
+Three auth modes, tried in priority order — first match wins. **You only need one.**
+
+### Mode 1 — fetchproxy fallback (zero env vars, recommended)
+
+Install the [fetchproxy extension](https://github.com/chrischall/fetchproxy) once, sign into [signupgenius.com](https://www.signupgenius.com), and add to `.mcp.json` (project) or `~/.claude/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "signupgenius": {
+      "command": "npx",
+      "args": ["-y", "signupgenius-mcp"]
+    }
+  }
+}
+```
+
+At startup the MCP reads your `accessToken` / `cfid` / `cftoken` cookies once via the extension, then talks to SignUpGenius directly — the extension is **not** in the request hot path after that. Works with free accounts.
+
+### Mode 2 — session login (email + password)
+
+Add an env block with your direct-login credentials (won't work with Google/Apple/Facebook/Microsoft SSO or 2FA):
+
+```json
+{
+  "mcpServers": {
+    "signupgenius": {
+      "command": "npx",
+      "args": ["-y", "signupgenius-mcp"],
+      "env": {
+        "SIGNUPGENIUS_EMAIL": "you@example.com",
+        "SIGNUPGENIUS_PASSWORD": "your-password"
+      }
+    }
+  }
+}
+```
+
+### Mode 3 — Pro API key (required for slot reports)
+
+The three `signupgenius_report_*` tools that list filled / available / all participants for a given sign-up only work against the documented Pro v2 API. Get a key from **Pro Tools → API Management** in your SignUpGenius dashboard (Pro subscription required), then:
+
+```json
+"env": { "SIGNUPGENIUS_USER_KEY": "your-api-key" }
+```
+
+Modes can be combined; Pro key wins where it applies, session/fetchproxy handles everything else.
+
+## Tools
+
+### Profile
+
+- **`signupgenius_get_profile`** — Your own profile (name, email, account type).
+
+### Groups
+
+- **`signupgenius_list_groups`** — Every group you own or belong to.
+- **`signupgenius_list_group_members`** — Members of one of your groups.
+- **`signupgenius_get_group_member`** — One member's full record.
+- **`signupgenius_add_group_member`** *(write)* — Add a person to one of your groups.
+
+### Sign-ups — created by you
+
+- **`signupgenius_list_created_active`** — Sign-ups you've created that are still open.
+- **`signupgenius_list_created_expired`** — Sign-ups you've created that have ended.
+- **`signupgenius_list_created_all`** — Both active and expired in one call.
+
+### Sign-ups — others'
+
+- **`signupgenius_list_invited`** — Sign-ups you've been invited to.
+- **`signupgenius_list_signedupfor`** — Sign-ups you've taken a slot on. (Session-mode also includes the bonus `signupgenius_legacy_get_my_signups` which calls the same backend the SignUpGenius web wizard uses and sometimes returns fuller data.)
+- **`signupgenius_legacy_get_my_signups`** *(session only)* — Bonus richer "what am I signed up for" lookup.
+
+### Public sign-up
+
+- **`signupgenius_get_public_signup`** — Fetch a public sign-up page by URL or slug. No auth required.
+- **`signupgenius_rsvp`** *(write)* — RSVP to a public sign-up slot.
+
+### Reports — slots for a sign-up (Pro key only)
+
+- **`signupgenius_report_all`** — Every slot + participant on a sign-up.
+- **`signupgenius_report_filled`** — Filled slots only.
+- **`signupgenius_report_available`** — Available slots only.
+
+Session-mode users hit a fast `ModeMismatchError` on the report tools with a clear instruction to set `SIGNUPGENIUS_USER_KEY`.
+
+## Trigger examples
+
+- "Check SignUpGenius — what am I signed up for this week?" → `signupgenius_list_signedupfor` (+ `_legacy_get_my_signups` in session mode)
+- "What slots are still open on the PTA potluck sign-up?" → `signupgenius_report_available` (Pro key)
+- "List my SignUpGenius groups" → `signupgenius_list_groups`
+- "Add Jordan Smith (<jordan@example.com>) to my Scouts group" → `signupgenius_add_group_member`
+- "What sign-ups have I created that are still active?" → `signupgenius_list_created_active`
+- "RSVP me to slot 3 on this SignUpGenius link" → `signupgenius_rsvp`
+
+## Gotchas
+
+- **Reports require Pro.** `signupgenius_report_*` only work with `SIGNUPGENIUS_USER_KEY` — session/fetchproxy users get a clear error pointing at the key.
+- **SSO accounts not supported.** Session mode is direct email/password only — no Google/Apple/Facebook/Microsoft SSO, no 2FA. Use fetchproxy mode instead if your account uses SSO.
+- **Session listings collapse.** In session mode the v3 `signups/created` endpoint returns active + expired in one paginated call — the three `list_created_*` tools all hit the same endpoint and filter client-side. Pro key mode has separate endpoints and exposes the real distinction.
+- **Write surface is small.** Only `signupgenius_add_group_member` and `signupgenius_rsvp` mutate; everything else is read-only.
+- **ToS caveat.** SignUpGenius's terms generally prohibit scripted/automated access. Personal-account, personal-scale use is the intended audience; running this against accounts you don't own or at scale is your problem.

package/skills/signupgenius-api/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: signupgenius-api
+description: "Access SignUpGenius (sign-ups, groups, RSVPs) from a shell with curl instead of running the signupgenius-mcp server — server-side email/password login to a JWT + cfid/cftoken cookies, then curl the v3 API and legacy /SUGboxAPI.cfm dispatcher directly. Use when you want SignUpGenius data without the MCP, in a script, or on a machine where the MCP isn't installed."
+---
+
+# SignUpGenius via curl (no MCP)
+
+SignUpGenius's session mode is a classic ColdFusion login: POST email+password
+to the login form, get back a `accessToken` JWT cookie plus `cfid`/`cftoken`
+session cookies. No browser or extension needed — everything here is a plain
+`curl` call. This is the same auth path `signupgenius-mcp` uses in session
+mode (`src/auth-session-login.ts`); its fetchproxy path (lifting the same
+cookies out of a signed-in browser tab) is only a **fallback** for when you
+don't want to put a password in `.env` — this skill always logs in directly.
+
+## One-time setup
+
+```sh
+export SIGNUPGENIUS_EMAIL="you@example.com"
+export SIGNUPGENIUS_PASSWORD="..."
+# or: export SIGNUPGENIUS_PASSWORD="$(op read 'op://Private/SignUpGenius/password')"
+```
+
+SSO accounts (Google/Apple/Facebook/Microsoft) and 2FA-enabled accounts can't
+use this flow — same limitation as the MCP's session mode.
+
+## Log in: get the JWT + cookies
+
+```sh
+COOKIEJAR=$(mktemp)
+
+CSRF=$(curl -s -c "$COOKIEJAR" https://www.signupgenius.com/login \
+  | grep -oE 'name="csrfToken"[[:space:]]+value="[^"]+"' \
+  | sed -E 's/.*value="([^"]+)".*/\1/')
+
+curl -s -D /tmp/sug-login-headers.txt -o /dev/null \
+  -b "$COOKIEJAR" -c "$COOKIEJAR" \
+  -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36' \
+  -X POST 'https://www.signupgenius.com/index.cfm?go=c.Login' \
+  --data-urlencode "csrfToken=$CSRF" \
+  --data-urlencode "loginemail=$SIGNUPGENIUS_EMAIL" \
+  --data-urlencode "pword=$SIGNUPGENIUS_PASSWORD" \
+  --data-urlencode "successpage=c.jump&jump=/index.cfm?go=c.MyAccount" \
+  --data-urlencode "failpage=c.Register" \
+  --data-urlencode "ScreenWidth=2000" \
+  --data-urlencode "ScreenHeight=1200" \
+  --data-urlencode "formaction=1" \
+  --data-urlencode "formName=loginform" \
+  --data-urlencode "refererUrl="
+
+# Bad credentials 302 to c.Register instead of setting accessToken — check both:
+grep -q 'c.Register' /tmp/sug-login-headers.txt && echo "LOGIN FAILED (bad credentials)" >&2
+
+ACCESS_TOKEN=$(awk -F'\t' '$6=="accessToken"{print $7}' "$COOKIEJAR")
+CFID=$(awk -F'\t' '$6=="cfid"{print $7}' "$COOKIEJAR")
+CFTOKEN=$(awk -F'\t' '$6=="cftoken"{print $7}' "$COOKIEJAR")
+[ -z "$ACCESS_TOKEN" ] && echo "LOGIN FAILED (no accessToken cookie set)" >&2
+COOKIE_HEADER="accessToken=${ACCESS_TOKEN}; cfid=${CFID}; cftoken=${CFTOKEN}"
+```
+
+This mirrors `sessionLoginFlow` exactly: GET `/login` for the CSRF token +
+`cfid`/`cftoken`, POST the credentials with the exact same static form fields
+the wizard sends, and read the `accessToken` cookie back out of the jar as
+the success marker.
+
+## Core call pattern
+
+Every authenticated call carries **both** headers — a Bearer JWT for the v3
+API and the raw cookie header for the legacy dispatcher (the client sends
+both on every request regardless of which surface it's hitting):
+
+```sh
+curl -s 'https://api.signupgenius.com/v3/member/profile/' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H "Cookie: $COOKIE_HEADER" | jq .
+```
+
+```sh
+curl -s -X POST 'https://www.signupgenius.com/SUGboxAPI.cfm?go=t.getMySignups' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" \
+  -H "Cookie: $COOKIE_HEADER" \
+  -H 'Content-Type: application/json' \
+  -d '{}' | jq .
+```
+
+Ready-to-run request bodies for every tool endpoint (groups, sign-up
+listings, public sign-up lookup, and the 3-step RSVP flow) are in
+`references/sug-endpoints.md`.
+
+## The two envelope shapes
+
+- v3 API (`api.signupgenius.com/v3/...`) returns **lower-case**
+  `{data, message, success}`.
+- The legacy dispatcher (`/SUGboxAPI.cfm?go=...`) returns **upper-case**
+  `{DATA, MESSAGE, SUCCESS}` — `MESSAGE` may be a bare string instead of an
+  array.
+
+`jq` recipes in the reference file account for the case difference per
+endpoint.
+
+## Session expiry
+
+Two signals mean the session lapsed — re-run the login step and retry:
+
+- an HTTP `401` from either surface, or
+- an HTTP `200` whose body is HTML containing `loginform`/`loginemail`/
+  `go=c.Login` (the server quietly bounced you to the login page instead of
+  returning JSON).
+
+A `403` is a Pro-permission failure, not expiry — don't retry the login for
+that one.
+
+## Out of scope for this skill
+
+- **Pro API key mode** (`SIGNUPGENIUS_USER_KEY`, `Authorization: <key>` against
+  `api.signupgenius.com/v2/k`) is a different auth entirely — it's the only
+  mode that can call the slot-report endpoints
+  (`/signups/report/{all,filled,available}/{signupId}`), which are not
+  reachable in session mode at all (no v3 equivalent exists). Not covered
+  here since this skill is the email/password session path.
+- **fetchproxy** (lifting these same cookies out of a signed-in browser tab)
+  is the MCP's fallback for when no env credentials are set. This skill
+  always logs in directly, so fetchproxy/the Transporter extension is never
+  needed.

package/skills/signupgenius-api/references/sug-endpoints.md

@@ -0,0 +1,200 @@
+# SignUpGenius session-mode endpoints for curl
+
+All calls assume `$ACCESS_TOKEN` and `$COOKIE_HEADER` from the login step in
+`../SKILL.md`. Every call sends both:
+
+```
+-H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER"
+```
+
+Paths under `api.signupgenius.com/v3` are the exact paths `signupgenius-mcp`'s
+`client.ts` builds in session mode (it appends a trailing `/` to every v3
+path — included below). Legacy calls POST JSON to
+`https://www.signupgenius.com/SUGboxAPI.cfm?go=<action>` with
+`Content-Type: application/json`.
+
+---
+
+## 1. Profile
+
+```sh
+curl -s 'https://api.signupgenius.com/v3/member/profile/' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" | jq '.data'
+```
+
+## 2. Groups
+
+List groups (`sort` is optional, `asc`/`desc`):
+
+```sh
+curl -s 'https://api.signupgenius.com/v3/groups/all/?sort=asc' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  | jq -r '.data[] | "\(.groupid)\t\(.title)"'
+```
+
+List a group's members (`GROUP_ID` from above):
+
+```sh
+curl -s "https://api.signupgenius.com/v3/groups/${GROUP_ID}/members/" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  | jq -r '.data[] | "\(.communitymemberid)\t\(.emailaddress)"'
+```
+
+Get one member's detail (address/phone — only present if they supplied it on
+a sign-up):
+
+```sh
+curl -s "https://api.signupgenius.com/v3/groups/${GROUP_ID}/members/${MEMBER_ID}/details/" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" | jq '.data'
+```
+
+Add a member (**write** — confirm with the user first; `firstname`/`lastname`
+are optional):
+
+```sh
+curl -s -X POST "https://api.signupgenius.com/v3/groups/${GROUP_ID}/members/create/" \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  -H 'Content-Type: application/json' \
+  -d '{"emailaddress":"new-member@example.com","firstname":"Jane","lastname":"Doe"}' \
+  | jq '.success, .message'
+```
+
+## 3. Sign-up listings
+
+In session mode `created`/`invited`/`signedupfor` each have **one** v3 path
+each (unlike key mode's separate `/active`/`/expired`/`/all` paths) — filter
+on `enddate` client-side if you only want active ones:
+
+```sh
+# everything the account created (active + expired together)
+curl -s 'https://api.signupgenius.com/v3/signups/created/' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  | jq -r '.data[] | "\(.signupid)\t\(.enddate)\t\(.title)"'
+
+# sign-ups invited to
+curl -s 'https://api.signupgenius.com/v3/signups/invited/' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" | jq '.data'
+
+# sign-ups personally signed up for
+curl -s 'https://api.signupgenius.com/v3/signups/signedupfor/' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" | jq '.data'
+```
+
+Legacy dispatcher equivalent — sometimes returns fuller data than v3
+(note the **upper-case** envelope):
+
+```sh
+curl -s -X POST 'https://www.signupgenius.com/SUGboxAPI.cfm?go=t.getMySignups' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  -H 'Content-Type: application/json' -d '{}' \
+  | jq -r '.DATA[] | "\(.signupid)\t\(.title)"'
+```
+
+## 4. Public sign-up lookup (no auth)
+
+Any sign-up's public page is server-rendered HTML at
+`https://www.signupgenius.com/go/<urlid>-<signupid>[-<vanity>]` — no login
+needed, works even without the login step above:
+
+```sh
+curl -s 'https://www.signupgenius.com/go/10C054DA9AF2BA0FEC07-63774883-myers' -o /tmp/sug-page.html
+
+grep -oE '<h1 class="SUGHeaderText">[^<]*' /tmp/sug-page.html | sed 's/.*>//'   # title
+grep -A2 '<strong>Date' /tmp/sug-page.html | head -1                           # date (needs HTML stripping)
+```
+
+There's no JSON surface for this page — `signupgenius-mcp`'s
+`tools/public-signup.ts` regex-scrapes the same landmarks
+(`h1.SUGHeaderText`, `<strong>Date/Time/Location</strong>`, the
+`creator-info` table, and `Yes:/No:/Maybe:` response counts). Reproduce with
+`grep`/`sed` for a quick look, or pull the regexes straight from that file for
+anything more than a spot-check.
+
+## 5. RSVP (write, 3-step flow)
+
+RSVP-only (Yes/No/Maybe headcount) sheets. **Confirm with the user before
+running step 3** — it's the real submit. Get `URLID` (the full slug) by
+parsing the public URL as in §4.
+
+**Step 1 — PreProcessSignup** (sets a server-side session pointer; without
+this every SUGboxAPI call below 404s with "none to be processed"). Expect
+**301/302**, not 200:
+
+```sh
+curl -s -o /dev/null -w '%{http_code}\n' -D - \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: text/html' \
+  -X POST "https://www.signupgenius.com/index.cfm?go=s.PreProcessSignup&URLID=${URLID}" \
+  --data 'ScreenWidth=2000&ScreenHeight=1200'
+```
+
+**Step 2 — getSignupInfo** (fetch `useRSVP` + `rsvpdetails.slotid`; reject if
+`useRSVP != 1` or `rsvpdetails.rsvpitems` is non-empty — that's an item-based
+sheet, unsupported by this flow):
+
+```sh
+curl -s -X POST 'https://www.signupgenius.com/SUGboxAPI.cfm?go=s.getSignupInfo' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  -H 'Content-Type: application/json' \
+  -d "{\"urlid\":\"${URLID}\"}" | tee /tmp/sug-signupinfo.json | jq '.DATA | {useRSVP, owner, id, title, slotid: .rsvpdetails.slotid}'
+```
+
+**Step 3 — processSignUpFormHandler** (the actual RSVP submit). `RSVPITEMS`
+must always be present as `[]` — the CFML validator throws
+`key [RSVPITEMS] doesn't exist` if it's omitted. `changemembermame` is
+SignUpGenius's own typo — preserve it verbatim. `rsvpresponse` is a single
+letter: `y`/`n`/`m`. A `n` response forces both guest counts to `0`
+regardless of what you pass:
+
+```sh
+OWNER=$(jq -r '.DATA.owner' /tmp/sug-signupinfo.json)
+LISTID=$(jq -r '.DATA.id' /tmp/sug-signupinfo.json)
+TITLE=$(jq -r '.DATA.title' /tmp/sug-signupinfo.json)
+SLOTID=$(jq -r '.DATA.rsvpdetails.slotid' /tmp/sug-signupinfo.json)
+
+curl -s -X POST 'https://www.signupgenius.com/SUGboxAPI.cfm?go=s.processSignUpFormHandler' \
+  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Cookie: $COOKIE_HEADER" \
+  -H 'Content-Type: application/json' \
+  -d @- <<JSON | jq '.SUCCESS, .MESSAGE'
+{
+  "listid": ${LISTID},
+  "owner": ${OWNER},
+  "urlid": "${URLID}",
+  "title": "${TITLE}",
+  "siid": "",
+  "rsvpid": 0,
+  "imid": 0,
+  "usealternatename": false,
+  "changemembermame": false,
+  "displayfirstname": "Jane",
+  "displaylastname": "Doe",
+  "firstname": "Jane",
+  "lastname": "Doe",
+  "email": "jane@example.com",
+  "optInStatus": false,
+  "savecontactinfo": false,
+  "rsvpresponse": "y",
+  "rsvpadult": 1,
+  "rsvpchildren": 0,
+  "rsvpitems": [],
+  "rsvpcomments": "",
+  "type": "rsvp",
+  "source": "main",
+  "slotid": ${SLOTID},
+  "isLoggedin": true,
+  "payLater": false,
+  "customFields": []
+}
+JSON
+```
+
+## Omitted — not reachable in session mode
+
+Slot-report endpoints (`/signups/report/all|filled|available/{signupId}`)
+require `SIGNUPGENIUS_USER_KEY` (Pro API key mode, `Authorization: <key>`
+against `api.signupgenius.com/v2/k`, `user_key` in the query string) — a
+different auth entirely from the session login this skill uses. No v3
+equivalent was found during the MCP's recon (`src/tools/reports.ts`), so
+there's nothing to transcribe for session mode. Slot-based (non-headcount)
+sign-ups also have no submit flow here — the wizard's `s.getSignUpFormItems`
++ per-item payload was never captured.