infinitecampus-mcp 2.1.2 → 2.2.3

package/dist/client.js

@@ -7,13 +7,50 @@ export class ICClient {
     linkedTo = new Map(); // linkedDistrictName → primaryDistrictName
     primaryName;
     featuresCache = new Map();
-    constructor(account) {
+    /**
+     * True when the primary account has empty creds (fetchproxy mode). The
+     * client uses pre-loaded cookies in place of the `verify.jsp` POST and
+     * cannot re-login when those cookies expire — the user must re-sign-in
+     * in the browser. CUPS linked-district discovery still runs lazily on
+     * first call to `ensureDiscovery()`.
+     */
+    fetchproxyMode = false;
+    fetchproxyDiscoveryRan = false;
+    /**
+     * `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.
+     */
+    constructor(account, opts = {}) {
         this.accounts.set(account.name, account);
         this.primaryName = account.name;
+        if (opts.preloaded) {
+            this.sessions.set(account.name, {
+                cookie: opts.preloaded.cookieHeader,
+                xsrfToken: opts.preloaded.xsrfToken,
+                loggedInAt: Date.now(),
+                loginInFlight: null,
+            });
+            this.fetchproxyMode = true;
+        }
     }
     async ensureDiscovery() {
         // Ensure primary account is logged in, which triggers CUPS linked-district discovery
         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.
+        if (this.fetchproxyMode && !this.fetchproxyDiscoveryRan) {
+            this.fetchproxyDiscoveryRan = true;
+            await this.discoverLinkedDistricts(this.accounts.get(this.primaryName));
+        }
     }
     listDistricts() {
         return [...this.accounts.values()].map((a) => ({
@@ -50,6 +87,14 @@ export class ICClient {
                 throw new UnknownDistrictError(district, [...this.accounts.keys()]);
         }
         await this.ensureSession(account);
+        // In fetchproxy mode, login() never runs 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);
+        }
         return this.doRequest(account, path, opts, false);
     }
     async ensureSession(account) {
@@ -73,6 +118,15 @@ export class ICClient {
         }
     }
     async login(account) {
+        // 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.
+        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' });

package/dist/config.js

@@ -16,33 +16,53 @@ function readVar(env, key) {
         return undefined;
     return trimmed;
 }
+/**
+ * Load the Account from env vars. IC_BASE_URL + IC_DISTRICT are ALWAYS
+ * required (the MCP needs to know which host to talk to and which district to
+ * dispatch on). IC_USERNAME + IC_PASSWORD must be set together or omitted
+ * together — partial creds are treated as a user mistake and throw rather
+ * than falling through to fetchproxy (which would mask the typo).
+ *
+ * When username/password are omitted the resolved Account carries empty
+ * strings. The caller (`resolveAuth()`) treats that as "try fetchproxy".
+ */
 export function loadAccount(env = process.env) {
     const baseUrl = readVar(env, 'IC_BASE_URL');
     const district = readVar(env, 'IC_DISTRICT');
     const username = readVar(env, 'IC_USERNAME');
     const password = readVar(env, 'IC_PASSWORD');
     const name = readVar(env, 'IC_NAME') ?? district;
+    // IC_BASE_URL + IC_DISTRICT are always required.
     const missing = [];
     if (!baseUrl)
         missing.push('IC_BASE_URL');
     if (!district)
         missing.push('IC_DISTRICT');
-    if (!username)
-        missing.push('IC_USERNAME');
-    if (!password)
-        missing.push('IC_PASSWORD');
     if (missing.length > 0) {
         throw new Error(`Missing required env var(s): ${missing.join(', ')}. ` +
-            'Set IC_BASE_URL, IC_DISTRICT, IC_USERNAME, and IC_PASSWORD.');
+            'Set IC_BASE_URL (your portal URL) and IC_DISTRICT (the app-name path segment).');
     }
     if (!/^https:\/\//.test(baseUrl)) {
         throw new Error(`IC_BASE_URL must be an https URL, got: '${baseUrl}'`);
     }
+    // Username + password must be set together or omitted together. Partial
+    // configuration is almost always a typo, so surface it rather than silently
+    // falling through to fetchproxy.
+    if ((username && !password) || (!username && password)) {
+        const partialMissing = [];
+        if (!username)
+            partialMissing.push('IC_USERNAME');
+        if (!password)
+            partialMissing.push('IC_PASSWORD');
+        throw new Error(`Missing required env var(s) for password auth: ${partialMissing.join(', ')}. ` +
+            'Set both IC_USERNAME and IC_PASSWORD, or leave both unset to use the fetchproxy ' +
+            'fallback (requires the fetchproxy browser extension and a signed-in IC portal tab).');
+    }
     return {
         name: name,
         baseUrl: baseUrl.replace(/\/$/, ''),
         district: district,
-        username: username,
-        password: password,
+        username: username ?? '',
+        password: password ?? '',
     };
 }

package/dist/index.js

@@ -13,7 +13,7 @@ catch {
 }
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { loadAccount } from './config.js';
+import { resolveAuth } from './auth.js';
 import { ICClient } from './client.js';
 import { registerDistrictTools } from './tools/districts.js';
 import { registerStudentTools } from './tools/students.js';
@@ -32,27 +32,51 @@ import { registerTeacherTools } from './tools/teachers.js';
 import { registerAssessmentTools } from './tools/assessments.js';
 import { registerFeeTools } from './tools/fees.js';
 import { registerFeaturesTools } from './tools/features.js';
-const account = loadAccount();
-const client = new ICClient(account);
-const server = new McpServer({ name: 'infinitecampus', version: '2.1.2' });
-registerDistrictTools(server, client);
-registerStudentTools(server, client);
-registerScheduleTools(server, client);
-registerAssignmentTools(server, client);
-registerGradeTools(server, client);
-registerAttendanceTools(server, client);
-registerBehaviorTools(server, client);
-registerFoodServiceTools(server, client);
-registerMessageTools(server, client);
-registerDocumentTools(server, client);
-registerCalendarTools(server, client);
-registerAttendanceEventsTools(server, client);
-registerRecentGradesTools(server, client);
-registerTeacherTools(server, client);
-registerAssessmentTools(server, client);
-registerFeeTools(server, client);
-registerFeaturesTools(server, client);
-console.error(`[infinitecampus-mcp] District: ${account.name} (${account.baseUrl})`);
+// Defer config errors so the server can still start cleanly when env vars
+// aren't set (e.g. during the host's install-time smoke test, before the
+// user has filled in user_config OR the user hasn't yet signed into their
+// 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 source;
+let configError = null;
+try {
+    const resolved = await resolveAuth();
+    account = resolved.account;
+    preloaded = resolved.preloaded;
+    source = resolved.source;
+}
+catch (e) {
+    configError = e;
+}
+const server = new McpServer({ name: 'infinitecampus', version: '2.2.3' }); // x-release-please-version
+if (account) {
+    const client = new ICClient(account, { preloaded });
+    registerDistrictTools(server, client);
+    registerStudentTools(server, client);
+    registerScheduleTools(server, client);
+    registerAssignmentTools(server, client);
+    registerGradeTools(server, client);
+    registerAttendanceTools(server, client);
+    registerBehaviorTools(server, client);
+    registerFoodServiceTools(server, client);
+    registerMessageTools(server, client);
+    registerDocumentTools(server, client);
+    registerCalendarTools(server, client);
+    registerAttendanceEventsTools(server, client);
+    registerRecentGradesTools(server, client);
+    registerTeacherTools(server, client);
+    registerAssessmentTools(server, client);
+    registerFeeTools(server, client);
+    registerFeaturesTools(server, client);
+    const suffix = source === 'fetchproxy' ? ' [via fetchproxy]' : '';
+    console.error(`[infinitecampus-mcp] District: ${account.name} (${account.baseUrl})${suffix}`);
+}
+else {
+    console.error(`[infinitecampus-mcp] Not configured: ${configError?.message ?? 'unknown error'}`);
+    console.error('[infinitecampus-mcp] Server is running with no tools registered. Set the required env vars and reinstall.');
+}
 console.error('[infinitecampus-mcp] Developed and maintained by AI (Claude). Use at your own discretion.');
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.1.2",
+  "version": "2.2.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>",
@@ -36,21 +36,22 @@
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
-    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
+    "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"
   },
   "dependencies": {
+    "@fetchproxy/bootstrap": "^0.6.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "dotenv": "^17.4.0",
-    "zod": "^4.3.6"
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.5.2",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/infinitecampus-mcp",
     "source": "github"
   },
-  "version": "2.1.2",
+  "version": "2.2.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "infinitecampus-mcp",
-      "version": "2.1.2",
+      "version": "2.2.3",
       "transport": {
         "type": "stdio"
       },
@@ -30,14 +30,14 @@
         },
         {
           "name": "IC_USERNAME",
-          "description": "Campus Parent portal username",
-          "isRequired": true,
+          "description": "Campus Parent portal username. Optional: leave unset to use the fetchproxy browser-extension fallback.",
+          "isRequired": false,
           "format": "string"
         },
         {
           "name": "IC_PASSWORD",
-          "description": "Campus Parent portal password",
-          "isRequired": true,
+          "description": "Campus Parent portal password. Required only when IC_USERNAME is set.",
+          "isRequired": false,
           "format": "string",
           "isSecret": true
         },
@@ -46,6 +46,12 @@
           "description": "Friendly name for the district (defaults to district appname)",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "IC_DISABLE_FETCHPROXY",
+          "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"
         }
       ]
     }