infinitecampus-mcp 2.4.0 → 2.4.3

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Infinite Campus (Campus Parent) — grades, attendance, assignments, messages, documents",
-    "version": "2.4.0"
+    "version": "2.4.3"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Infinite Campus",
       "source": "./",
       "description": "Infinite Campus (Campus Parent) MCP server for Claude — grades, attendance, assignments, messages, and documents via natural language",
-      "version": "2.4.0",
+      "version": "2.4.3",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "infinitecampus-mcp",
   "displayName": "Infinite Campus",
-  "version": "2.4.0",
+  "version": "2.4.3",
   "description": "Infinite Campus (Campus Parent) MCP server for Claude — grades, attendance, assignments, messages, and documents",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -42,7 +42,7 @@ Tools that the harness will gate as write/IO operations: `ic_download_document`.
    IC_PASSWORD=...
    IC_NAME=Springfield           # optional, defaults to IC_DISTRICT
    ```
-2. **fetchproxy fallback (no password needed).** Set only `IC_BASE_URL` + `IC_DISTRICT` (still required so the MCP knows which host to talk to and which district to dispatch on), then install the [fetchproxy 0.3.0 extension](https://github.com/chrischall/fetchproxy) (Chrome Web Store / Safari `.dmg`) and sign into your IC portal once. The MCP reads the `JSESSIONID` (HttpOnly) + `XSRF-TOKEN` cookies on startup and goes direct-to-API from Node thereafter — the extension is **not** in the request hot path.
+2. **fetchproxy fallback (no password needed).** Set only `IC_BASE_URL` + `IC_DISTRICT` (still required so the MCP knows which host to talk to and which district to dispatch on), then install the [fetchproxy 0.3.0 extension](https://github.com/chrischall/fetchproxy) (Chrome Web Store / Safari `.dmg`) and sign into your IC portal once. The MCP reads the `JSESSIONID` (HttpOnly) + `XSRF-TOKEN` cookies from that tab and goes direct-to-API from Node thereafter — the extension is **not** in the request hot path. The read is repeated whenever the session lapses (JSESSIONID is a servlet session with a short idle timeout), so you stay signed in without restarting the MCP.
 
 Set `IC_DISABLE_FETCHPROXY=1` to opt out of the fallback (turns missing credentials into a hard error — useful in headless CI).
 

package/dist/auth.js

@@ -46,7 +46,7 @@
 //   - `@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 { createSessionLifter } from '@fetchproxy/bootstrap';
 import { classifyBridgeError } from '@chrischall/mcp-utils/fetchproxy';
 import { parseBoolEnv } from '@chrischall/mcp-utils';
 import { loadAccount } from './config.js';
@@ -71,65 +71,103 @@ export async function resolveAuth() {
         return { account, source: 'env' };
     }
     // ── Path 2: fetchproxy fallback.
+    //
+    // NOTE: the browser is NOT read here. `resolveAuth()` runs once at process
+    // start; the lift is handed to the client as `refresh` and runs lazily on
+    // the first request and again on every expiry. Two bugs this avoids:
+    //
+    //   * The lapsed-session dead end. JSESSIONID is a servlet session with a
+    //     short idle timeout. A cookie captured at boot left the server
+    //     unauthenticated the moment it lapsed, with no way back — the account
+    //     has empty creds, so verify.jsp is not an option.
+    //   * The sticky startup failure. A lift that failed at boot (user not yet
+    //     signed in) was cached for the life of the process, so signing in
+    //     afterwards changed nothing.
     if (!fetchproxyDisabled()) {
-        try {
-            const host = new URL(account.baseUrl).hostname;
-            const session = await bootstrap({
-                serverName: pkg.name,
-                version: pkg.version,
-                // IC tenants live on per-district hosts (campus.<district>.org,
-                // <district>.infinitecampus.org, etc.). Declare just this host
-                // — each district is its own root, no wildcard needed.
-                domains: [host],
-                declare: {
-                    // JSESSIONID is HttpOnly (chrome.cookies.get sees it; the
-                    // security gate is the declared key list). XSRF-TOKEN is
-                    // non-HttpOnly because the page JS reads it back and echoes
-                    // it on every state-changing call as the X-XSRF-TOKEN header.
-                    cookies: ['JSESSIONID', 'XSRF-TOKEN'],
-                    localStorage: [],
-                    sessionStorage: [],
-                    captureHeaders: [],
-                },
-            });
-            const jsessionid = session.cookies['JSESSIONID'];
-            const xsrf = session.cookies['XSRF-TOKEN'];
-            if (!jsessionid) {
-                throw new Error(`JSESSIONID cookie not found on ${host}. ` +
-                    'Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.');
-            }
-            if (!xsrf) {
-                throw new Error(`XSRF-TOKEN cookie not found on ${host}. ` +
-                    'Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.');
-            }
-            return {
-                account,
-                preloaded: {
-                    cookieHeader: `JSESSIONID=${jsessionid}; XSRF-TOKEN=${xsrf}`,
-                    xsrfToken: xsrf,
-                },
-                source: 'fetchproxy',
-            };
-        }
-        catch (e) {
-            // 0.8.0+ typed-error discrimination. The fetchproxy server already
-            // retries once on SW eviction (bridgeReviveDelayMs=2000 default), so
-            // a thrown FetchproxyBridgeDownError means the retry also failed —
-            // the extension's service worker is genuinely down and the user
-            // needs to wake it. The `.hint` is the actionable copy
-            // ("click the extension toolbar icon...") that we'd otherwise have
-            // to hand-write here. Surface it verbatim so users in path 2 get
-            // the same self-service guidance as path 3.
-            if (classifyBridgeError(e) === 'bridge_down') {
-                const downErr = e;
-                throw new Error(`IC auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`);
-            }
-            const msg = e instanceof Error ? e.message : String(e);
-            throw new Error('IC auth: no IC_USERNAME/IC_PASSWORD set, and fetchproxy fallback failed: ' + msg);
-        }
+        return {
+            account,
+            refresh: () => liftBrowserSession(account),
+            source: 'fetchproxy',
+        };
     }
     // ── Path 3: nothing configured and fetchproxy explicitly disabled.
     throw new Error('IC auth: set IC_USERNAME + IC_PASSWORD, ' +
         'or install the fetchproxy extension and sign into your IC portal ' +
         '(unset IC_DISABLE_FETCHPROXY if it is set).');
 }
