infinitecampus-mcp 2.2.3 → 2.3.0

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.2.3"
+    "version": "2.3.0"
   },
   "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.2.3",
+      "version": "2.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/dist/auth.js

@@ -47,6 +47,7 @@
 //   - `loadAccount()` (the existing env-var resolver) is reused as-is so the
 //     legacy paths keep working unchanged.
 import { bootstrap } from '@fetchproxy/bootstrap';
+import { classifyBridgeError } from '@fetchproxy/server';
 import { loadAccount } from './config.js';
 import pkg from '../package.json' with { type: 'json' };
 function readEnv(key) {
@@ -123,6 +124,18 @@ export async function resolveAuth() {
             };
         }
         catch (e) {
+            // 0.8.0+ typed-error discrimination. The fetchproxy server already
+            // retries once on SW eviction (bridgeReviveDelayMs=2000 default), so
+            // a thrown FetchproxyBridgeDownError means the retry also failed —
+            // the extension's service worker is genuinely down and the user
+            // needs to wake it. The `.hint` is the actionable copy
+            // ("click the extension toolbar icon...") that we'd otherwise have
+            // to hand-write here. Surface it verbatim so users in path 2 get
+            // the same self-service guidance as path 3.
+            if (classifyBridgeError(e) === 'bridge_down') {
+                const downErr = e;
+                throw new Error(`IC auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`);
+            }
             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);
         }

package/dist/bundle.js

@@ -35927,6 +35927,52 @@ var FetchproxyHttpError = class extends Error {
     this.name = "FetchproxyHttpError";
   }
 };
