brightspace-mcp-server 5.1.25 → 5.1.27

package/README.md

@@ -159,6 +159,8 @@ npx -y brightspace-mcp-server@latest auth
 
 **Want fewer 2FA prompts?** `setup` asks one question, "How often do you want to approve sign-ins on your phone?": **1** every time (default), **2** remember this computer, or **3** let this computer answer Microsoft's code requests itself (needs an authenticator setup key). Options 2 and 3 are opt-in and not for shared computers; to turn them off, rerun `setup` and pick 1. The tradeoffs and the steps for getting the key are in [docs/sign-in.md](docs/sign-in.md#fewer-2fa-prompts).
 
+**To sign in,** just ask your AI app to sign you in to Brightspace — it can start the sign-in itself now, and it opens a window for you when no password is saved. You can also run `npx -y brightspace-mcp-server@latest auth` in a terminal.
+
 **To sign out early** (on a shared computer, say), just ask your AI app to sign you out of Brightspace, or run `npx -y brightspace-mcp-server@latest auth --logout` in a terminal. It deletes this computer's saved Brightspace session, so the next question does a full sign-in. Your saved password, authenticator key, and settings are kept, so with a saved authenticator key that sign-in can finish without you; on a shared computer, also delete the saved `brightspace-mcp-server` entries from your computer's password store (Keychain Access on a Mac, Credential Manager on Windows). Other AI apps open on this computer are signed out too and will ask you to sign in on their next question. (An app you opened before updating may keep answering for up to an hour; quit and reopen it to sign it out right away.) It only clears this computer; it does not sign you out of Microsoft or Brightspace anywhere else. Both also cancel a sign-in an AI app started that is still waiting for you to approve it (`auth --logout` can't on Windows, and leaves an `auth` run in another terminal alone, deleting nothing). Cancelling doesn't get you a new prompt any sooner: Microsoft won't send another until the earlier one expires, up to 5 minutes after it was sent.
 
 How often you're asked is up to your school, not this tool. Everything else about sign-in — Duo, authenticator codes, visible-browser mode, and running without a browser at all (Docker, WSL, hardware keys) — is in [docs/sign-in.md](docs/sign-in.md).

package/build/auth/auth-runner.js

@@ -422,6 +422,15 @@ export class AuthRunner {
     timeoutMs;
     onProgress;
     sessionDir;
+    /**
+     * Whether the next child this runner spawns should open a window, set by
+     * sign_in and cleared as that child starts. A first sign-in with no saved
+     * password cannot finish headlessly: there is nothing to type into the
+     * school's form, so it waits and times out. Opt-in and one-shot, because
+     * background recovery must never put a browser over the user's work on its
+     * own; that is the standing rule the D2L_HEADLESS default encodes.
+     */
+    visibleNextChild = false;
     constructor(options = {}) {
         // Resolve paths relative to this file's compiled location (build/auth/auth-runner.js)
         const thisDir = path.dirname(fileURLToPath(import.meta.url));
@@ -440,6 +449,15 @@ export class AuthRunner {
     busy() {
         return this.inFlight !== null || this.childDone !== null;
     }
+    /**
+     * Ask that the next child this runner spawns sign in with a visible window
+     * (see visibleNextChild). Takes effect only for a child this runner starts:
+     * a call that joins a sign-in already running inherits that sign-in's mode,
+     * so sign_in checks busy() before asking.
+     */
+    requestVisibleBrowser() {
+        this.visibleNextChild = true;
+    }
     /**
      * Cancel this process's sign-in, if one is running: stop the child at once
      * (no MFA cooldown is recorded, see forceStop) and answer every call waiting
@@ -811,6 +829,10 @@ export class AuthRunner {
      */
     async spawnAuth() {
         const started = Date.now();
+        // Read and cleared here, so a visible request never outlives the one
+        // child it was made for.
+        const visible = this.visibleNextChild;
+        this.visibleNextChild = false;
         const recoveryId = newRecoveryId();
         devActivity("recovery_started", { recoveryId });
         log("INFO", "Auto-launching brightspace-auth...");
@@ -822,7 +844,15 @@ export class AuthRunner {
                 // unless D2L_HEADLESS explicitly asks for one; the saved
                 // visible-browser preference applies to manual sign-in only.
                 // The recovery id lets the child's dev activity join this recovery.
-                env: { D2L_HEADLESS: "true", ...process.env, [RECOVERY_ID_ENV]: recoveryId },
+                // An explicit sign_in request for a window comes last, so it wins
+                // over an inherited D2L_HEADLESS that would hide the one page the
+                // user has to finish by hand.
+                env: {
+                    D2L_HEADLESS: "true",
+                    ...process.env,
+                    [RECOVERY_ID_ENV]: recoveryId,
+                    ...(visible ? { D2L_HEADLESS: "false" } : {}),
+                },
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: process.platform !== "win32",
                 windowsHide: true,

package/build/server.js

@@ -9,7 +9,7 @@ import { D2LApiClient } from "./api/index.js";
 import { trackToolActivity } from "./utils/dev-activity.js";
 import { log } from "./utils/logger.js";
 import { envCredentialRejectedMessage, ENV_COOKIE_REJECTED } from "./utils/commands.js";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, COURSE_FILE_NEEDS_COOKIE, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, COURSE_FILE_NEEDS_COOKIE, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerSignIn, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 /**
  * Build the shared runtime. Nothing here reaches Brightspace: API versions
@@ -94,6 +94,7 @@ export function createMcpServer(runtime) {
     registerGetServerInfo(server, config, version, apiClient);
     registerSearchCourse(server, apiClient);
     registerSignOut(server, config, apiClient, tokenManager, authRunner);
+    registerSignIn(server, config, tokenManager, authRunner);
     // Instructor / TA dropbox tools (read-only) — 403 for a student account.
     registerGetDropboxFolders(server, apiClient);
     registerGetDropboxSubmissions(server, apiClient);

package/build/tools/index.js

@@ -24,6 +24,7 @@ export { registerGetVideoTranscript } from "./get-video-transcript.js";
 export { registerGetServerInfo } from "./get-server-info.js";
 export { registerSearchCourse } from "./search-course.js";
 export { registerSignOut } from "./sign-out.js";
+export { registerSignIn } from "./sign-in.js";
 // Instructor / TA dropbox tools (read-only)
 export { registerGetDropboxFolders } from "./get-dropbox-folders.js";
 export { registerGetDropboxSubmissions } from "./get-dropbox-submissions.js";

package/build/tools/schemas.js

@@ -162,6 +162,10 @@ export const GetMyGroupsSchema = z.object({
 });
 export const GetServerInfoSchema = z.object({});
 export const SignOutSchema = z.object({});
+export const SignInSchema = z.object({
+    visible: z.boolean().optional()
+        .describe("Open a browser window for the user to sign in by hand. Omit to decide automatically: a window opens only when no password is saved on this computer, because a sign-in with no window has nothing to type into the school's form and would only time out. Pass true when a background sign-in has already failed or the school's page needs a step it cannot do, false to insist on a background sign-in."),
+});
 // ── Instructor / TA dropbox tools ──────────────────────────────────────────
 // Read-only, instructor/TA-side views of a course's dropbox (assignment)
 // folders and the submissions inside them. These answer "who has/hasn't

package/build/tools/sign-in.js

@@ -0,0 +1,108 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { AuthProcessError } from "../auth/auth-runner.js";
+import { log } from "../utils/logger.js";
+import { createSSOFlow } from "../auth/sso-flow.js";
+import { SignInSchema } from "./schemas.js";
+import { authPendingNotice, sanitizeError, textResponse as text } from "./tool-helpers.js";
+import { AUTH_COMMAND, SETUP_COMMAND } from "../utils/commands.js";
+const ALREADY = "Already signed in to Brightspace on this computer; the saved session is still valid. Nothing was changed. Go ahead and call the tool you actually need.";
+const ENV_CREDENTIAL = "Nothing to do. This server authenticates with a credential from its configuration (D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE), not with a sign-in it can start. If Brightspace is rejecting it, the user has to paste a fresh one into their AI app's configuration or .env file and restart the app.";
+const NO_RUNNER = `This server cannot start a sign-in itself. Tell the user to run \`${AUTH_COMMAND}\` in a terminal, prefixed with D2L_HEADLESS=false if they need to see the sign-in page and finish it by hand.`;
+const SUCCESS = "Signed in to Brightspace. The session is saved on this computer, so other Brightspace apps here can use it too.";
+/** What an open window means for the caller: this one waits on a person, not on a retry. */
+const WINDOW_OPEN = "A browser window is opening on the user's screen for them to sign in by hand. Tell the user to complete it, including any 2FA, then ask them to say when they are done.";
+const NEEDS_PASSWORD_FOR_HEADLESS = `No password is saved on this computer, so a sign-in with no window has nothing to type into the school's form and would only wait and time out. Either call sign_in again with visible true, or tell the user to run \`${SETUP_COMMAND}\` to save one.`;
+/**
+ * A sign-in still working is progress, not a failure, so these are not marked
+ * isError: the shared guidance for them already tells the caller to come back
+ * (each call polls the running sign-in), and isError invites a model to give
+ * up or apologize instead.
+ */
+const STILL_WORKING = new Set([
+    "mfaPending",
+    "automaticPending",
+    "inProgress",
+]);
+/**
+ * Register sign_in tool.
+ *
+ * The counterpart to sign_out, and the reason it exists: an AI app had no way
+ * to *start* a sign-in. Recovery happened only as a side effect of some other
+ * tool hitting a 401, and the one documented fix for a first sign-in — open a
+ * window — lived in an environment variable that nothing reachable from a
+ * chat could set. So an assistant whose session had lapsed could only tell
+ * the user to go and run a terminal command.
+ *
+ * What is specific to this tool is the decision to sign in at all, and the
+ * window: the saved session is read first (TokenManager), so calling this
+ * speculatively costs the user no MFA approval, and `visible`, left out,
+ * opens a window exactly when the school's sign-in flow has nothing to sign
+ * in with (no username, or no password and not passwordless), which is when a
+ * headless sign-in can only time out.
+ * A window cannot be asked of a sign-in already running, which keeps its own
+ * mode, so busy() is checked before one is promised.
+ *
+ * Everything a *failure* should say is authPendingNotice's, not this file's:
+ * the per-kind guidance, the MFA number, the dedup when a parallel call
+ * already carried it, and the "ask for 2FA less often" tip. Writing that
+ * wording again here would be a second policy to keep in step with
+ * AuthRunner — and a wrong one, since the house guidance tells a caller to
+ * keep calling while a sign-in polls, which is the opposite of what a
+ * hand-written "do not retry" would say.
+ */
+export function registerSignIn(server, config, tokenManager, authRunner) {
+    server.registerTool("sign_in", {
+        title: "Sign In to Brightspace",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: "Sign in to Brightspace on this computer so the other tools work. Does nothing and says so if the saved session is already valid, so it is safe to call first when you are unsure. Opens a browser window for the user to sign in by hand when no password is saved (nothing to type means a windowless sign-in can only time out); otherwise it signs in in the background and reports the 2FA number for the user to approve on their phone. Call this when a Brightspace tool failed because of authentication, or when the user asks to sign in or log in to Brightspace. Every answer says what to do next, including whether to call again.",
+        inputSchema: SignInSchema,
+    }, async ({ visible }) => {
+        if (config.envAccessToken || config.envSessionCookie)
+            return text(ENV_CREDENTIAL);
+        if (!authRunner)
+            return text(NO_RUNNER);
+        // First, so signing in again when the saved session is fine never asks
+        // the user for an approval they did not need to give.
+        try {
+            const token = await tokenManager.getToken();
+            if (token && tokenManager.isValid(token))
+                return text(ALREADY);
+        }
+        catch (error) {
+            // A session that cannot be read is exactly what signing in fixes.
+            log("DEBUG", "sign_in could not read the saved session; signing in", error);
+        }
+        // The same test the sign-in itself makes before typing anything: each
+        // school's flow decides. A passwordless account keeps no password yet
+        // signs in without a window (the phone approves it).
+        const canSignInHeadless = createSSOFlow(config).hasCredentials();
+        // A window only when a headless sign-in could not work anyway.
+        const wantWindow = visible ?? !canSignInHeadless;
+        // A joined sign-in keeps the mode it started with, so asking would only
+        // promise the user a window that never appears.
+        const windowOpened = wantWindow && !authRunner.busy();
+        if (windowOpened)
+            authRunner.requestVisibleBrowser();
+        else if (wantWindow)
+            log("INFO", "sign_in was asked for a window but a sign-in is already running");
+        if (!wantWindow && !canSignInHeadless)
+            return text(NEEDS_PASSWORD_FOR_HEADLESS, true);
+        try {
+            await authRunner.run();
+            return text(SUCCESS);
+        }
+        catch (error) {
+            if (error instanceof AuthProcessError) {
+                const guidance = authPendingNotice(error);
+                return text(windowOpened ? `${WINDOW_OPEN} ${guidance}` : guidance, !STILL_WORKING.has(error.kind));
+            }
+            // Everything else goes through the house path, which logs it and
+            // keeps stack traces and raw responses out of the answer.
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/sign-out.js

@@ -9,7 +9,7 @@ import { clearSavedSession, RemoveError } from "../auth/logout.js";
 import { authLockPath } from "../auth/mfa-challenge.js";
 import { log } from "../utils/logger.js";
 import { SignOutSchema } from "./schemas.js";
-import { withUpdateNotice } from "./tool-helpers.js";
+import { textResponse as text } from "./tool-helpers.js";
 const KEPT = "Kept (if you set them up): your saved password, your settings, and your authenticator key.";
 const OTHER_APPS = "Other Brightspace apps open on this computer are signed out too and will sign in again from scratch on their next question. An app you opened before updating to this version may keep answering for up to an hour; quit and reopen it to sign it out right away.";
 const NEXT_SIGN_IN = "Because your saved password (and authenticator key, if you saved one) stay on this computer, that next sign-in may just ask you to approve it, or finish on its own if you saved an authenticator key. On a shared computer, also delete the saved \"brightspace-mcp-server\" entries from your computer's password store (Keychain Access on a Mac, Credential Manager on Windows).";
@@ -20,10 +20,6 @@ const NEXT_QUESTION = "Microsoft keeps that prompt open for up to 5 minutes afte
 const ALREADY_SIGNED_OUT = "You're already signed out of Brightspace on this computer; there was no saved session to remove.";
 const NOTHING_SAVED = "There was no saved session to remove.";
 const UNEXPECTED_FAILURE = "Could not clear the saved session because of an unexpected error. Nothing more was changed; try again, or run `npx -y brightspace-mcp-server@latest auth --logout` in a terminal to see the details.";
-function text(message, isError = false) {
-    const result = withUpdateNotice([{ type: "text", text: message }]);
-    return isError ? { ...result, isError: true } : result;
-}
 /**
  * Register sign_out tool.
  *

package/build/tools/tool-helpers.js

@@ -29,6 +29,15 @@ export function withUpdateNotice(content) {
         content.push({ type: "text", text: notice });
     return { content };
 }
+/**
+ * A plain-text answer, as the sign-in tools give: prose a model relays to the
+ * user, not a JSON envelope to read fields out of. Carries the update notice
+ * like every other response.
+ */
+export function textResponse(message, isError = false) {
+    const result = withUpdateNotice([{ type: "text", text: message }]);
+    return isError ? { ...result, isError: true } : result;
+}
 /**
  * Wrap data as MCP-compatible tool result.
  *

package/build/utils/zip-extract.js

@@ -16,8 +16,9 @@ import { inflateRawSync } from "node:zlib";
  * parsing a header that does not exist.
  *
  * Nothing here throws. A truncated download, an unsupported compression
- * method, or a ZIP64 archive all return null, because the caller's fallback
- * is simply to report the file without its text.
+ * method, a ZIP64 archive, or an entry that inflates past the size budget all
+ * return null, because the caller's fallback is simply to report the file
+ * without its text.
  */
 const EOCD_SIGNATURE = 0x06054b50;
 const CENTRAL_FILE_SIGNATURE = 0x02014b50;
@@ -26,6 +27,13 @@ const EOCD_MAX_COMMENT = 0xffff;
 const ZIP64_MARKER = 0xffffffff;
 const METHOD_STORED = 0;
 const METHOD_DEFLATE = 8;
+/**
+ * Most bytes one document may inflate to, across every entry read from it.
+ * DEFLATE reaches ~1000:1, so a 50 MB download could otherwise inflate to
+ * tens of gigabytes and take the server down (issue #380). Real Office XML
+ * sits far below this.
+ */
+export const MAX_INFLATED_BYTES = 64 * 1024 * 1024;
 /** Find the End of Central Directory record by scanning backwards. */
 function findEocd(buffer) {
     const earliest = Math.max(0, buffer.length - EOCD_MIN_SIZE - EOCD_MAX_COMMENT);
@@ -70,7 +78,13 @@ function readCentralDirectory(buffer) {
     }
     return entries;
 }
-function readEntryData(buffer, entry) {
+/**
+ * An entry's bytes, or null when it would exceed `limit`. The declared size
+ * is checked first, but a header can lie, so inflation is capped as well.
+ */
+function readEntryData(buffer, entry, limit) {
+    if (entry.uncompressedSize > limit)
+        return null;
     const header = entry.localHeaderOffset;
     if (header + 30 > buffer.length)
         return null;
@@ -84,18 +98,19 @@ function readEntryData(buffer, entry) {
         return null;
     const raw = buffer.subarray(start, end);
     if (entry.method === METHOD_STORED)
-        return Buffer.from(raw);
+        return raw.length > limit ? null : Buffer.from(raw);
     if (entry.method !== METHOD_DEFLATE)
         return null;
     try {
-        return inflateRawSync(raw);
+        // Throws a RangeError past maxOutputLength.
+        return inflateRawSync(raw, { maxOutputLength: Math.max(1, limit) });
     }
     catch {
         return null;
     }
 }
 /** One entry from a ZIP archive by exact name, or null. Never throws. */
-export function extractZipEntry(buffer, entryName) {
+export function extractZipEntry(buffer, entryName, limit = MAX_INFLATED_BYTES) {
     try {
         const entries = readCentralDirectory(buffer);
         if (!entries)
@@ -103,7 +118,7 @@ export function extractZipEntry(buffer, entryName) {
         const entry = entries.find((e) => e.name === entryName);
         if (!entry)
             return null;
-        return readEntryData(buffer, entry);
+        return readEntryData(buffer, entry, limit);
     }
     catch {
         return null;
@@ -145,7 +160,22 @@ export function officeDocumentText(buffer) {
     const names = listZipEntries(buffer);
     if (!names)
         return null;
-    const read = (name) => xmlToText(extractZipEntry(buffer, name)?.toString("utf-8") ?? "");
+    // One budget for the whole document, so a PPTX can't spread a zip bomb
+    // across many slides that each fit on their own. An entry that fails to
+    // read (oversize included) ends the walk: retrying the rest would re-inflate
+    // up to the budget once per entry.
+    let budget = MAX_INFLATED_BYTES;
+    const read = (name) => {
+        if (budget <= 0)
+            return "";
+        const data = extractZipEntry(buffer, name, budget);
+        if (!data) {
+            budget = 0;
+            return "";
+        }
+        budget -= data.length;
+        return xmlToText(data.toString("utf-8"));
+    };
     let text = "";
     if (names.includes("word/document.xml")) {
         text = read("word/document.xml");

package/package.json

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