signupgenius-mcp 1.1.4 → 1.1.6

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.4"
+    "version": "1.1.6"
   },
   "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.4",
+      "version": "1.1.6",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "signupgenius-mcp",
   "displayName": "SignUpGenius",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "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",

package/dist/bundle.js

@@ -13,7 +13,11 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 var __commonJS = (cb, mod) => function __require2() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -34697,6 +34701,32 @@ var McpToolError = class extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+var UnreachableError = class extends McpToolError {
+  /** Upstream HTTP status, when one was observed. */
+  status;
+  constructor(service, status) {
+    const suffix = status !== void 0 ? ` (status ${status})` : "";
+    super(`${service} unreachable${suffix}. The service may be down \u2014 try again later.`, {
+      hint: "The upstream service is temporarily unavailable; retry later."
+    });
+    this.name = "UnreachableError";
+    if (status !== void 0)
+      this.status = status;
+  }
+};
+var ModeMismatchError = class extends McpToolError {
+  currentMode;
+  requiredMode;
+  feature;
+  constructor(currentMode, requiredMode, feature) {
+    const hint = `Switch to ${requiredMode} mode to use ${feature}.`;
+    super(`${feature} requires ${requiredMode} mode but the server is running in ${currentMode} mode. ${hint}`, { hint });
+    this.currentMode = currentMode;
+    this.requiredMode = requiredMode;
+    this.feature = feature;
+    this.name = "ModeMismatchError";
+  }
+};
 function createHelpfulError(message, opts) {
   return new McpToolError(message, opts);
 }
