brightspace-mcp-server 3.4.1 → 3.6.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
 
@@ -112,7 +114,7 @@ npx -y brightspace-mcp-server@latest auth
 | Quizzes | "Which quizzes close this week?" · "Is Quiz 3 timed, and does it have a grace period?" |
 | Assignment files | "What does the lab 4 spec actually ask for?" · "Summarize the rubric attached to the project" |
 | Exams | "Is there a midterm in the gradebook that isn't on my assignments list?" |
-| Announcements | "Did any professor post something important today?" · "What did my CS prof announce this week?" · "Any announcements since last Monday?" |
+| Announcements | "Did any professor post something important today?" · "What did my CS prof announce this week?" · "Any announcements since last Monday?" · "Read the file attached to today's announcement" · "Save the rubric my prof attached to that announcement" |
 | Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "What's new in this course since I last checked?" |
 | Roster | "Who are the TAs for ECE 264?" · "Get me my instructor's email" |
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |

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}`);

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;

package/build/auth/auth-cooldown.js

@@ -19,7 +19,7 @@ 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";
     }

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/duo-mfa.js

@@ -53,6 +53,8 @@ export class DuoMfaHandler {
     approvalAnnounced = false;
     verificationCodeAnnounced = null;
     passcodeSubmitted = false;
+    /** True once onMfaChallenge has been told about this login, code or not. */
+    announcedToCaller = false;
     constructor(options) {
         this.options = options;
     }
@@ -63,14 +65,21 @@ export class DuoMfaHandler {
     async handle(page) {
         if (!this.isChallenge(page))
             return false;
+        const verificationCode = await this.readVerificationCode(page);
         if (!this.approvalAnnounced) {
             this.approvalAnnounced = true;
             log("WARN", "Waiting up to 5 minutes for Duo MFA approval on your device.");
+            this.options.onMfaChallenge?.(verificationCode);
+            if (verificationCode)
+                this.announcedToCaller = true;
         }
-        const verificationCode = await this.readVerificationCode(page);
         if (verificationCode && verificationCode !== this.verificationCodeAnnounced) {
             this.verificationCodeAnnounced = verificationCode;
             log("WARN", `Duo verification code: ${verificationCode}. Enter it in Duo Mobile.`);
+            if (!this.announcedToCaller) {
+                this.announcedToCaller = true;
+                this.options.onMfaChallenge?.(verificationCode);
+            }
         }
         await this.submitPasscode(page);
         return true;

package/build/auth/purdue-sso.js

@@ -184,6 +184,8 @@ export class PurdueSSOFlow {
         const deadline = Date.now() + MFA_TIMEOUT_MS;
         let challenged = false;
         let announced = null;
+        /** True once onMfaChallenge has been told about this login, number or not. */
+        let announcedToCaller = false;
         try {
             while (Date.now() < deadline) {
                 if (await this.duoMfa.handle(page))
@@ -197,10 +199,17 @@ export class PurdueSSOFlow {
                 if (challengeVisible && !challenged) {
                     challenged = true;
                     log("WARN", "Waiting up to 5 minutes for Microsoft MFA approval on your device.");
+                    this.config.onMfaChallenge?.(number);
+                    if (number)
+                        announcedToCaller = true;
                 }
                 if (number && number !== announced) {
                     announced = number;
                     log("WARN", `Number match: ${number}. Enter it in Microsoft Authenticator.`);
+                    if (!announcedToCaller) {
+                        announcedToCaller = true;
+                        this.config.onMfaChallenge?.(number);
+                    }
                 }
                 if (await this.isAuthenticated(page)) {
                     log("INFO", "Login successful - verified Brightspace home");

package/build/auth/sso-flow.js

@@ -35,13 +35,14 @@ export class MfaApprovalError extends BrowserAuthError {
  * else uses the default flow, which already covers the common Shibboleth,
  * CAS, and Microsoft Entra forms.
  */
-export function createSSOFlow(config, requestMfaCode) {
+export function createSSOFlow(config, requestMfaCode, onMfaChallenge) {
     const credentials = {
         username: config.username,
         password: config.password,
         baseUrl: config.baseUrl,
         headless: config.headless,
         requestMfaCode,
+        onMfaChallenge,
     };
     if (isSunyBrightspace(config.baseUrl)) {
         return new SunySSOFlow({ ...credentials, campus: config.campus });

package/build/auth/suny-sso.js

@@ -56,6 +56,7 @@ export class SunySSOFlow {
             baseUrl: `https://${SUNY_BRIGHTSPACE_HOST}`,
             headless: config.headless,
             requestMfaCode: config.requestMfaCode,
