brightspace-mcp-server 3.15.1 → 3.15.3

package/README.md

@@ -57,7 +57,7 @@ If your school uses D2L Brightspace, yes. These have automatic sign-in built in:
 | McGill University | Microsoft Entra | `--mcgill` |
 | 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, a browser window opens so you can sign in by hand | none |
+| 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 |
 
 School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 
@@ -97,7 +97,6 @@ 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 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` (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 |

package/build/api/client.js

@@ -12,6 +12,20 @@ import { withRetry, isRetryableFailure, retryAfterMsFrom, parseRetryAfter, } fro
 import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { devActivity } from "../utils/dev-activity.js";
+/**
+ * True when a followed redirect ended on this Brightspace's sign-in page. A
+ * web route asked with a dead cookie 302s there rather than serving the
+ * expired-session stub, and fetch follows the redirect to an HTTP 200.
+ */
+function landedOnLogin(responseUrl, baseUrl) {
+    try {
+        const url = new URL(responseUrl);
+        return url.origin === new URL(baseUrl).origin && url.pathname.toLowerCase() === "/d2l/login";
+    }
+    catch {
+        return false;
+    }
+}
 /** An ordinary course HTML link to the login page is not an expired session. */
 function isExpiredSessionRedirect(body, baseUrl) {
     const expiredTarget = (target) => {
@@ -575,8 +589,8 @@ export class D2LApiClient {
             const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
             if (contentType.startsWith("text/html")) {
                 const body = await response.text();
-                if (isExpiredSessionRedirect(body, this.baseUrl)) {
-                    log("DEBUG", "File download answered with the session-expired stub, treating it as a 401");
+                if (isExpiredSessionRedirect(body, this.baseUrl) || landedOnLogin(response.url, this.baseUrl)) {
+                    log("DEBUG", "File download answered with the sign-in page, treating it as a 401");
                     throw new ApiError(401, path, `Session expired. Please re-authenticate via ${AUTH_COMMAND}.`);
                 }
                 // A legitimate HTML page: hand back an equivalent response with the

package/build/setup.js

@@ -361,7 +361,7 @@ export function buildConfigToSave(existing, answers) {
         username: answers.username,
         // Always the freshly typed one: a carried v1 plaintext password would
         // otherwise be the value written to the native store.
-        password: answers.passwordless ? undefined : answers.password,
+        password: answers.password,
         // Only ever the freshly typed one. Never read back out of `carried`: the
         // enrollment lives in the credential store, never in config.json, so a
         // value here could only have come from this run.
@@ -370,8 +370,10 @@ export function buildConfigToSave(existing, answers) {
     };
     if (answers.rememberMfa !== undefined)
         config.rememberMfa = answers.rememberMfa;
-    if (answers.passwordless !== undefined)
-        config.passwordless = answers.passwordless;
+    // Setup no longer offers passwordless sign-in and always saves a password,
+    // so a carried `passwordless: true` would make sign-in ignore that password.
+    // D2L_PASSWORDLESS still turns it on for anyone who wants it.
+    delete config.passwordless;
     if (answers.campus)
         config.campus = answers.campus;
     return config;
@@ -438,6 +440,10 @@ async function main() {
     }
     console.log(dim("  By Rohan Muppa — github.com/rohanmuppa/brightspace-mcp-server"));
     console.log("");
+    // An assistant often opens this wizard in a side panel the user has never
+    // used, and their typing keeps going to the chat box until they click here.
+    console.log("  Click in this window, then type your answer to each question and press Enter.");
+    console.log("");
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
@@ -496,44 +502,20 @@ async function main() {
     }
     console.log("");
     // ── Step 3: Password (hidden) ────────────────────────────────────
-    // Opt-in only, asked the way remember-MFA is: passwordless trades a saved
-    // password for a phone approval on every sign-in, so it is never the default.
-    let savedPasswordless;
-    try {
-        savedPasswordless = configStoreExists() ? loadConfigStore().passwordless : undefined;
-    }
-    catch {
-        // An invalid old config is replaced by the setup values below.
-    }
-    console.log(dim("  Microsoft Entra schools can sign you in with only a phone approval, so no password is saved on this computer."));
-    console.log(dim("  The cost: every sign-in, including automatic ones after a session expires, waits until you approve on your phone."));
-    console.log(dim("  Fine for using an assistant at your desk; not for unattended or scheduled use. It needs passwordless phone sign-in"));
-    console.log(dim("  turned on in Microsoft Authenticator first, or Microsoft will still ask for a password and sign-in will stop."));
-    const defaultPasswordless = savedPasswordless === true ? "yes" : "no";
-    let passwordlessAnswer = "";
-    while (!/^(y(es)?|no?)$/i.test(passwordlessAnswer)) {
-        passwordlessAnswer = await ask(rl, `  Sign in without a saved password (Microsoft Entra only)? (yes/no) [${defaultPasswordless}]: `) || defaultPasswordless;
-        if (!/^(y(es)?|no?)$/i.test(passwordlessAnswer))
-            console.log(yellow("  Please enter yes or no."));
-    }
-    const passwordless = /^y/i.test(passwordlessAnswer);
-    console.log("");
     // Close the rl temporarily since askPassword manages its own
     rl.close();
     let password = "";
-    if (!passwordless) {
-        console.log(dim("  The password you use to sign in. It won't be shown as you type — asterisks stand in for each character."));
-        const passwordPrompt = preset
-            ? `What is your ${preset.name} password? `
-            : "What is your Brightspace password? ";
-        while (!password) {
-            password = await askPassword(passwordPrompt);
-            if (!password) {
-                console.log(yellow("  Password is required."));
-            }
+    console.log(dim("  The password you use to sign in. It won't be shown as you type — asterisks stand in for each character."));
+    const passwordPrompt = preset
+        ? `What is your ${preset.name} password? `
+        : "What is your Brightspace password? ";
+    while (!password) {
+        password = await askPassword(passwordPrompt);
+        if (!password) {
+            console.log(yellow("  Password is required."));
         }
-        console.log("");
     }
+    console.log("");
     // Re-open readline for remaining prompts
     let rl2 = readline.createInterface({
         input: process.stdin,
@@ -553,9 +535,9 @@ async function main() {
     // MFA you have is detected at sign-in time, so offering "approve a prompt"
     // and "type a code" as separate choices would be a distinction the code does
     // not make, and picking between them would change nothing on disk.
-    console.log("  When your school asks you to approve the sign-in, how will you do it?");
-    console.log("    1. I approve on my phone, or I type a code from an authenticator app (recommended)");
-    console.log("    2. Something else — open a browser window I can use");
+    console.log("  How do you confirm it's you when you sign in?");
+    console.log("    1. With a phone app: I tap Approve or type a code (recommended)");
+    console.log("    2. Another way, like a text message: show me the sign-in page");
     let savedHeadless;
     let savedRememberMfa;
     try {
@@ -575,8 +557,8 @@ async function main() {
     }
     const headless = mfaChoice !== "2";
     console.log(dim(headless
-        ? "  Authentication will run without a browser window."
-        : "  A browser window will open when authentication is needed."));
+        ? "  Sign-in will run in the background."
+        : "  The sign-in page will open when you sign in here, so you can finish it yourself."));
     console.log("");
     // ── Step 4b: How often to approve (the one 2FA question) ─────────
     // Opt-in only: the default asks every time, and a shared computer must never
@@ -621,13 +603,10 @@ async function main() {
         totpUri,
         headless,
         rememberMfa,
-        passwordless,
         campus: campus || undefined,
     });
     await saveSecureConfig(config);
-    console.log(green(passwordless
-        ? "  No password saved: each sign-in will wait for your phone approval."
-        : "  Password saved in your operating system credential store."));
+    console.log(green("  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) {
@@ -664,7 +643,7 @@ async function main() {
     // ── Step 7: Claude Desktop auto-config ───────────────────────────
     const claudePath = getClaudeDesktopConfigPath();
     if (claudePath) {
-        const configClaude = await ask(rl2, "Would you like to automatically configure Claude Desktop? (yes/no): ");
+        const configClaude = await ask(rl2, "Would you like to automatically configure Claude Desktop? Highly recommended. (yes/no): ");
         if (/^y(es)?$/i.test(configClaude) &&
             await registerWithClient(rl2, "Claude Desktop", inspectMcpClient(claudePath), () => configureMcpClient(claudePath))) {
             configuredClients.push("Claude Desktop");
@@ -696,7 +675,7 @@ async function main() {
     for (const client of cliMcpClients()) {
         if (!isCliAvailable(client))
             continue;
-        const configureClient = await ask(rl2, `${client.displayName} detected. Configure it automatically? (yes/no): `);
+        const configureClient = await ask(rl2, `${client.displayName} detected. Configure it automatically? Highly recommended. (yes/no): `);
         if (/^y(es)?$/i.test(configureClient) &&
             await registerWithClient(rl2, client.displayName, inspectCliMcpClient(client), (replace) => registerCliMcpClient(client, { replace }))) {
             configuredClients.push(client.displayName);

package/build/tools/download-file.js

@@ -288,7 +288,7 @@ export function registerDownloadFile(server, apiClient) {
             }
             // Determine download source
             if (coursePath !== undefined) {
-                const filePath = parseCoursePath(coursePath, courseId);
+                const filePath = parseCoursePath(coursePath, courseId, apiClient.origin);
                 if (typeof filePath !== "string")
                     return errorResponse(filePath.error);
                 return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename);
@@ -311,7 +311,7 @@ export function registerDownloadFile(server, apiClient) {
                 return await downloadNewsAttachment(apiClient, courseId, newsId, fileId, downloadPath, customFilename);
             }
             else {
-                return errorResponse("Either topicId (for content files), both folderId and fileId (for submission files), or both newsId and fileId (for announcement attachments) must be provided");
+                return errorResponse("Either topicId (for content files), coursePath (for course files linked from a module description), both folderId and fileId (for submission files), or both newsId and fileId (for announcement attachments) must be provided");
             }
         }
         catch (error) {
@@ -329,7 +329,15 @@ async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, c
     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.`);