@@ -34714,6 +34744,9 @@ var API_KEY_RE = new RegExp([
   "whsec_[A-Za-z0-9]{16,}\\b"
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
+var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
+var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
+var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
 
 // node_modules/@chrischall/mcp-utils/dist/response/index.js
 function textResult(data) {
@@ -35860,10 +35893,20 @@ async function openEncryptedFrame(sessionKey, frame) {
 
 // node_modules/@fetchproxy/server/dist/election.js
 import { createServer, Server as HttpServer } from "node:http";
+var DEFAULT_BIND_TIMEOUT_MS = 5e3;
 async function electRole(opts) {
   const server = createServer();
+  const bindTimeoutMs = opts.bindTimeoutMs ?? DEFAULT_BIND_TIMEOUT_MS;
   return new Promise((resolve, reject) => {
+    let timer;
+    const clearBindTimer = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+    };
     const onError = (e) => {
+      clearBindTimer();
       server.removeListener("listening", onListening);
       if (e.code === "EADDRINUSE") {
         try {
@@ -35876,11 +35919,25 @@ async function electRole(opts) {
       }
     };
     const onListening = () => {
+      clearBindTimer();
       server.removeListener("error", onError);
       resolve({ role: "host", server });
     };
     server.once("error", onError);
     server.once("listening", onListening);
+    if (bindTimeoutMs > 0) {
+      timer = setTimeout(() => {
+        server.removeListener("error", onError);
+        server.removeListener("listening", onListening);
+        try {
+          server.close();
+        } catch {
+        }
+        reject(new Error(`fetchproxy: bind to ${opts.host}:${opts.port} timed out after ${bindTimeoutMs}ms (port may be in a bad state)`));
+      }, bindTimeoutMs);
+      if (typeof timer.unref === "function")
+        timer.unref();
+    }
     server.listen(opts.port, opts.host);
   });
 }
@@ -35973,6 +36030,44 @@ var SessionState = class {
   }
 };
 
+// node_modules/@fetchproxy/server/dist/session-ready.js
+var SESSION_READY_TIMEOUT_MS = 3e4;
+var FetchproxySessionNotReadyError = class extends Error {
+  reason;
+  pairCode;
+  mcpId;
+  hint;
+  constructor(info) {
+    const pairing = info.pairCode !== null && info.pairCode !== "";
+    const hint = pairing ? `Open the Transporter extension popup and approve pair code ${info.pairCode} for "${info.mcpId}", then retry.` : `The extension is connected but hasn't confirmed a session for "${info.mcpId}" \u2014 sign in to the target site in that browser (and approve the requested scope if it changed), then retry.`;
+    super(`fetchproxy: ${pairing ? "pairing not yet approved" : "no confirmed browser session"} for "${info.mcpId}". ${hint}`);
+    this.name = "FetchproxySessionNotReadyError";
+    this.reason = pairing ? "pair-required" : "not-ready";
+    this.pairCode = pairing ? info.pairCode : null;
+    this.mcpId = info.mcpId;
+    this.hint = hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+async function awaitSessionReady(ready, opts) {
+  const ms = opts.timeoutMs ?? SESSION_READY_TIMEOUT_MS;
+  if (ms <= 0)
+    return ready;
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new FetchproxySessionNotReadyError({ mcpId: opts.mcpId, pairCode: opts.pendingPairCode() }));
+    }, ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([ready, timeout]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+  }
+}
+
 // node_modules/@fetchproxy/server/dist/host.js
 var PUBLIC_ORIGIN_RE = /^https?:\/\/(?!(127\.0\.0\.1|localhost)(:|$))/i;
 var enc2 = new TextEncoder();
@@ -36060,6 +36155,29 @@ async function startHost(opts) {
           return;
         }
         if (frame.type === "hello" && frame.role === "server") {
+          const peerEdPub = fromB64(frame.identityEd25519Pub);
+          const peerSigMsg = concatBytes(enc2.encode(frame.mcpId), fromB64(frame.sessionNonce));
+          const peerSig = fromB64(frame.sessionSig);
+          let peerSigOk = false;
+          try {
+            peerSigOk = await ed25519Verify(peerEdPub, peerSigMsg, peerSig);
+          } catch {
+            peerSigOk = false;
+          }
+          if (!peerSigOk) {
+            console.warn("[fetchproxy] peer hello signature invalid \u2014 refusing registration (possible squatter)");
+            ws.close(1008, "peer hello signature invalid");
+            return;
+          }
+          const existing = peers.get(frame.mcpId);
+          if (existing && existing.ws !== ws) {
+            const existingEdPub = existing.helloFrame.identityEd25519Pub;
+            if (existingEdPub !== frame.identityEd25519Pub) {
+              console.warn("[fetchproxy] peer mcpId already mapped to a different identity \u2014 refusing (mcpId squatting)");
+              ws.close(1008, "mcpId already registered to another identity");
+              return;
+            }
+          }
           identified = "peer";
           peerMcpId = frame.mcpId;
           peers.set(frame.mcpId, { ws, helloFrame: frame });
@@ -36152,8 +36270,10 @@ async function startHost(opts) {
         resetSessionPromise();
         disconnectListeners.forEach((cb) => cb());
       }
-      if (identified === "peer" && peerMcpId)
-        peers.delete(peerMcpId);
+      if (identified === "peer" && peerMcpId) {
+        if (peers.get(peerMcpId)?.ws === ws)
+          peers.delete(peerMcpId);
+      }
     });
   });
   return {
@@ -36169,7 +36289,10 @@ async function startHost(opts) {
       });
     }),
     sendOwnInner: async (inner) => {
-      const session = await ownSessionReady;
+      const session = await awaitSessionReady(ownSessionReady, {
+        mcpId: opts.ownMcpId,
+        pendingPairCode: () => ownPendingPairCode
+      });
       if (!extensionWs)
         throw new Error("host: no extension connected");
       const sealed = await sealInnerFrame(session.sessionKey, opts.ownMcpId, session.nextOutboundSeq(), inner);
@@ -36274,7 +36397,10 @@ async function startPeer(opts) {
     ws,
     session: sessionPromise,
     sendInner: async (inner) => {
-      await sessionPromise;
+      await awaitSessionReady(sessionPromise, {
+        mcpId: opts.mcpId,
+        pendingPairCode: () => pendingPairCode
+      });
       const s = session;
       const sealed = await sealInnerFrame(s.sessionKey, opts.mcpId, s.nextOutboundSeq(), inner);
       ws.send(JSON.stringify(sealed));
@@ -36940,6 +37066,35 @@ var FetchproxyServer = class {
       this.keepAliveTimer = null;
     }
   }
+  /**
+   * Send an inner request frame via whichever bridge handle is active. If the
+   * send throws (e.g. `FetchproxySessionNotReadyError` — the session never
+   * confirmed), the frame never reached the bridge, so no reply will arrive:
+   * drop the just-registered pending resolver for this id (it lives in exactly
+   * one of the op maps — request ids are unique) so it doesn't leak until the
+   * server closes, then rethrow.
+   */
+  async sendInnerFrame(inner) {
+    try {
+      if (this.hostHandle) {
+        await this.hostHandle.sendOwnInner(inner);
+      } else if (this.peerHandle) {
+        await this.peerHandle.sendInner(inner);
+      }
+    } catch (err) {
+      if ("id" in inner && typeof inner.id === "number") {
+        const { id } = inner;
+        this.pending.delete(id);
+        this.pendingReadCookies.delete(id);
+        this.pendingStorage.delete(id);
+        this.pendingCapture.delete(id);
+        this.pendingRedirect.delete(id);
+        this.pendingDownload.delete(id);
+        this.pendingIdb.delete(id);
+      }
+      throw err;
+    }
+  }
   /**
    * Single bridge round-trip, wrapped by `fetchTimeoutMs` when set.
    * On timeout returns the `{ok:false, kind:'timeout'}` envelope —
@@ -36951,11 +37106,7 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve) => {
       this.pending.set(id, resolve);
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
+    await this.sendInnerFrame(inner);
     const timeoutMs = this.opts.fetchTimeoutMs;
     if (timeoutMs === void 0 || timeoutMs <= 0)
       return pending;
@@ -36984,6 +37135,51 @@ var FetchproxyServer = class {
         clearTimeout(timer);
     }
   }
+  /**
+   * FP-B2: bound a non-`fetch` verb's reply wait by `fetchTimeoutMs`.
+   *
+   * Before this, only `fetch()` raced its `pending` reply against a timer
+   * (`_fetchOnceWithTimeout`); `readCookies`, the storage reads,
+   * `capture_request_header`, `capture_redirect`, `download`, and
+   * `read_indexed_db` awaited their `pending` promise with no race, so a
+   * wedged extension hung the tool call indefinitely.
+   *
+   * `pending` is the already-registered reply promise. `pendingMap`/`id`
+   * point at the op-specific map entry so we can drop it on expiry exactly
+   * as `_fetchOnceWithTimeout` does — otherwise a late bridge reply would
+   * resolve into a stale resolver / leak. On timeout we reject with a
+   * `FetchproxyTimeoutError` (the same throwable the convenience methods
+   * already surface for fetch timeouts). `0`/unset opts out (unbounded),
+   * matching the fetch path.
+   */
+  async _withVerbTimeout(pending, pendingMap, id, url2) {
+    const timeoutMs = this.opts.fetchTimeoutMs;
+    if (timeoutMs === void 0 || timeoutMs <= 0)
+      return pending;
+    let timer;
+    const start = Date.now();
+    try {
+      return await Promise.race([
+        pending,
+        new Promise((_resolve, reject) => {
+          timer = setTimeout(() => {
+            pendingMap.delete(id);
+            reject(new FetchproxyTimeoutError({
+              url: url2,
+              timeoutMs,
+              role: this.role,
+              port: this.opts.port,
+              elapsedMs: Date.now() - start,
+              retryAttempted: false
+            }));
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
   /**
    * Map an `ok:false` fetch result to its typed throwable. Centralizes
    * the kind-to-error-class switch so `request()` and (via the same
@@ -37274,12 +37470,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve) => {
       this.pendingReadCookies.set(id, resolve);
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    const result = await pending;
+    await this.sendInnerFrame(inner);
+    const result = await this._withVerbTimeout(pending, this.pendingReadCookies, id, `https://${host}`);
     if (!result.ok) {
       throw new FetchproxyProtocolError(result.error);
     }
@@ -37345,12 +37537,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve, reject) => {
       this.pendingStorage.set(id, { resolve, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingStorage, id, `https://${host}`);
   }
   /**
    * 0.3.0+: snapshot the next outgoing request's named header. Single-
@@ -37454,12 +37642,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve, reject) => {
       this.pendingCapture.set(id, { resolve, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingCapture, id, `https://${opts.host}${opts.path ?? "/*"}`);
   }
   /**
    * Snapshot the redirect target URL of the next request the browser
@@ -37543,12 +37727,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve, reject) => {
       this.pendingRedirect.set(id, { resolve, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingRedirect, id, `https://${opts.host}${opts.path ?? "/*"}`);
   }
   /**
    * Download `url` through the BROWSER's own network stack via
@@ -37629,12 +37809,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve, reject) => {
       this.pendingDownload.set(id, { resolve, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingDownload, id, opts.url);
   }
   /**
    * 0.4.0+: read declared IndexedDB keys from the user's signed-in
@@ -37681,12 +37857,8 @@ var FetchproxyServer = class {
     const pending = new Promise((resolve, reject) => {
       this.pendingIdb.set(id, { resolve, reject });
     });
-    if (this.hostHandle) {
-      await this.hostHandle.sendOwnInner(inner);
-    } else if (this.peerHandle) {
-      await this.peerHandle.sendInner(inner);
-    }
-    return pending;
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
   }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
@@ -38154,7 +38326,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "signupgenius-mcp",
-  version: "1.1.4",
+  version: "1.1.6",
   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>",
@@ -38191,7 +38363,7 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.8.0",
+    "@chrischall/mcp-utils": "^0.12.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -38199,7 +38371,7 @@ var package_default = {
     zod: "^4.4.3"
   },
   devDependencies: {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
     typescript: "^6.0.3",
@@ -38291,18 +38463,30 @@ var CookieSessionManager = class {
   inFlight;
   /** A cached *permanent* config error: once set, every `ensure` rethrows it. */
   permanentError;
+  /** When the current session was minted (login) or installed (seed) — for maxAgeMs. */
+  sessionAt = 0;
   loginFn;
   isExpiredFn;
   isPermanentErrorFn;
+  maxAgeMs;
+  now;
+  onReplayLoginErrorFn;
   constructor(opts) {
     this.loginFn = opts.login;
-    this.isExpiredFn = opts.isExpired;
+    this.isExpiredFn = opts.isExpired ?? (() => false);
     this.isPermanentErrorFn = opts.isPermanentError ?? (() => false);
+    this.maxAgeMs = opts.maxAgeMs;
+    this.now = opts.now ?? Date.now;
+    this.onReplayLoginErrorFn = opts.onReplayLoginError;
   }
   /** The current session, or `undefined` before the first successful login. */
   get current() {
     return this.session;
   }
+  /** True when {@link CookieSessionManagerOptions.maxAgeMs} says the session is too old. */
+  isStale() {
+    return this.maxAgeMs !== void 0 && this.now() - this.sessionAt >= this.maxAgeMs;
+  }
   /**
    * Return the current session, or single-flight a login if there is none.
    *
@@ -38311,10 +38495,16 @@ var CookieSessionManager = class {
    * the next call retries. A login error classified permanent by
    * {@link CookieSessionManagerOptions.isPermanentError} is cached and rethrown
    * on every later call; a transient error is not cached (next call retries).
+   * With {@link CookieSessionManagerOptions.maxAgeMs} set, a session past its
+   * TTL is invalidated first, so the call falls through to a (single-flight)
+   * re-login.
    */
   async ensure() {
-    if (this.session !== void 0)
-      return this.session;
+    if (this.session !== void 0) {
+      if (!this.isStale())
+        return this.session;
+      this.invalidate();
+    }
     if (this.permanentError !== void 0)
       throw this.permanentError;
     if (this.inFlight === void 0) {
@@ -38322,6 +38512,21 @@ var CookieSessionManager = class {
     }
     return this.inFlight;
   }
+  /**
+   * Install an externally-minted session (e.g. infinitecampus's CUPS linked-
+   * district discovery, which mints sessions outside {@link
+   * CookieSessionManagerOptions.login}). The seed becomes the current session
+   * with a fresh {@link CookieSessionManagerOptions.maxAgeMs} clock, and any
+   * in-flight login is DETACHED: its waiters still receive its result, but a
+   * late resolution will not overwrite the seed. A cached permanent config
+   * error is left intact — the login path is still misconfigured, and the next
+   * post-seed re-login should keep saying so.
+   */
+  seed(session) {
+    this.session = session;
+    this.sessionAt = this.now();
+    this.inFlight = void 0;
+  }
   /**
    * One login attempt. Self-clears `inFlight` on settle so a rejected login
    * never sticks, and stamps the resulting session only while it's still the
@@ -38333,8 +38538,10 @@ var CookieSessionManager = class {
     holder.p = (async () => {
       try {
         const session = await this.loginFn();
-        if (this.inFlight === holder.p)
+        if (this.inFlight === holder.p) {
           this.session = session;
+          this.sessionAt = this.now();
+        }
         return session;
       } catch (err) {
         if (this.isPermanentErrorFn(err))
@@ -38366,6 +38573,10 @@ var CookieSessionManager = class {
    * rather than looping. If the re-login itself fails, the original
    * (expired-looking) response is returned so the caller can surface a clean
    * sign-in error rather than the login failure.
+   *
+   * `call` resolves to `R` (the generic response type, default {@link Response});
+   * the manager passes it untouched to {@link CookieSessionManagerOptions.isExpired}
+   * and returns it untouched, so a custom transport type flows through cleanly.
    */
   async withSession(call) {
     const session = await this.ensure();
@@ -38377,7 +38588,8 @@ var CookieSessionManager = class {
     let fresh;
     try {
       fresh = await this.ensure();
-    } catch {
+    } catch (err) {
+      this.onReplayLoginErrorFn?.(err);
       return res;
     }
     return call(fresh);
@@ -38654,7 +38866,7 @@ async function parseEnvelope(res, context, normalize) {
   const msg = parsed?.message.join("; ");
   if (res.status === 401 || res.status === 403) throw new AuthError(res.status, msg);
   if (res.status === 404) throw new Error(`SignUpGenius 404 ${context}`);
-  if (res.status >= 500) throw new UnreachableError(res.status);
+  if (res.status >= 500) throw new UnreachableError("SignUpGenius", res.status);
   if (!res.ok) throw new Error(`SignUpGenius ${res.status} ${msg || res.statusText} for ${context}`);
   if (!parsed) {
     throw new Error(`SignUpGenius returned ${text === "" ? "empty" : "non-JSON"} body for ${context}`);
@@ -38672,37 +38884,17 @@ function parseJsonBody(text) {
     return null;
   }
 }
-var AuthError = class extends Error {
+var AuthError = class _AuthError extends McpToolError {
   constructor(status, detail) {
     super(
-      `SignUpGenius rejected the request (${status}). For key mode: check SIGNUPGENIUS_USER_KEY (it may be wrong, revoked, or the account no longer has Pro). For session mode: the session cookie may have been invalidated server-side.` + (detail ? ` (${detail})` : "")
+      `SignUpGenius rejected the request (${status}). ` + _AuthError.HINT + (detail ? ` (${detail})` : ""),
+      { hint: _AuthError.HINT }
     );
     this.status = status;
     this.name = "AuthError";
   }
   status;
-};
-var UnreachableError = class extends Error {
-  constructor(status) {
-    super(`SignUpGenius unreachable (status ${status})`);
-    this.status = status;
-    this.name = "UnreachableError";
-  }
-  status;
-};
-var ModeMismatchError = class extends Error {
-  constructor(currentMode, requiredMode, feature) {
-    super(
-      `${feature} requires ${requiredMode} mode but the server is running in ${currentMode} mode. ` + (requiredMode === "key" ? "Set SIGNUPGENIUS_USER_KEY (Pro subscription required for the documented v2/k API)." : "Set SIGNUPGENIUS_EMAIL + SIGNUPGENIUS_PASSWORD to enable this tool.")
-    );
-    this.currentMode = currentMode;
-    this.requiredMode = requiredMode;
-    this.feature = feature;
-    this.name = "ModeMismatchError";
-  }
-  currentMode;
-  requiredMode;
-  feature;
+  static HINT = "For key mode: check SIGNUPGENIUS_USER_KEY (it may be wrong, revoked, or the account no longer has Pro). For session mode: the session cookie may have been invalidated server-side.";
 };
 
 // src/tools/_shared.ts
@@ -39195,7 +39387,7 @@ bannerLines.push(
 );
 await runMcp({
   name: "signupgenius",
-  version: "1.1.4",
+  version: "1.1.6",
   // x-release-please-version
   banner: bannerLines.join("\n"),
   deps: client,

package/dist/client.js

@@ -1,4 +1,8 @@
+import { McpToolError, ModeMismatchError, UnreachableError } from '@chrischall/mcp-utils';
 import { CookieSessionManager } from '@chrischall/mcp-utils/session';
+// Re-exported so tools/tests keep importing the error types from the client
+// module (the shared classes live in @chrischall/mcp-utils since 0.10.x).
+export { ModeMismatchError, UnreachableError };
 import { sessionLogin as defaultSessionLogin } from './auth-session-login.js';
 /**
  * Detect a session that lapsed server-side. SignUpGenius signals expiry two
@@ -245,7 +249,7 @@ async function parseEnvelope(res, context, normalize) {
     if (res.status === 404)
         throw new Error(`SignUpGenius 404 ${context}`);
     if (res.status >= 500)
-        throw new UnreachableError(res.status);
+        throw new UnreachableError('SignUpGenius', res.status);
     if (!res.ok)
         throw new Error(`SignUpGenius ${res.status} ${msg || res.statusText} for ${context}`);
     if (!parsed) {
@@ -266,37 +270,21 @@ function parseJsonBody(text) {
         return null;
     }
 }
-export class AuthError extends Error {
+/**
+ * SignUpGenius rejected a request (401/403). Kept as a local class (rather
+ * than the shared `SessionNotAuthenticatedError`, whose fixed browser-sign-in
+ * message can't carry it) because the remediation is mode-dependent SUG
+ * guidance — surfaced as the `hint` per the `McpToolError` contract.
+ */
+export class AuthError extends McpToolError {
     status;
+    static HINT = 'For key mode: check SIGNUPGENIUS_USER_KEY (it may be wrong, revoked, or the account no longer has Pro). ' +
+        'For session mode: the session cookie may have been invalidated server-side.';
     constructor(status, detail) {
         super(`SignUpGenius rejected the request (${status}). ` +
-            'For key mode: check SIGNUPGENIUS_USER_KEY (it may be wrong, revoked, or the account no longer has Pro). ' +
-            'For session mode: the session cookie may have been invalidated server-side.' +
-            (detail ? ` (${detail})` : ''));
+            AuthError.HINT +
+            (detail ? ` (${detail})` : ''), { hint: AuthError.HINT });
         this.status = status;
         this.name = 'AuthError';
     }
 }
-export class UnreachableError extends Error {
-    status;
-    constructor(status) {
-        super(`SignUpGenius unreachable (status ${status})`);
-        this.status = status;
-        this.name = 'UnreachableError';
-    }
-}
-export class ModeMismatchError extends Error {
-    currentMode;
-    requiredMode;
-    feature;
-    constructor(currentMode, requiredMode, feature) {
-        super(`${feature} requires ${requiredMode} mode but the server is running in ${currentMode} mode. ` +
-            (requiredMode === 'key'
-                ? 'Set SIGNUPGENIUS_USER_KEY (Pro subscription required for the documented v2/k API).'
-                : 'Set SIGNUPGENIUS_EMAIL + SIGNUPGENIUS_PASSWORD to enable this tool.'));
-        this.currentMode = currentMode;
-        this.requiredMode = requiredMode;
-        this.feature = feature;
-        this.name = 'ModeMismatchError';
-    }
-}

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.4', // x-release-please-version
+    version: '1.1.6', // x-release-please-version
     banner: bannerLines.join('\n'),
     deps: client,
     tools: [

package/dist/tools/reports.js

@@ -7,8 +7,9 @@ const reportArgs = z.object({
  * Report endpoints are Pro-only. The session-mode v3 web API has no
  * equivalent — only the sign-up owner can pull report data, and the v3 paths
  * for it were not discovered during recon. We still register the tools so
- * Claude knows they exist, but in session mode they fail fast with a
- * ModeMismatchError pointing the user at SIGNUPGENIUS_USER_KEY.
+ * Claude knows they exist, but in session mode they fail fast with the shared
+ * ModeMismatchError, whose hint says "Switch to key mode to use {tool}." —
+ * the SIGNUPGENIUS_USER_KEY pointer lives in each tool's description below.
  */
 export function registerReportTools(server, client) {
     const register = (toolName, path, blurb) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signupgenius-mcp",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "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.8.0",
+    "@chrischall/mcp-utils": "^0.12.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -45,7 +45,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
     "typescript": "^6.0.3",

package/server.json

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