canvas-parent-mcp 0.1.4 → 1.0.1

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": "0.1.4"
+    "version": "1.0.1"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Canvas LMS",
       "source": "./",
       "description": "Canvas LMS (Instructure) MCP server for Claude — student/observer access via natural language",
-      "version": "0.1.4",
+      "version": "1.0.1",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -8,7 +8,6 @@
         "CANVAS_TOKEN": "${CANVAS_TOKEN}",
         "CANVAS_USERNAME": "${CANVAS_USERNAME}",
         "CANVAS_PASSWORD": "${CANVAS_PASSWORD}",
-        "CANVAS_COOKIE": "${CANVAS_COOKIE}",
         "CANVAS_CLIENT_ID": "${CANVAS_CLIENT_ID}",
         "CANVAS_CLIENT_SECRET": "${CANVAS_CLIENT_SECRET}",
         "CANVAS_REFRESH_TOKEN": "${CANVAS_REFRESH_TOKEN}",

package/README.md

@@ -27,34 +27,36 @@ Tools that the harness will gate as write/IO operations: `canvas_download_file`.
 
 ## Configuration
 
-Set the base URL plus *one* auth mode:
+Set the base URL plus *one* auth mode. **Username/password is recommended** — most schools have disabled personal-access-token creation, and this mode auto-logs-in on first request and silently re-mints session cookies on 401, so you never have to re-bootstrap.
 
-**Personal access token (recommended):**
+**Username/password (recommended):**
 
 ```
 CANVAS_BASE_URL=https://cms.instructure.com
-CANVAS_TOKEN=your-personal-access-token
+CANVAS_USERNAME=me@example.com
+CANVAS_PASSWORD=your-canvas-password
 CANVAS_NAME=cms                # optional, defaults to host portion of base URL
 ```
 
-**Username/password (auto-login + auto-renew, simplest when tokens are disabled):**
+**Direct Canvas accounts only** — won't work with SAML/Google/Microsoft SSO or 2FA. Treat `.env` like a password file: do not commit it.
 
-```
-CANVAS_BASE_URL=https://cms.instructure.com
-CANVAS_USERNAME=me@example.com
-CANVAS_PASSWORD=your-canvas-password
-```
+### Advanced alternatives
 