+/**
+ * One lifter per host, built lazily and reused.
+ *
+ * Unlike most MCPs the declared scope is not static — IC tenants live on
+ * per-district hosts — so the lifter cannot be a module-level constant.
+ * Caching by host still matters: `createSessionLifter` single-flights
+ * concurrent calls, and that only helps if renewals share ONE lifter instead
+ * of constructing a fresh one each time.
+ */
+const liftersByHost = new Map();
+function lifterFor(host) {
+    let lift = liftersByHost.get(host);
+    if (!lift) {
+        lift = createSessionLifter({
+            serverName: pkg.name,
+            version: pkg.version,
+            // IC tenants live on per-district hosts (campus.<district>.org,
+            // <district>.infinitecampus.org, etc.). Declare just this host
+            // — each district is its own root, no wildcard needed.
+            domains: [host],
+            declare: {
+                // JSESSIONID is HttpOnly (chrome.cookies.get sees it; the
+                // security gate is the declared key list). XSRF-TOKEN is
+                // non-HttpOnly because the page JS reads it back and echoes
+                // it on every state-changing call as the X-XSRF-TOKEN header.
+                cookies: ['JSESSIONID', 'XSRF-TOKEN'],
+                localStorage: [],
+                sessionStorage: [],
+                captureHeaders: [],
+            },
+        });
+        liftersByHost.set(host, lift);
+    }
+    return lift;
+}
+/**
+ * Lift a fresh IC session out of the user's signed-in portal tab.
+ *
+ * Runs on every login/renewal, not once at startup — fetchproxy is not in the
+ * request hot path, only the renewal path.
+ */
+async function liftBrowserSession(account) {
+    try {
+        const host = new URL(account.baseUrl).hostname;
+        const session = await lifterFor(host)();
+        const jsessionid = session.cookies['JSESSIONID'];
+        const xsrf = session.cookies['XSRF-TOKEN'];
+        if (!jsessionid) {
+            throw new Error(`JSESSIONID cookie not found on ${host}. ` +
+                'Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.');
+        }
+        if (!xsrf) {
+            throw new Error(`XSRF-TOKEN cookie not found on ${host}. ` +
+                'Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.');
+        }
+        return {
+            cookieHeader: `JSESSIONID=${jsessionid}; XSRF-TOKEN=${xsrf}`,
+            xsrfToken: xsrf,
+        };
+    }
+    catch (e) {
+        // 0.8.0+ typed-error discrimination. The fetchproxy server already
+        // retries once on SW eviction (bridgeReviveDelayMs=2000 default), so
+        // a thrown FetchproxyBridgeDownError means the retry also failed —
+        // the extension's service worker is genuinely down and the user
+        // needs to wake it. The `.hint` is the actionable copy
+        // ("click the extension toolbar icon...") that we'd otherwise have
+        // to hand-write here.
+        if (classifyBridgeError(e) === 'bridge_down') {
+            const downErr = e;
+            throw new Error(`IC auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`);
+        }
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error('IC auth: no IC_USERNAME/IC_PASSWORD set, and fetchproxy lift failed: ' + msg);
+    }
+}

package/dist/bundle.js

