infinitecampus-mcp 2.1.3 → 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.3"
+    "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.3",
+      "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.3",
+  "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

@@ -49,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/bundle.js

@@ -7572,6 +7572,10 @@ var require_receiver = __commonJS({
        *     extensions
        * @param {Boolean} [options.isServer=false] Specifies whether to operate in
        *     client or server mode
+       * @param {Number} [options.maxBufferedChunks=0] The maximum number of
+       *     buffered data chunks
+       * @param {Number} [options.maxFragments=0] The maximum number of message
+       *     fragments
        * @param {Number} [options.maxPayload=0] The maximum allowed message length
        * @param {Boolean} [options.skipUTF8Validation=false] Specifies whether or
        *     not to skip UTF-8 validation for text and close messages
@@ -7582,6 +7586,8 @@ var require_receiver = __commonJS({
         this._binaryType = options.binaryType || BINARY_TYPES[0];
         this._extensions = options.extensions || {};
         this._isServer = !!options.isServer;
+        this._maxBufferedChunks = options.maxBufferedChunks | 0;
+        this._maxFragments = options.maxFragments | 0;
         this._maxPayload = options.maxPayload | 0;
         this._skipUTF8Validation = !!options.skipUTF8Validation;
         this[kWebSocket] = void 0;
@@ -7611,6 +7617,18 @@ var require_receiver = __commonJS({
        */
       _write(chunk, encoding, cb) {
         if (this._opcode === 8 && this._state == GET_INFO) return cb();
+        if (this._maxBufferedChunks > 0 && this._buffers.length >= this._maxBufferedChunks) {
+          cb(
+            this.createError(
+              RangeError,
+              "Too many buffered chunks",
+              false,
+              1008,
+              "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+            )
+          );
+          return;
+        }
         this._bufferedBytes += chunk.length;
         this._buffers.push(chunk);
         this.startLoop(cb);
@@ -7940,6 +7958,17 @@ var require_receiver = __commonJS({
           return;
         }
         if (data.length) {
+          if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
+            const error51 = this.createError(
+              RangeError,
+              "Too many message fragments",
+              false,
+              1008,
+              "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+            );
+            cb(error51);
+            return;
+          }
           this._messageLength = this._totalPayloadLength;
           this._fragments.push(data);
         }
@@ -7969,6 +7998,17 @@ var require_receiver = __commonJS({
               cb(error51);
               return;
             }
+            if (this._maxFragments > 0 && this._fragments.length >= this._maxFragments) {
+              const error51 = this.createError(
+                RangeError,
+                "Too many message fragments",
+                false,
+                1008,
+                "WS_ERR_TOO_MANY_BUFFERED_PARTS"
+              );
+              cb(error51);
+              return;
+            }
             this._fragments.push(buf);
           }
           this.dataMessage(cb);
@@ -9175,6 +9215,10 @@ var require_websocket = __commonJS({
        *     multiple times in the same tick
        * @param {Function} [options.generateMask] The function used to generate the
        *     masking key
+       * @param {Number} [options.maxBufferedChunks=0] The maximum number of
+       *     buffered data chunks
+       * @param {Number} [options.maxFragments=0] The maximum number of message
+       *     fragments
        * @param {Number} [options.maxPayload=0] The maximum allowed message size
        * @param {Boolean} [options.skipUTF8Validation=false] Specifies whether or
        *     not to skip UTF-8 validation for text and close messages
@@ -9186,6 +9230,8 @@ var require_websocket = __commonJS({
           binaryType: this.binaryType,
           extensions: this._extensions,
           isServer: this._isServer,
+          maxBufferedChunks: options.maxBufferedChunks,
+          maxFragments: options.maxFragments,
           maxPayload: options.maxPayload,
           skipUTF8Validation: options.skipUTF8Validation
         });
@@ -9485,6 +9531,8 @@ var require_websocket = __commonJS({
         autoPong: true,
         closeTimeout: CLOSE_TIMEOUT,
         protocolVersion: protocolVersions[1],
+        maxBufferedChunks: 1024 * 1024,
+        maxFragments: 128 * 1024,
         maxPayload: 100 * 1024 * 1024,
         skipUTF8Validation: false,
         perMessageDeflate: true,
@@ -9727,6 +9775,8 @@ var require_websocket = __commonJS({
         websocket.setSocket(socket, head, {
           allowSynchronousEvents: opts.allowSynchronousEvents,
           generateMask: opts.generateMask,
+          maxBufferedChunks: opts.maxBufferedChunks,
+          maxFragments: opts.maxFragments,
           maxPayload: opts.maxPayload,
           skipUTF8Validation: opts.skipUTF8Validation
         });
@@ -10069,6 +10119,10 @@ var require_websocket_server = __commonJS({
        *     called
        * @param {Function} [options.handleProtocols] A hook to handle protocols
        * @param {String} [options.host] The hostname where to bind the server
+       * @param {Number} [options.maxBufferedChunks=1048576] The maximum number of
+       *     buffered data chunks
+       * @param {Number} [options.maxFragments=131072] The maximum number of message
+       *     fragments
        * @param {Number} [options.maxPayload=104857600] The maximum allowed message
        *     size
        * @param {Boolean} [options.noServer=false] Enable no server mode
@@ -10090,6 +10144,8 @@ var require_websocket_server = __commonJS({
         options = {
           allowSynchronousEvents: true,
           autoPong: true,
+          maxBufferedChunks: 1024 * 1024,
+          maxFragments: 128 * 1024,
           maxPayload: 100 * 1024 * 1024,
           skipUTF8Validation: false,
           perMessageDeflate: false,
@@ -10369,6 +10425,8 @@ var require_websocket_server = __commonJS({
         socket.removeListener("error", socketOnError);
         ws.setSocket(socket, head, {
           allowSynchronousEvents: this.options.allowSynchronousEvents,
+          maxBufferedChunks: this.options.maxBufferedChunks,
+          maxFragments: this.options.maxFragments,
           maxPayload: this.options.maxPayload,
           skipUTF8Validation: this.options.skipUTF8Validation
         });
@@ -34495,6 +34553,7 @@ var StdioServerTransport = class {
 
 // node_modules/@fetchproxy/protocol/dist/frames.js
 var PROTOCOL_VERSION = 2;
+var HKDF_SESSION_INFO = "fetchproxy/1.0.0/session";
 var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "fetch",
   "read_cookies",
@@ -34569,7 +34628,7 @@ var ProtocolError = class extends Error {
 var FORBIDDEN_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
 var BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
 var SCOPE_KEY_RE = /^[A-Za-z0-9_.\-]{1,256}$/;
-var SCOPE_KEY_GLOB_RE = /^[A-Za-z0-9_.\-]{1,255}\*?$/;
+var SCOPE_KEY_GLOB_RE = /^[A-Za-z0-9_.\-]{1,256}\*?$/;
 var HEADER_NAME_RE = /^[A-Za-z0-9_\-]{1,128}$/;
 var HOSTNAME_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/i;
 function assertObject(x, label) {
@@ -34698,7 +34757,7 @@ function assertStoragePointersArray(value, label, declaredKeys) {
     if (entry.jsonPointer === void 0) {
       throw new ProtocolError(`${label}[${i}].jsonPointer: missing`);
     }
-    if (typeof entry.key !== "string" || !SCOPE_KEY_GLOB_RE.test(entry.key)) {
+    if (typeof entry.key !== "string" || !SCOPE_KEY_RE.test(entry.key)) {
       throw new ProtocolError(`${label}[${i}].key: invalid key ${JSON.stringify(entry.key)}`);
     }
     if (typeof entry.jsonPointer !== "string" || !isValidJsonPointer(entry.jsonPointer)) {
@@ -34797,6 +34856,8 @@ function validateFrame(raw) {
     return validateReady(raw);
   if (t === "frame")
     return validateEncrypted(raw);
+  if (t === "pair-pending")
+    return validatePairPending(raw);
   throw new ProtocolError(`unknown frame type: ${String(t)}`);
 }
 function validateHello(raw) {
@@ -34898,6 +34959,17 @@ function validateEncrypted(raw) {
   assertBase64(raw.ciphertext, "frame.ciphertext");
   return raw;
 }
+var PAIR_CODE_RE = /^\d{3}-\d{3}$/;
+function validatePairPending(raw) {
+  assertString(raw.mcpId, "pair-pending.mcpId");
+  if (!isValidMcpId(raw.mcpId))
+    throw new ProtocolError("pair-pending.mcpId: invalid format");
+  assertString(raw.pairCode, "pair-pending.pairCode");
+  if (!PAIR_CODE_RE.test(raw.pairCode)) {
+    throw new ProtocolError(`pair-pending.pairCode: must match XXX-XXX, got ${String(raw.pairCode)}`);
+  }
+  return { type: "pair-pending", mcpId: raw.mcpId, pairCode: raw.pairCode };
+}
 function validateInnerFrame(raw) {
   assertObject(raw, "inner");
   const t = raw.type;
@@ -35480,15 +35552,22 @@ async function startHost(opts) {
   let extensionWs = null;
   const peers = /* @__PURE__ */ new Map();
   const ownInnerListeners = [];
+  const disconnectListeners = [];
+  const pendingPairListeners = [];
   let ownSession = null;
+  let ownPendingPairCode = null;
   let resolveOwnSession;
   let rejectOwnSession;
-  const ownSessionReady = new Promise((resolve, reject) => {
-    resolveOwnSession = resolve;
-    rejectOwnSession = reject;
-  });
-  ownSessionReady.catch(() => {
-  });
+  let ownSessionReady;
+  function resetSessionPromise() {
+    ownSessionReady = new Promise((resolve, reject) => {
+      resolveOwnSession = resolve;
+      rejectOwnSession = reject;
+    });
+    ownSessionReady.catch(() => {
+    });
+  }
+  resetSessionPromise();
   let extensionHello = null;
   wss.on("connection", (ws) => {
     let identified = null;
@@ -35557,11 +35636,12 @@ async function startHost(opts) {
             }
             const extPub = fromB64(frame.extensionSessionPub);
             const shared = await ecdhX25519(opts.ownIdentity.x25519Priv, extPub);
-            const key = await hkdfSha256(shared, ownSessionNonce, enc2.encode("fetchproxy/0.1.0/session"), 32);
-            if (!ownSession) {
-              ownSession = new SessionState(key);
-              resolveOwnSession(ownSession);
-            }
+            const key = await hkdfSha256(shared, ownSessionNonce, enc2.encode(HKDF_SESSION_INFO), 32);
+            if (extensionWs !== ws)
+              return;
+            ownSession = new SessionState(key);
+            ownPendingPairCode = null;
+            resolveOwnSession(ownSession);
           } else {
             const slot = peers.get(frame.mcpId);
             if (slot)
@@ -35588,6 +35668,16 @@ async function startHost(opts) {
               extensionWs.send(JSON.stringify(frame));
           }
         }
+        if (frame.type === "pair-pending" && identified === "extension") {
+          if (frame.mcpId === opts.ownMcpId) {
+            ownPendingPairCode = frame.pairCode;
+            pendingPairListeners.forEach((cb) => cb(frame.pairCode));
+          } else {
+            const slot = peers.get(frame.mcpId);
+            if (slot)
+              slot.ws.send(JSON.stringify(frame));
+          }
+        }
       } catch (e) {
         console.error("[fetchproxy] host: message handler error:", e);
         try {
@@ -35603,6 +35693,9 @@ async function startHost(opts) {
         if (!ownSession) {
           rejectOwnSession(new Error("extension disconnected before ready"));
         }
+        ownSession = null;
+        resetSessionPromise();
+        disconnectListeners.forEach((cb) => cb());
       }
       if (identified === "peer" && peerMcpId)
         peers.delete(peerMcpId);
@@ -35627,7 +35720,14 @@ async function startHost(opts) {
     },
     onOwnInner: (cb) => {
       ownInnerListeners.push(cb);
-    }
+    },
+    onExtensionDisconnect: (cb) => {
+      disconnectListeners.push(cb);
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => ownPendingPairCode
   };
 }
 
@@ -35657,36 +35757,57 @@ async function startPeer(opts) {
   const sessionNonce = fromB64(hello.sessionNonce);
   ws.send(JSON.stringify(hello));
   const innerListeners = [];
+  const renegotiateListeners = [];
+  const pendingPairListeners = [];
   let session = null;
+  let pendingPairCode = null;
+  let resolveFirstReady;
+  let rejectFirstReady;
   const sessionPromise = new Promise((resolve, reject) => {
-    const onMessage = async (data) => {
-      try {
-        const raw = JSON.parse(data.toString());
-        const frame = validateFrame(raw);
-        if (frame.type === "ready" && frame.mcpId === opts.mcpId) {
-          const extPub = fromB64(frame.extensionSessionPub);
-          const shared = await ecdhX25519(opts.identity.x25519Priv, extPub);
-          const sessionKey = await hkdfSha256(shared, sessionNonce, enc3.encode("fetchproxy/0.1.0/session"), 32);
-          session = new SessionState(sessionKey);
-          resolve(session);
-          return;
+    resolveFirstReady = resolve;
+    rejectFirstReady = reject;
+  });
+  const onMessage = async (data) => {
+    try {
+      const raw = JSON.parse(data.toString());
+      const frame = validateFrame(raw);
+      if (frame.type === "ready" && frame.mcpId === opts.mcpId) {
+        const extPub = fromB64(frame.extensionSessionPub);
+        const shared = await ecdhX25519(opts.identity.x25519Priv, extPub);
+        const sessionKey = await hkdfSha256(shared, sessionNonce, enc3.encode(HKDF_SESSION_INFO), 32);
+        const isRenegotiation = session !== null;
+        session = new SessionState(sessionKey);
+        pendingPairCode = null;
+        if (isRenegotiation) {
+          renegotiateListeners.forEach((cb) => cb());
+        } else {
+          resolveFirstReady(session);
         }
-        if (frame.type === "frame" && frame.mcpId === opts.mcpId) {
-          if (!session)
-            return;
-          if (!session.acceptInboundSeq(frame.seq))
-            return;
+        return;
+      }
+      if (frame.type === "pair-pending" && frame.mcpId === opts.mcpId) {
+        pendingPairCode = frame.pairCode;
+        pendingPairListeners.forEach((cb) => cb(frame.pairCode));
+        return;
+      }
+      if (frame.type === "frame" && frame.mcpId === opts.mcpId) {
+        if (!session)
+          return;
+        if (!session.acceptInboundSeq(frame.seq))
+          return;
+        try {
           const inner = await openEncryptedFrame(session.sessionKey, frame);
           innerListeners.forEach((cb) => cb(inner));
+        } catch {
         }
-      } catch (e) {
-        reject(e instanceof Error ? e : new Error(String(e)));
       }
-    };
-    ws.on("message", onMessage);
-    ws.once("close", () => {
-      reject(new Error("peer WS closed before ready"));
-    });
+    } catch (e) {
+      rejectFirstReady(e instanceof Error ? e : new Error(String(e)));
+    }
+  };
+  ws.on("message", onMessage);
+  ws.once("close", () => {
+    rejectFirstReady(new Error("peer WS closed before ready"));
   });
   sessionPromise.catch(() => {
   });
@@ -35694,13 +35815,21 @@ async function startPeer(opts) {
     ws,
     session: sessionPromise,
     sendInner: async (inner) => {
-      const s = await sessionPromise;
+      await sessionPromise;
+      const s = session;
       const sealed = await sealInnerFrame(s.sessionKey, opts.mcpId, s.nextOutboundSeq(), inner);
       ws.send(JSON.stringify(sealed));
     },
     onInner: (cb) => {
       innerListeners.push(cb);
     },
+    onRenegotiate: (cb) => {
+      renegotiateListeners.push(cb);
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => pendingPairCode,
     close: () => ws.close()
   };
   return handle;
@@ -35757,6 +35886,32 @@ async function loadOrCreateIdentity(serverName, dir = defaultIdentityDir()) {
   return id;
 }
 
+// node_modules/@fetchproxy/server/dist/error-kind.js
+function classifyFetchError(error51) {
+  if (/Could not establish connection/i.test(error51) || /Receiving end does not exist/i.test(error51)) {
+    return "content_script_unreachable";
+  }
+  if (/^tab fetch failed:/.test(error51)) {
+    return "tab_fetch_failed";
+  }
+  if (/^fetch threw:/.test(error51)) {
+    return "tab_fetch_failed";
+  }
+  if (/^no tab matching /.test(error51)) {
+    return "no_tab";
+  }
+  if (/not in domains \[/.test(error51)) {
+    return "domain_denied";
+  }
+  if (/^capability .+ not granted/.test(error51)) {
+    return "capability_denied";
+  }
+  if (/^(request|response) body too large:/.test(error51)) {
+    return "body_too_large";
+  }
+  return "other";
+}
+
 // node_modules/@fetchproxy/server/dist/ws-server.js
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
@@ -35799,7 +35954,11 @@ function assertUrlInDomains(field, url2, domains) {
 }
 var DEFAULT_JSON_OK_STATUSES = [200, 201, 202, 204];
 var FetchproxyServer = class {
-  /** Set after `listen()` succeeds. Null while not listening. */
+  /**
+   * Bridge role. `null` until the first verb call (or an explicit
+   * `connect()`) — `listen()` no longer triggers the role election
+   * as of 0.5.3+. Reset to `null` on `close()`.
+   */
   role = null;
   opts;
   hostHandle = null;
@@ -35821,6 +35980,12 @@ var FetchproxyServer = class {
   pendingIdb = /* @__PURE__ */ new Map();
   mcpId = null;
   identity = null;
+  // 0.5.3+: in-flight role-election / handle-start promise. Set the
+  // first time a verb call runs `ensureConnected`, awaited by concurrent
+  // callers, cleared once the connection is up. Single source of truth
+  // for "we're connecting right now" so two parallel first-calls don't
+  // race the port bind.
+  connectingPromise = null;
   constructor(opts) {
     if (!Array.isArray(opts.domains) || opts.domains.length === 0) {
       throw new Error("FetchproxyServer: opts.domains must be a non-empty array of hostnames");
@@ -35872,23 +36037,87 @@ var FetchproxyServer = class {
     };
   }
   /**
-   * Start the WebSocket bridge. Loads the long-term identity keypair
-   * from disk (creating it on first call), elects the host-vs-peer
-   * role by attempting to bind the configured port, and stands up the
-   * matching handshake machinery. Idempotent only insofar as it leaves
-   * `role` non-null on success; calling `listen()` twice without an
-   * intervening `close()` is a programming error.
+   * Prepare the bridge for use. Loads the long-term identity keypair
+   * from disk (creating it on first call) and computes this instance's
+   * `mcpId`. Does NOT bind the bridge port or dial any WebSocket — the
+   * connection is established lazily on the first verb call (see
+   * `ensureConnected` / `getOrConnect`).
+   *
+   * Pre-0.5.3 behavior: `listen()` also did role election and started
+   * the host/peer immediately, which meant every configured-but-unused
+   * MCP claimed bridge resources at MCP-client boot. Several MCPs
+   * starting in parallel under Claude Desktop also produced noisy
+   * `ERR_CONNECTION_REFUSED` errors in the extension if it raced ahead
+   * of the first MCP's port bind. Deferring keeps boot quiet and
+   * leaves the port unowned until something actually needs it.
+   *
+   * Calling `listen()` twice without an intervening `close()` is a
+   * no-op (the second call's identity load is idempotent).
    */
   async listen() {
-    this.identity = await loadOrCreateIdentity(this.opts.serverName, this.opts.identityDir);
-    this.mcpId = generateMcpId(this.opts.serverName, this.opts.version);
+    if (!this.identity) {
+      this.identity = await loadOrCreateIdentity(this.opts.serverName, this.opts.identityDir);
+    }
+    if (!this.mcpId) {
+      this.mcpId = generateMcpId(this.opts.serverName, this.opts.version);
+    }
+  }
+  /**
+   * Force an eager bridge connection (role-election + host/peer handle
+   * start + listener wiring) without waiting for the first verb call.
+   * Useful for callers that want to surface the role / connection
+   * outcome at boot, or for tests whose harness dials a mock extension
+   * immediately after server construction. Production MCPs that just
+   * answer tool calls should NOT call this — the lazy connect via
+   * `ensureConnected` will do the right thing on first use, keeping
+   * boot cheap and avoiding port-bind contention for MCPs that never
+   * actually get invoked.
+   *
+   * Idempotent: a second call after the first has resolved is a no-op
+   * (the existing handle is reused). Throws if `listen()` was never
+   * called.
+   */
+  async connect() {
+    await this.ensureConnected();
+  }
+  /**
+   * Establish the bridge connection (role-election + host/peer handle
+   * start + listener wiring) the first time a verb is invoked.
+   * Idempotent after the connection is up; concurrent first-callers
+   * share the same in-flight promise so only one election happens.
+   *
+   * Throws if `listen()` was never called — the contract is that the
+   * MCP author still must wire `transport.start()` at boot to load
+   * identity / set mcpId, even though the WS doesn't open until a
+   * verb runs.
+   */
+  async ensureConnected() {
+    if (this.hostHandle || this.peerHandle)
+      return;
+    if (this.connectingPromise) {
+      await this.connectingPromise;
+      return;
+    }
+    if (!this.identity || !this.mcpId) {
+      throw new Error("FetchproxyServer: ensureConnected called before listen() \u2014 call listen() at MCP boot to load identity");
+    }
+    this.connectingPromise = this.doConnect();
+    try {
+      await this.connectingPromise;
+    } finally {
+      this.connectingPromise = null;
+    }
+  }
+  async doConnect() {
+    const identity = this.identity;
+    const mcpId = this.mcpId;
     const el = await electRole({ host: this.opts.host, port: this.opts.port });
     if (el.role === "host") {
       this.role = "host";
       this.hostHandle = await startHost({
         httpServer: el.server,
-        ownIdentity: this.identity,
-        ownMcpId: this.mcpId,
+        ownIdentity: identity,
+        ownMcpId: mcpId,
         ownServerName: this.opts.serverName,
         ownVersion: this.opts.version,
         ownDomains: this.opts.domains,
@@ -35903,13 +36132,17 @@ var FetchproxyServer = class {
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
+      this.hostHandle.onExtensionDisconnect(() => this.rejectAllPending());
+      this.hostHandle.onPendingPair((code) => {
+        this.rejectAllPending(this.pairingErrorMessage(code));
+      });
     } else {
       this.role = "peer";
       this.peerHandle = await startPeer({
         host: this.opts.host,
         port: this.opts.port,
-        identity: this.identity,
-        mcpId: this.mcpId,
+        identity,
+        mcpId,
         serverName: this.opts.serverName,
         version: this.opts.version,
         domains: this.opts.domains,
@@ -35923,8 +36156,19 @@ var FetchproxyServer = class {
         sessionStoragePointers: this.opts.sessionStoragePointers
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
+      this.peerHandle.onRenegotiate(() => this.rejectAllPending());
+      this.peerHandle.onPendingPair((code) => {
+        this.rejectAllPending(this.pairingErrorMessage(code));
+      });
+      if (this.opts.onPairCode) {
+        const cb = this.opts.onPairCode;
+        this.peerHandle.onPendingPair((code) => cb(code));
+      }
     }
   }
+  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}`;
+  }
   /**
    * Raw single-shot fetch through the bridge. Most callers should prefer
    * the verb shortcuts (`get` / `post` / `getJson` / `postJson` / `getHtml`)
@@ -35940,8 +36184,11 @@ var FetchproxyServer = class {
    * offline, etc.).
    */
   async fetch(init) {
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.fetch called before listen() \u2014 not listening");
+    await this.ensureConnected();
+    const pendingCode = this.currentPendingPairCode();
+    if (pendingCode !== null) {
+      const error51 = this.pairingErrorMessage(pendingCode);
+      return { ok: false, error: error51, kind: classifyFetchError(error51) };
     }
     const id = this.nextRequestId++;
     const inner = { type: "request", id, op: "fetch", init };
@@ -36082,9 +36329,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("read_cookies")) {
       throw new Error('FetchproxyServer.readCookies(): MCP did not declare "read_cookies" in capabilities \u2014 add it to FetchproxyServerOpts.capabilities to enable this verb');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.readCookies called before listen() \u2014 not listening");
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (opts.subdomain !== void 0)
       assertSubdomainLabel(opts.subdomain);
     const baseDomain = this.resolveBaseDomain(opts.domain);
@@ -36141,9 +36387,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes(op)) {
       throw new Error(`FetchproxyServer.${op === "read_local_storage" ? "readLocalStorage" : "readSessionStorage"}(): MCP did not declare ${JSON.stringify(op)} in capabilities`);
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error(`FetchproxyServer.${op} called before listen() \u2014 not listening`);
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (!Array.isArray(opts.keys) || opts.keys.length === 0) {
       throw new Error(`FetchproxyServer.${op}: opts.keys must be a non-empty array`);
     }
@@ -36198,9 +36443,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("capture_request_header")) {
       throw new Error('FetchproxyServer.captureRequestHeader(): MCP did not declare "capture_request_header" in capabilities');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.captureRequestHeader called before listen() \u2014 not listening");
-    }
+    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`);
@@ -36241,9 +36485,8 @@ var FetchproxyServer = class {
     if (!this.opts.capabilities.includes("read_indexed_db")) {
       throw new Error('FetchproxyServer.readIndexedDb(): MCP did not declare "read_indexed_db" in capabilities');
     }
-    if (!this.hostHandle && !this.peerHandle) {
-      throw new Error("FetchproxyServer.readIndexedDb called before listen() \u2014 not listening");
-    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
     if (!Array.isArray(opts.keys) || opts.keys.length === 0) {
       throw new Error("FetchproxyServer.readIndexedDb: opts.keys must be a non-empty array");
     }
@@ -36321,10 +36564,11 @@ var FetchproxyServer = class {
         if (inner.op === void 0 || inner.op === "fetch") {
           fetchCb({ ok: true, status: inner.status, url: inner.url, body: inner.body });
         } else {
-          fetchCb({ ok: false, error: `unexpected ${inner.op} response on fetch awaiter` });
+          const error51 = `unexpected ${inner.op} response on fetch awaiter`;
+          fetchCb({ ok: false, error: error51, kind: classifyFetchError(error51) });
         }
       } else {
-        fetchCb({ ok: false, error: inner.error });
+        fetchCb({ ok: false, error: inner.error, kind: classifyFetchError(inner.error) });
       }
       return;
     }
@@ -36391,6 +36635,52 @@ 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) });
+    }
+    this.pending.clear();
+    for (const cb of this.pendingReadCookies.values()) {
+      cb({ ok: false, error: err.message });
+    }
+    this.pendingReadCookies.clear();
+    for (const { reject } of this.pendingStorage.values())
+      reject(err);
+    this.pendingStorage.clear();
+    for (const { reject } of this.pendingCapture.values())
+      reject(err);
+    this.pendingCapture.clear();
+    for (const { reject } of this.pendingIdb.values())
+      reject(err);
+    this.pendingIdb.clear();
+  }
+  /**
+   * 0.5.2+: read the current pair-pending pair code from whichever handle
+   * is active, returning null when none is pending. Public verbs call this
+   * at the top so that a tool invoked while the bridge is waiting on user
+   * approval fails fast with the actionable error rather than hanging on a
+   * sealed frame the extension will never process.
+   */
+  currentPendingPairCode() {
+    if (this.hostHandle)
+      return this.hostHandle.pendingPairCode();
+    if (this.peerHandle)
+      return this.peerHandle.pendingPairCode();
+    return null;
+  }
+  /**
+   * 0.5.2+: throw `FetchproxyProtocolError` with the actionable pair-code
+   * message if the bridge is waiting on user approval. Used by the verb
+   * methods (readCookies, readLocalStorage, etc.) that surface errors via
+   * thrown exceptions rather than `ok:false` discriminated unions.
+   */
+  throwIfPendingPair() {
+    const code = this.currentPendingPairCode();
+    if (code !== null) {
+      throw new FetchproxyProtocolError(this.pairingErrorMessage(code));
+    }
+  }
   /**
    * Shut down the bridge. Host: terminates the WebSocket server and any
    * still-attached extension/peer clients. Peer: closes the upstream
@@ -36398,6 +36688,10 @@ var FetchproxyServer = class {
    * twice in a row.
    */
   async close() {
+    this.rejectAllPending();
+    if (this.connectingPromise) {
+      await this.connectingPromise.catch(() => void 0);
+    }
     if (this.hostHandle)
       await this.hostHandle.close();
     if (this.peerHandle)
@@ -36405,6 +36699,7 @@ var FetchproxyServer = class {
     this.hostHandle = null;
     this.peerHandle = null;
     this.role = null;
+    this.connectingPromise = null;
   }
 };
 
@@ -36493,8 +36788,7 @@ async function bootstrap(opts) {
       for (const p of localStoragePointers) {
         pointers[p.outputKey] = { storageKey: p.storageKey, jsonPointer: p.jsonPointer };
       }
-      const stub = server2;
-      localStorage = await stub.readLocalStorage({
+      localStorage = await server2.readLocalStorage({
         keys: allKeys,
         ...storageDomainOpts,
         ...localStoragePointers.length > 0 ? { pointers } : {}
@@ -36507,8 +36801,7 @@ async function bootstrap(opts) {
       for (const p of sessionStoragePointers) {
         pointers[p.outputKey] = { storageKey: p.storageKey, jsonPointer: p.jsonPointer };
       }
-      const stub = server2;
-      sessionStorage = await stub.readSessionStorage({
+      sessionStorage = await server2.readSessionStorage({
         keys: allKeys,
         ...storageDomainOpts,
         ...sessionStoragePointers.length > 0 ? { pointers } : {}
@@ -36531,9 +36824,6 @@ async function bootstrap(opts) {
     }
     const indexedDbBucket = {};
     for (const d of indexedDb) {
-      if (!server2.readIndexedDb) {
-        throw new Error("bootstrap: server factory does not implement readIndexedDb (declared indexedDb but server stub omits it)");
-      }
       const values = await server2.readIndexedDb({
         database: d.database,
         store: d.store,
@@ -36614,7 +36904,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "infinitecampus-mcp",
-  version: "2.1.3",
+  version: "2.2.3",
   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>",
@@ -36656,17 +36946,17 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.4.2",
+    "@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"
   }
 };
 
@@ -37985,7 +38275,7 @@ try {
 } catch (e) {
   configError = e;
 }
-var server = new McpServer({ name: "infinitecampus", version: "2.1.3" });
+var server = new McpServer({ name: "infinitecampus", version: "2.2.3" });
 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.1.3' });
+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);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "infinitecampus-mcp",
-  "version": "2.1.3",
+  "version": "2.2.3",
   "mcpName": "io.github.chrischall/infinitecampus-mcp",
-  "description": "Infinite Campus (Campus Parent) MCP server \u2014 multi-district read + message/document write",
+  "description": "Infinite Campus (Campus Parent) MCP server — multi-district read + message/document write",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
   "repository": {
     "type": "git",
@@ -42,16 +42,16 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.4.2",
+    "@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.3",
+  "version": "2.2.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "infinitecampus-mcp",
-      "version": "2.1.3",
+      "version": "2.2.3",
       "transport": {
         "type": "stdio"
       },