brightspace-mcp-server 5.1.28 → 5.1.30

package/build/auth/auth-exit-code.js

@@ -0,0 +1,25 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT: see LICENSE file for details.
+ */
+import { BrowserInstallError } from "../utils/browser-install.js";
+import { NativeCredentialStoreError } from "./credential-store.js";
+import { MfaApprovalError } from "./sso-flow.js";
+/**
+ * The exit code auth-cli ends with for a failed sign-in. AuthRunner
+ * maps each code back to a failure kind (see its `failures` table), so the two
+ * must stay in step: 2 busy, 3 cooldown, 4 unsupported, 5 secureStorage,
+ * 6 transport, 7 MFA not approved, 8/9 browser install, 10 stuck, 1 anything else.
+ */
+export function authExitCode(error) {
+    const code = error?.code;
+    return error instanceof BrowserInstallError ? (error.dependencyMissing ? 9 : 8)
+        : error instanceof NativeCredentialStoreError ? 5
+            : code === "AUTH_IN_PROGRESS" ? 2
+                : code === "AUTH_COOLDOWN" ? 3
+                    : code === "AUTH_UNSUPPORTED" ? 4
+                        : code === "AUTH_TRANSPORT" ? 6
+                            : code === "AUTH_STUCK" ? 10
+                                : error instanceof MfaApprovalError ? 7 : 1;
+}

package/build/auth/auth-runner.js

