canvas-parent-mcp 1.0.2 → 1.0.3

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/README.md

@@ -27,9 +27,28 @@ Tools that the harness will gate as write/IO operations: `canvas_download_file`.
 
 ## Configuration
 
-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.
+Set `CANVAS_BASE_URL` plus one of four auth modes. `canvas-parent-mcp` tries them in priority order:
 
-**Username/password (recommended):**
+1. **`CANVAS_TOKEN`** → personal access token
+2. **`CANVAS_CLIENT_ID` + `CANVAS_CLIENT_SECRET` + `CANVAS_REFRESH_TOKEN`** → OAuth
+3. **`CANVAS_USERNAME` + `CANVAS_PASSWORD`** → session-scrape (direct Canvas accounts only)
+4. **fetchproxy fallback** → no env vars needed; reads `canvas_session` + `pseudonym_credentials` cookies from your signed-in Canvas tab via the [fetchproxy](https://github.com/chrischall/fetchproxy) browser extension
+
+If none succeed, you get an error that names every escape hatch.
+
+### Mode A — fetchproxy fallback (recommended, zero config)
+
+```
+CANVAS_BASE_URL=https://cms.instructure.com
+```
+
+Install the fetchproxy 0.3.0 Chrome / Safari extension (Chrome Web Store / Safari `.dmg`), sign into your Canvas instance once, and the MCP reads your session cookies at startup. After that, all Canvas API calls go directly from Node — the extension is **not** in the request hot path. Works with any auth flow (SSO/SAML/2FA included) because Canvas itself handled the sign-in.
+
+Multiple districts? Declared domain `instructure.com` matches every `*.instructure.com` host, so you only pair the extension once. The MCP uses whichever district you set in `CANVAS_BASE_URL`.
+
+Set `CANVAS_DISABLE_FETCHPROXY=1` to opt out (missing creds become a hard error — useful in headless CI).
+
+### Mode B — username/password (legacy session-scrape)
 
 ```
 CANVAS_BASE_URL=https://cms.instructure.com
@@ -38,12 +57,10 @@ CANVAS_PASSWORD=your-canvas-password
 CANVAS_NAME=cms                # optional, defaults to host portion of base URL
 ```
 
-**Direct Canvas accounts only** — won't work with SAML/Google/Microsoft SSO or 2FA. Treat `.env` like a password file: do not commit it.
+**Direct Canvas accounts only** — won't work with SAML/Google/Microsoft SSO or 2FA. Brittle (breaks on every Canvas login-page restyling). Prefer fetchproxy if your tab is already signed in. Treat `.env` like a password file.
 
 ### Advanced alternatives
 
-If your admin still allows tokens, or your account uses SSO (so username/password won't work), pick one of these instead:
-
 <details>
 <summary><b>Personal access token</b> — simplest if your admin allows it</summary>
 
@@ -65,10 +82,10 @@ CANVAS_CLIENT_SECRET=...
 CANVAS_REFRESH_TOKEN=...
 ```
 
-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.
+If your account uses SSO and you can't use fetchproxy (e.g. headless server), 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>
 
-**Precedence when multiple are set:** `CANVAS_TOKEN` > `CANVAS_USERNAME`+`CANVAS_PASSWORD` > OAuth.
+**Precedence when multiple are set:** `CANVAS_TOKEN` > username/password > OAuth > fetchproxy.
 
 See `.env.example`.
 

package/dist/auth.js

@@ -0,0 +1,167 @@
+// ────────────────────────────────────────────────────────────────────────────
+// Auth resolution — Pattern A template
+// ────────────────────────────────────────────────────────────────────────────
+//
+// Canvas supports four auth paths. This file picks one, in priority order,
+// and hands the chosen path to `CanvasClient`. It mirrors the Pattern A
+// shape used by sibling MCPs (ofw-mcp/src/auth.ts, signupgenius-mcp/src/auth.ts)
+// so all the MCPs in this family stay structurally aligned.
+//
+// THE FOUR PATHS, in priority order:
+//
+//   1. Personal access token (existing)
+//      CANVAS_TOKEN set → stateless `Authorization: Bearer <token>`. The
+//      most reliable mode but most schools have disabled token creation
+//      for non-admins. Unchanged from pre-fetchproxy behavior.
+//
+//   2. OAuth refresh token (existing)
+//      CANVAS_CLIENT_ID + CANVAS_CLIENT_SECRET + CANVAS_REFRESH_TOKEN →
+//      `grant_type=refresh_token` against `/login/oauth2/token`, bootstrap
+//      via the bundled QR-login helper. Unchanged.
+//
+//   3. Username/password session-scrape (existing)
+//      CANVAS_USERNAME + CANVAS_PASSWORD → scrape `authenticity_token`
+//      from `/login/canvas`, POST creds, capture `canvas_session` +
+//      `pseudonym_credentials` cookies. Brittle (breaks on SSO/2FA and
+//      every Canvas login-page restyling) but works for direct Canvas
+//      accounts. Unchanged from pre-fetchproxy behavior.
+//
+//   4. fetchproxy fallback (new)
+//      When no env vars are set, lift the user's session out of their
+//      already-signed-in canvas tab. `@fetchproxy/bootstrap` opens a
+//      one-shot WebSocket bridge, asks the extension for the
+//      `canvas_session` + `pseudonym_credentials` cookies (declared
+//      upfront — that's the security boundary), and closes the bridge.
+//      Subsequent Canvas API calls go out via plain Node `fetch()` with
+//      those cookies attached — fetchproxy is NOT in the request hot path.
+//
+//      Note: `pseudonym_credentials` is HttpOnly, which is fine —
+//      @fetchproxy/bootstrap@^0.3.0 uses `chrome.cookies.get` to read
+//      it, and the security gate is the declared cookie key list, not
+//      HttpOnly status.
+//
+//      Users opt out with CANVAS_DISABLE_FETCHPROXY=1 (anyone who wants
+//      the old behavior of "fail loudly when creds are missing").
+//
+//   5. Error
+//      Nothing to authenticate with. We throw a message that names every
+//      escape hatch the user can try.
+//
+// Testability:
+//   - `@fetchproxy/bootstrap` is mocked at the module boundary in tests.
+//   - `loadAccount()` (the existing env-var resolver) is reused as-is so
+//     the legacy paths keep working unchanged.
+import { bootstrap } from '@fetchproxy/bootstrap';
+import { loadAccount } from './config.js';
+import pkg from '../package.json' with { type: 'json' };
+function readEnv(key) {
+    const raw = process.env[key];
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed === 'undefined' || trimmed === 'null')
+        return undefined;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+function fetchproxyDisabled() {
+    const raw = readEnv('CANVAS_DISABLE_FETCHPROXY');
+    if (raw === undefined)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(raw.toLowerCase());
+}
+/**
+ * The exact error message `loadAccount()` throws when NO auth env vars are
+ * set. We catch this specific string so partial-config errors (which the
+ * user MUST fix) still propagate, but the "you didn't set anything at all"
+ * case falls through to fetchproxy.
+ */
+const NO_ENV_CONFIG_MARKER = 'Missing Canvas auth config';
+/**
+ * Resolve Canvas auth using the four-path priority described at the top of
+ * this file. Throws with an actionable message when no path succeeds.
+ */
+export async function resolveAuth() {
+    // ── Paths 1, 2, 3: env-var credentials. loadAccount() handles precedence,
+    //    partial-config errors, and env-var sanitization for us.
+    try {
+        const account = loadAccount();
+        return { account, source: 'env' };
+    }
+    catch (e) {
+        // Partial-config errors (missing one of USERNAME/PASSWORD, incomplete
+        // OAuth triple, non-https BASE_URL, etc.) are USER MISTAKES — they
+        // propagate. Only the "no auth config set at all" case falls through.
+        if (!e.message.startsWith(NO_ENV_CONFIG_MARKER)) {
+            throw e;
+        }
+    }
+    // ── Path 4: fetchproxy fallback.
+    if (!fetchproxyDisabled()) {
+        // CANVAS_BASE_URL is guaranteed valid here — loadAccount() validates it
+        // before throwing the NO_ENV_CONFIG_MARKER error we caught above.
+        const baseUrl = readEnv('CANVAS_BASE_URL');
+        const baseHost = new URL(baseUrl).hostname;
+        // Wildcard match: Canvas tenants live on per-district subdomains of
+        // *.instructure.com. The 0.2.0+ matcher does `*.${domain}` matching, so
+        // declaring `instructure.com` covers every district the user might
+        // switch between. Self-hosted Canvas installations (rare) declare the
+        // literal hostname instead.
+        const declaredDomain = baseHost.endsWith('.instructure.com')
+            ? 'instructure.com'
+            : baseHost;
+        const name = readEnv('CANVAS_NAME') ?? baseHost;
+        const cleanBaseUrl = baseUrl.replace(/\/$/, '');
+        try {
+            const session = await bootstrap({
+                serverName: pkg.name,
+                version: pkg.version,
+                domains: [declaredDomain],
+                declare: {
+                    cookies: ['canvas_session', 'pseudonym_credentials'],
+                    localStorage: [],
+                    sessionStorage: [],
+                    captureHeaders: [],
+                },
+            });
+            const canvasSession = session.cookies['canvas_session'];
+            const pseudoCreds = session.cookies['pseudonym_credentials'];
+            if (!canvasSession || !pseudoCreds) {
+                throw new Error(`required cookies not found on ${baseHost}. ` +
+                    'Sign into your Canvas instance in the browser ' +
+                    '(with the fetchproxy extension installed) and retry.');
+            }
+            const cookie = `canvas_session=${canvasSession}; pseudonym_credentials=${pseudoCreds}`;
+            // Synthesize a session account with empty creds — the client will see
+            // `preloaded` and skip the form login. This mirrors the cookie shape
+            // the legacy session-scrape path produces, so everything downstream
+            // (Cookie header, 401-retry, file downloads) keeps working.
+            const account = {
+                mode: 'session',
+                name,
+                baseUrl: cleanBaseUrl,
+                username: '',
+                password: '',
+            };
+            return {
+                account,
+                preloaded: { cookie },
+                source: 'fetchproxy',
+            };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Canvas auth: no CANVAS_TOKEN, CANVAS_CLIENT_*/CANVAS_REFRESH_TOKEN, or CANVAS_USERNAME/CANVAS_PASSWORD set, ` +
+                `and fetchproxy fallback failed: ${msg}`);
+        }
+    }
+    // ── Path 5: nothing configured and fetchproxy explicitly disabled.
+    throw new Error('Missing Canvas auth config. Set one of: CANVAS_TOKEN (personal access token), ' +
+        'CANVAS_USERNAME+CANVAS_PASSWORD (auto-login), ' +
+        'all three of CANVAS_CLIENT_ID, CANVAS_CLIENT_SECRET, CANVAS_REFRESH_TOKEN (OAuth), ' +
+        'or install the fetchproxy extension and sign into your Canvas instance ' +
+        '(unset CANVAS_DISABLE_FETCHPROXY if it is set).');
+}