brightspace-mcp-server 5.1.43 → 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/auth/auth-runner.js

@@ -13,17 +13,19 @@ import { AUTH_COMMAND } from "../utils/commands.js";
 import { dependencyRepairHint, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
 import { devActivity, newRecoveryId, RECOVERY_ID_ENV } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
-import { AUTOMATIC_PENDING_MARKER, MFA_HELD_MARKER, RELAYED_CHALLENGE_MARKER, RELAYED_STARTING_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
+import { AUTOMATIC_PENDING_MARKER, MFA_HELD_MARKER, MFA_MAX_WAIT_MS, RELAYED_CHALLENGE_MARKER, RELAYED_STARTING_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
 import { inspectLockOwner, liveAutomaticOwner } from "./auth-lock.js";
 /**
  * Timeout for the auth process. It has to outlast the child's own MFA wait,
- * which is five minutes: a person has to find their phone, unlock it, and read
- * a number off the screen. A shorter parent budget would kill the child in the
- * middle of a sign-in the user was still completing. run() itself usually
+ * which is up to MFA_MAX_WAIT_MS (15 minutes: five for the first number and five
+ * more for each of the two resent ones, see purdue-sso.ts) plus the browser
+ * launch and sign-in pages before MFA starts. A shorter parent budget would
+ * kill the child in the middle of a sign-in the user was still completing
+ * (the 8-minute budget cut a resent number's window short). run() itself usually
  * returns long before this fires — the moment the child reports an MFA
  * challenge — but this timer keeps bounding the background child regardless.
  */
-const AUTH_TIMEOUT_MS = 8 * 60 * 1000;
+const AUTH_TIMEOUT_MS = MFA_MAX_WAIT_MS + 3 * 60 * 1000;
 const KILL_GRACE_MS = 5000;
 /**
  * How long a caller keeps waiting for the background sign-in once the
@@ -65,8 +67,8 @@ const ABANDON_MS = MFA_POLL_MS;
 const RELAY_POLL_MS = 1000;
 /**
  * How long a relayed challenge stays "already told to a caller" for the rule
- * that only a RETRY waits on another process's sign-in. The MFA window is five
- * minutes, so a number reported longer ago than that belongs to a sign-in that
+ * that only a RETRY waits on another process's sign-in. One number's MFA window is five
+ * minutes (a resent number is a new number with a new window), so a number reported longer ago than that belongs to a sign-in that
  * is over; the same digits showing up again are a new challenge.
  */
 const RELAY_TOLD_MS = 5 * 60 * 1000;

package/build/auth/mfa-challenge.js

@@ -16,6 +16,21 @@ import * as fs from "node:fs/promises";
 import { statSync } from "node:fs";
 import * as path from "node:path";
 import { CHALLENGE_FILE } from "./auth-lock.js";
+/**
+ * How long one Microsoft number-match request stays approvable: a person has
+ * to find their phone, unlock it and read a prompt, and Microsoft expires the
+ * request itself at about this mark.
+ */
+export const MFA_APPROVAL_WINDOW_MS = 5 * 60 * 1000;
+/** Times a sign-in may ask Microsoft for a fresh number after one expires or is denied. */
+export const MFA_MAX_RESENDS = 2;
+/**
+ * The longest a sign-in waits on MFA: the first number's window plus a full
+ * window for each resent number (each resend restarts the clock, see
+ * purdue-sso.ts handleMFA). 15 minutes. Anything that bounds the sign-in
+ * from outside has to outlast this.
+ */
+export const MFA_MAX_WAIT_MS = MFA_APPROVAL_WINDOW_MS * (1 + MFA_MAX_RESENDS);
 /** Same bound the auth child's stdout marker enforces: 1-3 digits and nothing else. */
 const NUMBER_MATCH = /^\d{1,3}$/;
 export function authLockPath(sessionDir) {

package/build/auth/purdue-sso.js

@@ -9,6 +9,7 @@ import { devActivity } from "../utils/dev-activity.js";
 import { AutomaticCodeAuthenticationError, MfaApprovalError, UnsupportedAuthenticationError } from "./sso-flow.js";
 import { DuoMfaHandler } from "./duo-mfa.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
+import { MFA_APPROVAL_WINDOW_MS, MFA_MAX_RESENDS } from "./mfa-challenge.js";
 import { generateTotp, secondsUntilFreshCode } from "./totp.js";
 // Entra names its username field type=email/loginfmt; Shibboleth portals (USC's
 // login.usc.edu among them) use the protocol's j_username.
@@ -66,16 +67,20 @@ const REMEMBER_MFA_LOG = {
 /** How often to look for the number while waiting on MFA. */
 const NUMBER_MATCH_POLL_MS = 2000;
 /** A person has to find their phone, unlock it, and read a prompt. */
-const MFA_TIMEOUT_MS = 5 * 60 * 1000;
+const MFA_TIMEOUT_MS = MFA_APPROVAL_WINDOW_MS;
 /**
- * Entra's number-match request itself expires (typically ~1-2 minutes) well
- * before the 5-minute MFA_TIMEOUT_MS this flow allows overall, or the user
- * can tap Deny. Either way Entra stops showing the number and offers a way to
- * send another request; without asking for one this flow just polls a dead
- * request until MFA_TIMEOUT_MS. Bounded so a tenant that never clears this
- * screen still hits the ordinary timeout instead of resending forever.
+ * Entra's number-match request itself expires (observed live at about the
+ * same 5 minutes as MFA_TIMEOUT_MS, 2026-11-08; earlier tenants showed 1-2
+ * minutes), or the user can tap Deny. Either way Entra stops showing the
+ * number and offers a way to send another request; without asking for one
+ * this flow just polls a dead request until the deadline. Each resend gives
+ * the new number its own full MFA_TIMEOUT_MS (the deadline moves to
+ * resend time + MFA_TIMEOUT_MS), because a resend made at the 5-minute mark
+ * left the new number about four seconds. Bounded, so the total is at most
+ * (1 + MAX_RESENDS) * MFA_TIMEOUT_MS (MFA_MAX_WAIT_MS, 15 minutes) and a
+ * tenant that never clears this screen still ends instead of resending forever.
  */
-const MAX_RESENDS = 2;
+const MAX_RESENDS = MFA_MAX_RESENDS;
 /**
  * EXPECTED, not verified against a live tenant from here: Entra's "Send
  * another request" control on the number-match timeout/denied view.
@@ -412,7 +417,7 @@ export class PurdueSSOFlow {
             throw new UnsupportedAuthenticationError("A school URL is required to verify authentication.");
         }
         const startedAt = Date.now();
-        const deadline = startedAt + MFA_TIMEOUT_MS;
+        let deadline = startedAt + MFA_TIMEOUT_MS;
         let challenged = false;
         /** True once onMfaHeld has reported this login. */
         let heldReported = false;
@@ -565,9 +570,9 @@ export class PurdueSSOFlow {
                     resendNotFoundWarned = false;
                 }
                 // Fix 2: Entra's number-match request itself times out (or the user
-                // taps Deny) well before the 5-minute budget above. Once that has
+                // taps Deny), at the latest about when the budget above runs out. Once that has
                 // happened, ask Entra for another one instead of polling a dead
-                // request until MFA_TIMEOUT_MS; readNumberMatch on the next poll
+                // request until the deadline; readNumberMatch on the next poll
                 // picks up the fresh number, and the re-announce logic above tells
                 // the caller about it.
                 if (manualRequired && sawNumber && number === null && new URL(page.url()).hostname === "login.microsoftonline.com") {
@@ -581,6 +586,8 @@ export class PurdueSSOFlow {
                         onResend: (clickedAt) => {
                             resendCount += 1;
                             resendLastClickAt = clickedAt;
+                            // The new number gets its own full approval window; never shorten.
+                            deadline = Math.max(deadline, clickedAt + MFA_TIMEOUT_MS);
                         },
                     });
                 }
@@ -637,7 +644,7 @@ export class PurdueSSOFlow {
         }
         const clickedAt = Date.now();
         state.onResend(clickedAt);
-        log("WARN", `Number-match request expired; sent another request (${state.resendCount + 1} of ${MAX_RESENDS}).`);
+        log("WARN", `Number-match request expired; sent another request (${state.resendCount + 1} of ${MAX_RESENDS}). The new number gets its own ${MFA_TIMEOUT_MS / 60000} minutes.`);
         await control.click().catch(() => { });
         return state.resendNotFoundWarned;
     }

package/build/auth/sso-flow.js

@@ -39,7 +39,7 @@ export class MfaApprovalError extends BrowserAuthError {
      */
     numberMatch;
     constructor(cause, numberMatch) {
-        super(`MFA approval failed or timed out after 5 minutes. Run ${AUTH_COMMAND} to retry.`, "mfa_approval", cause);
+        super(`MFA approval failed or timed out: no approval within 5 minutes of the last number shown. Run ${AUTH_COMMAND} to retry.`, "mfa_approval", cause);
         this.name = "MfaApprovalError";
         this.numberMatch = numberMatch;
     }

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) {