signupgenius-mcp 1.0.1 → 1.0.2

package/README.md

@@ -2,11 +2,12 @@
 
 MCP server for [SignUpGenius](https://www.signupgenius.com). 13 read tools and 1 write across profile, groups, sign-ups, and reports.
 
-Two auth modes:
-- **Session mode (recommended).** Logs in with your normal email/password to call the same web API the signupgenius.com dashboard uses. **Free accounts work.** No SSO/2FA.
-- **Key mode.** Uses the documented Pro API key. Required only for the slot REPORT tools (filled/available/all-participants). Pro subscription needed.
+Three auth modes (tried in this priority order — first match wins):
+1. **Pro key mode.** Uses the documented Pro API key. Required only for the slot REPORT tools (filled/available/all-participants). Pro subscription needed.
+2. **Session mode.** Logs in with your normal email/password to call the same web API the signupgenius.com dashboard uses. **Free accounts work.** No SSO/2FA.
+3. **fetchproxy fallback (no env vars needed).** When no env vars are set, the server reads `accessToken` / `cfid` / `cftoken` cookies once at startup from your already-signed-in `signupgenius.com` tab via the [fetchproxy](https://github.com/chrischall/fetchproxy) browser extension. After that one read, all SignUpGenius API calls go directly from Node — the extension is **not** in the request hot path. Install the extension once, sign into SignUpGenius, and the MCP just works.
 
-Both modes can be configured at the same time — set `SIGNUPGENIUS_USER_KEY` to force key mode, otherwise email/password takes effect.
+Set `SIGNUPGENIUS_DISABLE_FETCHPROXY=1` to opt out of the fallback (turns missing credentials into a hard error — useful in headless CI).
 
 ## Tools
 
@@ -45,9 +46,15 @@ SIGNUPGENIUS_NAME=PTA Org              # optional
 
 Find the user key in SignUpGenius under **Pro Tools → API Management**.
 
+### fetchproxy fallback (no env vars)
+
+Install the [fetchproxy extension](https://github.com/chrischall/fetchproxy) (Chrome Web Store / Safari `.dmg`), sign into [signupgenius.com](https://www.signupgenius.com), and remove the env block from your MCP config. The MCP reads `accessToken` / `cfid` / `cftoken` cookies once at startup and uses them like a session-mode login. No password copy-paste required.
+
+The slot REPORT tools still require Pro key mode — `SIGNUPGENIUS_USER_KEY` is the only path that hits the documented v2/k Pro API.
+
 ### Both at once
 
-Set both. Key mode wins. Useful if you have Pro for some accounts and want reports while still using your normal login elsewhere.
+Set both Pro key and email/password. Key mode wins. Useful if you have Pro for some accounts and want reports while still using your normal login elsewhere.
 
 ### Advanced overrides
 
@@ -56,6 +63,7 @@ Set both. Key mode wins. Useful if you have Pro for some accounts and want repor
 | `SIGNUPGENIUS_BASE_URL` | key: `https://api.signupgenius.com/v2/k`<br>session: `https://api.signupgenius.com/v3` | Override the JSON API base. |
 | `SIGNUPGENIUS_LEGACY_BASE_URL` | `https://www.signupgenius.com` | Override the host for `/SUGboxAPI.cfm?go=…` legacy calls. |
 | `SIGNUPGENIUS_LOGIN_URL` | `https://www.signupgenius.com` | Override the login form host. |
+| `SIGNUPGENIUS_DISABLE_FETCHPROXY` | unset | Set to `1` to skip the fetchproxy fallback (missing creds become a hard error). |
 
 ## ToS caveat
 

package/dist/auth.js

@@ -0,0 +1,163 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Auth resolution — Pattern A template
+// ────────────────────────────────────────────────────────────────────────────
+//
+// SignUpGenius supports three auth paths. This file picks one, in priority
+// order, and hands the chosen path to `SignUpGeniusClient`. It mirrors the
+// Pattern A shape used by ofw-mcp/src/auth.ts so all sibling MCPs in this
+// family stay structurally aligned.
+//
+// THE THREE PATHS, in priority order:
+//
+//   1. Pro API key (existing)
+//      SIGNUPGENIUS_USER_KEY set → stateless `Authorization: <key>` against
+//      the documented v2/k Pro API. The only path that can call slot reports.
+//      Unchanged from pre-fetchproxy behavior.
+//
+//   2. Session-login (existing)
+//      SIGNUPGENIUS_EMAIL + SIGNUPGENIUS_PASSWORD set → POST the login form,
+//      scrape `csrfToken`, capture `accessToken` (JWT) + `cfid`/`cftoken`
+//      cookies. Calls go to the v3 web API (Bearer) and the legacy
+//      `/SUGboxAPI.cfm` dispatcher (cookies). Unchanged from pre-fetchproxy
+//      behavior.
+//
+//   3. fetchproxy fallback (new)
+//      When no env vars are set, lift the user's session out of their
+//      already-signed-in signupgenius.com browser tab. `@fetchproxy/bootstrap`
+//      opens a one-shot WebSocket bridge, asks the extension for the
+//      `accessToken` / `MTOKEN` / `cfid` / `cftoken` cookies (all declared
+//      upfront — that's the security boundary), and closes the bridge.
+//      Subsequent SignUpGenius calls go out via plain Node `fetch()` with
+//      those cookies attached — fetchproxy is NOT in the request hot path.
+//
+//      Note: `accessToken` and `MTOKEN` carry the same JWT value (verified
+//      via DevTools); we accept either and prefer `accessToken` if both are
+//      present.
+//
+//      Users opt out with SIGNUPGENIUS_DISABLE_FETCHPROXY=1 (anyone who
+//      wants the old behavior of "fail loudly when creds are missing").
+//
+//   4. Error
+//      Nothing to authenticate with. We throw a message that names both
+//      escape hatches: set creds OR install the extension and sign in.
+//
+// Testability:
+//   - `@fetchproxy/bootstrap` is mocked at the module boundary in tests.
+//   - `loadAccount()` (the existing env-var resolver) is reused as-is so the
+//     legacy paths keep working unchanged.
+import { bootstrap } from '@fetchproxy/bootstrap';
+import { loadAccount } from './config.js';
+import pkg from '../package.json' with { type: 'json' };
+function readEnv(key) {
+    const raw = process.env[key];
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed === 'undefined' || trimmed === 'null')
+        return undefined;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+function fetchproxyDisabled() {
+    const raw = readEnv('SIGNUPGENIUS_DISABLE_FETCHPROXY');
+    if (raw === undefined)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+}
+/**
+ * The exact error message `loadAccount()` throws when NO auth env vars are
+ * set. We catch this specific string so partial-config errors (which the
+ * user MUST fix) still propagate, but the "you didn't set anything at all"
+ * case falls through to fetchproxy.
+ */
+const NO_ENV_CONFIG_MARKER = 'Missing SignUpGenius auth config';
+/**
+ * Resolve SignUpGenius auth using the three-path priority described at the
+ * top of this file. Throws with an actionable message when no path succeeds.
+ */
+export async function resolveAuth() {
+    // ── Paths 1 & 2: env-var credentials. loadAccount() handles precedence,
+    //    partial-config errors, and env-var sanitization for us.
+    try {
+        const account = loadAccount();
+        return { account, source: 'env' };
+    }
+    catch (e) {
+        // `loadAccount()` only ever throws plain Error instances (validated by
+        // tests in config.test.ts). Partial-config errors (missing one of the
+        // EMAIL/PASSWORD pair, non-https override URL, etc.) are USER MISTAKES
+        // and should propagate. Only the "nothing set at all" case is allowed
+        // to fall through to fetchproxy.
+        if (!e.message.startsWith(NO_ENV_CONFIG_MARKER)) {
+            throw e;
+        }
+    }
+    // ── Path 3: fetchproxy fallback.
+    if (!fetchproxyDisabled()) {
+        try {
+            const session = await bootstrap({
+                serverName: pkg.name,
+                version: pkg.version,
+                domains: ['signupgenius.com'],
+                declare: {
+                    // Declare ALL the cookies we might need. The 0.3.0 read_cookies
+                    // capability uses chrome.cookies.get (HttpOnly-visible) — the
+                    // security gate is this declared key list, not HttpOnly status.
+                    // MTOKEN is signupgenius.com's older name for the JWT; on some
+                    // browsers/sessions one shows up first. accessToken takes priority
+                    // when both are present.
+                    cookies: ['MTOKEN', 'accessToken', 'cfid', 'cftoken'],
+                    localStorage: [],
+                    sessionStorage: [],
+                    captureHeaders: [],
+                },
+            });
+            const accessToken = session.cookies['accessToken'] ?? session.cookies['MTOKEN'];
+            if (!accessToken) {
+                throw new Error('accessToken cookie missing on signupgenius.com. ' +
+                    'Sign into signupgenius.com in your browser (with the fetchproxy extension installed) and retry.');
+            }
+            // Build the cookie header the legacy /SUGboxAPI.cfm dispatcher expects.
+            // accessToken first (the JWT also lives in this cookie jar) then the CF
+            // pair if present. Anything else gets ignored.
+            const parts = [`accessToken=${accessToken}`];
+            const cfid = session.cookies['cfid'];
+            const cftoken = session.cookies['cftoken'];
+            if (cfid)
+                parts.push(`cfid=${cfid}`);
+            if (cftoken)
+                parts.push(`cftoken=${cftoken}`);
+            const cookieHeader = parts.join('; ');
+            // Synthesize a session account with empty creds — the client will see
+            // `preloaded` and skip the form login. The bases match the defaults
+            // used by `loadAccount()` so behavior is identical from here on.
+            const account = {
+                mode: 'session',
+                name: 'signupgenius.com (browser)',
+                baseUrl: 'https://api.signupgenius.com/v3',
+                legacyBaseUrl: 'https://www.signupgenius.com',
+                loginBaseUrl: 'https://www.signupgenius.com',
+                email: '',
+                password: '',
+            };
+            return {
+                account,
+                preloaded: { accessToken, cookieHeader },
+                source: 'fetchproxy',
+            };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error('SignUpGenius auth: no SIGNUPGENIUS_USER_KEY or SIGNUPGENIUS_EMAIL/PASSWORD set, ' +
+                `and fetchproxy fallback failed: ${msg}`);
+        }
+    }
+    // ── Path 4: nothing configured and fetchproxy explicitly disabled.
+    throw new Error('Missing SignUpGenius auth config. Set SIGNUPGENIUS_USER_KEY (Pro API), ' +
+        'or SIGNUPGENIUS_EMAIL + SIGNUPGENIUS_PASSWORD (session mode, free accounts), ' +
+        'or install the fetchproxy extension and sign into signupgenius.com ' +
+        '(unset SIGNUPGENIUS_DISABLE_FETCHPROXY if it is set).');
+}