-The MCP logs in lazily on the first request and silently re-mints cookies on 401, so you never have to re-bootstrap. **Direct Canvas accounts only** — won't work with SAML/Google/Microsoft SSO or 2FA. Treat `.env` like a password file: do not commit it.
+If your admin still allows tokens, or your account uses SSO (so username/password won't work), pick one of these instead:
 
-**Session cookie (precomputed, no auto-renewal):**
+<details>
+<summary><b>Personal access token</b> — simplest if your admin allows it</summary>
 
 ```
 CANVAS_BASE_URL=https://cms.instructure.com
-CANVAS_COOKIE=canvas_session=...; pseudonym_credentials=...; ...
+CANVAS_TOKEN=your-personal-access-token
 ```
 
-**OAuth (advanced):**
+Generate via Canvas → Account → Settings → "+ New Access Token". Most institutions have disabled this for non-admins.
+</details>
+
+<details>
+<summary><b>OAuth via mobile QR code</b> — bootstrapped from the mobile-app login flow</summary>
 
 ```
 CANVAS_BASE_URL=https://cms.instructure.com
@@ -63,30 +65,16 @@ CANVAS_CLIENT_SECRET=...
 CANVAS_REFRESH_TOKEN=...
 ```
 
-Precedence when multiple are set: `CANVAS_TOKEN` > session env vars (`CANVAS_USERNAME`+`CANVAS_PASSWORD` and/or `CANVAS_COOKIE`) > OAuth. If both `CANVAS_COOKIE` and username/password are set, the cookie is used initially and username/password is the fallback for re-minting on 401.
+If your account uses SSO (so username/password can't auth), mint OAuth credentials by reusing the Canvas mobile-app QR-login flow — see [Bootstrapping OAuth via the mobile QR code](#bootstrapping-oauth-via-the-mobile-qr-code) below.
+</details>
 
-See `.env.example`.
+**Precedence when multiple are set:** `CANVAS_TOKEN` > `CANVAS_USERNAME`+`CANVAS_PASSWORD` > OAuth.
 
-### Bootstrapping cookie auth via username/password
-
-When your Canvas admin has disabled personal-access-token creation entirely, the bundled `canvas-parent-mcp-login` CLI logs in via the same `/login/canvas` form your browser uses and prints a `CANVAS_COOKIE` env var:
-
-```
-canvas-parent-mcp-login -b https://cms.instructure.com -u me@example.com >> .env
-# Password: ******    (TTY prompt with no echo)
-```
-
-Or piped (no TTY prompt):
-
-```
-canvas-parent-mcp-login -b https://cms.instructure.com -u me@example.com <<< "$PW" >> .env
-```
-
-The "remember me" cookie (`pseudonym_credentials`) is good for ~2 weeks; re-run the CLI when API calls start returning 401s. **Limitations**: only works for direct Canvas accounts — institutions using SAML/Google/Microsoft SSO or 2FA cannot use this flow, and the CLI exits with a clear error if it detects an SSO redirect or a missing `pseudonym_credentials` cookie. Treat the resulting `CANVAS_COOKIE` value like a password.
+See `.env.example`.
 
 ### Bootstrapping OAuth via the mobile QR code
 
-If your Canvas admin has disabled personal-access-token creation (some institutions restrict tokens to "the mobile app only"), you can mint OAuth credentials by going through the same QR-login flow that the official Canvas mobile apps use:
+If your Canvas admin has disabled personal-access-token creation (some institutions restrict tokens to "the mobile app only") AND your account uses SSO so username/password can't auth, you can mint OAuth credentials by going through the same QR-login flow that the official Canvas mobile apps use:
 
 1. In Canvas web, open **Account → QR for Mobile Login** — Canvas shows a QR that's valid for 10 minutes.
 2. Decode the QR with any QR reader. The result is a URL on `sso.canvaslms.com` like `https://sso.canvaslms.com/canvas/login?domain=...&code=...`.

package/dist/bundle.js

@@ -30860,36 +30860,49 @@ var StdioServerTransport = class {
 };
 
 // src/config.ts
+function readVar(env, key) {
+  const raw = env[key];
+  if (typeof raw !== "string") return void 0;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return void 0;
+  if (/^\$\{[^}]*\}$/.test(trimmed)) return void 0;
+  return trimmed;
+}
 function loadAccount(env = process.env) {
-  const baseUrl = env.CANVAS_BASE_URL;
+  const baseUrl = readVar(env, "CANVAS_BASE_URL");
   if (!baseUrl) {
     throw new Error(
-      "Missing required env var: CANVAS_BASE_URL. Set CANVAS_BASE_URL (e.g. https://cms.instructure.com) plus either CANVAS_TOKEN or the OAuth triple."
+      "Missing required env var: CANVAS_BASE_URL. Set CANVAS_BASE_URL (e.g. https://cms.instructure.com) plus an auth mode."
     );
   }
   if (!/^https:\/\//.test(baseUrl)) {
     throw new Error(`CANVAS_BASE_URL must be an https URL, got: '${baseUrl}'`);
   }
   const cleanBaseUrl = baseUrl.replace(/\/$/, "");
-  const name = env.CANVAS_NAME || new URL(cleanBaseUrl).host;
-  const token = env.CANVAS_TOKEN;
-  const cookie = env.CANVAS_COOKIE;
-  const username = env.CANVAS_USERNAME;
-  const password = env.CANVAS_PASSWORD;
-  const clientId = env.CANVAS_CLIENT_ID;
-  const clientSecret = env.CANVAS_CLIENT_SECRET;
-  const refreshToken = env.CANVAS_REFRESH_TOKEN;
+  const name = readVar(env, "CANVAS_NAME") ?? new URL(cleanBaseUrl).host;
+  const token = readVar(env, "CANVAS_TOKEN");
+  const username = readVar(env, "CANVAS_USERNAME");
+  const password = readVar(env, "CANVAS_PASSWORD");
+  const clientId = readVar(env, "CANVAS_CLIENT_ID");
+  const clientSecret = readVar(env, "CANVAS_CLIENT_SECRET");
+  const refreshToken = readVar(env, "CANVAS_REFRESH_TOKEN");
   const oauthSet = [clientId, clientSecret, refreshToken].filter((v) => !!v);
   const hasFullOAuth = oauthSet.length === 3;
   const hasPartialOAuth = oauthSet.length > 0 && oauthSet.length < 3;
   const hasFullUserPass = !!username && !!password;
   const hasPartialUserPass = !!username !== !!password;
-  const hasSession = !!cookie || hasFullUserPass;
   if (token) {
-    const others = [hasFullOAuth ? "OAuth" : null, hasSession ? "session env vars" : null].filter(Boolean).join(" and ");
-    if (others) {
+    const others = [];
+    if (hasFullOAuth) others.push("OAuth env vars");
+    else if (hasPartialOAuth) others.push("partial OAuth env vars (CANVAS_CLIENT_*/CANVAS_REFRESH_TOKEN)");
+    if (hasFullUserPass) others.push("username/password env vars");
+    else if (hasPartialUserPass) {
+      others.push(`partial username/password (only ${username ? "CANVAS_USERNAME" : "CANVAS_PASSWORD"} set)`);
+    }
+    if (others.length > 0) {
+      const joined = others.join(" and ");
       console.error(
-        `[canvas-mcp] CANVAS_TOKEN takes precedence over ${others} \u2014 using CANVAS_TOKEN. Unset CANVAS_TOKEN to use ${others}.`
+        `[canvas-parent-mcp] CANVAS_TOKEN takes precedence over ${joined} \u2014 using CANVAS_TOKEN. Unset CANVAS_TOKEN to use ${joined}.`
       );
     }
     return { mode: "token", name, baseUrl: cleanBaseUrl, token };
@@ -30900,19 +30913,13 @@ function loadAccount(env = process.env) {
       `Incomplete username/password config \u2014 missing: ${missing}. Set both CANVAS_USERNAME and CANVAS_PASSWORD, or unset both.`
     );
   }
-  if (hasSession) {
+  if (hasFullUserPass) {
     if (hasFullOAuth) {
       console.error(
-        "[canvas-mcp] Session env vars (CANVAS_COOKIE / CANVAS_USERNAME+CANVAS_PASSWORD) take precedence over OAuth \u2014 using session mode. Unset them to use OAuth."
+        "[canvas-parent-mcp] CANVAS_USERNAME+CANVAS_PASSWORD takes precedence over OAuth \u2014 using username/password. Unset them to use OAuth."
       );
     }
-    const acct = { mode: "session", name, baseUrl: cleanBaseUrl };
-    if (cookie) acct.cookie = cookie;
-    if (hasFullUserPass) {
-      acct.username = username;
-      acct.password = password;
-    }
-    return acct;
+    return { mode: "session", name, baseUrl: cleanBaseUrl, username, password };
   }
   if (hasPartialOAuth) {
     const missing = [];
@@ -30920,7 +30927,7 @@ function loadAccount(env = process.env) {
     if (!clientSecret) missing.push("CANVAS_CLIENT_SECRET");
     if (!refreshToken) missing.push("CANVAS_REFRESH_TOKEN");
     throw new Error(
-      `Incomplete OAuth config \u2014 missing: ${missing.join(", ")}. Set all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN (or set CANVAS_TOKEN / CANVAS_COOKIE / CANVAS_USERNAME+CANVAS_PASSWORD instead).`
+      `Incomplete OAuth config \u2014 missing: ${missing.join(", ")}. Set all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN (or set CANVAS_TOKEN / CANVAS_USERNAME+CANVAS_PASSWORD instead).`
     );
   }
   if (hasFullOAuth) {
@@ -30931,11 +30938,11 @@ function loadAccount(env = process.env) {
       clientId,
       clientSecret,
       refreshToken,
-      accessToken: env.CANVAS_ACCESS_TOKEN
+      accessToken: readVar(env, "CANVAS_ACCESS_TOKEN")
     };
   }
   throw new Error(
-    "Missing Canvas auth config. Set one of: CANVAS_TOKEN (personal access token), CANVAS_USERNAME+CANVAS_PASSWORD (auto-login), CANVAS_COOKIE (session cookie jar from canvas-parent-mcp-login), or all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN."
+    "Missing Canvas auth config. Set one of: CANVAS_TOKEN (personal access token), CANVAS_USERNAME+CANVAS_PASSWORD (auto-login), or all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN."
   );
 }
 
@@ -31041,10 +31048,7 @@ async function sessionLogin(opts) {
   const sessionCookies = respCookies.filter(
     (c) => ["canvas_session", "pseudonym_credentials", "_csrf_token", "log_session_id"].includes(c.name)
   );
-  return {
-    baseUrl,
-    cookie: serializeCookies(sessionCookies)
-  };
+  return { cookie: serializeCookies(sessionCookies) };
 }
 
 // src/client.ts
@@ -31054,6 +31058,7 @@ var CanvasClient = class {
   account;
   refreshInFlight = null;
   accessTokenExpiresAt = 0;
+  sessionCookie = null;
   sessionLoginFn;
   constructor(account2, opts = {}) {
     this.account = account2;
@@ -31064,7 +31069,7 @@ var CanvasClient = class {
     return { name: this.account.name, baseUrl: this.account.baseUrl, mode: this.account.mode };
   }
   async request(path, opts = {}) {
-    const res = await this.doRawRequest(path, opts, false);
+    const res = await this.doRawRequest(path, opts);
     const text = await res.text();
     if (opts.responseType === "text") return text;
     return parseJsonBody(text) ?? null;
@@ -31075,7 +31080,7 @@ var CanvasClient = class {
     let url2 = injectPerPage(path, perPage);
     const out = [];
     for (let page = 0; page < maxPages; page++) {
-      const res = await this.doRawRequest(url2, opts, false);
+      const res = await this.doRawRequest(url2, opts);
       const text = await res.text();
       const parsed = parseJsonBody(text) ?? [];
       for (const item of parsed) out.push(item);
@@ -31100,11 +31105,8 @@ var CanvasClient = class {
     } catch {
       throw new ParentDirectoryMissingError(parent);
     }
-    await this.ensureAuth();
     const url2 = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
-    const res = await fetch(url2, {
-      headers: this.getAuthHeaders()
-    });
+    const res = await this.authedFetch(url2, {});
     if (res.status === 404) throw new Error(`Canvas download 404 for ${path}`);
     if (!res.ok) throw new Error(`Canvas download ${res.status} for ${path}`);
     const buf = new Uint8Array(await res.arrayBuffer());
@@ -31115,42 +31117,43 @@ var CanvasClient = class {
       contentType: res.headers.get("content-type") ?? "application/octet-stream"
     };
   }
-  async doRawRequest(path, opts, isRetry) {
-    await this.ensureAuth();
+  async doRawRequest(path, opts) {
     const url2 = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
     const accept = opts.responseType === "text" ? "text/html, text/plain, */*" : "application/json+canvas-string-ids, application/json";
-    const res = await fetch(url2, {
+    const res = await this.authedFetch(url2, {
       method: opts.method ?? "GET",
-      headers: {
-        ...this.getAuthHeaders(),
-        Accept: accept,
-        ...opts.headers ?? {}
-      },
+      headers: { Accept: accept, ...opts.headers ?? {} },
       body: opts.body
     });
+    if (res.status === 404) throw new Error(`Canvas 404 ${path}`);
+    if (res.status >= 500) throw new CanvasUnreachableError(res.status);
+    if (!res.ok) throw new Error(`Canvas ${res.status} ${res.statusText} for ${path}`);
+    return res;
+  }
+  /**
+   * Fetch with auth headers attached and transparent 401 retry. Token mode has
+   * no refresh path so a 401 throws immediately; oauth and session both attempt
+   * one re-auth before giving up. Used by both API requests and file downloads.
+   */
+  async authedFetch(url2, init, isRetry = false) {
+    await this.ensureAuth();
+    const res = await fetch(url2, {
+      ...init,
+      headers: { ...this.getAuthHeaders(), ...init.headers }
+    });
     if (res.status === 401) {
-      if (isRetry || !this.canRefreshAuth()) {
+      if (isRetry || this.account.mode === "token") {
         throw new TokenExpiredError(this.account.mode);
       }
       await this.ensureAuth({ force: true });
-      return this.doRawRequest(path, opts, true);
+      return this.authedFetch(url2, init, true);
     }
-    if (res.status === 404) throw new Error(`Canvas 404 ${path}`);
-    if (res.status >= 500) throw new CanvasUnreachableError(res.status);
-    if (!res.ok) throw new Error(`Canvas ${res.status} ${res.statusText} for ${path}`);
     return res;
   }
-  /** Whether this account can mint or refresh credentials in response to a 401. */
-  canRefreshAuth() {
-    const acct = this.account;
-    if (acct.mode === "oauth") return true;
-    if (acct.mode === "session") return !!acct.username && !!acct.password;
-    return false;
-  }
   getAuthHeaders() {
     const acct = this.account;
     if (acct.mode === "token") return { Authorization: `Bearer ${acct.token}` };
-    if (acct.mode === "session") return { Cookie: acct.cookie };
+    if (acct.mode === "session") return { Cookie: this.sessionCookie };
     return { Authorization: `Bearer ${acct.accessToken}` };
   }
   async ensureAuth(opts = {}) {
@@ -31158,10 +31161,7 @@ var CanvasClient = class {
     if (acct.mode === "token") return;
     if (!opts.force) {
       if (acct.mode === "oauth" && acct.accessToken && Date.now() < this.accessTokenExpiresAt) return;
-      if (acct.mode === "session" && acct.cookie) return;
-    }
-    if (acct.mode === "session" && !this.canRefreshAuth()) {
-      throw new TokenExpiredError("session");
+      if (acct.mode === "session" && this.sessionCookie) return;
     }
     if (this.refreshInFlight) {
       await this.refreshInFlight;
@@ -31180,7 +31180,7 @@ var CanvasClient = class {
       username: acct.username,
       password: acct.password
     });
-    acct.cookie = result.cookie;
+    this.sessionCookie = result.cookie;
   }
   async refreshAccessToken(acct) {
     const body = new URLSearchParams({
@@ -31224,7 +31224,7 @@ function parseLinkHeader(header) {
 }
 var TokenExpiredError = class extends Error {
   constructor(mode, detail) {
-    const base = mode === "token" ? "Canvas access token rejected (401). Check CANVAS_TOKEN \u2014 it may be expired or revoked." : mode === "session" ? "Canvas session cookie rejected (401). Re-run canvas-parent-mcp-login to mint a fresh CANVAS_COOKIE." : "Canvas OAuth refresh failed. Check CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN.";
+    const base = mode === "token" ? "Canvas access token rejected (401). Check CANVAS_TOKEN \u2014 it may be expired or revoked." : mode === "session" ? "Canvas session login failed (401). Check CANVAS_USERNAME / CANVAS_PASSWORD \u2014 they may have changed, or the account may be locked or behind SSO." : "Canvas OAuth refresh failed. Check CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN.";
     super(detail ? `${base} (${detail})` : base);
     this.mode = mode;
     this.detail = detail;
@@ -31642,7 +31642,7 @@ try {
 }
 var account = loadAccount();
 var client = new CanvasClient(account);
-var server = new McpServer({ name: "canvas", version: "0.1.4" });
+var server = new McpServer({ name: "canvas", version: "1.0.1" });
 registerProfileTools(server, client);
 registerObserveeTools(server, client);
 registerCourseTools(server, client);

package/dist/client.js

@@ -7,6 +7,7 @@ export class CanvasClient {
     account;
     refreshInFlight = null;
     accessTokenExpiresAt = 0;
+    sessionCookie = null;
     sessionLoginFn;
     constructor(account, opts = {}) {
         this.account = account;
@@ -17,7 +18,7 @@ export class CanvasClient {
         return { name: this.account.name, baseUrl: this.account.baseUrl, mode: this.account.mode };
     }
     async request(path, opts = {}) {
-        const res = await this.doRawRequest(path, opts, false);
+        const res = await this.doRawRequest(path, opts);
         const text = await res.text();
         if (opts.responseType === 'text')
             return text;
@@ -29,7 +30,7 @@ export class CanvasClient {
         let url = injectPerPage(path, perPage);
         const out = [];
         for (let page = 0; page < maxPages; page++) {
-            const res = await this.doRawRequest(url, opts, false);
+            const res = await this.doRawRequest(url, opts);
             const text = await res.text();
             const parsed = parseJsonBody(text) ?? [];
             for (const item of parsed)
@@ -59,11 +60,8 @@ export class CanvasClient {
         catch {
             throw new ParentDirectoryMissingError(parent);
         }
-        await this.ensureAuth();
         const url = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
-        const res = await fetch(url, {
-            headers: this.getAuthHeaders(),
-        });
+        const res = await this.authedFetch(url, {});
         if (res.status === 404)
             throw new Error(`Canvas download 404 for ${path}`);
         if (!res.ok)
@@ -76,28 +74,16 @@ export class CanvasClient {
             contentType: res.headers.get('content-type') ?? 'application/octet-stream',
         };
     }
-    async doRawRequest(path, opts, isRetry) {
-        await this.ensureAuth();
+    async doRawRequest(path, opts) {
         const url = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
         const accept = opts.responseType === 'text'
             ? 'text/html, text/plain, */*'
             : 'application/json+canvas-string-ids, application/json';
-        const res = await fetch(url, {
+        const res = await this.authedFetch(url, {
             method: opts.method ?? 'GET',
-            headers: {
-                ...this.getAuthHeaders(),
-                Accept: accept,
-                ...(opts.headers ?? {}),
-            },
+            headers: { Accept: accept, ...(opts.headers ?? {}) },
             body: opts.body,
         });
-        if (res.status === 401) {
-            if (isRetry || !this.canRefreshAuth()) {
-                throw new TokenExpiredError(this.account.mode);
-            }
-            await this.ensureAuth({ force: true });
-            return this.doRawRequest(path, opts, true);
-        }
         if (res.status === 404)
             throw new Error(`Canvas 404 ${path}`);
         if (res.status >= 500)
@@ -106,39 +92,45 @@ export class CanvasClient {
             throw new Error(`Canvas ${res.status} ${res.statusText} for ${path}`);
         return res;
     }
-    /** Whether this account can mint or refresh credentials in response to a 401. */
-    canRefreshAuth() {
-        const acct = this.account;
-        if (acct.mode === 'oauth')
-            return true;
-        if (acct.mode === 'session')
-            return !!acct.username && !!acct.password;
-        return false;
+    /**
+     * Fetch with auth headers attached and transparent 401 retry. Token mode has
+     * no refresh path so a 401 throws immediately; oauth and session both attempt
+     * one re-auth before giving up. Used by both API requests and file downloads.
+     */
+    async authedFetch(url, init, isRetry = false) {
+        await this.ensureAuth();
+        const res = await fetch(url, {
+            ...init,
+            headers: { ...this.getAuthHeaders(), ...init.headers },
+        });
+        if (res.status === 401) {
+            if (isRetry || this.account.mode === 'token') {
+                throw new TokenExpiredError(this.account.mode);
+            }
+            await this.ensureAuth({ force: true });
+            return this.authedFetch(url, init, true);
+        }
+        return res;
     }
     getAuthHeaders() {
         const acct = this.account;
-        // For oauth/session: callers always invoke ensureAuth() first, which guarantees the credential is set.
         if (acct.mode === 'token')
             return { Authorization: `Bearer ${acct.token}` };
+        // For oauth/session: callers always invoke ensureAuth() first, which guarantees the credential is set.
         if (acct.mode === 'session')
-            return { Cookie: acct.cookie };
+            return { Cookie: this.sessionCookie };
         return { Authorization: `Bearer ${acct.accessToken}` };
     }
     async ensureAuth(opts = {}) {
         const acct = this.account;
         if (acct.mode === 'token')
             return;
-        // Decide whether the cached creds are still good.
         if (!opts.force) {
             if (acct.mode === 'oauth' && acct.accessToken && Date.now() < this.accessTokenExpiresAt)
                 return;
-            if (acct.mode === 'session' && acct.cookie)
+            if (acct.mode === 'session' && this.sessionCookie)
                 return;
         }
-        // Session mode without u/p has nothing to refresh — caller must rotate CANVAS_COOKIE.
-        if (acct.mode === 'session' && !this.canRefreshAuth()) {
-            throw new TokenExpiredError('session');
-        }
         if (this.refreshInFlight) {
             await this.refreshInFlight;
             return;
@@ -159,7 +151,7 @@ export class CanvasClient {
             username: acct.username,
             password: acct.password,
         });
-        acct.cookie = result.cookie;
+        this.sessionCookie = result.cookie;
     }
     async refreshAccessToken(acct) {
         const body = new URLSearchParams({
@@ -217,7 +209,7 @@ export class TokenExpiredError extends Error {
         const base = mode === 'token'
             ? 'Canvas access token rejected (401). Check CANVAS_TOKEN — it may be expired or revoked.'
             : mode === 'session'
-                ? 'Canvas session cookie rejected (401). Re-run canvas-parent-mcp-login to mint a fresh CANVAS_COOKIE.'
+                ? 'Canvas session login failed (401). Check CANVAS_USERNAME / CANVAS_PASSWORD — they may have changed, or the account may be locked or behind SSO.'
                 : 'Canvas OAuth refresh failed. Check CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN.';
         super(detail ? `${base} (${detail})` : base);
         this.mode = mode;

package/dist/config.js

@@ -1,34 +1,58 @@
+/**
+ * Read an env var, trim whitespace, and treat the empty string as unset. Also
+ * defensively rejects values that look like an unsubstituted shell placeholder
+ * (e.g. "${CANVAS_TOKEN}") — these can leak through .mcp.json env blocks when
+ * the host (Claude Code / Desktop) doesn't expand them, and would otherwise
+ * be sent to Canvas as a literal token and rejected with a confusing 401.
+ */
+function readVar(env, key) {
+    const raw = env[key];
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
 export function loadAccount(env = process.env) {
-    const baseUrl = env.CANVAS_BASE_URL;
+    const baseUrl = readVar(env, 'CANVAS_BASE_URL');
     if (!baseUrl) {
         throw new Error('Missing required env var: CANVAS_BASE_URL. ' +
-            'Set CANVAS_BASE_URL (e.g. https://cms.instructure.com) plus either CANVAS_TOKEN or the OAuth triple.');
+            'Set CANVAS_BASE_URL (e.g. https://cms.instructure.com) plus an auth mode.');
     }
     if (!/^https:\/\//.test(baseUrl)) {
         throw new Error(`CANVAS_BASE_URL must be an https URL, got: '${baseUrl}'`);
     }
     const cleanBaseUrl = baseUrl.replace(/\/$/, '');
-    const name = env.CANVAS_NAME || new URL(cleanBaseUrl).host;
-    const token = env.CANVAS_TOKEN;
-    const cookie = env.CANVAS_COOKIE;
-    const username = env.CANVAS_USERNAME;
-    const password = env.CANVAS_PASSWORD;
-    const clientId = env.CANVAS_CLIENT_ID;
-    const clientSecret = env.CANVAS_CLIENT_SECRET;
-    const refreshToken = env.CANVAS_REFRESH_TOKEN;
+    const name = readVar(env, 'CANVAS_NAME') ?? new URL(cleanBaseUrl).host;
+    const token = readVar(env, 'CANVAS_TOKEN');
+    const username = readVar(env, 'CANVAS_USERNAME');
+    const password = readVar(env, 'CANVAS_PASSWORD');
+    const clientId = readVar(env, 'CANVAS_CLIENT_ID');
+    const clientSecret = readVar(env, 'CANVAS_CLIENT_SECRET');
+    const refreshToken = readVar(env, 'CANVAS_REFRESH_TOKEN');
     const oauthSet = [clientId, clientSecret, refreshToken].filter((v) => !!v);
     const hasFullOAuth = oauthSet.length === 3;
     const hasPartialOAuth = oauthSet.length > 0 && oauthSet.length < 3;
     const hasFullUserPass = !!username && !!password;
     const hasPartialUserPass = (!!username) !== (!!password);
-    const hasSession = !!cookie || hasFullUserPass;
     if (token) {
-        const others = [hasFullOAuth ? 'OAuth' : null, hasSession ? 'session env vars' : null]
-            .filter(Boolean)
-            .join(' and ');
-        if (others) {
-            console.error(`[canvas-mcp] CANVAS_TOKEN takes precedence over ${others} — using CANVAS_TOKEN. ` +
-                `Unset CANVAS_TOKEN to use ${others}.`);
+        const others = [];
+        if (hasFullOAuth)
+            others.push('OAuth env vars');
+        else if (hasPartialOAuth)
+            others.push('partial OAuth env vars (CANVAS_CLIENT_*/CANVAS_REFRESH_TOKEN)');
+        if (hasFullUserPass)
+            others.push('username/password env vars');
+        else if (hasPartialUserPass) {
+            others.push(`partial username/password (only ${username ? 'CANVAS_USERNAME' : 'CANVAS_PASSWORD'} set)`);
+        }
+        if (others.length > 0) {
+            const joined = others.join(' and ');
+            console.error(`[canvas-parent-mcp] CANVAS_TOKEN takes precedence over ${joined} — using CANVAS_TOKEN. ` +
+                `Unset CANVAS_TOKEN to use ${joined}.`);
         }
         return { mode: 'token', name, baseUrl: cleanBaseUrl, token };
     }
@@ -37,19 +61,12 @@ export function loadAccount(env = process.env) {
         throw new Error(`Incomplete username/password config — missing: ${missing}. ` +
             'Set both CANVAS_USERNAME and CANVAS_PASSWORD, or unset both.');
     }
-    if (hasSession) {
+    if (hasFullUserPass) {
         if (hasFullOAuth) {
-            console.error('[canvas-mcp] Session env vars (CANVAS_COOKIE / CANVAS_USERNAME+CANVAS_PASSWORD) take precedence ' +
-                'over OAuth — using session mode. Unset them to use OAuth.');
-        }
-        const acct = { mode: 'session', name, baseUrl: cleanBaseUrl };
-        if (cookie)
-            acct.cookie = cookie;
-        if (hasFullUserPass) {
-            acct.username = username;
-            acct.password = password;
+            console.error('[canvas-parent-mcp] CANVAS_USERNAME+CANVAS_PASSWORD takes precedence over OAuth — using ' +
+                'username/password. Unset them to use OAuth.');
         }
-        return acct;
+        return { mode: 'session', name, baseUrl: cleanBaseUrl, username: username, password: password };
     }
     if (hasPartialOAuth) {
         const missing = [];
@@ -61,7 +78,7 @@ export function loadAccount(env = process.env) {
             missing.push('CANVAS_REFRESH_TOKEN');
         throw new Error(`Incomplete OAuth config — missing: ${missing.join(', ')}. ` +
             'Set all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN ' +
-            '(or set CANVAS_TOKEN / CANVAS_COOKIE / CANVAS_USERNAME+CANVAS_PASSWORD instead).');
+            '(or set CANVAS_TOKEN / CANVAS_USERNAME+CANVAS_PASSWORD instead).');
     }
     if (hasFullOAuth) {
         return {
@@ -71,11 +88,10 @@ export function loadAccount(env = process.env) {
             clientId: clientId,
             clientSecret: clientSecret,
             refreshToken: refreshToken,
-            accessToken: env.CANVAS_ACCESS_TOKEN,
+            accessToken: readVar(env, 'CANVAS_ACCESS_TOKEN'),
         };
     }
     throw new Error('Missing Canvas auth config. Set one of: CANVAS_TOKEN (personal access token), ' +
         'CANVAS_USERNAME+CANVAS_PASSWORD (auto-login), ' +
-        'CANVAS_COOKIE (session cookie jar from canvas-parent-mcp-login), ' +
         'or all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN.');
 }

package/dist/index.js

@@ -29,7 +29,7 @@ import { registerDiscussionTools } from './tools/discussions.js';
 import { registerFileTools } from './tools/files.js';
 const account = loadAccount();
 const client = new CanvasClient(account);
-const server = new McpServer({ name: 'canvas', version: '0.1.4' });
+const server = new McpServer({ name: 'canvas', version: '1.0.1' });
 registerProfileTools(server, client);
 registerObserveeTools(server, client);
 registerCourseTools(server, client);

package/dist/session-login.js

@@ -5,9 +5,10 @@
 // page to capture the CSRF cookie + authenticity_token, then POST credentials
 // and harvest the resulting session cookies (canvas_session, pseudonym_credentials).
 //
-// The cookie jar is what callers persist as CANVAS_COOKIE. CanvasClient sends
-// it on every API request in place of an OAuth bearer token. pseudonym_credentials
-// is the "remember me" cookie and is the one with a meaningful expiry (~14 days);
+// The returned cookie jar is held in memory by CanvasClient.sessionCookie and
+// sent on every API request in place of an OAuth bearer token; on a 401 the
+// client re-invokes sessionLogin to mint a fresh jar. pseudonym_credentials
+// is the "remember me" cookie with a meaningful expiry (~14 days);
 // canvas_session piggybacks on it.
 const 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';
@@ -115,8 +116,5 @@ export async function sessionLogin(opts) {
     // Filter to the cookies that actually authenticate API calls. Path/Secure/HttpOnly
     // attributes are stripped during parseSetCookie, so we just join name=value pairs.
     const sessionCookies = respCookies.filter((c) => ['canvas_session', 'pseudonym_credentials', '_csrf_token', 'log_session_id'].includes(c.name));
-    return {
-        baseUrl,
-        cookie: serializeCookies(sessionCookies),
-    };
+    return { cookie: serializeCookies(sessionCookies) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-parent-mcp",
-  "version": "0.1.4",
+  "version": "1.0.1",
   "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>",
@@ -27,8 +27,7 @@
   "type": "module",
   "bin": {
     "canvas-parent-mcp": "dist/index.js",
-    "canvas-parent-mcp-qr-login": "dist/qr-login-cli.js",
-    "canvas-parent-mcp-login": "dist/session-login-cli.js"
+    "canvas-parent-mcp-qr-login": "dist/qr-login-cli.js"
   },
   "files": [
     "dist",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/canvas-parent-mcp",
     "source": "github"
   },
-  "version": "0.1.4",
+  "version": "1.0.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "canvas-parent-mcp",
-      "version": "0.1.4",
+      "version": "1.0.1",
       "transport": {
         "type": "stdio"
       },
@@ -22,49 +22,42 @@
           "isRequired": true,
           "format": "string"
         },
-        {
-          "name": "CANVAS_TOKEN",
-          "description": "Canvas personal access token (pick ONE auth mode: this, USERNAME+PASSWORD, COOKIE, or OAuth triple)",
-          "isRequired": false,
-          "format": "string",
-          "isSecret": true
-        },
         {
           "name": "CANVAS_USERNAME",
-          "description": "Canvas login username/email — pair with CANVAS_PASSWORD for auto-login (no SSO/2FA)",
+          "description": "Canvas login username/email (recommended) — pair with CANVAS_PASSWORD for auto-login. No SSO/2FA.",
           "isRequired": false,
           "format": "string"
         },
         {
           "name": "CANVAS_PASSWORD",
-          "description": "Canvas password for auto-login — required iff CANVAS_USERNAME is set",
+          "description": "Canvas password (recommended) — required iff CANVAS_USERNAME is set",
           "isRequired": false,
           "format": "string",
           "isSecret": true
         },
         {
-          "name": "CANVAS_COOKIE",
-          "description": "Pre-minted Canvas session cookie jar (from canvas-parent-mcp-login or qr-login CLI)",
+          "name": "CANVAS_TOKEN",
+          "description": "Canvas personal access token (advanced) — most schools have disabled token creation",
           "isRequired": false,
           "format": "string",
           "isSecret": true
         },
         {
           "name": "CANVAS_CLIENT_ID",
-          "description": "Canvas OAuth client ID (required if not using CANVAS_TOKEN)",
+          "description": "Canvas OAuth client ID (advanced — for SSO accounts that can't use username/password)",
           "isRequired": false,
           "format": "string"
         },
         {
           "name": "CANVAS_CLIENT_SECRET",
-          "description": "Canvas OAuth client secret (required if not using CANVAS_TOKEN)",
+          "description": "Canvas OAuth client secret (advanced)",
           "isRequired": false,
           "format": "string",
           "isSecret": true
         },
         {
           "name": "CANVAS_REFRESH_TOKEN",
-          "description": "Canvas OAuth refresh token (required if not using CANVAS_TOKEN)",
+          "description": "Canvas OAuth refresh token (advanced) — bootstrap via canvas-parent-mcp-qr-login",
           "isRequired": false,
           "format": "string",
           "isSecret": true

package/skills/canvas/SKILL.md

@@ -12,7 +12,7 @@ MCP server for Canvas LMS (Instructure) — 18 tools covering profile, observees
 
 ## Setup
 
-Two auth modes — set one. Personal access token is recommended.
+Pick one auth mode. **Username/password is recommended** — most schools have disabled personal-access-token creation.
 
 ### Option A — Claude Code (direct MCP, no mcporter)
 
@@ -26,7 +26,8 @@ Add to `.mcp.json` in your project or `~/.claude/mcp.json`:
       "args": ["-y", "canvas-parent-mcp"],
       "env": {
         "CANVAS_BASE_URL": "https://cms.instructure.com",
-        "CANVAS_TOKEN": "your-personal-access-token",
+        "CANVAS_USERNAME": "me@example.com",
+        "CANVAS_PASSWORD": "your-canvas-password",
         "CANVAS_NAME": "CMS"
       }
     }
@@ -34,40 +35,27 @@ Add to `.mcp.json` in your project or `~/.claude/mcp.json`:
 }
 ```
 
-When admins have disabled token creation, use username/password (auto-login + auto-renew):
+The server logs in lazily on the first request and silently re-mints cookies on 401, so you never have to re-bootstrap. Direct Canvas accounts only — won't work with SAML/Google/Microsoft SSO or 2FA.
+
+#### Advanced alternatives
+
+If your admin still allows tokens, swap `CANVAS_USERNAME`/`CANVAS_PASSWORD` for `CANVAS_TOKEN`:
 
 ```json
-{
-  "mcpServers": {
-    "canvas": {
-      "command": "npx",
-      "args": ["-y", "canvas-parent-mcp"],
-      "env": {
-        "CANVAS_BASE_URL": "https://cms.instructure.com",
-        "CANVAS_USERNAME": "me@example.com",
-        "CANVAS_PASSWORD": "your-canvas-password"
-      }
-    }
-  }
+"env": {
+  "CANVAS_BASE_URL": "https://cms.instructure.com",
+  "CANVAS_TOKEN": "your-personal-access-token"
 }
 ```
 
-Direct Canvas accounts only — won't work with SAML/Google/Microsoft SSO or 2FA. Or, for OAuth instead of a token:
+If your account uses SSO (so username/password won't work), mint OAuth credentials by reusing the Canvas mobile-app QR-login flow (`canvas-parent-mcp-qr-login`), then:
 
 ```json
-{
-  "mcpServers": {
-    "canvas": {
-      "command": "npx",
-      "args": ["-y", "canvas-parent-mcp"],
-      "env": {
-        "CANVAS_BASE_URL": "https://cms.instructure.com",
-        "CANVAS_CLIENT_ID": "...",
-        "CANVAS_CLIENT_SECRET": "...",
-        "CANVAS_REFRESH_TOKEN": "..."
-      }
-    }
-  }
+"env": {
+  "CANVAS_BASE_URL": "https://cms.instructure.com",
+  "CANVAS_CLIENT_ID": "...",
+  "CANVAS_CLIENT_SECRET": "...",
+  "CANVAS_REFRESH_TOKEN": "..."
 }
 ```
 
@@ -90,7 +78,7 @@ npm install && npm run build
 
 ```bash
 cp .env.example .env
-# Edit .env: set CANVAS_BASE_URL plus one of CANVAS_TOKEN, CANVAS_USERNAME+CANVAS_PASSWORD, CANVAS_COOKIE, or the OAuth triple.
+# Edit .env: set CANVAS_BASE_URL plus one of CANVAS_TOKEN, CANVAS_USERNAME+CANVAS_PASSWORD, or the OAuth triple.
 ```
 
 #### 3. Register with mcporter
@@ -99,11 +87,14 @@ cp .env.example .env
 mcporter config add canvas \
   --command "canvas-parent-mcp" \
   --env "CANVAS_BASE_URL=https://cms.instructure.com" \
-  --env "CANVAS_TOKEN=your-personal-access-token" \
+  --env "CANVAS_USERNAME=me@example.com" \
+  --env "CANVAS_PASSWORD=your-canvas-password" \
   --env "CANVAS_NAME=CMS" \
   --config ~/.mcporter/mcporter.json
 ```
 
+(Or substitute `CANVAS_TOKEN` / OAuth env vars per the alternatives above.)
+
 #### 4. Verify
 
 ```bash
@@ -207,5 +198,5 @@ Most tools accept an optional `observeeId` (defaults to `self`) — set it to a
 ## Caution
 
 - `canvas_download_file` writes to disk at `destinationPath` — confirm the path with the user; pass `overwrite:true` to replace.
-- Personal access tokens grant the same access as the user account they were issued for. Treat them as secrets.
+- All auth credentials (password, token, refresh token) grant the same access as the user account. Treat them as secrets — never commit `.env`.
 - Endpoints that return paginated results follow Canvas's RFC 5988 `Link` headers automatically up to 50 pages (5,000 items at the default `per_page=100`).

package/dist/session-login-cli.js

@@ -1,121 +0,0 @@
-#!/usr/bin/env node
-import { sessionLogin, SessionLoginError } from './session-login.js';
-function parseArgs(argv) {
-    const out = {};
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '-h' || a === '--help')
-            out.help = true;
-        else if (a === '-b' || a === '--base-url')
-            out.baseUrl = argv[++i];
-        else if (a === '-u' || a === '--username')
-            out.username = argv[++i];
-        else if (a.startsWith('--base-url='))
-            out.baseUrl = a.slice('--base-url='.length);
-        else if (a.startsWith('--username='))
-            out.username = a.slice('--username='.length);
-    }
-    return out;
-}
-function usage() {
-    return ('Usage: canvas-parent-mcp-login -b <base-url> -u <username>\n\n' +
-        'Logs into Canvas with username/password (no SSO/2FA support) and prints\n' +
-        'CANVAS_BASE_URL / CANVAS_COOKIE env vars to stdout. Pipe stdin to supply the\n' +
-        'password without a prompt:\n\n' +
-        '  canvas-parent-mcp-login -b https://cms.instructure.com -u me@example.com <<< "$PW"\n\n' +
-        'When stdin is a TTY the tool prompts for the password with no echo.\n' +
-        'CANVAS_COOKIE is sensitive — treat it like a password.\n');
-}
-async function readStdinAll() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(chunk);
-    return Buffer.concat(chunks).toString('utf8');
-}
-async function readPasswordFromTty() {
-    return new Promise((resolve, reject) => {
-        process.stderr.write('Password: ');
-        const stdin = process.stdin;
-        stdin.setRawMode(true);
-        stdin.resume();
-        stdin.setEncoding('utf8');
-        let buf = '';
-        const cleanup = () => {
-            stdin.setRawMode(false);
-            stdin.pause();
-            stdin.removeListener('data', onData);
-            process.stderr.write('\n');
-        };
-        const onData = (data) => {
-            for (const ch of data) {
-                if (ch === '\r' || ch === '\n') {
-                    cleanup();
-                    resolve(buf);
-                    return;
-                }
-                if (ch === '\u0003') {
-                    // Ctrl+C
-                    cleanup();
-                    reject(new Error('cancelled'));
-                    return;
-                }
-                if (ch === '\u007f' || ch === '\b') {
-                    // DEL or backspace
-                    buf = buf.slice(0, -1);
-                    continue;
-                }
-                buf += ch;
-            }
-        };
-        stdin.on('data', onData);
-    });
-}
-async function readPassword() {
-    if (process.stdin.isTTY)
-        return readPasswordFromTty();
-    return (await readStdinAll()).replace(/\r?\n$/, '');
-}
-async function main() {
-    const args = parseArgs(process.argv.slice(2));
-    if (args.help) {
-        process.stderr.write(usage());
-        return 0;
-    }
-    if (!args.baseUrl || !args.username) {
-        process.stderr.write(usage());
-        return 2;
-    }
-    let password;
-    try {
-        password = await readPassword();
-    }
-    catch {
-        process.stderr.write('Cancelled.\n');
-        return 130;
-    }
-    if (!password) {
-        process.stderr.write('Password is empty — refusing to attempt login.\n');
-        return 2;
-    }
-    try {
-        const result = await sessionLogin({
-            baseUrl: args.baseUrl,
-            username: args.username,
-            password,
-        });
-        process.stderr.write(`Logged in to ${result.baseUrl}. Add the following to your .env ` +
-            '(CANVAS_COOKIE is sensitive — keep it secret):\n\n');
-        process.stdout.write(`CANVAS_BASE_URL=${result.baseUrl}\n`);
-        process.stdout.write(`CANVAS_COOKIE=${result.cookie}\n`);
-        process.stderr.write('\nFor hands-off auto-renewal (re-mints cookies on 401), also add:\n' +
-            `  CANVAS_USERNAME=${args.username}\n` +
-            '  CANVAS_PASSWORD=<your password>\n');
-        return 0;
-    }
-    catch (err) {
-        const msg = err instanceof SessionLoginError ? err.message : err.message;
-        process.stderr.write(`Login failed: ${msg}\n`);
-        return 1;
-    }
-}
-main().then((code) => process.exit(code));