canvas-parent-mcp 1.2.5 → 1.3.0

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

package/.claude-plugin/plugin.json

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

package/dist/bundle.js

@@ -2991,7 +2991,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve.call(this, root, ref);
+      let _sch = resolve2.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3018,7 +3018,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve(root, ref) {
+    function resolve2(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3649,7 +3649,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve(baseURI, relativeURI, options) {
+    function resolve2(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
       const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
@@ -3933,7 +3933,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve,
+      resolve: resolve2,
       resolveComponent,
       equal,
       serialize,
@@ -9161,7 +9161,7 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash } = __require("crypto");
+    var { randomBytes: randomBytes2, createHash } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -9699,7 +9699,7 @@ var require_websocket = __commonJS({
         }
       }
       const defaultPort = isSecure ? 443 : 80;
-      const key = randomBytes(16).toString("base64");
+      const key = randomBytes2(16).toString("base64");
       const request = isSecure ? https.request : http.request;
       const protocolSet = /* @__PURE__ */ new Set();
       let perMessageDeflate;
@@ -10593,7 +10593,7 @@ var require_websocket_server = __commonJS({
 });
 
 // src/index.ts
-import { dirname as dirname2, join as join3 } from "path";
+import { dirname as dirname3, join as join4 } from "path";
 import { fileURLToPath } from "url";
 
 // node_modules/zod/v3/helpers/util.js
@@ -32554,7 +32554,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error51) {
@@ -32571,7 +32571,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -32649,7 +32649,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve(parseResult.data);
+            resolve2(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -32910,12 +32910,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve, interval);
+      const timeoutId = setTimeout(resolve2, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -34006,7 +34006,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -34670,64 +34670,17 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve) => {
+    return new Promise((resolve2) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve();
+        resolve2();
       } else {
-        this._stdout.once("drain", resolve);
+        this._stdout.once("drain", resolve2);
       }
     });
   }
 };
 
-// node_modules/@chrischall/mcp-utils/dist/server/index.js
-async function createMcpServer(opts) {
-  const server = new McpServer({ name: opts.name, version: opts.version });
-  if (opts.banner !== void 0) {
-    console.error(opts.banner);
-  }
-  const deps = opts.deps;
-  for (const register of opts.tools) {
-    await register(server, deps);
-  }
-  return server;
-}
-function withGracefulShutdown(server, opts = {}) {
-  const shouldExit = opts.exit ?? true;
-  let shuttingDown = false;
-  const handler = (signal) => {
-    if (shuttingDown)
-      return;
-    shuttingDown = true;
-    void (async () => {
-      try {
-        if (opts.onSignal)
-          await opts.onSignal(signal);
-        await server.close();
-      } catch (err) {
-        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
-      } finally {
-        if (shouldExit)
-          process.exit(0);
-      }
-    })();
-  };
-  process.on("SIGINT", () => handler("SIGINT"));
-  process.on("SIGTERM", () => handler("SIGTERM"));
-}
-async function runMcp(opts) {
-  const server = await createMcpServer(opts);
-  const shutdown = opts.shutdown ?? true;
-  if (shutdown !== false) {
-    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
-  }
-  const spec = opts.transport ?? "stdio";
-  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
-  await server.connect(transport);
-  return server;
-}
-
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 var DEFAULT_ERROR_MESSAGE_MAX = 500;
 var McpToolError = class extends Error {
@@ -34785,6 +34738,81 @@ function textResult(data) {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   };
 }
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: redactSecrets(message) }],
+    isError: true
+  };
+}
+
+// node_modules/@chrischall/mcp-utils/dist/server/index.js
+function hintResultOrRethrow(err) {
+  if (err instanceof McpToolError && err.hint) {
+    return errorResult(`${err.message}
+
+Hint: ${err.hint}`);
+  }
+  throw err;
+}
+function surfaceToolHints(server) {
+  const register = server.registerTool.bind(server);
+  server.registerTool = (name, config2, cb) => register(name, config2, (...args) => {
+    let result;
+    try {
+      result = cb(...args);
+    } catch (err) {
+      return hintResultOrRethrow(err);
+    }
+    return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
+  });
+}
+async function createMcpServer(opts) {
+  const server = new McpServer({ name: opts.name, version: opts.version });
+  if (opts.surfaceHints !== false)
+    surfaceToolHints(server);
+  if (opts.banner !== void 0) {
+    console.error(opts.banner);
+  }
+  const deps = opts.deps;
+  for (const register of opts.tools) {
+    await register(server, deps);
+  }
+  return server;
+}
+function withGracefulShutdown(server, opts = {}) {
+  const shouldExit = opts.exit ?? true;
+  let shuttingDown = false;
+  const handler = (signal) => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    void (async () => {
+      try {
+        if (opts.onSignal)
+          await opts.onSignal(signal);
+        await server.close();
+      } catch (err) {
+        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
+      } finally {
+        if (shouldExit)
+          process.exit(0);
+      }
+    })();
+  };
+  process.on("SIGINT", () => handler("SIGINT"));
+  process.on("SIGTERM", () => handler("SIGTERM"));
+}
+async function runMcp(opts) {
+  const server = await createMcpServer(opts);
+  const shutdown = opts.shutdown ?? true;
+  if (shutdown !== false) {
+    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
+  }
+  const spec = opts.transport ?? "stdio";
+  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
+  await server.connect(transport);
+  return server;
+}
 
 // node_modules/@chrischall/mcp-utils/dist/config/index.js
 var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
