infinitecampus-mcp 2.3.2 → 2.3.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.3.2"
+    "version": "2.3.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.3.2",
+      "version": "2.3.3",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/dist/bundle.js

@@ -34791,7 +34791,9 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "read_local_storage",
   "read_session_storage",
   "capture_request_header",
-  "read_indexed_db"
+  "capture_redirect",
+  "read_indexed_db",
+  "download"
 ]);
 
 // node_modules/@fetchproxy/protocol/dist/mcp-id.js
@@ -35351,6 +35353,31 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
+  if (raw.op === "capture_redirect") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.host === void 0) {
+      throw new ProtocolError("inner.init.host: missing");
+    }
+    assertString(raw.init.host, "inner.init.host");
+    if (!HOSTNAME_RE.test(raw.init.host)) {
+      throw new ProtocolError(`inner.init.host: invalid hostname ${JSON.stringify(raw.init.host)}`);
+    }
+    if (raw.init.path !== void 0) {
+      assertString(raw.init.path, "inner.init.path");
+      if (!CAPTURE_PATH_RE.test(raw.init.path)) {
+        throw new ProtocolError(`inner.init.path: must start with '/' ${JSON.stringify(raw.init.path)}`);
+      }
+    }
+    if (raw.init.timeoutMs !== void 0) {
+      assertPositiveInt(raw.init.timeoutMs, "inner.init.timeoutMs");
+    }
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "host" && k !== "path" && k !== "timeoutMs") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on capture_redirect`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "read_indexed_db") {
     assertObject(raw.init, "inner.init");
     if (raw.init.origin === void 0)
@@ -35376,7 +35403,32 @@ 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", "read_indexed_db"; got ${JSON.stringify(raw.op)}`);
+  if (raw.op === "download") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.url === void 0) {
+      throw new ProtocolError("inner.init.url: missing");
+    }
+    assertHttpUrl(raw.init.url, "inner.init.url");
+    if (raw.init.filename !== void 0) {
+      assertString(raw.init.filename, "inner.init.filename");
+      if (/^([/\\]|[A-Za-z]:)/.test(raw.init.filename)) {
+        throw new ProtocolError(`inner.init.filename: must be relative ${JSON.stringify(raw.init.filename)}`);
+      }
+      if (raw.init.filename.split(/[/\\]/).includes("..")) {
+        throw new ProtocolError(`inner.init.filename: must not contain '..' ${JSON.stringify(raw.init.filename)}`);
+      }
+    }
+    if (raw.init.timeoutMs !== void 0) {
+      assertPositiveInt(raw.init.timeoutMs, "inner.init.timeoutMs");
+    }
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "url" && k !== "filename" && k !== "timeoutMs") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on download`);
+      }
+    }
+    return raw;
+  }
+  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "download"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35447,6 +35499,13 @@ function validateInnerResponse(raw) {
       assertString(raw.value, "inner.value");
       return raw;
     }
+    if (op === "capture_redirect") {
+      if (raw.value === void 0) {
+        throw new ProtocolError("inner.value: missing on capture_redirect response");
+      }
+      assertString(raw.value, "inner.value");
+      return raw;
+    }
     if (op === "read_indexed_db") {
       if (raw.values === void 0) {
         throw new ProtocolError("inner.values: missing on read_indexed_db response");
@@ -35454,6 +35513,25 @@ function validateInnerResponse(raw) {
       assertObject(raw.values, "inner.values");
       return raw;
     }
+    if (op === "download") {
+      assertObject(raw.value, "inner.value");
+      assertString(raw.value.path, "inner.value.path");
+      if (typeof raw.value.bytes !== "number" || !Number.isInteger(raw.value.bytes) || raw.value.bytes < 0) {
+        throw new ProtocolError("inner.value.bytes: expected non-negative integer");
+      }
+      if (raw.value.mime !== void 0) {
+        assertString(raw.value.mime, "inner.value.mime");
+      }
+      if (raw.value.finalUrl !== void 0) {
+        assertString(raw.value.finalUrl, "inner.value.finalUrl");
+      }
+      for (const k of Object.keys(raw.value)) {
+        if (k !== "path" && k !== "bytes" && k !== "mime" && k !== "finalUrl") {
+          throw new ProtocolError(`inner.value: unexpected field ${JSON.stringify(k)} on download response`);
+        }
+      }
+      return raw;
+    }
     throw new ProtocolError(`inner.op: unknown success-response op ${JSON.stringify(raw.op)}`);
   }
   if (raw.ok === false) {
@@ -36324,8 +36402,12 @@ var FetchproxyServer = class {
   pendingStorage = /* @__PURE__ */ new Map();
   // 0.3.0+: capture-header awaiters resolve a single string.
   pendingCapture = /* @__PURE__ */ new Map();
+  // capture_redirect awaiters resolve the captured redirect URL string.
+  pendingRedirect = /* @__PURE__ */ new Map();
   // 0.4.0+: read_indexed_db awaiters resolve a JSON-typed values map.
   pendingIdb = /* @__PURE__ */ new Map();
+  // download awaiters resolve the saved-file metadata (path + size + mime).
+  pendingDownload = /* @__PURE__ */ new Map();
   mcpId = null;
   identity = null;
   // 0.5.3+: in-flight role-election / handle-start promise. Set the
@@ -37257,6 +37339,181 @@ var FetchproxyServer = class {
     }
     return pending;
   }
+  /**
+   * Snapshot the redirect target URL of the next request the browser
+   * makes to `(host, path?)`. Single-shot: the extension registers a
+   * one-time `chrome.webRequest.onBeforeRedirect` listener filtered on
+   * `https://${host}${path ?? '/*'}`, captures `details.redirectUrl` on
+   * the first match, removes itself, and resolves with the URL. Times out
+   * after `timeoutMs` (default 30s on the extension).
+   *
+   * Use case: a Cloudflare-walled endpoint that 302-redirects cross-origin
+   * to a presigned URL — a page-level fetch sees only an opaque redirect,
+   * but `onBeforeRedirect` exposes the target. Capture is limited to the
+   * MCP's own declared `domains`; no per-entry declared scope is required.
+   */
+  async captureRedirect(opts) {
+    if (!this.opts.capabilities.includes("capture_redirect")) {
+      throw new Error('FetchproxyServer.captureRedirect(): MCP did not declare "capture_redirect" in capabilities');
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    try {
+      const result = await this._captureRedirectOnce(opts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`capture_redirect: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      this.lastEvictionDetectedAt = Date.now();
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        this.lazyReviveAttempts += 1;
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._captureRedirectOnce(opts);
+          this.lazyReviveSuccesses += 1;
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`capture_redirect: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`capture_redirect bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "capture_redirect",
+            url: `https://${opts.host}${opts.path ?? "/*"}`,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`capture_redirect bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "capture_redirect",
+        url: `https://${opts.host}${opts.path ?? "/*"}`,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+  }
+  async _captureRedirectOnce(opts) {
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "capture_redirect",
+      init: {
+        host: opts.host,
+        ...opts.path !== void 0 ? { path: opts.path } : {},
+        ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
+      }
+    };
+    const pending = new Promise((resolve, reject) => {
+      this.pendingRedirect.set(id, { resolve, reject });
+    });
+    if (this.hostHandle) {
+      await this.hostHandle.sendOwnInner(inner);
+    } else if (this.peerHandle) {
+      await this.peerHandle.sendInner(inner);
+    }
+    return pending;
+  }
+  /**
+   * Download `url` through the BROWSER's own network stack via
+   * `chrome.downloads` (real cookies + TLS/JA3 fingerprint). Unlike a
+   * page-level `fetch()` (cors mode), this clears a Cloudflare bot-challenge
+   * on the endpoint and follows the cross-origin redirect to the final file.
+   * Resolves the saved local file path + size; the bridge is loopback-only /
+   * single-host, so the MCP reads the bytes from the same disk. Requires
+   * `'download'` in capabilities and the `url` host to be a declared `domain`.
+   */
+  async download(opts) {
+    if (!this.opts.capabilities.includes("download")) {
+      throw new Error('FetchproxyServer.download(): MCP did not declare "download" in capabilities');
+    }
+    assertUrlInDomains("download url", opts.url, this.opts.domains);
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    try {
+      const result = await this._downloadOnce(opts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`download: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      this.lastEvictionDetectedAt = Date.now();
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        this.lazyReviveAttempts += 1;
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._downloadOnce(opts);
+          this.lazyReviveSuccesses += 1;
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`download: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`download bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "download",
+            url: opts.url,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`download bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "download",
+        url: opts.url,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+  }
+  async _downloadOnce(opts) {
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "download",
+      init: {
+        url: opts.url,
+        ...opts.filename !== void 0 ? { filename: opts.filename } : {},
+        ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
+      }
+    };
+    const pending = new Promise((resolve, reject) => {
+      this.pendingDownload.set(id, { resolve, reject });
+    });
+    if (this.hostHandle) {
+      await this.hostHandle.sendOwnInner(inner);
+    } else if (this.peerHandle) {
+      await this.peerHandle.sendInner(inner);
+    }
+    return pending;
+  }
   /**
    * 0.4.0+: read declared IndexedDB keys from the user's signed-in
    * tab. Requires `'read_indexed_db'` in capabilities AND the
@@ -37404,6 +37661,20 @@ var FetchproxyServer = class {
       }
       return;
     }
+    const redirectCb = this.pendingRedirect.get(inner.id);
+    if (redirectCb) {
+      this.pendingRedirect.delete(inner.id);
+      if (inner.ok) {
+        if (inner.op === "capture_redirect" && typeof inner.value === "string") {
+          redirectCb.resolve(inner.value);
+        } else {
+          redirectCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on capture_redirect awaiter`));
+        }
+      } else {
+        redirectCb.reject(new FetchproxyProtocolError(inner.error));
+      }
+      return;
+    }
     const idbCb = this.pendingIdb.get(inner.id);
     if (idbCb) {
       this.pendingIdb.delete(inner.id);
@@ -37418,6 +37689,20 @@ var FetchproxyServer = class {
       }
       return;
     }
+    const downloadCb = this.pendingDownload.get(inner.id);
+    if (downloadCb) {
+      this.pendingDownload.delete(inner.id);
+      if (inner.ok) {
+        if (inner.op === "download" && inner.value && typeof inner.value === "object") {
+          downloadCb.resolve({ ...inner.value });
+        } else {
+          downloadCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on download awaiter`));
+        }
+      } else {
+        downloadCb.reject(new FetchproxyProtocolError(inner.error));
+      }
+      return;
+    }
     const cookiesCb = this.pendingReadCookies.get(inner.id);
     if (cookiesCb) {
       this.pendingReadCookies.delete(inner.id);
@@ -37460,9 +37745,15 @@ var FetchproxyServer = class {
     for (const { reject } of this.pendingCapture.values())
       reject(err);
     this.pendingCapture.clear();
+    for (const { reject } of this.pendingRedirect.values())
+      reject(err);
+    this.pendingRedirect.clear();
     for (const { reject } of this.pendingIdb.values())
       reject(err);
     this.pendingIdb.clear();
+    for (const { reject } of this.pendingDownload.values())
+      reject(err);
+    this.pendingDownload.clear();
   }
   /**
    * 0.5.2+: read the current pair-pending pair code from whichever handle
@@ -37709,7 +38000,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "infinitecampus-mcp",
-  version: "2.3.2",
+  version: "2.3.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>",
@@ -37941,6 +38232,20 @@ var ICClient = class {
     }
   }
   async login(account2) {
+    const primaryName = this.linkedTo.get(account2.name);
+    if (primaryName) {
+      this.sessions.delete(account2.name);
+      const primaryAccount = this.accounts.get(primaryName);
+      await this.ensureSession(primaryAccount);
+      if (!this.sessions.has(account2.name)) {
+        throw new AuthFailedError(
+          account2.name,
+          "linked-district session could not be re-established via the primary district",
+          { credentialHint: false }
+        );
+      }
+      return;
+    }
     if (!account2.username || !account2.password) {
       throw new AuthFailedError(
         account2.name,
@@ -37948,8 +38253,17 @@ var ICClient = class {
       );
     }
     const postRes = await fetch(
-      `${account2.baseUrl}/campus/verify.jsp?nonBrowser=true&username=${encodeURIComponent(account2.username)}&password=${encodeURIComponent(account2.password)}&appName=${encodeURIComponent(account2.district)}&portalLoginPage=parents`,
-      { method: "POST" }
+      `${account2.baseUrl}/campus/verify.jsp?nonBrowser=true`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          username: account2.username,
+          password: account2.password,
+          appName: account2.district,
+          portalLoginPage: "parents"
+        }).toString()
+      }
     );
     if (postRes.status >= 500) throw new PortalUnreachableError(account2.name, postRes.status);
     const body = await postRes.text();
@@ -37972,9 +38286,7 @@ var ICClient = class {
     session.cookie = cookies.cookieHeader;
     session.xsrfToken = cookies.xsrfToken;
     session.loggedInAt = Date.now();
-    if (!this.linkedTo.has(account2.name)) {
-      await this.discoverLinkedDistricts(account2);
-    }
+    await this.discoverLinkedDistricts(account2);
   }
   async discoverLinkedDistricts(account2) {
     try {
@@ -38157,11 +38469,16 @@ var UnknownDistrictError = class extends Error {
   available;
 };
 var AuthFailedError = class extends Error {
-  constructor(district, reason) {
+  /**
+   * @param opts.credentialHint When `false`, the message omits the
+   *   "Check IC_USERNAME and IC_PASSWORD" suffix — used for failures where the
+   *   credentials are known-good (e.g. a linked-district CUPS/SSO re-discovery
+   *   failure) and pointing the user at their creds would be misleading.
+   */
+  constructor(district, reason, opts) {
     const detail = reason ? ` (${reason})` : "";
-    super(
-      `Login failed for district '${district}'${detail}. Check IC_USERNAME and IC_PASSWORD; if those are correct, the account may be locked or the portal may be down.`
-    );
+    const remedy = opts?.credentialHint === false ? "Sign in again at the IC portal in your browser, then restart the MCP." : "Check IC_USERNAME and IC_PASSWORD; if those are correct, the account may be locked or the portal may be down.";
+    super(`Login failed for district '${district}'${detail}. ${remedy}`);
     this.district = district;
     this.reason = reason;
     this.name = "AuthFailedError";
@@ -39086,7 +39403,7 @@ try {
 }
 var COMMON = {
   name: "infinitecampus",
-  version: "2.3.2"
+  version: "2.3.3"
   // x-release-please-version
 };
 if (account) {

package/dist/client.js

@@ -44,10 +44,9 @@ export class ICClient {
         await this.ensureSession(this.accounts.get(this.primaryName));
         // fetchproxy mode skips 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), so
-        // no need to guard on that — the existing guard inside login() is for
-        // the inverse case where login() is called for an already-linked
-        // district during a TTL refresh.
+        // primary is never in linkedTo (it's the root of the linkedTo map). When
+        // login() is called 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));
@@ -119,18 +118,50 @@ export class ICClient {
         }
     }
     async login(account) {
+        // Linked districts have no real credentials of their own — they hold
+        // synthetic '(linked)' placeholders and are authenticated by the primary's
+        // CUPS SSO switch, not by their own verify.jsp. When a linked-district
+        // session expires by TTL (vs. a 401, which doRequest already routes through
+        // the primary), ensureSession lands here. Re-login the primary, which
+        // re-runs discoverLinkedDistricts and re-establishes this district's
+        // session — POSTing the placeholder creds to verify.jsp would instead yield
+        // a misleading password-error. See the comment block at the top of the file.
+        const primaryName = this.linkedTo.get(account.name);
+        if (primaryName) {
+            // Drop the stale linked session so re-discovery installs a fresh one.
+            this.sessions.delete(account.name);
+            const primaryAccount = this.accounts.get(primaryName);
+            await this.ensureSession(primaryAccount);
+            // ensureSession(primary) re-ran login() → discoverLinkedDistricts(),
+            // which re-creates the linked session. If discovery failed to restore it,
+            // surface a clear error rather than leaving callers with a null session.
+            if (!this.sessions.has(account.name)) {
+                throw new AuthFailedError(account.name, 'linked-district session could not be re-established via the primary district', { credentialHint: false });
+            }
+            return;
+        }
         // 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
-        // will pick up the fresh cookies). Linked accounts have placeholder
-        // creds too; their re-auth flows through the primary via CUPS, not
-        // verify.jsp directly.
+        // will pick up the fresh cookies).
         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');
         }
         // 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).
-        const postRes = await fetch(`${account.baseUrl}/campus/verify.jsp?nonBrowser=true&username=${encodeURIComponent(account.username)}&password=${encodeURIComponent(account.password)}&appName=${encodeURIComponent(account.district)}&portalLoginPage=parents`, { method: 'POST' });
+        // Credentials go in the urlencoded form body, NOT the URL query string —
+        // query-string creds land in proxy/LB/server access logs even over HTTPS.
+        // Mirrors the CUPS switch POST body construction against the same host.
+        const postRes = await fetch(`${account.baseUrl}/campus/verify.jsp?nonBrowser=true`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                username: account.username,
+                password: account.password,
+                appName: account.district,
+                portalLoginPage: 'parents',
+            }).toString(),
+        });
         if (postRes.status >= 500)
             throw new PortalUnreachableError(account.name, postRes.status);
         // IC's verify.jsp returns 200 with an <AUTHENTICATION>X</AUTHENTICATION>
@@ -160,10 +191,11 @@ export class ICClient {
         session.cookie = cookies.cookieHeader;
         session.xsrfToken = cookies.xsrfToken;
         session.loggedInAt = Date.now();
-        // Discover linked districts (CUPS SSO) — non-blocking, errors logged not thrown
-        if (!this.linkedTo.has(account.name)) {
-            await this.discoverLinkedDistricts(account);
-        }
+        // Discover linked districts (CUPS SSO) — non-blocking, errors logged not
+        // thrown. By construction we only reach here for the primary (or fetchproxy
+        // primary): linked districts return early above and re-auth via the primary,
+        // so no `linkedTo` guard is needed.
+        await this.discoverLinkedDistricts(account);
     }
     async discoverLinkedDistricts(account) {
         try {
@@ -379,11 +411,19 @@ export class UnknownDistrictError extends Error {
 export class AuthFailedError extends Error {
     district;
     reason;
-    constructor(district, reason) {
+    /**
+     * @param opts.credentialHint When `false`, the message omits the
+     *   "Check IC_USERNAME and IC_PASSWORD" suffix — used for failures where the
+     *   credentials are known-good (e.g. a linked-district CUPS/SSO re-discovery
+     *   failure) and pointing the user at their creds would be misleading.
+     */
+    constructor(district, reason, opts) {
         const detail = reason ? ` (${reason})` : '';
-        super(`Login failed for district '${district}'${detail}. ` +
-            `Check IC_USERNAME and IC_PASSWORD; ` +
-            `if those are correct, the account may be locked or the portal may be down.`);
+        const remedy = opts?.credentialHint === false
+            ? 'Sign in again at the IC portal in your browser, then restart the MCP.'
+            : 'Check IC_USERNAME and IC_PASSWORD; ' +
+                'if those are correct, the account may be locked or the portal may be down.';
+        super(`Login failed for district '${district}'${detail}. ${remedy}`);
         this.district = district;
         this.reason = reason;
         this.name = 'AuthFailedError';

package/dist/index.js

@@ -57,7 +57,7 @@ catch (e) {
 // actionable stderr message (banner) instead of a crash loop.
 const COMMON = {
     name: 'infinitecampus',
-    version: '2.3.2', // x-release-please-version
+    version: '2.3.3', // x-release-please-version
 };
 if (account) {
     const client = new ICClient(account, { preloaded });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.3.2",
+  "version": "2.3.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>",

package/server.json

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