infinitecampus-mcp 2.3.1 → 2.3.3

package/dist/client.js

@@ -1,5 +1,6 @@
 import { writeFile, stat } from 'fs/promises';
 import { dirname } from 'path';
+import { parseCookieJar } from '@chrischall/mcp-utils';
 const SESSION_TTL_MS = 5 * 60 * 60 * 1000; // 5h, slightly under IC's typical 6h
 export class ICClient {
     accounts = new Map();
@@ -43,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));
@@ -118,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>
@@ -159,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 {
@@ -342,39 +375,23 @@ export class ICClient {
     }
 }
 /**
- * Parse Set-Cookie headers into a deduplicated cookie string + XSRF token.
- *
- * IC's login response sets ~20 cookies including deletion markers (Max-Age=0).
- * Sending both `appName=` (delete) and `appName=springfield` (set) causes IC to
- * reject requests with "conflicting app name values". This parser:
- * - Filters out cookies with Max-Age=0 (deletion markers)
- * - Deduplicates by name (last value wins)
- * - Extracts XSRF-TOKEN separately for the X-XSRF-TOKEN request header
+ * Parse Set-Cookie headers into a deduplicated Cookie header + XSRF token via
+ * `parseCookieJar` (see inline comment for the splitter/jar details).
  */
 function parseSetCookies(headers) {
+    // Prefer the structured getSetCookie() split (one cookie per array entry,
+    // what real Node fetch Responses provide). Only when it's unavailable do we
+    // fall back to naively comma-splitting the joined header — kept identical to
+    // the original so the edge-case behavior (commas inside attribute lists) is
+    // preserved rather than inheriting parseCookieJar's smarter-but-different
+    // splitter. parseCookieJar then does the jar logic: drop deletion markers
+    // (Max-Age=0 / expired Expires) and empty values, dedupe by name. That's
+    // load-bearing so the synthesized Cookie header never carries both the
+    // `appName=` deletion and the real value (IC rejects "conflicting app name").
     const raw = headers.getSetCookie?.() ?? [];
-    const headerStrings = raw.length > 0 ? raw : splitFallback(headers.get('set-cookie'));
-    const jar = new Map();
-    let xsrfToken = '';
-    for (const entry of headerStrings) {
-        // Check for Max-Age=0 → this is a cookie deletion, skip it
-        if (/Max-Age=0/i.test(entry))
-            continue;
-        const nameValue = entry.split(';')[0].trim();
-        const eqIdx = nameValue.indexOf('=');
-        if (eqIdx < 1)
-            continue;
-        const name = nameValue.substring(0, eqIdx);
-        const value = nameValue.substring(eqIdx + 1);
-        // Skip cookies with empty values (clearing instructions)
-        if (!value)
-            continue;
-        jar.set(name, value);
-        if (name === 'XSRF-TOKEN')
-            xsrfToken = value;
-    }
-    const cookieHeader = [...jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
-    return { cookieHeader, xsrfToken };
+    const entries = raw.length > 0 ? raw : splitFallback(headers.get('set-cookie'));
+    const { cookies, cookieHeader } = parseCookieJar(entries);
+    return { cookieHeader, xsrfToken: cookies['XSRF-TOKEN'] ?? '' };
 }
 function splitFallback(header) {
     if (!header)
@@ -394,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/config.js

@@ -1,20 +1,14 @@
+import { readEnvVar } from '@chrischall/mcp-utils';
 /**
  * Read an env var, trim whitespace, and treat as unset if blank or if the value
  * looks like an unsubstituted shell placeholder (e.g. `${FOO}`) — defends
  * against MCP hosts that pass .mcp.json env blocks through unexpanded.
+ *
+ * Thin adapter over mcp-utils' `readEnvVar` (same defensive semantics), keeping
+ * the local `(env, key)` arg order so the call sites below stay unchanged.
  */
 function readVar(env, key) {
-    const raw = 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;
+    return readEnvVar(key, { env });
 }
 /**
  * Load the Account from env vars. IC_BASE_URL + IC_DISTRICT are ALWAYS

package/dist/index.js

@@ -1,18 +1,16 @@
 #!/usr/bin/env node
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-try {
-    const { config } = await import('dotenv');
-    const __dirname = dirname(fileURLToPath(import.meta.url));
-    // quiet:true suppresses dotenv's startup banner — required because MCP uses
-    // stdout for JSON-RPC and any extra output corrupts the stream.
-    config({ path: join(__dirname, '..', '.env'), override: false, quiet: true });
-}
-catch {
-    // dotenv not available — rely on process.env
-}
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadDotenvSafely, runMcp } from '@chrischall/mcp-utils';
+// quiet load of the local .env (no-throw, silent when the file is absent —
+// e.g. inside an mcpb bundle). Path is resolved next to dist/ so the same
+// `..`/.env that the previous inline dotenv call used still applies.
+// override:false keeps real host-provided env winning. stdout stays clean
+// for JSON-RPC (loadDotenvSafely forces dotenv's quiet:true).
+await loadDotenvSafely({
+    path: join(dirname(fileURLToPath(import.meta.url)), '..', '.env'),
+    override: false,
+});
 import { resolveAuth } from './auth.js';
 import { ICClient } from './client.js';
 import { registerDistrictTools } from './tools/districts.js';
@@ -32,6 +30,7 @@ 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 AI_NOTICE = '[infinitecampus-mcp] Developed and maintained by AI (Claude). Use at your own discretion.';
 // 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
@@ -50,33 +49,43 @@ try {
 catch (e) {
     configError = e;
 }
-const server = new McpServer({ name: 'infinitecampus', version: '2.3.1' }); // x-release-please-version
+// Hand off to mcp-utils' runMcp for the connect + stdio transport + graceful
+// shutdown. We keep the deferred-config-error pattern by deciding the registrar
+// list and banner up here: when configured we wire every
+// register<Domain>Tools(server, client) call; when not, we register no tools so
+// the host's install-time tools/list still succeeds and the user gets an
+// actionable stderr message (banner) instead of a crash loop.
+const COMMON = {
+    name: 'infinitecampus',
+    version: '2.3.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 tools = [
+        registerDistrictTools,
+        registerStudentTools,
+        registerScheduleTools,
+        registerAssignmentTools,
+        registerGradeTools,
+        registerAttendanceTools,
+        registerBehaviorTools,
+        registerFoodServiceTools,
+        registerMessageTools,
+        registerDocumentTools,
+        registerCalendarTools,
+        registerAttendanceEventsTools,
+        registerRecentGradesTools,
+        registerTeacherTools,
+        registerAssessmentTools,
+        registerFeeTools,
+        registerFeaturesTools,
+    ];
     const suffix = source === 'fetchproxy' ? ' [via fetchproxy]' : '';
-    console.error(`[infinitecampus-mcp] District: ${account.name} (${account.baseUrl})${suffix}`);
+    const districtLine = `[infinitecampus-mcp] District: ${account.name} (${account.baseUrl})${suffix}`;
+    await runMcp({ ...COMMON, deps: client, tools, banner: `${districtLine}\n${AI_NOTICE}` });
 }
 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.');
+    const notConfigured = `[infinitecampus-mcp] Not configured: ${configError?.message ?? 'unknown error'}\n` +
+        '[infinitecampus-mcp] Server is running with no tools registered. Set the required env vars and reinstall.';
+    await runMcp({ ...COMMON, tools: [], banner: `${notConfigured}\n${AI_NOTICE}` });
 }
-console.error('[infinitecampus-mcp] Developed and maintained by AI (Claude). Use at your own discretion.');
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/dist/tools/_shared.js

@@ -1,6 +1,12 @@
-/** Wrap a value as an MCP text content block — the standard tool return shape. */
+import { textResult } from '@chrischall/mcp-utils';
+/**
+ * Wrap a value as an MCP text content block — the standard tool return shape.
+ * Thin re-export of mcp-utils' `textResult` so the whole fleet shares one
+ * pretty-printed-JSON formatter; the local name is kept to avoid churning
+ * every tool call site.
+ */
 export function textContent(data) {
-    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    return textResult(data);
 }
 /** Detect "IC 404 ..." errors thrown by ICClient.request for endpoints that don't exist. */
 export function is404(e) {

package/dist/tools/messages.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { extractPlainTextFromHtml } from '@chrischall/mcp-utils/html';
 import { textContent, toArray } from './_shared.js';
 const listArgs = z.object({
     district: z.string(),
@@ -44,29 +45,18 @@ export function normalizeMessageUrl(input) {
  * The HTML has:
  *   <title>Message -- <subject></title>
  *   body with "Message: <subject>", "Date: MM/DD/YYYY", then the message body.
- * Dependency-free: no DOM parser, just regex + tag stripping.
+ * Dependency-free: title via regex, body via mcp-utils'
+ * `extractPlainTextFromHtml` (script/style strip + tag strip + entity decode +
+ * whitespace collapse — the shared fleet helper this extractor was hoisted from).
  */
 export function parseMessageHtml(html, url) {
     // Extract <title>
     const titleMatch = html.match(/<title>([^<]*)<\/title>/i);
     let subject = titleMatch ? titleMatch[1].trim() : '';
     subject = subject.replace(/^Message\s*--\s*/i, '');
-    // Strip <script> and <style> blocks first
-    let text = html
-        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
-        .replace(/<style[\s\S]*?<\/style>/gi, ' ');
-    // Strip remaining tags
-    text = text.replace(/<[^>]+>/g, ' ');
-    // Decode a few common entities
-    text = text
-        .replace(/&nbsp;/g, ' ')
-        .replace(/&amp;/g, '&')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&#39;/g, "'");
-    // Collapse whitespace
-    text = text.replace(/\s+/g, ' ').trim();
+    // Strip the body down to plain text (script/style content removed, tags
+    // dropped, entities decoded, whitespace collapsed).
+    const text = extractPlainTextFromHtml(html);
     // Extract "Date: MM/DD/YYYY" if present
     const dateMatch = text.match(/Date:\s*(\d{1,2}\/\d{1,2}\/\d{2,4})/);
     const date = dateMatch ? dateMatch[1] : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.3.1",
+  "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>",
@@ -42,10 +42,12 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.8.0",
-    "@fetchproxy/server": "^0.8.0",
+    "@chrischall/mcp-utils": "^0.5.0",
+    "@fetchproxy/bootstrap": "^1.0.0",
+    "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
+    "node-html-parser": "^7.1.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/server.json

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