infinitecampus-mcp 2.1.2 → 2.2.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.2.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.2.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.2.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:
+`infinitecampus-mcp` tries two auth paths in priority order; whichever succeeds first is used. Existing setups keep working unchanged.
 
-```
-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
-```
+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.
 
@@ -45,3 +49,25 @@ See `.env.example`.
 ## Status
 
 Unofficial — not affiliated with Infinite Campus. AI-maintained.
+
+## Acknowledgement of Terms
+
+By using this MCP server, you acknowledge and agree to the following:
+
+**1. This server accesses your own Campus Parent account.** Auth happens via your own credentials, scoped to the student records your school district has authorized you to view. It does not — and cannot — access anyone else's student records.
+
+**2. [Infinite Campus's Terms of Use](https://www.infinitecampus.com/terms/terms-of-use) govern your use of this server**, just as they govern your direct use of Campus Parent. The clauses most relevant here:
+
+> Users may not access, use, or search the Services by any means other than our publicly supported interfaces (for example, scraping or using the content to train artificial intelligence software).
+
+And: *"You are responsible for safeguarding the password that you use to access the Service and you agree not to disclose your password to any third party."*
+
+You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server. This server uses Infinite Campus's mobile-app JSON endpoints (`/campus/api/oneRosterCampus`, `/portal/api/...`) which are not "publicly supported interfaces" — IC may treat this as a ToS violation.
+
+**3. Personal, parent/student use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Infinite Campus, Inc. or any school district. It is a personal automation tool for an authorized Campus Parent / Campus Student user to read their own (or their student's) records. **Do not** use it to bulk-extract student data, share another family's grades, or train AI models on student records.
+
+**4. FERPA + COPPA apply.** Student educational records are protected under the federal Family Educational Rights and Privacy Act (FERPA), and student data for under-13 users is additionally covered by COPPA. Even though *your* parent-portal access is lawful, **how you store, redistribute, or feed that data into LLMs is regulated**. Treat any output from this server (grades, attendance, behavior records, schedules) as confidential student data. Do not put it in shared LLM contexts, do not paste it into screenshots, and do not train models on it.
+
+**5. You accept full responsibility** for any consequences of using this server in connection with your Campus Parent account — rate limiting, account warnings, district IT investigations, or any enforcement action your district or Infinite Campus takes. Your district may have additional acceptable-use policies (acceptable-use agreements, parent handbooks) that further restrict automation. If your district or Infinite Campus objects to your use, stop using this server.
+
+This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Infinite Campus's actual ToU or any school district's policies.

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).');
+}