infinitecampus-mcp 2.4.4 → 2.5.0

package/dist/client.js

@@ -2,6 +2,7 @@ import { writeFile, stat } from 'fs/promises';
 import { dirname } from 'path';
 import { parseCookieJar } from '@chrischall/mcp-utils';
 import { createCookieSessionManager } from '@chrischall/mcp-utils/session';
+import { createSessionCache, reportCacheWriteFailure } from './session-cache.js';
 const SESSION_TTL_MS = 5 * 60 * 60 * 1000; // 5h, slightly under IC's typical 6h
 export class ICClient {
     accounts = new Map();
@@ -25,6 +26,32 @@ export class ICClient {
      * first call to `ensureDiscovery()`.
      */
     fetchproxyMode = false;
+    /**
+     * Whether CUPS linked-district discovery has run IN THIS PROCESS. Not "is
+     * there a session" — a session restored from the on-disk cache is real while
+     * discovery has not run, and conflating the two leaves linked districts
+     * invisible. See {@link InfiniteCampusClient.ensureDiscovery}.
+     */
+    discoveryDone = false;
+    /**
+     * The in-flight discovery, so concurrent callers await the SAME one.
+     *
+     * A bare boolean is not enough: `discoveryDone` flips as soon as the CUPS
+     * probe answers, but `accounts`/`linkedTo` are only populated further down.
+     * A second request for a linked district landing in that window would read
+     * the flag as done, find `accounts` still empty, and throw
+     * UnknownDistrictError for a district that was moments from existing.
+     */
+    discoveryInFlight = null;
+    /**
+     * The session the last discovery attempt used.
+     *
+     * `login()` runs discovery on every fresh mint. If that probe fails without
+     * latching, `ensureDiscovery` would immediately re-probe with the very same
+     * session and fail identically — two requests for one answer. Retrying is
+     * right; retrying the same session inside one call is not.
+     */
+    lastDiscoverySession = null;
     /**
      * 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
@@ -45,11 +72,16 @@ export class ICClient {
     constructor(account, opts = {}) {
         this.accounts.set(account.name, account);
         this.primaryName = account.name;
-        this.managers.set(account.name, this.makeManager(account));
+        // BEFORE makeManager: it reads `fetchproxyMode` to decide what a cached
+        // record binds to. Setting it afterwards left the primary manager built with
+        // browserBacked:false, and fetchproxy accounts carry empty credentials — so
+        // the binding came back null and the mode this cache helps MOST was the one
+        // mode that never got one.
         if (opts.refreshSession) {
             this.refreshSession = opts.refreshSession;
             this.fetchproxyMode = true;
         }
+        this.managers.set(account.name, this.makeManager(account));
     }
     /**
      * Build the per-district CookieSessionManager.
@@ -69,8 +101,24 @@ export class ICClient {
      *   bookkeeping used to provide.
      */
     makeManager(account) {
+        // PRIMARY ONLY. A linked district's session is seeded by the primary's
+        // discovery and has no `linkedTo` entry behind it until that runs, so a
+        // linked record restored on its own would be a session belonging to nothing.
+        // Caching the primary is what makes the expensive part free; discovery
+        // re-runs from the restored session and re-establishes the rest.
+        const cache = account.name === this.primaryName
+            ? createSessionCache({
+                district: account.name,
+                baseUrl: account.baseUrl,
+                username: account.username,
+                password: account.password,
+                browserBacked: this.fetchproxyMode,
+            })
+            : null;
         return createCookieSessionManager({
             login: () => this.login(account),
+            persistence: cache ?? undefined,
+            onPersistError: reportCacheWriteFailure,
             isExpired: (res) => this.detectExpiredSession(account.name, res),
             isPermanentError: (e) => e instanceof AuthFailedError && e.permanent,
             maxAgeMs: SESSION_TTL_MS,
@@ -101,13 +149,60 @@ export class ICClient {
         return true;
     }
     async ensureDiscovery() {
-        // Ensure primary account is logged in, which triggers CUPS linked-district discovery
         const session = await this.managers.get(this.primaryName).ensure();
-        // 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;
+        // This used to be a no-op, resting on "a cached primary session means
+        // discovery already ran for it". That held while the only cache was in
+        // memory: a session in hand implied THIS process had minted it, and every
+        // mint runs discovery. A session RESTORED from disk breaks it — the session
+        // is real, discovery never ran here, and `accounts`/`linkedTo` are empty,
+        // so linked districts would silently not exist.
+        //
+        // Tracking it explicitly is the fix, and it is the right shape regardless
+        // of persistence: the invariant is "discovery has run in this process",
+        // which is now stated rather than inferred from a side effect.
+        if (this.discoveryDone)
+            return;
+        // ORDER MATTERS. The in-flight check comes first: a concurrent caller must
+        // AWAIT a discovery already running, not skip it — returning early would
+        // let it proceed on a half-populated `accounts` and throw
+        // UnknownDistrictError for a district that was moments from existing. The
+        // same-session guard below returns early by design, so putting it first
+        // would reintroduce exactly that race.
+        if (this.discoveryInFlight !== null) {
+            await this.discoveryInFlight;
+            return;
+        }
+        // Cleared on settle so a transiently-failed probe can be retried later.
+        // Non-null like every other primary lookup in this file: the constructor
+        // registers the primary account and sets primaryName from it.
+        const primary = this.accounts.get(this.primaryName);
+        const manager = this.managers.get(this.primaryName);
+        this.discoveryInFlight = (async () => {
+            // Reaching here means discovery has not latched. Both routes out are the
+            // same: get a FRESH session, because `login()` runs discovery itself on
+            // every mint — so re-minting IS the retry. Coverage made that plain, by
+            // showing the explicit re-probes this once had were unreachable: the
+            // latch was always already set by login's own discovery.
+            if (this.lastDiscoverySession === session) {
+                // Already probed this exact session and it did not latch, so it is
+                // spent. A re-mint (after the failed probe invalidated it) runs
+                // discovery against the new one.
+                await manager.ensure();
+                return;
+            }
+            if (await this.discoverLinkedDistricts(primary, session))
+                return;
+            // The probe rejected that session, so it has just been invalidated.
+            // Re-minting here rather than on the NEXT call is the whole point: before
+            // this, the first ic_list_districts after a restart silently omitted
+            // linked districts and the first request('<linked>') threw
+            // UnknownDistrictError. Once — login's discovery either succeeds or the
+            // problem is not staleness.
+            await manager.ensure();
+        })().finally(() => {
+            this.discoveryInFlight = null;
+        });
+        await this.discoveryInFlight;
     }
     listDistricts() {
         return [...this.accounts.values()].map((a) => ({
@@ -243,7 +338,20 @@ export class ICClient {
         await this.discoverLinkedDistricts(account, session);
         return session;
     }
+    /**
+     * @returns whether the CUPS probe ANSWERED. `false` means the session was
+     * rejected (and has been invalidated), so the caller can mint a fresh one and
+     * try once more — without that, recovery lands a call too late and the first
+     * `ic_list_districts` after a restart silently omits linked districts.
+     */
     async discoverLinkedDistricts(account, session) {
+        this.lastDiscoverySession = session;
+        // The latch is set where the CUPS probe ANSWERS, not here. Setting it up
+        // front conflated two very different silences: "this district has no CUPS"
+        // (permanent — never retry) and "the session was dead so the probe 401'd"
+        // (transient — must retry). A restored-but-idle-expired session hit the
+        // second, latched the flag, and left linked districts invisible for the
+        // life of the process.
         try {
             const baseHeaders = {
                 Cookie: session.cookieHeader,
@@ -255,18 +363,45 @@ export class ICClient {
             };
             // 1. Get linked accounts
             const laRes = await fetch(`${account.baseUrl}/campus/api/campus/authentication/cups/linkedAccounts`, { headers: baseHeaders });
-            if (!laRes.ok)
-                return; // silently skip if endpoint doesn't exist
+            if (!laRes.ok) {
+                // A 401/403 here does not mean "no CUPS" — it means the session this
+                // probe used is dead. Leaving it in place was the half-fix: the latch
+                // was gone, but `lastDiscoverySession` then blocked every retry, so
+                // linked districts stayed invisible and request('<linked>') threw
+                // UnknownDistrictError until some unrelated primary call happened to
+                // 401. Dropping the session is what makes the retry real — the next
+                // ensure() mints a fresh one and discovery runs against that.
+                if (laRes.status === 401 || laRes.status === 403) {
+                    // Invalidate ONLY. `lastDiscoverySession` deliberately keeps pointing
+                    // at this dead session: it stops ensureDiscovery re-probing the same
+                    // one immediately (two requests for one answer), while the
+                    // invalidation guarantees the NEXT call mints a different session
+                    // object — which the guard then lets through as a genuine retry.
+                    this.managers.get(account.name)?.invalidate();
+                    return false; // dead session — the caller can retry with a fresh one
+                }
+                // The session was fine — this is a 404 (no CUPS here) or a 5xx. Either
+                // way discovery did NOT complete, so it stays unlatched and a later
+                // call retries. `true` says only "do not re-mint the session".
+                return true;
+            }
             const laData = await laRes.json();
-            if (!laData.accounts?.length)
-                return;
+            if (!laData.accounts?.length) {
+                // The one genuinely permanent answer in this method: the endpoint
+                // responded and said there are no linked accounts. Latch it.
+                this.discoveryDone = true;
+                return true;
+            }
             // 2. Get original district info (needed for all linked accounts)
             const [origRes, currRes] = await Promise.all([
                 fetch(`${account.baseUrl}/campus/api/campus/user/userAccountSwitch/originalDistrict`, { headers: baseHeaders }),
                 fetch(`${account.baseUrl}/campus/api/campus/districts/current`, { headers: baseHeaders }),
             ]);
+            // Same shape as above: the session answered, so no re-mint — but
+            // discovery did not complete, so no latch either, and a later call
+            // retries.
             if (!origRes.ok || !currRes.ok)
-                return;
+                return true;
             const origData = await origRes.json();
             const currData = await currRes.json();
             // 3. For each linked account, get CUPS token and authenticate
@@ -334,10 +469,23 @@ export class ICClient {
                     console.error(`[ic] CUPS flow failed for ${linked.districtName}: ${e instanceof Error ? e.message : e}`);
                 }
             }
+            // Latched HERE, at the end of a run that got all the way through, rather
+            // than at the first probe. Everything between — originalDistrict,
+            // districts/current, the per-linked switch loop — can fail transiently,
+            // and latching early wrote linked districts off permanently on any of
+            // them. A per-district CUPS failure inside the loop is caught and logged
+            // above, so it does not block the latch: that one district is genuinely
+            // unavailable, the rest were established.
+            this.discoveryDone = true;
+            return true;
         }
         catch (e) {
-            // Don't fail primary login on linked-district errors
+            // Don't fail primary login on linked-district errors, and do NOT latch —
+            // an exception here means discovery did not complete, so a later call
+            // with a live session should try again. Reported as "answered" so the
+            // caller does not re-mint: the session was fine, something else broke.
             console.error(`[ic] Linked district discovery failed: ${e instanceof Error ? e.message : e}`);
+            return true;
         }
     }
     async download(district, path, destinationPath, opts = {}) {

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.4.4', // x-release-please-version
+    version: '2.5.0', // x-release-please-version
 };
 if (account) {
     const client = new ICClient(account, { refreshSession });

package/dist/session-cache.js

@@ -0,0 +1,95 @@
+import { createFileStatePersistence, resolveStateFile, } from '@chrischall/mcp-utils/session';
+import { readEnvVar, parseBoolEnv } from '@chrischall/mcp-utils';
+/**
+ * Where the primary district's session is cached between runs.
+ *
+ * Per district, because a deployment can point at more than one Infinite Campus
+ * instance and their sessions are unrelated — one shared file would have each
+ * clobber the other, and every record would then fail its own binding check.
+ */
+export function sessionCachePath(env = process.env, district) {
+    const seg = (district ?? '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '_').slice(0, 64);
+    return resolveStateFile({
+        env,
+        envVar: 'IC_SESSION_FILE',
+        subdir: '.infinitecampus-mcp',
+        fileName: seg === '' ? 'session.json' : `session-${seg}.json`,
+    });
+}
+/** Guard the stored envelope: a usable cookie header, and a login time. */
+function isStored(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const r = raw;
+    if (typeof r.sessionAt !== 'number')
+        return false;
+    const s = r.session;
+    if (s === null || typeof s !== 'object')
+        return false;
+    // An empty header is not a session — restoring one would look authenticated
+    // and then 401 every request until the expiry heuristic caught it.
+    if (typeof s.cookieHeader !== 'string' || s.cookieHeader === '')
+        return false;
+    // Required rather than optional: a restored session missing it would read as
+    // authenticated and then fail every write that needs the X-XSRF-TOKEN header.
+    return typeof s.xsrfToken === 'string';
+}
+/**
+ * The session cache for the PRIMARY district, or `null` when disabled.
+ *
+ * Only the primary is cached. Linked districts hold synthetic `(linked)`
+ * credentials and are authenticated by the primary's CUPS SSO switch, then
+ * `seed()`ed into their managers by discovery — so a linked session restored on
+ * its own would be a session with no `linkedTo` entry behind it. Caching the
+ * primary is what makes the expensive part free; discovery re-runs from the
+ * restored session and re-establishes the rest.
+ *
+ * Fetchproxy mode deliberately does NOT cache — see the note in the body. It
+ * would benefit most, and there is no identity to bind a record to, so a cached
+ * session could be restored for the wrong account.
+ */
+export function createSessionCache(opts) {
+    const env = opts.env ?? process.env;
+    if (!parseBoolEnv('IC_SESSION_CACHE', { env, default: true }))
+        return null;
+    const username = opts.username ?? readEnvVar('IC_USERNAME', { env });
+    const password = opts.password ?? readEnvVar('IC_PASSWORD', { env });
+    // Fetchproxy mode does NOT cache, and the reasoning is worth keeping.
+    //
+    // The previous review was right that it would benefit most — that mode cannot
+    // re-login unaided, so a cached session is what lets a cold start proceed with
+    // no browser. But there is nothing to bind a record to: the credentials are
+    // empty by design and the identity lives in the browser, known only after a
+    // lift. Binding to ['fetchproxy', baseUrl] means signing into a DIFFERENT IC
+    // account at the same instance restores the previous account's session, and
+    // the server then acts as the wrong parent against another family's student
+    // data. That is a worse outcome than a browser round-trip, so this declines.
+    //
+    // Making it safe needs an identity check on restore, which is a network call
+    // the sync load() path cannot make — a separate change, not a tweak here.
+    if (opts.browserBacked === true)
+        return null;
+    const boundTo = username && password
+        ? ['login', opts.baseUrl, username.trim().toLowerCase(), password].join('\u0000')
+        : null;
+    if (boundTo === null)
+        return null;
+    return createFileStatePersistence({
+        filePath: sessionCachePath(env, opts.district),
+        boundTo,
+        validate: (raw) => (isStored(raw) ? raw : null),
+    });
+}
+/**
+ * Report a cache write that failed. Not fatal in env mode: the session is
+ * re-mintable from the credentials. In fetchproxy mode a lost write costs the
+ * next start a trip through the browser, which is worse but still recoverable —
+ * and failing the request would not make the browser any more available.
+ *
+ * stderr only; stdout is the JSON-RPC channel.
+ */
+export function reportCacheWriteFailure(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    console.error(`[infinitecampus-mcp] could not cache the session (${detail}); continuing without ` +
+        'the cache — every restart will authenticate again until this is fixed.');
+}

package/mint.yaml

@@ -0,0 +1,72 @@
+version: 1
+name: Infinite Campus
+slug: infinitecampus
+summary: >-
+  Infinite Campus (Campus Parent) MCP — single-account with CUPS
+  auto-discovery. Two auth paths: IC_USERNAME/IC_PASSWORD, or sign in via
+  the fetchproxy browser extension.
+#
+# Hosting note (a comment, not user-facing summary text): this is a
+# BROWSER-BRIDGE MCP — it reaches its site through the user's signed-in
+# tab via the fetchproxy bridge. A bridged registration also needs runtime
+# `fly-shared`, `bridge: true` and a `bridgePortEnv`, which are registration
+# fields this manifest has no schema for (set them over the control API).
+# `state.dataDir` below is required for `bridge`.
+env:
+  - name: IC_BASE_URL
+    required: true
+    help: >-
+      Campus Parent portal base URL, e.g. https://campus.district.k12.example.us
+  - name: IC_DISTRICT
+    required: true
+    help: >-
+      Infinite Campus district app name (appName path segment from the portal
+      URL)
+  - name: IC_USERNAME
+    required: false
+    help: >-
+      Campus Parent portal username. Optional: leave unset to use the fetchproxy
+      browser-extension fallback.
+  - name: IC_PASSWORD
+    secret: true
+    required: false
+    help: >-
+      Campus Parent portal password. Required only when IC_USERNAME is set.
+  - name: IC_NAME
+    required: false
+    help: >-
+      Friendly name for the district (defaults to district appname)
+  - name: IC_DISABLE_FETCHPROXY
+    required: false
+    help: >-
+      Set to 1 to skip the fetchproxy browser-extension fallback (missing creds
+      become a hard error — useful in headless CI).
+  - name: IC_SESSION_CACHE
+    required: false
+    help: >-
+      Set to false to disable the on-disk session cache and authenticate on
+      every process start. Defaults to enabled.
+  - name: IC_SESSION_FILE
+    required: false
+    help: >-
+      Absolute path for the session cache file. Defaults to
+      $MCP_DATA_DIR/.infinitecampus-mcp/session-<district>.json.
+state:
+  dataDir: true
+  reason: >-
+    Two things live here. The fetchproxy identity is at
+    $HOME/.fetchproxy/identity/<name>.json and the pair code derives from it —
+    without a persistent $HOME every cold start mints a fresh identity and
+    re-prompts pairing in the browser, and the API refuses bridge without it.
+    The primary district's session is also cached at
+    $MCP_DATA_DIR/.infinitecampus-mcp/session-<district>.json (0600) when
+    credentials are configured, so a restart reuses it instead of logging in
+    again. Fetchproxy sessions are deliberately NOT cached: they carry no
+    identity to bind a record to, so a restored one could belong to a different
+    IC account at the same instance.
+# egress: intentionally NOT declared.
+#
+# This server's upstream host is per-deployment, so no fixed allowlist can
+# be correct here. On the isolated tier, allow:
+#   your district's Infinite Campus host, from IC_BASE_URL (districts are each on their own host, e.g. <district>.infinitecampus.org)
+# Everything else in this file applies regardless of which host that is.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "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>",
@@ -32,19 +32,22 @@
     ".claude-plugin",
     "skills",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
     "dev": "node --env-file=.env dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "npm run typecheck && vitest run",
+    "test:coverage": "npm run typecheck && vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
-    "@fetchproxy/bootstrap": "^1.11.0",
-    "@fetchproxy/server": "^1.7.0",
+    "@chrischall/mcp-utils": "^0.18.0",
+    "@fetchproxy/bootstrap": "^2.0.0",
+    "@fetchproxy/server": "^2.0.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.4",
+  "version": "2.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "infinitecampus-mcp",
-      "version": "2.4.4",
+      "version": "2.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -52,6 +52,18 @@
           "description": "Set to 1 to skip the fetchproxy browser-extension fallback (missing creds become a hard error — useful in headless CI).",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "IC_SESSION_CACHE",
+          "description": "Set to false to disable the on-disk session cache and re-authenticate on every process start. Defaults to enabled.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "IC_SESSION_FILE",
+          "description": "Absolute path for the session cache file. Defaults to $MCP_DATA_DIR/.infinitecampus-mcp/session-<district>.json.",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }