brightspace-mcp-server 3.9.26 → 3.10.0

package/README.md

@@ -104,7 +104,7 @@ All optional, set in your AI app's MCP `env` config or your shell. The full list
 
 ## When it asks you to sign in
 
-There's no separate login — asking a question signs you in, and it stays signed in on its own most days. When your school wants two-factor again, the number to approve shows up right in the answer; approve it on your phone and ask again. If it ever gets stuck, run this in a terminal:
+There's no separate login — asking a question signs you in, and it stays signed in on its own most days. When your school wants two-factor again, the number to approve shows up right in the answer; approve it on your phone and ask again. If your AI client shows tool progress messages, the number appears while the question is still running instead, and approving within 45 seconds (less if sign-in was slow to reach two-factor) finishes the original answer without asking again. If it ever gets stuck, run this in a terminal:
 
 ```bash
 npx -y brightspace-mcp-server@latest auth

package/build/auth/auth-runner.js

@@ -28,6 +28,25 @@ const KILL_GRACE_MS = 5000;
  * approval window.
  */
 const JOIN_GRACE_MS = 5000;
+/**
+ * How long a caller that can be told the challenge mid-call (see run()'s
+ * onChallenge) keeps waiting for the background sign-in after the challenge
+ * appears: long enough to find a phone and approve.
+ */
+const MFA_POLL_MS = 45000;
+/**
+ * The latest a polling caller is answered, counted from when it called run().
+ * Browser launch and the SSO pages can take half a minute before the
+ * challenge even appears, so the poll is cut short to fit this budget. It
+ * stays under the 60-second request timeout MCP clients commonly apply, so a
+ * client that never shows the mid-call notice still gets the number in the
+ * answer.
+ */
+const CALL_BUDGET_MS = 55000;
+/** How long to poll after a challenge seen elapsedMs into the call. */
+function pollWindowMs(elapsedMs) {
+    return Math.min(MFA_POLL_MS, CALL_BUDGET_MS - elapsedMs);
+}
 /**
  * The only two lines auth-cli.ts is allowed to hand back as structured data.
  * Deliberately strict (whole line, 1-3 digits or the literal word) so this
@@ -161,8 +180,35 @@ export class AuthRunner {
     /**
      * Authenticate, joining the login this process already started if there is
      * one. Returns true on success and throws a useful error on failure.
+     *
+     * Without onChallenge, an MFA challenge answers the caller at once with an
+     * mfaPending error. With it, the caller is handed the challenge (the
+     * number to enter, if any) and keeps waiting on the background sign-in for
+     * up to MFA_POLL_MS, and never past CALL_BUDGET_MS from the call, so an
+     * approval within that window completes the caller's original request;
+     * past it, the caller gets the same mfaPending answer it would have had up
+     * front.
      */
-    async run() {
+    async run(onChallenge) {
+        const startedAt = Date.now();
+        try {
+            return await this.runOnce();
+        }
+        catch (error) {
+            const childDone = this.childDone;
+            if (!onChallenge || !childDone || !(error instanceof AuthProcessError) || error.kind !== "mfaPending")
+                throw error;
+            const windowMs = pollWindowMs(Date.now() - startedAt);
+            if (windowMs <= 0)
+                throw error;
+            try {
+                onChallenge(error.numberMatch);
+            }
+            catch { /* Announcing must not interrupt authentication. */ }
+            return this.awaitBackgroundChild(childDone, windowMs);
+        }
+    }
+    runOnce() {
         if (this.inFlight) {
             log("DEBUG", "Joining the authentication already in flight");
             return this.inFlight;
@@ -204,17 +250,26 @@ export class AuthRunner {
         if (!this.pendingChallenge && this.challengeSignal) {
             await Promise.race([childDone.catch(() => { }), this.challengeSignal]);
         }
-        const challenge = this.pendingChallenge;
-        if (!challenge)
+        if (!this.pendingChallenge)
             return childDone;
+        return this.awaitBackgroundChild(childDone, JOIN_GRACE_MS);
+    }
+    /**
+     * Race a background child already past its MFA challenge against a wait
+     * of graceMs. The child's own outcome wins if it lands in time; otherwise
+     * the caller is re-answered with the latest challenge the child reported.
+     */
+    awaitBackgroundChild(childDone, graceMs) {
+        const challenge = this.pendingChallenge;
         return new Promise((resolve, reject) => {
             let settled = false;
             const graceTimer = setTimeout(() => {
                 if (settled)
                     return;
                 settled = true;
-                reject(new AuthProcessError(...mfaPendingFailure(challenge.numberMatch), challenge.numberMatch));
-            }, JOIN_GRACE_MS);
+                const numberMatch = this.pendingChallenge?.numberMatch ?? challenge?.numberMatch;
+                reject(new AuthProcessError(...mfaPendingFailure(numberMatch), numberMatch));
+            }, graceMs);
             graceTimer.unref?.();
             childDone.then((value) => {
                 if (settled)

package/build/index.js

@@ -16,7 +16,7 @@ import { startUpdateChecks } from "./utils/update-checker.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -92,7 +92,7 @@ else {
             const apiClient = new D2LApiClient({
                 baseUrl: config.baseUrl,
                 tokenManager,
-                onAuthExpired: authRunner ? () => authRunner.run() : undefined,
+                onAuthExpired: authRunner ? () => authRunner.run(currentMfaAnnouncer()) : undefined,
                 authExpiredMessage: config.envAccessToken
                     ? "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set."
                     : config.envSessionCookie
@@ -118,7 +118,10 @@ else {
                     activeOnly: config.courseFilter.activeOnly,
                 });
             }
-            // Register MCP tools
+            // Register MCP tools. Each one, when its client sends a progress token,
+            // shows an MFA challenge mid-call and waits for the approval instead of
+            // asking to be called again (see relayMfaChallenges).
+            relayMfaChallenges(server);
             registerGetMyCourses(server, apiClient, config);
             registerGetUpcomingDueDates(server, apiClient, config);
             registerGetCalendarEvents(server, apiClient, config);

package/build/tools/index.js

@@ -32,4 +32,5 @@ export { registerGetRubricsForObject } from "./get-rubrics-for-object.js";
 export { registerDownloadDropboxSubmissionFile } from "./download-dropbox-submission-file.js";
 // Re-export shared helpers and schemas for convenience
 export { toolResponse, errorResponse, sanitizeError } from "./tool-helpers.js";
+export { relayMfaChallenges, currentMfaAnnouncer } from "./mfa-relay.js";
 export * from "./schemas.js";

package/build/tools/mfa-relay.js

@@ -0,0 +1,54 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const announcers = new AsyncLocalStorage();
+/**
+ * The announcer for the tool call currently running, if its client can be
+ * told about an MFA challenge before the call returns. The API client's
+ * re-auth hook hands this to AuthRunner.run(), which then keeps the call
+ * waiting on the sign-in instead of answering "call this tool again".
+ */
+export function currentMfaAnnouncer() {
+    return announcers.getStore();
+}
+/**
+ * The text of the mid-call notice. numberMatch is the 1-3 digit value
+ * AuthRunner parsed from a strictly matched marker, never free child output.
+ */
+function challengeNotice(numberMatch) {
+    const step = numberMatch
+        ? `Open Microsoft Authenticator and enter ${numberMatch} within 5 minutes.`
+        : "Approve the sign-in request on your phone (Microsoft Authenticator or Duo).";
+    return `${step} Waiting for the sign-in to finish…`;
+}
+/**
+ * Make every tool registered on this server from here on announce MFA
+ * challenges mid-call.
+ *
+ * A client that sends a progress token with tools/call can show progress
+ * messages while the call is still open, so the challenge goes out as a
+ * progress notification on that call. A client that sends none gets no
+ * announcer, and its calls keep answering the moment a challenge appears.
+ */
+export function relayMfaChallenges(server) {
+    const register = server.registerTool.bind(server);
+    server.registerTool = ((name, config, callback) => register(name, config, ((...args) => {
+        // The request context is always the handler's last argument.
+        const extra = args[args.length - 1];
+        const progressToken = extra?._meta?.progressToken;
+        let progress = 0;
+        const announce = progressToken === undefined
+            ? undefined
+            : (numberMatch) => {
+                progress += 1;
+                void extra.sendNotification({
+                    method: "notifications/progress",
+                    params: { progressToken, progress, message: challengeNotice(numberMatch) },
+                }).catch(() => { });
+            };
+        return announcers.run(announce, () => callback(...args));
+    })));
+}

package/package.json

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