brightspace-mcp-server 3.13.22 → 3.15.0

package/README.md

@@ -96,9 +96,9 @@ All optional, set in your AI app's MCP `env` config or your shell. The full list
 
 | 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 and saves it as `rememberMfa` in `config.json`; the env var overrides it |
+| `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_PASSWORDLESS=true` | Sign in with Microsoft Entra's passwordless phone approval, so no password is saved on the computer (off by default; Entra schools only). Every sign-in, including automatic ones, then waits for you to approve on your phone, so it suits interactive use, not unattended or scheduled jobs. `setup` asks this and saves it as `passwordless` in `config.json`; the env var overrides it ([details](docs/sign-in.md#passwordless-sign-in)) |
-| `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`, 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#answering-code-challenges-without-your-phone)) |
+| `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)) |
@@ -118,13 +118,7 @@ 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.
 
-**If your school asks for a 6-digit code** rather than a phone approval, `setup` can save the
-authenticator **setup key** (not a code) you got when you enrolled the app. From then on automatic
-sign-ins generate the code on this computer and finish without you, which is what unattended and
-scheduled use needs. It is optional and off unless you paste a key. The tradeoff is real: the key
-sits beside your password, so on **this** computer your two factors become one. It still stops
-anyone who only has your password, and it changes nothing for your other devices. Full enrollment
-steps: [docs/sign-in.md](docs/sign-in.md#answering-code-challenges-without-your-phone).
+**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 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. If a sign-in is in progress, it refuses and deletes nothing.
 

package/build/api/client.js

@@ -327,11 +327,20 @@ export class D2LApiClient {
      * read by a read-only tool is not worth an MFA prompt.
      */
     async getPage(path) {
+        const response = await this.getPageRaw(path);
+        return response ? await response.text() : null;
+    }
+    /**
+     * Like getPage, but returns the response itself so a binary body (a course
+     * file reached through a quickLink or /content/enforced path) is not decoded
+     * as text. Same cookie, same origin check, same null on a dead session.
+     */
+    async getPageRaw(path) {
         // The cookie belongs to this Brightspace alone. A path that would make
         // `${baseUrl}${path}` name another host (`@evil.example/`, `.evil.example/`,
         // `//evil.example/`) is refused before the cookie is ever read.
         if (!this.isSameOriginPath(path)) {
-            log("WARN", "getPage refused a path outside the Brightspace origin");
+            log("WARN", "getPageRaw refused a path outside the Brightspace origin");
             return null;
         }
         const token = await this.tokenManager.getToken();
