canvas-parent-mcp 1.1.8 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -46,7 +46,7 @@ catch (e) {
46
46
  // host's install-time `tools/list` succeeds.
47
47
  await runMcp({
48
48
  name: 'canvas',
49
- version: '1.1.8', // x-release-please-version
49
+ version: '1.2.2', // x-release-please-version
50
50
  tools: [
51
51
  (server) => {
52
52
  if (resolved) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "canvas-parent-mcp",
3
- "version": "1.1.8",
3
+ "version": "1.2.2",
4
4
  "mcpName": "io.github.chrischall/canvas-parent-mcp",
5
5
  "description": "Canvas LMS (Instructure) MCP server — student/observer read access with optional file download",
6
6
  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -44,9 +44,9 @@
44
44
  "test:watch": "vitest"
45
45
  },
46
46
  "dependencies": {
47
- "@chrischall/mcp-utils": "^0.12.0",
48
- "@fetchproxy/bootstrap": "^1.0.0",
49
- "@fetchproxy/server": "^1.0.0",
47
+ "@chrischall/mcp-utils": "^0.14.0",
48
+ "@fetchproxy/bootstrap": "^1.7.0",
49
+ "@fetchproxy/server": "^1.7.0",
50
50
  "@modelcontextprotocol/sdk": "^1.29.0",
51
51
  "dotenv": "^17.4.2",
52
52
  "zod": "^4.4.3"
@@ -55,7 +55,7 @@
55
55
  "@types/node": "^26.0.0",
56
56
  "@vitest/coverage-v8": "^4.1.7",
57
57
  "esbuild": "^0.28.0",
58
- "typescript": "^6.0.3",
58
+ "typescript": "^7.0.2",
59
59
  "vitest": "^4.1.7"
60
60
  }
61
61
  }
package/server.json CHANGED
@@ -6,12 +6,12 @@
6
6
  "url": "https://github.com/chrischall/canvas-parent-mcp",
7
7
  "source": "github"
8
8
  },
9
- "version": "1.1.8",
9
+ "version": "1.2.2",
10
10
  "packages": [
11
11
  {
12
12
  "registryType": "npm",
13
13
  "identifier": "canvas-parent-mcp",
14
- "version": "1.1.8",
14
+ "version": "1.2.2",
15
15
  "transport": {
16
16
  "type": "stdio"
17
17
  },
@@ -0,0 +1,92 @@
1
+ ---
2
+ name: canvas-parent-mcp
3
+ 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.
4
+ ---
5
+
6
+ # canvas-parent-mcp
7
+
8
+ 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`.
9
+
10
+ - **npm:** [npmjs.com/package/canvas-parent-mcp](https://www.npmjs.com/package/canvas-parent-mcp)
11
+ - **Source:** [github.com/chrischall/canvas-parent-mcp](https://github.com/chrischall/canvas-parent-mcp)
12
+
13
+ ## Setup
14
+
15
+ ### Option A — npx (recommended)
16
+
17
+ Add to `.mcp.json` in your project or `~/.claude/mcp.json`:
18
+
19
+ ```json
20
+ {
21
+ "mcpServers": {
22
+ "canvas": {
23
+ "command": "npx",
24
+ "args": ["-y", "canvas-parent-mcp"],
25
+ "env": {
26
+ "CANVAS_BASE_URL": "https://cms.instructure.com"
27
+ }
28
+ }
29
+ }
30
+ }
31
+ ```
32
+
33
+ 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.
34
+
35
+ ### Option B — from source
36
+
37
+ ```bash
38
+ git clone https://github.com/chrischall/canvas-parent-mcp
39
+ cd canvas-parent-mcp
40
+ npm install && npm run build
41
+ ```
42
+
43
+ ## Authentication
44
+
45
+ **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).
46
+
47
+ ### Alternatives (env-var)
48
+
49
+ - **Personal access token** — set `CANVAS_TOKEN`. Most institutions have disabled this for non-admins.
50
+ - **OAuth** — set `CANVAS_CLIENT_ID`, `CANVAS_CLIENT_SECRET`, `CANVAS_REFRESH_TOKEN`. Bootstrap via `canvas-parent-mcp-qr-login`.
51
+ - **Username/password (session-scrape)** — set `CANVAS_USERNAME` + `CANVAS_PASSWORD`. Direct Canvas accounts only (no SSO/2FA). Brittle.
52
+
53
+ Precedence when multiple are set: `CANVAS_TOKEN` > username/password > OAuth > fetchproxy. Set `CANVAS_DISABLE_FETCHPROXY=1` to opt out of the fallback.
54
+
55
+ ## Tools (prefix `canvas_`)
56
+
57
+ ### Profile & observees
58
+ - `canvas_get_profile` — your Canvas profile
59
+ - `canvas_list_observees` — students linked to your observer account
60
+
61
+ ### Courses
62
+ - `canvas_list_courses` — your active courses with grades
63
+ - `canvas_get_course(courseId)` — course detail with syllabus + teachers
64
+
65
+ ### Assignments & submissions
66
+ - `canvas_list_assignments(courseId)` — assignments in a course
67
+ - `canvas_list_missing_submissions` — past-due unsubmitted work
68
+ - `canvas_get_submission(courseId, assignmentId)` — your submission with comments + rubric
69
+ - `canvas_list_recent_submissions(courseId)` — recently graded submissions (default 14d)
70
+
71
+ ### Grades
72
+ - `canvas_list_enrollments` — per-course grades
73
+
74
+ ### Calendar & planner
75
+ - `canvas_list_calendar_events` — calendar events / assignments
76
+ - `canvas_list_upcoming_events` — server-curated next 7 days
77
+ - `canvas_list_planner_items` — unified to-do feed
78
+
79
+ ### Communication
80
+ - `canvas_list_announcements(contextCodes)` — course announcements
81
+ - `canvas_list_conversations` — inbox
82
+ - `canvas_get_conversation(id)` — full conversation thread
83
+ - `canvas_list_discussion_topics(courseId)` — course discussion topics
84
+
85
+ ### Files
86
+ - `canvas_list_course_files(courseId)` — file metadata
87
+ - `canvas_download_file(url, destinationPath)` — download a file to disk
88
+
89
+ ## Notes
90
+
91
+ - Set `CANVAS_NAME` if you want a friendly label other than the host portion of the base URL.
92
+ - 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.
@@ -0,0 +1,138 @@
1
+ ---
2
+ name: canvas-parent-api
3
+ 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."
4
+ ---
5
+
6
+ # Canvas LMS via curl (no MCP)
7
+
8
+ Canvas's REST API (`/api/v1/...`) is a normal per-institution API reachable
9
+ directly with `curl` — no browser bridge, no bot wall. Every request needs an
10
+ `Authorization: Bearer <token>` header; there is no anonymous access. The
11
+ host is **per-institution** (`https://<district>.instructure.com`, or a
12
+ self-hosted domain) — always read it from `$CANVAS_BASE_URL`, never hardcode
13
+ one tenant.
14
+
15
+ This is the same data the `canvas_*` MCP tools return, reached with plain
16
+ `curl` instead of a running server.
17
+
18
+ ## One-time setup — get a bearer token
19
+
20
+ Pick whichever your institution allows (mirrors `canvas-parent-mcp`'s
21
+ `CANVAS_TOKEN` / OAuth modes — the session-cookie and fetchproxy modes need
22
+ the MCP or a browser and are out of scope here):
23
+
24
+ **A. Personal access token (simplest, if allowed)**
25
+
26
+ Canvas web UI → Account → Settings → **+ New Access Token**. Most
27
+ institutions disable this for non-admins, so try B if it's not offered.
28
+
29
+ ```sh
30
+ export CANVAS_BASE_URL=https://<district>.instructure.com # per-institution, no trailing slash
31
+ export CANVAS_TOKEN=<token from the UI>
32
+ ```
33
+
34
+ **B. OAuth via the mobile QR-login flow**
35
+
36
+ In the Canvas mobile app: Account → **QR for Login** (or "Pair with
37
+ Observer/QR Login"), scan it with any camera to get the URL it encodes
38
+ (`https://sso.canvaslms.com/canvas/login?domain=...&code=...`). Exchange it
39
+ once for OAuth credentials with the helper this same repo ships (no MCP
40
+ server needs to be *running* — it's a one-off CLI).
41
+
42
+ It prints four `NAME=value` lines to stdout
43
+ (`CANVAS_BASE_URL`/`CANVAS_CLIENT_ID`/`CANVAS_CLIENT_SECRET`/`CANVAS_REFRESH_TOKEN`)
44
+ — **export them into the shell**, since the next `curl` reads them as env
45
+ vars and this step can't be skipped:
46
+
47
+ ```sh
48
+ eval "$(npx canvas-parent-mcp-qr-login "<qr-url>" | sed 's/^/export /')"
49
+ ```
50
+
51
+ Then mint (and later re-mint) a short-lived access token from the refresh
52
+ token with `curl` directly — no need to re-scan the QR each time:
53
+
54
+ ```sh
55
+ curl -s -X POST "$CANVAS_BASE_URL/login/oauth2/token" \
56
+ -d grant_type=refresh_token \
57
+ -d client_id="$CANVAS_CLIENT_ID" \
58
+ -d client_secret="$CANVAS_CLIENT_SECRET" \
59
+ -d refresh_token="$CANVAS_REFRESH_TOKEN" \
60
+ | jq -r '.access_token'
61
+ ```
62
+
63
+ Export the result as `CANVAS_TOKEN` (access tokens expire in ~1h — re-run
64
+ this when calls start 401ing).
65
+
66
+ ## Core call pattern
67
+
68
+ ```sh
69
+ curl -s \
70
+ -H "Authorization: Bearer $CANVAS_TOKEN" \
71
+ -H "Accept: application/json+canvas-string-ids, application/json" \
72
+ "$CANVAS_BASE_URL/api/v1/users/self/profile" \
73
+ | sed 's/^while(1);//' | jq .
74
+ ```
75
+
76
+ Two quirks every call needs:
77
+
78
+ - **`Accept: application/json+canvas-string-ids, application/json`** — without
79
+ it, large numeric IDs can silently round-trip wrong (JS `2^53` overflow).
80
+ - **XSSI prefix** — some endpoints prepend `while(1);` to the JSON body.
81
+ Strip it before piping to `jq` (`sed 's/^while(1);//'`), or it'll fail to
82
+ parse.
83
+
84
+ ## Resolve-first rule: get IDs before detail
85
+
86
+ Most detail/list-by-course endpoints need a `courseId` and (for parents) an
87
+ observee's user ID — get those first, then substitute them into the paths in
88
+ `references/canvas-endpoints.md`:
89
+
90
+ ```sh
91
+ # Your own profile (sanity-check the token works)
92
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
93
+ "$CANVAS_BASE_URL/api/v1/users/self/profile" | sed 's/^while(1);//' | jq '{id, name, primary_email}'
94
+
95
+ # Students linked to your observer account (empty array for a plain student token)
96
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
97
+ "$CANVAS_BASE_URL/api/v1/users/self/observees?include[]=avatar_url" | sed 's/^while(1);//' | jq '.[] | {id, name}'
98
+
99
+ # Your (or an observee's) active courses, with grades
100
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
101
+ "$CANVAS_BASE_URL/api/v1/users/self/courses?enrollment_state=active&state[]=available&include[]=total_scores&include[]=current_grading_period_scores&include[]=term" \
102
+ | sed 's/^while(1);//' | jq '.[] | {id, name}'
103
+ ```
104
+
105
+ For an observee, swap `users/self` for `users/<observeeId>` in any path that
106
+ starts that way (per-user endpoints); course-scoped endpoints
107
+ (`/api/v1/courses/<courseId>/...`) don't need the observee ID at all — Canvas
108
+ scopes them to whichever user the token belongs to.
109
+
110
+ ## Pagination
111
+
112
+ Canvas paginates with an RFC 5988 `Link` header, not a body field. Fetch
113
+ headers separately to follow `rel="next"`:
114
+
115
+ ```sh
116
+ url="$CANVAS_BASE_URL/api/v1/courses/123/students/submissions?student_ids[]=self&per_page=100"
117
+ while [ -n "$url" ]; do
118
+ headers=$(curl -sD - -o page.json -H "Authorization: Bearer $CANVAS_TOKEN" \
119
+ -H "Accept: application/json+canvas-string-ids, application/json" "$url")
120
+ sed 's/^while(1);//' page.json | jq -c '.[]' >> all.jsonl
121
+ url=$(echo "$headers" | grep -i '^link:' | grep -oE '<[^>]+>; rel="next"' | grep -oE 'https?://[^>]+')
122
+ done
123
+ ```
124
+
125
+ Bumping `per_page` (Canvas allows up to 100) is usually enough for one-off
126
+ queries; only bother with the loop for genuinely large collections.
127
+
128
+ ## Auth expiry
129
+
130
+ - **Personal token**: a 401 means it's expired or revoked — mint a fresh one
131
+ in the Canvas UI (tokens don't self-refresh).
132
+ - **OAuth access token**: expires in ~1h — re-run the `refresh_token`
133
+ exchange above; the refresh token itself is long-lived.
134
+
135
+ All 18 endpoints (courses, assignments, submissions, grades, calendar,
136
+ planner, announcements, conversations, discussions, files) are in
137
+ `references/canvas-endpoints.md` with the real query params and a `jq`
138
+ projection for each.
@@ -0,0 +1,223 @@
1
+ # Canvas API endpoints for curl
2
+
3
+ All 18 `canvas_*` MCP tools, transcribed from `src/tools/*.ts` in
4
+ `canvas-parent-mcp`. Every call needs:
5
+
6
+ ```sh
7
+ -H "Authorization: Bearer $CANVAS_TOKEN"
8
+ -H "Accept: application/json+canvas-string-ids, application/json"
9
+ ```
10
+
11
+ against `$CANVAS_BASE_URL` (per-institution, e.g.
12
+ `https://<district>.instructure.com`). Pipe every response through
13
+ `sed 's/^while(1);//'` before `jq` (Canvas's XSSI guard). List endpoints are
14
+ marked **paginated** — see the `Link`-header loop in `SKILL.md` for anything
15
+ you expect to run long; for a quick look just bump `per_page`.
16
+
17
+ `{userSegment}` below means `users/self`, or `users/<observeeId>` to read a
18
+ linked observee's data instead (get IDs from §2).
19
+
20
+ ---
21
+
22
+ ## 1. Profile
23
+
24
+ ```sh
25
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
26
+ "$CANVAS_BASE_URL/api/v1/users/self/profile" | sed 's/^while(1);//' \
27
+ | jq '{id, name, primary_email, login_id, locale, time_zone}'
28
+ ```
29
+
30
+ ## 2. Observees — students linked to your observer account
31
+
32
+ Empty array for a plain student token.
33
+
34
+ ```sh
35
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
36
+ "$CANVAS_BASE_URL/api/v1/users/self/observees?include[]=avatar_url" | sed 's/^while(1);//' \
37
+ | jq '.[] | {id, name}'
38
+ ```
39
+
40
+ *(paginated)*
41
+
42
+ ## 3. Courses — active, with grades
43
+
44
+ ```sh
45
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
46
+ "$CANVAS_BASE_URL/api/v1/{userSegment}/courses?enrollment_state=active&state[]=available&include[]=total_scores&include[]=current_grading_period_scores&include[]=term" \
47
+ | sed 's/^while(1);//' | jq '.[] | {id, name, total_scores}'
48
+ ```
49
+
50
+ *(paginated)*
51
+
52
+ ## 4. Single course — syllabus, teachers, term
53
+
54
+ ```sh
55
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
56
+ "$CANVAS_BASE_URL/api/v1/courses/{courseId}?include[]=syllabus_body&include[]=teachers&include[]=term" \
57
+ | sed 's/^while(1);//' | jq '{id, name, syllabus_body, teachers, term}'
58
+ ```
59
+
60
+ ## 5. Assignments — a course's assignment list, with your submission inline
61
+
62
+ `bucket` (optional): `past` `overdue` `undated` `ungraded` `unsubmitted`
63
+ `upcoming` `future`.
64
+
65
+ ```sh
66
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
67
+ "$CANVAS_BASE_URL/api/v1/courses/{courseId}/assignments?include[]=submission&order_by=due_at&bucket=upcoming" \
68
+ | sed 's/^while(1);//' | jq '.[] | {id, name, due_at, submission: .submission.workflow_state}'
69
+ ```
70
+
71
+ *(paginated)*
72
+
73
+ ## 6. Missing submissions — past-due, unsubmitted
74
+
75
+ For an observee, `course_ids[]` (repeat the param per ID) is required.
76
+
77
+ ```sh
78
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
79
+ "$CANVAS_BASE_URL/api/v1/{userSegment}/missing_submissions?include[]=planner_overrides&include[]=course&filter[]=submittable&course_ids[]=123&course_ids[]=456" \
80
+ | sed 's/^while(1);//' | jq '.[] | {id, name, due_at, course_id}'
81
+ ```
82
+
83
+ *(paginated)*
84
+
85
+ ## 7. Single submission — rubric + grader comments
86
+
87
+ `userId` defaults to `self`; pass a numeric Canvas user ID for an observee.
88
+
89
+ ```sh
90
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
91
+ "$CANVAS_BASE_URL/api/v1/courses/{courseId}/assignments/{assignmentId}/submissions/self?include[]=submission_comments&include[]=rubric_assessment&include[]=assignment" \
92
+ | sed 's/^while(1);//' | jq '{score, grade, submitted_at, submission_comments}'
93
+ ```
94
+
95
+ ## 8. Recent graded submissions in a course
96
+
97
+ `student_ids[]` defaults to `self`; `graded_since` defaults to 14 days ago
98
+ (ISO 8601, compute it yourself for curl — Canvas doesn't).
99
+
100
+ ```sh
101
+ since=$(date -u -v-14d +%Y-%m-%dT%H:%M:%SZ) # macOS date; use `date -u -d '14 days ago' ...` on GNU
102
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
103
+ "$CANVAS_BASE_URL/api/v1/courses/{courseId}/students/submissions?student_ids[]=self&workflow_state[]=graded&graded_since=$since&include[]=assignment&include[]=submission_comments" \
104
+ | sed 's/^while(1);//' | jq '.[] | {assignment: .assignment.name, score, grade}'
105
+ ```
106
+
107
+ *(paginated)*
108
+
109
+ ## 9. Enrollments — per-course grades
110
+
111
+ ```sh
112
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
113
+ "$CANVAS_BASE_URL/api/v1/{userSegment}/enrollments?state[]=active&type[]=StudentEnrollment&include[]=current_points&include[]=grades" \
114
+ | sed 's/^while(1);//' | jq '.[] | {course_id, grades}'
115
+ ```
116
+
117
+ *(paginated)*
118
+
119
+ ## 10. Calendar events / assignments across contexts
120
+
121
+ `context_codes[]` looks like `course_123`, `user_456` (repeat the param per
122
+ code). `type` is `event` or `assignment`.
123
+
124
+ ```sh
125
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
126
+ "$CANVAS_BASE_URL/api/v1/calendar_events?type=assignment&start_date=2026-07-01&end_date=2026-07-31&context_codes[]=course_123" \
127
+ | sed 's/^while(1);//' | jq '.[] | {title, start_at}'
128
+ ```
129
+
130
+ *(paginated)*
131
+
132
+ ## 11. Upcoming events — Canvas's curated next-7-days view
133
+
134
+ ```sh
135
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
136
+ "$CANVAS_BASE_URL/api/v1/users/self/upcoming_events" | sed 's/^while(1);//' | jq .
137
+ ```
138
+
139
+ ## 12. Planner items — assignments + announcements + notes + events
140
+
141
+ Omit `{observeeId}` (use `/api/v1/planner/items`) for yourself.
142
+
143
+ ```sh
144
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
145
+ "$CANVAS_BASE_URL/api/v1/users/{observeeId}/planner/items?start_date=2026-07-01&end_date=2026-07-31" \
146
+ | sed 's/^while(1);//' | jq '.[] | {plannable_type, plannable_date: .plannable_date}'
147
+ ```
148
+
149
+ *(paginated; self variant: `$CANVAS_BASE_URL/api/v1/planner/items?...`)*
150
+
151
+ ## 13. Announcements — across one or more courses
152
+
153
+ `context_codes[]` is **required** (e.g. `course_123`); defaults to
154
+ `active_only=true`.
155
+
156
+ ```sh
157
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
158
+ "$CANVAS_BASE_URL/api/v1/announcements?context_codes[]=course_123&context_codes[]=course_456&active_only=true" \
159
+ | sed 's/^while(1);//' | jq '.[] | {title, posted_at}'
160
+ ```
161
+
162
+ *(paginated)*
163
+
164
+ ## 14. Conversations (inbox) — list
165
+
166
+ `scope` (optional): `unread` `starred` `archived` `sent`. `filter[]` is an
167
+ array of context codes.
168
+
169
+ ```sh
170
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
171
+ "$CANVAS_BASE_URL/api/v1/conversations?scope=unread&include[]=participant_avatars" \
172
+ | sed 's/^while(1);//' | jq '.[] | {id, subject, last_message}'
173
+ ```
174
+
175
+ *(paginated)*
176
+
177
+ ## 15. Conversation detail — full thread
178
+
179
+ ```sh
180
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
181
+ "$CANVAS_BASE_URL/api/v1/conversations/{id}?include[]=participant_avatars" \
182
+ | sed 's/^while(1);//' | jq '.messages[] | {author_id, body, created_at}'
183
+ ```
184
+
185
+ ## 16. Discussion topics — a course's list
186
+
187
+ `only_announcements` defaults `false`; `order_by` (optional): `position`
188
+ `recent_activity` `title`.
189
+
190
+ ```sh
191
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
192
+ "$CANVAS_BASE_URL/api/v1/courses/{courseId}/discussion_topics?only_announcements=false&order_by=recent_activity" \
193
+ | sed 's/^while(1);//' | jq '.[] | {id, title, posted_at}'
194
+ ```
195
+
196
+ *(paginated)*
197
+
198
+ ## 17. Course files — metadata list
199
+
200
+ `search_term` and `content_types[]` are optional filters.
201
+
202
+ ```sh
203
+ curl -s -H "Authorization: Bearer $CANVAS_TOKEN" -H "Accept: application/json+canvas-string-ids, application/json" \
204
+ "$CANVAS_BASE_URL/api/v1/courses/{courseId}/files?search_term=syllabus" \
205
+ | sed 's/^while(1);//' | jq '.[] | {id, display_name, url, "content-type"}'
206
+ ```
207
+
208
+ *(paginated)*
209
+
210
+ ## 18. Download a file
211
+
212
+ Use the absolute `url` field from §17 directly — it's already a
213
+ fully-qualified, Bearer-authable Canvas URL (no `/api/v1` prefix needed):
214
+
215
+ ```sh
216
+ curl -sL -H "Authorization: Bearer $CANVAS_TOKEN" "$FILE_URL" -o /path/to/destination.pdf
217
+ ```
218
+
219
+ `-L` follows Canvas's redirect to the actual file storage backend. The MCP's
220
+ `canvas_download_file` tool additionally refuses to overwrite an existing
221
+ destination unless told to and validates the parent directory exists —
222
+ replicate that yourself in a script if it matters (`[ -f dest ] && exit 1`,
223
+ `[ -d "$(dirname dest)" ] || exit 1`).