+var FetchproxyBridgeDownError = class extends FetchproxyProtocolError {
+  originalError;
+  retryAttempted;
+  op;
+  url;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time (the same port `listen()` bound to). */
+  port;
+  hint;
+  constructor(args) {
+    const retryAttempted = args.retryAttempted ?? false;
+    const op = args.op ?? "fetch";
+    const retryClause = retryAttempted ? `Server already burned a one-shot lazy-revive retry; SW is still down. ` : `Server lazy-revive retry was disabled (bridgeReviveDelayMs unset/0). `;
+    const hint = `the fetchproxy extension's service worker is not responding ("${args.originalError}"). Chrome evicts extension service workers after ~30s idle by default. ${retryClause}Wake it by clicking the fetchproxy extension toolbar icon, then retry. If it keeps happening, reload the extension from chrome://extensions.`;
+    super(`fetchproxy bridge down during ${op}${args.url ? ` (${args.url})` : ""}. ${hint}`);
+    this.name = "FetchproxyBridgeDownError";
+    this.originalError = args.originalError;
+    this.retryAttempted = retryAttempted;
+    this.op = op;
+    if (args.url !== void 0)
+      this.url = args.url;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.hint = hint;
+  }
+};
+var FetchproxyTimeoutError = class extends FetchproxyProtocolError {
+  url;
+  timeoutMs;
+  /** 0.8.0+: bridge role at throw time; `null` if listen() hadn't bound yet. */
+  role;
+  /** 0.8.0+: bridge port at throw time. */
+  port;
+  /** 0.8.0+: actual elapsed milliseconds when the timer won the race. */
+  elapsedMs;
+  constructor(args) {
+    super(`fetchproxy: ${args.url} did not respond within ${args.timeoutMs}ms`);
+    this.name = "FetchproxyTimeoutError";
+    this.url = args.url;
+    this.timeoutMs = args.timeoutMs;
+    this.role = args.role ?? null;
+    this.port = args.port ?? 0;
+    this.elapsedMs = args.elapsedMs ?? args.timeoutMs;
+  }
+};
 var SUBDOMAIN_LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
 function assertSubdomainLabel(label) {
   if (!SUBDOMAIN_LABEL_RE.test(label)) {
@@ -35964,6 +36010,18 @@ var FetchproxyServer = class {
   hostHandle = null;
   peerHandle = null;
   nextRequestId = 1;
+  // 0.8.0+: process-wide freshness counters surfaced via bridgeHealth().
+  // Replaces the local copies every downstream MCP was rolling on top
+  // of its own transport adapter — see realty-mcp cohort drift notes.
+  // Updated by recordSuccess / recordFailure from fetch + capture paths.
+  // `lastExtensionMessageAt` (#23 ask 4) is updated whenever any inner
+  // frame from the extension arrives — gives extension-side liveness
+  // distinct from per-call success/failure.
+  lastSuccessAt = null;
+  lastFailureAt = null;
+  lastFailureReason = null;
+  consecutiveFailures = 0;
+  lastExtensionMessageAt = null;
   pending = /* @__PURE__ */ new Map();
   // Separate pending map for read_cookies so the response shape (cookies
   // string vs status/body) doesn't have to share a union type with fetch.
@@ -36032,6 +36090,12 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
+      // adapter was about to set these to the same numbers anyway; the
+      // back-door is `0` (explicit opt-out) if a caller genuinely wants
+      // the legacy hang-forever / fail-once-on-SW-eviction behavior.
+      fetchTimeoutMs: opts.fetchTimeoutMs ?? 3e4,
+      bridgeReviveDelayMs: opts.bridgeReviveDelayMs ?? 2e3,
       identityDir: opts.identityDir,
       onPairCode: opts.onPairCode
     };
@@ -36167,7 +36231,7 @@ var FetchproxyServer = class {
     }
   }
   pairingErrorMessage(code) {
-    return `fetchproxy: pairing required for ${this.opts.serverName} \u2014 open the fetchproxy extension popup in Chrome and approve the pair request. Verify the pair code matches: ${code}`;
+    return `fetchproxy transport error: pairing required for ${this.opts.serverName}. Tell the user to open the Transporter browser extension popup and approve the pair request. The pair code is: ${code} \u2014 display this code to the user so they can verify it matches.`;
   }
   /**
    * Raw single-shot fetch through the bridge. Most callers should prefer
@@ -36188,8 +36252,71 @@ var FetchproxyServer = class {
     const pendingCode = this.currentPendingPairCode();
     if (pendingCode !== null) {
       const error51 = this.pairingErrorMessage(pendingCode);
-      return { ok: false, error: error51, kind: classifyFetchError(error51) };
+      return {
+        ok: false,
+        error: error51,
+        kind: classifyFetchError(error51),
+        retryAttempted: false
+      };
+    }
+    const first = await this._fetchOnceWithTimeout(init);
+    const reviveMs = this.opts.bridgeReviveDelayMs;
+    let final = first;
+    if (!first.ok && first.kind === "content_script_unreachable" && reviveMs !== void 0 && reviveMs > 0) {
+      await new Promise((r) => setTimeout(r, reviveMs));
+      const second = await this._fetchOnceWithTimeout(init);
+      if (second.ok)
+        this.recordSuccess();
+      else
+        this.recordFailure(`${second.kind ?? "other"}: ${second.error}`);
+      return { ...second, retryAttempted: true };
     }
+    if (first.ok)
+      this.recordSuccess();
+    else
+      this.recordFailure(`${first.kind ?? "other"}: ${first.error}`);
+    return { ...first, retryAttempted: false };
+  }
+  /**
+   * 0.8.0+: snapshot of the bridge's process-wide freshness counters,
+   * suitable for surfacing through a downstream MCP's healthcheck tool.
+   * Counters reset on a success (consecutiveFailures), accumulate
+   * across the process lifetime otherwise. Replaces the per-MCP
+   * duplication the realty cohort had been rolling in their adapters.
+   * `lastExtensionMessageAt` is updated whenever ANY inner frame
+   * arrives from the extension — gives extension-side liveness
+   * distinct from server-side success/failure of the user-visible
+   * call (addresses #23 ask 4).
+   */
+  bridgeHealth() {
+    return {
+      role: this.role,
+      port: this.opts.port,
+      serverVersion: this.opts.version,
+      fetchTimeoutMs: this.opts.fetchTimeoutMs ?? 0,
+      bridgeReviveDelayMs: this.opts.bridgeReviveDelayMs ?? 0,
+      lastSuccessAt: this.lastSuccessAt,
+      lastFailureAt: this.lastFailureAt,
+      lastFailureReason: this.lastFailureReason,
+      consecutiveFailures: this.consecutiveFailures,
+      lastExtensionMessageAt: this.lastExtensionMessageAt
+    };
+  }
+  recordSuccess() {
+    this.lastSuccessAt = Date.now();
+    this.consecutiveFailures = 0;
+  }
+  recordFailure(reason) {
+    this.lastFailureAt = Date.now();
+    this.lastFailureReason = reason;
+    this.consecutiveFailures += 1;
+  }
+  /**
+   * Single bridge round-trip, wrapped by `fetchTimeoutMs` when set.
+   * On timeout returns the `{ok:false, kind:'timeout'}` envelope —
+   * the throwing surface is the convenience methods.
+   */
+  async _fetchOnceWithTimeout(init) {
     const id = this.nextRequestId++;
     const inner = { type: "request", id, op: "fetch", init };
     const pending = new Promise((resolve) => {
@@ -36200,7 +36327,61 @@ var FetchproxyServer = class {
     } else if (this.peerHandle) {
       await this.peerHandle.sendInner(inner);
     }
-    return pending;
+    const timeoutMs = this.opts.fetchTimeoutMs;
+    if (timeoutMs === void 0 || timeoutMs <= 0)
+      return pending;
+    let timer;
+    const start = Date.now();
+    try {
+      return await Promise.race([
+        pending,
+        new Promise((resolve) => {
+          timer = setTimeout(() => {
+            this.pending.delete(id);
+            const elapsedMs = Date.now() - start;
+            const error51 = `fetchproxy: ${init.url} did not respond within ${timeoutMs}ms`;
+            resolve({
+              ok: false,
+              error: error51,
+              kind: "timeout",
+              retryAttempted: false,
+              elapsedMs
+            });
+          }, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer)
+        clearTimeout(timer);
+    }
+  }
+  /**
+   * Map an `ok:false` fetch result to its typed throwable. Centralizes
+   * the kind-to-error-class switch so `request()` and (via the same
+   * logic re-implemented inline) `captureRequestHeader()` agree on what
+   * to throw.
+   */
+  _typedErrorFor(result, url2, op, retryAttempted) {
+    if (result.kind === "timeout") {
+      return new FetchproxyTimeoutError({
+        url: url2,
+        timeoutMs: this.opts.fetchTimeoutMs ?? 0,
+        role: this.role,
+        port: this.opts.port,
+        elapsedMs: result.elapsedMs
+      });
+    }
+    if (result.kind === "content_script_unreachable") {
+      return new FetchproxyBridgeDownError({
+        originalError: result.error,
+        retryAttempted,
+        op,
+        url: url2,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+    return new FetchproxyProtocolError(result.error);
   }
   /**
    * Convenience wrapper around `fetch()`. Builds the URL from a path
@@ -36223,8 +36404,18 @@ var FetchproxyServer = class {
     if (opts.subdomain !== void 0)
       assertSubdomainLabel(opts.subdomain);
     const baseDomain = this.resolveBaseDomain(opts.domain);
-    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
-    const url2 = path.startsWith("http://") || path.startsWith("https://") ? path : `https://${host}${path}`;
+    const isAbsolute = path.startsWith("http://") || path.startsWith("https://");
+    let host;
+    if (isAbsolute) {
+      try {
+        host = new URL(path).host;
+      } catch {
+        throw new Error(`FetchproxyServer.request: absolute path is not a valid URL: ${JSON.stringify(path)}`);
+      }
+    } else {
+      host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    }
+    const url2 = isAbsolute ? path : `https://${host}${path}`;
     assertUrlInDomains("request url", url2, this.opts.domains);
     const init = {
       url: url2,
@@ -36235,7 +36426,7 @@ var FetchproxyServer = class {
     };
     const result = await this.fetch(init);
     if (!result.ok) {
-      throw new FetchproxyProtocolError(result.error);
+      throw this._typedErrorFor(result, init.url, "fetch", result.retryAttempted ?? false);
     }
     const response = {
       status: result.status,
@@ -36445,10 +36636,73 @@ var FetchproxyServer = class {
     }
     await this.ensureConnected();
     this.throwIfPendingPair();
-    const declared = this.opts.captureHeaders.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
-    if (!declared) {
-      throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+    const decls = this.opts.captureHeaders;
+    let resolved;
+    if (opts?.urlPattern !== void 0 && opts?.headerName !== void 0) {
+      const found = decls.find((d) => d.urlPattern === opts.urlPattern && d.headerName === opts.headerName);
+      if (!found) {
+        throw new Error(`FetchproxyServer.captureRequestHeader: (urlPattern=${JSON.stringify(opts.urlPattern)}, headerName=${JSON.stringify(opts.headerName)}) not declared in captureHeaders`);
+      }
+      resolved = found;
+    } else if (opts?.urlPattern === void 0 && opts?.headerName === void 0) {
+      if (decls.length === 0) {
+        throw new Error("FetchproxyServer.captureRequestHeader: no captureHeaders declared on this server \u2014 declare at least one entry in FetchproxyServerOpts.captureHeaders, or pass {urlPattern, headerName} explicitly");
+      }
+      if (decls.length > 1) {
+        const list = decls.map((d) => `${JSON.stringify(d.urlPattern)}/${JSON.stringify(d.headerName)}`).join(", ");
+        throw new Error(`FetchproxyServer.captureRequestHeader: multiple captureHeaders declared (${decls.length}: ${list}); pass {urlPattern, headerName} to disambiguate`);
+      }
+      resolved = decls[0];
+    } else {
+      throw new Error("FetchproxyServer.captureRequestHeader: pass both urlPattern AND headerName, or neither (which defaults to the single declared entry)");
     }
+    const callOpts = { ...resolved, ...opts?.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {} };
+    try {
+      const result = await this._captureRequestHeaderOnce(callOpts);
+      this.recordSuccess();
+      return result;
+    } catch (err) {
+      const swDown = err instanceof FetchproxyProtocolError && classifyFetchError(err.message) === "content_script_unreachable";
+      if (!swDown) {
+        this.recordFailure(`capture_request_header: ${err.message ?? String(err)}`);
+        throw err;
+      }
+      const reviveMs = this.opts.bridgeReviveDelayMs ?? 0;
+      if (reviveMs > 0) {
+        await new Promise((r) => setTimeout(r, reviveMs));
+        try {
+          const result = await this._captureRequestHeaderOnce(callOpts);
+          this.recordSuccess();
+          return result;
+        } catch (retryErr) {
+          const stillDown = retryErr instanceof FetchproxyProtocolError && classifyFetchError(retryErr.message) === "content_script_unreachable";
+          if (!stillDown) {
+            this.recordFailure(`capture_request_header: ${retryErr.message ?? String(retryErr)}`);
+            throw retryErr;
+          }
+          this.recordFailure(`capture_request_header bridge-down: ${retryErr.message}`);
+          throw new FetchproxyBridgeDownError({
+            originalError: retryErr.message,
+            retryAttempted: true,
+            op: "capture_request_header",
+            url: resolved.urlPattern,
+            role: this.role,
+            port: this.opts.port
+          });
+        }
+      }
+      this.recordFailure(`capture_request_header bridge-down: ${err.message}`);
+      throw new FetchproxyBridgeDownError({
+        originalError: err.message,
+        retryAttempted: false,
+        op: "capture_request_header",
+        url: resolved.urlPattern,
+        role: this.role,
+        port: this.opts.port
+      });
+    }
+  }
+  async _captureRequestHeaderOnce(opts) {
     const id = this.nextRequestId++;
     const inner = {
       type: "request",
@@ -36557,18 +36811,35 @@ var FetchproxyServer = class {
   onInner(inner) {
     if (inner.type !== "response")
       return;
+    this.lastExtensionMessageAt = Date.now();
     const fetchCb = this.pending.get(inner.id);
     if (fetchCb) {
       this.pending.delete(inner.id);
       if (inner.ok) {
         if (inner.op === void 0 || inner.op === "fetch") {
-          fetchCb({ ok: true, status: inner.status, url: inner.url, body: inner.body });
+          fetchCb({
+            ok: true,
+            status: inner.status,
+            url: inner.url,
+            body: inner.body,
+            retryAttempted: false
+          });
         } else {
           const error51 = `unexpected ${inner.op} response on fetch awaiter`;
-          fetchCb({ ok: false, error: error51, kind: classifyFetchError(error51) });
+          fetchCb({
+            ok: false,
+            error: error51,
+            kind: classifyFetchError(error51),
+            retryAttempted: false
+          });
         }
       } else {
-        fetchCb({ ok: false, error: inner.error, kind: classifyFetchError(inner.error) });
+        fetchCb({
+          ok: false,
+          error: inner.error,
+          kind: classifyFetchError(inner.error),
+          retryAttempted: false
+        });
       }
       return;
     }
@@ -36638,7 +36909,12 @@ var FetchproxyServer = class {
   rejectAllPending(reason = "extension disconnected") {
     const err = new FetchproxyProtocolError(reason);
     for (const cb of this.pending.values()) {
-      cb({ ok: false, error: err.message, kind: classifyFetchError(err.message) });
+      cb({
+        ok: false,
+        error: err.message,
+        kind: classifyFetchError(err.message),
+        retryAttempted: false
+      });
     }
     this.pending.clear();
     for (const cb of this.pendingReadCookies.values()) {
@@ -36703,6 +36979,19 @@ var FetchproxyServer = class {
   }
 };
 
+// node_modules/@fetchproxy/server/dist/classify-bridge-error.js
+function classifyBridgeError(err) {
+  if (err instanceof FetchproxyTimeoutError)
+    return "timeout";
+  if (err instanceof FetchproxyBridgeDownError)
+    return "bridge_down";
+  if (err instanceof FetchproxyHttpError)
+    return "http";
+  if (err instanceof FetchproxyProtocolError)
+    return "protocol";
+  return "other";
+}
+
 // node_modules/@fetchproxy/bootstrap/dist/index.js
 var defaultFactory = (opts) => new FetchproxyServer(opts);
 async function bootstrap(opts) {
@@ -36757,7 +37046,11 @@ async function bootstrap(opts) {
       key: p.storageKey,
       jsonPointer: p.jsonPointer
     })),
-    onPairCode: opts.onPairCode
+    onPairCode: opts.onPairCode,
+    // 0.8.0+ pass-through. Only forwarded when the caller set them;
+    // unset → server defaults apply (30000 / 2000 in 0.8.0).
+    ...opts.fetchTimeoutMs !== void 0 ? { fetchTimeoutMs: opts.fetchTimeoutMs } : {},
+    ...opts.bridgeReviveDelayMs !== void 0 ? { bridgeReviveDelayMs: opts.bridgeReviveDelayMs } : {}
   });
   const storageDomainOpts = {};
   if (opts.storageDomain !== void 0)
@@ -36904,7 +37197,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "infinitecampus-mcp",
-  version: "2.2.3",
+  version: "2.3.0",
   mcpName: "io.github.chrischall/infinitecampus-mcp",
   description: "Infinite Campus (Campus Parent) MCP server \u2014 multi-district read + message/document write",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -36946,7 +37239,8 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.6.0",
+    "@fetchproxy/bootstrap": "^0.8.0",
+    "@fetchproxy/server": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
     zod: "^4.4.3"
@@ -37022,6 +37316,12 @@ async function resolveAuth() {
         source: "fetchproxy"
       };
     } catch (e) {
+      if (classifyBridgeError(e) === "bridge_down") {
+        const downErr = e;
+        throw new Error(
+          `IC auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+        );
+      }
       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
@@ -38275,7 +38575,7 @@ try {
 } catch (e) {
   configError = e;
 }
-var server = new McpServer({ name: "infinitecampus", version: "2.2.3" });
+var server = new McpServer({ name: "infinitecampus", version: "2.3.0" });
 if (account) {
   const client = new ICClient(account, { preloaded });
   registerDistrictTools(server, client);

package/dist/index.js

@@ -50,7 +50,7 @@ try {
 catch (e) {
     configError = e;
 }
-const server = new McpServer({ name: 'infinitecampus', version: '2.2.3' }); // x-release-please-version
+const server = new McpServer({ name: 'infinitecampus', version: '2.3.0' }); // x-release-please-version
 if (account) {
     const client = new ICClient(account, { preloaded });
     registerDistrictTools(server, client);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.2.3",
+  "version": "2.3.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>",
@@ -42,7 +42,8 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.6.0",
+    "@fetchproxy/bootstrap": "^0.8.0",
+    "@fetchproxy/server": "^0.8.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.2",
     "zod": "^4.4.3"

package/server.json

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