brightspace-mcp-server 5.1.21 → 5.1.23

package/README.md

@@ -159,7 +159,7 @@ 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 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. Asking your AI app also cancels a sign-in still waiting for you to approve it; the `auth --logout` command instead refuses and deletes nothing while a sign-in is in progress. 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.
+**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-lock.js

@@ -119,7 +119,7 @@ export async function inspectLockOwner(lockPath) {
 /**
  * The PID of a live "automatic" owner (a background AuthRunner child), or
  * undefined when the lock is free, its owner is gone, or it is held some other
- * way. Used by sign_out to cancel another app's waiting sign-in.
+ * way. Used by sign_out and `auth --logout` to cancel another app's waiting sign-in.
  */
 export async function liveAutomaticOwner(lockPath) {
     const owner = await readOwner(lockPath);

package/build/auth/auth-runner.js

@@ -243,16 +243,25 @@ function forceStop(pid) {
 const CANCEL_WAIT_MS = 5000;
 /**
  * Stop a background sign-in that ANOTHER server process on this computer
- * started and that holds the cross-process lock, so sign_out can cancel a
- * sign-in whichever app began it. Only an "automatic" owner is stopped (a
+ * started and that holds the cross-process lock, so sign_out and
+ * `auth --logout` can cancel a sign-in whichever app began it. Only an "automatic" owner is stopped (a
  * person's `auth` run in a terminal never is), and only after its command
  * line confirms it is this package's sign-in child: the PID comes from a file,
  * and a PID the system has since reused must never be killed. That check
- * needs ps, so on Windows nothing is stopped and sign_out reports the sign-in
- * as one it cannot cancel. Its own server's waiting calls are answered
+ * needs ps, so on Windows nothing is stopped and sign_out or `auth --logout`
+ * reports the sign-in as one it cannot cancel. Its own server's waiting calls are answered
  * "cancelled" (see the close handler in spawnAuth). The dead owner leaves a
  * stale lock the next lock holder reclaims. Resolves true once it has exited.
  */
+/**
+ * True when a `ps` command line is this package's background sign-in child:
+ * `auth-cli.js` as a whole path segment, followed later by a standalone
+ * `--automatic`. The runtime binary is not checked, since an app may run the
+ * server on an embedded runtime that isn't named node.
+ */
+export function isAutomaticSignInCommand(command) {
+    return /(?:^|[\s/\\])auth-cli\.js\s(?:.*\s)?--automatic(?:\s|$)/.test(command.trim());
+}
 export async function stopAutomaticSignIn(lockPath) {
     if (process.platform === "win32")
         return false;
@@ -266,17 +275,20 @@ export async function stopAutomaticSignIn(lockPath) {
     catch {
         return false;
     }
-    if (!/auth-cli\.js\b/.test(command) || !command.includes("--automatic"))
+    if (!isAutomaticSignInCommand(command))
         return false;
-    log("WARN", `Cancelling another app's background sign-in (pid ${pid}) for sign_out`);
+    log("WARN", `Cancelling another app's background sign-in (pid ${pid}) to sign out`);
     forceStop(pid);
     const deadline = Date.now() + CANCEL_WAIT_MS;
     while (Date.now() < deadline) {
+        // Only "no such process" means it exited: EPERM is a live process this
+        // user cannot signal, which the SIGKILL did not stop either.
         try {
             process.kill(pid, 0);
         }
-        catch {
-            return true;
+        catch (error) {
+            if (error.code === "ESRCH")
+                return true;
         }
         await new Promise((resolve) => setTimeout(resolve, 50));
     }

package/build/auth/logout.js

@@ -3,8 +3,9 @@
  *
  * `auth --logout`: end the saved Brightspace session on this computer early.
  *
- * This is a local sign-out only. It deletes the files that let the next tool
- * call skip the browser, so that call does a full sign-in. It does not log out
+ * This is a local sign-out only. It first stops a background sign-in an AI
+ * app started (as sign_out does), then deletes the files that let the next
+ * tool call skip the browser, so that call does a full sign-in. It does not log out
  * of Microsoft or D2L on their servers, and it leaves the saved password,
  * config.json, and every credential-store entry (including the session
  * encryption key, which the next sign-in reuses) exactly as they were.
@@ -15,6 +16,7 @@ import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.j
 import { BROWSER_STATE_FILE, LEGACY_BROWSER_STATE_FILE } from "./browser-state-store.js";
 import { MICROSOFT_SESSION_FILE } from "./microsoft-session.js";
 import { authLockPath } from "./mfa-challenge.js";
+import { stopAutomaticSignIn } from "./auth-runner.js";
 import { SESSION_FILE, SessionStore } from "./session-store.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { resolveSessionLocation } from "../utils/config.js";
@@ -94,16 +96,38 @@ export async function clearSavedSession(sessionDir) {
 const KEPT = "Kept: your saved password, config.json, and any authenticator or credential-store entries.";
 const MEMORY_NOTE = "Other Brightspace apps open on this computer sign out on their next request. One you opened before updating may keep answering for up to an hour; quit and reopen it to sign it out right away.";
 const LOCAL_ONLY = "This only clears files on this computer. It does not sign you out of Microsoft or Brightspace on their servers.";
+const CANCELLED = "Cancelled the Brightspace sign-in that was waiting for approval, so the prompt or number from it no longer works.";
+const NEXT_PROMPT = "Microsoft keeps that prompt open for up to 5 minutes after sending it and sends this account no other until then, so the next sign-in can take that long to show a new number to approve.";
 /**
  * The `auth --logout` command. Resolves to the process exit code: 0 when the
- * session was cleared or there was nothing to clear, 2 when a sign-in is in
- * progress (the same code `auth` uses for that), 1 for anything else.
+ * session was cleared or there was nothing to clear, 2 when a sign-in or
+ * sign-out it can't stop holds the lock (the same code `auth` uses for that),
+ * 1 for anything else. A background sign-in an AI app started is stopped
+ * first; a person's `auth` run is never stopped.
  */
 export async function runLogout(options = {}) {
     const print = options.print ?? ((line) => console.error(line));
     try {
         const sessionDir = options.sessionDir ?? resolveSessionLocation().sessionDir;
-        const { removed } = await clearSavedSession(sessionDir);
+        // A sign-in an AI app started in the background holds the lock, and a
+        // terminal has no other way to stop it, so stop it as sign_out does.
+        const stopBackground = options.stopBackground ?? ((dir) => stopAutomaticSignIn(authLockPath(dir)));
+        const cancelled = await stopBackground(sessionDir);
+        if (cancelled)
+            print(CANCELLED);
+        let removed;
+        try {
+            ({ removed } = await clearSavedSession(sessionDir));
+        }
+        catch (error) {
+            // The lock was taken again between stopping one sign-in and clearing:
+            // most likely the AI app's next question started a new one.
+            if (cancelled && error instanceof AuthenticationInProgressError) {
+                print("Not signed out: a new sign-in started before the session could be cleared, so nothing was deleted. Run this command again.");
+                return 2;
+            }
+            throw error;
+        }
         if (removed.length === 0) {
             print("No saved Brightspace session was found on this computer, so there is nothing to clear.");
         }
@@ -114,13 +138,15 @@ export async function runLogout(options = {}) {
             print(`The next Brightspace request, or \`${AUTH_COMMAND}\`, will do a full sign-in.`);
         }
         print(MEMORY_NOTE);
+        if (cancelled)
+            print(NEXT_PROMPT);
         print(LOCAL_ONLY);
         return 0;
     }
     catch (error) {
         if (error instanceof AuthenticationInProgressError) {
-            print("Not signed out: a sign-in is in progress. Nothing was deleted.");
-            print("Wait for it to finish (or cancel it), then run this command again.");
+            print("Not signed out: a sign-in or sign-out this command can't stop is in progress, so nothing was deleted.");
+            print("If it is an `auth` run in another terminal, finish or close it there. On Windows, a sign-in an AI app started can't be stopped from here: wait for it to finish (up to 5 minutes). Then run this command again.");
             return 2;
         }
         if (error instanceof RemoveError) {

package/build/auth/token-manager.js

@@ -262,6 +262,9 @@ export class TokenManager {
                 capturedAt: now,
                 expiresAt: now + FAR_FUTURE_MS,
                 source: "env",
+                // The token answers API calls; web pages such as course files only
+                // accept the session cookie, so keep it when both were pasted.
+                ...(this.envSessionCookie ? { cookieHeader: this.envSessionCookie } : {}),
             };
         }
         return {

package/build/doctor.js

@@ -28,7 +28,8 @@ import { describeShortcuts } from "./utils/two-factor-shortcuts.js";
 import { discoverVersions } from "./api/version-discovery.js";
 import { D2LApiClient } from "./api/client.js";
 import { fetchLatestVersion, isNewerVersion, safeVersionLabel, installKindOf, } from "./utils/update-checker.js";
-import { SETUP_COMMAND, AUTH_COMMAND, GLOBAL_INSTALL_COMMAND, CLEAR_NPX_CACHE_COMMAND, prepareCommand, signInCommand, } from "./utils/commands.js";
+import { SETUP_COMMAND, AUTH_COMMAND, GLOBAL_INSTALL_COMMAND, CLEAR_NPX_CACHE_COMMAND, prepareCommand, signInCommand, envCredentialRejectedMessage, } from "./utils/commands.js";
+import { ApiError } from "./api/errors.js";
 import { chromiumReady, chromiumStatus, dependencyRepairHint, BROWSER_REPAIR_COMMAND } from "./utils/browser-install.js";
 import { nodeVersionSupported, readOnlyTokenManager, readSavedSessionToken, sessionDirFor } from "./utils/saved-session.js";
 // Tests import this from doctor.ts.
@@ -236,6 +237,11 @@ async function checkSession(deps, baseUrl, sessionDir, envAccessToken, envSessio
         : `Not signed in yet — run this in a terminal: ${signInCommand(baseUrl)}`;
     try {
         const token = await deps.getSessionToken(baseUrl, sessionDir, envAccessToken, envSessionCookie);
+        // A pasted credential is used as given, so nothing was issued here: the
+        // course check below is what shows whether Brightspace accepts it.
+        const pasted = envAccessToken ? "D2L_ACCESS_TOKEN" : envSessionCookie ? "D2L_SESSION_COOKIE" : undefined;
+        if (token && pasted)
+            return { ok: true, result: pass("session", `Using the credential in ${pasted}; the course check below shows whether Brightspace accepts it`) };
         if (token)
             return { ok: true, result: pass("session", "Saved sign-in works — a token was issued without opening a browser") };
         return { ok: false, result: problem("session", failMessage) };
@@ -262,6 +268,14 @@ async function checkCourses(deps, baseUrl, sessionDir, envAccessToken, envSessio
         return pass("courses", `Found ${label} course${count === 1 ? "" : "s"} on Brightspace`);
     }
     catch (error) {
+        const rejected = error instanceof ApiError && error.status === 401
+            ? envCredentialRejectedMessage(envAccessToken, envSessionCookie)
+            : undefined;
+        if (rejected)
+            return problem("courses", `Brightspace refused the course list. ${rejected}`);
+        if (error instanceof ApiError && error.status === 401) {
+            return problem("courses", `Brightspace refused the saved sign-in when loading your courses — sign in again: ${AUTH_COMMAND}`);
+        }
         const detail = error instanceof Error ? sanitizeErrorDetail(error.message) : "an unknown error";
         return problem("courses", `Could not load your courses (${detail}) — run doctor again after checking your connection.`);
     }

package/build/server.js

@@ -8,7 +8,8 @@ import { TokenManager, AuthRunner } from "./auth/index.js";
 import { D2LApiClient } from "./api/index.js";
 import { trackToolActivity } from "./utils/dev-activity.js";
 import { log } from "./utils/logger.js";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.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 { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 /**
  * Build the shared runtime. Nothing here reaches Brightspace: API versions
@@ -48,11 +49,7 @@ export function createRuntime(config, version) {
         baseUrl: config.baseUrl,
         tokenManager,
         onAuthExpired: authRunner ? () => authRunner.run(currentMfaAnnouncer()) : undefined,
-        authExpiredMessage: config.envAccessToken
-            ? "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set."
-            : config.envSessionCookie
-                ? "The pasted D2L_SESSION_COOKIE has expired. Copy a fresh d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser and update the environment variable; this server does not fall back to a browser login while D2L_SESSION_COOKIE is set."
-                : undefined,
+        authExpiredMessage: envCredentialRejectedMessage(config.envAccessToken, config.envSessionCookie),
     });
     return { config, version, tokenManager, apiClient, authRunner };
 }
@@ -87,7 +84,7 @@ export function createMcpServer(runtime) {
     registerGetAssignmentFiles(server, apiClient, config.baseUrl);
     registerGetAnnouncementFiles(server, apiClient);
     registerGetCourseContent(server, apiClient);
-    registerDownloadFile(server, apiClient);
+    registerDownloadFile(server, apiClient, config.envSessionCookie ? ENV_COOKIE_REJECTED : config.envAccessToken ? COURSE_FILE_NEEDS_COOKIE : undefined);
     registerGetClasslistEmails(server, apiClient);
     registerGetRoster(server, apiClient);
     registerGetMyGroups(server, apiClient);

package/build/tools/download-file.js

@@ -261,10 +261,21 @@ function extensionNote(requestedFilename, saved) {
             `not the format the requested name implied. Open it with an application that reads ${savedExt} files.`,
     };
 }
+/**
+ * Course files need a Brightspace web session, which D2L_ACCESS_TOKEN alone
+ * does not carry, and signing in again would not give it one.
+ */
+export const COURSE_FILE_NEEDS_COOKIE = "Course files are served only to a signed-in Brightspace web session, and D2L_ACCESS_TOKEN alone carries none. Set D2L_SESSION_COOKIE as well (a d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser) and restart the server.";
 /**
  * Register download_file tool
  */
-export function registerDownloadFile(server, apiClient) {
+export function registerDownloadFile(server, apiClient, 
+/**
+ * The fix to show when the session cookie a course file needs is missing
+ * or refused, set when the server runs on a pasted credential: there is no
+ * browser sign-in behind it, so signing in again would not help.
+ */
+cookieRejectedMessage) {
     server.registerTool("download_file", {
         title: "Download File",
         description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. The directory must already exist; it is not created for you. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
@@ -309,7 +320,7 @@ export function registerDownloadFile(server, apiClient) {
                 const filePath = parseCoursePath(coursePath, courseId, apiClient.origin);
                 if (typeof filePath !== "string")
                     return errorResponse(filePath.error, "invalidInput");
-                return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename);
+                return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename, cookieRejectedMessage);
             }
             else if (topicId !== undefined) {
                 // Content file download
@@ -343,10 +354,12 @@ export function registerDownloadFile(server, apiClient) {
  * topics, so they have no topicId. Brightspace serves them to the signed-in
  * web session, not to the API token, so this goes through the session cookie.
  */
-async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename) {
+async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename, cookieRejectedMessage) {
     log("INFO", `Downloading course file: courseId=${courseId}, path=${filePath}`);
     const response = await apiClient.getPageRaw(`${QUICKLINK_PATH}?ou=${courseId}&type=coursefile&fileId=${encodeURIComponent(filePath)}`);
     if (!response) {
+        if (cookieRejectedMessage)
+            return errorResponse(cookieRejectedMessage, "auth");
         return errorResponse(`Course files are served only to a signed-in Brightspace web session, and there is no valid one: the session cookie is missing or has expired. Sign in again with \`${AUTH_COMMAND}\` and retry. A server that runs on D2L_ACCESS_TOKEN alone has no cookie: set D2L_SESSION_COOKIE as well, or sign in through the browser.`, "auth");
     }
     // A missing file or a refused one can come back as an ordinary Brightspace

package/build/tools/get-syllabus.js

@@ -5,7 +5,7 @@
  */
 import { ApiError, DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetSyllabusSchema } from "./schemas.js";
-import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { stripD2lSessionParams } from "../utils/session-params.js";
 import { secureDownload, readBodyCapped } from "../utils/download-helpers.js";
@@ -61,9 +61,13 @@ async function tryLookup(lookup, fetch) {
         return { ok: true, value: await fetch() };
     }
     catch (error) {
+        // A pending or refused sign-in is not a permission the student lacks:
+        // the lookup never ran, so the call fails with the sign-in's answer.
+        if (isAuthUnavailable(error))
+            throw error;
         log("DEBUG", `get_syllabus: could not read ${LOOKUP_LABELS[lookup]}`, error);
         if (error instanceof ApiError) {
-            const forbidden = error.status === 401 || error.status === 403;
+            const forbidden = error.status === 403;
             return {
                 ok: false,
                 unavailable: { lookup, reason: forbidden ? "permission-denied" : "request-failed", status: error.status },

package/build/tools/index.js

@@ -14,7 +14,7 @@ export { registerGetAssignmentRubric } from "./get-assignment-rubric.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 { registerDownloadFile, COURSE_FILE_NEEDS_COOKIE } from "./download-file.js";
 export { registerGetClasslistEmails } from "./get-classlist-emails.js";
 export { registerGetRoster } from "./get-roster.js";
 export { registerGetMyGroups } from "./get-my-groups.js";

package/build/tools/search-course.js

@@ -5,7 +5,7 @@
  */
 import { ApiError } from "../api/index.js";
 import { SearchCourseSchema } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { fetchRootContent, buildContentTree } from "./get-course-content.js";
 import { fetchCourseNews, isPublishedNewsItem, mapNewsItem } from "./get-announcements.js";
@@ -188,6 +188,10 @@ export function registerSearchCourse(server, apiClient) {
                 entries.push(...flattenContentTree(tree));
             }
             catch (error) {
+                // A pending or refused sign-in is not a source that failed: the
+                // search never ran, and its answer carries what the user must do.
+                if (isAuthUnavailable(error))
+                    throw error;
                 log("DEBUG", `search_course: content fetch failed for course ${courseId}`, error);
                 notes.push(`content: ${describeFailure(error)}`);
             }
@@ -205,6 +209,10 @@ export function registerSearchCourse(server, apiClient) {
                 }
             }
             catch (error) {
+                // A pending or refused sign-in is not a source that failed: the
+                // search never ran, and its answer carries what the user must do.
+                if (isAuthUnavailable(error))
+                    throw error;
                 log("DEBUG", `search_course: announcements fetch failed for course ${courseId}`, error);
                 notes.push(`announcements: ${describeFailure(error)}`);
             }
@@ -234,12 +242,16 @@ export function registerSearchCourse(server, apiClient) {
                         // One forum's topics failing (e.g. no access) shouldn't drop
                         // every other forum, but it still has to be named in `note` so
                         // a search missing those topics never reads as complete.
+                        if (isAuthUnavailable(error))
+                            throw error;
                         log("DEBUG", `search_course: topics fetch failed for forum ${forum.ForumId}`, error);
                         notes.push(`discussions: topics in "${forum.Name}" ${describeFailure(error)}`);
                     }
                 }
             }
             catch (error) {
+                if (isAuthUnavailable(error))
+                    throw error;
                 log("DEBUG", `search_course: discussions fetch failed for course ${courseId}`, error);
                 notes.push(`discussions: ${describeFailure(error)}`);
             }

package/build/tools/sign-out.js

@@ -27,10 +27,10 @@ function text(message, isError = false) {
 /**
  * Register sign_out tool.
  *
- * The in-chat version of `auth --logout`, plus one thing the command does not
- * do: it first cancels a background sign-in still waiting on MFA, this
- * server's (AuthRunner.cancel, which answers every call waiting on it) or
- * another app's on this computer (stopAutomaticSignIn). A user who missed the
+ * The in-chat version of `auth --logout`. Both first cancel a background
+ * sign-in another app on this computer started (stopAutomaticSignIn); this
+ * one also cancels this server's own (AuthRunner.cancel, which answers every
+ * call waiting on it), which the command has no server to do. A user who missed the
  * prompt otherwise waited out its 5-minute window for a new one. Then it
  * deletes this computer's saved
  * session for the account the server is configured with (clearSavedSession,

package/build/utils/commands.js

@@ -28,6 +28,21 @@ export const DOCTOR_COMMAND = `npx -y ${PACKAGE_NAME}@latest doctor`;
 export const GLOBAL_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}@latest`;
 /** Drop cached npx copies so the next `@latest` genuinely refetches. */
 export const CLEAR_NPX_CACHE_COMMAND = "npx clear-npx-cache";
+/** What to do when Brightspace rejects a pasted D2L_ACCESS_TOKEN. */
+export const ENV_TOKEN_REJECTED = "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set.";
+/** What to do when Brightspace rejects a pasted D2L_SESSION_COOKIE. */
+export const ENV_COOKIE_REJECTED = "The pasted D2L_SESSION_COOKIE has expired. Copy a fresh d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser and update the environment variable; this server does not fall back to a browser login while D2L_SESSION_COOKIE is set.";
+/**
+ * The fix for a rejected credential pasted into the environment, or undefined
+ * when neither is set. D2L_ACCESS_TOKEN wins, as it does for signing in.
+ */
+export function envCredentialRejectedMessage(envAccessToken, envSessionCookie) {
+    if (envAccessToken)
+        return ENV_TOKEN_REJECTED;
+    if (envSessionCookie)
+        return ENV_COOKIE_REJECTED;
+    return undefined;
+}
 /**
  * The school's flag for a setup command, or `--url <origin>` for a school
  * with no preset. An unreadable URL gives no school at all, which `setup`

package/package.json

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