brightspace-mcp-server 3.4.0 → 3.5.0

package/README.md

@@ -101,7 +101,9 @@ If you miss an MFA request, automatic browser authentication pauses for five min
 npx -y brightspace-mcp-server@latest auth
 ```
 
-**MFA at Purdue** commonly uses Microsoft Authenticator number matching: enter the terminal-displayed number on your phone. Google Authenticator and other one-time-code apps work too, with no setting to change: run the auth command above in a terminal and it prompts for the code when your provider asks for one. Pick the visible-browser option during setup only if your identity provider needs interaction the server cannot drive. The MCP also sends authentication progress as logging notifications to clients that display them. Some desktop clients hide server logs, so use the terminal command above for interactive MFA.
+Run it from your home folder. On macOS, a terminal that lacks Files and Folders permission (the terminal panel inside Claude Desktop, or a fresh editor terminal) cannot start `npx` from inside Documents, Desktop, or Downloads — it fails with `EPERM: process.cwd failed … uv_cwd` before the server runs. The same applies if your AI client launches the server with one of those folders as its working directory; grant the app access under System Settings → Privacy & Security → Files and Folders, or start the server elsewhere.
+
+**MFA at Purdue** commonly uses Microsoft Authenticator number matching (some schools use Duo instead). When a sign-in needs it, the tool call itself returns quickly with the number to enter, rather than sitting silent for up to five minutes — approve it on your phone, then call the tool again; sign-in finishes in the background in the meantime. Google Authenticator and other one-time-code apps work too, with no setting to change: run the auth command above in a terminal and it prompts for the code when your provider asks for one. Pick the visible-browser option during setup only if your identity provider needs interaction the server cannot drive. The MCP also sends authentication progress as logging notifications to clients that display them, useful if you don't see the number in the tool response for some reason.
 
 ## What You Can Ask About
 

package/build/api/cache.js

@@ -22,12 +22,25 @@ export class TTLCache {
             timerId.unref();
         }
         // Store entry
-        this.cache.set(key, { data: value, timerId });
+        this.cache.set(key, { data: value, timerId, storedAt: Date.now() });
     }
     get(key) {
         const entry = this.cache.get(key);
         return entry?.data;
     }
+    /**
+     * How long ago this key was written, in milliseconds, or undefined when it
+     * is not cached.
+     *
+     * One key can be written under several TTLs: two tools ask for the same
+     * path with different freshness requirements. An entry another caller kept
+     * alive for an hour is still too old for a caller that asked for ten
+     * minutes, and only its age can say so.
+     */
+    ageOf(key) {
+        const entry = this.cache.get(key);
+        return entry ? Date.now() - entry.storedAt : undefined;
+    }
     has(key) {
         return this.cache.has(key);
     }

package/build/api/client.js

@@ -103,9 +103,12 @@ export class D2LApiClient {
         this.cacheTTLs = { ...DEFAULT_CACHE_TTLS, ...options.cacheTTLs };
         // Initialize cache and rate limiter
         this.cache = new TTLCache();
+        // Sized for the per-course fan-out the tools do (a dozen courses is ~60
+        // requests); at 3/s that took ~17 s once the limiter actually reserved
+        // tokens. Brightspace 429s are still retried with Retry-After.
         const rateLimitConfig = options.rateLimitConfig ?? {
-            capacity: 10,
-            refillRate: 3,
+            capacity: 20,
+            refillRate: 8,
         };
         this.rateLimiter = new TokenBucket(rateLimitConfig.capacity, rateLimitConfig.refillRate);
         log("DEBUG", `D2LApiClient initialized for ${this.baseUrl}`);
@@ -183,9 +186,18 @@ export class D2LApiClient {
     async get(path, options) {
         // Checked before the path is resolved, and keyed by the path as the caller
         // wrote it, so a cached read needs neither version discovery nor a token.
-        if (options?.ttl && this.cache.has(path)) {
-            log("DEBUG", `Cache hit: ${path}`);
-            return this.cache.get(path);
+        //
+        // The entry has to be younger than this caller's own TTL, not merely
+        // still alive. One path can be written under two TTLs: the discussion
+        // forum list is thirty minutes of course content to get_discussions and
+        // ten minutes of due dates to get_upcoming_due_dates. Trusting the
+        // surviving entry served the longer caller's staleness to the shorter one.
+        if (options?.ttl) {
+            const age = this.cache.ageOf(path);
+            if (age !== undefined && age <= options.ttl) {
+                log("DEBUG", `Cache hit: ${path}`);
+                return this.cache.get(path);
+            }
         }
         const resolved = await this.resolvePath(path);
         const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token));

package/build/api/rate-limiter.js

@@ -3,8 +3,8 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
-// Token bucket rate limiter - allows bursts up to capacity
-// Conservative defaults: capacity 10, refill 3/sec
+// Token bucket rate limiter - allows bursts up to capacity.
+// Defaults live in D2LApiClient (client.ts).
 export class TokenBucket {
     tokens;
     lastRefill;
@@ -25,21 +25,30 @@ export class TokenBucket {
         this.tokens = Math.min(this.capacity, this.tokens + tokensToAdd);
         this.lastRefill = now;
     }
+    /**
+     * Take `count` tokens, waiting for them if the bucket is short.
+     *
+     * The tokens are deducted before the wait rather than after it, so
+     * concurrent callers queue behind one another. Deducting afterwards let
+     * every caller read the same empty bucket, wait for the same single token,
+     * and then wake together and take it: a fan-out across courses drained the
+     * burst and then admitted the whole remainder one refill later, which is the
+     * 429 storm this limiter exists to prevent. It also left the balance deeply
+     * negative, so the next unrelated request paid the whole debt in one wait.
+     *
+     * A negative balance is that debt, owed by the waiters already queued, and
+     * refill() pays it down at the refill rate.
+     */
     async consume(count = 1) {
         this.refill();
-        if (this.tokens >= count) {
-            // Enough tokens available - consume immediately
-            this.tokens -= count;
+        const shortfall = count - this.tokens;
+        this.tokens -= count;
+        if (shortfall <= 0) {
+            // Enough tokens were already banked - proceed immediately.
             return;
         }
-        // Not enough tokens - calculate wait time
-        const tokensNeeded = count - this.tokens;
-        const waitTimeMs = (tokensNeeded / this.refillRate) * 1000;
-        // Wait for tokens to refill
+        const waitTimeMs = (shortfall / this.refillRate) * 1000;
         await new Promise((resolve) => setTimeout(resolve, waitTimeMs));
-        // Refill and consume
-        this.refill();
-        this.tokens -= count;
     }
     tryConsume(count = 1) {
         this.refill();
@@ -49,8 +58,10 @@ export class TokenBucket {
         }
         return false;
     }
+    /** Tokens free to take right now. Never negative: an outstanding
+     * reservation is a debt, not a negative supply. */
     get availableTokens() {
         this.refill();
-        return this.tokens;
+        return Math.max(0, this.tokens);
     }
 }

package/build/auth/auth-cooldown.js

@@ -19,11 +19,25 @@ export class AuthenticationCooldownError extends Error {
         // stalled chat window nothing they can act on.
         const minutes = Math.max(1, Math.ceil((retryAt - Date.now()) / 60000));
         super(`The last sign-in prompt was not approved, so automatic sign-in is paused for ${minutes} more minute${minutes === 1 ? "" : "s"}. ` +
-            `To sign in right now, run this in a terminal: ${AUTH_COMMAND}`);
+            `To sign in right now, run this in a terminal from your home folder: ${AUTH_COMMAND}`);
         this.retryAt = retryAt;
         this.name = "AuthenticationCooldownError";
     }
 }
+/** The recorded retry time, or undefined when the file says nothing usable. */
+function readRetryAt(content) {
+    let status;
+    try {
+        status = JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof status !== "object" || status === null || Array.isArray(status))
+        return undefined;
+    const retryAt = status.retryAt;
+    return typeof retryAt === "number" && Number.isFinite(retryAt) ? retryAt : undefined;
+}
 /** Non-secret retry metadata. Call only while holding the authentication lock. */
 export class AuthCooldown {
     file;
@@ -40,9 +54,19 @@ export class AuthCooldown {
                 return;
             throw error;
         }
-        const status = JSON.parse(content);
-        if (typeof status.retryAt === "number" && status.retryAt > Date.now())
-            throw new AuthenticationCooldownError(status.retryAt);
+        const retryAt = readRetryAt(content);
+        if (retryAt === undefined) {
+            // This file is non-secret retry metadata, and only a readable retryAt is
+            // evidence of anything. A truncated or non-object file used to throw out
+            // of here, which runs before the sign-in attempt — and the automatic path
+            // only clears the file after a sign-in that then never started. One
+            // damaged file disabled background sign-in for good, with nothing on
+            // screen naming the cause. Discard it and let this attempt proceed.
+            await fs.unlink(this.file).catch(() => { });
+            return;
+        }
+        if (retryAt > Date.now())
+            throw new AuthenticationCooldownError(retryAt);
     }
     async recordMfaFailure() {
         await this.write({ retryAt: Date.now() + MFA_COOLDOWN_MS });

package/build/auth/auth-runner.js

@@ -13,17 +13,36 @@ import { AUTH_COMMAND } from "../utils/commands.js";
  * Timeout for the auth process. It has to outlast the child's own MFA wait,
  * which is five minutes: a person has to find their phone, unlock it, and read
  * a number off the screen. A shorter parent budget would kill the child in the
- * middle of a sign-in the user was still completing.
+ * middle of a sign-in the user was still completing. run() itself usually
+ * returns long before this fires — the moment the child reports an MFA
+ * challenge — but this timer keeps bounding the background child regardless.
  */
 const AUTH_TIMEOUT_MS = 8 * 60 * 1000;
 const KILL_GRACE_MS = 5000;
 /**
- * The only line auth-cli.ts is allowed to hand back as structured data.
- * Deliberately strict (1-3 digits, whole line) so this can never become a
- * channel for arbitrary child-process text to reach a tool response —
- * anything that doesn't match this exactly is just another log line.
+ * How long a caller that joins a background child already reported as
+ * mfaPending waits for it before re-answering with the same challenge.
+ * Long enough for an already-approved login to finish its next ~2s poll and
+ * mint a token; short enough that a not-yet-approved one still answers
+ * within this tool call instead of blocking for the rest of the 5-minute
+ * approval window.
+ */
+const JOIN_GRACE_MS = 5000;
+/**
+ * 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
+ * can never become a channel for arbitrary child-process text to reach a
+ * tool response — anything that doesn't match exactly is just another log
+ * line.
  */
 const MFA_NUMBER_MARKER = /^MFA_NUMBER:(\d{1,3})$/;
+const MFA_PENDING_MARKER = /^MFA_PENDING$/;
+/** The mfaPending kind and message, with or without number-match digits. */
+function mfaPendingFailure(numberMatch) {
+    return numberMatch
+        ? ["mfaPending", `Open Microsoft Authenticator and enter ${numberMatch} within 5 minutes, then try again.`]
+        : ["mfaPending", "An MFA approval was not completed in time. Try again."];
+}
 export class AuthProcessError extends AuthError {
     kind;
     numberMatch;
@@ -93,6 +112,12 @@ function forwardLines(stream, emit) {
  *
  * The child inherits the parent's resolved environment and working directory,
  * so both processes read the same account configuration and .env file.
+ *
+ * run() settles as soon as the child reports an MFA challenge (with or
+ * without a number to display) rather than waiting for the child to exit —
+ * a tool call must not block for the whole approval window. The child keeps
+ * running in the background; a later run() call joins that background child
+ * instead of spawning a second one.
  */
 export class AuthRunner {
     /**
@@ -106,6 +131,22 @@ export class AuthRunner {
      * caller await the same login and read the same outcome.
      */
     inFlight = null;
+    /**
+     * The child from a login that answered its caller early (an MFA challenge
+     * was reported) and is still running in the background. Set for the
+     * duration of every spawned child, not just the early-answer case, so a
+     * caller who joins after the answer already exists resolves immediately.
+     */
+    childDone = null;
+    /**
+     * The last MFA challenge the current background child reported, if any.
+     * Set the moment a marker settles a caller early, cleared alongside
+     * childDone. Lets a later joiner re-answer immediately instead of
+     * discovering the challenge is stale only after blocking on childDone.
+     */
+    pendingChallenge = null;
+    /** Resolves on the next marker from the current child; null between children. */
+    challengeSignal = null;
     scriptPath;
     timeoutMs;
     onProgress;
@@ -125,6 +166,14 @@ export class AuthRunner {
             log("DEBUG", "Joining the authentication already in flight");
             return this.inFlight;
         }
+        // A caller that answered early is gone, but its child can still be
+        // running in the background (waiting on the user's phone). Join it
+        // instead of spawning a second child, which would only hit the
+        // cross-process lock and return "busy".
+        if (this.childDone) {
+            log("DEBUG", "Joining the background sign-in still running from an earlier call");
+            return this.joinBackgroundChild(this.childDone);
+        }
         // The latch is released by the flow that owns it, as it settles, so a
         // failed login is never replayed: the tool call after a declined MFA
         // prompt starts a fresh attempt rather than inheriting the stale
@@ -137,7 +186,55 @@ export class AuthRunner {
         this.inFlight = flow;
         return flow;
     }
-    /** One child process, start to finish. */
+    /**
+     * Join a background child from an earlier early-answered call instead of
+     * spawning a new one. A joiner must not simply await childDone: that
+     * blocks for whatever is left of the 5-minute approval window, exactly the
+     * problem run() otherwise fixes, since the caller usually retries right
+     * after reading "call this tool again" and well before actually approving.
+     *
+     * If no challenge has been reported yet (the child hasn't reached MFA),
+     * wait for one — or for the child to finish on its own. Once a challenge
+     * is known, race the child against a short grace window: fast enough for
+     * an already-approved login to land, short enough to re-answer with the
+     * same challenge rather than block.
+     */
+    async joinBackgroundChild(childDone) {
+        if (!this.pendingChallenge && this.challengeSignal) {
+            await Promise.race([childDone.catch(() => { }), this.challengeSignal]);
+        }
+        const challenge = this.pendingChallenge;
+        if (!challenge)
+            return childDone;
+        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);
+            graceTimer.unref?.();
+            childDone.then((value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(graceTimer);
+                resolve(value);
+            }, (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(graceTimer);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * One child process, start to finish. The returned promise can settle
+     * before the child actually exits (see the stdout handler below); the
+     * child's real completion is tracked separately on this.childDone.
+     */
     async spawnAuth() {
         log("INFO", "Auto-launching brightspace-auth...");
         return await new Promise((resolve, reject) => {
@@ -149,7 +246,14 @@ export class AuthRunner {
                 detached: process.platform !== "win32",
             });
             let timedOut = false;
-            let settled = false;
+            // Whether the caller-facing promise above (resolve/reject) has
+            // settled. Distinct from childFinished: an early MFA answer settles
+            // this while the child keeps running.
+            let callerSettled = false;
+            // Whether the child has actually finished (exited, timed out, or
+            // failed to start) and teardown has run. Guards every handler below
+            // against double cleanup.
+            let childFinished = false;
             let numberMatch;
             let killTimer;
             const kill = (signal) => {
@@ -182,25 +286,83 @@ export class AuthRunner {
             };
             const onExit = () => kill("SIGTERM");
             process.once("exit", onExit);
-            const finish = (error) => {
-                if (settled)
+            const settleCaller = (error) => {
+                if (callerSettled)
                     return;
-                settled = true;
+                callerSettled = true;
+                if (error)
+                    reject(error);
+                else
+                    resolve(true);
+            };
+            // Tracks the child to its real end, independent of an early caller
+            // answer. Exposed as this.childDone so the next run() call can join
+            // it. A dummy catch keeps an unapproved background failure from
+            // becoming an unhandled rejection when nobody ever joins it; it does
+            // not stop a later `await this.childDone` from seeing the rejection.
+            let resolveChildDone;
+            let rejectChildDone;
+            const completion = new Promise((res, rej) => {
+                resolveChildDone = res;
+                rejectChildDone = rej;
+            });
+            const trackedCompletion = completion.finally(() => {
+                if (this.childDone === trackedCompletion) {
+                    this.childDone = null;
+                    this.pendingChallenge = null;
+                    this.challengeSignal = null;
+                }
+            });
+            trackedCompletion.catch(() => { });
+            this.childDone = trackedCompletion;
+            this.pendingChallenge = null;
+            let resolveChallengeSignal;
+            this.challengeSignal = new Promise((res) => { resolveChallengeSignal = res; });
+            // Records the challenge (number or not) and wakes a joiner waiting in
+            // joinBackgroundChild. Idempotent on the "already known" question, but
+            // a later number still overwrites a numberless pendingChallenge so a
+            // fresh joiner sees it — see MFA_PENDING_MARKER's own comment.
+            const publishChallenge = (matched) => {
+                const firstChallenge = this.pendingChallenge === null;
+                if (firstChallenge || matched) {
+                    this.pendingChallenge = { numberMatch: matched ?? this.pendingChallenge?.numberMatch };
+                }
+                if (firstChallenge)
+                    resolveChallengeSignal();
+                if (!callerSettled) {
+                    settleCaller(new AuthProcessError(...mfaPendingFailure(this.pendingChallenge?.numberMatch), this.pendingChallenge?.numberMatch));
+                }
+            };
+            // Runs once the child is actually done. Settles the caller too, if an
+            // early answer had not already done so; otherwise this is just the
+            // background sign-in finishing, which only childDone's joiner sees.
+            const finishChild = (error) => {
+                if (childFinished)
+                    return;
+                childFinished = true;
                 clearTimeout(timer);
                 if (killTimer)
                     clearTimeout(killTimer);
                 process.off("exit", onExit);
+                const answeredEarly = callerSettled;
+                settleCaller(error);
+                if (answeredEarly) {
+                    if (error)
+                        log("WARN", `Background sign-in finished with ${error.kind}: ${error.message}`);
+                    else
+                        log("INFO", "Background sign-in completed successfully after an early MFA response");
+                }
                 if (error)
-                    reject(error);
+                    rejectChildDone(error);
                 else
-                    resolve(true);
+                    resolveChildDone(true);
             };
             const timer = setTimeout(() => {
                 timedOut = true;
                 kill("SIGTERM");
                 killTimer = setTimeout(() => {
                     kill("SIGKILL");
-                    finish(new AuthProcessError("timeout", `Authentication timed out. Run ${AUTH_COMMAND} to try again.`));
+                    finishChild(new AuthProcessError("timeout", `Authentication timed out. Run ${AUTH_COMMAND} to try again.`));
                 }, KILL_GRACE_MS);
             }, this.timeoutMs);
             forwardLines(child.stderr, (line) => {
@@ -211,31 +373,38 @@ export class AuthRunner {
                 catch { /* Logging must not interrupt authentication. */ }
             });
             // Piped and drained rather than ignored: a full stdout pipe would
-            // block the child mid-login.
+            // block the child mid-login. The first marker settles the caller
+            // immediately, without killing the child — see the class doc comment.
             forwardLines(child.stdout, (line) => {
-                const match = MFA_NUMBER_MARKER.exec(line);
-                if (match)
-                    numberMatch = match[1];
-                else
+                const numberMarker = MFA_NUMBER_MARKER.exec(line);
+                if (numberMarker) {
+                    numberMatch = numberMarker[1];
+                    publishChallenge(numberMatch);
+                }
+                else if (MFA_PENDING_MARKER.test(line)) {
+                    publishChallenge(undefined);
+                }
+                else {
                     log("DEBUG", line);
+                }
             });
             child.on("error", (error) => {
-                if (settled)
+                if (childFinished)
                     return;
                 log("ERROR", "Auto-auth process failed", error.message);
                 kill("SIGKILL");
-                finish(new AuthProcessError("failed", `Could not start authentication. Run ${AUTH_COMMAND} for details.`));
+                finishChild(new AuthProcessError("failed", `Could not start authentication. Run ${AUTH_COMMAND} for details.`));
             });
             child.on("close", (code) => {
-                if (settled)
+                if (childFinished)
                     return;
                 if (timedOut) {
                     kill("SIGKILL");
-                    finish(new AuthProcessError("timeout", `Authentication timed out. Run ${AUTH_COMMAND} to try again.`));
+                    finishChild(new AuthProcessError("timeout", `Authentication timed out. Run ${AUTH_COMMAND} to try again.`));
                 }
                 else if (code === 0) {
                     log("INFO", "Auto-auth completed successfully");
-                    finish();
+                    finishChild();
                 }
                 else {
                     const failures = {
@@ -244,13 +413,11 @@ 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."],
-                        7: numberMatch
-                            ? ["mfaPending", `Open Microsoft Authenticator and enter ${numberMatch} within 5 minutes, then try again.`]
-                            : ["mfaPending", "A Microsoft Authenticator approval was not completed in time. Try again."],
+                        7: mfaPendingFailure(numberMatch),
                     };
                     const [kind, message] = failures[code ?? -1] ?? ["failed", `Authentication failed. Run ${AUTH_COMMAND} to try again.`];
                     kill("SIGKILL");
-                    finish(new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined));
+                    finishChild(new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined));
                 }
             });
         });

package/build/auth/browser-auth.js

@@ -39,9 +39,9 @@ export class BrowserAuth {
     ssoFlow;
     stateStore;
     cooldown;
-    constructor(config, requestMfaCode) {
+    constructor(config, options = {}) {
         this.config = config;
-        this.ssoFlow = createSSOFlow(config, requestMfaCode);
+        this.ssoFlow = createSSOFlow(config, options.requestMfaCode, options.onMfaChallenge);
         this.stateStore = new BrowserStateStore(config.sessionDir);
         this.cooldown = new AuthCooldown(config.sessionDir);
     }

package/build/auth/credential-store.js

@@ -178,11 +178,24 @@ function decodeKey(value) {
     }
     return Buffer.from(value, "hex");
 }
+function sessionKeyAccount(canonicalDir) {
+    return `session-key:${createHash("sha256").update(canonicalDir).digest("hex")}`;
+}
+/**
+ * Whether this session directory already holds a native encryption key, which
+ * is what separates an upgrade that has not run yet from one that finished.
+ * A locked or unavailable store raises instead of answering false, so a
+ * caller never mistakes "cannot tell" for "not migrated".
+ */
+export async function hasSessionEncryptionKey(sessionDir, backend = nativeCredentialBackend) {
+    const canonicalDir = await fs.realpath(sessionDir);
+    return (await backend.getPassword(SERVICE, sessionKeyAccount(canonicalDir))) !== null;
+}
 /** The canonical session directory stays stable when DHCP changes the hostname. */
 export async function getSessionEncryptionKey(sessionDir, backend = nativeCredentialBackend, create = true) {
     await fs.mkdir(sessionDir, { recursive: true, mode: 0o700 });
     const canonicalDir = await fs.realpath(sessionDir);
-    const account = `session-key:${createHash("sha256").update(canonicalDir).digest("hex")}`;
+    const account = sessionKeyAccount(canonicalDir);
     const existing = await backend.getPassword(SERVICE, account);
     if (existing !== null) {
         try {