brightspace-mcp-server 3.13.9 → 3.13.11

package/README.md

@@ -77,6 +77,7 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 | Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura, including BoilerCast LTI links, and YouTube) |
 | Calendar | "When is my midterm?" · "Is lab cancelled on Thursday?" |
 | For instructors and TAs | "Which students haven't submitted Lab 4 yet?" · "What feedback did I leave on this student's homework?" · "Download that student's submitted PDF" (students see a clear "instructor access required" note) |
+| Signing out | "Sign me out of Brightspace" (your AI app may ask you to confirm first; details under [When it asks you to sign in](#when-it-asks-you-to-sign-in)) |
 
 ## Prompts
 
@@ -124,7 +125,7 @@ sits beside your password, so on **this** computer your two factors become one.
 anyone who only has your password, and it changes nothing for your other devices. Full enrollment
 steps: [docs/sign-in.md](docs/sign-in.md#answering-code-challenges-without-your-phone).
 
-**To sign out early** (on a shared computer, say), run `npx -y brightspace-mcp-server@latest auth --logout`. 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. An AI app that is already running can keep answering until its current access token expires; restart the app to drop it right away. It only clears this computer; it does not sign you out of Microsoft or Brightspace anywhere else. If a sign-in is in progress, it refuses and deletes nothing.
+**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. If a sign-in is in progress, it refuses and deletes nothing.
 
 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/api/client.js

@@ -132,6 +132,13 @@ export class D2LApiClient {
      * Adapted from JhostinAleck/brightspace-mcp (MIT) — RequestCoalescer.ts.
      */
     pendingGets = new Map();
+    /**
+     * Bumped by clearCache(). A GET remembers the value it started under and
+     * stores its result only if it is unchanged, so a read begun with the old
+     * session cannot refill a cache that was cleared (sign-out) while it was in
+     * flight.
+     */
+    cacheGeneration = 0;
     statsData = {
         statusClasses: { "2xx": 0, "401": 0, "403": 0, "404": 0, "429": 0, "5xx": 0, other: 0 },
         networkErrors: 0,
@@ -258,6 +265,13 @@ export class D2LApiClient {
         // ten minutes of due dates to get_upcoming_due_dates. Trusting the
         // surviving entry served the longer caller's staleness to the shorter one.
         if (options?.ttl) {
+            // The saved session may have been deleted by another process (logout),
+            // or replaced by a different account's. A signed-out server must not
+            // answer from memory, so drop every cached response and let this read
+            // take the normal path. Only asked when something is cached, so a cold
+            // cache costs nothing.
+            if (this.cache.size > 0 && await this.tokenManager.sessionChanged?.())
+                this.clearCache();
             const age = this.cache.ageOf(path);
             if (age !== undefined && age <= options.ttl) {
                 log("DEBUG", `Cache hit: ${path}`);
@@ -275,10 +289,11 @@ export class D2LApiClient {
             log("DEBUG", `Coalescing GET onto an in-flight request: ${path}`);
             return pending;
         }
+        const generation = this.cacheGeneration;
         const inFlight = (async () => {
             const resolved = await this.resolvePath(path);
             const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token));
-            if (options?.ttl) {
+            if (options?.ttl && generation === this.cacheGeneration) {
                 this.cache.set(path, data, options.ttl);
                 log("DEBUG", `Cached response for ${path} (TTL: ${options.ttl}ms)`);
             }
@@ -633,9 +648,13 @@ export class D2LApiClient {
         return `/d2l/api/le/${LE_VERSION}${path}`;
     }
     /**
-     * Clear all cached responses.
+     * Clear all cached responses, and stop later callers joining GETs already
+     * in flight (they began under the session being discarded; those callers
+     * still get their own answer, but it is not remembered).
      */
     clearCache() {
+        this.cacheGeneration++;
+        this.pendingGets.clear();
         this.cache.clear();
         log("DEBUG", "Cache cleared");
     }

package/build/auth/auth-lock.js

@@ -52,6 +52,12 @@ export class AuthenticationInProgressError extends Error {
      * CHALLENGE_FILE from this one.
      */
     challenge;
+    /**
+     * How the auth lock's owner holds it, when the caller looked it up (see
+     * BrowserAuth.authenticate). Set only for the auth lock, never for the
+     * other locks that throw this same error.
+     */
+    ownerMode;
     constructor() {
         super("Authentication already in progress. Retry after the current authentication finishes.");
         this.name = "AuthenticationInProgressError";
@@ -98,6 +104,18 @@ export const lockOps = {
     kill: (pid, signal) => { process.kill(pid, signal); },
     isDead: isDeadImpl,
 };
+/**
+ * What a contender can tell about a lock's owner: how it holds the lock
+ * ("exclusive" reads back as "explicit", see readOwner) and whether that
+ * process is gone. undefined when there is no readable owner record, which
+ * is not proof the owner is gone (it may still be writing it).
+ */
+export async function inspectLockOwner(lockPath) {
+    const owner = await readOwner(lockPath);
+    if (!owner)
+        return undefined;
+    return { mode: owner.mode === "automatic" ? "automatic" : "explicit", gone: lockOps.isDead(owner) };
+}
 /** Remove only our fixed metadata names, after the directory was retired. */
 async function cleanRetired(lockPath) {
     await fs.unlink(path.join(lockPath, "owner.json")).catch(() => { });

package/build/auth/auth-runner.js

@@ -12,7 +12,8 @@ import { AuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { devActivity } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
-import { AUTOMATIC_PENDING_MARKER, RELAYED_CHALLENGE_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
+import { AUTOMATIC_PENDING_MARKER, RELAYED_CHALLENGE_MARKER, RELAYED_STARTING_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
+import { inspectLockOwner } from "./auth-lock.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
@@ -68,6 +69,27 @@ const RELAY_POLL_MS = 1000;
  * is over; the same digits showing up again are a new challenge.
  */
 const RELAY_TOLD_MS = 5 * 60 * 1000;
+/**
+ * A call that arrives this soon after another call was answered with an MFA
+ * challenge is that call's sibling, not a retry. Claude Code runs tool calls
+ * that are not marked read-only one at a time, so a batch the model sent
+ * together arrives as a queue: each call lands moments after the previous one
+ * answered. Treated as retries, they each waited up to 45 seconds for an
+ * approval the user could not give yet, because the model cannot show the
+ * number until the whole batch is done. A real retry comes after the model
+ * has read the answer and written to the user, which takes longer than this.
+ * Measured from when the call arrived, and from the previous answer of either
+ * kind, so a queue of siblings chains (see SIBLING_CHAIN_MS).
+ */
+const SIBLING_GRACE_MS = 1500;
+/**
+ * How long a chain of sibling answers may run after the last answer that was
+ * not a sibling's. A queue of a few tool calls fits easily; a loop of calls
+ * that never stops to wait is cut off here and has to wait like a retry.
+ */
+const SIBLING_CHAIN_MS = 20000;
+/** What a call is told when the sign-in it waited on is still short of its challenge. */
+const STILL_SIGNING_IN = "Sign-in is still running in the background. Try again.";
 /**
  * Calls arriving within this long of a batch's first call count as that batch
  * (issue #212). A client running tool calls in parallel sends them within
@@ -152,7 +174,7 @@ export class AuthProcessError extends AuthError {
 function withinCallBudget(work, startedAt) {
     return new Promise((resolve, reject) => {
         const budgetTimer = setTimeout(() => {
-            reject(new AuthProcessError("inProgress", "Sign-in is still running in the background. Try again."));
+            reject(new AuthProcessError("inProgress", STILL_SIGNING_IN));
         }, Math.max(0, CALL_BUDGET_MS - (Date.now() - startedAt)));
         budgetTimer.unref?.();
         work.then((value) => { clearTimeout(budgetTimer); resolve(value); }, (error) => { clearTimeout(budgetTimer); reject(error); });
@@ -223,6 +245,13 @@ function dedupeChallenge(error, wave) {
     }
     return new AuthProcessError(error.kind, error.message, error.numberMatch, true, error.relayed);
 }
+/**
+ * Answers given to a queued sibling (see SIBLING_GRACE_MS). They extend the
+ * chain (Telling.last) but never restart it (Telling.anchor).
+ */
+const siblingAnswers = new WeakSet();
+/** Whether a call arriving at arrivedAt is a queued sibling of that telling. */
+const isQueuedSibling = (told, arrivedAt) => told !== undefined && arrivedAt - told.last < SIBLING_GRACE_MS && arrivedAt - told.anchor < SIBLING_CHAIN_MS;
 /** Identifies a challenge for "was this already reported to a caller". */
 const relayKey = (kind, numberMatch) => `${kind}:${numberMatch ?? ""}`;
 export class AuthRunner {
@@ -269,6 +298,18 @@ export class AuthRunner {
      * that sign-in instead of repeating the answer (see attendRelay).
      */
     relayTold = new Map();
+    /**
+     * When callers here were answered with this process's own pending
+     * challenge. A call arriving just after is a queued sibling and is
+     * answered at once (see SIBLING_GRACE_MS).
+     */
+    challengeTold = null;
+    /**
+     * What the current child reported when it only relayed another process's
+     * sign-in. A later call answers from it instead of joining that child,
+     * which can linger for seconds after it has said everything it will say.
+     */
+    relayProbe = null;
     scriptPath;
     timeoutMs;
     onProgress;
@@ -281,6 +322,16 @@ export class AuthRunner {
         this.onProgress = options.onProgress;
         this.sessionDir = options.sessionDir;
     }
+    /**
+     * Whether this process has a sign-in child running: true from the moment it
+     * is spawned (before the child has taken the cross-process sign-in lock, so
+     * a lock check alone would miss it) until the child exits, even after the
+     * caller that started it was answered early with an MFA challenge. Read-only;
+     * sign_out uses it to refuse to delete a session a sign-in is about to write.
+     */
+    busy() {
+        return this.inFlight !== null || this.childDone !== null;
+    }
     /**
      * Authenticate, joining the login this process already started if there is
      * one. Returns true on success and throws a useful error on failure.
@@ -298,6 +349,9 @@ export class AuthRunner {
      * the next call to join.
      */
     async run(onChallenge) {
+        const sibling = this.queuedSiblingAnswer(Date.now());
+        if (sibling)
+            throw sibling;
         // Synchronous, before any await: calls in one tick cannot split a batch.
         const wave = this.joinWave();
         // Also synchronous: what was already told BEFORE this call, so siblings in
@@ -310,31 +364,61 @@ export class AuthRunner {
         }
         catch (error) {
             this.noteRelayReported(error);
-            throw dedupeChallenge(error, wave);
+            const answer = dedupeChallenge(error, wave);
+            if (answer instanceof AuthProcessError && answer.kind === "mfaPending" && !answer.duplicate && !answer.relayed) {
+                const now = Date.now();
+                this.challengeTold = { anchor: now, last: now };
+            }
+            throw answer;
         }
         finally {
             this.waiting -= 1;
             this.lastAttendedAt = Date.now();
         }
     }
+    /**
+     * The answer for a call queued right behind one that was just answered
+     * with this process's pending challenge
+     * (see SIBLING_GRACE_MS), or null when this call should run normally.
+     */
+    queuedSiblingAnswer(arrivedAt) {
+        const pending = this.pendingChallenge;
+        const told = this.challengeTold;
+        if (!this.childDone || pending?.kind !== "mfaPending" || !told || !isQueuedSibling(told, arrivedAt))
+            return null;
+        told.last = arrivedAt;
+        // In full, not the short sibling line: if the answer before it was lost,
+        // this one still carries the digits (#201). It never reaches catch in
+        // run(), so it extends the chain without restarting it.
+        return new AuthProcessError(...mfaPendingFailure(pending.numberMatch), pending.numberMatch);
+    }
+    /** Relayed challenges already told to a caller here, and when (a snapshot). */
     relayChallengesTold() {
         const now = Date.now();
-        const told = new Set();
+        const told = new Map();
         for (const [key, at] of this.relayTold) {
-            if (now - at > RELAY_TOLD_MS)
+            if (now - at.last > RELAY_TOLD_MS)
                 this.relayTold.delete(key);
             else
-                told.add(key);
+                told.set(key, { ...at });
         }
         return told;
     }
     /** A relayed challenge that went back to a caller counts as told. */
     noteRelayReported(error) {
-        if (!(error instanceof AuthProcessError) || !error.relayed)
+        if (!(error instanceof AuthProcessError) || !error.relayed || error.duplicate)
             return;
         if (error.kind !== "mfaPending" && error.kind !== "automaticPending")
             return;
-        this.relayTold.set(relayKey(error.kind, error.numberMatch), Date.now());
+        const key = relayKey(error.kind, error.numberMatch);
+        const now = Date.now();
+        const told = this.relayTold.get(key);
+        // A sibling's answer extends the chain but does not restart it, or a loop
+        // of quick calls could keep every one of them from waiting.
+        if (told && siblingAnswers.has(error))
+            told.last = now;
+        else
+            this.relayTold.set(key, { anchor: now, last: now });
     }
     joinWave() {
         const now = Date.now();
@@ -393,14 +477,25 @@ export class AuthRunner {
      * relay, so every caller waits.
      */
     attendRelay(error, startedAt, onChallenge, toldBefore) {
-        const retry = toldBefore.has(relayKey(error.kind, error.numberMatch));
+        const told = toldBefore.get(relayKey(error.kind, error.numberMatch));
+        // startedAt is when this call arrived, not when its child finished: a
+        // queued call is a sibling however long the lock check took.
+        if (error.kind === "mfaPending" && isQueuedSibling(told, startedAt)) {
+            // Queued right behind the call that was told (see SIBLING_GRACE_MS):
+            // answer in full at once.
+            const sibling = new AuthProcessError(error.kind, error.message, error.numberMatch, false, true);
+            siblingAnswers.add(sibling);
+            throw sibling;
+        }
+        const retry = told !== undefined;
         if (error.kind === "mfaPending" && onChallenge && !retry) {
             try {
                 onChallenge(error.numberMatch);
             }
             catch { /* Announcing must not interrupt authentication. */ }
         }
-        const waits = error.kind === "automaticPending" || (error.kind === "mfaPending" && retry);
+        // inProgress: the owner has not reached a challenge yet. Wait for one.
+        const waits = error.kind === "automaticPending" || error.kind === "inProgress" || (error.kind === "mfaPending" && retry);
         if (!waits)
             throw error;
         const windowMs = pollWindowMs(Date.now() - startedAt);
@@ -426,21 +521,30 @@ export class AuthRunner {
     async awaitRelayedOwner(error, windowMs) {
         const lockPath = authLockPath(this.sessionDir);
         const deadline = Date.now() + windowMs;
-        let latest = {
-            automatic: error.kind === "automaticPending",
-            numberMatch: error.numberMatch,
-        };
+        let latest = error.kind === "inProgress" ? { phase: "starting" }
+            : error.kind === "automaticPending" ? { phase: "automatic" }
+                : { phase: "approval", numberMatch: error.numberMatch };
         for (;;) {
             const held = await fs.access(lockPath).then(() => true, () => false);
             if (!held) {
                 this.relayTold.clear();
                 return true;
             }
+            // The owner died without releasing its lock. Waiting longer only runs
+            // the clock down; the next call's sign-in reclaims the dead lock.
+            if ((await inspectLockOwner(lockPath))?.gone)
+                throw new AuthProcessError("inProgress", STILL_SIGNING_IN);
             const relayed = await relayChallenge(lockPath);
             if (relayed) {
-                latest = relayed.kind === "automatic"
-                    ? { automatic: true }
-                    : { automatic: false, numberMatch: relayed.numberMatch ?? (latest.automatic ? undefined : latest.numberMatch) };
+                const next = relayed.kind === "automatic"
+                    ? { phase: "automatic" }
+                    : { phase: "approval", numberMatch: relayed.numberMatch ?? (latest.phase === "approval" ? latest.numberMatch : undefined) };
+                // A challenge appearing while this caller waited on a sign-in that had
+                // none yet is what the user needs right now: answer with it at once.
+                if (next.phase === "approval" && latest.phase !== "approval") {
+                    throw new AuthProcessError(...mfaPendingFailure(next.numberMatch), next.numberMatch, false, true);
+                }
+                latest = next;
             }
             const remaining = deadline - Date.now();
             if (remaining <= 0)
@@ -450,7 +554,9 @@ export class AuthRunner {
                 timer.unref?.();
             });
         }
-        if (latest.automatic)
+        if (latest.phase === "starting")
+            throw new AuthProcessError("inProgress", STILL_SIGNING_IN, undefined, false, true);
+        if (latest.phase === "automatic")
             throw automaticPendingFailure(true);
         throw new AuthProcessError(...mfaPendingFailure(latest.numberMatch), latest.numberMatch, false, true);
     }
@@ -463,6 +569,12 @@ export class AuthRunner {
         // 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".
+        // That child only relayed another process's sign-in, and has said all it
+        // will: answer from its report rather than wait for it to exit.
+        if (this.childDone && this.relayProbe) {
+            const probe = this.relayProbe;
+            return Promise.reject(new AuthProcessError(probe.kind, probe.message, probe.numberMatch, false, true));
+        }
         if (this.childDone) {
             log("DEBUG", "Joining the background sign-in still running from an earlier call");
             return this.joinBackgroundChild(this.childDone, startedAt);
@@ -633,11 +745,14 @@ export class AuthRunner {
                     this.pendingChallenge = null;
                     this.challengeSignal = null;
                     this.wave = null;
+                    this.challengeTold = null;
+                    this.relayProbe = null;
                 }
             });
             trackedCompletion.catch(() => { });
             this.childDone = trackedCompletion;
             this.pendingChallenge = null;
+            this.relayProbe = null;
             let resolveChallengeSignal;
             this.challengeSignal = new Promise((res) => { resolveChallengeSignal = res; });
             // Records the challenge (number or not) and wakes a joiner waiting in
@@ -683,9 +798,11 @@ export class AuthRunner {
                 }
                 if (firstChallenge)
                     resolveChallengeSignal();
-                if (!callerSettled) {
-                    settleCaller(new AuthProcessError(...mfaPendingFailure(this.pendingChallenge?.numberMatch), this.pendingChallenge?.numberMatch, false, relayed));
-                }
+                const answer = new AuthProcessError(...mfaPendingFailure(this.pendingChallenge?.numberMatch), this.pendingChallenge?.numberMatch, false, relayed);
+                if (relayed)
+                    this.relayProbe = answer;
+                if (!callerSettled)
+                    settleCaller(answer);
             };
             /**
              * The child is typing its own verification code. Watched for abandonment
@@ -700,7 +817,10 @@ export class AuthRunner {
                 this.pendingChallenge = { kind: "automaticPending" };
                 startWatching();
                 resolveChallengeSignal();
-                settleCaller(automaticPendingFailure(relayed));
+                const answer = automaticPendingFailure(relayed);
+                if (relayed)
+                    this.relayProbe = answer;
+                settleCaller(answer);
             };
             // 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
@@ -768,6 +888,18 @@ export class AuthRunner {
                     // marker that follows it settles the caller.
                     relayed = true;
                 }
+                else if (line === RELAYED_STARTING_MARKER) {
+                    // Another process's background sign-in holds the lock and has no
+                    // challenge yet. With a lock to watch, answer now so the caller can
+                    // wait on it (attendRelay); the child may linger a few seconds more.
+                    // Without one, the close handler answers "busy" as it always has.
+                    relayed = true;
+                    if (this.sessionDir) {
+                        const answer = new AuthProcessError("inProgress", STILL_SIGNING_IN, undefined, false, true);
+                        this.relayProbe = answer;
+                        settleCaller(answer);
+                    }
+                }
                 else {
                     log("DEBUG", line);
                 }
@@ -807,9 +939,13 @@ export class AuthRunner {
                     // nothing to approve, so say that rather than "busy".
                     else if (code === 2 && automaticSeen)
                         failures[2] = ["automaticPending", automaticPendingFailure().message];
+                    // Busy because another process's sign-in has not reached a
+                    // challenge yet: the caller can wait on it (see attendRelay).
+                    else if (code === 2 && relayed && this.sessionDir)
+                        failures[2] = ["inProgress", STILL_SIGNING_IN];
                     const [kind, message] = failures[code ?? -1] ?? ["failed", `Authentication failed. Run ${AUTH_COMMAND} to try again.`];
                     kill("SIGKILL");
-                    const challenged = kind === "mfaPending" || kind === "automaticPending";
+                    const challenged = kind === "mfaPending" || kind === "automaticPending" || kind === "inProgress";
                     finishChild(new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined, false, relayed && challenged));
                 }
             });

package/build/auth/browser-auth.js

@@ -10,7 +10,7 @@ import { createSSOFlow, UnsupportedAuthenticationError, MfaApprovalError, Automa
 import { isDuoPrompt } from "./duo-mfa.js";
 import { BrowserStateStore } from "./browser-state-store.js";
 import { hasNewerEntraState, recordMicrosoftSession } from "./microsoft-session.js";
-import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
+import { acquireProcessLock, AuthenticationInProgressError, inspectLockOwner } from "./auth-lock.js";
 import { authLockPath, publishAutomaticProgress, publishChallenge, relayChallenge } from "./mfa-challenge.js";
 import { AuthCooldown } from "./auth-cooldown.js";
 import { mintAccessToken } from "./token-mint.js";
@@ -126,8 +126,10 @@ export class BrowserAuth {
         const release = await acquireProcessLock(this.lockPath, { mode: options.automatic ? "automatic" : "explicit" }).catch(async (error) => {
             // Hand back the number the owner is showing, so this caller's user can
             // approve that sign-in instead of being told only to wait for it.
-            if (error instanceof AuthenticationInProgressError)
+            if (error instanceof AuthenticationInProgressError) {
                 error.challenge = await relayChallenge(this.lockPath);
+                error.ownerMode = (await inspectLockOwner(this.lockPath))?.mode;
+            }
             throw error;
         });
         try {

package/build/auth/logout.js

@@ -20,7 +20,7 @@ import { AUTH_COMMAND } from "../utils/commands.js";
 import { resolveSessionLocation } from "../utils/config.js";
 /** Browser state files other than the session token itself, in the order they are deleted. */
 const BROWSER_STATE_FILES = [BROWSER_STATE_FILE, LEGACY_BROWSER_STATE_FILE, MICROSOFT_SESSION_FILE];
-class RemoveError extends Error {
+export class RemoveError extends Error {
     file;
     constructor(file, cause) {
         super(`Could not remove ${file}: ${cause instanceof Error ? cause.message : String(cause)}`);
@@ -39,6 +39,18 @@ async function removeIfPresent(file) {
         throw new RemoveError(path.basename(file), error);
     }
 }
+/** SessionStore.remove() throws SessionStoreError; report it like every other file that would not delete. */
+async function removeSessionFile(sessionDir) {
+    try {
+        return await new SessionStore(sessionDir).remove();
+    }
+    catch (error) {
+        // A session write that holds its lock too long is still "in progress", not a file that won't delete.
+        if (error instanceof AuthenticationInProgressError)
+            throw error;
+        throw new RemoveError(SESSION_FILE, error);
+    }
+}
 /**
  * Delete the saved session files in one account's session directory.
  *
@@ -67,7 +79,7 @@ export async function clearSavedSession(sessionDir) {
     const release = await acquireProcessLock(authLockPath(sessionDir), { mode: "exclusive" });
     try {
         const removed = [];
-        if (await new SessionStore(sessionDir).remove())
+        if (await removeSessionFile(sessionDir))
             removed.push(SESSION_FILE);
         for (const name of BROWSER_STATE_FILES) {
             if (await removeIfPresent(path.join(sessionDir, name)))
@@ -80,7 +92,7 @@ export async function clearSavedSession(sessionDir) {
     }
 }
 const KEPT = "Kept: your saved password, config.json, and any authenticator or credential-store entries.";
-const MEMORY_NOTE = "A running Brightspace MCP server may still hold an access token in memory until it expires. Restart your AI client to drop it right away.";
+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.";
 /**
  * The `auth --logout` command. Resolves to the process exit code: 0 when the

package/build/auth/mfa-challenge.js

@@ -86,6 +86,26 @@ export const AUTOMATIC_PENDING_MARKER = "AUTH_AUTOMATIC_PENDING";
  * needed.
  */
 export const RELAYED_CHALLENGE_MARKER = "AUTH_RELAYED";
+/**
+ * Printed alone, instead of the relay marker and a challenge, when the lock
+ * belongs to another server's background sign-in that has not reached a
+ * challenge yet. The parent can wait on that sign-in (AuthRunner.attendRelay).
+ */
+export const RELAYED_STARTING_MARKER = "AUTH_RELAYED_STARTING";
+/**
+ * What an automatic child prints when its sign-in found the auth lock held:
+ * the owner's challenge after the relay marker; or, when a background sign-in
+ * (mode "automatic") holds the lock with no challenge yet, the starting
+ * marker. Nothing for anything else, so the parent answers "busy": an
+ * explicit `auth` run in a terminal never publishes a challenge, and an owner
+ * that cannot be identified may be a stuck lock someone has to clear.
+ */
+export function relayedLockLines(challenge, ownerMode) {
+    if (challenge) {
+        return [RELAYED_CHALLENGE_MARKER, challenge.kind === "automatic" ? AUTOMATIC_PENDING_MARKER : challengeMarker(challenge.numberMatch)];
+    }
+    return ownerMode === "automatic" ? [RELAYED_STARTING_MARKER] : [];
+}
 /** The stdout marker AuthRunner parses for a challenge. */
 export function challengeMarker(numberMatch) {
     return numberMatch ? `MFA_NUMBER:${numberMatch}` : "MFA_PENDING";

package/build/auth/session-store.js

@@ -164,6 +164,29 @@ export class SessionStore {
             this.storeError("save", error);
         }
     }
+    /**
+     * A cheap identity for the saved session file, so a running server can tell
+     * "same file" from "signed out" from "signed out and signed in again". A
+     * single stat: nothing is read or decrypted and no lock is taken, so it is
+     * cheap enough to ask before every request.
+     *
+     * - `null`: the file definitely does not exist (ENOENT). Signed out.
+     * - a string: the file exists; it changes whenever the file is replaced or
+     *   rewritten (inode, size, and the modified, changed and birth times in
+     *   nanoseconds; Windows may report inode 0, which the times and size still
+     *   distinguish).
+     * - `undefined`: the stat failed for any other reason. An unreadable
+     *   directory is not evidence of a sign-out, so callers keep what they have.
+     */
+    async fingerprint() {
+        try {
+            const stat = await fs.stat(this.sessionFilePath, { bigint: true });
+            return `${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}:${stat.birthtimeNs}`;
+        }
+        catch (error) {
+            return error.code === "ENOENT" ? null : undefined;
+        }
+    }
     /** Missing files return null. Damaged or inaccessible secrets fail without MFA. */
     async load() {
         try {

package/build/auth/token-manager.js

@@ -30,6 +30,21 @@ export class TokenManager {
     /** Single in-flight mint, so concurrent callers share one request. */
     mintInFlight = null;
     rejectedAccessToken = null;
+    /**
+     * The saved session this process last read or wrote, as the account it
+     * belongs to. Kept even while cachedToken is null (an unusable token on
+     * disk), so a later sign-in can still be compared with the account that
+     * the in-memory state, and the API client's response cache, were built for.
+     * Null once the session is known to be gone.
+     */
+    identityToken = null;
+    /** SessionStore.fingerprint() of the file when identityToken was read or written. */
+    observedFingerprint;
+    /**
+     * Set when the session was signed out or replaced by a different account
+     * since sessionChanged() last answered. Errs toward true.
+     */
+    sessionReplaced = false;
     constructor(sessionDirOrOptions) {
         const options = typeof sessionDirOrOptions === "string" || sessionDirOrOptions === undefined
             ? { sessionDir: sessionDirOrOptions }
@@ -64,13 +79,20 @@ export class TokenManager {
             }
             return token;
         }
-        // Check memory cache first
+        // Check memory cache first, after asking whether the saved session is
+        // still the one this process remembers. Another process may have signed
+        // out (deleted it), or signed in again, since this token was cached; when
+        // it has, the memory is dropped or refreshed from disk here. Skipped when
+        // nothing is remembered, so a cold start costs no extra stat.
+        await this.syncWithDisk();
         if (this.cachedToken && this.isUsable(this.cachedToken)) {
             log("DEBUG", "Returning cached token");
             return this.cachedToken;
         }
         // Try loading from disk
         const storedToken = await this.sessionStore.load();
+        if (storedToken)
+            await this.observe(storedToken);
         if (storedToken && this.isUsable(storedToken)) {
             log("DEBUG", "Loaded valid token from session store");
             this.cachedToken = storedToken;
@@ -89,6 +111,120 @@ export class TokenManager {
         log("DEBUG", "No valid token available");
         return null;
     }
+    /**
+     * Whether the saved session was signed out or replaced by a different
+     * account since this was last asked, for example by `brightspace-auth
+     * --logout` or the sign_out tool running in another process, or a new
+     * sign-in as someone else. When it was, anything built under the old
+     * session (the API client's response cache) must not be trusted. Costs one
+     * stat while the file is unchanged.
+     *
+     * True when the file is missing, and when a reload shows a different
+     * account than the one remembered. Names are compared when both sides have
+     * one, otherwise the session cookie; with neither, the answer is true,
+     * because when unsure the safe move is to clear. The same account's token
+     * re-minted by another process (hourly) is not a change, so it does not
+     * wipe a cache that is still valid. The answer is true once per change.
+     * Always false for D2L_ACCESS_TOKEN / D2L_SESSION_COOKIE, which have no
+     * saved session. A failed stat answers false; a replaced file this process
+     * cannot read answers true (the in-memory token is still served, but cached
+     * responses are not trusted until the file reads again).
+     */
+    async sessionChanged() {
+        if (this.envAccessToken || this.envSessionCookie)
+            return false;
+        await this.syncWithDisk();
+        const changed = this.sessionReplaced;
+        this.sessionReplaced = false;
+        return changed;
+    }
+    /**
+     * Drop everything remembered about the saved session without touching any
+     * file: the cached token, a remembered rejection and the recorded file
+     * identity. The next getToken() reads the disk afresh. Call it right after
+     * deleting the session files (the sign_out tool does), so this process stops
+     * acting signed in even when another app has already signed in again and
+     * recreated the file, which a plain existence check could not tell apart.
+     * Also makes the next sessionChanged() answer true, so cached API responses
+     * are not served either.
+     */
+    forgetSession() {
+        this.cachedToken = null;
+        this.rejectedAccessToken = null;
+        this.identityToken = null;
+        this.observedFingerprint = undefined;
+        this.sessionReplaced = true;
+    }
+    /**
+     * Compare the saved file with what this process last saw of it, and bring
+     * memory in line: file gone, forget everything; file replaced or rewritten,
+     * reload it and adopt it (flagging a different account). A fingerprint
+     * that cannot be determined, or an unreadable replacement, keeps the
+     * current state, with an unreadable replacement flagged as changed.
+     * Does nothing, and costs nothing, when nothing is remembered.
+     */
+    async syncWithDisk() {
+        if (!this.identityToken && !this.rejectedAccessToken)
+            return;
+        const fingerprint = await this.sessionStore.fingerprint?.();
+        if (fingerprint === null) {
+            log("DEBUG", "The saved session is gone; dropping the in-memory token");
+            this.forgetSession();
+            return;
+        }
+        if (typeof fingerprint !== "string" || !this.identityToken || fingerprint === this.observedFingerprint)
+            return;
+        log("DEBUG", "The saved session changed on disk; reloading it");
+        let loaded;
+        try {
+            loaded = await this.sessionStore.load();
+        }
+        catch (error) {
+            // Cannot tell whose session this is. Keep serving the token in memory,
+            // do not record the fingerprint (so the next call tries again), and
+            // make sure cached responses are not trusted.
+            log("WARN", "The saved session changed but could not be read", error);
+            this.sessionReplaced = true;
+            return;
+        }
+        if (!loaded) {
+            this.forgetSession();
+            return;
+        }
+        this.adopt(loaded, fingerprint);
+        this.cachedToken = this.isUsable(loaded) ? loaded : null;
+    }
+    /**
+     * Remember `token` as the session now on disk. `fingerprint` is the file's
+     * identity from a stat taken before it was read; without one, it is taken
+     * now, after the read or write that produced `token`. If another process
+     * rewrote the file in the instant between that read or write and the stat,
+     * this records their file's identity against our token, so the change goes
+     * unnoticed until the next rewrite. That is acceptable: the token held is
+     * itself valid, and the window is microseconds wide.
+     */
+    adopt(token, fingerprint) {
+        if (this.identityToken && !this.sameAccount(this.identityToken, token))
+            this.sessionReplaced = true;
+        this.identityToken = token;
+        this.observedFingerprint = fingerprint ?? undefined;
+    }
+    async observe(token) {
+        this.adopt(token, await this.sessionStore.fingerprint?.());
+    }
+    /**
+     * Whether two sessions belong to the same account on the same tenant.
+     * Unknown is not the same: with no name on both sides and no shared cookie,
+     * this answers false.
+     */
+    sameAccount(a, b) {
+        if (a.tenantOrigin !== b.tenantOrigin)
+            return false;
+        if (a.uniqueName !== undefined && b.uniqueName !== undefined) {
+            return a.uniqueName.toLowerCase() === b.uniqueName.toLowerCase();
+        }
+        return a.cookieHeader !== undefined && a.cookieHeader === b.cookieHeader;
+    }
     /**
      * Build the token for D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE;
      * D2L_ACCESS_TOKEN wins when both are set. expiresAt is pushed far into the
@@ -163,7 +299,15 @@ export class TokenManager {
         // The auth CLI or another MCP process can finish a login while HTTP minting
         // is in flight. Its newer session wins over either result of this request.
         const current = await this.sessionStore.load();
-        if (current && !this.sameToken(current, stale)) {
+        if (!current) {
+            // Signed out while the mint was in flight. Saving a token now would
+            // quietly undo that, so drop everything and let the caller sign in.
+            log("DEBUG", "The saved session was removed during the refresh");
+            this.forgetSession();
+            return null;
+        }
+        if (!this.sameToken(current, stale)) {
+            await this.observe(current);
             this.cachedToken = current;
             if (this.isUsable(current))
                 return current;
@@ -187,6 +331,7 @@ export class TokenManager {
             };
             if (!await this.sessionStore.saveIfCurrent(token, stale))
                 return this.afterConcurrentChange();
+            await this.observe(token);
             this.cachedToken = token;
             this.rejectedAccessToken = null;
             log("INFO", "Minted a fresh access token from the session cookie");
@@ -197,6 +342,7 @@ export class TokenManager {
             if (!await this.sessionStore.clearIfCurrent(stale))
                 return this.afterConcurrentChange();
             this.cachedToken = null;
+            this.observedFingerprint = undefined;
             return null;
         }
         throw new TokenRefreshError(result.detail ?? "unexpected token service response");
@@ -206,6 +352,7 @@ export class TokenManager {
      */
     async setToken(token) {
         await this.sessionStore.save(token);
+        await this.observe(token);
         this.cachedToken = token;
         this.rejectedAccessToken = null;
         log("DEBUG", "Token cached and persisted");
@@ -215,6 +362,9 @@ export class TokenManager {
      */
     async clearToken() {
         this.cachedToken = null;
+        this.identityToken = null;
+        this.observedFingerprint = undefined;
+        this.sessionReplaced = true;
         await this.sessionStore.clear();
         log("DEBUG", "Token cleared from memory and disk");
     }
@@ -229,9 +379,17 @@ export class TokenManager {
             a.cookieHeader === b.cookieHeader && a.csrfToken === b.csrfToken && a.tenantOrigin === b.tenantOrigin;
     }
     async afterConcurrentChange() {
-        this.cachedToken = await this.sessionStore.load();
-        if (this.cachedToken && this.isUsable(this.cachedToken))
-            return this.cachedToken;
+        const loaded = await this.sessionStore.load();
+        if (!loaded) {
+            // Nothing is saved any more: the user signed out. That is not a refresh
+            // failure; the caller proceeds to the ordinary sign-in.
+            this.forgetSession();
+            return null;
+        }
+        await this.observe(loaded);
+        this.cachedToken = loaded;
+        if (this.isUsable(loaded))
+            return loaded;
         throw new TokenRefreshError("saved authentication changed during refresh");
     }
     /**

package/build/auth-cli.js

@@ -12,7 +12,7 @@ import { NativeCredentialStoreError } from "./auth/credential-store.js";
 import { retireLegacyProfile } from "./auth/legacy-profile.js";
 import { formatPhaseMarker } from "./auth/auth-phases.js";
 import { AuthenticationInProgressError } from "./auth/auth-lock.js";
-import { AUTOMATIC_PENDING_MARKER, RELAYED_CHALLENGE_MARKER, challengeMarker } from "./auth/mfa-challenge.js";
+import { AUTOMATIC_PENDING_MARKER, challengeMarker, relayedLockLines } from "./auth/mfa-challenge.js";
 import { runLogout } from "./auth/logout.js";
 import { configureDevActivity } from "./utils/dev-activity.js";
 import { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
@@ -111,11 +111,12 @@ async function main() {
         }
         // Another process's sign-in holds the lock and is showing a challenge:
         // pass it on, so this caller can tell its user what to approve.
-        if (automatic && error instanceof AuthenticationInProgressError && error.challenge) {
-            console.log(RELAYED_CHALLENGE_MARKER);
-            console.log(error.challenge.kind === "automatic"
-                ? AUTOMATIC_PENDING_MARKER
-                : challengeMarker(error.challenge.numberMatch));
+        // Before it has one, say that it is starting, so the caller can wait on
+        // it. Only the auth lock's own contention sets challenge/ownerMode
+        // (BrowserAuth.authenticate); any other lock stays a plain "busy".
+        if (automatic && error instanceof AuthenticationInProgressError) {
+            for (const line of relayedLockLines(error.challenge, error.ownerMode))
+                console.log(line);
         }
         process.exitCode = error instanceof NativeCredentialStoreError ? 5
             : code === "AUTH_IN_PROGRESS" ? 2

package/build/index.js

@@ -18,7 +18,7 @@ import { configureDevActivity, trackToolActivity } from "./utils/dev-activity.js
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.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, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -145,6 +145,7 @@ else {
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION, apiClient);
             registerSearchCourse(server, apiClient);
+            registerSignOut(server, config, apiClient, tokenManager, authRunner);
             // Instructor / TA dropbox tools (read-only) — 403 for a student account.
             registerGetDropboxFolders(server, apiClient);
             registerGetDropboxSubmissions(server, apiClient);
@@ -152,7 +153,7 @@ else {
             registerGetDropboxFeedback(server, apiClient);
             registerGetRubricsForObject(server, apiClient);
             registerDownloadDropboxSubmissionFile(server, apiClient);
-            log("DEBUG", "MCP tools registered (25 tools)");
+            log("DEBUG", "MCP tools registered (26 tools)");
             // Register MCP prompts — surfaced in clients (e.g. Claude Desktop) as a
             // picker, distinct from tools. Each one is a canned user message that
             // names our own tools by name, so a client with no idea what to ask
@@ -165,7 +166,7 @@ else {
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (25 tools, 4 prompts registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (26 tools, 4 prompts registered)");
             log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
         }
         catch (error) {

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

@@ -27,6 +27,7 @@ async function listNews(apiClient, courseId, newsId) {
 export function registerGetAnnouncementFiles(server, apiClient) {
     server.registerTool("get_announcement_files", {
         title: "Get Announcement Files",
+        annotations: { readOnlyHint: true },
         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) => {

package/build/tools/get-announcements.js

@@ -99,6 +99,7 @@ export function mapNewsItem(item) {
 export function registerGetAnnouncements(server, apiClient, config) {
     server.registerTool("get_announcements", {
         title: "Get Announcements",
+        annotations: { readOnlyHint: true },
         description: "Fetch announcements from one course with courseId, or all courses when omitted, newest first. count is 1-50 per page. Continue with offset= pagination.nextOffset until it is null. Pagination metadata is in a separate JSON text block for array responses, or the pagination field with modifiedSince. A false coverageComplete means some courses were not fetched: retry from offset 0 after recovery. Offsets reflect the current filtered list; new posts can shift pages. Attachments are listed per announcement; fetch them with download_file (newsId + fileId) or read them with get_announcement_files.",
         inputSchema: GetAnnouncementsSchema,
     }, async (args) => {

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

@@ -26,6 +26,7 @@ async function listFolders(apiClient, courseId, folderId) {
 export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
     server.registerTool("get_assignment_files", {
         title: "Get Assignment Files",
+        annotations: { readOnlyHint: true },
         description: "Read the files an instructor attached to an assignment: the spec or instructions PDF, a starter workbook, a rubric document. Call it with just courseId to see which assignments have attachments, then with folderId and fileId to read one. Use this when the user asks what an assignment requires, what the instructions say, or to summarize a handout. Returns the text itself. Use download_file instead when the user wants the file saved to disk.",
         inputSchema: GetAssignmentFilesSchema,
     }, async (args) => {

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

@@ -256,6 +256,7 @@ export async function fetchAssignmentRubrics(apiClient, courseId, assignmentId)
 export function registerGetAssignmentRubric(server, apiClient) {
     server.registerTool("get_assignment_rubric", {
         title: "Get Assignment Rubric",
+        annotations: { readOnlyHint: true },
         description: "Fetch the full grading rubric for a dropbox assignment: every criteria group, criterion, and achievement level with its points and description, plus the student's own graded outcome per criterion once it has been released. Use this when the user asks what a rubric wants, how an assignment will be graded, or why they got a particular score on a criterion.",
         inputSchema: GetAssignmentRubricSchema,
     }, async (args) => {

package/build/tools/get-assignments.js

@@ -425,6 +425,7 @@ function gradebookHeadsUp(raw, fetched, courseId, baseUrl) {
 export function registerGetAssignments(server, apiClient, config) {
     server.registerTool("get_assignments", {
         title: "Get Assignments",
+        annotations: { readOnlyHint: true },
         description: "Fetch assignments and quizzes for a specific course or all enrolled courses. Shows dropbox submissions and quizzes with due dates, status, and rubric info. Use this when the user asks about assignments, homework, what to submit, quizzes, or assignment details and rubrics. " +
             "Read submissionStatus/attemptStatus, not just submission/attemptsUsed, to decide whether something was turned in: some tenants deny students access to submission or attempt data, in which case the status is \"unknown\" even though submission is null or attemptsUsed is 0. Never report an \"unknown\" item as missing, unsubmitted, or not attempted - say it could not be verified and point the user to Brightspace.",
         inputSchema: GetAssignmentsSchema,

package/build/tools/get-calendar-events.js

@@ -15,6 +15,7 @@ const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
 export function registerGetCalendarEvents(server, apiClient, config) {
     server.registerTool("get_calendar_events", {
         title: "Get Calendar Events",
+        annotations: { readOnlyHint: true },
         description: "Fetch course calendar events — exams, midterms, labs, recitations, review sessions, schedule changes, and deadlines instructors typed straight onto the calendar — across all your courses or one course, in a time window (default: the next 7 days). Use this when the user asks when an exam is, what's on their calendar, or what's happening this week.",
         inputSchema: GetCalendarEventsSchema,
     }, async (args) => {

package/build/tools/get-classlist-emails.js

@@ -14,6 +14,7 @@ import { log } from "../utils/logger.js";
 export function registerGetClasslistEmails(server, apiClient) {
     server.registerTool("get_classlist_emails", {
         title: "Get Classlist Emails",
+        annotations: { readOnlyHint: true },
         description: "Fetch all email addresses for everyone in a course — instructors, TAs, and students. " +
             "Use this when the user wants a list of emails for a class, needs to email the whole class, " +
             "or wants contact info for everyone enrolled.",

package/build/tools/get-course-content.js

@@ -228,6 +228,7 @@ function countModules(tree) {
 export function registerGetCourseContent(server, apiClient) {
     server.registerTool("get_course_content", {
         title: "Get Course Content",
+        annotations: { readOnlyHint: true },
         description: "Fetch the content tree for a course showing modules, topics, files, and links. Use this when the user asks about course materials, lecture slides, uploaded files, content structure, or what's in a course module. Use moduleTitle to filter to a specific module (e.g. 'Labs', 'Staff', 'Homeworks') instead of fetching the entire tree. Use maxDepth to limit recursion depth for a table-of-contents view. A module or topic that isn't currently available carries isAvailable/availabilityStatus/availabilityMessage (and startDate/endDate when known) explaining why; absence of these fields means it's available now.",
         inputSchema: GetCourseContentSchema,
     }, async (args) => {

package/build/tools/get-discussions.js

@@ -34,6 +34,7 @@ export async function fetchForumTopics(apiClient, courseId, forumId) {
 export function registerGetDiscussions(server, apiClient) {
     server.registerTool("get_discussions", {
         title: "Get Discussions",
+        annotations: { readOnlyHint: true },
         description: "Fetch discussion board content for a course including forums, topics, and posts. Use this when the user asks about discussion boards, forum posts, class discussions, or wants to see what's been posted. Provide just courseId to list all forums and their topics. Add forumId to get topics and posts for a specific forum. Add both forumId and topicId to get all posts in a specific discussion topic.",
         inputSchema: GetDiscussionsSchema,
     }, async (args) => {

package/build/tools/get-dropbox-feedback.js

@@ -14,6 +14,7 @@ import { log } from "../utils/logger.js";
 export function registerGetDropboxFeedback(server, apiClient) {
     server.registerTool("get_dropbox_feedback", {
         title: "Get Dropbox Feedback",
+        annotations: { readOnlyHint: true },
         description: "Retrieve the existing feedback already saved for a specific user or group in a dropbox folder, " +
             "for an instructor or TA — score, graded state, feedback text, and rubric assessment detail. " +
             "Use this before drafting new feedback to see what has already been recorded. Requires " +

package/build/tools/get-dropbox-folders.js

@@ -23,6 +23,7 @@ function submissionTypeLabel(t) {
 export function registerGetDropboxFolders(server, apiClient) {
     server.registerTool("get_dropbox_folders", {
         title: "Get Dropbox Folders",
+        annotations: { readOnlyHint: true },
         description: "List all assignment/dropbox folders for a course, for an instructor or TA. Returns folder ID, " +
             "name, due date, start/end dates, submission type, visibility, and whether rubrics are attached. " +
             "Use this to discover folderId values before calling get_dropbox_submissions, " +

package/build/tools/get-dropbox-submissions.js

@@ -27,6 +27,7 @@ async function mapWithConcurrency(items, concurrency, fn) {
 export function registerGetDropboxSubmissions(server, apiClient) {
     server.registerTool("get_dropbox_submissions", {
         title: "Get Dropbox Submissions",
+        annotations: { readOnlyHint: true },
         description: "List every student's (or group's) submission to a dropbox folder, for an instructor or TA — " +
             "submitter names, submission dates, late status, file lists, and feedback/grading status. " +
             "Use get_dropbox_folders first to find folderId. Requires instructor or TA access; a student " +

package/build/tools/get-dropbox-user-submissions.js

@@ -13,6 +13,7 @@ import { log } from "../utils/logger.js";
 export function registerGetDropboxUserSubmissions(server, apiClient) {
     server.registerTool("get_dropbox_user_submissions", {
         title: "Get Dropbox User Submissions",
+        annotations: { readOnlyHint: true },
         description: "Retrieve all submissions made by one specific student (or group) in a dropbox folder, for an " +
             "instructor or TA — useful for reviewing a single student's work before drafting feedback. " +
             "Use get_dropbox_submissions or get_roster to find the userId first. Requires instructor or TA " +

package/build/tools/get-my-courses.js

@@ -15,6 +15,7 @@ import { applyCourseFilter } from "../utils/course-filter.js";
 export function registerGetMyCourses(server, apiClient, config) {
     server.registerTool("get_my_courses", {
         title: "Get My Courses",
+        annotations: { readOnlyHint: true },
         description: "Fetch your enrolled Brightspace courses with names, codes, and IDs. Use this when the user asks about their courses, enrolled classes, what they're taking this semester, or needs a course ID for other queries.",
         inputSchema: GetMyCoursesSchema,
     }, async (args) => {

package/build/tools/get-my-grades.js

@@ -71,6 +71,7 @@ function toGradeItems(gradeValues, quizzes, baseUrl, courseId) {
 export function registerGetMyGrades(server, apiClient, config) {
     server.registerTool("get_my_grades", {
         title: "Get My Grades",
+        annotations: { readOnlyHint: true },
         description: "Fetch your grade breakdown for a specific course or all enrolled courses. Shows grade items with points, percentages, and comments. Use this when the user asks about grades, scores, marks, GPA, academic performance, or how they're doing in a class.",
         inputSchema: GetMyGradesSchema,
     }, async (args) => {

package/build/tools/get-my-groups.js

@@ -19,6 +19,7 @@ function isMissingOrForbidden(error) {
 export function registerGetMyGroups(server, apiClient) {
     server.registerTool("get_my_groups", {
         title: "Get My Groups",
+        annotations: { readOnlyHint: true },
         description: "List the current user's project/discussion groups in a course, with each group's members. " +
             "Use this when a student asks who is in their project group, lab group, or discussion group.",
         inputSchema: GetMyGroupsSchema,

package/build/tools/get-roster.js

@@ -48,6 +48,7 @@ export async function fetchClasslistUsers(apiClient, courseId, options) {
 export function registerGetRoster(server, apiClient) {
     server.registerTool("get_roster", {
         title: "Get Course Roster",
+        annotations: { readOnlyHint: true },
         description: "Fetch the roster for a course including instructors, TAs, and optionally students with their names, emails, and roles. Use this when the user asks about classmates, instructor contact info, TA emails, professor names, or who's in a class. By default returns only instructors and TAs for privacy. Use includeStudents to get full class list.",
         inputSchema: GetRosterSchema,
     }, async (args) => {

package/build/tools/get-rubrics-for-object.js

@@ -13,6 +13,7 @@ import { log } from "../utils/logger.js";
 export function registerGetRubricsForObject(server, apiClient) {
     server.registerTool("get_rubrics_for_object", {
         title: "Get Rubrics for Dropbox Folder",
+        annotations: { readOnlyHint: true },
         description: "Retrieve the full rubric table (criteria, levels, and point values) attached to a dropbox " +
             "folder, for an instructor or TA. Use get_dropbox_folders first to find folderId. Like " +
             "get_dropbox_folders, this reads the folder listing's embedded rubric data, so it is not " +

package/build/tools/get-server-info.js

@@ -56,6 +56,7 @@ async function defaultReadSignedInIdentity(sessionDir) {
 export function registerGetServerInfo(server, config, version, apiClient, readSignedInIdentity = () => defaultReadSignedInIdentity(config.sessionDir)) {
     server.registerTool("get_server_info", {
         title: "Get Server Info",
+        annotations: { readOnlyHint: true },
         description: "Report which version of the Brightspace MCP server is running, the Node.js runtime, platform, config file path, session state directory, configured school URL, whether a credential is stored, the server's local timezone and UTC offset, (once a browser sign-in has been saved) what Microsoft remembered: stay-signed-in and the Don't ask again MFA checkbox, (when signed in) the account's uniqueName/displayName as signedInAs, and this process's request counters (requests: responses by status class, network errors, cache hits/misses, coalesced joins, and token refreshes). Use this for troubleshooting, when the user asks which version they have, or what timezone/account dates are being computed against. Never contacts Brightspace and never returns secrets.",
         inputSchema: GetServerInfoSchema,
     }, async () => {

package/build/tools/get-upcoming-due-dates.js

@@ -183,6 +183,7 @@ async function fetchCourseDueItems(apiClient, baseUrl, course, from, to) {
 export function registerGetUpcomingDueDates(server, apiClient, config) {
     server.registerTool("get_upcoming_due_dates", {
         title: "Get Upcoming Due Dates",
+        annotations: { readOnlyHint: true },
         description: "Fetch upcoming due dates across all your courses, derived from the due dates on assignments (dropbox folders), quizzes, and graded discussion topics themselves, plus course calendar events such as exams and labs (type: event). Use this when the user asks about deadlines, what's due, upcoming work, or what they need to do this week.",
         inputSchema: GetUpcomingDueDatesSchema,
     }, async (args) => {

package/build/tools/get-video-transcript.js

@@ -109,6 +109,7 @@ async function fetchTranscript(platform, videoUrl, fetchImpl) {
 export function registerGetVideoTranscript(server, apiClient, fetchImpl = fetch) {
     server.registerTool("get_video_transcript", {
         title: "Get Video Transcript",
+        annotations: { readOnlyHint: true },
         description: "Read the transcript of a video embedded in course content, such as a recorded lecture or explainer clip. " +
             "Call it with courseId and topicId from get_course_content (typeFilter: 'video' or 'other'), or with videoUrl " +
             "directly if you already have the link. Returns transcript text with timestamps, plus title and duration when " +

package/build/tools/index.js

@@ -23,6 +23,7 @@ export { registerGetDiscussions } from "./get-discussions.js";
 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";
 // 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

@@ -159,6 +159,7 @@ export const GetMyGroupsSchema = z.object({
         .describe("Course ID to list the current user's project/discussion groups for."),
 });
 export const GetServerInfoSchema = z.object({});
+export const SignOutSchema = z.object({});
 // ── 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/search-course.js

@@ -172,6 +172,7 @@ function describeFailure(error) {
 export function registerSearchCourse(server, apiClient) {
     server.registerTool("search_course", {
         title: "Search Course",
+        annotations: { readOnlyHint: true },
         description: "Search a course's content (modules, topics, file names), announcements, and discussion forums/topics by keyword in a single call, instead of reading the whole content tree. Use this when the user wants to find something specific, e.g. 'find the midterm review slides' or 'did anyone post about office hours'. Results are ranked: a result matching every query term ranks above one matching only some, and within that, a match in the title ranks above one only in the body text. If one source (e.g. discussions) can't be read, it's skipped and named in `note` rather than failing the whole search. This fans out over the entire content tree, announcements, and every discussion forum, so it can be slower than calling a single tool like get_course_content directly.",
         inputSchema: SearchCourseSchema,
     }, async (args) => {

package/build/tools/sign-out.js

@@ -0,0 +1,82 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { AuthenticationInProgressError } from "../auth/auth-lock.js";
+import { clearSavedSession, RemoveError } from "../auth/logout.js";
+import { log } from "../utils/logger.js";
+import { SignOutSchema } from "./schemas.js";
+import { withUpdateNotice } 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).";
+const LOCAL_ONLY = "This only clears this computer. It does not sign you out of Microsoft or Brightspace on other devices.";
+const IN_PROGRESS = "Not signed out: a sign-in is in progress on this computer, so nothing was deleted. If you don't want to sign in, don't approve the prompt. Tell the user to ask again after the sign-in finishes or times out; do not call sign_out again on your own.";
+const ALREADY_SIGNED_OUT = "You're already signed out of Brightspace on this computer; 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.
+ *
+ * The in-chat version of `auth --logout`: it deletes this computer's saved
+ * session for the account the server is configured with (clearSavedSession,
+ * under the sign-in lock, so a running sign-in is never disturbed), then
+ * empties the API client's response cache and this process's in-memory token
+ * so it serves nothing from the session it just signed out of. Answers are
+ * plain text, not JSON. A sign-in in progress and an env-supplied credential
+ * are ordinary answers rather than errors, so a model has no reason to retry
+ * in a loop; only a file that could not be deleted is reported as a failure.
+ *
+ * authRunner covers the moment between this server spawning a sign-in and
+ * that child taking the cross-process lock, when the lock alone still looks
+ * free. It is absent when the server uses a pasted credential (no runner).
+ *
+ * clear is an injection seam: tests point it at a temporary directory.
+ */
+export function registerSignOut(server, config, apiClient, tokenManager, authRunner, clear = clearSavedSession) {
+    server.registerTool("sign_out", {
+        title: "Sign Out of Brightspace",
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        description: "Sign out of Brightspace on this computer: delete the saved Brightspace session, so every Brightspace app here must sign in again from scratch on its next question. Keeps the saved password, settings, and authenticator key. Does not sign out of Microsoft or Brightspace on other devices. Call this ONLY when the user explicitly asks to sign out or log out of Brightspace (a shared computer, handing the machine on). Never call it to fix an error, never as part of answering another question, and never to retry or refresh a sign-in.",
+        inputSchema: SignOutSchema,
+    }, async () => {
+        if (config.envAccessToken || config.envSessionCookie) {
+            return text("Nothing was signed out. This server uses a credential from its configuration (D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE, set in your AI app's client configuration or a .env file), and sign_out cannot remove that. To stop using it, remove that setting and restart the app.");
+        }
+        if (authRunner?.busy())
+            return text(IN_PROGRESS);
+        const dropInMemory = () => {
+            apiClient.clearCache();
+            tokenManager.forgetSession();
+        };
+        try {
+            const { removed } = await clear(config.sessionDir);
+            dropInMemory();
+            if (removed.length === 0)
+                return text(ALREADY_SIGNED_OUT);
+            return text([
+                "Signed out of Brightspace on this computer.",
+                `Removed: ${removed.join(", ")}`,
+                KEPT,
+                OTHER_APPS,
+                NEXT_SIGN_IN,
+                LOCAL_ONLY,
+            ].join("\n"));
+        }
+        catch (error) {
+            if (error instanceof AuthenticationInProgressError)
+                return text(IN_PROGRESS);
+            dropInMemory();
+            if (error instanceof RemoveError) {
+                log("ERROR", "sign_out could not remove a session file", error);
+                return text(`Sign-out is incomplete: ${error.file} could not be deleted, so part of the saved session is still on this computer. Close anything that may be using that file, then ask to sign out again to finish.`, true);
+            }
+            log("ERROR", "sign_out failed", error);
+            return text(UNEXPECTED_FAILURE, true);
+        }
+    });
+}

package/build/tools/tool-helpers.js

@@ -117,9 +117,9 @@ const AUTH_FAILURE_GUIDANCE = {
         "as the sign-in completes. Keep calling until it succeeds or reports a different error. " +
         MFA_SOLO_CALL,
     inProgress: "Brightspace sign-in is still starting in the background (opening the browser and the " +
-        "school's login pages). Call this tool again right away: the next call joins the same " +
-        "sign-in, so it sends no second MFA prompt, and returns the number to approve as soon as " +
-        "one appears. Don't ask the user to do anything yet.",
+        "school's login pages). Call this tool again right away: the next call picks up that " +
+        "sign-in and returns the number to approve as soon as one appears. Don't ask the user to " +
+        "do anything yet.",
 };
 /**
  * mfaPending is the one kind whose guidance is partly dynamic: `numberMatch`

package/package.json

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