canvas-parent-mcp 0.1.2 → 0.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": "0.1.2"
+    "version": "0.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": "0.1.2",
+      "version": "0.1.3",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -37,6 +37,23 @@ CANVAS_TOKEN=your-personal-access-token
 CANVAS_NAME=cms                # optional, defaults to host portion of base URL
 ```
 
+**Username/password (auto-login + auto-renew, simplest when tokens are disabled):**
+
+```
+CANVAS_BASE_URL=https://cms.instructure.com
+CANVAS_USERNAME=me@example.com
+CANVAS_PASSWORD=your-canvas-password
+```
+
+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.
+
+**Session cookie (precomputed, no auto-renewal):**
+
+```
+CANVAS_BASE_URL=https://cms.instructure.com
+CANVAS_COOKIE=canvas_session=...; pseudonym_credentials=...; ...
+```
+
 **OAuth (advanced):**
 
 ```
@@ -46,10 +63,43 @@ CANVAS_CLIENT_SECRET=...
 CANVAS_REFRESH_TOKEN=...
 ```
 
-If both modes are set, the token wins.
+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.
 
 See `.env.example`.
 
+### 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.
+
+### 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:
+
+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=...`.
+3. Run the bundled helper:
+
+   ```
+   npx canvas-parent-mcp-qr-login "<decoded-qr-url>" >> .env
+   ```
+
+   It hits Canvas's public `mobile_verify.json` endpoint to fetch the mobile client_id/client_secret, exchanges the QR's one-time code for an access+refresh token pair, and prints `CANVAS_BASE_URL` / `CANVAS_CLIENT_ID` / `CANVAS_CLIENT_SECRET` / `CANVAS_REFRESH_TOKEN` to stdout. The refresh token is sensitive — treat it like a password.
+
+This reuses the same SSO + OAuth endpoints the official Canvas Student/Parent apps use; from Canvas's perspective the resulting session looks like a mobile-app session. Use it only against accounts you legitimately control.
+
 ## Status
 
 Unofficial — not affiliated with Instructure. AI-maintained.

package/dist/bundle.js

