infinitecampus-mcp 2.4.2 → 2.4.4

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "infinitecampus-mcp",
   "displayName": "Infinite Campus",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "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,115 @@ 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],
+            // IC is a Tomcat app deployed at /campus, and Tomcat scopes JSESSIONID
+            // to the servlet context by default:
+            //
+            //   JSESSIONID=...; Path=/campus; Secure; HttpOnly; SameSite=Lax
+            //
+            // chrome.cookies.get matches that Path against the URL it is given, so a
+            // read aimed at the origin root silently returns nothing — which is
+            // indistinguishable from "the user is signed out", and is why this path
+            // never worked on any tenant. Verified live: without this the lift found
+            // no cookies while a fetch through the same tab returned authenticated
+            // data; with it, JSESSIONID + XSRF-TOKEN both come back.
+            storagePath: '/campus',
+            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

@@ -26729,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 {
@@ -33354,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");
     }
@@ -34551,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() {
@@ -34580,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.
@@ -34955,6 +34977,15 @@ function assertHttpUrl(x, label) {
     throw new ProtocolError(`${label}: must be http(s), got ${u.protocol}`);
   }
 }
+function assertCookiePath(x, label) {
+  assertString(x, label);
+  if (!x.startsWith("/") || x.startsWith("//")) {
+    throw new ProtocolError(`${label}: must be an absolute path like "/campus"`);
+  }
+  if (x.includes("?") || x.includes("#") || x.includes("\\")) {
+    throw new ProtocolError(`${label}: must not contain a query, fragment, or backslash`);
+  }
+}
 function assertHttpsOriginOnly(x, label) {
   assertString(x, label);
   let u;
@@ -35399,8 +35430,10 @@ function validateInnerRequest(raw) {
     }
     assertHttpsOriginOnly(raw.init.origin, "inner.init.origin");
     assertNonEmptyKeyArray(raw.init.keys, "inner.init.keys");
+    if (raw.init.path !== void 0)
+      assertCookiePath(raw.init.path, "inner.init.path");
     for (const k of Object.keys(raw.init)) {
-      if (k !== "origin" && k !== "keys") {
+      if (k !== "origin" && k !== "keys" && k !== "path") {
         throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on read_cookies`);
       }
     }
@@ -36631,6 +36664,22 @@ var FetchproxyBridgeDownError = class extends FetchproxyProtocolError {
     this.hint = hint;
   }
 };
+var FetchproxyScopeError = class extends FetchproxyProtocolError {
+  /** The extension's raw rejection, unmodified. */
+  originalError;
+  hint;
+  constructor(originalError) {
+    const hint = "the declared scope changed since you paired, so the extension is refusing the request. Revoke this MCP in the Transporter extension popup, then re-run \u2014 you will be asked to approve the new scope. This is not a version problem and does not need an update.";
+    super(`${originalError} \u2014 ${hint}`);
+    this.name = "FetchproxyScopeError";
+    this.originalError = originalError;
+    this.hint = hint;
+  }
+};
+var SCOPE_REJECTION = /not in declared/;
+function protocolErrorFrom(error51) {
+  return SCOPE_REJECTION.test(error51) ? new FetchproxyScopeError(error51) : new FetchproxyProtocolError(error51);
+}
 var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
   url;
   timeoutMs;
@@ -36660,6 +36709,17 @@ var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
   }
 };
 var SUBDOMAIN_LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
+function normalizeCookiePath(path) {
+  if (path === void 0 || path === "")
+    return void 0;
+  const trimmed = path.endsWith("/") && path !== "/" ? path.slice(0, -1) : path;
+  try {
+    assertCookiePath(trimmed, "path");
+  } catch (e) {
+    throw new Error(`FetchproxyServer: ${e instanceof Error ? e.message : String(e)} (got ${JSON.stringify(path)})`);
+  }
+  return trimmed;
+}
 function assertSubdomainLabel(label) {
   if (!SUBDOMAIN_LABEL_RE.test(label)) {
     throw new Error(`FetchproxyServer: subdomain must be a DNS label like "www" or "api" (or dot-separated like "auth.api"), got ${JSON.stringify(label)}`);
@@ -37301,7 +37361,7 @@ var FetchproxyServer = class {
         port: this.opts.port
       });
     }
-    return new FetchproxyProtocolError(result.error);
+    return protocolErrorFrom(result.error);
   }
   /**
    * Convenience wrapper around `fetch()`. Builds the URL from a path
@@ -37552,9 +37612,14 @@ var FetchproxyServer = class {
     let inner;
     if (opts.keys !== void 0) {
       this.assertScopeSubset(opts.keys, this.opts.cookieKeys, "cookieKeys");
+      const cookiePath = normalizeCookiePath(opts.path);
       const initV3 = {
+        // Origin stays BARE. The path travels as its own validated field —
+        // `assertHttpsOriginOnly` deliberately refuses a path here so one
+        // cannot be used to re-point the read past the domain gate.
         origin: `https://${host}`,
-        keys: [...opts.keys]
+        keys: [...opts.keys],
+        ...cookiePath !== void 0 ? { path: cookiePath } : {}
       };
       inner = { type: "request", id, op: "read_cookies", init: initV3 };
     } else {
@@ -37567,7 +37632,7 @@ var FetchproxyServer = class {
     await this.sendInnerFrame(inner);
     const result = await this._withVerbTimeout(pending, this.pendingReadCookies, id, `https://${host}`);
     if (!result.ok) {
-      throw new FetchproxyProtocolError(result.error);
+      throw protocolErrorFrom(result.error);
     }
     return result.cookies;
   }
@@ -38117,7 +38182,7 @@ var FetchproxyServer = class {
           storageCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on storage awaiter`));
         }
       } else {
-        storageCb.reject(new FetchproxyProtocolError(inner.error));
+        storageCb.reject(protocolErrorFrom(inner.error));
       }
       return;
     }
@@ -38131,7 +38196,7 @@ var FetchproxyServer = class {
           captureCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on capture awaiter`));
         }
       } else {
-        captureCb.reject(new FetchproxyProtocolError(inner.error));
+        captureCb.reject(protocolErrorFrom(inner.error));
       }
       return;
     }