@@ -134,6 +134,15 @@ function mfaPendingFailure(numberMatch) {
  * send the user looking for a prompt that will never arrive.
  */
 const automaticPendingFailure = (relayed = false) => new AuthProcessError("automaticPending", "Sign-in is entering its own verification code in the background. Try again.", undefined, false, relayed);
+/** What every caller is told when the school's sign-in page never settled. */
+const STUCK_MESSAGE = "Sign-in got stuck on the school's sign-in page and stopped. Call sign_in again.";
+/**
+ * Stuck failures from a child that never showed the user anything (no number,
+ * no automatic-code notice, no held prompt). Only these are retried by
+ * themselves: after a prompt reached the user's phone, a second sign-in could
+ * send a second one.
+ */
+const retryableStuck = new WeakSet();
 /**
  * Microsoft is refusing a new prompt for the account until an earlier one
  * expires. Nothing is on the user's phone to approve, and calling again does
@@ -733,7 +742,16 @@ export class AuthRunner {
         // prompt starts a fresh attempt rather than inheriting the stale
         // rejection. Ownership is checked because a caller could in principle
         // clear the latch while this flow is still running.
-        const flow = this.spawnAuth().finally(() => {
+        const flow = this.spawnAuth().catch((error) => {
+            // The sign-in page jammed before anything reached the user: one more
+            // try, in the same call. Anything else (a number shown, a prompt sent)
+            // is reported as it is.
+            if (error instanceof AuthProcessError && retryableStuck.has(error)) {
+                log("WARN", "Sign-in got stuck before any challenge; trying once more");
+                return this.spawnAuth();
+            }
+            throw error;
+        }).finally(() => {
             if (this.inFlight === flow)
                 this.inFlight = null;
         });
@@ -1163,6 +1181,9 @@ export class AuthRunner {
                         4: ["unsupported", "This identity provider cannot complete headless authentication. See the authentication logs."],
                         5: ["secureStorage", "The native credential store is unavailable or locked. Unlock it and retry."],
                         6: ["transport", "Brightspace authentication is temporarily unavailable because of a network or server failure. Your saved session was preserved. Try again later."],
+                        // The page never settled (BrowserAuthStuckError): Brightspace was
+                        // reachable, so this is not the network. runOnce retries it once.
+                        10: ["stuck", STUCK_MESSAGE],
                         // The MFA loop gave up (MfaApprovalError) and recorded the
                         // cooldown: the number it showed no longer works, so a caller
                         // still polling hears what the next call would, not "enter 42".
@@ -1187,7 +1208,10 @@ export class AuthRunner {
                     const [kind, message] = failures[code ?? -1] ?? ["failed", `Authentication failed. Run ${AUTH_COMMAND} to try again.`];
                     kill("SIGKILL");
                     const challenged = kind === "mfaPending" || kind === "automaticPending" || kind === "inProgress";
-                    finishChild(new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined, false, relayed && challenged));
+                    const failure = new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined, false, relayed && challenged);
+                    if (kind === "stuck" && !challengeSeen && !automaticSeen && !heldSeen && !relayed)
+                        retryableStuck.add(failure);
+                    finishChild(failure);
                 }
             });
         });

package/build/auth/browser-auth.js

@@ -18,6 +18,9 @@ import { launchWithBrowserRecovery } from "../utils/browser-install.js";
 import { signInCommand } from "../utils/commands.js";
 const SILENT_SSO_TIMEOUT_MS = 30000;
 const SILENT_SSO_POLL_MS = 1000;
+/** How long navigateAndLogin keeps looking for a challenge once silent SSO ends on a page it does not recognise. */
+const CHALLENGE_SETTLE_POLLS = 5;
+const LOAD_STATE_WAIT_MS = 2000;
 const INITIAL_NAVIGATION_TIMEOUT_MS = 60000;
 const VISIBLE_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
 const SILENT_SSO = {
@@ -50,6 +53,29 @@ export class BrowserAuthTransportError extends Error {
         this.name = "BrowserAuthTransportError";
     }
 }
+/**
+ * The school's sign-in page never settled on anything the sign-in can act on:
+ * Brightspace was reachable, the page just kept moving or showed something
+ * unrecognized. Still a BrowserAuthTransportError for existing callers, but
+ * its own code, so the user is told to call sign_in again rather than that the
+ * network is down.
+ */
+export class BrowserAuthStuckError extends BrowserAuthTransportError {
+    code = "AUTH_STUCK";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "BrowserAuthStuckError";
+    }
+}
+/**
+ * Playwright's errors for a page that navigated while it was being read. They
+ * are the normal state of a redirect chain, not a dead browser: the next poll
+ * reads the page that arrived.
+ */
+const NAVIGATION_RACE = /Execution context was destroyed|because of a navigation|Cannot find context with specified id|frame was detached/i;
+export function isNavigationRace(error) {
+    return error instanceof Error && NAVIGATION_RACE.test(error.message);
+}
 export class BrowserAuth {
     config;
     ssoFlow;
@@ -409,9 +435,22 @@ export class BrowserAuth {
             log("INFO", "Saved session is active");
             return true;
         }
-        const pendingMfa = await this.hasMfaChallenge(page);
-        const credentialPrompt = await this.hasCredentialPrompt(page);
+        let pendingMfa = await this.hasMfaChallenge(page);
+        let credentialPrompt = await this.hasCredentialPrompt(page);
         const hasCredentials = this.ssoFlow.hasCredentials();
+        // A page caught mid-redirect shows nothing yet; give it a few more seconds
+        // before calling it unsupported. Without credentials there is nothing to
+        // do with a challenge anyway, so that path does not wait.
+        for (let i = 0; hasCredentials && this.config.headless !== false && !pendingMfa && !credentialPrompt && i < CHALLENGE_SETTLE_POLLS; i++) {
+            // A closed browser is classified by the probe below, not by the wait.
+            await page.waitForTimeout(SILENT_SSO_POLL_MS).catch(() => { });
+            if (await this.hasLiveSession(page)) {
+                log("INFO", "Saved session is active");
+                return true;
+            }
+            pendingMfa = await this.hasMfaChallenge(page);
+            credentialPrompt = await this.hasCredentialPrompt(page);
+        }
         if (!hasCredentials && !pendingMfa) {
             if (this.config.headless === false) {
                 await this.waitForVisibleLogin(page);
@@ -424,7 +463,7 @@ export class BrowserAuth {
                 await this.waitForVisibleLogin(page);
                 return false;
             }
-            throw new BrowserAuthTransportError("The sign-in page has not settled on a supported login challenge. Retry shortly; saved state is preserved.", navigationError === undefined ? undefined : { cause: navigationError });
+            throw new BrowserAuthStuckError("The sign-in page has not settled on a supported login challenge. Retry shortly; saved state is preserved.", navigationError === undefined ? undefined : { cause: navigationError });
         }
         const loginStartedAt = Date.now();
         this.challengeSeenAt = undefined;
@@ -478,7 +517,10 @@ export class BrowserAuth {
         let accountHintAttempted = false;
         let passwordPromptPolls = 0;
         let passwordSwitchAttempted = false;
-        do {
+        // The poll that starts at or after the deadline is the last: it still looks
+        // for a challenge, so a password field first seen on it is acted on.
+        for (;;) {
+            const finalPoll = Date.now() >= deadline;
             if (await this.hasLiveSession(page))
                 return true;
             // Only a visible supported challenge justifies entering credentials or
@@ -520,7 +562,7 @@ export class BrowserAuth {
                 // Entra can briefly expose a password-shaped control while its email
                 // view initializes. Brightspace Bar polls the evolving page instead of
                 // concluding from that first transient snapshot.
-                if (passwordPromptPolls >= 2) {
+                if (passwordPromptPolls >= 2 || finalPoll) {
                     log("INFO", "The identity provider requires a login challenge");
                     return false;
                 }
@@ -528,6 +570,8 @@ export class BrowserAuth {
                 continue;
             }
             passwordPromptPolls = 0;
+            if (finalPoll)
+                break;
             try {
                 await this.clickSilentSurfaces(page);
                 await page.waitForTimeout(SILENT_SSO_POLL_MS);
@@ -535,12 +579,18 @@ export class BrowserAuth {
             catch (error) {
                 if (error instanceof BrowserAuthError || error instanceof BrowserAuthTransportError)
                     throw error;
+                // The page navigated under the click: read the page that arrived.
+                if (isNavigationRace(error)) {
+                    log("DEBUG", "The sign-in page navigated during a poll; polling again");
+                    await page.waitForTimeout(SILENT_SSO_POLL_MS).catch(() => { });
+                    continue;
+                }
                 throw new BrowserAuthTransportError("Silent sign-in could not reach the identity provider. Saved state is preserved.", { cause: error });
             }
-        } while (Date.now() < deadline);
+        }
         if (this.config.headless === false)
             return false;
-        throw new BrowserAuthTransportError("Silent sign-in did not reach Brightspace or a supported login challenge within 30 seconds. Retry shortly; saved state is preserved.");
+        throw new BrowserAuthStuckError("Silent sign-in did not reach Brightspace or a supported login challenge within 30 seconds. Retry shortly; saved state is preserved.");
     }
     async hasCredentialPrompt(page) {
         return await this.isAnyOnScreen(page, SILENT_SSO.emailFields) ||
@@ -572,6 +622,18 @@ export class BrowserAuth {
      * cookie and a reachable D2L JS context are required.
      */
     async hasLiveSession(page) {
+        // A page caught mid-navigation is read once more after the page that
+        // arrived has loaded: the check right after a sign-in has no next poll, so
+        // a race there would otherwise fail a login the user just approved.
+        for (let attempt = 1;; attempt++) {
+            const live = await this.readLiveSession(page);
+            if (live !== "raced")
+                return live;
+            if (attempt >= 2)
+                return false;
+        }
+    }
+    async readLiveSession(page) {
         try {
             const location = new URL(page.url());
             if (location.origin !== new URL(this.config.baseUrl).origin)
@@ -584,12 +646,18 @@ export class BrowserAuth {
             if (!cookies.some((c) => c.name === "d2lSessionVal" && Boolean(c.value))) {
                 return false;
             }
+            // An expired session answers /d2l/home with a stub that redirects to the
+            // login page while already carrying the cookie; read it once it loads.
+            await page.waitForLoadState("domcontentloaded", { timeout: LOAD_STATE_WAIT_MS }).catch(() => { });
             return await page.evaluate(() => {
                 const d2l = window.D2L;
                 return d2l !== undefined && Boolean(d2l.LP);
             });
         }
         catch (error) {
+            // Mid-navigation is "not live yet", not a dead browser.
+            if (isNavigationRace(error))
+                return "raced";
             throw new BrowserAuthTransportError("The browser could not verify the saved Brightspace session. Saved state is preserved.", { cause: error });
         }
     }
@@ -644,6 +712,8 @@ export class BrowserAuth {
             return await page.locator(selector).first().isVisible();
         }
         catch (error) {
+            if (isNavigationRace(error))
+                return false;
             throw new BrowserAuthTransportError("The browser could not inspect the sign-in page. Saved state is preserved.", { cause: error });
         }
     }

package/build/auth/error-cause.js

@@ -0,0 +1,38 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT: see LICENSE file for details.
+ */
+const MAX_CAUSES = 4;
+const MAX_LINE = 200;
+/**
+ * One safe line per link of an error's `cause` chain, outermost first, so a
+ * failure reported as a wrapper ("could not verify the session") also logs
+ * what actually broke. Only the first line of each message is kept, any URL
+ * is cut to its origin (query strings and paths can carry tokens), and the
+ * line is length-capped. The top error itself is not included.
+ */
+export function causeSummaries(error) {
+    const lines = [];
+    const seen = new Set([error]);
+    let current = error?.cause;
+    while (current !== undefined && current !== null && lines.length < MAX_CAUSES && !seen.has(current)) {
+        seen.add(current);
+        const raw = current instanceof Error ? current.message : typeof current === "string" ? current : "";
+        const name = current instanceof Error && current.name !== "Error" ? `${current.name}: ` : "";
+        const firstLine = raw.split(/\r?\n/, 1)[0] ?? "";
+        const safe = `${name}${firstLine}`
+            .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s/?#)'"]+[^\s)'"]*/gi, (url) => {
+            try {
+                return new URL(url).origin;
+            }
+            catch {
+                return "[url]";
+            }
+        })
+            .slice(0, MAX_LINE);
+        lines.push(safe || "(no message)");
+        current = current.cause;
+    }
+    return lines;
+}

package/build/auth-cli.js

@@ -8,7 +8,6 @@ import dotenv from "dotenv";
 import { loadConfig } from "./utils/config.js";
 import { BrowserAuth, TokenManager } from "./auth/index.js";
 import { MfaApprovalError } from "./auth/sso-flow.js";
-import { NativeCredentialStoreError } from "./auth/credential-store.js";
 import { retireLegacyProfile } from "./auth/legacy-profile.js";
 import { formatPhaseMarker } from "./auth/auth-phases.js";
 import { AuthenticationInProgressError } from "./auth/auth-lock.js";
@@ -20,6 +19,8 @@ import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
 import { reexecLatestIfStale } from "./utils/self-update.js";
 import { detectSkew } from "./utils/install-sites.js";
 import { BrowserInstallError } from "./utils/browser-install.js";
+import { causeSummaries } from "./auth/error-cause.js";
+import { authExitCode } from "./auth/auth-exit-code.js";
 dotenv.config({ quiet: true });
 const pkg = JSON.parse(readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
 async function requestMfaCode() {
@@ -104,7 +105,6 @@ async function main() {
         console.error("\nAuthentication successful. Your encrypted session is ready for the MCP server.");
     }
     catch (error) {
-        const code = error?.code;
         // A pending number-match approval gets its own exit code so the caller
         // can tell "still waiting on the phone" apart from a hard failure, and
         // its own stdout marker so the digits — already validated to 1-3 digits
@@ -122,14 +122,10 @@ async function main() {
             for (const line of relayedLockLines(error.challenge, error.ownerMode))
                 console.log(line);
         }
-        process.exitCode = error instanceof BrowserInstallError ? (error.dependencyMissing ? 9 : 8)
-            : error instanceof NativeCredentialStoreError ? 5
-                : code === "AUTH_IN_PROGRESS" ? 2
-                    : code === "AUTH_COOLDOWN" ? 3
-                        : code === "AUTH_UNSUPPORTED" ? 4
-                            : code === "AUTH_TRANSPORT" ? 6
-                                : error instanceof MfaApprovalError ? 7 : 1;
+        process.exitCode = authExitCode(error);
         console.error("\nAuthentication failed:", error instanceof Error ? error.message : "Unknown authentication error");
+        for (const cause of causeSummaries(error))
+            console.error(`  caused by: ${cause}`);
         if (!(error instanceof BrowserInstallError)) {
             console.error(`Run \`${SETUP_COMMAND}\` to update saved credentials.`);
             console.error(`Run \`${AUTH_COMMAND}\` to retry explicitly. This bypasses the automatic MFA cooldown.`);

package/build/tools/schemas.js

@@ -164,7 +164,7 @@ export const GetServerInfoSchema = z.object({});
 export const SignOutSchema = z.object({});
 export const SignInSchema = z.object({
     visible: z.boolean().optional()
-        .describe("Open a browser window for the user to sign in by hand. Omit to decide automatically: a window opens only when no password is saved on this computer, because a sign-in with no window has nothing to type into the school's form and would only time out. Pass true when a background sign-in has already failed or the school's page needs a step it cannot do, false to insist on a background sign-in."),
+        .describe("Open a browser window for the user to sign in by hand. Omit it: a window then opens by itself only when no password is saved on this computer, because a sign-in with no window has nothing to type into the school's form and would only time out. Pass true ONLY when the user asks for a window, or an error says a step needs the user's own hands (an unsupported sign-in, or no saved password). Do NOT pass true after a \"could not be reached\", stuck, or timeout failure: just call sign_in again, because the saved password is typed in the background and a window adds nothing. Pass false to insist on a background sign-in."),
 });
 // ── Instructor / TA dropbox tools ──────────────────────────────────────────
 // Read-only, instructor/TA-side views of a course's dropbox (assignment)

package/build/tools/sign-in.js

@@ -14,7 +14,10 @@ const ENV_CREDENTIAL = "Nothing to do. This server authenticates with a credenti
 const NO_RUNNER = `This server cannot start a sign-in itself. Tell the user to run \`${AUTH_COMMAND}\` in a terminal, prefixed with D2L_HEADLESS=false if they need to see the sign-in page and finish it by hand.`;
 const SUCCESS = "Signed in to Brightspace. The session is saved on this computer, so other Brightspace apps here can use it too.";
 /** What an open window means for the caller: this one waits on a person, not on a retry. */
-const WINDOW_OPEN = "A browser window is opening on the user's screen for them to sign in by hand. Tell the user to complete it, including any 2FA, then ask them to say when they are done.";
+const WINDOW_FINISH = "Tell the user to complete it, including any 2FA, then ask them to say when they are done.";
+const WINDOW_ASKED = `A browser window is opening on the user's screen because a window was requested. ${WINDOW_FINISH}`;
+const WINDOW_NO_PASSWORD = `A browser window is opening on the user's screen because no password is saved on this computer, so the user has to type it themselves. ${WINDOW_FINISH}`;
+const WINDOW_JOINED = "No window was opened: a sign-in was already running, and this call joined it.";
 const NEEDS_PASSWORD_FOR_HEADLESS = `No password is saved on this computer, so a sign-in with no window has nothing to type into the school's form and would only wait and time out. Either call sign_in again with visible true, or tell the user to run \`${SETUP_COMMAND}\` to save one.`;
 /**
  * A sign-in still working is progress, not a failure, so these are not marked
@@ -58,7 +61,7 @@ export function registerSignIn(server, config, tokenManager, authRunner) {
     server.registerTool("sign_in", {
         title: "Sign In to Brightspace",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-        description: "Sign in to Brightspace on this computer so the other tools work. Does nothing and says so if the saved session is already valid, so it is safe to call first when you are unsure. Opens a browser window for the user to sign in by hand when no password is saved (nothing to type means a windowless sign-in can only time out); otherwise it signs in in the background and reports the 2FA number for the user to approve on their phone. Call this when a Brightspace tool failed because of authentication, or when the user asks to sign in or log in to Brightspace. Every answer says what to do next, including whether to call again.",
+        description: "Sign in to Brightspace on this computer so the other tools work. Does nothing and says so if the saved session is already valid, so it is safe to call first when you are unsure. Opens a browser window for the user to sign in by hand when no password is saved (nothing to type means a windowless sign-in can only time out); otherwise it signs in in the background and reports the 2FA number for the user to approve on their phone. A window is for the user's own hands only (no saved password, or when the user asks to see one): after a \"could not be reached\", stuck, or timeout answer, call sign_in again without visible. Call this when a Brightspace tool failed because of authentication, or when the user asks to sign in or log in to Brightspace. Every answer says what to do next, including whether to call again.",
         inputSchema: SignInSchema,
     }, async ({ visible }) => {
         if (config.envAccessToken || config.envSessionCookie)
@@ -98,7 +101,8 @@ export function registerSignIn(server, config, tokenManager, authRunner) {
         catch (error) {
             if (error instanceof AuthProcessError) {
                 const guidance = authPendingNotice(error);
-                return text(windowOpened ? `${WINDOW_OPEN} ${guidance}` : guidance, !STILL_WORKING.has(error.kind));
+                return text(windowOpened ? `${visible === true ? WINDOW_ASKED : WINDOW_NO_PASSWORD} ${guidance}`
+                    : wantWindow ? `${WINDOW_JOINED} ${guidance}` : guidance, !STILL_WORKING.has(error.kind));
             }
             // Everything else goes through the house path, which logs it and
             // keeps stack traces and raw responses out of the answer.

package/build/tools/tool-helpers.js

@@ -139,9 +139,13 @@ const AUTH_FAILURE_GUIDANCE = {
     secureStorage: "The operating system credential store is locked or unavailable, so the saved " +
         "password could not be read. Unlock your keychain or keyring, then try again.",
     transport: "Brightspace could not be reached to sign in. The saved session was kept. " +
-        "Check your connection and try again in a few minutes.",
+        "Call sign_in once more without visible; forcing a browser window does not help. " +
+        "If it fails again, ask the user to check their connection and try again in a few minutes.",
+    stuck: "Sign-in got stuck on the school's sign-in page and stopped; the saved session was kept. " +
+        "Call sign_in again — no window is needed.",
     timeout: "The sign-in did not finish in time, usually a missed MFA prompt, and has stopped: the prompt it " +
         "sent no longer works. The next call starts a new sign-in, or says automatic sign-in is paused. " +
+        "Don't open a window to retry; a window does not skip the prompt. " +
         `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to complete it with the number visible.`,
     failed: `The sign-in did not complete. Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to see why, ` +
         "or `brightspace-setup` if your saved school or username is wrong.",

package/build/utils/dev-activity.js

@@ -103,7 +103,7 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
     if (["success", "error", "sessionExpired", "transport"].includes(fields.outcome ?? ""))
         record.outcome = fields.outcome;
     if (["busy", "cooldown", "unsupported", "secureStorage", "transport", "timeout", "failed", "mfaPending",
-        "automaticPending", "inProgress", "mfaHeld"].includes(fields.reason ?? ""))
+        "automaticPending", "inProgress", "mfaHeld", "stuck"].includes(fields.reason ?? ""))
         record.reason = fields.reason;
     if (AUTH_PHASES.includes(fields.phase ?? ""))
         record.phase = fields.phase;

package/package.json

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