@@ -30873,27 +30873,54 @@ function loadAccount(env = process.env) {
   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 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) {
-    if (hasFullOAuth) {
+    const others = [hasFullOAuth ? "OAuth" : null, hasSession ? "session env vars" : null].filter(Boolean).join(" and ");
+    if (others) {
       console.error(
-        "[canvas-mcp] Both CANVAS_TOKEN and OAuth env vars are set \u2014 using CANVAS_TOKEN. Unset CANVAS_TOKEN to use OAuth."
+        `[canvas-mcp] CANVAS_TOKEN takes precedence over ${others} \u2014 using CANVAS_TOKEN. Unset CANVAS_TOKEN to use ${others}.`
       );
     }
     return { mode: "token", name, baseUrl: cleanBaseUrl, token };
   }
+  if (hasPartialUserPass) {
+    const missing = !username ? "CANVAS_USERNAME" : "CANVAS_PASSWORD";
+    throw new Error(
+      `Incomplete username/password config \u2014 missing: ${missing}. Set both CANVAS_USERNAME and CANVAS_PASSWORD, or unset both.`
+    );
+  }
+  if (hasSession) {
+    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."
+      );
+    }
+    const acct = { mode: "session", name, baseUrl: cleanBaseUrl };
+    if (cookie) acct.cookie = cookie;
+    if (hasFullUserPass) {
+      acct.username = username;
+      acct.password = password;
+    }
+    return acct;
+  }
   if (hasPartialOAuth) {
     const missing = [];
     if (!clientId) missing.push("CANVAS_CLIENT_ID");
     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 instead for personal-access-token auth).`
+      `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).`
     );
   }
   if (hasFullOAuth) {
@@ -30908,21 +30935,129 @@ function loadAccount(env = process.env) {
     };
   }
   throw new Error(
-    "Missing Canvas auth config. Set either CANVAS_TOKEN (personal access token) 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), CANVAS_COOKIE (session cookie jar from canvas-parent-mcp-login), or all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN."
   );
 }
 
 // src/client.ts
 import { writeFile, stat } from "fs/promises";
 import { dirname } 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 {
+  constructor(message) {
+    super(message);
+    this.name = "SessionLoginError";
+  }
+};
+function extractAuthenticityToken(html) {
+  const tagRegex = /<input\b[^>]*\bname=["']authenticity_token["'][^>]*>/gi;
+  const matches = html.match(tagRegex);
+  if (!matches) return null;
+  for (const tag of matches) {
+    const valMatch = tag.match(/\bvalue=["']([^"']+)["']/);
+    if (valMatch) return valMatch[1];
+  }
+  return null;
+}
+function parseSetCookie(setCookieValue) {
+  const semi = setCookieValue.indexOf(";");
+  const nameValue = semi === -1 ? setCookieValue : setCookieValue.slice(0, semi);
+  const eq = nameValue.indexOf("=");
+  if (eq === -1) return null;
+  const name = nameValue.slice(0, eq).trim();
+  const value = nameValue.slice(eq + 1).trim();
+  if (!name) return null;
+  return { name, value };
+}
+function serializeCookies(cookies) {
+  return cookies.map((c) => `${c.name}=${c.value}`).join("; ");
+}
+function collectSetCookies(headers) {
+  const out = [];
+  for (const sc of headers.getSetCookie()) {
+    const parsed = parseSetCookie(sc);
+    if (parsed) out.push(parsed);
+  }
+  return out;
+}
+async function sessionLogin(opts) {
+  const baseUrl = opts.baseUrl.replace(/\/$/, "");
+  const loginUrl = `${baseUrl}/login/canvas`;
+  const getRes = await fetch(loginUrl, {
+    headers: {
+      "User-Agent": USER_AGENT,
+      Accept: "text/html,application/xhtml+xml"
+    }
+  });
+  if (!getRes.ok) {
+    throw new SessionLoginError(
+      `Login page fetch failed: ${getRes.status} ${getRes.statusText}`
+    );
+  }
+  const html = await getRes.text();
+  const initialCookies = collectSetCookies(getRes.headers);
+  const authToken = extractAuthenticityToken(html);
+  if (!authToken) {
+    throw new SessionLoginError(
+      "Could not find authenticity_token on the login page. This Canvas instance may use SSO (SAML/Google/Microsoft) \u2014 direct password login is not available."
+    );
+  }
+  const body = new URLSearchParams();
+  body.append("utf8", "\u2713");
+  body.append("authenticity_token", authToken);
+  body.append("redirect_to_ssl", "1");
+  body.append("pseudonym_session[unique_id]", opts.username);
+  body.append("pseudonym_session[password]", opts.password);
+  body.append("pseudonym_session[remember_me]", "0");
+  body.append("pseudonym_session[remember_me]", "1");
+  const postRes = await fetch(loginUrl, {
+    method: "POST",
+    redirect: "manual",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "text/html,application/xhtml+xml",
+      "User-Agent": USER_AGENT,
+      Cookie: serializeCookies(initialCookies),
+      Origin: baseUrl,
+      Referer: loginUrl
+    },
+    body: body.toString()
+  });
+  const respCookies = collectSetCookies(postRes.headers);
+  const hasCreds = respCookies.some((c) => c.name === "pseudonym_credentials");
+  if (!hasCreds) {
+    const location = postRes.headers.get("location") ?? "";
+    if (location && !location.startsWith(baseUrl) && !location.includes("sso.canvaslms.com")) {
+      throw new SessionLoginError(
+        `Login redirected to an external identity provider (${location.slice(0, 100)}). This Canvas account requires SSO/2FA \u2014 direct password login is not supported.`
+      );
+    }
+    throw new SessionLoginError(
+      "Login response did not include a pseudonym_credentials cookie \u2014 incorrect username or password, or the account is locked."
+    );
+  }
+  const sessionCookies = respCookies.filter(
+    (c) => ["canvas_session", "pseudonym_credentials", "_csrf_token", "log_session_id"].includes(c.name)
+  );
+  return {
+    baseUrl,
+    cookie: serializeCookies(sessionCookies)
+  };
+}
+
+// src/client.ts
 var DEFAULT_PER_PAGE = 100;
 var DEFAULT_MAX_PAGES = 50;
 var CanvasClient = class {
   account;
   refreshInFlight = null;
   accessTokenExpiresAt = 0;
-  constructor(account2) {
+  sessionLoginFn;
+  constructor(account2, opts = {}) {
     this.account = account2;
+    this.sessionLoginFn = opts.sessionLogin ?? sessionLogin;
   }
   /** Account metadata (no secrets) — useful for diagnostics. */
   describe() {
@@ -30965,10 +31100,10 @@ var CanvasClient = class {
     } catch {
       throw new ParentDirectoryMissingError(parent);
     }
-    await this.ensureToken();
+    await this.ensureAuth();
     const url2 = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
     const res = await fetch(url2, {
-      headers: { Authorization: `Bearer ${this.getAccessToken()}` }
+      headers: this.getAuthHeaders()
     });
     if (res.status === 404) throw new Error(`Canvas download 404 for ${path}`);
     if (!res.ok) throw new Error(`Canvas download ${res.status} for ${path}`);
@@ -30981,23 +31116,23 @@ var CanvasClient = class {
     };
   }
   async doRawRequest(path, opts, isRetry) {
-    await this.ensureToken();
+    await this.ensureAuth();
     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, {
       method: opts.method ?? "GET",
       headers: {
-        Authorization: `Bearer ${this.getAccessToken()}`,
+        ...this.getAuthHeaders(),
         Accept: accept,
         ...opts.headers ?? {}
       },
       body: opts.body
     });
     if (res.status === 401) {
-      if (isRetry || this.account.mode === "token") {
+      if (isRetry || !this.canRefreshAuth()) {
         throw new TokenExpiredError(this.account.mode);
       }
-      await this.ensureToken({ force: true });
+      await this.ensureAuth({ force: true });
       return this.doRawRequest(path, opts, true);
     }
     if (res.status === 404) throw new Error(`Canvas 404 ${path}`);
@@ -31005,25 +31140,48 @@ var CanvasClient = class {
     if (!res.ok) throw new Error(`Canvas ${res.status} ${res.statusText} for ${path}`);
     return res;
   }
-  getAccessToken() {
-    if (this.account.mode === "token") return this.account.token;
-    return this.account.accessToken;
+  /** 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 };
+    return { Authorization: `Bearer ${acct.accessToken}` };
   }
-  async ensureToken(opts = {}) {
+  async ensureAuth(opts = {}) {
     const acct = this.account;
     if (acct.mode === "token") return;
-    if (!opts.force && acct.accessToken && Date.now() < this.accessTokenExpiresAt) 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 (this.refreshInFlight) {
       await this.refreshInFlight;
       return;
     }
-    this.refreshInFlight = this.refreshAccessToken(acct);
+    this.refreshInFlight = acct.mode === "oauth" ? this.refreshAccessToken(acct) : this.mintSessionCookie(acct);
     try {
       await this.refreshInFlight;
     } finally {
       this.refreshInFlight = null;
     }
   }
+  async mintSessionCookie(acct) {
+    const result = await this.sessionLoginFn({
+      baseUrl: acct.baseUrl,
+      username: acct.username,
+      password: acct.password
+    });
+    acct.cookie = result.cookie;
+  }
   async refreshAccessToken(acct) {
     const body = new URLSearchParams({
       grant_type: "refresh_token",
@@ -31066,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." : "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 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.";
     super(detail ? `${base} (${detail})` : base);
     this.mode = mode;
     this.detail = detail;
@@ -31484,7 +31642,7 @@ try {
 }
 var account = loadAccount();
 var client = new CanvasClient(account);
-var server = new McpServer({ name: "canvas", version: "0.1.2" });
+var server = new McpServer({ name: "canvas", version: "0.1.3" });
 registerProfileTools(server, client);
 registerObserveeTools(server, client);
 registerCourseTools(server, client);

package/dist/client.js

@@ -1,13 +1,16 @@
 import { writeFile, stat } from 'fs/promises';
 import { dirname } from 'path';
+import { sessionLogin as defaultSessionLogin } from './session-login.js';
 const DEFAULT_PER_PAGE = 100;
 const DEFAULT_MAX_PAGES = 50;
 export class CanvasClient {
     account;
     refreshInFlight = null;
     accessTokenExpiresAt = 0;
-    constructor(account) {
+    sessionLoginFn;
+    constructor(account, opts = {}) {
         this.account = account;
+        this.sessionLoginFn = opts.sessionLogin ?? defaultSessionLogin;
     }
     /** Account metadata (no secrets) — useful for diagnostics. */
     describe() {
@@ -56,10 +59,10 @@ export class CanvasClient {
         catch {
             throw new ParentDirectoryMissingError(parent);
         }
-        await this.ensureToken();
+        await this.ensureAuth();
         const url = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
         const res = await fetch(url, {
-            headers: { Authorization: `Bearer ${this.getAccessToken()}` },
+            headers: this.getAuthHeaders(),
         });
         if (res.status === 404)
             throw new Error(`Canvas download 404 for ${path}`);
@@ -74,7 +77,7 @@ export class CanvasClient {
         };
     }
     async doRawRequest(path, opts, isRetry) {
-        await this.ensureToken();
+        await this.ensureAuth();
         const url = /^https?:\/\//i.test(path) ? path : `${this.account.baseUrl}${path}`;
         const accept = opts.responseType === 'text'
             ? 'text/html, text/plain, */*'
@@ -82,17 +85,17 @@ export class CanvasClient {
         const res = await fetch(url, {
             method: opts.method ?? 'GET',
             headers: {
-                Authorization: `Bearer ${this.getAccessToken()}`,
+                ...this.getAuthHeaders(),
                 Accept: accept,
                 ...(opts.headers ?? {}),
             },
             body: opts.body,
         });
         if (res.status === 401) {
-            if (isRetry || this.account.mode === 'token') {
+            if (isRetry || !this.canRefreshAuth()) {
                 throw new TokenExpiredError(this.account.mode);
             }
-            await this.ensureToken({ force: true });
+            await this.ensureAuth({ force: true });
             return this.doRawRequest(path, opts, true);
         }
         if (res.status === 404)
@@ -103,24 +106,46 @@ export class CanvasClient {
             throw new Error(`Canvas ${res.status} ${res.statusText} for ${path}`);
         return res;
     }
-    getAccessToken() {
-        if (this.account.mode === 'token')
-            return this.account.token;
-        // OAuth mode: callers always invoke ensureToken() first, which guarantees accessToken is set.
-        return this.account.accessToken;
+    /** 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;
     }
-    async ensureToken(opts = {}) {
+    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}` };
+        if (acct.mode === 'session')
+            return { Cookie: acct.cookie };
+        return { Authorization: `Bearer ${acct.accessToken}` };
+    }
+    async ensureAuth(opts = {}) {
         const acct = this.account;
-        // Token mode: nothing to refresh. doRawRequest throws on 401 before reaching here with force=true.
         if (acct.mode === 'token')
             return;
-        if (!opts.force && acct.accessToken && Date.now() < this.accessTokenExpiresAt)
-            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)
+                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;
         }
