infinitecampus-mcp 2.1.2 → 2.1.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.1.2"
+    "version": "2.1.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.1.2",
+      "version": "2.1.3",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -28,15 +28,19 @@ Tools that the harness will gate as write/IO operations: `ic_download_document`.
 
 ## Configuration
 
-Set a single set of env vars for your primary Infinite Campus account:
-
-```
-IC_BASE_URL=https://campus.springfield.k12.example.us
-IC_DISTRICT=springfield
-IC_USERNAME=parent@example.com
-IC_PASSWORD=...
-IC_NAME=Springfield           # optional, defaults to IC_DISTRICT
-```
+`infinitecampus-mcp` tries two auth paths in priority order; whichever succeeds first is used. Existing setups keep working unchanged.
+
+1. **Env-var credentials (legacy).** Set all four:
+   ```
+   IC_BASE_URL=https://campus.springfield.k12.example.us
+   IC_DISTRICT=springfield
+   IC_USERNAME=parent@example.com
+   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.
+
+Set `IC_DISABLE_FETCHPROXY=1` to opt out of the fallback (turns missing credentials into a hard error — useful in headless CI).
 
 Linked districts (via CUPS SSO) are auto-discovered after primary login — a parent with kids in two districts only configures the primary. No extra config needed. If you have truly separate IC instances with different credentials, run two MCP instances.
 

package/dist/auth.js

@@ -0,0 +1,134 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Auth resolution — Pattern A template
+// ────────────────────────────────────────────────────────────────────────────
+//
+// Infinite Campus supports two auth paths. This file picks one, in priority
+// order, and hands the chosen path to `ICClient`. It mirrors the Pattern A
+// shape used by ofw-mcp/src/auth.ts (and signupgenius-mcp, zola-mcp, …) so
+// all sibling MCPs in this family stay structurally aligned.
+//
+// THE PATHS, in priority order:
+//
+//   1. Password login (existing)
+//      IC_BASE_URL + IC_DISTRICT + IC_USERNAME + IC_PASSWORD set →
+//      `loadAccount()` returns an Account with credentials; `ICClient.login()`
+//      POSTs to `verify.jsp` exactly as before. Unchanged from pre-fetchproxy
+//      behavior. The 401 retry + linked-district CUPS SSO discovery in
+//      `client.ts` both keep working.
+//
+//   2. fetchproxy fallback (new)
+//      IC_BASE_URL + IC_DISTRICT set but no IC_USERNAME/IC_PASSWORD →
+//      `@fetchproxy/bootstrap` opens a one-shot WebSocket bridge to the
+//      0.3.0 extension, reads `JSESSIONID` (HttpOnly) and `XSRF-TOKEN`
+//      (non-HttpOnly) cookies from the user's signed-in IC portal tab via
+//      `chrome.cookies.get`, then closes the bridge. The client receives
+//      pre-loaded session cookies and skips the login POST. All subsequent
+//      IC calls go out via plain Node `fetch()` — fetchproxy is NOT in the
+//      request hot path.
+//
+//      The CUPS linked-district token-minting flow in `client.ts` continues
+//      to work unchanged because it only needs the primary district's
+//      cookies, which fetchproxy provides on initial bootstrap.
+//
+//      IC_BASE_URL + IC_DISTRICT remain REQUIRED in this mode — the MCP
+//      needs to know which host to declare (the extension whitelists by
+//      host suffix) and which district appName to dispatch CUPS calls on.
+//
+//      Users opt out with IC_DISABLE_FETCHPROXY=1 (e.g. headless CI where
+//      no extension is available — turns missing creds into a hard error).
+//
+//   3. Error
+//      Nothing to authenticate with. We throw a message that names both
+//      escape hatches: set IC_USERNAME/IC_PASSWORD, OR install the extension
+//      and sign in.
+//
+// Testability:
+//   - `@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 { loadAccount } from './config.js';
+import pkg from '../package.json' with { type: 'json' };
+function readEnv(key) {
+    const raw = process.env[key];
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed === 'undefined' || trimmed === 'null')
+        return undefined;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+function fetchproxyDisabled() {
+    const raw = readEnv('IC_DISABLE_FETCHPROXY');
+    if (raw === undefined)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+}
+/**
+ * Resolve IC auth using the path priority described at the top of this file.
+ * Throws with an actionable message when no path succeeds.
+ */
+export async function resolveAuth() {
+    // `loadAccount()` enforces IC_BASE_URL + IC_DISTRICT + https validation
+    // and the "both username/password or neither" rule. Any of those failing
+    // is a user mistake; we let them propagate so the user can fix the typo.
+    const account = loadAccount();
+    // ── Path 1: full env-var credentials.
+    if (account.username && account.password) {
+        return { account, source: 'env' };
+    }
+    // ── Path 2: fetchproxy fallback.
+    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) {
+            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);
+        }
+    }
+    // ── 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).');
+}