@@ -34799,6 +34827,20 @@ function readEnvVar(key, opts = {}) {
   }
   return opts.default;
 }
+var TRUE_TOKENS = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var FALSE_TOKENS = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+function parseBoolEnv(key, opts = {}) {
+  const fallback = opts.default ?? false;
+  const raw = readEnvVar(key, { env: opts.env });
+  if (raw === void 0)
+    return fallback;
+  const token = raw.toLowerCase();
+  if (TRUE_TOKENS.has(token))
+    return true;
+  if (FALSE_TOKENS.has(token))
+    return false;
+  return fallback;
+}
 async function loadDotenvSafely(opts = {}) {
   try {
     const mod = await import(
@@ -36191,7 +36233,7 @@ var DEFAULT_BIND_TIMEOUT_MS = 5e3;
 async function electRole(opts) {
   const server = createServer();
   const bindTimeoutMs = opts.bindTimeoutMs ?? DEFAULT_BIND_TIMEOUT_MS;
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let timer;
     const clearBindTimer = () => {
       if (timer) {
@@ -36207,7 +36249,7 @@ async function electRole(opts) {
           server.close();
         } catch {
         }
-        resolve({ role: "peer" });
+        resolve2({ role: "peer" });
       } else {
         reject(e);
       }
@@ -36215,7 +36257,7 @@ async function electRole(opts) {
     const onListening = () => {
       clearBindTimer();
       server.removeListener("error", onError);
-      resolve({ role: "host", server });
+      resolve2({ role: "host", server });
     };
     server.once("error", onError);
     server.once("listening", onListening);
@@ -36561,8 +36603,8 @@ async function startHost(opts) {
   let rejectOwnSession;
   let ownSessionReady;
   function resetSessionPromise() {
-    ownSessionReady = new Promise((resolve, reject) => {
-      resolveOwnSession = resolve;
+    ownSessionReady = new Promise((resolve2, reject) => {
+      resolveOwnSession = resolve2;
       rejectOwnSession = reject;
     });
     ownSessionReady.catch(() => {
@@ -36783,7 +36825,7 @@ async function startHost(opts) {
     });
   });
   return {
-    close: () => new Promise((resolve) => {
+    close: () => new Promise((resolve2) => {
       for (const client of wss.clients) {
         try {
           client.terminate();
@@ -36791,7 +36833,7 @@ async function startHost(opts) {
         }
       }
       wss.close(() => {
-        opts.httpServer.close(() => resolve());
+        opts.httpServer.close(() => resolve2());
       });
     }),
     sendOwnInner: async (inner) => {
@@ -36821,8 +36863,8 @@ async function startHost(opts) {
 var enc3 = new TextEncoder();
 async function startPeer(opts) {
   const ws = new import_websocket.default(`ws://${opts.host}:${opts.port}`);
-  await new Promise((resolve, reject) => {
-    ws.once("open", () => resolve());
+  await new Promise((resolve2, reject) => {
+    ws.once("open", () => resolve2());
     ws.once("error", reject);
   });
   const hello = await buildServerHello({
@@ -36852,8 +36894,8 @@ async function startPeer(opts) {
   let pendingPairCode = null;
   let resolveFirstReady;
   let rejectFirstReady;
-  const sessionPromise = new Promise((resolve, reject) => {
-    resolveFirstReady = resolve;
+  const sessionPromise = new Promise((resolve2, reject) => {
+    resolveFirstReady = resolve2;
     rejectFirstReady = reject;
   });
   let extensionHello = null;
@@ -37054,6 +37096,17 @@ function classifyBridgeError(err) {
 }
 
 // node_modules/@fetchproxy/server/dist/ws-server.js
+function envWsPort() {
+  const raw = process.env.FETCHPROXY_WS_PORT;
+  if (raw === void 0 || raw.trim() === "")
+    return void 0;
+  if (!/^\d+$/.test(raw.trim()))
+    return void 0;
+  const port = Number(raw.trim());
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    return void 0;
+  return port;
+}
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
     super(message);
@@ -37301,7 +37354,7 @@ var FetchproxyServer = class {
       }
     }
     this.opts = {
-      port: opts.port ?? 37149,
+      port: opts.port ?? envWsPort() ?? 37149,
       host: opts.host ?? "127.0.0.1",
       serverName: opts.serverName,
       version: opts.version,
@@ -37731,8 +37784,8 @@ var FetchproxyServer = class {
   async _fetchOnceWithTimeout(init) {
     const id = this.nextRequestId++;
     const inner = { type: "request", id, op: "fetch", init };
-    const pending = new Promise((resolve) => {
-      this.pending.set(id, resolve);
+    const pending = new Promise((resolve2) => {
+      this.pending.set(id, resolve2);
     });
     await this.sendInnerFrame(inner);
     const timeoutMs = this.opts.fetchTimeoutMs;
@@ -37743,12 +37796,12 @@ var FetchproxyServer = class {
     try {
       return await Promise.race([
         pending,
-        new Promise((resolve) => {
+        new Promise((resolve2) => {
           timer = setTimeout(() => {
             this.pending.delete(id);
             const elapsedMs = Date.now() - start;
             const error51 = `fetchproxy: ${init.url} did not respond within ${timeoutMs}ms`;
-            resolve({
+            resolve2({
               ok: false,
               error: error51,
               kind: "timeout",
@@ -38110,8 +38163,8 @@ var FetchproxyServer = class {
       const tabUrl = `https://${host}/`;
       inner = { type: "request", id, op: "read_cookies", init: { tabUrl } };
     }
-    const pending = new Promise((resolve) => {
-      this.pendingReadCookies.set(id, resolve);
+    const pending = new Promise((resolve2) => {
+      this.pendingReadCookies.set(id, resolve2);
     });
     await this.sendInnerFrame(inner);
     const result = await this._withVerbTimeout(pending, this.pendingReadCookies, id, `https://${host}`);
@@ -38169,8 +38222,8 @@ var FetchproxyServer = class {
         ...cookiePath !== void 0 ? { path: cookiePath } : {}
       }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingWriteCookies.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingWriteCookies.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingWriteCookies, id, `https://${host}`);
@@ -38232,8 +38285,8 @@ var FetchproxyServer = class {
         ...opts.pointers ? { pointers: { ...opts.pointers } } : {}
       }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingStorage.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingStorage.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingStorage, id, `https://${host}`);
@@ -38337,8 +38390,8 @@ var FetchproxyServer = class {
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingCapture.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingCapture.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingCapture, id, `https://${opts.host}${opts.path ?? "/*"}`);
@@ -38422,8 +38475,8 @@ var FetchproxyServer = class {
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingRedirect.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingRedirect.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingRedirect, id, `https://${opts.host}${opts.path ?? "/*"}`);
@@ -38504,8 +38557,8 @@ var FetchproxyServer = class {
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingDownload.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingDownload.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingDownload, id, opts.url);
@@ -38552,8 +38605,8 @@ var FetchproxyServer = class {
         keys: [...opts.keys]
       }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingIdb.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingIdb.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
@@ -38592,8 +38645,8 @@ var FetchproxyServer = class {
       op: "read_dom",
       init: { origin, names: [...opts.names] }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingStorage.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingStorage.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
@@ -38638,8 +38691,8 @@ var FetchproxyServer = class {
         ...opts.tabUrl !== void 0 ? { tabUrl: opts.tabUrl } : {}
       }
     };
-    const pending = new Promise((resolve, reject) => {
-      this.pendingGraphql.set(id, { resolve, reject });
+    const pending = new Promise((resolve2, reject) => {
+      this.pendingGraphql.set(id, { resolve: resolve2, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingGraphql, id, opts.name);
@@ -39173,7 +39226,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "canvas-parent-mcp",
-  version: "1.2.5",
+  version: "1.3.0",
   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>",
@@ -39207,17 +39260,20 @@ var package_default = {
     ".claude-plugin",
     "skills",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   scripts: {
     build: "tsc && npm run bundle",
     bundle: `esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from "module"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js`,
     dev: "node --env-file=.env dist/index.js",
-    test: "vitest run",
-    "test:watch": "vitest"
+    test: "npm run typecheck && vitest run",
+    "test:coverage": "npm run typecheck && vitest run --coverage",
+    "test:watch": "vitest",
+    typecheck: "tsc -p tsconfig.json --noEmit"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.17.1",
     "@fetchproxy/bootstrap": "^2.0.0",
     "@fetchproxy/server": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -39327,10 +39383,127 @@ async function liftBrowserCookie(declaredDomain, baseHost) {
 
 // src/client.ts
 import { writeFile as writeFile3, stat } from "fs/promises";
-import { dirname } from "path";
 
 // node_modules/@chrischall/mcp-utils/dist/session/index.js
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join as join3, resolve } from "node:path";
+import { homedir as homedir2 } from "node:os";
+import { randomBytes, createHmac } from "node:crypto";
+function bindingDigest(secret, salt) {
+  return createHmac("sha256", salt).update(secret).digest("hex").slice(0, 32);
+}
+function isEnvelope(raw) {
+  return raw !== null && typeof raw === "object" && raw.v === 1 && "state" in raw;
+}
+var StatePersistenceError = class extends Error {
+  cause;
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = "StatePersistenceError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function createFileStatePersistence(opts) {
+  const { filePath, validate } = opts;
+  const secret = opts.boundTo;
+  return {
+    load() {
+      if (!existsSync(filePath))
+        return null;
+      try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        let state;
+        if (isEnvelope(raw)) {
+          const b = raw.boundTo;
+          if (secret === void 0) {
+            if (b !== void 0)
+              return null;
+          } else {
+            if (b === void 0)
+              return null;
+            if (bindingDigest(secret, b.salt) !== b.digest)
+              return null;
+          }
+          state = raw.state;
+        } else {
+          if (secret !== void 0)
+            return null;
+          state = raw;
+        }
+        if (validate !== void 0)
+          return validate(state);
+        return state;
+      } catch {
+        return null;
+      }
+    },
+    save(state) {
+      const dir = dirname(filePath);
+      const tmp = `${filePath}.tmp-${randomBytes(6).toString("hex")}`;
+      const dirExisted = existsSync(dir);
+      try {
+        mkdirSync(dir, { recursive: true, mode: 448 });
+        if (!dirExisted)
+          chmodSync(dir, 448);
+        let boundTo;
+        if (secret !== void 0) {
+          const salt = randomBytes(16).toString("hex");
+          boundTo = { salt, digest: bindingDigest(secret, salt) };
+        }
+        const envelope = { v: 1, ...boundTo !== void 0 ? { boundTo } : {}, state };
+        writeFileSync(tmp, JSON.stringify(envelope, null, 2), { mode: 384 });
+        chmodSync(tmp, 384);
+        renameSync(tmp, filePath);
+        chmodSync(filePath, 384);
+      } catch (err) {
+        try {
+          if (existsSync(tmp))
+            unlinkSync(tmp);
+        } catch {
+        }
+        throw err;
+      }
+    },
+    clear() {
+      try {
+        if (existsSync(filePath))
+          unlinkSync(filePath);
+      } catch {
+      }
+    }
+  };
+}
+function homeOf(env) {
+  return readEnvVar("HOME", { env }) ?? homedir2();
+}
+function resolveStateDir(opts = {}) {
+  const env = opts.env;
+  return join3(readEnvVar("MCP_DATA_DIR", { env }) ?? homeOf(env), opts.subdir ?? "");
+}
+function resolveStateFile(opts) {
+  const override = opts.envVar !== void 0 ? readEnvVar(opts.envVar, { env: opts.env }) : void 0;
+  if (override !== void 0) {
+    if (override === "~")
+      return homeOf(opts.env);
+    if (override.startsWith("~/"))
+      return join3(homeOf(opts.env), override.slice(2));
+    return resolve(override);
+  }
+  const dirOpts = { env: opts.env };
+  if (opts.subdir !== void 0)
+    dirOpts.subdir = opts.subdir;
+  return join3(resolveStateDir(dirOpts), opts.fileName);
+}
 var TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1e3;
+function isPersistedCookieSession(raw) {
+  if (raw === null || typeof raw !== "object")
+    return false;
+  const r = raw;
+  if (typeof r.sessionAt !== "number" || !Number.isFinite(r.sessionAt))
+    return false;
+  return typeof r.session === "object" && r.session !== null;
+}
 var CookieSessionManager = class {
   session;
   inFlight;
@@ -39344,6 +39517,17 @@ var CookieSessionManager = class {
   maxAgeMs;
   now;
   onReplayLoginErrorFn;
+  persistence;
+  onPersistErrorFn;
+  /** Persistence is consulted once per process; a miss must not be re-read. */
+  persistenceRead = false;
+  /**
+   * Serializes persistence writes. `seed()` and `invalidate()` are synchronous
+   * by contract and so fire-and-forget their save/clear; with an async backend a
+   * slow save could otherwise land AFTER the clear that followed it and leave an
+   * invalidated session on disk.
+   */
+  persistChain = Promise.resolve();
   constructor(opts) {
     this.loginFn = opts.login;
     this.isExpiredFn = opts.isExpired ?? (() => false);
@@ -39351,6 +39535,8 @@ var CookieSessionManager = class {
     this.maxAgeMs = opts.maxAgeMs;
     this.now = opts.now ?? Date.now;
     this.onReplayLoginErrorFn = opts.onReplayLoginError;
+    this.persistence = opts.persistence;
+    this.onPersistErrorFn = opts.onPersistError;
   }
   /** The current session, or `undefined` before the first successful login. */
   get current() {
@@ -39399,6 +39585,8 @@ var CookieSessionManager = class {
     this.session = session;
     this.sessionAt = this.now();
     this.inFlight = void 0;
+    this.persistenceRead = true;
+    void this.persist(session, this.sessionAt);
   }
   /**
    * One login attempt. Self-clears `inFlight` on settle so a rejected login
@@ -39410,13 +39598,25 @@ var CookieSessionManager = class {
     const holder = {};
     holder.p = (async () => {
       try {
+        const restored = this.persistence !== void 0 && !this.persistenceRead ? await this.restoreFromPersistence() : null;
+        if (restored !== null) {
+          if (this.inFlight === holder.p) {
+            this.session = restored.session;
+            this.sessionAt = restored.sessionAt;
+          }
+          return restored.session;
+        }
         const session = await this.loginFn();
+        const at = this.now();
         if (this.inFlight === holder.p) {
           this.session = session;
-          this.sessionAt = this.now();
+          this.sessionAt = at;
         }
+        await this.persist(session, at);
         return session;
       } catch (err) {
+        if (err instanceof StatePersistenceError)
+          throw err.cause;
         if (this.isPermanentErrorFn(err))
           this.permanentError = err;
         throw err;
@@ -39436,6 +39636,71 @@ var CookieSessionManager = class {
   invalidate() {
     this.session = void 0;
     this.inFlight = void 0;
+    void this.clearPersisted();
+  }
+  /**
+   * The persisted session, if there is one worth using. Read at most once per
+   * process — after that the in-memory session (or its absence) is the truth,
+   * so an invalidate() cannot be undone by a stale file.
+   */
+  async restoreFromPersistence() {
+    if (this.persistence === void 0 || this.persistenceRead)
+      return null;
+    this.persistenceRead = true;
+    try {
+      let raw = null;
+      await this.enqueuePersist(async () => {
+        raw = await this.persistence?.load();
+      });
+      if (!isPersistedCookieSession(raw))
+        return null;
+      if (this.maxAgeMs !== void 0 && this.now() - raw.sessionAt >= this.maxAgeMs)
+        return null;
+      return raw;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Append a persistence op to the chain, preserving call order.
+   *
+   * The RETURNED promise can reject — that is the whole `StatePersistenceError`
+   * path, and the awaited login write depends on it. Only the retained chain is
+   * swallowed, so one failed write cannot poison every later one.
+   */
+  enqueuePersist(op) {
+    const next = this.persistChain.then(op);
+    this.persistChain = next.catch(() => void 0);
+    return next;
+  }
+  /** Write the session. Silent unless `onPersistError` throws. */
+  persist(session, sessionAt) {
+    return this.enqueuePersist(async () => {
+      if (this.persistence === void 0)
+        return;
+      try {
+        await this.persistence.save({ session, sessionAt });
+      } catch (err) {
+        if (this.onPersistErrorFn === void 0)
+          return;
+        try {
+          this.onPersistErrorFn(err);
+        } catch (hookErr) {
+          throw new StatePersistenceError(hookErr);
+        }
+      }
+    });
+  }
+  /** Discard the persisted session. Never throws. */
+  clearPersisted() {
+    return this.enqueuePersist(async () => {
+      if (this.persistence?.clear === void 0)
+        return;
+      try {
+        await this.persistence.clear();
+      } catch {
+      }
+    });
   }
   /**
    * Run an authenticated `call` with the current session and reactive
@@ -39469,6 +39734,57 @@ var CookieSessionManager = class {
   }
 };
 
+// src/session-cache.ts
+function sessionCachePath(env = process.env) {
+  return resolveStateFile({
+    env,
+    envVar: "CANVAS_SESSION_FILE",
+    subdir: ".canvas-parent-mcp",
+    fileName: "session.json"
+  });
+}
+function isRecord(raw) {
+  if (raw === null || typeof raw !== "object") return false;
+  const r = raw;
+  if (typeof r.sessionAt !== "number") return false;
+  const s = r.session;
+  if (s === null || typeof s !== "object") return false;
+  const h = s.headers;
+  if (h === null || typeof h !== "object" || Object.keys(h).length === 0) return false;
+  if (Object.values(h).some((v) => typeof v !== "string")) return false;
+  return s.accessTokenExpiresAt === void 0 || typeof s.accessTokenExpiresAt === "number";
+}
+function bindingFor(account, browserBacked) {
+  if (account.mode === "token") return null;
+  if (account.mode === "session") {
+    if (browserBacked) return null;
+    return ["session", account.baseUrl, account.username.trim().toLowerCase(), account.password].join(
+      "\0"
+    );
+  }
+  return ["oauth", account.baseUrl, account.clientId, account.refreshToken].join("\0");
+}
+function createSessionCache(account, opts = {}) {
+  const env = opts.env ?? process.env;
+  if (!parseBoolEnv("CANVAS_SESSION_CACHE", { env, default: true })) return null;
+  const boundTo = bindingFor(account, opts.browserBacked === true);
+  if (boundTo === null) return null;
+  return createFileStatePersistence({
+    filePath: sessionCachePath(env),
+    boundTo,
+    validate: (raw) => isRecord(raw) ? raw : null
+  });
+}
+function reportCacheWriteFailure(err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  console.error(
+    `[canvas-parent-mcp] could not cache the session (${detail}); continuing without the cache \u2014 every restart will authenticate again until this is fixed.`
+  );
+}
+
+// src/client.ts
+import { dirname as dirname2 } from "path";
+
 // src/session-login.ts
 var USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36";
 var SessionLoginError = class extends Error {
@@ -39589,7 +39905,9 @@ var CanvasClient = class {
       // account with neither a lift nor credentials still can't — those 401s
       // fall through as a Response and `mapStatus` turns them into a
       // TokenExpiredError.
-      isExpired: (res) => res.status === 401 && this.canReauth()
+      isExpired: (res) => res.status === 401 && this.canReauth(),
+      persistence: createSessionCache(account, { browserBacked: this.refreshSession !== null }) ?? void 0,
+      onPersistError: reportCacheWriteFailure
     });
   }
   /** Account metadata (no secrets) — useful for diagnostics. */
@@ -39627,7 +39945,7 @@ var CanvasClient = class {
     }
     if (destStat?.isDirectory()) throw new InvalidPathError(destinationPath);
     if (destStat && !opts.overwrite) throw new FileExistsError(destinationPath);
-    const parent = dirname(destinationPath);
+    const parent = dirname2(destinationPath);
     try {
       await stat(parent);
     } catch {
@@ -40162,8 +40480,8 @@ function registerFileTools(server, client) {
 }
 
 // src/index.ts
-var __dirname = dirname2(fileURLToPath(import.meta.url));
-await loadDotenvSafely({ path: join3(__dirname, "..", ".env"), override: false });
+var __dirname = dirname3(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join4(__dirname, "..", ".env"), override: false });
 var resolved = null;
 var configError = null;
 try {
@@ -40173,7 +40491,7 @@ try {
 }
 await runMcp({
   name: "canvas",
-  version: "1.2.5",
+  version: "1.3.0",
   // x-release-please-version
   tools: [
     (server) => {

package/dist/client.js

@@ -1,4 +1,5 @@
 import { writeFile, stat } from 'fs/promises';
+import { createSessionCache, reportCacheWriteFailure } from './session-cache.js';
 import { dirname } from 'path';
 import { createOAuth2Refresher, parseLinkHeader } from '@chrischall/mcp-utils';
 import { CookieSessionManager } from '@chrischall/mcp-utils/session';
@@ -43,6 +44,8 @@ export class CanvasClient {
             // fall through as a Response and `mapStatus` turns them into a
             // TokenExpiredError.
             isExpired: (res) => res.status === 401 && this.canReauth(),
+            persistence: createSessionCache(account, { browserBacked: this.refreshSession !== null }) ?? undefined,
+            onPersistError: reportCacheWriteFailure,
         });
     }
     /** Account metadata (no secrets) — useful for diagnostics. */

package/dist/index.js

@@ -46,7 +46,7 @@ catch (e) {
 // host's install-time `tools/list` succeeds.
 await runMcp({
     name: 'canvas',
-    version: '1.2.5', // x-release-please-version
+    version: '1.3.0', // x-release-please-version
     tools: [
         (server) => {
             if (resolved) {

package/dist/session-cache.js

@@ -0,0 +1,91 @@
+import { createFileStatePersistence, resolveStateFile, } from '@chrischall/mcp-utils/session';
+import { parseBoolEnv } from '@chrischall/mcp-utils';
+/** Where the signed-in session is cached between runs. */
+export function sessionCachePath(env = process.env) {
+    return resolveStateFile({
+        env,
+        envVar: 'CANVAS_SESSION_FILE',
+        subdir: '.canvas-parent-mcp',
+        fileName: 'session.json',
+    });
+}
+/** Guard the stored envelope: real headers, and a login time. */
+function isRecord(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return false;
+    const r = raw;
+    if (typeof r.sessionAt !== 'number')
+        return false;
+    const s = r.session;
+    if (s === null || typeof s !== 'object')
+        return false;
+    const h = s.headers;
+    if (h === null || typeof h !== 'object' || Object.keys(h).length === 0)
+        return false;
+    if (Object.values(h).some((v) => typeof v !== 'string'))
+        return false;
+    return s.accessTokenExpiresAt === undefined || typeof s.accessTokenExpiresAt === 'number';
+}
+/**
+ * The credential a cached record is bound to, or `null` when this account has
+ * nothing worth caching.
+ *
+ * Mode decides, because what a login COSTS differs by mode:
+ *
+ *  - `token` — the login builds an `Authorization` header from a static env
+ *    token and makes no network call at all. Caching it would save nothing and
+ *    put a bearer token on disk for no reason.
+ *  - `session` with a fetchproxy lift — the cookie is re-read from a signed-in
+ *    browser tab on every mint, which is both cheap and the point of that path.
+ *    There is also no stored secret to bind to.
+ *  - `session` with credentials — a real form login. Worth caching.
+ *  - `oauth` — every login spends a refresh-token exchange against Canvas.
+ *    Worth caching.
+ */
+function bindingFor(account, browserBacked) {
+    if (account.mode === 'token')
+        return null;
+    if (account.mode === 'session') {
+        if (browserBacked)
+            return null;
+        return ['session', account.baseUrl, account.username.trim().toLowerCase(), account.password].join('\u0000');
+    }
+    // oauth: the refresh token and client identity are what a re-bootstrap changes.
+    return ['oauth', account.baseUrl, account.clientId, account.refreshToken].join('\u0000');
+}
+/**
+ * The session cache for this account, or `null` when caching is off, or when
+ * the mode has nothing worth caching (see {@link bindingFor}).
+ *
+ * The record is bound to the credentials that minted it — username+password for
+ * a session account, refresh token + client id for an oauth one — so rotating
+ * any of them discards it. Only a salted digest is written, never the values.
+ * The base URL is part of the binding too, so pointing the same credentials at
+ * a different Canvas instance does not reuse a session from the old one.
+ */
+export function createSessionCache(account, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (!parseBoolEnv('CANVAS_SESSION_CACHE', { env, default: true }))
+        return null;
+    const boundTo = bindingFor(account, opts.browserBacked === true);
+    if (boundTo === null)
+        return null;
+    return createFileStatePersistence({
+        filePath: sessionCachePath(env),
+        boundTo,
+        validate: (raw) => (isRecord(raw) ? raw : null),
+    });
+}
+/**
+ * Report a cache write that failed. Not fatal: the session is re-mintable from
+ * the credentials in the environment, so a lost write costs the next start a
+ * login rather than access. Canvas oauth refresh tokens are reusable — unlike a
+ * single-use rotating one, losing a write here cannot strand the account.
+ *
+ * stderr only; stdout is the JSON-RPC channel.
+ */
+export function reportCacheWriteFailure(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    console.error(`[canvas-parent-mcp] could not cache the session (${detail}); continuing without the ` +
+        'cache — every restart will authenticate again until this is fixed.');
+}

package/mint.yaml

@@ -0,0 +1,84 @@
+version: 1
+name: Canvas Parent
+slug: canvas-parent
+summary: >-
+  Canvas LMS courses, assignments, grades and messages for a parent/observer.
+  The package ships TWO bins, so command.bin below is required — without it the
+  install refuses. A token or OAuth registration hosts on any tier; the
+  username/password and bridge paths need a browser and do not.
+command:
+  # REQUIRED: package.json declares canvas-parent-mcp (the server) and
+  # canvas-parent-mcp-qr-login (a local CLI). Without this the install refuses.
+  bin: canvas-parent-mcp
+env:
+  - name: CANVAS_BASE_URL
+    required: true
+    help: >-
+      Your district's Canvas host, e.g. https://cms.instructure.com. Must be an
+      https URL. Everything else is an auth mode on top of this.
+  - name: CANVAS_TOKEN
+    secret: true
+    required: false
+    help: >-
+      A Canvas personal access token (Account → Settings → New Access Token).
+      The simplest hosted auth mode; tried first.
+  - name: CANVAS_CLIENT_ID
+    required: false
+    help: OAuth client id. Use with CANVAS_CLIENT_SECRET + CANVAS_REFRESH_TOKEN.
+  - name: CANVAS_CLIENT_SECRET
+    secret: true
+    required: false
+    help: OAuth client secret. Use with CANVAS_CLIENT_ID + CANVAS_REFRESH_TOKEN.
+  - name: CANVAS_REFRESH_TOKEN
+    secret: true
+    required: false
+    help: OAuth refresh token. Use with CANVAS_CLIENT_ID + CANVAS_CLIENT_SECRET.
+  - name: CANVAS_USERNAME
+    required: false
+    help: >-
+      Canvas login email, for the session-scrape mode (direct Canvas accounts
+      only — not SSO). Prefer CANVAS_TOKEN when hosted.
+  - name: CANVAS_PASSWORD
+    secret: true
+    required: false
+    help: Canvas password, paired with CANVAS_USERNAME. Prefer CANVAS_TOKEN when hosted.
+  - name: CANVAS_NAME
+    required: false
+    help: Label for this district. Defaults to the host portion of CANVAS_BASE_URL.
+  - name: CANVAS_DISABLE_FETCHPROXY
+    required: false
+    help: >-
+      Set to 1 to disable the browser-bridge fallback, making missing
+      credentials a hard error. Recommended for a hosted registration, which has
+      no browser to fall back to.
+  - name: CANVAS_SESSION_CACHE
+    required: false
+    help: >-
+      Set to false to disable the on-disk session cache and authenticate on
+      every process start. Defaults to enabled.
+  - name: CANVAS_SESSION_FILE
+    required: false
+    help: >-
+      Absolute path for the session cache file. Defaults to
+      $MCP_DATA_DIR/.canvas-parent-mcp/session.json.
+egress:
+  allow:
+    # Canvas is multi-tenant per district: the base URL is a *.instructure.com
+    # host (cms.instructure.com is the CMS district). Narrow this to YOUR
+    # district's host if you prefer.
+    #
+    # sso.canvaslms.com is deliberately NOT here: the hosted server never
+    # contacts it. session-login.ts only INSPECTS a redirect's Location for
+    # that host, and qr-login.ts is the separate canvas-parent-mcp-qr-login
+    # bin, not the child this manifest configures.
+    - instructure.com
+    - cms.instructure.com
+
+state:
+  dataDir: true
+  reason: >-
+    Caches the signed-in session at
+    $MCP_DATA_DIR/.canvas-parent-mcp/session.json (0600). Without it every cold
+    start re-runs the form login (session mode) or spends a refresh-token
+    exchange against Canvas (oauth mode); a hosted child idles out after ten
+    minutes, so that is most starts. Token mode caches nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-parent-mcp",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "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>",
@@ -34,17 +34,20 @@
     ".claude-plugin",
     "skills",
     ".mcp.json",
-    "server.json"
+    "server.json",
+    "mint.yaml"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from \"module\"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js",
     "dev": "node --env-file=.env dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "test": "npm run typecheck && vitest run",
+    "test:coverage": "npm run typecheck && vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.17.1",
     "@fetchproxy/bootstrap": "^2.0.0",
     "@fetchproxy/server": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/canvas-parent-mcp",
     "source": "github"
   },
-  "version": "1.2.5",
+  "version": "1.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "canvas-parent-mcp",
-      "version": "1.2.5",
+      "version": "1.3.0",
       "transport": {
         "type": "stdio"
       },
@@ -67,6 +67,18 @@
           "description": "Friendly name for the Canvas instance (defaults to the host portion of the base URL)",
           "isRequired": false,
           "format": "string"
+        },
+        {
+          "name": "CANVAS_SESSION_CACHE",
+          "description": "Set to false to disable the on-disk session cache and re-authenticate on every process start. Defaults to enabled.",
+          "isRequired": false,
+          "format": "string"
+        },
+        {
+          "name": "CANVAS_SESSION_FILE",
+          "description": "Absolute path for the session cache file. Defaults to $MCP_DATA_DIR/.canvas-parent-mcp/session.json.",
+          "isRequired": false,
+          "format": "string"
         }
       ]
     }

package/skills/canvas-parent/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: canvas-parent-mcp
+name: canvas-parent
 description: This skill should be used when the user asks about Canvas LMS data — their own student account or any observed student. Triggers on phrases like "check Canvas", "what's my grade", "Canvas inbox", "what's due", "missing assignments", "Canvas LMS", "Instructure", "course announcements", "syllabus", or any request about courses, assignments, grades, conversations, announcements, planner items, or files in Canvas.
 ---