-        this.refreshInFlight = this.refreshAccessToken(acct);
+        this.refreshInFlight = acct.mode === 'oauth'
+            ? this.refreshAccessToken(acct)
+            : this.mintSessionCookie(acct);
         try {
             await this.refreshInFlight;
         }
@@ -128,6 +153,14 @@ export class CanvasClient {
             this.refreshInFlight = null;
         }
     }
+    async mintSessionCookie(acct) {
+        const result = await this.sessionLoginFn({
+            baseUrl: acct.baseUrl,
+            username: acct.username,
+            password: acct.password,
+        });
+        acct.cookie = result.cookie;
+    }
     async refreshAccessToken(acct) {
         const body = new URLSearchParams({
             grant_type: 'refresh_token',
@@ -183,7 +216,9 @@ export class TokenExpiredError extends Error {
     constructor(mode, detail) {
         const base = mode === 'token'
             ? 'Canvas access token rejected (401). Check CANVAS_TOKEN — it may be expired or revoked.'
-            : 'Canvas OAuth refresh failed. Check CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN.';
+            : 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.';
         super(detail ? `${base} (${detail})` : base);
         this.mode = mode;
         this.detail = detail;

package/dist/config.js

@@ -10,19 +10,47 @@ export function loadAccount(env = process.env) {
     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 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) {
-        if (hasFullOAuth) {
-            console.error('[canvas-mcp] Both CANVAS_TOKEN and OAuth env vars are set — using CANVAS_TOKEN. ' +
-                'Unset CANVAS_TOKEN to use OAuth.');
+        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}.`);
         }
         return { mode: 'token', name, baseUrl: cleanBaseUrl, token };
     }
+    if (hasPartialUserPass) {
+        const missing = !username ? 'CANVAS_USERNAME' : 'CANVAS_PASSWORD';
+        throw new Error(`Incomplete username/password config — missing: ${missing}. ` +
+            'Set both CANVAS_USERNAME and CANVAS_PASSWORD, or unset both.');
+    }
+    if (hasSession) {
+        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;
+        }
+        return acct;
+    }
     if (hasPartialOAuth) {
         const missing = [];
         if (!clientId)
@@ -33,7 +61,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 instead for personal-access-token auth).');
+            '(or set CANVAS_TOKEN / CANVAS_COOKIE / CANVAS_USERNAME+CANVAS_PASSWORD instead).');
     }
     if (hasFullOAuth) {
         return {
@@ -46,6 +74,8 @@ export function loadAccount(env = process.env) {
             accessToken: env.CANVAS_ACCESS_TOKEN,
         };
     }
-    throw new Error('Missing Canvas auth config. Set either CANVAS_TOKEN (personal 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.2' });
+const server = new McpServer({ name: 'canvas', version: '0.1.3' });
 registerProfileTools(server, client);
 registerObserveeTools(server, client);
 registerCourseTools(server, client);

package/dist/qr-login-cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { qrLogin, QrLoginError } from './qr-login.js';
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8').trim();
+}
+async function main() {
+    const arg = process.argv[2];
+    if (arg === '-h' || arg === '--help') {
+        process.stderr.write(usage());
+        return 0;
+    }
+    const qrUrl = arg ?? (process.stdin.isTTY ? '' : await readStdin());
+    if (!qrUrl) {
+        process.stderr.write(usage());
+        return 2;
+    }
+    try {
+        const result = await qrLogin(qrUrl);
+        process.stderr.write(`Logged in as ${result.user.name} (id ${result.user.id}) on ${result.baseUrl}\n` +
+            `Add the following to your .env (refresh token is sensitive — keep it secret):\n\n`);
+        process.stdout.write(`CANVAS_BASE_URL=${result.baseUrl}\n`);
+        process.stdout.write(`CANVAS_CLIENT_ID=${result.clientId}\n`);
+        process.stdout.write(`CANVAS_CLIENT_SECRET=${result.clientSecret}\n`);
+        process.stdout.write(`CANVAS_REFRESH_TOKEN=${result.refreshToken}\n`);
+        return 0;
+    }
+    catch (err) {
+        const msg = err instanceof QrLoginError ? err.message : err.message;
+        process.stderr.write(`QR login failed: ${msg}\n`);
+        return 1;
+    }
+}
+function usage() {
+    return ('Usage: canvas-parent-mcp-qr-login <qr-url>\n' +
+        '   or: echo "<qr-url>" | canvas-parent-mcp-qr-login\n\n' +
+        'Decode the QR shown at <canvas>/profile/qr_mobile_login (any QR-reader app),\n' +
+        'then pass the resulting URL. Outputs CANVAS_* env vars to stdout.\n');
+}
+main().then((code) => process.exit(code));

package/dist/qr-login.js

@@ -0,0 +1,108 @@
+// Canvas mobile QR login flow — mirrors the canvas-ios reference implementation
+// (Core/Core/Features/Login/{MobileVerify,APIOAuth,GetSSOLogin}.swift).
+//
+// 1. The QR encodes:    https://sso.canvaslms.com/canvas/login?domain=<host>&code=<one-time>
+// 2. mobile_verify.json hands out the mobile client_id/client_secret for that domain.
+// 3. POST /login/oauth2/token (authorization_code grant) trades the code for access+refresh tokens.
+//
+// Once we have the refresh_token + client_id + client_secret, the existing CanvasClient
+// OAuth refresh path takes over for ongoing use.
+const SSO_HOSTS = ['sso.canvaslms.com', 'sso.beta.canvaslms.com', 'sso.test.canvaslms.com'];
+export class QrLoginError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'QrLoginError';
+    }
+}
+export function parseQrLoginUrl(qrUrl) {
+    let url;
+    try {
+        url = new URL(qrUrl);
+    }
+    catch {
+        throw new QrLoginError(`Not a valid URL: ${qrUrl}`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new QrLoginError(`QR URL must be https, got ${url.protocol}`);
+    }
+    if (!SSO_HOSTS.includes(url.hostname)) {
+        throw new QrLoginError(`Unrecognized SSO host '${url.hostname}'; expected one of ${SSO_HOSTS.join(', ')}`);
+    }
+    if (url.pathname !== '/canvas/login') {
+        throw new QrLoginError(`Expected path /canvas/login, got '${url.pathname}'`);
+    }
+    const rawDomain = url.searchParams.get('domain');
+    if (!rawDomain)
+        throw new QrLoginError("QR URL is missing 'domain' query parameter");
+    const code = url.searchParams.get('code');
+    if (!code)
+        throw new QrLoginError("QR URL is missing 'code' query parameter");
+    return { ssoHost: url.hostname, domain: normalizeDomain(rawDomain), code };
+}
+function normalizeDomain(raw) {
+    const stripped = raw.replace(/^https?:\/\//, '').replace(/\/$/, '');
+    return stripped;
+}
+export async function fetchMobileClient(domain, ssoHost) {
+    const url = `https://${ssoHost}/api/v1/mobile_verify.json?domain=${encodeURIComponent(domain)}`;
+    const res = await fetch(url, { headers: { Accept: 'application/json' } });
+    if (!res.ok) {
+        const body = (await res.text()).slice(0, 200);
+        throw new QrLoginError(`mobile_verify failed: ${res.status} ${res.statusText}: ${body}`);
+    }
+    const data = (await res.json());
+    if (data.authorized !== true) {
+        throw new QrLoginError(`mobile_verify returned not authorized for domain '${domain}'. ` +
+            'The host may not allow mobile logins.');
+    }
+    if (!data.base_url) {
+        throw new QrLoginError(`mobile_verify response is missing base_url for domain '${domain}'`);
+    }
+    if (!data.client_id || !data.client_secret) {
+        throw new QrLoginError(`mobile_verify response is missing mobile client credentials for domain '${domain}'`);
+    }
+    return {
+        baseUrl: data.base_url.replace(/\/$/, ''),
+        clientId: data.client_id,
+        clientSecret: data.client_secret,
+    };
+}
+export async function exchangeAuthCode(client, code) {
+    const res = await fetch(`${client.baseUrl}/login/oauth2/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({
+            client_id: client.clientId,
+            client_secret: client.clientSecret,
+            grant_type: 'authorization_code',
+            code,
+        }),
+    });
+    if (!res.ok) {
+        const body = (await res.text()).slice(0, 200);
+        throw new QrLoginError(`Token exchange failed: ${res.status} ${res.statusText}: ${body}`);
+    }
+    const data = (await res.json());
+    if (!data.access_token)
+        throw new QrLoginError('Token response missing access_token');
+    if (!data.refresh_token) {
+        throw new QrLoginError('Token response missing refresh_token — cannot persist this session. ' +
+            'The QR code may be one-shot only on this Canvas instance.');
+    }
+    if (!data.user)
+        throw new QrLoginError('Token response missing user');
+    const result = {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        user: data.user,
+    };
+    if (data.expires_in !== undefined)
+        result.expiresIn = data.expires_in;
+    return result;
+}
+export async function qrLogin(qrUrl) {
+    const parsed = parseQrLoginUrl(qrUrl);
+    const client = await fetchMobileClient(parsed.domain, parsed.ssoHost);
+    const tokens = await exchangeAuthCode(client, parsed.code);
+    return { ...client, ...tokens };
+}

package/dist/session-login-cli.js

@@ -0,0 +1,121 @@
+#!/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));

package/dist/session-login.js

@@ -0,0 +1,122 @@
+// Username/password login via the Canvas web form (/login/canvas).
+//
+// Required when the institution has restricted personal-access-token creation
+// to the official mobile app. We reproduce a browser session: GET the login
+// 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);
+// 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';
+export class SessionLoginError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SessionLoginError';
+    }
+}
+export function extractAuthenticityToken(html) {
+    const tagRegex = /<input\b[^>]*\bname=["']authenticity_token["'][^>]*>/gi;
+    const matches = html.match(tagRegex);
+    if (!matches)
+        return null;
+    for (const tag of matches) {
+        const valMatch = tag.match(/\bvalue=["']([^"']+)["']/);
+        if (valMatch)
+            return valMatch[1];
+    }
+    return null;
+}
+export function parseSetCookie(setCookieValue) {
+    const semi = setCookieValue.indexOf(';');
+    const nameValue = semi === -1 ? setCookieValue : setCookieValue.slice(0, semi);
+    const eq = nameValue.indexOf('=');
+    if (eq === -1)
+        return null;
+    const name = nameValue.slice(0, eq).trim();
+    const value = nameValue.slice(eq + 1).trim();
+    if (!name)
+        return null;
+    return { name, value };
+}
+export function serializeCookies(cookies) {
+    return cookies.map((c) => `${c.name}=${c.value}`).join('; ');
+}
+function collectSetCookies(headers) {
+    const out = [];
+    // Node 18+: Headers.getSetCookie() returns each Set-Cookie as a separate string.
+    for (const sc of headers.getSetCookie()) {
+        const parsed = parseSetCookie(sc);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+export async function sessionLogin(opts) {
+    const baseUrl = opts.baseUrl.replace(/\/$/, '');
+    const loginUrl = `${baseUrl}/login/canvas`;
+    // 1. GET the login page to capture the CSRF cookie + authenticity_token form value.
+    const getRes = await fetch(loginUrl, {
+        headers: {
+            'User-Agent': USER_AGENT,
+            Accept: 'text/html,application/xhtml+xml',
+        },
+    });
+    if (!getRes.ok) {
+        throw new SessionLoginError(`Login page fetch failed: ${getRes.status} ${getRes.statusText}`);
+    }
+    const html = await getRes.text();
+    const initialCookies = collectSetCookies(getRes.headers);
+    const authToken = extractAuthenticityToken(html);
+    if (!authToken) {
+        throw new SessionLoginError("Could not find authenticity_token on the login page. " +
+            "This Canvas instance may use SSO (SAML/Google/Microsoft) — direct password login is not available.");
+    }
+    // 2. POST the credentials. Mirror the field set Canvas's web form submits, including
+    //    the duplicate remember_me=0/1 (Rails idiom for unchecked-then-checked) so the
+    //    response carries a long-lived pseudonym_credentials cookie.
+    const body = new URLSearchParams();
+    body.append('utf8', '✓');
+    body.append('authenticity_token', authToken);
+    body.append('redirect_to_ssl', '1');
+    body.append('pseudonym_session[unique_id]', opts.username);
+    body.append('pseudonym_session[password]', opts.password);
+    body.append('pseudonym_session[remember_me]', '0');
+    body.append('pseudonym_session[remember_me]', '1');
+    const postRes = await fetch(loginUrl, {
+        method: 'POST',
+        redirect: 'manual',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Accept: 'text/html,application/xhtml+xml',
+            'User-Agent': USER_AGENT,
+            Cookie: serializeCookies(initialCookies),
+            Origin: baseUrl,
+            Referer: loginUrl,
+        },
+        body: body.toString(),
+    });
+    // 3. Verify success by looking for the pseudonym_credentials cookie. Canvas sets it
+    //    only when authentication actually succeeded; a failed login returns a fresh
+    //    csrf token but no credentials cookie.
+    const respCookies = collectSetCookies(postRes.headers);
+    const hasCreds = respCookies.some((c) => c.name === 'pseudonym_credentials');
+    if (!hasCreds) {
+        const location = postRes.headers.get('location') ?? '';
+        if (location && !location.startsWith(baseUrl) && !location.includes('sso.canvaslms.com')) {
+            throw new SessionLoginError(`Login redirected to an external identity provider (${location.slice(0, 100)}). ` +
+                'This Canvas account requires SSO/2FA — direct password login is not supported.');
+        }
+        throw new SessionLoginError('Login response did not include a pseudonym_credentials cookie — ' +
+            'incorrect username or password, or the account is locked.');
+    }
+    // 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),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-parent-mcp",
-  "version": "0.1.2",
+  "version": "0.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>",
@@ -26,7 +26,9 @@
   ],
   "type": "module",
   "bin": {
-    "canvas-parent-mcp": "dist/index.js"
+    "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"
   },
   "files": [
     "dist",

package/server.json

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