@@ -38145,7 +38210,7 @@ var FetchproxyServer = class {
           redirectCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on capture_redirect awaiter`));
         }
       } else {
-        redirectCb.reject(new FetchproxyProtocolError(inner.error));
+        redirectCb.reject(protocolErrorFrom(inner.error));
       }
       return;
     }
@@ -38159,7 +38224,7 @@ var FetchproxyServer = class {
           idbCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on read_indexed_db awaiter`));
         }
       } else {
-        idbCb.reject(new FetchproxyProtocolError(inner.error));
+        idbCb.reject(protocolErrorFrom(inner.error));
       }
       return;
     }
@@ -38173,7 +38238,7 @@ var FetchproxyServer = class {
           downloadCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on download awaiter`));
         }
       } else {
-        downloadCb.reject(new FetchproxyProtocolError(inner.error));
+        downloadCb.reject(protocolErrorFrom(inner.error));
       }
       return;
     }
@@ -38187,7 +38252,7 @@ var FetchproxyServer = class {
           graphqlCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on graphql_query awaiter`));
         }
       } else {
-        graphqlCb.reject(new FetchproxyProtocolError(inner.error));
+        graphqlCb.reject(protocolErrorFrom(inner.error));
       }
       return;
     }
@@ -38298,7 +38363,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") {
@@ -38367,7 +38445,9 @@ async function bootstrap(opts) {
     if (opts.declare.cookies.length > 0) {
       const joined = await server.readCookies({
         keys: opts.declare.cookies,
-        ...storageDomainOpts
+        ...storageDomainOpts,
+        // Cookie-only: the other buckets are origin-scoped and ignore path.
+        ...opts.storagePath !== void 0 ? { path: opts.storagePath } : {}
       });
       for (const piece of joined.split("; ")) {
         if (!piece)
@@ -38425,12 +38505,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 {
@@ -38491,7 +38577,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "infinitecampus-mcp",
-  version: "2.4.2",
+  version: "2.4.4",
   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>",
@@ -38534,7 +38620,7 @@ var package_default = {
   },
   dependencies: {
     "@chrischall/mcp-utils": "^0.14.0",
-    "@fetchproxy/bootstrap": "^1.7.0",
+    "@fetchproxy/bootstrap": "^1.11.0",
     "@fetchproxy/server": "^1.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
@@ -38560,62 +38646,86 @@ 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],
+      // IC is a Tomcat app deployed at /campus, and Tomcat scopes JSESSIONID
+      // to the servlet context by default:
+      //
+      //   JSESSIONID=...; Path=/campus; Secure; HttpOnly; SameSite=Lax
+      //
+      // chrome.cookies.get matches that Path against the URL it is given, so a
+      // read aimed at the origin root silently returns nothing — which is
+      // indistinguishable from "the user is signed out", and is why this path
+      // never worked on any tenant. Verified live: without this the lift found
+      // no cookies while a fetch through the same tab returned authenticated
+      // data; with it, JSESSIONID + XSRF-TOKEN both come back.
+      storagePath: "/campus",
+      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
@@ -38790,24 +38900,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;
     }
   }
@@ -38862,10 +38977,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) => ({
@@ -38897,11 +39009,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) {
@@ -38918,15 +39026,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 }
       );
     }
@@ -40094,24 +40202,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.2"
+  version: "2.4.4"
   // 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.2', // x-release-please-version
+    version: '2.4.4', // 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.2",
+  "version": "2.4.4",
   "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>",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@chrischall/mcp-utils": "^0.14.0",
-    "@fetchproxy/bootstrap": "^1.7.0",
+    "@fetchproxy/bootstrap": "^1.11.0",
     "@fetchproxy/server": "^1.7.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",

package/server.json

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