canvas-parent-mcp 1.1.8 → 1.2.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canvas-parent-mcp",
   "displayName": "Canvas LMS",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "description": "Canvas LMS (Instructure) MCP server for Claude — courses, grades, assignments, announcements, planner, conversations, files",
   "author": {
     "name": "Chris Hall",
@@ -20,6 +20,6 @@
     "education",
     "mcp"
   ],
-  "skills": "./SKILL.md",
+  "skills": "./skills/",
   "mcp": "./.mcp.json"
 }

package/dist/bundle.js

@@ -34989,6 +34989,7 @@ var KNOWN_CAPABILITIES = /* @__PURE__ */ new Set([
   "capture_request_header",
   "capture_redirect",
   "read_indexed_db",
+  "read_dom",
   "download"
 ]);
 
@@ -35290,6 +35291,44 @@ function assertIndexedDbScopesArray(value, label) {
     }
   }
 }
+var DOM_SELECTOR_RE = /^[^-]{1,512}$/;
+var DOM_ATTRIBUTE_RE = /^[A-Za-z_:][A-Za-z0-9_:.\-]{0,127}$/;
+function assertDomSelectorsArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new ProtocolError(`${label}: expected array, got ${typeof value}`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    assertObject(entry, `${label}[${i}]`);
+    if (entry.name === void 0) {
+      throw new ProtocolError(`${label}[${i}].name: missing`);
+    }
+    if (entry.selector === void 0) {
+      throw new ProtocolError(`${label}[${i}].selector: missing`);
+    }
+    if (typeof entry.name !== "string" || !SCOPE_KEY_RE.test(entry.name)) {
+      throw new ProtocolError(`${label}[${i}].name: invalid ${JSON.stringify(entry.name)}`);
+    }
+    if (typeof entry.selector !== "string" || !DOM_SELECTOR_RE.test(entry.selector)) {
+      throw new ProtocolError(`${label}[${i}].selector: invalid ${JSON.stringify(entry.selector)}`);
+    }
+    if (entry.attribute !== void 0) {
+      if (typeof entry.attribute !== "string" || !DOM_ATTRIBUTE_RE.test(entry.attribute)) {
+        throw new ProtocolError(`${label}[${i}].attribute: invalid ${JSON.stringify(entry.attribute)}`);
+      }
+    }
+    if (seen.has(entry.name)) {
+      throw new ProtocolError(`${label}: duplicate name ${JSON.stringify(entry.name)}`);
+    }
+    seen.add(entry.name);
+    for (const k of Object.keys(entry)) {
+      if (k !== "name" && k !== "selector" && k !== "attribute") {
+        throw new ProtocolError(`${label}[${i}]: unexpected field ${JSON.stringify(k)}`);
+      }
+    }
+  }
+}
 function validateFrame(raw) {
   assertObject(raw, "frame");
   const t = raw.type;
@@ -35365,6 +35404,9 @@ function validateHello(raw) {
     if (raw.sessionStoragePointers !== void 0) {
       assertStoragePointersArray(raw.sessionStoragePointers, "hello.sessionStoragePointers", raw.sessionStorageKeys);
     }
+    if (raw.domSelectors !== void 0) {
+      assertDomSelectorsArray(raw.domSelectors, "hello.domSelectors");
+    }
     assertBase64(raw.identityX25519Pub, "hello.identityX25519Pub");
     assertBase64(raw.identityEd25519Pub, "hello.identityEd25519Pub");
     assertBase64(raw.sessionNonce, "hello.sessionNonce");
@@ -35599,6 +35641,21 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
+  if (raw.op === "read_dom") {
+    assertObject(raw.init, "inner.init");
+    if (raw.init.origin === void 0)
+      throw new ProtocolError("inner.init.origin: missing");
+    if (raw.init.names === void 0)
+      throw new ProtocolError("inner.init.names: missing");
+    assertHttpsOriginOnly(raw.init.origin, "inner.init.origin");
+    assertNonEmptyKeyArray(raw.init.names, "inner.init.names");
+    for (const k of Object.keys(raw.init)) {
+      if (k !== "origin" && k !== "names") {
+        throw new ProtocolError(`inner.init: unexpected field ${JSON.stringify(k)} on read_dom`);
+      }
+    }
+    return raw;
+  }
   if (raw.op === "download") {
     assertObject(raw.init, "inner.init");
     if (raw.init.url === void 0) {
@@ -35624,7 +35681,7 @@ function validateInnerRequest(raw) {
     }
     return raw;
   }
-  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "download"; got ${JSON.stringify(raw.op)}`);
+  throw new ProtocolError(`inner.op: must be one of "fetch", "read_cookies", "read_local_storage", "read_session_storage", "capture_request_header", "capture_redirect", "read_indexed_db", "read_dom", "download"; got ${JSON.stringify(raw.op)}`);
 }
 function assertNonEmptyKeyArray(value, label) {
   if (!Array.isArray(value)) {
@@ -35709,6 +35766,13 @@ function validateInnerResponse(raw) {
       assertObject(raw.values, "inner.values");
       return raw;
     }
+    if (op === "read_dom") {
+      if (raw.values === void 0) {
+        throw new ProtocolError("inner.values: missing on read_dom response");
+      }
+      assertStringMap(raw.values, "inner.values");
+      return raw;
+    }
     if (op === "download") {
       assertObject(raw.value, "inner.value");
       assertString(raw.value.path, "inner.value.path");
@@ -36048,6 +36112,13 @@ async function buildServerHello(opts) {
       jsonPointer: d.jsonPointer
     }));
   }
+  if (opts.domSelectors && opts.domSelectors.length > 0) {
+    hello.domSelectors = opts.domSelectors.map((d) => ({
+      name: d.name,
+      selector: d.selector,
+      ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+    }));
+  }
   return hello;
 }
 
@@ -36137,7 +36208,8 @@ async function startHost(opts) {
     captureHeaders: opts.ownCaptureHeaders,
     indexedDbScopes: opts.ownIndexedDbScopes,
     localStoragePointers: opts.ownLocalStoragePointers,
-    sessionStoragePointers: opts.ownSessionStoragePointers
+    sessionStoragePointers: opts.ownSessionStoragePointers,
+    domSelectors: opts.ownDomSelectors
   });
   const ownSessionNonce = fromB64(ownHello.sessionNonce);
   let extensionWs = null;
@@ -36372,6 +36444,7 @@ async function startPeer(opts) {
     sessionStorageKeys: opts.sessionStorageKeys,
     captureHeaders: opts.captureHeaders,
     indexedDbScopes: opts.indexedDbScopes,
+    domSelectors: opts.domSelectors,
     localStoragePointers: opts.localStoragePointers,
     sessionStoragePointers: opts.sessionStoragePointers
   });
@@ -36779,6 +36852,11 @@ var FetchproxyServer = class {
         key: d.key,
         jsonPointer: d.jsonPointer
       })),
+      domSelectors: (opts.domSelectors ?? []).map((d) => ({
+        name: d.name,
+        selector: d.selector,
+        ...d.attribute !== void 0 ? { attribute: d.attribute } : {}
+      })),
       // 0.8.0+: timer + lazy-revive default to ON. Every realty MCP
       // adapter was about to set these to the same numbers anyway; the
       // back-door is `0` (explicit opt-out) if a caller genuinely wants
@@ -36899,6 +36977,7 @@ var FetchproxyServer = class {
         ownIndexedDbScopes: this.opts.indexedDbScopes,
         ownLocalStoragePointers: this.opts.localStoragePointers,
         ownSessionStoragePointers: this.opts.sessionStoragePointers,
+        ownDomSelectors: this.opts.domSelectors,
         onPairCode: this.opts.onPairCode
       });
       this.hostHandle.onOwnInner((inner) => this.onInner(inner));
@@ -36926,7 +37005,8 @@ var FetchproxyServer = class {
         captureHeaders: this.opts.captureHeaders,
         indexedDbScopes: this.opts.indexedDbScopes,
         localStoragePointers: this.opts.localStoragePointers,
-        sessionStoragePointers: this.opts.sessionStoragePointers
+        sessionStoragePointers: this.opts.sessionStoragePointers,
+        domSelectors: this.opts.domSelectors
       });
       this.peerHandle.onInner((inner) => this.onInner(inner));
       this.peerHandle.onRenegotiate(() => {
@@ -37901,6 +37981,46 @@ var FetchproxyServer = class {
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
   }
+  /**
+   * 1.4.0+: read declared DOM values from the user's signed-in tab.
+   * Requires `'read_dom'` in capabilities AND every requested `name` to
+   * match a declared `domSelectors` entry. The extension reads each
+   * declared selector from the matched tab's DOM (isolated-world
+   * `querySelector`, value or attribute) — no page-JS execution.
+   *
+   * Returns a `Record<string, string>` of `name → value`, with names
+   * whose element (or attribute) was absent omitted. Throws
+   * `FetchproxyProtocolError` on bridge failures and a plain `Error` on
+   * developer mistakes (undeclared capability, undeclared name).
+   */
+  async readDom(opts) {
+    if (!this.opts.capabilities.includes("read_dom")) {
+      throw new Error('FetchproxyServer.readDom(): MCP did not declare "read_dom" in capabilities');
+    }
+    await this.ensureConnected();
+    this.throwIfPendingPair();
+    if (!Array.isArray(opts.names) || opts.names.length === 0) {
+      throw new Error("FetchproxyServer.readDom: opts.names must be a non-empty array");
+    }
+    this.assertScopeSubset(opts.names, this.opts.domSelectors.map((d) => d.name), "domSelectors");
+    if (opts.subdomain !== void 0)
+      assertSubdomainLabel(opts.subdomain);
+    const baseDomain = this.resolveBaseDomain(opts.domain);
+    const host = opts.subdomain ? `${opts.subdomain}.${baseDomain}` : baseDomain;
+    const origin = `https://${host}`;
+    const id = this.nextRequestId++;
+    const inner = {
+      type: "request",
+      id,
+      op: "read_dom",
+      init: { origin, names: [...opts.names] }
+    };
+    const pending = new Promise((resolve, reject) => {
+      this.pendingStorage.set(id, { resolve, reject });
+    });
+    await this.sendInnerFrame(inner);
+    return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
+  }
   assertScopeSubset(requested, declared, label) {
     const undeclared = undeclaredKeys(requested, declared);
     if (undeclared.length > 0) {
@@ -37972,7 +38092,7 @@ var FetchproxyServer = class {
     if (storageCb) {
       this.pendingStorage.delete(inner.id);
       if (inner.ok) {
-        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage") && inner.values) {
+        if ((inner.op === "read_local_storage" || inner.op === "read_session_storage" || inner.op === "read_dom") && inner.values) {
           storageCb.resolve({ ...inner.values });
         } else {
           storageCb.reject(new FetchproxyProtocolError(`unexpected ${String(inner.op)} response on storage awaiter`));
@@ -38379,7 +38499,7 @@ function loadAccount(env = process.env) {
 // package.json
 var package_default = {
   name: "canvas-parent-mcp",
-  version: "1.1.8",
+  version: "1.2.0",
   mcpName: "io.github.chrischall/canvas-parent-mcp",
   description: "Canvas LMS (Instructure) MCP server \u2014 student/observer read access with optional file download",
   author: "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -38423,7 +38543,7 @@ var package_default = {
     "test:watch": "vitest"
   },
   dependencies: {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -38434,7 +38554,7 @@ var package_default = {
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     esbuild: "^0.28.0",
-    typescript: "^6.0.3",
+    typescript: "^7.0.2",
     vitest: "^4.1.7"
   }
 };
@@ -39355,7 +39475,7 @@ try {
 }
 await runMcp({
   name: "canvas",
-  version: "1.1.8",
+  version: "1.2.0",
   // x-release-please-version
   tools: [
     (server) => {

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-parent-mcp",
-  "version": "1.1.8",
+  "version": "1.2.0",
   "mcpName": "io.github.chrischall/canvas-parent-mcp",
   "description": "Canvas LMS (Instructure) MCP server — student/observer read access with optional file download",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -44,7 +44,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.12.0",
+    "@chrischall/mcp-utils": "^0.13.0",
     "@fetchproxy/bootstrap": "^1.0.0",
     "@fetchproxy/server": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -55,7 +55,7 @@
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.7"
   }
 }

package/server.json

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

package/skills/canvas-parent/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: canvas-parent-mcp
+description: This skill should be used when the user asks about Canvas LMS data — their own student account or any observed student. Triggers on phrases like "check Canvas", "what's my grade", "Canvas inbox", "what's due", "missing assignments", "Canvas LMS", "Instructure", "course announcements", "syllabus", or any request about courses, assignments, grades, conversations, announcements, planner items, or files in Canvas.
+---
+
+# canvas-parent-mcp
+
+MCP server for Canvas LMS (Instructure) — read courses, grades, assignments, announcements, planner items, and conversations; download course files. Mirrors the parent/observer scope of the sibling `infinitecampus-mcp`.
+
+- **npm:** [npmjs.com/package/canvas-parent-mcp](https://www.npmjs.com/package/canvas-parent-mcp)
+- **Source:** [github.com/chrischall/canvas-parent-mcp](https://github.com/chrischall/canvas-parent-mcp)
+
+## Setup
+
+### Option A — npx (recommended)
+
+Add to `.mcp.json` in your project or `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "npx",
+      "args": ["-y", "canvas-parent-mcp"],
+      "env": {
+        "CANVAS_BASE_URL": "https://cms.instructure.com"
+      }
+    }
+  }
+}
+```
+
+With the [fetchproxy extension](https://github.com/chrischall/fetchproxy) installed and a signed-in Canvas tab, that's enough — the MCP reads your session cookies at startup. Add `CANVAS_TOKEN`, `CANVAS_CLIENT_*`/`CANVAS_REFRESH_TOKEN`, or `CANVAS_USERNAME`/`CANVAS_PASSWORD` to the `env` block if you'd rather use one of those modes.
+
+### Option B — from source
+
+```bash
+git clone https://github.com/chrischall/canvas-parent-mcp
+cd canvas-parent-mcp
+npm install && npm run build
+```
+
+## Authentication
+
+**fetchproxy fallback (recommended, zero-config).** Set only `CANVAS_BASE_URL`. Install the [fetchproxy](https://github.com/chrischall/fetchproxy) browser extension, sign into your Canvas instance once. The MCP reads `canvas_session` + `pseudonym_credentials` cookies from your tab at startup; all API calls go directly from Node after that. Works with any auth flow (SSO/SAML/2FA included).
+
+### Alternatives (env-var)
+
+- **Personal access token** — set `CANVAS_TOKEN`. Most institutions have disabled this for non-admins.
+- **OAuth** — set `CANVAS_CLIENT_ID`, `CANVAS_CLIENT_SECRET`, `CANVAS_REFRESH_TOKEN`. Bootstrap via `canvas-parent-mcp-qr-login`.
+- **Username/password (session-scrape)** — set `CANVAS_USERNAME` + `CANVAS_PASSWORD`. Direct Canvas accounts only (no SSO/2FA). Brittle.
+
+Precedence when multiple are set: `CANVAS_TOKEN` > username/password > OAuth > fetchproxy. Set `CANVAS_DISABLE_FETCHPROXY=1` to opt out of the fallback.
+
+## Tools (prefix `canvas_`)
+
+### Profile & observees
+- `canvas_get_profile` — your Canvas profile
+- `canvas_list_observees` — students linked to your observer account
+
+### Courses
+- `canvas_list_courses` — your active courses with grades
+- `canvas_get_course(courseId)` — course detail with syllabus + teachers
+
+### Assignments & submissions
+- `canvas_list_assignments(courseId)` — assignments in a course
+- `canvas_list_missing_submissions` — past-due unsubmitted work
+- `canvas_get_submission(courseId, assignmentId)` — your submission with comments + rubric
+- `canvas_list_recent_submissions(courseId)` — recently graded submissions (default 14d)
+
+### Grades
+- `canvas_list_enrollments` — per-course grades
+
+### Calendar & planner
+- `canvas_list_calendar_events` — calendar events / assignments
+- `canvas_list_upcoming_events` — server-curated next 7 days
+- `canvas_list_planner_items` — unified to-do feed
+
+### Communication
+- `canvas_list_announcements(contextCodes)` — course announcements
+- `canvas_list_conversations` — inbox
+- `canvas_get_conversation(id)` — full conversation thread
+- `canvas_list_discussion_topics(courseId)` — course discussion topics
+
+### Files
+- `canvas_list_course_files(courseId)` — file metadata
+- `canvas_download_file(url, destinationPath)` — download a file to disk
+
+## Notes
+
+- Set `CANVAS_NAME` if you want a friendly label other than the host portion of the base URL.
+- All read tools that target a user accept an optional `observeeId` parameter (defaults to `self`) — useful when an observer is checking on a linked student.

package/skills/canvas-parent-api/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: canvas-parent-api
+description: "Query Canvas LMS (Instructure) from a shell with curl and a bearer access token instead of running the canvas-parent-mcp server — courses, grades, assignments, submissions, calendar, planner, announcements, conversations, discussions, and files for yourself or a linked observee. Use when you want Canvas data without the MCP, in a script, or on a machine where the MCP isn't installed."
+---
+
+# Canvas LMS via curl (no MCP)
+
+Canvas's REST API (`/api/v1/...`) is a normal per-institution API reachable
+directly with `curl` — no browser bridge, no bot wall. Every request needs an
+`Authorization: Bearer <token>` header; there is no anonymous access. The
+host is **per-institution** (`https://<district>.instructure.com`, or a
+self-hosted domain) — always read it from `$CANVAS_BASE_URL`, never hardcode
+one tenant.
+
+This is the same data the `canvas_*` MCP tools return, reached with plain
+`curl` instead of a running server.
+
+## One-time setup — get a bearer token
+
+Pick whichever your institution allows (mirrors `canvas-parent-mcp`'s
+`CANVAS_TOKEN` / OAuth modes — the session-cookie and fetchproxy modes need
+the MCP or a browser and are out of scope here):
+
+**A. Personal access token (simplest, if allowed)**
+
+Canvas web UI → Account → Settings → **+ New Access Token**. Most
+institutions disable this for non-admins, so try B if it's not offered.
+
+```sh
+export CANVAS_BASE_URL=https://<district>.instructure.com   # per-institution, no trailing slash
+export CANVAS_TOKEN=<token from the UI>
+```
+
+**B. OAuth via the mobile QR-login flow**
+
+In the Canvas mobile app: Account → **QR for Login** (or "Pair with
+Observer/QR Login"), scan it with any camera to get the URL it encodes
+(`https://sso.canvaslms.com/canvas/login?domain=...&code=...`). Exchange it
+once for OAuth credentials with the helper this same repo ships (no MCP
+server needs to be *running* — it's a one-off CLI).
+
+It prints four `NAME=value` lines to stdout
+(`CANVAS_BASE_URL`/`CANVAS_CLIENT_ID`/`CANVAS_CLIENT_SECRET`/`CANVAS_REFRESH_TOKEN`)
+— **export them into the shell**, since the next `curl` reads them as env
+vars and this step can't be skipped:
+
+```sh
+eval "$(npx canvas-parent-mcp-qr-login "<qr-url>" | sed 's/^/export /')"
+```
+
+Then mint (and later re-mint) a short-lived access token from the refresh
+token with `curl` directly — no need to re-scan the QR each time:
+
+```sh
+curl -s -X POST "$CANVAS_BASE_URL/login/oauth2/token" \
+  -d grant_type=refresh_token \
+  -d client_id="$CANVAS_CLIENT_ID" \
+  -d client_secret="$CANVAS_CLIENT_SECRET" \
+  -d refresh_token="$CANVAS_REFRESH_TOKEN" \
+  | jq -r '.access_token'
+```
+
+Export the result as `CANVAS_TOKEN` (access tokens expire in ~1h — re-run
+this when calls start 401ing).
+
+## Core call pattern
+
+```sh
+curl -s \
+  -H "Authorization: Bearer $CANVAS_TOKEN" \
+  -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/self/profile" \
+  | sed 's/^while(1);//' | jq .
+```
+
+Two quirks every call needs:
+
+- **`Accept: application/json+canvas-string-ids, application/json`** — without
+  it, large numeric IDs can silently round-trip wrong (JS `2^53` overflow).
+- **XSSI prefix** — some endpoints prepend `while(1);` to the JSON body.
+  Strip it before piping to `jq` (`sed 's/^while(1);//'`), or it'll fail to
+  parse.
+
+## Resolve-first rule: get IDs before detail
+
+Most detail/list-by-course endpoints need a `courseId` and (for parents) an
+observee's user ID — get those first, then substitute them into the paths in
+`references/canvas-endpoints.md`:
+
+```sh
+# Your own profile (sanity-check the token works)
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/self/profile" | sed 's/^while(1);//' | jq '{id, name, primary_email}'
+
+# Students linked to your observer account (empty array for a plain student token)
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/self/observees?include[]=avatar_url" | sed 's/^while(1);//' | jq '.[] | {id, name}'
+
+# Your (or an observee's) active courses, with grades
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/self/courses?enrollment_state=active&state[]=available&include[]=total_scores&include[]=current_grading_period_scores&include[]=term" \
+  | sed 's/^while(1);//' | jq '.[] | {id, name}'
+```
+
+For an observee, swap `users/self` for `users/<observeeId>` in any path that
+starts that way (per-user endpoints); course-scoped endpoints
+(`/api/v1/courses/<courseId>/...`) don't need the observee ID at all — Canvas
+scopes them to whichever user the token belongs to.
+
+## Pagination
+
+Canvas paginates with an RFC 5988 `Link` header, not a body field. Fetch
+headers separately to follow `rel="next"`:
+
+```sh
+url="$CANVAS_BASE_URL/api/v1/courses/123/students/submissions?student_ids[]=self&per_page=100"
+while [ -n "$url" ]; do
+  headers=$(curl -sD - -o page.json -H "Authorization: Bearer $CANVAS_TOKEN" \
+    -H "Accept: application/json+canvas-string-ids, application/json" "$url")
+  sed 's/^while(1);//' page.json | jq -c '.[]' >> all.jsonl
+  url=$(echo "$headers" | grep -i '^link:' | grep -oE '<[^>]+>; rel="next"' | grep -oE 'https?://[^>]+')
+done
+```
+
+Bumping `per_page` (Canvas allows up to 100) is usually enough for one-off
+queries; only bother with the loop for genuinely large collections.
+
+## Auth expiry
+
+- **Personal token**: a 401 means it's expired or revoked — mint a fresh one
+  in the Canvas UI (tokens don't self-refresh).
+- **OAuth access token**: expires in ~1h — re-run the `refresh_token`
+  exchange above; the refresh token itself is long-lived.
+
+All 18 endpoints (courses, assignments, submissions, grades, calendar,
+planner, announcements, conversations, discussions, files) are in
+`references/canvas-endpoints.md` with the real query params and a `jq`
+projection for each.

package/skills/canvas-parent-api/references/canvas-endpoints.md

@@ -0,0 +1,223 @@
+# Canvas API endpoints for curl
+
+All 18 `canvas_*` MCP tools, transcribed from `src/tools/*.ts` in
+`canvas-parent-mcp`. Every call needs:
+
+```sh
+-H "Authorization: Bearer $CANVAS_TOKEN"
+-H "Accept: application/json+canvas-string-ids, application/json"
+```
+
+against `$CANVAS_BASE_URL` (per-institution, e.g.
+`https://<district>.instructure.com`). Pipe every response through
+`sed 's/^while(1);//'` before `jq` (Canvas's XSSI guard). List endpoints are
+marked **paginated** — see the `Link`-header loop in `SKILL.md` for anything
+you expect to run long; for a quick look just bump `per_page`.
+
+`{userSegment}` below means `users/self`, or `users/<observeeId>` to read a
+linked observee's data instead (get IDs from §2).
+
+---
+
+## 1. Profile
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/self/profile" | sed 's/^while(1);//' \
+  | jq '{id, name, primary_email, login_id, locale, time_zone}'
+```
+
+## 2. Observees — students linked to your observer account
+
+Empty array for a plain student token.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/self/observees?include[]=avatar_url" | sed 's/^while(1);//' \
+  | jq '.[] | {id, name}'
+```
+
+*(paginated)*
+
+## 3. Courses — active, with grades
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/{userSegment}/courses?enrollment_state=active&state[]=available&include[]=total_scores&include[]=current_grading_period_scores&include[]=term" \
+  | sed 's/^while(1);//' | jq '.[] | {id, name, total_scores}'
+```
+
+*(paginated)*
+
+## 4. Single course — syllabus, teachers, term
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/courses/{courseId}?include[]=syllabus_body&include[]=teachers&include[]=term" \
+  | sed 's/^while(1);//' | jq '{id, name, syllabus_body, teachers, term}'
+```
+
+## 5. Assignments — a course's assignment list, with your submission inline
+
+`bucket` (optional): `past` `overdue` `undated` `ungraded` `unsubmitted`
+`upcoming` `future`.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/courses/{courseId}/assignments?include[]=submission&order_by=due_at&bucket=upcoming" \
+  | sed 's/^while(1);//' | jq '.[] | {id, name, due_at, submission: .submission.workflow_state}'
+```
+
+*(paginated)*
+
+## 6. Missing submissions — past-due, unsubmitted
+
+For an observee, `course_ids[]` (repeat the param per ID) is required.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/{userSegment}/missing_submissions?include[]=planner_overrides&include[]=course&filter[]=submittable&course_ids[]=123&course_ids[]=456" \
+  | sed 's/^while(1);//' | jq '.[] | {id, name, due_at, course_id}'
+```
+
+*(paginated)*
+
+## 7. Single submission — rubric + grader comments
+
+`userId` defaults to `self`; pass a numeric Canvas user ID for an observee.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/courses/{courseId}/assignments/{assignmentId}/submissions/self?include[]=submission_comments&include[]=rubric_assessment&include[]=assignment" \
+  | sed 's/^while(1);//' | jq '{score, grade, submitted_at, submission_comments}'
+```
+
+## 8. Recent graded submissions in a course
+
+`student_ids[]` defaults to `self`; `graded_since` defaults to 14 days ago
+(ISO 8601, compute it yourself for curl — Canvas doesn't).
+
+```sh
+since=$(date -u -v-14d +%Y-%m-%dT%H:%M:%SZ)   # macOS date; use `date -u -d '14 days ago' ...` on GNU
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/courses/{courseId}/students/submissions?student_ids[]=self&workflow_state[]=graded&graded_since=$since&include[]=assignment&include[]=submission_comments" \
+  | sed 's/^while(1);//' | jq '.[] | {assignment: .assignment.name, score, grade}'
+```
+
+*(paginated)*
+
+## 9. Enrollments — per-course grades
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/{userSegment}/enrollments?state[]=active&type[]=StudentEnrollment&include[]=current_points&include[]=grades" \
+  | sed 's/^while(1);//' | jq '.[] | {course_id, grades}'
+```
+
+*(paginated)*
+
+## 10. Calendar events / assignments across contexts
+
+`context_codes[]` looks like `course_123`, `user_456` (repeat the param per
+code). `type` is `event` or `assignment`.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/calendar_events?type=assignment&start_date=2026-07-01&end_date=2026-07-31&context_codes[]=course_123" \
+  | sed 's/^while(1);//' | jq '.[] | {title, start_at}'
+```
+
+*(paginated)*
+
+## 11. Upcoming events — Canvas's curated next-7-days view
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/self/upcoming_events" | sed 's/^while(1);//' | jq .
+```
+
+## 12. Planner items — assignments + announcements + notes + events
+
+Omit `{observeeId}` (use `/api/v1/planner/items`) for yourself.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/users/{observeeId}/planner/items?start_date=2026-07-01&end_date=2026-07-31" \
+  | sed 's/^while(1);//' | jq '.[] | {plannable_type, plannable_date: .plannable_date}'
+```
+
+*(paginated; self variant: `$CANVAS_BASE_URL/api/v1/planner/items?...`)*
+
+## 13. Announcements — across one or more courses
+
+`context_codes[]` is **required** (e.g. `course_123`); defaults to
+`active_only=true`.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/announcements?context_codes[]=course_123&context_codes[]=course_456&active_only=true" \
+  | sed 's/^while(1);//' | jq '.[] | {title, posted_at}'
+```
+
+*(paginated)*
+
+## 14. Conversations (inbox) — list
+
+`scope` (optional): `unread` `starred` `archived` `sent`. `filter[]` is an
+array of context codes.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/conversations?scope=unread&include[]=participant_avatars" \
+  | sed 's/^while(1);//' | jq '.[] | {id, subject, last_message}'
+```
+
+*(paginated)*
+
+## 15. Conversation detail — full thread
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/conversations/{id}?include[]=participant_avatars" \
+  | sed 's/^while(1);//' | jq '.messages[] | {author_id, body, created_at}'
+```
+
+## 16. Discussion topics — a course's list
+
+`only_announcements` defaults `false`; `order_by` (optional): `position`
+`recent_activity` `title`.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/courses/{courseId}/discussion_topics?only_announcements=false&order_by=recent_activity" \
+  | sed 's/^while(1);//' | jq '.[] | {id, title, posted_at}'
+```
+
+*(paginated)*
+
+## 17. Course files — metadata list
+
+`search_term` and `content_types[]` are optional filters.
+
+```sh
+curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
+  "$CANVAS_BASE_URL/api/v1/courses/{courseId}/files?search_term=syllabus" \
+  | sed 's/^while(1);//' | jq '.[] | {id, display_name, url, "content-type"}'
+```
+
+*(paginated)*
+
+## 18. Download a file
+
+Use the absolute `url` field from §17 directly — it's already a
+fully-qualified, Bearer-authable Canvas URL (no `/api/v1` prefix needed):
+
+```sh
+curl -sL -H "Authorization: Bearer $CANVAS_TOKEN" "$FILE_URL" -o /path/to/destination.pdf
+```
+
+`-L` follows Canvas's redirect to the actual file storage backend. The MCP's
+`canvas_download_file` tool additionally refuses to overwrite an existing
+destination unless told to and validates the parent directory exists —
+replicate that yourself in a script if it matters (`[ -f dest ] && exit 1`,
+`[ -d "$(dirname dest)" ] || exit 1`).

package/skills/canvas/SKILL.md

@@ -1,202 +0,0 @@
----
-name: canvas
-description: This skill should be used when the user asks about Canvas LMS (Instructure) data for themselves or any student they observe. Triggers on phrases like "check Canvas", "what's my grade", "Canvas inbox", "what's due", "missing assignments", "Canvas LMS", "Instructure", "course announcements", "syllabus", or any request about courses, assignments, grades, conversations, announcements, planner items, or files.
----
-
-# canvas-parent-mcp
-
-MCP server for Canvas LMS (Instructure) — 18 tools covering profile, observees, courses, assignments, submissions, grades, calendar, planner, announcements, conversations, discussions, and files. Read-only except for one file-download tool.
-
-- **Source:** [github.com/chrischall/canvas-parent-mcp](https://github.com/chrischall/canvas-parent-mcp)
-- **npm:** [npmjs.com/package/canvas-parent-mcp](https://www.npmjs.com/package/canvas-parent-mcp)
-
-## Setup
-
-Pick one auth mode. **Username/password is recommended** — most schools have disabled personal-access-token creation.
-
-### Option A — Claude Code (direct MCP, no mcporter)
-
-Add to `.mcp.json` in your project or `~/.claude/mcp.json`:
-
-```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",
-        "CANVAS_NAME": "CMS"
-      }
-    }
-  }
-}
-```
-
-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
-"env": {
-  "CANVAS_BASE_URL": "https://cms.instructure.com",
-  "CANVAS_TOKEN": "your-personal-access-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
-"env": {
-  "CANVAS_BASE_URL": "https://cms.instructure.com",
-  "CANVAS_CLIENT_ID": "...",
-  "CANVAS_CLIENT_SECRET": "...",
-  "CANVAS_REFRESH_TOKEN": "..."
-}
-```
-
-### Option B — mcporter
-
-#### 1. Install
-
-```bash
-npm install -g canvas-parent-mcp
-```
-
-Or from source:
-```bash
-git clone https://github.com/chrischall/canvas-parent-mcp
-cd canvas-parent-mcp
-npm install && npm run build
-```
-
-#### 2. Configure credentials
-
-```bash
-cp .env.example .env
-# Edit .env: set CANVAS_BASE_URL plus one of CANVAS_TOKEN, CANVAS_USERNAME+CANVAS_PASSWORD, or the OAuth triple.
-```
-
-#### 3. Register with mcporter
-
-```bash
-mcporter config add canvas \
-  --command "canvas-parent-mcp" \
-  --env "CANVAS_BASE_URL=https://cms.instructure.com" \
-  --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
-mcporter list --config ~/.mcporter/mcporter.json
-mcporter call canvas.canvas_get_profile --config ~/.mcporter/mcporter.json
-```
-
-## Calling tools (mcporter)
-
-```bash
-mcporter call canvas.<tool_name> [key=value ...] --config ~/.mcporter/mcporter.json
-```
-
-Always pass `--config ~/.mcporter/mcporter.json` unless a local `config/mcporter.json` exists.
-
-Most tools accept an optional `observeeId` (defaults to `self`) — set it to a student's user ID when an observer is checking on a linked student. List the candidates with `canvas_list_observees`.
-
-## Tools
-
-### Profile & observees
-| Tool | Notes |
-|------|-------|
-| `canvas_get_profile` | Your Canvas profile (id, name, email, login, locale, timezone). Call this first to confirm credentials work. |
-| `canvas_list_observees` | Students linked to your observer account. Returns `[]` for plain student tokens. |
-
-### Courses
-| Tool | Notes |
-|------|-------|
-| `canvas_list_courses(observeeId?)` | Active courses with course-level grades. Includes total scores + current grading period scores. |
-| `canvas_get_course(courseId)` | Course detail: syllabus, teachers, term. |
-
-### Assignments & submissions
-| Tool | Notes |
-|------|-------|
-| `canvas_list_assignments(courseId, bucket?)` | Assignments for a course. `bucket` can be `upcoming`, `overdue`, `past`, or `undated`. Includes the user's submission inline. |
-| `canvas_list_missing_submissions(observeeId?, courseIds?)` | Past-due unsubmitted assignments. For an observee, `courseIds` is required. |
-| `canvas_get_submission(courseId, assignmentId, userId?)` | A single submission with comments + rubric assessment. `userId` defaults to `self`. |
-| `canvas_list_recent_submissions(courseId, since?)` | Recently graded submissions in a course. Defaults to a 14-day window. |
-
-### Grades
-| Tool | Notes |
-|------|-------|
-| `canvas_list_enrollments(observeeId?)` | Active student enrollments with `grades` (current_score, final_score, current_grade, final_grade, current grading period). |
-
-### Calendar & planner
-| Tool | Notes |
-|------|-------|
-| `canvas_list_calendar_events(contextCodes?, type?, startDate?, endDate?)` | Calendar events / assignments. `contextCodes` is an array like `["course_123", "user_456"]`. |
-| `canvas_list_upcoming_events` | Canvas's curated next-7-days view. |
-| `canvas_list_planner_items(observeeId?, startDate?, endDate?, contextCodes?)` | Unified planner: assignments + announcements + planner notes + calendar events. |
-
-### Communication
-| Tool | Notes |
-|------|-------|
-| `canvas_list_announcements(contextCodes, startDate?, endDate?)` | Announcements across one or more courses. `contextCodes` is required (e.g. `["course_123"]`). Defaults to the last 14 days. |
-| `canvas_list_conversations(scope?)` | Inbox conversation list. `scope` ∈ `unread` / `starred` / `archived`. |
-| `canvas_get_conversation(id)` | Full conversation thread with messages. |
-| `canvas_list_discussion_topics(courseId)` | Discussion topic list for a course (read-only). |
-
-### Files
-| Tool | Notes |
-|------|-------|
-| `canvas_list_course_files(courseId, searchTerm?)` | File metadata: id, display_name, size, content-type, **`url`**. |
-| `canvas_download_file(url, destinationPath, overwrite?)` | Writes the file to `destinationPath` on disk. **`destinationPath` is required** — confirm the path with the user before calling. |
-
-## Workflows
-
-**Discovery (first time):**
-1. `canvas_get_profile` → confirm credentials
-2. `canvas_list_observees` → if empty, you're a student; otherwise capture observee IDs
-3. `canvas_list_courses` → capture course IDs
-
-**Is everything OK at school?**
-1. `canvas_list_courses` (capture IDs)
-2. `canvas_list_recent_submissions(courseId)` for each — last 14 days of grading
-3. `canvas_list_missing_submissions` — past-due work
-4. `canvas_list_announcements(contextCodes=["course_<id>"])` — recent announcements
-
-**What got graded this week?**
-- `canvas_list_recent_submissions(courseId, since="YYYY-MM-DDTHH:MM:SSZ")`
-
-**What's due soon?**
-- `canvas_list_planner_items(startDate=..., endDate=...)` — unified planner
-- Or `canvas_list_assignments(courseId, bucket="upcoming")` per course
-
-**Today's calendar:**
-- `canvas_list_upcoming_events`
-
-**Read a syllabus:**
-- `canvas_get_course(courseId)` — `syllabus_body` is included
-
-**Inbox:**
-1. `canvas_list_conversations` — find a thread
-2. `canvas_get_conversation(id)` — read it
-
-**Download a file:**
-1. `canvas_list_course_files(courseId)` → find the file's `url`
-2. Confirm destination path with the user
-3. `canvas_download_file(url, destinationPath="/Users/.../file.pdf")`
-
-## Caution
-
-- `canvas_download_file` writes to disk at `destinationPath` — confirm the path with the user; pass `overwrite:true` to replace.
-- 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`).