brightspace-mcp-server 5.1.44 → 5.2.0

package/README.md

@@ -12,7 +12,7 @@ Lets your AI see your Brightspace classes, so you can just ask:
 
 > "What's due this week?" · "Am I passing all my classes?" · "Summarize today's announcements" · "Turn my lecture slides into flashcards"
 
-Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, and any other app that supports [MCP](https://modelcontextprotocol.io) (the standard way to plug tools into an AI). It only **reads** your courses — it never submits, edits, or deletes anything.
+Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, and any other app that supports [MCP](https://modelcontextprotocol.io). It only **reads** your courses. It never submits, edits, or deletes anything.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/RohanMuppa/brightspace-mcp-server/main/docs/how-it-works.svg" alt="Architecture diagram" width="100%">
@@ -20,19 +20,19 @@ Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, and a
 
 ## Get started in 3 steps
 
-1. **Install [Node.js](https://nodejs.org/)** (version 22 or newer) if you don't have it. Download, run the installer, done.
-2. **Open a terminal and run the setup:**
+1. **Install [Node.js](https://nodejs.org/)** version 22 or newer.
+2. **Run the setup in a terminal:**
    ```bash
    npx -y brightspace-mcp-server@latest setup
    ```
-   It asks for your school's Brightspace address, your username and password, and how you confirm it's you when you sign in (a phone app, or another way like a text message). Your password goes into your computer's own password store (Keychain on Mac, Credential Manager on Windows), never into a file. Before signing you in, it connects itself to Claude Desktop, Cursor, Antigravity, Codex, or Claude Code if you have them. If one of them already has a `brightspace` entry pointing somewhere else (an old local build, a fork), setup shows you that entry and asks before replacing it.
+   It asks for your school's Brightspace address, your username and password, and how you confirm it's you (a phone app, or another way such as a text message). Your password goes into your computer's password store (Keychain on Mac, Credential Manager on Windows), never into a file. Setup also connects the server to Claude Desktop, Cursor, Antigravity, Codex, or Claude Code if you have them. If one already has a `brightspace` entry pointing somewhere else, setup asks before replacing it.
 
-   **On a Mac:** when Keychain asks whether `node` may use the saved Brightspace password, choose **Always Allow**, not just Allow. That lets later sign-ins (the `auth` command and questions from your AI app) read it without asking again.
-3. **Restart your AI app and ask it something** — the first question signs you in. If your phone asks you to approve a sign-in, approve it and ask again.
+   If your school is in the table below, add its flag (such as `--purdue`) to skip typing the address.
 
-At one of these schools, add the flag and skip typing the address: `--purdue`, `--suny`, `--western`, `--tudelft`, `--cuny`, `--leiden`, `--mcgill`, `--mun`, `--ngeeann`, `--javeriana`.
+   **On a Mac:** when Keychain asks whether `node` may use the saved Brightspace password, choose **Always Allow**, not just Allow.
+3. **Restart your AI app and ask it something.** The first question signs you in. If your phone asks you to approve a sign-in, approve it and ask again.
 
-**Rather have the AI install it for you?** Paste this into Claude Code, Cursor, Windsurf, Copilot, or Codex:
+**Rather have the AI install it?** Paste this into Claude Code, Cursor, Windsurf, Copilot, or Codex:
 
 ```
 Install brightspace-mcp-server for me by following
@@ -40,9 +40,9 @@ https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
 (use --purdue at Purdue, --suny at SUNY, --tudelft at TU Delft, --cuny at CUNY, --leiden at Leiden, --mcgill at McGill, --mun at Memorial University, --ngeeann at Ngee Ann Polytechnic, or --javeriana at Javeriana Cali).
 ```
 
-The AI does everything it can by itself: it checks your computer, downloads the browser sign-in uses, and connects your AI apps. Then it gives you one command to run in a terminal. That command asks for your password and waits for you to approve the sign-in on your phone. That's the only part that needs you. Afterwards the AI checks that it can see your courses.
+The AI does everything it can by itself, then gives you one terminal command. That command asks for your password and waits for you to approve the sign-in on your phone. That's the only part that needs you. Afterwards the AI checks that it can see your courses.
 
-Using a different AI app? Add the command `npx -y brightspace-mcp-server@latest` to its MCP settings (on Windows: `cmd /c npx -y brightspace-mcp-server@latest`). Exact steps for each app: [docs/troubleshooting.md](docs/troubleshooting.md).
+Using a different AI app? Add the command `npx -y brightspace-mcp-server@latest` to its MCP settings (on Windows: `cmd /c npx -y brightspace-mcp-server@latest`). Codex and Claude Code commands, and general steps, are in [docs/troubleshooting.md](docs/troubleshooting.md).
 
 ## Does my school work?
 
@@ -60,124 +60,125 @@ If your school uses D2L Brightspace, yes. These have automatic sign-in built in:
 | Memorial University of Newfoundland | MUN Login (CAS, no two-factor when tested) | `--mun` |
 | Javeriana Cali | OneGate (password + authenticator code) | `--javeriana` |
 | Ngee Ann Polytechnic | Microsoft Entra | `--ngeeann` |
-| Any other D2L school | Paste your Brightspace address. If the login page isn't recognized, pick option 2 at setup's sign-in question so the page opens for you to finish by hand | none |
+| Any other D2L school | Paste your Brightspace address at setup. If the sign-in page isn't recognized, answer 2 to setup's sign-in question to finish it by hand | none |
 
-School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
+School-specific quirks are in [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 
 ## Things to ask
 
 | About | Try |
 |-------|-----|
-| Grades | "Am I passing all my classes?" · "Compare my grades across courses" · "What did my professor say about Mini-Assignment 1?" (own assignment feedback is read from every route Brightspace documents for students) · "Is there feedback on my midterm?" (quiz-scored grades link to the quiz, since quiz feedback, including feedback only viewable in LockDown Browser, isn't readable through the API) |
+| Grades | "Am I passing all my classes?" · "Compare my grades across courses" · "Is there feedback on my midterm?" (quiz feedback often can't be read through the API, so the answer links to the quiz instead) |
 | Due dates | "What's due in the next 48 hours?" · "Build me a study schedule for the week" |
-| Assignments and rubrics | "What does the lab 4 spec actually ask for?" · "Why did I lose points on the analysis criterion?" · "Did I turn in HW 3?" (if Brightspace won't give students their own submission list, the assignment's feedback page is checked instead; when neither shows a submission it's reported as unknown, never as missing) |
-| Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" (quizzes are collected from the quiz list, the course content, and the gradebook, so a closed quiz or one the list leaves out still shows up; each course says whether its quiz sources all answered, and if Brightspace refused one it's marked incomplete rather than passed off as everything; "complete" means every source answered, not that every quiz is guaranteed to be listed. A gradebook column linked to a quiz the list omits now shows up as a quiz with its dates and attempts instead of a bare grade-only row when the quiz can be read. Gradebook-only rows now also appear on tenants that send only the documented `GradeType` on grade columns; hidden grade columns, hidden assignments and inactive quizzes never produce one. Content quizzes beyond the first 30 per course are listed from the course content alone and the course is marked incomplete. Quiz rows may also say whether they are open, closed, or not yet open, and mark a quiz whose details Brightspace would not return; gradebook lookups for unlisted quizzes are capped at 20 per course, or 5 when the course's quiz tool can't be identified) |
+| Assignments and rubrics | "What does the lab 4 spec actually ask for?" · "Why did I lose points on the analysis criterion?" · "Did I turn in HW 3?" |
+| Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" |
 | Announcements | "Did any professor post something important today?" · "Read the file attached to today's announcement" |
-| Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "Search this course for office hours" · or just read a file inline instead of saving it |
-| Syllabus | "What's the late policy in ECE 264's syllabus?" (if the course keeps its syllabus in an external tool such as Simple Syllabus, you get the link to open instead) |
+| Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "Save this whole course to a folder on my computer" · "Search this course for office hours" · or read a file inline instead of saving it |
+| Syllabus | "What's the late policy in ECE 264's syllabus?" (if the syllabus lives in an external tool, you get the link to open instead) |
 | People | "Who are the TAs for ECE 264?" · "Who is in my project group?" |
 | Discussions | "Summarize the latest posts in the final project thread" |
-| Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura, including BoilerCast LTI links, and YouTube. When YouTube asks for a sign-in or a "not a bot" check, the answer says so, with the video link and how to get the transcript yourself: open the link in your browser, choose "Show transcript", and paste it in. The server never gets past that check for you) |
+| Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura and YouTube. If YouTube asks for a sign-in or "not a bot" check, the answer gives the link: open it, choose "Show transcript", and paste that text here) |
 | Calendar | "When is my midterm?" · "Is lab cancelled on Thursday?" |
-| For instructors and TAs | "Which students haven't submitted Lab 4 yet?" · "What feedback did I leave on this student's homework?" · "Download that student's submitted PDF" (students get a clear "instructor access required" note for these, but can read their own released feedback, below) |
-| Signing out | "Sign me out of Brightspace" (your AI app may ask you to confirm first; details under [When it asks you to sign in](#when-it-asks-you-to-sign-in)) |
+| Instructors and TAs | "Which students haven't submitted Lab 4 yet?" (students see "Instructor or TA access required" for these) |
 
-## Prompts
-
-Apps with a prompt picker (like Claude Desktop) also offer four ready-made prompts, so you can start from one click instead of typing a question:
+If Brightspace hides part of the data, such as a submission, quiz attempts, or part of the quiz list, the answer says "unknown" or "incomplete" rather than "missing" or "complete". Full tool reference: [LLMs.md](LLMs.md).
 
-| Prompt | Arguments | What it asks for |
-|--------|-----------|------------------|
-| `weekly_briefing` | — | A 7-day rollup of what's due, what's new, and what changed in your grades, across every course |
-| `grade_audit` | `courseId` (optional) | Analyzes grades for one course, or all of them, and flags missing or low-scoring items |
-| `study_planner` | `daysAhead` (optional, default 7) | Plans study time from upcoming due dates and calendar events |
-| `course_summary` | `courseId` (required) | Syllabus, content outline, assignments, and grades for one course |
+## Download a whole course
 
-## Settings you might want
+Ask your assistant to save a course, or run it yourself from a terminal:
 
-All optional, set in your AI app's MCP `env` config or your shell. The full list is in [LLMs.md](LLMs.md).
-
-| Setting | What it does |
-|---------|--------------|
-| `D2L_REMEMBER_MFA=true` | Tick Microsoft's "Don't ask again" box so later sign-ins skip the second factor (off by default; not for shared computers). `setup` asks this as option 2 of its one "how often do you want to approve sign-ins" question and saves it as `rememberMfa` in `config.json`; the env var overrides it ([details](docs/sign-in.md#fewer-2fa-prompts)) |
-| `D2L_TOTP_SECRET` | An authenticator setup key, so a Microsoft Entra "enter a code" challenge is answered on this computer instead of on your phone (off by default). Prefer `setup` (option 3), which keeps the key in your OS keychain; this variable is for CI and containers with no keychain and is weaker, because anything that can read the process environment gets your second factor ([details](docs/sign-in.md#fewer-2fa-prompts)) |
-| `D2L_HEADLESS=false` | Show the browser window during sign-in, for MFA methods that need a click |
-| `D2L_DUO_PASSCODE=1` | On Duo, type a passcode instead of waiting for a push |
-| `D2L_SESSION_COOKIE` / `D2L_ACCESS_TOKEN` | Skip the browser entirely with a pasted cookie or token ([how](docs/sign-in.md#no-browser-paste-a-session-cookie-or-token)) |
-| `D2L_INCLUDE_COURSES` / `D2L_EXCLUDE_COURSES` | Limit which courses the AI sees, by course id |
-| `D2L_ACTIVE_ONLY=false` | Include courses whose enrollment has ended |
-| `D2L_CURRENT_ONLY=true` | Only show courses in their current enrollment window, like Brightspace's "Current Courses" widget |
-| `D2L_NO_UPDATE_CHECK=1` | Turn off the new-version notice |
-| `D2L_RUNTIME_IDLE_SECONDS` | How long the shared background server waits with no question running before it stops (default 600) |
-| `D2L_DEV_MODE=true` | Write a local, content-free log of tool calls and sign-in events, for debugging session problems ([how](docs/dev-mode.md)) |
-
-## One server for all your chats
+```bash
+npx -y brightspace-mcp-server@latest sync --course 123456 --dest ~/Courses/ECE-264
+```
 
-Every chat already shares one Brightspace server, with nothing to set up. Each chat still launches the usual command, but that command is now only a small relay: the first question from any chat starts one shared background server for this computer, and every other chat (Claude Desktop, Codex, Cursor, …) uses that same one. That means one sign-in, one saved session, and one cache for all of them. Two chats starting at the same moment still end up with one server. Closing a chat never interrupts another chat's question. After 10 minutes with no question running, the shared server stops by itself, and the next question starts it again.
+Every file in the course's Content area is saved into folders named after its modules. Running it again fetches only what is new.
 
-Chats share a server only when they use the same settings and the same version of this package. A chat started with different `D2L_*` settings, or after an update, gets its own. Because the background server isn't attached to any chat, its log goes to `runtime.log` under `~/.d2l-session/…/shared-runtime/`. Set `D2L_RUNTIME_IDLE_SECONDS` to change how long it waits before stopping.
+| Option | What it does |
+|--------|--------------|
+| `--existing skip\|replace\|keep_both` | A file already there: `skip` (default) leaves it, `replace` re-downloads only files the sync saved and you haven't edited, `keep_both` saves a different copy as `name (1).ext` |
+| `--module <id>` | Only that module and the modules inside it |
+| `--dry-run` | List what would be downloaded, and download nothing |
+| `--max-files <n>` | Most files per run (default 300). Run it again to continue |
+| `--json` | Print the result as JSON on stdout, for scripts |
 
-### Running the shared server yourself (optional)
+- The sync keeps a `.brightspace-sync.json` manifest in the folder, which is how it knows which files are its own. Only one sync runs in a folder at a time. If a crashed run left its `.brightspace-sync.lock` behind, the next run takes it over.
+- Course names are made safe for your computer, and a course can't create dotfiles such as `.zshrc` in your folder.
+- Each run is capped at 300 files and 5 GB. The assistant's version also stops cleanly after 8 minutes. Ask it again to continue. Ctrl-C stops the CLI cleanly (exit 130) with no partial file left behind.
+- Exit codes: 0 when everything was done, 1 if a file failed or wasn't attempted (including a sign-in that expired partway; saved files are kept), 2 for a usage error. Links and embedded videos aren't files, so the result counts them separately rather than as missing downloads.
 
-You can also run **one** copy yourself and point every chat at it by URL. It uses the same saved password, saved session, and sign-in as before; a question that needs a sign-in still signs in once, for every chat.
+**Some folders are refused.** Downloads can't go to your home folder itself, a drive root, a hidden (dot) folder such as `~/.ssh`, `~/Library` (except cloud-drive and iCloud folders), system folders such as `/etc` or `/System`, or on Windows `Windows`, `Program Files`, `ProgramData` and `AppData`. Anything else is fine, including `/tmp`, external drives and `~/Documents`. Choose a folder like `~/Documents/Brightspace`; the refusal names the rule. The same rule applies to `download_file`, `get_syllabus` and every other tool that saves to disk. The person running the server can allow a folder anyway with `D2L_DOWNLOAD_ROOTS` (see [Settings](#settings-you-might-want)). Full rules: [LLMs.md](LLMs.md).
 
-1. **Make a secret token, once.** Chats must present it, so other programs and web pages can't read your grades. Generate one:
-   ```bash
-   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-   ```
-   Save it as a user environment variable named `D2L_HTTP_TOKEN`, where both the server and Codex can see it. On Windows: Start → "Edit environment variables for your account" → New, paste it as the value (apps and terminals opened afterwards see it). On macOS or Linux: add `export D2L_HTTP_TOKEN=<token>` to your shell profile (`~/.zshrc`, `~/.bashrc`); a Codex app launched from the Dock or a desktop menu may not read that profile, so start it from a terminal. The server never prints the token.
-2. **Start the server and leave it running** in a terminal of its own:
-   ```bash
-   npx -y brightspace-mcp-server@latest http
-   ```
-   This needs a release with HTTP support; to try it from a source checkout first, run `npm run build`, then `node build/index.js http`. It listens on `http://127.0.0.1:18765/mcp`, on this computer only. Pick another port with `--port 18766` or `D2L_HTTP_PORT`, and use that same port in the URL in step 3. Start it once per login: chats do not start it, and a second copy on the same port stops at once with "already in use" rather than running alongside the first. Nothing signs in at startup.
-3. **Point Codex at it.** In `~/.codex/config.toml`, replace the `command` and `args` lines of your `[mcp_servers.brightspace]` entry with:
-   ```toml
-   [mcp_servers.brightspace]
-   url = "http://127.0.0.1:18765/mcp"
-   bearer_token_env_var = "D2L_HTTP_TOKEN"
-   ```
-   (`env_http_headers = { "Authorization" = "D2L_HTTP_AUTHORIZATION" }` also works, if that variable holds `Bearer <token>`.) A project's own `.codex/config.toml` overrides this one, so remove any `brightspace` entry there or change it the same way. Rerunning `setup` recognizes this entry and keeps it, token settings included.
-4. **Restart Codex.** Chats that were already open keep the old per-chat server until Codex restarts. If you stop or restart the shared server, calls fail until it is back; if they still fail after that, start a new chat or restart Codex.
+## Prompts
 
-Things that change:
-- **Settings go to the server, not to Codex.** A URL entry has no process to pass an `env` table to, so `D2L_*` settings (the [table above](#settings-you-might-want)) are set in the terminal that runs `http`, in a `.env` file in the directory you start it from, or saved by `setup`.
-- **Sign-in messages show up in the server's terminal.** The number to approve still comes back in the chat's answer, and, in clients that show tool progress, while the question is running.
-- **Stopping it:** press Ctrl+C. Questions already running finish first; press Ctrl+C again to stop at once.
-- **Updating it:** restart the server, not Codex. Restarting a client only reconnects it to the server that is already running the old version. Stop the server and start the same `http` command again with the same `D2L_HTTP_TOKEN`, port, and settings; from a source checkout, run `npm run update` first. Update notices from a shared server say this too.
+Apps with a prompt picker (like Claude Desktop) also offer four one-click prompts:
 
-Any other MCP client that can connect to a Streamable HTTP URL with a bearer token can share the same server. To go back to the automatic shared server, put the `command`/`args` entry back (rerun `setup` and say yes when it offers to switch Codex back) and stop the server you started.
+- `weekly_briefing`: a 7-day rollup of what's due, what's new, and what changed in your grades
+- `grade_audit` (optional `courseId`): flags missing or low-scoring items
+- `study_planner` (optional `daysAhead`, default 7): plans study time from due dates and calendar events
+- `course_summary` (required `courseId`): syllabus, outline, assignments and grades for one course
 
 ## When it asks you to sign in
 
-There's no separate login — asking a question signs you in, and it stays signed in on its own most days. When your school wants two-factor again, the number to approve shows up right in the answer; approve it on your phone and the assistant keeps checking on its own — each check waits up to 45 seconds and the original question completes as soon as the sign-in does, without you having to say you've approved it. If your AI client shows tool progress messages, the number appears while the question is still running instead. If it ever gets stuck, run this in a terminal:
+There's no separate login. Asking a question signs you in, and it stays signed in on its own most days. When your school wants two-factor again, the number to approve shows up in the answer. Approve it on your phone, and the assistant keeps checking, so the original question completes as soon as sign-in does. If it gets stuck, run this in a terminal:
 
 ```bash
 npx -y brightspace-mcp-server@latest auth
 ```
 
-**On a Mac,** sign-in first reads your saved password from Keychain. If you picked a one-time **Allow** at the Keychain prompt, a later sign-in from your AI app or another terminal can fail or hang waiting for an approval nobody sees; pick **Always Allow** instead. That permission only lets the local Brightspace server read its own saved sign-in password, nothing else in your Keychain.
+How often your school asks for two-factor is up to the school, not this tool.
+
+**On a Mac,** a one-time **Allow** at the Keychain prompt can make later sign-ins from your AI app or another terminal fail or hang. Pick **Always Allow** instead. That permission only lets the local Brightspace server read its own saved sign-in password, nothing else in your Keychain.
+
+**Want fewer 2FA prompts?** `setup` asks **How often do you want to approve sign-ins on your phone?** Pick **1** every time (the default), **2** to remember this computer, or **3** to let it answer Microsoft's code requests (needs an authenticator setup key). Options 2 and 3 are not for shared computers. Steps and tradeoffs: [docs/sign-in.md](docs/sign-in.md#fewer-2fa-prompts).
 
-**Want fewer 2FA prompts?** `setup` asks one question, "How often do you want to approve sign-ins on your phone?": **1** every time (default), **2** remember this computer, or **3** let this computer answer Microsoft's code requests itself (needs an authenticator setup key). Options 2 and 3 are opt-in and not for shared computers; to turn them off, rerun `setup` and pick 1. The tradeoffs and the steps for getting the key are in [docs/sign-in.md](docs/sign-in.md#fewer-2fa-prompts).
+**To sign in** from a chat, ask your AI app to sign you in to Brightspace. It can start the sign-in itself, and opens a window for you when no password is saved.
 
-**To sign in,** just ask your AI app to sign you in to Brightspace — it can start the sign-in itself now, and it opens a window for you when no password is saved. You can also run `npx -y brightspace-mcp-server@latest auth` in a terminal.
+**To sign out early** (on a shared computer, say), ask your AI app to sign you out of Brightspace, or run `npx -y brightspace-mcp-server@latest auth --logout`. This deletes this computer's saved session, so the next question does a full sign-in. Your password and authenticator key are kept. It doesn't sign you out of Microsoft or Brightspace elsewhere. On a shared computer, also delete the saved `brightspace-mcp-server` entries from Keychain Access (Mac) or Credential Manager (Windows). Details: [docs/sign-in.md](docs/sign-in.md#signing-out-early).
 
-**To sign out early** (on a shared computer, say), just ask your AI app to sign you out of Brightspace, or run `npx -y brightspace-mcp-server@latest auth --logout` in a terminal. It deletes this computer's saved Brightspace session, so the next question does a full sign-in. Your saved password, authenticator key, and settings are kept, so with a saved authenticator key that sign-in can finish without you; on a shared computer, also delete the saved `brightspace-mcp-server` entries from your computer's password store (Keychain Access on a Mac, Credential Manager on Windows). Other AI apps open on this computer are signed out too and will ask you to sign in on their next question. (An app you opened before updating may keep answering for up to an hour; quit and reopen it to sign it out right away.) It only clears this computer; it does not sign you out of Microsoft or Brightspace anywhere else. Both also cancel a sign-in an AI app started that is still waiting for you to approve it (`auth --logout` can't on Windows, and leaves an `auth` run in another terminal alone, deleting nothing). Cancelling doesn't get you a new prompt any sooner: Microsoft won't send another until the earlier one expires, up to 5 minutes after it was sent.
+Duo, authenticator codes, visible-browser mode, and running without a browser at all (Docker, WSL, hardware keys) are covered in [docs/sign-in.md](docs/sign-in.md).
+
+## Settings you might want
 
-How often you're asked is up to your school, not this tool. Everything else about sign-in — Duo, authenticator codes, visible-browser mode, and running without a browser at all (Docker, WSL, hardware keys) — is in [docs/sign-in.md](docs/sign-in.md).
+All optional. Set them in your AI app's MCP `env` config or in your shell. The full list is in [LLMs.md](LLMs.md#environment-variables).
+
+| Setting | What it does |
+|---------|--------------|
+| `D2L_REMEMBER_MFA=true` | Tick Microsoft's "Don't ask again" box so later sign-ins skip the second factor. Off by default, and not for shared computers. `setup` option 2 saves the same choice |
+| `D2L_TOTP_SECRET` | An authenticator setup key, so a Microsoft code challenge is answered on this computer. Prefer `setup` option 3, which keeps the key in your OS keychain. Environment only for CI and containers: anything that can read the environment gets your second factor ([details](docs/sign-in.md#fewer-2fa-prompts)) |
+| `D2L_HEADLESS=false` | Show the browser window during sign-in, for MFA methods that need a click |
+| `D2L_DUO_PASSCODE=1` | On Duo, type a passcode instead of waiting for a push |
+| `D2L_SESSION_COOKIE` / `D2L_ACCESS_TOKEN` | Skip the browser entirely with a pasted cookie or token. See [docs/sign-in.md](docs/sign-in.md#no-browser-paste-a-session-cookie-or-token) |
+| `D2L_INCLUDE_COURSES` / `D2L_EXCLUDE_COURSES` | Comma-separated course ids to show or hide |
+| `D2L_ACTIVE_ONLY=false` | Include courses whose enrollment has ended |
+| `D2L_CURRENT_ONLY=true` | Only show courses in their current enrollment window (Brightspace's "Current Courses" widget) |
+| `D2L_DOWNLOAD_ROOTS=/data:/srv/courses` | Folders downloads may always use, even where the refusals above say no. Separate paths with `:` on macOS and Linux, `;` on Windows. Only the person running the server can set it |
+| `D2L_NO_UPDATE_CHECK=1` | Turn off the new-version notice |
+| `D2L_DEV_MODE=true` | Write a local, content-free log of tool calls and sign-in events, for debugging ([how](docs/dev-mode.md)) |
+
+## One server for all your chats
+
+Every chat shares one Brightspace server automatically, with one sign-in, one session and one cache. Closing a chat never interrupts another. Codex users, or anyone who wants to run one server themselves, can follow [docs/shared-server.md](docs/shared-server.md).
+
+## Privacy and security
+
+Your password is stored in your computer's password store, never in a plaintext file. Saved session state is encrypted with AES-256-GCM. Approvals (the tap or number) stay on your phone, and the server never sees them. A code you type, or one generated from a saved authenticator key, goes only to the sign-in page. None of the tools submit, edit or delete anything in your courses. More detail: [docs/sign-in.md](docs/sign-in.md#whats-stored-where).
 
 ## Something not working?
 
-- Run `npx -y brightspace-mcp-server@latest doctor` first — it checks your Node version, the sign-in browser, saved setup, credential store, Brightspace connectivity, saved sign-in, and installed version, and tells you exactly what to fix. For a global installation, use `brightspace-mcp-server doctor` to check the copy your client launches.
-- **Browser removed during disk cleanup?** Sign-in restores a missing Chromium download once and retries automatically. It uses the installed Playwright dependency's browser revision and preserves saved credentials, MFA enrollment and sessions. Downloads have a two-minute limit; offline or failed repairs return an actionable installation error instead of asking you to reset credentials.
-- **Repair without signing in or changing client configuration:** run `brightspace-mcp-server repair` for a global install, or `npx -y brightspace-mcp-server@latest repair` for an npx installation. Add `--json` for automation. Diagnostics print an absolute command for the exact installation being checked. Repair verifies both the full browser executable and a real headless launch and close. It does not register clients, update school settings, or start SSO/MFA.
-- Browser downloads are disposable; files inside an installed package's `node_modules` are dependency code. If those files were deleted, diagnostics give an installation-scoped npm command to restore the package's declared dependencies first. Browser repair does not run npm or upgrade packages automatically.
-- **`Authentication failed: The native credential store is locked or unavailable.`** Your password store is locked or hasn't let this server read the saved password. Unlock it (on a Mac, log in or unlock Keychain Access), then run `npx -y brightspace-mcp-server@latest auth` again, or `setup` if that still fails, and choose **Always Allow** when Keychain asks.
-- **It works in the terminal but not in the app:** the app starts it separately and may not see your password store yet — see [docs/troubleshooting.md](docs/troubleshooting.md).
-- **The app says the server timed out while starting:** open the app's MCP server log. Each startup step prints a timestamped `Startup: ...` line before it begins and `done in N ms` when it ends, and a step still running after 10 seconds prints `Startup: still ...` once. The last such line names the step it was stuck in, often the saved-password lookup in your password store. These lines never include your username, password, or cookies.
+- Run `npx -y brightspace-mcp-server@latest doctor` first. It checks the whole setup and tells you what to fix. For a global install, use `brightspace-mcp-server doctor`.
+- **Browser removed** (say, by a disk cleaner): sign-in restores it once by itself. To do it now, run `npx -y brightspace-mcp-server@latest repair`. It doesn't sign in or change your AI apps.
+- **`npx` fails with `EPERM` on a Mac:** run it from your home folder. macOS blocks `npx` from Documents, Desktop and Downloads unless you grant Files and Folders access.
+- **`Authentication failed: The native credential store is locked or unavailable.`** Unlock your password store (on a Mac, log in or unlock Keychain Access), run `npx -y brightspace-mcp-server@latest auth` again (or `setup` if that still fails), and choose **Always Allow** when Keychain asks.
+- **Works in a terminal but not in the app:** the app starts the server separately and may not see your password store yet.
+- **The app says the server timed out while starting:** see the startup notes in [docs/troubleshooting.md](docs/troubleshooting.md).
 - **Which version do I have?** Ask your AI "which version of the Brightspace server am I running?"
+- **Anything else:** see [docs/troubleshooting.md](docs/troubleshooting.md).
 - **Still stuck?** [Open an issue](https://github.com/RohanMuppa/brightspace-mcp-server/issues) and paste what the terminal printed.
 
 ## For developers
 
-Tool reference, response fields, and environment variables: [LLMs.md](LLMs.md). What's safe to build against: [STABILITY.md](STABILITY.md). Licensed under the MIT License.
+Tool reference, response fields, environment variables and the codebase map: [LLMs.md](LLMs.md). What's safe to build against: [STABILITY.md](STABILITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/build/api/client.js

@@ -293,7 +293,9 @@ export class D2LApiClient {
         // Join an identical GET already in flight rather than issuing a second
         // one. Keyed on the same unresolved path the cache above uses, so the
         // join happens before version discovery or a token is even touched.
-        const pending = this.pendingGets.get(path);
+        // A caller with a signal is never joined to another's request (its abort
+        // must end only its own) and never joined by one.
+        const pending = options?.signal ? undefined : this.pendingGets.get(path);
         if (pending) {
             this.statsData.coalescedJoins++;
             log("DEBUG", `Coalescing GET onto an in-flight request: ${path}`);
@@ -302,7 +304,7 @@ export class D2LApiClient {
         const generation = this.cacheGeneration;
         const inFlight = (async () => {
             const resolved = await this.resolvePath(path);
-            const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token));
+            const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token, options?.signal), options?.signal);
             if (options?.ttl && generation === this.cacheGeneration) {
                 this.cache.set(path, data, options.ttl);
                 log("DEBUG", `Cached response for ${path} (TTL: ${options.ttl}ms)`);
@@ -312,7 +314,8 @@ export class D2LApiClient {
             if (this.pendingGets.get(path) === inFlight)
                 this.pendingGets.delete(path);
         });
-        this.pendingGets.set(path, inFlight);
+        if (!options?.signal)
+            this.pendingGets.set(path, inFlight);
         return inFlight;
     }
     /**
@@ -325,9 +328,10 @@ export class D2LApiClient {
      * @throws ApiError on HTTP errors (401, 403, 429, etc.)
      * @throws NetworkError on network/fetch failures
      */
-    async getRaw(path) {
+    async getRaw(path, options) {
+        options?.signal?.throwIfAborted();
         const resolved = await this.resolvePath(path);
-        return this.withAuthentication(resolved, token => this.makeRawRequest(resolved, token));
+        return this.withAuthentication(resolved, token => this.makeRawRequest(resolved, token, options?.signal), options?.signal);
     }
     /**
      * Fetch a Brightspace web page (not an API route) as the signed-in user.
@@ -379,14 +383,14 @@ export class D2LApiClient {
         }
     }
     /** One HTTP refresh and at most one browser login per caller. */
-    async withAuthentication(path, request) {
+    async withAuthentication(path, request, signal) {
         let token = await this.tokenManager.getToken();
         let authenticated = false;
         if (!token) {
             token = await this.tryAutoReauth(path);
             authenticated = true;
         }
-        const send = (current) => this.retrying(() => this.throttled(() => request(current)));
+        const send = (current) => this.retrying(() => this.throttled(() => request(current)), signal);
         try {
             return await send(token);
         }
@@ -446,9 +450,24 @@ export class D2LApiClient {
         return fn();
     }
     /** Retry 429, 5xx, and network failures. A 401 is never retried here. */
-    retrying(fn) {
-        return withRetry(fn, {
+    retrying(fn, signal) {
+        if (!signal) {
+            return withRetry(fn, { ...this.retryConfig, shouldRetry: isRetryableFailure, retryAfterMs: retryAfterMsFrom });
+        }
+        // A caller that has given up gets no further attempt and does not sit out a backoff.
+        const sleep = this.retryConfig.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+        return withRetry(() => {
+            signal.throwIfAborted();
+            return fn();
+        }, {
             ...this.retryConfig,
+            sleep: ms => new Promise((resolve, reject) => {
+                if (signal.aborted)
+                    return reject(signal.reason);
+                const onAbort = () => reject(signal.reason);
+                signal.addEventListener("abort", onAbort, { once: true });
+                sleep(ms).then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+            }),
             shouldRetry: isRetryableFailure,
             retryAfterMs: retryAfterMsFrom,
         });
@@ -478,7 +497,7 @@ export class D2LApiClient {
     /**
      * Make one HTTP request. Authentication recovery is shared with raw downloads.
      */
-    async makeRequest(path, token) {
+    async makeRequest(path, token, signal) {
         const url = `${this.baseUrl}${path}`;
         const headers = this.buildAuthHeaders(token);
         try {
@@ -486,7 +505,7 @@ export class D2LApiClient {
             const response = await fetch(url, {
                 method: "GET",
                 headers,
-                signal: AbortSignal.timeout(this.timeoutMs),
+                signal: signal ? AbortSignal.any([AbortSignal.timeout(this.timeoutMs), signal]) : AbortSignal.timeout(this.timeoutMs),
             });
             this.recordStatus(response.status, path);
             // Preserve cookie material: a 401 only rejects this access token.
@@ -543,7 +562,7 @@ export class D2LApiClient {
     /**
      * Make one HTTP request for raw binary data.
      */
-    async makeRawRequest(path, token) {
+    async makeRawRequest(path, token, signal) {
         const url = `${this.baseUrl}${path}`;
         const headers = this.buildAuthHeaders(token);
         // A file can take far longer than timeoutMs to arrive. Time out on a
@@ -554,7 +573,7 @@ export class D2LApiClient {
             const response = await fetch(url, {
                 method: "GET",
                 headers,
-                signal: idle.signal,
+                signal: signal ? AbortSignal.any([idle.signal, signal]) : idle.signal,
             });
             this.recordStatus(response.status, path);
             // Preserve cookie material for the shared HTTP refresh path.

package/build/index.js

@@ -26,7 +26,7 @@ const PKG_VERSION = (() => {
 })();
 // ── Subcommand routing (before any MCP initialization) ──────────────
 const subcommand = process.argv[2];
-const COMMANDS = ['setup', 'auth', 'doctor', 'repair', 'http', 'runtime'];
+const COMMANDS = ['setup', 'auth', 'doctor', 'repair', 'sync', 'http', 'runtime'];
 // A mistyped command (`htp`) must not quietly start a stdio server that sits
 // waiting on stdin. Flags alone still mean the default stdio server.
 if (subcommand !== undefined && !subcommand.startsWith('-') && !COMMANDS.includes(subcommand)) {
@@ -38,6 +38,7 @@ if (subcommand !== undefined && !subcommand.startsWith('-') && !COMMANDS.include
         '  setup    configure your school and sign-in\n' +
         '  auth     sign in to Brightspace now\n' +
         '  doctor   check the install and configuration\n' +
+        '  sync     download every file of a course (sync --help for options)\n' +
         '  repair   restore and verify this installation\'s Chromium\n');
     process.exit(2);
 }
@@ -50,6 +51,9 @@ else if (subcommand === 'auth') {
 else if (subcommand === 'doctor') {
     await import('./doctor.js');
 }
+else if (subcommand === 'sync') {
+    await (await import('./sync/sync-cli.js')).main(PKG_VERSION);
+}
 else if (subcommand === 'repair') {
     await (await import('./repair.js')).main();
 }
@@ -138,7 +142,7 @@ else {
             const { resolveHttpPort, resolveHttpToken, startHttpServer } = await import("./http-server.js");
             const running = await startHttpServer({ runtime, token: resolveHttpToken(), port: resolveHttpPort() });
             stopServing = running.close;
-            log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (28 tools, 4 prompts registered)`);
+            log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (29 tools, 4 prompts registered)`);
             log("INFO", "Leave this running; every MCP client on this computer connects to that URL. Press Ctrl+C to stop.");
         }
         catch (error) {

package/build/runtime-relay.js

@@ -35,6 +35,13 @@ class Unreachable extends Error {
  */
 export async function relaySharedRuntime(transport, { dir, startRuntime, startTimeoutMs = DEFAULT_START_TIMEOUT_MS }) {
     const disconnected = new AbortController();
+    /**
+     * Each request is its own POST, so the runtime cannot match a later
+     * notifications/cancelled to it. The relay can: it keeps the POST of every
+     * request in progress and aborts it when the client cancels that request.
+     * The runtime ends the tool's own signal when its HTTP request goes away.
+     */
+    const inProgress = new Map();
     let current;
     let locating;
     /** The address to use, after `failed` (if given) did not answer. */
@@ -71,6 +78,15 @@ export async function relaySharedRuntime(transport, { dir, startRuntime, startTi
     };
     const forward = async (message) => {
         const id = "method" in message && "id" in message ? message.id : undefined;
+        if ("method" in message && message.method === "notifications/cancelled") {
+            const target = message.params?.requestId;
+            if (target !== undefined)
+                inProgress.get(target)?.abort();
+        }
+        const cancelled = new AbortController();
+        if (id !== undefined)
+            inProgress.set(id, cancelled);
+        const signal = AbortSignal.any([disconnected.signal, cancelled.signal]);
         let answered = false;
         const reply = (out) => {
             if (id !== undefined && "id" in out && out.id === id && !("method" in out))
@@ -82,7 +98,7 @@ export async function relaySharedRuntime(transport, { dir, startRuntime, startTi
             for (let attempt = 1;; attempt += 1) {
                 const address = await locate(failed);
                 try {
-                    await post(address, message, disconnected.signal, reply);
+                    await post(address, message, signal, reply);
                     if (id !== undefined && !answered)
                         throw new Error("the runtime ended the call without answering it");
                     return;
@@ -98,10 +114,17 @@ export async function relaySharedRuntime(transport, { dir, startRuntime, startTi
         catch (error) {
             if (disconnected.signal.aborted)
                 return;
+            // The client cancelled this request: it is no longer waiting for an answer.
+            if (cancelled.signal.aborted)
+                return;
             log("ERROR", "Relaying to the shared runtime failed", error);
             if (id !== undefined && !answered)
                 reply(failure(id, error));
         }
+        finally {
+            if (id !== undefined && inProgress.get(id) === cancelled)
+                inProgress.delete(id);
+        }
     };
     transport.onmessage = (message) => { void forward(message); };
     transport.onclose = () => disconnected.abort();

package/build/server.js

@@ -9,7 +9,7 @@ import { D2LApiClient } from "./api/index.js";
 import { trackToolActivity } from "./utils/dev-activity.js";
 import { log } from "./utils/logger.js";
 import { envCredentialRejectedMessage, ENV_COOKIE_REJECTED } from "./utils/commands.js";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, COURSE_FILE_NEEDS_COOKIE, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetAvailableGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerSignIn, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, COURSE_FILE_NEEDS_COOKIE, registerDownloadCourseFiles, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetAvailableGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerSignIn, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 /**
  * Build the shared runtime. Nothing here reaches Brightspace: API versions
@@ -85,6 +85,7 @@ export function createMcpServer(runtime) {
     registerGetAnnouncementFiles(server, apiClient);
     registerGetCourseContent(server, apiClient);
     registerDownloadFile(server, apiClient, config.envSessionCookie ? ENV_COOKIE_REJECTED : config.envAccessToken ? COURSE_FILE_NEEDS_COOKIE : undefined);
+    registerDownloadCourseFiles(server, apiClient);
     registerGetClasslistEmails(server, apiClient);
     registerGetRoster(server, apiClient);
     registerGetMyGroups(server, apiClient);
@@ -103,7 +104,7 @@ export function createMcpServer(runtime) {
     registerGetDropboxFeedback(server, apiClient);
     registerGetRubricsForObject(server, apiClient);
     registerDownloadDropboxSubmissionFile(server, apiClient);
-    log("DEBUG", "MCP tools registered (28 tools)");
+    log("DEBUG", "MCP tools registered (29 tools)");
     // Register MCP prompts — surfaced in clients (e.g. Claude Desktop) as a
     // picker, distinct from tools. Each one is a canned user message that
     // names our own tools by name, so a client with no idea what to ask

package/build/sync/cleanup.js

@@ -0,0 +1,61 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { log } from "../utils/logger.js";
+/** A partial download older than this belongs to a run that was killed, not one still going. */
+export const PARTIAL_MAX_AGE_MS = 60 * 60 * 1000;
+/** Exactly what secureStreamDownload names its temporary file. */
+const PARTIAL = /^\.download-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.part$/;
+const MAX_VISITED = 50_000;
+const MAX_DEPTH = 64;
+/**
+ * Remove the `.download-<uuid>.part` files a killed run (kill -9, power loss)
+ * left in the destination tree. Only that exact name, only regular files
+ * older than an hour, and nothing is followed through a symbolic link or into
+ * a hidden folder. Returns how many were removed.
+ */
+export async function removeStalePartials(root, now = Date.now()) {
+    let removed = 0;
+    let visited = 0;
+    const walk = async (dir, depth) => {
+        if (depth > MAX_DEPTH || visited > MAX_VISITED)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (++visited > MAX_VISITED)
+                return;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!entry.name.startsWith("."))
+                    await walk(full, depth + 1);
+            }
+            else if (entry.isFile() && PARTIAL.test(entry.name)) {
+                try {
+                    // lstat again: the entry type above could have changed, and a link is never touched.
+                    const stat = await fs.lstat(full);
+                    if (stat.isFile() && now - stat.mtimeMs > PARTIAL_MAX_AGE_MS) {
+                        await fs.rm(full, { force: true });
+                        removed++;
+                    }
+                }
+                catch {
+                    // Gone already, or not ours to remove.
+                }
+            }
+        }
+    };
+    await walk(root, 0);
+    if (removed > 0)
+        log("INFO", `Course sync: removed ${removed} partial download(s) left by an interrupted run`);
+    return removed;
+}