canvas-parent-mcp 1.1.2 → 1.1.3

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Canvas LMS (Instructure) — courses, grades, assignments, announcements, planner, conversations, files",
-    "version": "1.1.2"
+    "version": "1.1.3"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Canvas LMS",
       "source": "./",
       "description": "Canvas LMS (Instructure) MCP server for Claude — student/observer access via natural language",
-      "version": "1.1.2",
+      "version": "1.1.3",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canvas-parent-mcp",
   "displayName": "Canvas LMS",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Canvas LMS (Instructure) MCP server for Claude — courses, grades, assignments, announcements, planner, conversations, files",
   "author": {
     "name": "Chris Hall",

package/dist/bundle.js

@@ -34856,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) {
@@ -34957,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;
@@ -35540,7 +35553,9 @@ async function startHost(opts) {
   const peers = /* @__PURE__ */ new Map();
   const ownInnerListeners = [];
   const disconnectListeners = [];
+  const pendingPairListeners = [];
   let ownSession = null;
+  let ownPendingPairCode = null;
   let resolveOwnSession;
   let rejectOwnSession;
   let ownSessionReady;
@@ -35625,6 +35640,7 @@ async function startHost(opts) {
             if (extensionWs !== ws)
               return;
             ownSession = new SessionState(key);
+            ownPendingPairCode = null;
             resolveOwnSession(ownSession);
           } else {
             const slot = peers.get(frame.mcpId);
@@ -35652,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 {
@@ -35697,7 +35723,11 @@ async function startHost(opts) {
     },
     onExtensionDisconnect: (cb) => {
       disconnectListeners.push(cb);
-    }
+    },
+    onPendingPair: (cb) => {
+      pendingPairListeners.push(cb);
+    },
+    pendingPairCode: () => ownPendingPairCode
   };
 }
 
@@ -35727,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(HKDF_SESSION_INFO), 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(() => {
   });
@@ -35764,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;
@@ -35895,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;
@@ -35917,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");
@@ -35968,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,
@@ -36000,13 +36133,16 @@ var FetchproxyServer = class {
       });
       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,
@@ -36020,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`)
@@ -36037,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 };
@@ -36179,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);
@@ -36238,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`);
     }
@@ -36295,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`);
@@ -36338,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");
     }
@@ -36489,8 +36635,8 @@ var FetchproxyServer = class {
       }
     }
   }
-  rejectAllPending() {
-    const err = new FetchproxyProtocolError("extension disconnected");
+  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) });
     }
@@ -36509,6 +36655,32 @@ var FetchproxyServer = class {
       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
@@ -36517,6 +36689,9 @@ var FetchproxyServer = class {
    */
   async close() {
     this.rejectAllPending();
+    if (this.connectingPromise) {
+      await this.connectingPromise.catch(() => void 0);
+    }
     if (this.hostHandle)
       await this.hostHandle.close();
     if (this.peerHandle)
@@ -36524,6 +36699,7 @@ var FetchproxyServer = class {
     this.hostHandle = null;
     this.peerHandle = null;
     this.role = null;
+    this.connectingPromise = null;
   }
 };
 
@@ -36772,7 +36948,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "canvas-parent-mcp",
-  version: "1.1.2",
+  version: "1.1.3",
   mcpName: "io.github.chrischall/canvas-parent-mcp",
   description: "Canvas LMS (Instructure) MCP server \u2014 student/observer read access with optional file download",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -36816,17 +36992,17 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@fetchproxy/bootstrap": "^0.5.1",
+    "@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"
   }
 };
 
@@ -37618,7 +37794,7 @@ try {
 } catch (e) {
   configError = e;
 }
-var server = new McpServer({ name: "canvas", version: "1.1.2" });
+var server = new McpServer({ name: "canvas", version: "1.1.3" });
 if (resolved) {
   const client = new CanvasClient(resolved.account, {
     preloaded: resolved.preloaded

package/dist/index.js

@@ -44,7 +44,7 @@ try {
 catch (e) {
     configError = e;
 }
-const server = new McpServer({ name: 'canvas', version: '1.1.2' }); // x-release-please-version
+const server = new McpServer({ name: 'canvas', version: '1.1.3' }); // x-release-please-version
 if (resolved) {
     const client = new CanvasClient(resolved.account, {
         preloaded: resolved.preloaded,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-parent-mcp",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "mcpName": "io.github.chrischall/canvas-parent-mcp",
   "description": "Canvas LMS (Instructure) MCP server — student/observer read access with optional file download",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -44,16 +44,16 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@fetchproxy/bootstrap": "^0.5.1",
+    "@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/canvas-parent-mcp",
     "source": "github"
   },
-  "version": "1.1.2",
+  "version": "1.1.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "canvas-parent-mcp",
-      "version": "1.1.2",
+      "version": "1.1.3",
       "transport": {
         "type": "stdio"
       },