+        return errorResponse(`Course files are served only to a signed-in Brightspace web session, and there is no valid one: the session cookie is missing or has expired. Sign in again 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.`);
+    }
+    // A missing file or a refused one can come back as an ordinary Brightspace
+    // web page with HTTP 200. That page is not the file, so it is never saved
+    // or shown under the file's name.
+    const contentType = (response.headers.get("Content-Type") ?? "").toLowerCase();
+    if (contentType.startsWith("text/html") && !/\.html?$/i.test(filePath)) {
+        await response.body?.cancel();
+        return errorResponse(`Brightspace answered with a web page instead of the course file "${filePath}". The file may have been moved or deleted, or this account may not be allowed to open it.`);
     }
     const disposition = response.headers.get("Content-Disposition") ?? "";
     const filename = parseContentDispositionFilename(disposition) ?? filePath.split("/").pop() ?? "download";

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

@@ -109,9 +109,9 @@ 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) {
+                const courseFiles = item.Description?.Html ? extractCourseFilePaths(item.Description.Html, courseId, apiClient.origin) : [];
                 tree.push({
                     type: 'module',
                     id: item.Id,

package/build/utils/course-files.js

@@ -3,25 +3,26 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import { tagAttributes } from "./html-attributes.js";
+import { toBrightspacePath } from "./transcript/lti.js";
 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.
+ * An absolute quickLink URL must be on `origin`; without one, only a
+ * root-relative link is accepted.
  */
-export function parseCoursePath(input, courseId) {
+export function parseCoursePath(input, courseId, origin) {
     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." };
+    // A plain course-file path never starts with "/" or names a scheme, so
+    // anything that does is a link, however its file name reads.
+    if (filePath.startsWith("/") || /^[a-z][a-z\d+.-]*:\/\//i.test(filePath)) {
+        const brightspacePath = toBrightspacePath(filePath, origin);
+        const link = brightspacePath === null ? null : new URL(brightspacePath, "https://placeholder.invalid");
+        if (link === null || link.pathname !== QUICKLINK_PATH || link.searchParams.get("type") !== "coursefile") {
+            return { error: "coursePath must be a course file path or a quickLink URL on this Brightspace with type=coursefile." };
         }
         const ou = link.searchParams.get("ou");
         if (ou !== null && ou !== String(courseId)) {
@@ -45,10 +46,13 @@ export function parseCoursePath(input, courseId) {
  * 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) {
+export function extractCourseFilePaths(html, courseId, origin) {
     const found = [];
-    for (const [, href] of html.matchAll(/href\s*=\s*["']([^"']*quickLink\.d2l[^"']*)["']/gi)) {
-        const parsed = parseCoursePath(href.replace(/&/g, "&"), courseId);
+    for (const anchor of tagAttributes(html, "a")) {
+        const href = anchor.get("href");
+        if (!href?.includes("quickLink.d2l"))
+            continue;
+        const parsed = parseCoursePath(href, courseId, origin);
         if (typeof parsed === "string" && !found.includes(parsed))
             found.push(parsed);
     }

package/build/utils/html-attributes.js

@@ -0,0 +1,26 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+/** Decode the character references Brightspace's HTML editor writes into attribute values. */
+export function decodeEntities(value) {
+    return value
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)))
+        .replace(/"/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+/**
+ * The attributes of every `<tag>` element in `html`, names lowercased and
+ * values entity-decoded. A value ends only at its own closing quote, so an
+ * apostrophe inside a double-quoted href stays part of it.
+ */
+export function tagAttributes(html, tag) {
+    return [...html.matchAll(new RegExp(`<${tag}\\b[^>]*>`, "gi"))].map(element => new Map([...element[0].matchAll(/([\w-]+)\s*=\s*(["'])([\s\S]*?)\2/g)].map(match => [
+        match[1].toLowerCase(),
+        decodeEntities(match[3]),
+    ])));
+}

package/build/utils/transcript/lti.js

@@ -12,6 +12,7 @@
  * page; fetching it is the caller's job.
  */
 import { detectVideoPlatform, extractKalturaIds, extractYouTubeVideoId } from "./platform.js";
+import { tagAttributes } from "../html-attributes.js";
 /** A link into the user's own Brightspace, which only an authenticated request can follow. */
 export function isBrightspaceRelativeLink(url) {
     return url.startsWith("/d2l/");
@@ -50,21 +51,6 @@ export function toBrightspacePath(url, origin) {
         return null;
     return `${parsed.pathname}${parsed.search}`;
 }
-function decodeEntities(value) {
-    return value
-        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
-        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)))
-        .replace(/"/g, '"')
-        .replace(/&lt;/g, "<")
-        .replace(/&gt;/g, ">")
-        .replace(/&amp;/g, "&");
-}
-function tagAttributes(html, tag) {
-    return [...html.matchAll(new RegExp(`<${tag}\\b[^>]*>`, "gi"))].map(element => new Map([...element[0].matchAll(/([\w-]+)\s*=\s*(["'])([\s\S]*?)\2/g)].map(match => [
-        match[1].toLowerCase(),
-        decodeEntities(match[3]),
-    ])));
-}
 /** True when an adapter could fetch a transcript from `url`, or name the platform it can't yet. */
 function namesVideo(url) {
     switch (detectVideoPlatform(url)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "3.15.1",
+  "version": "3.15.3",
   "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",