+            onMfaChallenge: config.onMfaChallenge,
         });
     }
     hasCredentials() {

package/build/auth-cli.js

@@ -56,7 +56,14 @@ async function main() {
             tokenTtl: config.tokenTtl,
         });
         const codePrompt = config.headless && !automatic && process.stdin.isTTY ? requestMfaCode : undefined;
-        await new BrowserAuth(config, codePrompt).authenticate({
+        // In automatic mode, tell the parent (AuthRunner) about an MFA challenge
+        // the moment it appears, so a blocked tool call can answer within
+        // seconds instead of waiting out the whole approval window. Stdout only
+        // — the parent parses stdout for structured markers, never stderr.
+        const onMfaChallenge = automatic
+            ? (number) => console.log(number ? `MFA_NUMBER:${number}` : "MFA_PENDING")
+            : undefined;
+        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge }).authenticate({
             automatic,
             onAuthenticated: async (token) => {
                 await tokenManager.setToken(token);

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, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_VERSION = (() => {
@@ -106,6 +106,7 @@ else {
             registerGetAnnouncements(server, apiClient, config);
             registerGetAssignments(server, apiClient, config);
             registerGetAssignmentFiles(server, apiClient, config.baseUrl);
+            registerGetAnnouncementFiles(server, apiClient);
             registerGetCourseContent(server, apiClient);
             registerDownloadFile(server, apiClient);
             registerGetClasslistEmails(server, apiClient);
@@ -114,11 +115,11 @@ else {
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION);
-            log("DEBUG", "MCP tools registered (14 tools)");
+            log("DEBUG", "MCP tools registered (15 tools)");
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (14 tools registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (15 tools registered)");
             log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
         }
         catch (error) {

package/build/tools/attachment-reader.js

@@ -0,0 +1,83 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT. See LICENSE file for details.
+ */
+import { extractPdfText } from "../utils/pdf-extractor.js";
+import { officeDocumentText } from "../utils/zip-extract.js";
+const KIND_BY_EXTENSION = {
+    pdf: "pdf",
+    docx: "docx",
+    doc: "other",
+    xlsx: "xlsx",
+    xls: "other",
+    pptx: "pptx",
+    ppt: "other",
+    png: "image",
+    jpg: "image",
+    jpeg: "image",
+    gif: "image",
+    webp: "image",
+    txt: "text",
+    md: "text",
+    csv: "text",
+    json: "text",
+};
+export function fileKind(fileName) {
+    const extension = fileName.split(".").pop()?.toLowerCase() ?? "";
+    return KIND_BY_EXTENSION[extension] ?? "other";
+}
+export function describeAttachment(attachment) {
+    return {
+        fileId: attachment.FileId,
+        fileName: attachment.FileName,
+        size: attachment.Size,
+        kind: fileKind(attachment.FileName),
+    };
+}
+/**
+ * Read one attachment from the path that serves its bytes. The text is best
+ * effort: a scanned PDF or an image yields nothing, and that is reported
+ * rather than treated as a failure.
+ */
+export async function readAttachment(apiClient, sourcePath, attachment, extract, maxChars) {
+    const base = describeAttachment(attachment);
+    if (!extract)
+        return { ...base, text: null, note: "Text extraction was not requested." };
+    const response = await apiClient.getRaw(sourcePath);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    let text = null;
+    let note;
+    switch (base.kind) {
+        case "pdf": {
+            const extracted = await extractPdfText(buffer);
+            text = extracted?.text?.trim() || null;
+            if (!text)
+                note = "No text layer in this PDF. It may be a scan.";
+            break;
+        }
+        case "docx":
+        case "xlsx":
+        case "pptx": {
+            text = officeDocumentText(buffer);
+            if (!text)
+                note = "No readable text found in this Office document.";
+            break;
+        }
+        case "text": {
+            text = buffer.toString("utf-8").trim() || null;
+            break;
+        }
+        default: {
+            note = `Cannot extract text from a ${base.kind} file. Use download_file to save it.`;
+        }
+    }
+    const truncated = text !== null && text.length > maxChars;
+    return {
+        ...base,
+        bytes: buffer.length,
+        text: truncated ? text.slice(0, maxChars) : text,
+        truncated,
+        ...(note ? { note } : {}),
+    };
+}

package/build/tools/download-file.js

@@ -19,13 +19,13 @@ import path from "node:path";
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content or assignment submissions to a local directory. Use this when the user wants to download, save, or get a file from Brightspace course content or dropbox submissions. IMPORTANT: You MUST ask the user where they want to save the file before calling this tool. Never guess or assume a download directory. After identifying the file to download, suggest a clean readable filename to the user (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and ask if they'd like to rename it. Pass their preferred name as customFilename, or omit it to keep the original.",
+        description: "Download a file from course content, assignment submissions, or an announcement's attachments to a local directory. Use this when the user wants to download, save, or get a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool. Never guess or assume a download directory. After identifying the file to download, suggest a clean readable filename to the user (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and ask if they'd like to rename it. Pass their preferred name as customFilename, or omit it to keep the original.",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {
             log("DEBUG", "download_file tool called", { args });
             // Parse and validate input
-            const { courseId, topicId, folderId, fileId, downloadPath, customFilename } = DownloadFileSchema.parse(args);
+            const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename } = DownloadFileSchema.parse(args);
             // Validate courseId
             validateContentId(courseId);
             // Validate download path is absolute
@@ -57,8 +57,14 @@ export function registerDownloadFile(server, apiClient) {
                 validateContentId(fileId);
                 return await downloadSubmissionFile(apiClient, courseId, folderId, fileId, downloadPath, customFilename);
             }
+            else if (newsId !== undefined && fileId !== undefined) {
+                // Announcement attachment download
+                validateContentId(newsId);
+                validateContentId(fileId);
+                return await downloadNewsAttachment(apiClient, courseId, newsId, fileId, downloadPath, customFilename);
+            }
             else {
-                return errorResponse("Either topicId (for content files) or both folderId and fileId (for submission files) must be provided");
+                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");
             }
         }
         catch (error) {
@@ -202,3 +208,50 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
         message: `File downloaded successfully to ${result.path}`,
     });
 }
+/**
+ * Download an announcement attachment using newsId + fileId
+ */
+async function downloadNewsAttachment(apiClient, courseId, newsId, fileId, downloadPath, customFilename) {
+    log("INFO", `Downloading announcement attachment: courseId=${courseId}, newsId=${newsId}, fileId=${fileId}`);
+    const newsItem = await apiClient.get(apiClient.le(courseId, `/news/${newsId}`));
+    const attachments = newsItem?.Attachments ?? [];
+    const file = attachments.find((f) => f.FileId === fileId);
+    if (!file) {
+        return errorResponse(`File ID ${fileId} not found on this announcement. Available files: ${attachments.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
+    }
+    if (file.Size > MAX_FILE_SIZE) {
+        return errorResponse(`File too large (${Math.round(file.Size / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    }
+    // GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)
+    const response = await apiClient.getRaw(apiClient.le(courseId, `/news/${newsId}/attachments/${fileId}`));
+    // Check Content-Length BEFORE downloading body (prevent memory exhaustion)
+    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
+    if (contentLength > MAX_FILE_SIZE) {
+        return errorResponse(`File too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    }
+    const disposition = response.headers.get("Content-Disposition") ?? "";
+    const filename = parseContentDispositionFilename(disposition) ?? file.FileName;
+    // Download body as buffer
+    const buffer = Buffer.from(await response.arrayBuffer());
+    // Double-check actual size
+    if (buffer.length > MAX_FILE_SIZE) {
+        return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    }
+    const originalFilename = filename;
+    const effectiveFilename = customFilename || filename;
+    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
+    const result = await secureDownload({
+        targetDir: downloadPath,
+        filename: effectiveFilename,
+        data: buffer,
+    });
+    log("INFO", `Announcement attachment downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
+    return toolResponse({
+        success: true,
+        filePath: result.path,
+        fileSize: result.size,
+        mimeType: result.mime,
+        originalFilename,
+        message: `File downloaded successfully to ${result.path}`,
+    });
+}

package/build/tools/get-announcement-files.js

@@ -0,0 +1,89 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT. See LICENSE file for details.
+ */
+import { DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { GetAnnouncementFilesSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { describeAttachment, readAttachment } from "./attachment-reader.js";
+import { effectiveDate, isPublishedNewsItem } from "./get-announcements.js";
+import { log } from "../utils/logger.js";
+/**
+ * The files an instructor attached to an announcement: field-notes prompts,
+ * a rubric, an updated schedule. They hang off the news item, not course
+ * content, so get_course_content never lists them. Same shape as
+ * get_assignment_files: list first, then read one file by id.
+ */
+/** Every posted announcement in the course, narrowed to one when newsId is given. */
+async function listNews(apiClient, courseId, newsId) {
+    const items = await apiClient.get(apiClient.le(courseId, "/news/"), {
+        ttl: DEFAULT_CACHE_TTLS.announcements,
+    });
+    return items
+        .filter(isPublishedNewsItem)
+        .filter((item) => (newsId === undefined ? true : item.Id === newsId));
+}
+export function registerGetAnnouncementFiles(server, apiClient) {
+    server.registerTool("get_announcement_files", {
+        title: "Get Announcement Files",
+        description: "Read the files an instructor attached to an announcement: prompt questions, a rubric, an updated schedule, slides. Call it with just courseId to see which announcements have attachments, then with newsId and fileId to read one. Use this when the user asks what a file attached to an announcement says. Returns the text itself. Use download_file (newsId + fileId) instead when the user wants the file saved to disk.",
+        inputSchema: GetAnnouncementFilesSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_announcement_files tool called", { args });
+            const { courseId, newsId, fileId, extractText, maxChars } = GetAnnouncementFilesSchema.parse(args);
+            if (fileId !== undefined && newsId === undefined) {
+                return toolResponse({
+                    courseId,
+                    error: "newsId is required when fileId is given.",
+                });
+            }
+            const items = await listNews(apiClient, courseId, newsId);
+            if (newsId !== undefined && items.length === 0) {
+                return toolResponse({
+                    courseId,
+                    newsId,
+                    error: `No announcement with id ${newsId} in course ${courseId}.`,
+                });
+            }
+            // Read one file.
+            if (fileId !== undefined) {
+                const item = items[0];
+                const attachments = item.Attachments ?? [];
+                const attachment = attachments.find((a) => a.FileId === fileId);
+                if (!attachment) {
+                    return toolResponse({
+                        courseId,
+                        newsId,
+                        fileId,
+                        error: `No attachment with id ${fileId} on announcement "${item.Title}".`,
+                        available: attachments.map(describeAttachment),
+                    });
+                }
+                const file = await readAttachment(apiClient, apiClient.le(courseId, `/news/${item.Id}/attachments/${fileId}`), attachment, extractText, maxChars);
+                return toolResponse({ courseId, newsId, title: item.Title, file });
+            }
+            // Discovery: which announcements have files, without downloading any.
+            const withFiles = items
+                .filter((item) => (item.Attachments ?? []).length > 0)
+                .map((item) => ({
+                newsId: item.Id,
+                title: item.Title,
+                date: effectiveDate(item),
+                attachments: (item.Attachments ?? []).map(describeAttachment),
+            }));
+            log("INFO", `get_announcement_files: ${withFiles.length} announcements with attachments in course ${courseId}`);
+            return toolResponse({
+                courseId,
+                announcements: withFiles,
+                ...(withFiles.length === 0
+                    ? { note: "No announcement in this course has an attached file." }
+                    : {}),
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-announcements.js

@@ -56,6 +56,11 @@ export function newestFirst(a, b) {
  * Map a raw D2L news item to a clean announcement object.
  */
 export function mapNewsItem(item) {
+    const attachments = (item.Attachments ?? []).map((file) => ({
+        fileId: file.FileId,
+        fileName: file.FileName,
+        size: file.Size,
+    }));
     return {
         id: item.Id,
         title: item.Title,
@@ -64,6 +69,7 @@ export function mapNewsItem(item) {
         date: effectiveDate(item),
         isPinned: item.IsPinned,
         lastModified: item.LastModifiedDate ?? null,
+        ...(attachments.length > 0 ? { attachments } : {}),
     };
 }
 /**
@@ -72,7 +78,7 @@ export function mapNewsItem(item) {
 export function registerGetAnnouncements(server, apiClient, config) {
     server.registerTool("get_announcements", {
         title: "Get Announcements",
-        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said.",
+        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said. Attachments are listed per announcement; fetch them with download_file (newsId + fileId) or read them with get_announcement_files.",
         inputSchema: GetAnnouncementsSchema,
     }, async (args) => {
         try {

package/build/tools/get-assignment-files.js

@@ -6,44 +6,14 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetAssignmentFilesSchema } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
-import { extractPdfText } from "../utils/pdf-extractor.js";
-import { officeDocumentText } from "../utils/zip-extract.js";
+import { describeAttachment, readAttachment, } from "./attachment-reader.js";
 import { assignmentUrl } from "../utils/deep-links.js";
 import { log } from "../utils/logger.js";
+export { fileKind } from "./attachment-reader.js";
 /** D2L list endpoints return either a paged { Objects: [...] } or a flat array. */
 function unwrapList(raw) {
     return Array.isArray(raw) ? raw : (raw?.Objects ?? []);
 }
-const KIND_BY_EXTENSION = {
-    pdf: "pdf",
-    docx: "docx",
-    doc: "other",
-    xlsx: "xlsx",
-    xls: "other",
-    pptx: "pptx",
-    ppt: "other",
-    png: "image",
-    jpg: "image",
-    jpeg: "image",
-    gif: "image",
-    webp: "image",
-    txt: "text",
-    md: "text",
-    csv: "text",
-    json: "text",
-};
-export function fileKind(fileName) {
-    const extension = fileName.split(".").pop()?.toLowerCase() ?? "";
-    return KIND_BY_EXTENSION[extension] ?? "other";
-}
-function describeAttachment(attachment) {
-    return {
-        fileId: attachment.FileId,
-        fileName: attachment.FileName,
-        size: attachment.Size,
-        kind: fileKind(attachment.FileName),
-    };
-}
 /** Every visible folder in the course that has at least one attachment. */
 async function listFolders(apiClient, courseId, folderId) {
     const raw = await apiClient.get(apiClient.le(courseId, "/dropbox/folders/"), {
@@ -53,51 +23,6 @@ async function listFolders(apiClient, courseId, folderId) {
         .filter((folder) => folder.IsHidden !== true)
         .filter((folder) => (folderId === undefined ? true : folder.Id === folderId));
 }
-/**
- * Read one attachment. The text is best effort: a scanned PDF or an image
- * yields nothing, and that is reported rather than treated as a failure.
- */
-async function readAttachment(apiClient, courseId, folderId, attachment, extract, maxChars) {
-    const base = describeAttachment(attachment);
-    if (!extract)
-        return { ...base, text: null, note: "Text extraction was not requested." };
-    const response = await apiClient.getRaw(apiClient.le(courseId, `/dropbox/folders/${folderId}/attachments/${attachment.FileId}`));
-    const buffer = Buffer.from(await response.arrayBuffer());
-    let text = null;
-    let note;
-    switch (base.kind) {
-        case "pdf": {
-            const extracted = await extractPdfText(buffer);
-            text = extracted?.text?.trim() || null;
-            if (!text)
-                note = "No text layer in this PDF. It may be a scan.";
-            break;
-        }
-        case "docx":
-        case "xlsx":
-        case "pptx": {
-            text = officeDocumentText(buffer);
-            if (!text)
-                note = "No readable text found in this Office document.";
-            break;
-        }
-        case "text": {
-            text = buffer.toString("utf-8").trim() || null;
-            break;
-        }
-        default: {
-            note = `Cannot extract text from a ${base.kind} file. Use download_file to save it.`;
-        }
-    }
-    const truncated = text !== null && text.length > maxChars;
-    return {
-        ...base,
-        bytes: buffer.length,
-        text: truncated ? text.slice(0, maxChars) : text,
-        truncated,
-        ...(note ? { note } : {}),
-    };
-}
 export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
     server.registerTool("get_assignment_files", {
         title: "Get Assignment Files",
@@ -134,7 +59,7 @@ export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
                         available: (folder.Attachments ?? []).map(describeAttachment),
                     });
                 }
-                const file = await readAttachment(apiClient, courseId, folderId, attachment, extractText, maxChars);
+                const file = await readAttachment(apiClient, apiClient.le(courseId, `/dropbox/folders/${folderId}/attachments/${fileId}`), attachment, extractText, maxChars);
                 return toolResponse({
                     courseId,
                     folderId,

package/build/tools/index.js

@@ -10,6 +10,7 @@ export { registerGetMyGrades } from "./get-my-grades.js";
 export { registerGetAnnouncements } from "./get-announcements.js";
 export { registerGetAssignments } from "./get-assignments.js";
 export { registerGetAssignmentFiles } from "./get-assignment-files.js";
+export { registerGetAnnouncementFiles } from "./get-announcement-files.js";
 export { registerGetCourseContent } from "./get-course-content.js";
 export { registerDownloadFile } from "./download-file.js";
 export { registerGetClasslistEmails } from "./get-classlist-emails.js";

package/build/tools/schemas.js

@@ -59,7 +59,9 @@ export const DownloadFileSchema = z.object({
     folderId: z.coerce.number().int().positive().optional()
         .describe("Dropbox folder ID (for submission/feedback file downloads)."),
     fileId: z.coerce.number().int().positive().optional()
-        .describe("Specific file ID within a dropbox submission."),
+        .describe("Specific file ID within a dropbox submission, or an announcement attachment's file ID (with newsId)."),
+    newsId: z.coerce.number().int().positive().optional()
+        .describe("Announcement (news item) ID whose attachment to download. Requires fileId."),
     downloadPath: z.string().min(1)
         .describe("Absolute path to the directory where the file should be saved."),
     customFilename: z.string().max(255).optional()
@@ -91,6 +93,18 @@ export const GetAssignmentFilesSchema = z.object({
     maxChars: z.coerce.number().int().positive().max(100000).default(12000)
         .describe("Maximum characters of extracted text to return. The response reports whether it was truncated."),
 });
+export const GetAnnouncementFilesSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID whose announcement attachments to look at."),
+    newsId: z.coerce.number().int().positive().optional()
+        .describe("Announcement (news item) ID. Omit to list every announcement in the course that has attachments."),
+    fileId: z.coerce.number().int().positive().optional()
+        .describe("Attachment file ID to read. Requires newsId. Omit to list the files without reading them."),
+    extractText: z.boolean().default(true)
+        .describe("Extract readable text from the file. Works for PDF, DOCX, XLSX, PPTX, and plain text."),
+    maxChars: z.coerce.number().int().positive().max(100000).default(12000)
+        .describe("Maximum characters of extracted text to return. The response reports whether it was truncated."),
+});
 export const GetVideoTranscriptSchema = z.object({
     courseId: z.coerce.number().int().positive().optional()
         .describe("Course ID the video belongs to. Required together with topicId unless videoUrl is given directly."),

package/build/tools/tool-helpers.js

@@ -59,19 +59,20 @@ export function errorResponse(message) {
 const AUTH_FAILURE_GUIDANCE = {
     busy: "A sign-in is already running in another process. Let it finish, then try again.",
     cooldown: "Automatic sign-in is paused because an MFA prompt went unanswered. " +
-        `Run \`${AUTH_COMMAND}\` in a terminal to retry now and see the number to enter.`,
+        `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to retry now and see the number to enter.`,
     unsupported: "This login needs something your AI client cannot supply, usually a code from an "
         + "authenticator app. " +
-        `Run \`${AUTH_COMMAND}\` in a terminal and sign in there.`,
+        `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) and sign in there.`,
     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.",
     timeout: "The sign-in did not finish in time, usually a missed MFA prompt. " +
-        `Run \`${AUTH_COMMAND}\` in a terminal to complete it with the number visible.`,
-    failed: `The sign-in did not complete. Run \`${AUTH_COMMAND}\` in a terminal to see why, ` +
+        `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.",
-    mfaPending: "A Microsoft Authenticator approval was not completed in time. Try again.",
+    mfaPending: "Approve the sign-in request on your phone (Microsoft Authenticator or Duo), " +
+        "then call this tool again — the sign-in is finishing in the background.",
 };
 /**
  * mfaPending is the one kind whose guidance is partly dynamic: `numberMatch`
@@ -82,7 +83,8 @@ const AUTH_FAILURE_GUIDANCE = {
  */
 function authFailureMessage(error) {
     if (error.kind === "mfaPending" && error.numberMatch) {
-        return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes, then run this again.`;
+        return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes, ` +
+            "then call this tool again — the sign-in is finishing in the background.";
     }
     return AUTH_FAILURE_GUIDANCE[error.kind];
 }

package/package.json

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