@@ -3776,6 +3776,7 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
+    var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
     function getParseError(parsed, matches) {
       if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
         return 'URI path must start with "/" when authority is present.';
@@ -3805,6 +3806,11 @@ var require_fast_uri = __commonJS({
           uri = "//" + uri;
         }
       }
+      const authorityMatch = uri.match(AUTHORITY_PREFIX);
+      if (authorityMatch !== null && authorityMatch[1].indexOf("\\") !== -1) {
+        parsed.error = "URI authority must not contain a literal backslash.";
+        malformedAuthorityOrPort = true;
+      }
       const matches = uri.match(URI_PARSE);
       if (matches) {
         parsed.scheme = matches[1];
@@ -3848,7 +3854,7 @@ var require_fast_uri = __commonJS({
         if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport)) {
           if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
             try {
-              parsed.host = URL.domainToASCII(parsed.host.toLowerCase());
+              parsed.host = new URL("http://" + parsed.host).hostname;
             } catch (e) {
               parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e;
             }
@@ -7693,6 +7699,7 @@ var require_receiver = __commonJS({
         this._opcode = 0;
         this._totalPayloadLength = 0;
         this._messageLength = 0;
+        this._numFragments = 0;
         this._fragments = [];
         this._errored = false;
         this._loop = false;
@@ -8043,23 +8050,23 @@ var require_receiver = __commonJS({
           this.controlMessage(data, cb);
           return;
         }
+        if (this._maxFragments > 0 && ++this._numFragments > this._maxFragments) {
+          const error51 = this.createError(
+            RangeError,
+            "Too many message fragments",
+            false,
+            1008,
+            "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+          );
+          cb(error51);
+          return;
+        }
         if (this._compressed) {
           this._state = INFLATING;
           this.decompress(data, cb);
           return;
         }
         if (data.length) {
-          if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
-            const error51 = this.createError(
-              RangeError,
-              "Too many message fragments",
-              false,
-              1008,
-              "WS_ERR_TOO_MANY_BUFFERED_PARTS"
-            );
-            cb(error51);
-            return;
-          }
           this._messageLength = this._totalPayloadLength;
           this._fragments.push(data);
         }
@@ -8089,17 +8096,6 @@ var require_receiver = __commonJS({
               cb(error51);
               return;
             }
-            if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
-              const error51 = this.createError(
-                RangeError,
-                "Too many message fragments",
-                false,
-                1008,
-                "WS_ERR_TOO_MANY_BUFFERED_PARTS"
-              );
-              cb(error51);
-              return;
-            }
             this._fragments.push(buf);
           }
           this.dataMessage(cb);
@@ -8122,6 +8118,7 @@ var require_receiver = __commonJS({
         this._totalPayloadLength = 0;
         this._messageLength = 0;
         this._fragmented = 0;
+        this._numFragments = 0;
         this._fragments = [];
         if (this._opcode === 2) {
           let data;
@@ -9622,8 +9619,8 @@ var require_websocket = __commonJS({
         autoPong: true,
         closeTimeout: CLOSE_TIMEOUT,
         protocolVersion: protocolVersions[1],
-        maxBufferedChunks: 1024 * 1024,
-        maxFragments: 128 * 1024,
+        maxBufferedChunks: 256 * 1024,
+        maxFragments: 16 * 1024,
         maxPayload: 100 * 1024 * 1024,
         skipUTF8Validation: false,
         perMessageDeflate: true,
@@ -10210,9 +10207,9 @@ var require_websocket_server = __commonJS({
        *     called
        * @param {Function} [options.handleProtocols] A hook to handle protocols
        * @param {String} [options.host] The hostname where to bind the server
-       * @param {Number} [options.maxBufferedChunks=1048576] The maximum number of
+       * @param {Number} [options.maxBufferedChunks=262144] The maximum number of
        *     buffered data chunks
-       * @param {Number} [options.maxFragments=131072] The maximum number of message
+       * @param {Number} [options.maxFragments=16384] The maximum number of message
        *     fragments
        * @param {Number} [options.maxPayload=104857600] The maximum allowed message
        *     size
@@ -10235,8 +10232,8 @@ var require_websocket_server = __commonJS({
         options = {
           allowSynchronousEvents: true,
           autoPong: true,
-          maxBufferedChunks: 1024 * 1024,
-          maxFragments: 128 * 1024,
+          maxBufferedChunks: 256 * 1024,
+          maxFragments: 16 * 1024,
           maxPayload: 100 * 1024 * 1024,
           skipUTF8Validation: false,
           perMessageDeflate: false,
@@ -26732,17 +26729,33 @@ function normalizeObjectSchema(schema) {
   }
   return void 0;
 }
+function getDotPath(path) {
+  if (path.length === 0) {
+    return "object root";
+  }
+  return path.reduce((acc, seg, index) => {
+    if (index === 0) {
+      return String(seg);
+    }
+    if (typeof seg === "number") {
+      return `${acc}[${seg}]`;
+    }
+    return `${acc}.${seg}`;
+  }, "");
+}
 function getParseErrorMessage(error51) {
   if (error51 && typeof error51 === "object") {
+    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
+      return error51.issues.map((i) => {
+        if (!i.path?.length) {
+          return i.message;
+        }
+        return `${i.message} at ${getDotPath(i.path)}`;
+      }).join("\n");
+    }
     if ("message" in error51 && typeof error51.message === "string") {
       return error51.message;
     }
-    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
-      const firstIssue = error51.issues[0];
-      if (firstIssue && typeof firstIssue === "object" && "message" in firstIssue) {
-        return String(firstIssue.message);
-      }
-    }
     try {
       return JSON.stringify(error51);
     } catch {
@@ -33357,16 +33370,7 @@ var Server = class extends Protocol {
     if (!methodSchema) {
       throw new Error("Schema is missing a method literal");
     }
-    let methodValue;
-    if (isZ4Schema(methodSchema)) {
-      const v4Schema = methodSchema;
-      const v4Def = v4Schema._zod?.def;
-      methodValue = v4Def?.value ?? v4Schema.value;
-    } else {
-      const v3Schema = methodSchema;
-      const legacyDef = v3Schema._def;
-      methodValue = legacyDef?.value ?? v3Schema.value;
-    }
+    const methodValue = getLiteralValue(methodSchema);
     if (typeof methodValue !== "string") {
       throw new Error("Schema method literal must be a string");
     }
@@ -34554,8 +34558,17 @@ var EMPTY_COMPLETION_RESULT = {
 import process3 from "node:process";
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 var ReadBuffer = class {
+  constructor(options) {
+    this._maxBufferSize = options?.maxBufferSize ?? STDIO_DEFAULT_MAX_BUFFER_SIZE;
+  }
   append(chunk2) {
+    const newSize = (this._buffer?.length ?? 0) + chunk2.length;
+    if (newSize > this._maxBufferSize) {
+      this.clear();
+      throw new Error(`ReadBuffer exceeded maximum size of ${this._maxBufferSize} bytes`);
+    }
     this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk2]) : chunk2;
   }
   readMessage() {
@@ -34583,18 +34596,24 @@ function serializeMessage(message) {
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 var StdioServerTransport = class {
-  constructor(_stdin = process3.stdin, _stdout = process3.stdout) {
+  constructor(_stdin = process3.stdin, _stdout = process3.stdout, options) {
     this._stdin = _stdin;
     this._stdout = _stdout;
-    this._readBuffer = new ReadBuffer();
     this._started = false;
     this._ondata = (chunk2) => {
-      this._readBuffer.append(chunk2);
-      this.processReadBuffer();
+      try {
+        this._readBuffer.append(chunk2);
+        this.processReadBuffer();
+      } catch (error51) {
+        this.onerror?.(error51);
+        this.close().catch(() => {
+        });
+      }
     };
     this._onerror = (error51) => {
       this.onerror?.(error51);
     };
+    this._readBuffer = new ReadBuffer({ maxBufferSize: options?.maxBufferSize });
   }
   /**
    * Starts listening for messages on stdin.
@@ -34846,7 +34865,8 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_redirect",
   "read_indexed_db",
   "read_dom",
-  "download"
+  "download",
+  "graphql"
 ]);
 
 // node_modules/@fetchproxy/protocol/dist/mcp-id.js
@@ -35149,6 +35169,7 @@ function assertIndexedDbScopesArray(value, label) {
 }
 var DOM_SELECTOR_RE = /^[^-]{1,512}$/;
 var DOM_ATTRIBUTE_RE = /^[A-Za-z_:][A-Za-z0-9_:.\-]{0,127}$/;
+var GRAPHQL_OP_NAME_RE = /^[_A-Za-z][_0-9A-Za-z]{0,127}$/;
 function assertDomSelectorsArray(value, label) {
   if (!Array.isArray(value)) {
     throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
@@ -35185,6 +35206,37 @@ function assertDomSelectorsArray(value, label) {
     }
   }
 }
+function assertGraphqlOpsArray(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.operationName === void 0) {
+      throw new ProtocolError(`${label}[${i}].operationName: 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.operationName !== "string" || !GRAPHQL_OP_NAME_RE.test(entry.operationName)) {
+      throw new ProtocolError(`${label}[${i}].operationName: invalid ${JSON.stringify(entry.operationName)}`);
+    }
+    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 !== "operationName") {
+        throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
+      }
+    }
+  }
+}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35263,6 +35315,9 @@ function validateHello(raw) {
     if (raw.domSelectors !== void 0) {
       assertDomSelectorsArray(raw.domSelectors, "hello.domSelectors");
     }
+    if (raw.graphqlOps !== void 0) {
+      assertGraphqlOpsArray(raw.graphqlOps, "hello.graphqlOps");
+    }
     assertBase64(raw.identityX25519Pub, "hello.identityX25519Pub");
     assertBase64(raw.identityEd25519Pub, "hello.identityEd25519Pub");
     assertBase64(raw.sessionNonce, "hello.sessionNonce");
@@ -35512,6 +35567,28 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
+  if (raw.op === "graphql_query") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.name === void 0)
+      throw new ProtocolError("inner.init.name: missing");
+    if (raw.init.variables === void 0) {
+      throw new ProtocolError("inner.init.variables: missing");
+    }
+    assertString(raw.init.name, "inner.init.name");
+    if (raw.init.name.length === 0) {
+      throw new ProtocolError("inner.init.name: must be non-empty");
+    }
+    assertObject(raw.init.variables, "inner.init.variables");
+    if (raw.init.tabUrl !== void 0) {
+      assertString(raw.init.tabUrl, "inner.init.tabUrl");
+    }
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "name" && k !== "variables" && k !== "tabUrl") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on graphql_query`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "download") {
     assertObject(raw.init, "inner.init");
     if (raw.init.url === void 0) {
@@ -35537,7 +35614,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", "read_dom", "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", "graphql_query"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35568,6 +35645,10 @@ function assertStringMap(value, label) {
     }
   }
 }
+var KNOWN_RESPONSE_OPS = /* @__PURE__ */ new Set([
+  ...KNOWN_CAPABILITIES,
+  "graphql_query"
+]);
 function validateInnerResponse(raw) {
   assertPositiveInt(raw.id, "inner.id");
   if (raw.ok === true) {
@@ -35629,6 +35710,13 @@ function validateInnerResponse(raw) {
       assertStringMap(raw.values, "inner.values");
       return raw;
     }
+    if (op === "graphql_query") {
+      if (raw.data === void 0) {
+        throw new ProtocolError("inner.data: missing on graphql_query response");
+      }
+      assertObject(raw.data, "inner.data");
+      return raw;
+    }
     if (op === "download") {
       assertObject(raw.value, "inner.value");
       assertString(raw.value.path, "inner.value.path");
@@ -35653,7 +35741,7 @@ function validateInnerResponse(raw) {
   if (raw.ok === false) {
     assertString(raw.error, "inner.error");
     if (raw.op !== void 0) {
-      if (typeof raw.op !== "string" || !KNOWN_CAPABILITIES.has(raw.op)) {
+      if (typeof raw.op !== "string" || !KNOWN_RESPONSE_OPS.has(raw.op)) {
         throw new ProtocolError(`inner.op: unknown response op ${JSON.stringify(raw.op)}`);
       }
     }
@@ -35845,11 +35933,33 @@ async function sealInnerFrame(sessionKey, mcpId, seq, inner) {
   };
 }
 async function openEncryptedFrame(sessionKey, frame) {
-  const iv = fromB64(frame.iv);
-  const ct = fromB64(frame.ciphertext);
-  const pt = await aesGcmOpen(sessionKey, iv, ct);
-  const parsed = JSON.parse(dec.decode(pt));
-  return validateInnerFrame(parsed);
+  const result = await openEncryptedFrameDetailed(sessionKey, frame);
+  if (result.stage === "ok")
+    return result.inner;
+  throw result.error instanceof Error ? result.error : new Error(String(result.error));
+}
+async function openEncryptedFrameDetailed(sessionKey, frame) {
+  let pt;
+  try {
+    const iv = fromB64(frame.iv);
+    const ct = fromB64(frame.ciphertext);
+    pt = await aesGcmOpen(sessionKey, iv, ct);
+  } catch (error51) {
+    return { stage: "decrypt-failed", error: error51 };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(dec.decode(pt));
+  } catch (error51) {
+    return { stage: "validation-failed", error: error51, recoveredId: void 0 };
+  }
+  try {
+    const inner = validateInnerFrame(parsed);
+    return { stage: "ok", inner };
+  } catch (error51) {
+    const recoveredId = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && typeof parsed.id === "number" && Number.isInteger(parsed.id) && parsed.id > 0 ? parsed.id : void 0;
+    return { stage: "validation-failed", error: error51, recoveredId };
+  }
 }
 
 // node_modules/@fetchproxy/server/dist/election.js
@@ -35975,6 +36085,12 @@ async function buildServerHello(opts) {
       ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
     }));
   }
+  if (opts.graphqlOps && opts.graphqlOps.length > 0) {
+    hello.graphqlOps = opts.graphqlOps.map((d) => ({
+      name: d.name,
+      operationName: d.operationName
+    }));
+  }
   return hello;
 }
 
@@ -36065,7 +36181,8 @@ async function startHost(opts) {
     indexedDbScopes: opts.ownIndexedDbScopes,
     localStoragePointers: opts.ownLocalStoragePointers,
     sessionStoragePointers: opts.ownSessionStoragePointers,
-    domSelectors: opts.ownDomSelectors
+    domSelectors: opts.ownDomSelectors,
+    graphqlOps: opts.ownGraphqlOps
   });
   const ownSessionNonce = fromB64(ownHello.sessionNonce);
   let extensionWs = null;
@@ -36302,7 +36419,8 @@ async function startPeer(opts) {
     indexedDbScopes: opts.indexedDbScopes,
     domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
-    sessionStoragePointers: opts.sessionStoragePointers
+    sessionStoragePointers: opts.sessionStoragePointers,
+    graphqlOps: opts.graphqlOps
   });
   const sessionNonce = fromB64(hello.sessionNonce);
   ws.send(JSON.stringify(hello));
@@ -36346,10 +36464,20 @@ async function startPeer(opts) {
           return;
         if (!session.acceptInboundSeq(frame.seq))
           return;
-        try {
-          const inner = await openEncryptedFrame(session.sessionKey, frame);
-          innerListeners.forEach((cb) => cb(inner));
-        } catch {
+        const result = await openEncryptedFrameDetailed(session.sessionKey, frame);
+        if (result.stage === "ok") {
+          innerListeners.forEach((cb) => cb(result.inner));
+        } else if (result.stage === "decrypt-failed") {
+        } else {
+          console.error("[fetchproxy] peer: received a frame that decrypted OK but failed validation:", result.error);
+          if (result.recoveredId !== void 0) {
+            innerListeners.forEach((cb) => cb({
+              type: "response",
+              id: result.recoveredId,
+              ok: false,
+              error: `malformed response failed protocol validation: ${String(result.error)}`
+            }));
+          }
         }
       }
     } catch (e) {
@@ -36626,6 +36754,10 @@ var FetchproxyServer = class {
   pendingIdb = /* @__PURE__ */ new Map();
   // download awaiters resolve the saved-file metadata (path + size + mime).
   pendingDownload = /* @__PURE__ */ new Map();
+  // 1.x+: graphql_query awaiters resolve the GraphQL `data` object. Its
+  // shape is operation-specific, so the awaiter resolves `unknown` and the
+  // caller narrows.
+  pendingGraphql = /* @__PURE__ */ new Map();
   mcpId = null;
   identity = null;
   // 0.5.3+: in-flight role-election / handle-start promise. Set the
@@ -36713,6 +36845,10 @@ var FetchproxyServer = class {
         selector: d.selector,
         ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
       })),
+      graphqlOps: (opts.graphqlOps ?? []).map((d) => ({
+        name: d.name,
+        operationName: d.operationName
+      })),
       // 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
@@ -36834,6 +36970,7 @@ var FetchproxyServer = class {
         ownLocalStoragePointers: this.opts.localStoragePointers,
         ownSessionStoragePointers: this.opts.sessionStoragePointers,
         ownDomSelectors: this.opts.domSelectors,
+        ownGraphqlOps: this.opts.graphqlOps,
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
@@ -36862,7 +36999,8 @@ var FetchproxyServer = class {
         indexedDbScopes: this.opts.indexedDbScopes,
         localStoragePointers: this.opts.localStoragePointers,
         sessionStoragePointers: this.opts.sessionStoragePointers,
-        domSelectors: this.opts.domSelectors
+        domSelectors: this.opts.domSelectors,
+        graphqlOps: this.opts.graphqlOps
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
       this.peerHandle.onRenegotiate(() => {
@@ -37068,6 +37206,7 @@ var FetchproxyServer = class {
         this.pendingRedirect.delete(id);
         this.pendingDownload.delete(id);
         this.pendingIdb.delete(id);
+        this.pendingGraphql.delete(id);
       }
       throw err;
     }
@@ -37877,6 +38016,52 @@ var FetchproxyServer = class {
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
   }
+  /**
+   * 1.x+: run a declared GraphQL operation through the page's own Apollo
+   * client (`window.__APOLLO_CLIENT__`) in the signed-in tab's MAIN world.
+   * Requires `'graphql'` in capabilities AND `name` to match a declared
+   * `graphqlOps` entry. The extension resolves `name` → `operationName` →
+   * the live DocumentNode the page already observed, then invokes
+   * `client.query({ query, variables })` — the site's own request path, so
+   * per-request bot telemetry (Akamai etc.) runs automatically.
+   *
+   * Returns the GraphQL `data` object on success (shape is
+   * operation-specific; the caller narrows). Throws a plain `Error` on
+   * developer mistakes (undeclared capability, undeclared name) and a
+   * descriptive `Error` on the `ok:false` bridge path — which includes the
+   * typed "operation not yet observed on this tab" case (open the site's
+   * page and retry).
+   */
+  async graphqlQuery(opts) {
+    if (!this.opts.capabilities.includes("graphql")) {
+      throw new Error('FetchproxyServer.graphqlQuery(): MCP did not declare "graphql" in capabilities');
+    }
+    if (typeof opts.name !== "string" || opts.name.length === 0) {
+      throw new Error("FetchproxyServer.graphqlQuery: opts.name must be a non-empty string");
+    }
+    const declaredNames = this.opts.graphqlOps.map((d) => d.name);
+    if (!declaredNames.includes(opts.name)) {
+      throw new Error(`FetchproxyServer.graphqlQuery: operation ${JSON.stringify(opts.name)} not in declared graphqlOps [${declaredNames.map((n) => JSON.stringify(n)).join(", ")}]`);
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "graphql_query",
+      init: {
+        name: opts.name,
+        variables: opts.variables,
+        ...opts.tabUrl !== void 0 ? { tabUrl: opts.tabUrl } : {}
+      }
+    };
+    const pending = new Promise((resolve, reject) => {
+      this.pendingGraphql.set(id, { resolve, reject });
+    });
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingGraphql, id, opts.name);
+  }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
     if (undeclared.length > 0) {
@@ -38014,6 +38199,20 @@ var FetchproxyServer = class {
       }
       return;
     }
+    const graphqlCb = this.pendingGraphql.get(inner.id);
+    if (graphqlCb) {
+      this.pendingGraphql.delete(inner.id);
+      if (inner.ok) {
+        if (inner.op === "graphql_query") {
+          graphqlCb.resolve(inner.data);
+        } else {
+          graphqlCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on graphql_query awaiter`));
+        }
+      } else {
+        graphqlCb.reject(new FetchproxyProtocolError(inner.error));
+      }
+      return;
+    }
     const cookiesCb = this.pendingReadCookies.get(inner.id);
     if (cookiesCb) {
       this.pendingReadCookies.delete(inner.id);
@@ -38065,6 +38264,9 @@ var FetchproxyServer = class {
     for (const { reject } of this.pendingDownload.values())
       reject(err);
     this.pendingDownload.clear();
+    for (const { reject } of this.pendingGraphql.values())
+      reject(err);
+    this.pendingGraphql.clear();
   }
   /**
    * 0.5.2+: read the current pair-pending pair code from whichever handle
@@ -38118,7 +38320,20 @@ var FetchproxyServer = class {
 
 // node_modules/@fetchproxy/bootstrap/dist/index.js
 var defaultFactory = (opts) => new FetchproxyServer(opts);
-async function bootstrap(opts) {
+function createSessionLifter(opts) {
+  let inFlight = null;
+  return () => {
+    if (inFlight)
+      return inFlight;
+    const p = runOneLift(opts).finally(() => {
+      if (inFlight === p)
+        inFlight = null;
+    });
+    inFlight = p;
+    return p;
+  };
+}
+async function runOneLift(opts) {
   const envVar = opts.serverName.toUpperCase().replace(/[^A-Z0-9]/g, "_").replace(/^_+/, "") + "_DISABLE_FETCHPROXY";
   const envVal = process.env[envVar];
   if (envVal !== void 0 && envVal !== "" && envVal !== "0" && envVal !== "false") {
@@ -38245,12 +38460,18 @@ async function bootstrap(opts) {
       });
       indexedDbBucket[`${d.database}/${d.store}`] = values;
     }
+    const absent = (declared, got) => declared.filter((k) => !(k in got));
     return {
       cookies,
       localStorage,
       sessionStorage,
       capturedHeaders,
-      indexedDb: indexedDbBucket
+      indexedDb: indexedDbBucket,
+      missing: {
+        cookies: absent(opts.declare.cookies, cookies),
+        localStorage: absent(opts.declare.localStorage, localStorage),
+        sessionStorage: absent(opts.declare.sessionStorage, sessionStorage)
+      }
     };
   } finally {
     try {
@@ -38311,7 +38532,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "infinitecampus-mcp",
-  version: "2.4.0",
+  version: "2.4.3",
   mcpName: "io.github.chrischall/infinitecampus-mcp",
   description: "Infinite Campus (Campus Parent) MCP server \u2014 multi-district read + message/document write",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -38353,9 +38574,9 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.13.0",
-    "@fetchproxy/bootstrap": "^1.0.0",
-    "@fetchproxy/server": "^1.0.0",
+    "@chrischall/mcp-utils": "^0.14.0",
+    "@fetchproxy/bootstrap": "^1.9.1",
+    "@fetchproxy/server": "^1.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     "node-html-parser": "^9.0.0",
@@ -38380,62 +38601,74 @@ async function resolveAuth() {
     return { account: account2, source: "env" };
   }
   if (!fetchproxyDisabled()) {
-    try {
-      const host = new URL(account2.baseUrl).hostname;
-      const session = await bootstrap({
-        serverName: package_default.name,
-        version: package_default.version,
-        // IC tenants live on per-district hosts (campus.<district>.org,
-        // <district>.infinitecampus.org, etc.). Declare just this host
-        // — each district is its own root, no wildcard needed.
-        domains: [host],
-        declare: {
-          // JSESSIONID is HttpOnly (chrome.cookies.get sees it; the
-          // security gate is the declared key list). XSRF-TOKEN is
-          // non-HttpOnly because the page JS reads it back and echoes
-          // it on every state-changing call as the X-XSRF-TOKEN header.
-          cookies: ["JSESSIONID", "XSRF-TOKEN"],
-          localStorage: [],
-          sessionStorage: [],
-          captureHeaders: []
-        }
-      });
-      const jsessionid = session.cookies["JSESSIONID"];
-      const xsrf = session.cookies["XSRF-TOKEN"];
-      if (!jsessionid) {
-        throw new Error(
-          `JSESSIONID cookie not found on ${host}. Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.`
-        );
-      }
-      if (!xsrf) {
-        throw new Error(
-          `XSRF-TOKEN cookie not found on ${host}. Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.`
-        );
-      }
-      return {
-        account: account2,
-        preloaded: {
-          cookieHeader: `JSESSIONID=${jsessionid}; XSRF-TOKEN=${xsrf}`,
-          xsrfToken: xsrf
-        },
-        source: "fetchproxy"
-      };
-    } catch (e) {
-      if (classifyBridgeError(e) === "bridge_down") {
-        const downErr = e;
-        throw new Error(
-          `IC auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
-        );
+    return {
+      account: account2,
+      refresh: () => liftBrowserSession(account2),
+      source: "fetchproxy"
+    };
+  }
+  throw new Error(
+    "IC auth: set IC_USERNAME + IC_PASSWORD, or install the fetchproxy extension and sign into your IC portal (unset IC_DISABLE_FETCHPROXY if it is set)."
+  );
+}
+var liftersByHost = /* @__PURE__ */ new Map();
+function lifterFor(host) {
+  let lift = liftersByHost.get(host);
+  if (!lift) {
+    lift = createSessionLifter({
+      serverName: package_default.name,
+      version: package_default.version,
+      // IC tenants live on per-district hosts (campus.<district>.org,
+      // <district>.infinitecampus.org, etc.). Declare just this host
+      // — each district is its own root, no wildcard needed.
+      domains: [host],
+      declare: {
+        // JSESSIONID is HttpOnly (chrome.cookies.get sees it; the
+        // security gate is the declared key list). XSRF-TOKEN is
+        // non-HttpOnly because the page JS reads it back and echoes
+        // it on every state-changing call as the X-XSRF-TOKEN header.
+        cookies: ["JSESSIONID", "XSRF-TOKEN"],
+        localStorage: [],
+        sessionStorage: [],
+        captureHeaders: []
       }
-      const msg = e instanceof Error ? e.message : String(e);
+    });
+    liftersByHost.set(host, lift);
+  }
+  return lift;
+}
+async function liftBrowserSession(account2) {
+  try {
+    const host = new URL(account2.baseUrl).hostname;
+    const session = await lifterFor(host)();
+    const jsessionid = session.cookies["JSESSIONID"];
+    const xsrf = session.cookies["XSRF-TOKEN"];
+    if (!jsessionid) {
+      throw new Error(
+        `JSESSIONID cookie not found on ${host}. Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.`
+      );
+    }
+    if (!xsrf) {
       throw new Error(
-        "IC auth: no IC_USERNAME/IC_PASSWORD set, and fetchproxy fallback failed: " + msg
+        `XSRF-TOKEN cookie not found on ${host}. Sign into your IC portal in your browser (with the fetchproxy extension installed) and retry.`
       );
     }
+    return {
+      cookieHeader: `JSESSIONID=${jsessionid}; XSRF-TOKEN=${xsrf}`,
+      xsrfToken: xsrf
+    };
+  } catch (e) {
+    if (classifyBridgeError(e) === "bridge_down") {
+      const downErr = e;
+      throw new Error(
+        `IC auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+      );
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(
+      "IC auth: no IC_USERNAME/IC_PASSWORD set, and fetchproxy lift failed: " + msg
+    );
   }
-  throw new Error(
-    "IC auth: set IC_USERNAME + IC_PASSWORD, or install the fetchproxy extension and sign into your IC portal (unset IC_DISABLE_FETCHPROXY if it is set)."
-  );
 }
 
 // src/client.ts
@@ -38610,24 +38843,29 @@ var ICClient = class {
    * first call to `ensureDiscovery()`.
    */
   fetchproxyMode = false;
-  fetchproxyDiscoveryRan = false;
-  /** fetchproxy cookies, consumed by the primary manager's first login. */
-  preloaded = null;
-  /**
-   * `preloaded` is the fetchproxy escape hatch: when set, the client treats
-   * the supplied cookies as a freshly-completed login on the primary account.
-   * This skips the `verify.jsp` POST entirely (the account has empty creds
-   * in this mode) but otherwise behaves identically — CUPS linked-district
-   * discovery still runs on first request, 401 retry still triggers a
-   * re-login. On a 401 with empty credentials we can't re-login from Node;
-   * the user must re-sign-in in the browser.
+  /**
+   * fetchproxy lift. Called by the primary manager's login — on the first
+   * request AND on every renewal, which is what keeps the path alive past
+   * JSESSIONID's idle timeout.
+   */
+  refreshSession = null;
+  /**
+   * `refreshSession` is the fetchproxy escape hatch: when set, it REPLACES
+   * the `verify.jsp` POST as the way this client mints a primary session.
+   * It is called lazily on the first request and again on every expiry, so a
+   * lapsed servlet session recovers by re-reading the browser rather than
+   * dead-ending. CUPS linked-district discovery still runs on first request.
+   *
+   * It must re-read the browser each time rather than return a captured
+   * value: JSESSIONID lapses on a short idle timer and the account has no
+   * credentials to fall back on.
    */
   constructor(account2, opts = {}) {
     this.accounts.set(account2.name, account2);
     this.primaryName = account2.name;
     this.managers.set(account2.name, this.makeManager(account2));
-    if (opts.preloaded) {
-      this.preloaded = opts.preloaded;
+    if (opts.refreshSession) {
+      this.refreshSession = opts.refreshSession;
       this.fetchproxyMode = true;
     }
   }
@@ -38682,10 +38920,7 @@ var ICClient = class {
   }
   async ensureDiscovery() {
     const session = await this.managers.get(this.primaryName).ensure();
-    if (this.fetchproxyMode && !this.fetchproxyDiscoveryRan) {
-      this.fetchproxyDiscoveryRan = true;
-      await this.discoverLinkedDistricts(this.accounts.get(this.primaryName), session);
-    }
+    void session;
   }
   listDistricts() {
     return [...this.accounts.values()].map((a) => ({
@@ -38717,11 +38952,7 @@ var ICClient = class {
       account2 = this.accounts.get(district);
       if (!account2) throw new UnknownDistrictError(district, [...this.accounts.keys()]);
     }
-    const session = await this.managers.get(account2.name).ensure();
-    if (this.fetchproxyMode && !this.fetchproxyDiscoveryRan && account2.name === this.primaryName) {
-      this.fetchproxyDiscoveryRan = true;
-      await this.discoverLinkedDistricts(account2, session);
-    }
+    await this.managers.get(account2.name).ensure();
     return this.doRequest(account2, path, opts);
   }
   async login(account2) {
@@ -38738,15 +38969,15 @@ var ICClient = class {
       }
       return restored;
     }
-    if (this.preloaded) {
-      const { cookieHeader, xsrfToken } = this.preloaded;
-      this.preloaded = null;
-      return { cookieHeader, xsrfToken };
+    if (this.refreshSession) {
+      const session2 = await this.refreshSession();
+      await this.discoverLinkedDistricts(account2, session2);
+      return session2;
     }
     if (!account2.username || !account2.password) {
       throw new AuthFailedError(
         account2.name,
-        "session expired and no IC_USERNAME/IC_PASSWORD set \u2014 sign back into your IC portal in the browser and restart the MCP",
+        "session expired and no IC_USERNAME/IC_PASSWORD set \u2014 sign back into your IC portal in the browser, or set IC_USERNAME/IC_PASSWORD",
         { permanent: true }
       );
     }
@@ -39914,24 +40145,24 @@ await loadDotenvSafely({
 });
 var AI_NOTICE = "[infinitecampus-mcp] Developed and maintained by AI (Claude). Use at your own discretion.";
 var account = null;
-var preloaded;
+var refreshSession;
 var source;
 var configError = null;
 try {
   const resolved = await resolveAuth();
   account = resolved.account;
-  preloaded = resolved.preloaded;
+  refreshSession = resolved.refresh;
   source = resolved.source;
 } catch (e) {
   configError = e;
 }
 var COMMON = {
   name: "infinitecampus",
-  version: "2.4.0"
+  version: "2.4.3"
   // x-release-please-version
 };
 if (account) {
-  const client = new ICClient(account, { preloaded });
+  const client = new ICClient(account, { refreshSession });
   const tools = [
     registerDistrictTools,
     registerStudentTools,

package/dist/client.js

@@ -25,24 +25,29 @@ export class ICClient {
      * first call to `ensureDiscovery()`.
      */
     fetchproxyMode = false;
-    fetchproxyDiscoveryRan = false;
-    /** fetchproxy cookies, consumed by the primary manager's first login. */
-    preloaded = null;
     /**
-     * `preloaded` is the fetchproxy escape hatch: when set, the client treats
-     * the supplied cookies as a freshly-completed login on the primary account.
-     * This skips the `verify.jsp` POST entirely (the account has empty creds
-     * in this mode) but otherwise behaves identically — CUPS linked-district
-     * discovery still runs on first request, 401 retry still triggers a
-     * re-login. On a 401 with empty credentials we can't re-login from Node;
-     * the user must re-sign-in in the browser.
+     * fetchproxy lift. Called by the primary manager's login — on the first
+     * request AND on every renewal, which is what keeps the path alive past
+     * JSESSIONID's idle timeout.
+     */
+    refreshSession = null;
+    /**
+     * `refreshSession` is the fetchproxy escape hatch: when set, it REPLACES
+     * the `verify.jsp` POST as the way this client mints a primary session.
+     * It is called lazily on the first request and again on every expiry, so a
+     * lapsed servlet session recovers by re-reading the browser rather than
+     * dead-ending. CUPS linked-district discovery still runs on first request.
+     *
+     * It must re-read the browser each time rather than return a captured
+     * value: JSESSIONID lapses on a short idle timer and the account has no
+     * credentials to fall back on.
      */
     constructor(account, opts = {}) {
         this.accounts.set(account.name, account);
         this.primaryName = account.name;
         this.managers.set(account.name, this.makeManager(account));
-        if (opts.preloaded) {
-            this.preloaded = opts.preloaded;
+        if (opts.refreshSession) {
+            this.refreshSession = opts.refreshSession;
             this.fetchproxyMode = true;
         }
     }
@@ -98,16 +103,11 @@ export class ICClient {
     async ensureDiscovery() {
         // Ensure primary account is logged in, which triggers CUPS linked-district discovery
         const session = await this.managers.get(this.primaryName).ensure();
-        // fetchproxy mode skips the verify.jsp login and therefore the discovery
-        // call inside it. Run discovery directly the first time someone asks for
-        // it. The primary is never in linkedTo (it's the root of the linkedTo
-        // map). When login() runs for an already-linked district during a TTL
-        // refresh, it re-auths through the primary instead of running discovery
-        // itself.
-        if (this.fetchproxyMode && !this.fetchproxyDiscoveryRan) {
-            this.fetchproxyDiscoveryRan = true;
-            await this.discoverLinkedDistricts(this.accounts.get(this.primaryName), session);
-        }
+        // Nothing further to do: `ensure()` mints the primary session when one is
+        // needed, and every primary mint runs discovery — in fetchproxy mode via
+        // login()'s lift branch, in env mode via mintSessionCookie(). A cached
+        // primary session means discovery already ran for it.
+        void session;
     }
     listDistricts() {
         return [...this.accounts.values()].map((a) => ({
@@ -143,15 +143,7 @@ export class ICClient {
             if (!account)
                 throw new UnknownDistrictError(district, [...this.accounts.keys()]);
         }
-        const session = await this.managers.get(account.name).ensure();
-        // In fetchproxy mode, the preloaded-cookie login never runs verify.jsp
-        // and therefore never calls discoverLinkedDistricts. Run discovery once
-        // on the first primary call so linked districts are discoverable. (The
-        // primary is never in linkedTo by construction.)
-        if (this.fetchproxyMode && !this.fetchproxyDiscoveryRan && account.name === this.primaryName) {
-            this.fetchproxyDiscoveryRan = true;
-            await this.discoverLinkedDistricts(account, session);
-        }
+        await this.managers.get(account.name).ensure();
         return this.doRequest(account, path, opts);
     }
     async login(account) {
@@ -179,13 +171,20 @@ export class ICClient {
             }
             return restored;
         }
-        // fetchproxy mode: the first primary login consumes the preloaded browser
-        // cookies instead of POSTing to verify.jsp. Consumed exactly once — after
-        // an expiry/invalidate there is nothing left to re-login with (below).
-        if (this.preloaded) {
-            const { cookieHeader, xsrfToken } = this.preloaded;
-            this.preloaded = null;
-            return { cookieHeader, xsrfToken };
+        // fetchproxy mode: mint the primary session by re-reading the browser
+        // instead of POSTing to verify.jsp. This runs on EVERY login, not just
+        // the first — a lapsed JSESSIONID recovers by lifting the live session
+        // the browser still holds, which is the whole point.
+        if (this.refreshSession) {
+            const session = await this.refreshSession();
+            // Mirror mintSessionCookie(): a primary re-mint re-runs CUPS discovery
+            // so linked districts get re-seeded. Without this a linked district
+            // could never recover — its login() defers to the primary and then
+            // reads `current`, which would stay unset because the primary's mint
+            // short-circuited past discovery. By construction we only reach here
+            // for the primary (linked districts return early above).
+            await this.discoverLinkedDistricts(account, session);
+            return session;
         }
         // fetchproxy mode: empty primary creds, can't post to verify.jsp.
         // The user must re-sign-in in the browser (and the next process start
@@ -193,7 +192,7 @@ export class ICClient {
         // and rethrows this instead of retrying a login that can never succeed.
         if (!account.username || !account.password) {
             throw new AuthFailedError(account.name, 'session expired and no IC_USERNAME/IC_PASSWORD set — ' +
-                'sign back into your IC portal in the browser and restart the MCP', { permanent: true });
+                'sign back into your IC portal in the browser, or set IC_USERNAME/IC_PASSWORD', { permanent: true });
         }
         // ic_parent_api's pattern: single POST to verify.jsp, let the response
         // set cookies. No pre-login GET needed (unlike OFW's Spring Security).

package/dist/index.js

@@ -37,13 +37,13 @@ const AI_NOTICE = '[infinitecampus-mcp] Developed and maintained by AI (Claude).
 // IC portal in the browser). When not configured we register no tools and
 // log a clear stderr message — far better than the previous crash loop.
 let account = null;
-let preloaded;
+let refreshSession;
 let source;
 let configError = null;
 try {
     const resolved = await resolveAuth();
     account = resolved.account;
-    preloaded = resolved.preloaded;
+    refreshSession = resolved.refresh;
     source = resolved.source;
 }
 catch (e) {
@@ -57,10 +57,10 @@ catch (e) {
 // actionable stderr message (banner) instead of a crash loop.
 const COMMON = {
     name: 'infinitecampus',
-    version: '2.4.0', // x-release-please-version
+    version: '2.4.3', // x-release-please-version
 };
 if (account) {
-    const client = new ICClient(account, { preloaded });
+    const client = new ICClient(account, { refreshSession });
     const tools = [
         registerDistrictTools,
         registerStudentTools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.4.0",
+  "version": "2.4.3",
   "mcpName": "io.github.chrischall/infinitecampus-mcp",
   "description": "Infinite Campus (Campus Parent) MCP server — multi-district read + message/document write",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -42,9 +42,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.13.0",
-    "@fetchproxy/bootstrap": "^1.0.0",
-    "@fetchproxy/server": "^1.0.0",
+    "@chrischall/mcp-utils": "^0.14.0",
+    "@fetchproxy/bootstrap": "^1.9.1",
+    "@fetchproxy/server": "^1.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "node-html-parser": "^9.0.0",

package/server.json

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