@@ -339,8 +348,7 @@ export class D2LApiClient {
             return null;
         const cookieToken = { ...token, accessToken: `cookie:${token.cookieHeader}` };
         try {
-            const response = await this.retrying(() => this.throttled(() => this.makeRawRequest(path, cookieToken)));
-            return await response.text();
+            return await this.retrying(() => this.throttled(() => this.makeRawRequest(path, cookieToken)));
         }
         catch (error) {
             if (error instanceof ApiError && error.status === 401)

package/build/auth/credential-store.js

@@ -184,6 +184,17 @@ export async function setStoredTotpUri(baseUrl, username, uri, backend = nativeC
         throw new NativeCredentialStoreError("The authenticator enrollment could not be verified in the native credential store. Existing configuration was preserved.");
     }
 }
+/** Remove an account's saved authenticator enrollment. Safe when none was saved. */
+export async function deleteStoredTotpUri(baseUrl, username, backend = nativeCredentialBackend) {
+    const account = totpAccount(baseUrl, username);
+    // Some native stores raise on deleting an entry that does not exist.
+    if (await backend.getPassword(SERVICE, account) === null)
+        return;
+    await backend.deletePassword(SERVICE, account);
+    if (await backend.getPassword(SERVICE, account) !== null) {
+        throw new NativeCredentialStoreError("The saved authenticator enrollment could not be removed from the native credential store.");
+    }
+}
 export async function getStoredPassword(baseUrl, username, backend = nativeCredentialBackend) {
     return backend.getPassword(SERVICE, passwordAccount(baseUrl, username));
 }

package/build/doctor.js

@@ -23,8 +23,9 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import { configStoreExists, loadConfigStore, } from "./utils/config-store.js";
-import { accountSessionDirectory, expandTilde, readEnvSecret, parseSessionCookieEnv } from "./utils/config.js";
-import { getStoredPassword } from "./auth/credential-store.js";
+import { accountSessionDirectory, envBoolean, expandTilde, readEnvSecret, parseSessionCookieEnv } from "./utils/config.js";
+import { getStoredPassword, getStoredTotpUri } from "./auth/credential-store.js";
+import { describeShortcuts } from "./utils/two-factor-shortcuts.js";
 import { discoverVersions } from "./api/version-discovery.js";
 import { TokenManager } from "./auth/token-manager.js";
 import { SessionStore } from "./auth/session-store.js";
@@ -77,6 +78,7 @@ function defaultDoctorDeps() {
         configStoreExists,
         loadConfigStore,
         getStoredPassword,
+        getStoredTotpUri: (baseUrl, username) => getStoredTotpUri(baseUrl, username),
         discoverVersions,
         getSessionToken: (baseUrl, sessionDir, envAccessToken, envSessionCookie) => readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie).getToken(),
         countCourses: async (baseUrl, sessionDir, envAccessToken, envSessionCookie) => {
@@ -194,6 +196,39 @@ async function checkCredential(deps, baseUrl, username, envAccessToken, envSessi
         return problem("credential", `Run setup again: ${SETUP_COMMAND}`);
     }
 }
+/**
+ * The two opt-in ways to be asked for 2FA less often, as one informational
+ * line. Reports only whether each is on: the key itself is never read into
+ * the output, and a credential store that cannot be read says "not checked"
+ * rather than guessing.
+ */
+async function describeTwoFactorShortcuts(deps, baseUrl, username) {
+    let store = null;
+    try {
+        if (deps.configStoreExists())
+            store = deps.loadConfigStore();
+    }
+    catch {
+        store = null;
+    }
+    const rememberMfa = envBoolean(deps.env.D2L_REMEMBER_MFA, "D2L_REMEMBER_MFA") ?? store?.rememberMfa === true;
+    let keySaved;
+    if (deps.env.D2L_TOTP_SECRET) {
+        keySaved = true;
+    }
+    else if (!username) {
+        keySaved = false;
+    }
+    else {
+        try {
+            keySaved = Boolean(await deps.getStoredTotpUri(baseUrl, username));
+        }
+        catch {
+            keySaved = "unknown";
+        }
+    }
+    return describeShortcuts({ rememberMfa, keySaved });
+}
 async function checkNetwork(deps, baseUrl) {
     try {
         await deps.discoverVersions(baseUrl);
@@ -282,6 +317,7 @@ function skip(id, reason) {
 export async function runDoctorChecks(overrides = {}) {
     const deps = { ...defaultDoctorDeps(), ...overrides };
     const checks = [];
+    const notes = [];
     checks.push(checkNode(deps));
     const config = checkConfig(deps);
     checks.push(config.result);
@@ -293,6 +329,7 @@ export async function runDoctorChecks(overrides = {}) {
     }
     else {
         checks.push(await checkCredential(deps, config.baseUrl, config.username, config.envAccessToken, config.envSessionCookie));
+        notes.push(await describeTwoFactorShortcuts(deps, config.baseUrl, config.username));
         checks.push(await checkNetwork(deps, config.baseUrl));
         const session = await checkSession(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie);
         checks.push(session.result);
@@ -304,7 +341,7 @@ export async function runDoctorChecks(overrides = {}) {
         }
     }
     checks.push(await checkVersion(deps));
-    return { checks, allOk: checks.every((c) => c.ok) };
+    return { checks, allOk: checks.every((c) => c.ok), notes };
 }
 // ── CLI entry point ──────────────────────────────────────────────────
 async function main() {
@@ -314,6 +351,8 @@ async function main() {
     console.log("");
     for (const check of result.checks)
         console.log(`  ${check.line}`);
+    for (const note of result.notes)
+        console.log(`  ${note}`);
     console.log("");
     console.log(result.allOk
         ? "Everything looks good — open your AI app and ask a question."

package/build/index.js

@@ -11,6 +11,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { enableStdoutGuard, log } from "./utils/logger.js";
 import { guardServerProcess } from "./utils/process-guard.js";
 import { loadConfig } from "./utils/config.js";
+import { setActiveShortcuts } from "./utils/two-factor-shortcuts.js";
 import { TokenManager, AuthRunner } from "./auth/index.js";
 import { D2LApiClient } from "./api/index.js";
 import { startUpdateChecks } from "./utils/update-checker.js";
@@ -54,6 +55,9 @@ else {
             // Load configuration
             const config = await loadConfig();
             configureDevActivity(config.sessionDir);
+            // Lets the MFA approval message mention the setup options only to users
+            // who have neither turned on. Booleans only; the key is never passed.
+            setActiveShortcuts({ rememberMfa: config.rememberMfa === true, keySaved: Boolean(config.totpUri) });
             log("DEBUG", "Configuration loaded", { sessionDir: config.sessionDir });
             // Create MCP server instance
             const server = new McpServer({

package/build/setup.js

@@ -14,7 +14,8 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { configStoreExists, getConfigStorePath, loadConfigStore, } from "./utils/config-store.js";
 import { saveSecureConfig } from "./utils/secure-config.js";
-import { normalizeTotpEnrollment } from "./auth/totp.js";
+import { deleteStoredTotpUri, getStoredTotpUri } from "./auth/credential-store.js";
+import { askShortcutQuestion } from "./utils/two-factor-shortcuts.js";
 import { writeFileAtomicSync } from "./utils/atomic-write.js";
 import { AUTH_COMMAND, DOCTOR_COMMAND } from "./utils/commands.js";
 import { classifyRegistration, cliMcpClients, inspectCliMcpClient, isCliAvailable, registerCliMcpClient, serverCommand, } from "./utils/mcp-client-cli.js";
@@ -533,29 +534,6 @@ async function main() {
         }
         console.log("");
     }
-    // ── Step 3b: Authenticator enrollment (hidden, optional) ─────────
-    // Opt-in and off by default. Asked without naming a school: whether a code
-    // can be typed depends on the identity provider and the challenge it shows,
-    // which is only known at sign-in time.
-    console.log(dim("  Optional. If your school asks for a 6-digit code from an authenticator app, this computer can generate it"));
-    console.log(dim("  for you, so automatic sign-ins need nothing from your phone. Paste the SETUP KEY (or otpauth:// link) you"));
-    console.log(dim("  got when enrolling the app — a code showing on screen right now will not work."));
-    console.log(dim("  The tradeoff: the key is stored beside your password, so on THIS computer the two factors become one."));
-    console.log(dim("  It still stops anyone who only has your password. Press Enter to skip, or to keep a key you saved before."));
-    let totpUri;
-    while (true) {
-        const input = await askPassword("  Authenticator setup key or otpauth:// link (optional): ");
-        if (!input)
-            break;
-        try {
-            totpUri = normalizeTotpEnrollment(input, username);
-            break;
-        }
-        catch {
-            console.log(yellow("  That is not a setup key or otpauth:// link. Paste the enrollment key, or press Enter to skip."));
-        }
-    }
-    console.log("");
     // Re-open readline for remaining prompts
     let rl2 = readline.createInterface({
         input: process.stdin,
@@ -600,18 +578,40 @@ async function main() {
         ? "  Authentication will run without a browser window."
         : "  A browser window will open when authentication is needed."));
     console.log("");
-    // Opt-in only: a shared computer must never skip MFA unless asked to.
-    const defaultRemember = savedRememberMfa === true ? "yes" : "no";
-    let rememberAnswer = "";
-    while (!/^(y(es)?|no?)$/i.test(rememberAnswer)) {
-        rememberAnswer = await ask(rl2, `  Remember this device so later sign-ins can skip the second factor? Not for shared computers. (yes/no) [${defaultRemember}]: `) || defaultRemember;
-        if (!/^(y(es)?|no?)$/i.test(rememberAnswer))
-            console.log(yellow("  Please enter yes or no."));
+    // ── Step 4b: How often to approve (the one 2FA question) ─────────
+    // Opt-in only: the default asks every time, and a shared computer must never
+    // skip MFA unless asked to. Asked for every school and mode today; the
+    // sign-in flow itself decides at run time whether a code can be typed.
+    let keySaved = false;
+    try {
+        keySaved = Boolean(await getStoredTotpUri(baseUrl, username));
     }
-    const rememberMfa = /^y/i.test(rememberAnswer);
-    console.log(dim(rememberMfa
-        ? "  Later sign-ins will ask Microsoft not to repeat the second factor on this device."
-        : "  Every sign-in will ask for the second factor."));
+    catch {
+        // An unreadable credential store means there is nothing we can offer to remove.
+    }
+    const toneOf = { plain: (l) => l, dim, warn: yellow };
+    const shortcutIO = {
+        ask: (prompt) => ask(rl2, prompt),
+        // The hidden prompt manages its own readline, so the shared one steps aside.
+        async askSecret(prompt) {
+            rl2.close();
+            try {
+                return await askPassword(prompt);
+            }
+            finally {
+                rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
+            }
+        },
+        print: (line, tone = "plain") => console.log(toneOf[tone](line)),
+    };
+    const shortcuts = await askShortcutQuestion(shortcutIO, {
+        username,
+        rememberMfa: savedRememberMfa === true,
+        keySaved,
+        savedConfig: savedRememberMfa !== undefined || keySaved || savedHeadless !== undefined,
+    });
+    const rememberMfa = shortcuts?.rememberMfa;
+    const totpUri = shortcuts?.totpUri;
     console.log("");
     // ── Step 5: Save config ──────────────────────────────────────────
     const config = buildConfigToSave(readExistingConfig(), {
@@ -630,6 +630,15 @@ async function main() {
         : "  Password saved in your operating system credential store."));
     if (totpUri)
         console.log(green("  Authenticator enrollment saved in your operating system credential store."));
+    if (shortcuts?.removeKey) {
+        try {
+            await deleteStoredTotpUri(baseUrl, username);
+            console.log(green("  Saved authenticator key removed from your operating system credential store."));
+        }
+        catch {
+            console.log(yellow("  Could not remove the saved authenticator key. Delete the brightspace-mcp-server entries from your computer's password store."));
+        }
+    }
     console.log(green("  Config saved to: " + getConfigStorePath()));
     console.log("");
     // ── Step 6: Authenticate now? ────────────────────────────────────

package/build/tools/download-file.js

@@ -15,6 +15,8 @@ import { checkTopicAvailability } from "./topic-availability.js";
 import { validateContentId, validateFileType, MAX_FILE_SIZE, DISK_MAX_FILE_SIZE, } from "../utils/file-validator.js";
 import { secureStreamDownload, readBodyCapped } from "../utils/download-helpers.js";
 import { DownloadError } from "../utils/download-errors.js";
+import { AUTH_COMMAND } from "../utils/commands.js";
+import { parseCoursePath, QUICKLINK_PATH } from "../utils/course-files.js";
 import { extractPdfText } from "../utils/pdf-extractor.js";
 import { officeDocumentText } from "../utils/zip-extract.js";
 import fs from "node:fs/promises";
@@ -247,13 +249,16 @@ async function finishDownload(response, originalFilename, downloadPath, customFi
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content, instructor assignment attachments (source: assignmentAttachment with folderId + fileId), assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
+        description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {
             log("DEBUG", "download_file tool called", { args });
             // Parse and validate input
-            const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename, source } = DownloadFileSchema.parse(args);
+            const { courseId, topicId, coursePath, folderId, newsId, fileId, downloadPath, customFilename, source } = DownloadFileSchema.parse(args);
+            if (coursePath !== undefined && (topicId !== undefined || folderId !== undefined || newsId !== undefined || fileId !== undefined || source !== undefined)) {
+                return errorResponse("coursePath cannot be combined with topicId, folderId, newsId, fileId, or source.");
+            }
             if (source !== undefined && (topicId !== undefined || newsId !== undefined || folderId === undefined || fileId === undefined)) {
                 return errorResponse("source requires folderId and fileId and cannot be combined with topicId or newsId.");
             }
@@ -282,7 +287,13 @@ export function registerDownloadFile(server, apiClient) {
                 }
             }
             // Determine download source
-            if (topicId !== undefined) {
+            if (coursePath !== undefined) {
+                const filePath = parseCoursePath(coursePath, courseId);
+                if (typeof filePath !== "string")
+                    return errorResponse(filePath.error);
+                return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename);
+            }
+            else if (topicId !== undefined) {
                 // Content file download
                 validateContentId(topicId);
                 return await downloadContentFile(apiClient, courseId, topicId, downloadPath, customFilename);
@@ -308,6 +319,22 @@ export function registerDownloadFile(server, apiClient) {
         }
     });
 }
+/**
+ * Download a file from the course file store. Instructors often link these
+ * from a module or page description instead of adding them as content
+ * topics, so they have no topicId. Brightspace serves them to the signed-in
+ * web session, not to the API token, so this goes through the session cookie.
+ */
+async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename) {
+    log("INFO", `Downloading course file: courseId=${courseId}, path=${filePath}`);
+    const response = await apiClient.getPageRaw(`${QUICKLINK_PATH}?ou=${courseId}&type=coursefile&fileId=${encodeURIComponent(filePath)}`);
+    if (!response) {
+        return errorResponse(`Course files need a Brightspace web session cookie, and none is available. Sign in with \`${AUTH_COMMAND}\` and retry. A server that runs on D2L_ACCESS_TOKEN alone has no cookie: set D2L_SESSION_COOKIE as well, or sign in through the browser.`);
+    }
+    const disposition = response.headers.get("Content-Disposition") ?? "";
+    const filename = parseContentDispositionFilename(disposition) ?? filePath.split("/").pop() ?? "download";
+    return finishDownload(response, filename, downloadPath, customFilename, "Course file");
+}
 /** Download an instructor-provided handout, independently of student submissions. */
 async function downloadAssignmentAttachment(apiClient, courseId, folderId, fileId, downloadPath, customFilename) {
     const raw = await apiClient.get(apiClient.le(courseId, "/dropbox/folders/"));

package/build/tools/get-course-content.js

@@ -9,6 +9,7 @@ import { toolResponse, sanitizeError } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
 import { log } from "../utils/logger.js";
+import { extractCourseFilePaths } from "../utils/course-files.js";
 import { contentAvailability } from "./content-availability.js";
 // Topic type mapping
 const TOPIC_TYPE_MAP = {
@@ -108,6 +109,7 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
             else if (currentDepth >= MAX_CONTENT_DEPTH) {
                 log('DEBUG', `Content depth ceiling of ${MAX_CONTENT_DEPTH} reached at module ${item.Id}: not descending further`);
             }
+            const courseFiles = item.Description?.Html ? extractCourseFilePaths(item.Description.Html, courseId) : [];
             // Only include module if it has matching children (or filter is 'all')
             if (typeFilter === 'all' || processedChildren.length > 0) {
                 tree.push({
@@ -117,6 +119,7 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                     description: item.Description?.Html?.trim()
                         ? convertHtmlToMarkdown(item.Description.Html).markdown
                         : item.Description?.Text ?? null,
+                    ...(courseFiles.length > 0 ? { courseFiles } : {}),
                     ...(item.ModuleDueDate ? { dueDate: item.ModuleDueDate } : {}),
                     ...(item.IsHidden ? { isHidden: item.IsHidden } : {}),
                     ...(item.IsLocked ? { isLocked: item.IsLocked } : {}),

package/build/tools/schemas.js

@@ -69,6 +69,8 @@ export const DownloadFileSchema = z.object({
         .describe("Course ID the file belongs to."),
     topicId: z.coerce.number().int().positive().optional()
         .describe("Content topic ID to download (for course content files)."),
+    coursePath: z.string().min(1).max(1024).optional()
+        .describe("A file in the course's file store, for files an instructor linked inside a module or page description instead of adding as a content topic (get_course_content lists them as courseFiles on the module). Pass one of those paths (e.g. 'Notes/Lecture 1.pdf') or the whole quickLink URL. Not combined with topicId, folderId, or newsId."),
     folderId: z.coerce.number().int().positive().optional()
         .describe("Dropbox folder ID. Downloads your submission by default; set source to assignmentAttachment for an instructor-provided handout."),
     fileId: z.coerce.number().int().positive().optional()

package/build/tools/tool-helpers.js

@@ -10,6 +10,7 @@ import { AuthProcessError } from "../auth/auth-runner.js";
 import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { getUpdateNotice } from "../utils/update-checker.js";
+import { mfaShortcutTip } from "../utils/two-factor-shortcuts.js";
 import { DownloadError, isSafeDetail, } from "../utils/download-errors.js";
 /**
  * Append an available-update notice to an already-built content array and
@@ -141,7 +142,18 @@ function authFailureMessage(error) {
         return MFA_ALREADY_REPORTED;
     if (error.kind === "automaticPending" && error.duplicate)
         return AUTOMATIC_ALREADY_REPORTED;
-    if (error.kind === "mfaPending" && error.numberMatch) {
+    if (error.kind === "mfaPending") {
+        return withShortcutTip(mfaPendingMessage(error));
+    }
+    return AUTH_FAILURE_GUIDANCE[error.kind];
+}
+/** Appends the one-line "ask for 2FA less often" tip, when it applies (see two-factor-shortcuts.ts). */
+function withShortcutTip(message) {
+    const tip = mfaShortcutTip();
+    return tip ? `${message} ${tip}` : message;
+}
+function mfaPendingMessage(error) {
+    if (error.numberMatch) {
         return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes. ` +
             "Show the user that number now, as text in your reply, before you make any other tool call: " +
             "they can't see tool results, and some apps show nothing until you write it. Then call this " +

package/build/utils/config.js

@@ -189,7 +189,7 @@ function positiveSeconds(value, source) {
  * value counts as unset, and anything unrecognized is ignored with a warning
  * so config.json or the default applies, as positiveSeconds does.
  */
-function envBoolean(value, source) {
+export function envBoolean(value, source) {
     const text = value?.trim().toLowerCase();
     if (!text)
         return undefined;

package/build/utils/course-files.js

@@ -0,0 +1,56 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+export const QUICKLINK_PATH = "/d2l/common/dialogs/quickLink/quickLink.d2l";
+/**
+ * Reduce a coursePath argument to a plain course-file path ("Notes/a.pdf").
+ * Accepts that path or the quickLink URL a module description carries, and
+ * refuses anything that could name a file outside the course file store, so
+ * the argument can only ever steer the request inside this course's files.
+ */
+export function parseCoursePath(input, courseId) {
+    let filePath = input.trim();
+    if (filePath.includes("quickLink.d2l")) {
+        let link;
+        try {
+            link = new URL(filePath, "https://placeholder.invalid");
+        }
+        catch {
+            return { error: "coursePath is not a valid quickLink URL." };
+        }
+        if (link.pathname !== QUICKLINK_PATH || link.searchParams.get("type") !== "coursefile") {
+            return { error: "coursePath must be a course file path or a quickLink URL with type=coursefile." };
+        }
+        const ou = link.searchParams.get("ou");
+        if (ou !== null && ou !== String(courseId)) {
+            return { error: `This quickLink belongs to course ${ou}, not course ${courseId}.` };
+        }
+        filePath = link.searchParams.get("fileId") ?? "";
+    }
+    const segments = filePath.split("/");
+    if (filePath === "" ||
+        filePath.startsWith("/") ||
+        filePath.includes("\\") ||
+        filePath.includes("://") ||
+        segments.some(segment => segment === ".." || segment === "." || segment === "")) {
+        return { error: "coursePath must be a relative path inside the course files (e.g. 'Notes/Lecture 1.pdf'), without '..' segments." };
+    }
+    return filePath;
+}
+/**
+ * The course file paths a module description links through
+ * `quickLink.d2l?type=coursefile`, in page order, once each. Read from the raw
+ * HTML because the Markdown conversion escapes parentheses in file names.
+ * Anything parseCoursePath would refuse, and links to other courses, are left out.
+ */
+export function extractCourseFilePaths(html, courseId) {
+    const found = [];
+    for (const [, href] of html.matchAll(/href\s*=\s*["']([^"']*quickLink\.d2l[^"']*)["']/gi)) {
+        const parsed = parseCoursePath(href.replace(/&/g, "&"), courseId);
+        if (typeof parsed === "string" && !found.includes(parsed))
+            found.push(parsed);
+    }
+    return found;
+}

package/build/utils/two-factor-shortcuts.js

@@ -0,0 +1,179 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * The two opt-in ways to be asked for 2FA less often, described in one place.
+ * `setup`, the MFA hint in tool responses, and `doctor` all take their wording
+ * from here so they cannot drift apart, and all point at the one docs section
+ * that explains both options side by side.
+ *
+ *   A) Remember this device: `rememberMfa` / D2L_REMEMBER_MFA.
+ *   B) Saved authenticator key: the OS keychain entry (or D2L_TOTP_SECRET).
+ *
+ * Both are off by default. Nothing here changes what either one does, and
+ * nothing here ever sees, prints, or derives anything from the key itself:
+ * callers pass only whether one exists.
+ */
+import { normalizeTotpEnrollment } from "../auth/totp.js";
+import { SETUP_COMMAND } from "./commands.js";
+/** The single docs section that explains both options. */
+export const SHORTCUTS_DOCS_URL = "https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/docs/sign-in.md#fewer-2fa-prompts";
+/** Shown in `setup` when option 3 is chosen and no key is saved yet. */
+export const KEY_HOWTO_LINES = [
+    "  How to get the key: open https://mysignins.microsoft.com > Security info > Add sign-in method > Authenticator app,",
+    "  choose \"I want to use a different authenticator app\", then \"Can't scan image?\" and copy the secret key.",
+];
+/** The key prompt when no key is saved. Enter means none. */
+export const KEY_PROMPT = "  Authenticator setup key or otpauth:// link (Enter = none): ";
+/** The key prompt when a key is already saved. Enter keeps it. */
+export const KEY_PROMPT_KEEP = "  Paste a new setup key or otpauth:// link to replace the saved one (Enter to keep it): ";
+const OPTION_TEXT = {
+    every: "Every time Microsoft asks",
+    remember: "Less often: Microsoft remembers this computer for a while (your school decides how long)",
+    key: "Almost never: this computer answers Microsoft's code requests itself (needs a key from Microsoft, about 2 minutes)",
+};
+const CURRENT_NAME = {
+    every: "every time",
+    remember: "remember this computer",
+    key: "this computer answers code requests",
+};
+function currentChoice(input) {
+    return input.keySaved ? "key" : input.rememberMfa ? "remember" : "every";
+}
+async function askYesNo(io, prompt, fallback) {
+    while (true) {
+        const answer = (await io.ask(prompt)) || fallback;
+        if (/^(y(es)?|no?)$/i.test(answer))
+            return /^y/i.test(answer);
+        io.print("  Please enter yes or no.", "warn");
+    }
+}
+/**
+ * The one question setup asks about being asked for 2FA less often. Replaces
+ * the old pair (an optional key prompt, then a yes/no remember question).
+ *
+ * Returns null when no option applies, so nothing is asked. Everything the
+ * user types or sees about the key goes through `io`; the key itself is only
+ * handed to the normalizer and returned, never printed.
+ */
+export async function askShortcutQuestion(io, input) {
+    const applicable = input.applicable ?? { remember: true, key: true };
+    const choices = ["every"];
+    if (applicable.remember)
+        choices.push("remember");
+    if (applicable.key)
+        choices.push("key");
+    if (choices.length === 1)
+        return null;
+    const numberOf = (c) => choices.indexOf(c) + 1;
+    const numbers = choices.map((_, i) => String(i + 1));
+    const list = numbers.length === 2 ? "1 or 2" : "1, 2 or 3";
+    const current = currentChoice(input);
+    const defaultChoice = choices.includes(current) ? current : "every";
+    const defaultNumber = String(numberOf(defaultChoice));
+    io.print("  How often do you want to approve sign-ins on your phone?");
+    for (const c of choices) {
+        const suffix = c === "every" ? (defaultChoice === "every" ? " (default, safest)" : " (safest)") : "";
+        io.print(`    ${numberOf(c)}. ${OPTION_TEXT[c]}${suffix}`);
+    }
+    if (choices.includes("remember")) {
+        io.print(`  Option ${numberOf("remember")} ticks Microsoft's "Don't ask again" box, so you still approve now and then.`, "dim");
+    }
+    if (choices.includes("key")) {
+        io.print(`  Option ${numberOf("key")} stores a key next to your password, so on this computer the two factors become one. It still stops anyone who only has your password.`, "dim");
+        io.print("  It helps only when Microsoft asks for a 6-digit code. If your school only sends a number to approve, sign-in falls back to your phone.", "dim");
+    }
+    const skipping = choices.slice(1).map(numberOf).join(" and ");
+    io.print(`  ${choices.length === 2 ? "Option" : "Options"} ${skipping} ${choices.length === 2 ? "is" : "are"} not for shared computers. Details: ${SHORTCUTS_DOCS_URL}`);
+    if (input.savedConfig) {
+        io.print(`  Currently: ${numberOf(defaultChoice)} \u2014 ${CURRENT_NAME[defaultChoice]}`, "dim");
+    }
+    let reply = "";
+    let blank = false;
+    while (!numbers.includes(reply)) {
+        const raw = await io.ask(`  Choose ${list} [${defaultNumber}]: `);
+        blank = raw === "";
+        reply = raw || defaultNumber;
+        if (!numbers.includes(reply))
+            io.print(`  Please enter ${list}.`, "warn");
+    }
+    let choice = choices[Number(reply) - 1];
+    let removeKey = false;
+    let totpUri;
+    // Someone who saved a key without remember-this-device keeps exactly that on
+    // Enter: remembering a device is opt-in and is never switched on by default.
+    let rememberMfa = (choice === "remember" || (choice === "key" && applicable.remember)) &&
+        !(blank && input.keySaved && !input.rememberMfa);
+    if (choice === "key") {
+        if (input.keySaved) {
+            // Enter on "Currently: 3" is a plain keep; only an explicit 3 offers a replacement.
+            if (!blank)
+                totpUri = await askForKey(io, input.username, KEY_PROMPT_KEEP);
+            if (totpUri === undefined)
+                io.print("  Keeping the saved key.", "dim");
+        }
+        else {
+            for (const line of KEY_HOWTO_LINES)
+                io.print(line, "dim");
+            totpUri = await askForKey(io, input.username, KEY_PROMPT);
+            if (totpUri === undefined) {
+                choice = applicable.remember ? "remember" : "every";
+                rememberMfa = choice === "remember";
+                io.print(`  No key entered. Without a key, option ${numberOf("key")} is the same as option ${numberOf(choice)}, so it is saved as option ${numberOf(choice)}.`, "warn");
+            }
+        }
+    }
+    else if (input.keySaved) {
+        io.print("  A key is saved on this computer. Keeping it means Microsoft's code requests are still answered automatically.", "dim");
+        removeKey = await askYesNo(io, "  Remove the saved authenticator key from this computer? (yes/no) [yes]: ", "yes");
+    }
+    io.print(choice === "every"
+        ? "  Every sign-in will ask for the second factor."
+        : choice === "remember"
+            ? "  Later sign-ins will ask Microsoft not to repeat the second factor on this device."
+            : "  This computer will answer Microsoft's code requests itself.", "dim");
+    return { rememberMfa, removeKey, ...(totpUri ? { totpUri } : {}) };
+}
+/** Prompt (hidden) until a valid key, or Enter. Undefined means none was given. */
+async function askForKey(io, username, prompt) {
+    while (true) {
+        const input = await io.askSecret(prompt);
+        if (!input)
+            return undefined;
+        try {
+            return normalizeTotpEnrollment(input, username);
+        }
+        catch {
+            io.print("  That is not a setup key or otpauth:// link. Paste the enrollment key, or press Enter for none.", "warn");
+        }
+    }
+}
+let current;
+/**
+ * Record, once at startup, which shortcuts are on. Until this is called the
+ * state is unknown and no hint is ever shown, so nothing else is affected.
+ */
+export function setActiveShortcuts(state) {
+    current = { rememberMfa: state.rememberMfa, keySaved: state.keySaved };
+}
+/** Test seam: forget the recorded state. */
+export function resetActiveShortcuts() {
+    current = undefined;
+}
+/**
+ * One short line appended to the MFA approval message, only when the user has
+ * neither shortcut on. Empty string otherwise (including when unknown).
+ */
+export function mfaShortcutTip() {
+    if (!current || current.rememberMfa || current.keySaved)
+        return "";
+    return `Tip for the user: to be asked less often, rerun \`${SETUP_COMMAND}\` - see ${SHORTCUTS_DOCS_URL}`;
+}
+/** The one `doctor` line. Mentions the docs link only when both are off. */
+export function describeShortcuts(state) {
+    const device = `remember this device ${state.rememberMfa ? "on" : "off"}`;
+    const key = state.keySaved === "unknown"
+        ? "authenticator key not checked"
+        : `authenticator key ${state.keySaved ? "saved" : "not saved"}`;
+    const bothOff = !state.rememberMfa && state.keySaved === false;
+    return `2FA shortcuts: ${device}, ${key}.${bothOff ? ` Want fewer prompts? See ${SHORTCUTS_DOCS_URL}` : ""}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "3.13.22",
+  "version": "3.15.0",
   "mcpName": "io.github.RohanMuppa/brightspace",
   "description": "MCP server for Brightspace (D2L). Check grades, due dates, assignments, announcements, syllabus, rosters and more via Claude, ChatGPT, Cursor, Windsurf, or any MCP client.",
   "type": "module",