canvas-parent-mcp 1.0.2 → 1.1.2

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.1.2"
   },
   "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.1.2",
       "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.1.2",
   "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`.
 
@@ -91,3 +108,27 @@ This reuses the same SSO + OAuth endpoints the official Canvas Student/Parent ap
 ## Status
 
 Unofficial — not affiliated with Instructure. AI-maintained.
+
+## Acknowledgement of Terms
+
+By using this MCP server, you acknowledge and agree to the following:
+
+**1. This server accesses your own Canvas account via the official Canvas REST API.** Auth happens via your own personal access token, issued by your institution. It does not — and cannot — access anyone else's enrollments, grades, or messages.
+
+**2. [Instructure's Canvas API Policy](https://www.instructure.com/policies/canvas-api-policy) governs your use of this server**, in addition to your institution's own acceptable-use policy. The clauses most relevant here:
+
+> You may not use our APIs on behalf of any third-party… You may not use or access our APIs for competitive purposes… You may not interfere with our APIs, our systems, or other users… You may not circumvent any contractual usage limits.
+
+On rate limits: *"limits are enforced per user access token… with dynamic throttling."* On data: *"Any user information retrieved through the API—including course enrollments, grades, and profile information—should be considered and treated as private information."*
+
+You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server.
+
+**3. Personal, observer/student/parent use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Instructure, Inc. or any school district. It is a personal automation tool for an authenticated Canvas user (typically a parent observer) to read their own (or their student's) enrollments, assignments, grades, and announcements. Do not use it to bulk-extract a district's course content, redistribute student data, or train AI models on student records.
+
+**4. FERPA + your institution's AUP apply.** Student educational records are protected under the federal Family Educational Rights and Privacy Act (FERPA). Even though your token grants you lawful access, **how you store, redistribute, or feed that data into LLMs is regulated**. Treat any output (grades, assignments, comments, conversations) as confidential student data. Your institution's acceptable-use policy may add further restrictions on automated access — check before automating.
+
+**5. Your token is yours alone.** **Do not commit `CANVAS_API_TOKEN` to git**, do not paste it in shared chats, and rotate it if it's ever exposed. A leaked token grants full Canvas access scoped to your user.
+
+**6. You accept full responsibility** for any consequences of using this server in connection with your Canvas account — rate limiting (dynamic throttling kicks in well below documented limits when Canvas is under load), token revocation, account warnings, institution-admin investigations, or any enforcement action. If Instructure or your institution objects to your use, stop using this server.
+
+This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Instructure's actual Canvas API Policy or your institution's policies.

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).');
+}