brightspace-mcp-server 3.13.8 → 3.13.10

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;
@@ -298,6 +339,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 +354,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 +467,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 +511,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 +544,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 +559,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 +735,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 +788,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 +807,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 +878,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 +929,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/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-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/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/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/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/build/utils/transcript/captions.js

@@ -12,6 +12,121 @@ function parseTimestamp(raw) {
     return ((Number(hours ?? 0) * 3600 + Number(minutes) * 60 + Number(seconds)) * 1000 +
         Number(millis));
 }
+const ENTITIES = {
+    amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00a0", "#39": "'", "#34": '"',
+};
+/**
+ * Decode the XML/HTML entities caption payloads carry. YouTube's tracks are
+ * full of `&#39;` and `&amp;`, which used to reach the user verbatim.
+ */
+function decodeEntities(text) {
+    return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, body) => {
+        const key = body.toLowerCase();
+        if (ENTITIES[key] !== undefined)
+            return ENTITIES[key];
+        if (key.startsWith("#x")) {
+            const code = Number.parseInt(key.slice(2), 16);
+            return Number.isFinite(code) && code > 0 ? String.fromCodePoint(code) : whole;
+        }
+        if (key.startsWith("#")) {
+            const code = Number.parseInt(key.slice(1), 10);
+            return Number.isFinite(code) && code > 0 ? String.fromCodePoint(code) : whole;
+        }
+        return whole;
+    });
+}
+/*
+ * Only strip the tags captions actually use. The old `/<[^>]+>/g` ate
+ * everything between any two angle brackets, so a lecture line like
+ * "if x < y and y > z" silently lost the middle -- and maths and inequalities
+ * are exactly what a course recording says out loud.
+ */
+const CAPTION_TAG = /<\/?(?:[0-9:.]+|c(?:\.[^>\s]*)?|v(?:\s[^>]*)?|b|i|u|ruby|rt|lang(?:\s[^>]*)?)>/gi;
+function stripCaptionTags(text) {
+    return text.replace(CAPTION_TAG, "");
+}
+/**
+ * YouTube's auto-generated tracks roll: each cue repeats the tail of the one
+ * before it, so a naive join says every line two or three times. Drop a cue
+ * whose text the previous cue already ended with.
+ */
+function dropRollingRepeats(cues) {
+    const out = [];
+    for (const cue of cues) {
+        const previous = out[out.length - 1];
+        if (previous && (previous.text === cue.text || previous.text.endsWith(cue.text)))
+            continue;
+        if (previous && cue.text.startsWith(previous.text) && cue.text.length > previous.text.length) {
+            out[out.length - 1] = { ...previous, endMs: cue.endMs, text: cue.text };
+            continue;
+        }
+        out.push(cue);
+    }
+    return out;
+}
+/**
+ * A TTML/DFXP time expression: a clock value ("00:00:01.500", optionally with
+ * frames) or an offset ("1.5s", "150ms", "90f" treated as seconds-less).
+ */
+function parseTimeExpression(raw) {
+    const value = raw.trim();
+    const offset = /^(\d+(?:\.\d+)?)(h|min|m|s|ms)?$/.exec(value);
+    if (offset) {
+        const n = Number(offset[1]);
+        const unit = offset[2] ?? "s";
+        const scale = unit === "h" ? 3600_000 : unit === "min" || unit === "m" ? 60_000 : unit === "ms" ? 1 : 1000;
+        return Math.round(n * scale);
+    }
+    const clock = /^(?:(\d+):)?(\d{1,2}):(\d{2})(?:[.,](\d{1,3}))?$/.exec(value);
+    if (!clock)
+        return NaN;
+    const [, h, m, sec, frac] = clock;
+    const millis = frac ? Number(frac.padEnd(3, "0")) : 0;
+    return (Number(h ?? 0) * 3600 + Number(m) * 60 + Number(sec)) * 1000 + millis;
+}
+/**
+ * Timed-text XML. Three shapes reach us: YouTube srv3 (`<p t= d=>`), YouTube
+ * srv1 (`<text start= dur=>`), and TTML/DFXP (`<p begin= end=>`), which is
+ * what Kaltura serves for many caption assets. TTML used to parse as zero
+ * cues and be reported as a track with nothing readable in it.
+ */
+function parseTimedText(xml) {
+    const cues = [];
+    const element = /<(p|text)\b([^>]*)>([\s\S]*?)<\/\1>/g;
+    for (const match of xml.matchAll(element)) {
+        const attrs = match[2];
+        const numericStart = /\b(?:t|start)="([\d.]+)"/.exec(attrs)?.[1];
+        const numericDur = /\b(?:d|dur)="([\d.]+)"/.exec(attrs)?.[1];
+        const beginRaw = /\bbegin="([^"]+)"/.exec(attrs)?.[1];
+        const endRaw = /\bend="([^"]+)"/.exec(attrs)?.[1];
+        const ttmlDur = /\bdur="([^"]+)"/.exec(attrs)?.[1];
+        let startMs;
+        let durMs;
+        if (beginRaw !== undefined) {
+            startMs = parseTimeExpression(beginRaw);
+            const endMs = endRaw !== undefined ? parseTimeExpression(endRaw) : NaN;
+            durMs = Number.isFinite(endMs)
+                ? endMs - startMs
+                : ttmlDur !== undefined ? parseTimeExpression(ttmlDur) : 0;
+        }
+        else if (numericStart !== undefined) {
+            // srv3 counts milliseconds, srv1 counts fractional seconds.
+            const seconds = match[1] === "text";
+            startMs = Math.round(Number(numericStart) * (seconds ? 1000 : 1));
+            durMs = numericDur === undefined ? 0 : Math.round(Number(numericDur) * (seconds ? 1000 : 1));
+        }
+        else {
+            continue;
+        }
+        if (!Number.isFinite(startMs) || !Number.isFinite(durMs))
+            continue;
+        // <s> word segments inside a <p> carry the words for ASR tracks.
+        const text = decodeEntities(match[3].replace(/<[^>]*>/g, " ")).replace(/\s+/g, " ").trim();
+        if (text)
+            cues.push({ startMs, endMs: startMs + Math.max(0, durMs), text });
+    }
+    return cues;
+}
 /**
  * Parse WebVTT or SRT text into cues. Format is detected from the WEBVTT
  * header rather than taken on faith, since a caller only knows what the
@@ -19,7 +134,13 @@ function parseTimestamp(raw) {
  */
 export function parseCaptions(raw) {
     const normalized = raw.replace(/^/, "").replace(/\r\n?/g, "\n");
-    const format = /^WEBVTT/.test(normalized.trimStart()) ? "vtt" : "srt";
+    const head = normalized.trimStart();
+    // Dispatch on what actually arrived. Calling every non-VTT payload "srt" and
+    // then finding no cues is how an XML or HTML body got reported as a caption
+    // track with nothing readable in it.
+    if (head.startsWith("<"))
+        return { format: "timedtext", cues: dropRollingRepeats(parseTimedText(normalized)) };
+    const format = /^WEBVTT\b/.test(head) ? "vtt" : "srt";
     const cues = [];
     for (const block of normalized.split(/\n{2,}/)) {
         const lines = block.split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
@@ -31,15 +152,13 @@ export function parseCaptions(raw) {
         const endMs = parseTimestamp((endRaw ?? "").trim().split(/\s+/)[0] ?? "");
         if (Number.isNaN(startMs) || Number.isNaN(endMs))
             continue;
-        const text = lines
-            .slice(timingIndex + 1)
-            .join(" ")
-            .replace(/<[^>]+>/g, "")
+        const text = decodeEntities(stripCaptionTags(lines.slice(timingIndex + 1).join(" ")))
+            .replace(/\s+/g, " ")
             .trim();
         if (text)
             cues.push({ startMs, endMs, text });
     }
-    return { format, cues };
+    return { format, cues: dropRollingRepeats(cues) };
 }
 /** "H:MM:SS", matching how course-length recordings are usually captioned. */
 export function formatTimestamp(ms) {

package/build/utils/transcript/kaltura.js

@@ -21,6 +21,14 @@
 import { parseCaptions } from "./captions.js";
 import { NoTranscriptError, TranscriptFetchError } from "./errors.js";
 const KALTURA_API_BASE = "https://cdnapisec.kaltura.com/api_v3/service";
+/** The API's own refusal, in either envelope, or undefined when it did not refuse. */
+function apiException(data) {
+    if (data.error)
+        return data.error.message ?? data.error.code ?? "unknown error";
+    if (data.objectType === "KalturaAPIException")
+        return data.message ?? data.code ?? "unknown error";
+    return undefined;
+}
 async function startWidgetSession(partnerId, fetchImpl) {
     const res = await fetchImpl(`${KALTURA_API_BASE}/session/action/startWidgetSession?widgetId=_${encodeURIComponent(partnerId)}&format=1`);
     if (!res.ok) {
@@ -42,10 +50,16 @@ async function listCaptionAssets(ks, entryId, fetchImpl) {
         throw new TranscriptFetchError(`Kaltura caption list request failed (HTTP ${res.status}).`);
     }
     const data = (await res.json());
-    if (data.error) {
-        throw new TranscriptFetchError(`Kaltura rejected the caption list request: ${data.error.message ?? "unknown error"}.`);
+    const refusal = apiException(data);
+    if (refusal) {
+        throw new TranscriptFetchError(`Kaltura rejected the caption list request: ${refusal}.`);
+    }
+    // A missing `objects` is a malformed answer, not an empty list. Only a real
+    // empty array means the entry genuinely has no caption assets.
+    if (!Array.isArray(data.objects)) {
+        throw new TranscriptFetchError("Kaltura returned an unreadable caption list for this video.");
     }
-    return data.objects ?? [];
+    return data.objects;
 }
 async function serveCaption(ks, captionAssetId, fetchImpl) {
     const res = await fetchImpl(`${KALTURA_API_BASE}/caption_captionasset/action/serve?ks=${encodeURIComponent(ks)}` +
@@ -53,7 +67,17 @@ async function serveCaption(ks, captionAssetId, fetchImpl) {
     if (!res.ok) {
         throw new TranscriptFetchError(`Kaltura caption download failed (HTTP ${res.status}).`);
     }
-    return res.text();
+    const body = await res.text();
+    // The asset was listed a moment ago, so nothing coming back is a refusal,
+    // not an absence. An error page arrives as JSON here rather than as cues.
+    if (!body.trim()) {
+        throw new TranscriptFetchError("Kaltura listed a caption asset for this video but served an empty response for it.");
+    }
+    const refusal = body.trimStart().startsWith("{") ? apiException(JSON.parse(body)) : undefined;
+    if (refusal) {
+        throw new TranscriptFetchError(`Kaltura refused to serve the caption asset: ${refusal}.`);
+    }
+    return body;
 }
 /** Best-effort title/duration — a caption-only entry still has a usable transcript without this. */
 async function fetchMediaInfo(ks, entryId, fetchImpl) {
@@ -76,12 +100,30 @@ export async function getKalturaTranscript(partnerId, entryId, fetchImpl) {
     if (assets.length === 0) {
         throw new NoTranscriptError("This Kaltura video has no captions available.");
     }
-    const asset = assets.find((a) => a.isDefault) ?? assets[0];
-    const raw = await serveCaption(ks, asset.id, fetchImpl);
-    const { format, cues } = parseCaptions(raw);
-    if (cues.length === 0) {
-        throw new NoTranscriptError("This Kaltura video has a caption track, but it contained no readable cues.");
+    // Try the default asset first, then the rest: an entry can carry a stale or
+    // empty asset alongside a good one, and giving up on the first was enough to
+    // report a captioned lecture as having no transcript.
+    const ordered = [...assets].sort((a, b) => Number(Boolean(b.isDefault)) - Number(Boolean(a.isDefault)));
+    let asset = ordered[0];
+    let parsed;
+    let lastError;
+    for (const candidate of ordered) {
+        try {
+            const attempt = parseCaptions(await serveCaption(ks, candidate.id, fetchImpl));
+            if (attempt.cues.length > 0) {
+                asset = candidate;
+                parsed = attempt;
+                break;
+            }
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : undefined;
+        }
+    }
+    if (!parsed) {
+        throw lastError ?? new TranscriptFetchError("Kaltura served this video's caption assets in a format that could not be read.");
     }
+    const { format, cues } = parsed;
     const media = await fetchMediaInfo(ks, entryId, fetchImpl);
     return {
         cues,

package/build/utils/transcript/platform.js

@@ -43,7 +43,12 @@ export function detectVideoPlatform(url) {
     // query params or path segments before falling back to "unknown".
     if (hasHostLabel(host, "kaltura"))
         return "kaltura";
-    if (isDomainOrSubdomain(host, "youtube.com") || isDomainOrSubdomain(host, "youtu.be"))
+    if (isDomainOrSubdomain(host, "youtube.com")
+        || isDomainOrSubdomain(host, "youtu.be")
+        // Privacy-mode embeds are the same video. extractYouTubeVideoId has always
+        // accepted this host, so leaving it out here made the tool answer
+        // "unsupported platform" for a link it could in fact read.
+        || isDomainOrSubdomain(host, "youtube-nocookie.com"))
         return "youtube";
     if (hasHostLabel(host, "panopto"))
         return "panopto";
@@ -102,9 +107,12 @@ export function extractYouTubeVideoId(url) {
         const v = parsed.searchParams.get("v");
         if (v)
             return v;
-        const embedMatch = parsed.pathname.match(/\/embed\/([\w-]+)/);
-        if (embedMatch)
-            return embedMatch[1];
+        // /embed/, /shorts/, /live/ and the old /v/ all name the video in the path.
+        // Only /embed/ was handled, so a Shorts or a premiere link reported that no
+        // video id could be found.
+        const pathMatch = parsed.pathname.match(/\/(?:embed|shorts|live|v)\/([\w-]+)/);
+        if (pathMatch)
+            return pathMatch[1];
     }
     return null;
 }

package/build/utils/transcript/youtube.js

@@ -4,53 +4,166 @@
  * Licensed under MIT — see LICENSE file for details.
  */
 /**
- * YouTube transcript retrieval via its public timedtext endpoint. No
- * authentication is needed — this is the same caption track a signed-out
- * browser can fetch — so unlike Kaltura there is no session to reuse or fail
- * to obtain.
+ * YouTube transcript retrieval. Still no authentication: this is the caption
+ * track a signed-out viewer can read.
+ *
+ * It no longer uses `api/timedtext?type=list`. That endpoint now answers
+ * HTTP 200 with an empty body for every video, captioned or not, so listing
+ * tracks through it reported "this video has no captions" universally.
+ *
+ * The track list comes from YouTube's InnerTube player endpoint instead,
+ * asked as one of the mobile clients. The client identity matters: the signed
+ * caption URLs a browser page hands out are stamped `exp=xpe` and require a
+ * proof-of-origin token this server cannot mint, while the mobile clients'
+ * URLs are stamped `exp=xpo` and serve captions as-is. Both were measured;
+ * see the markers below.
  */
 import { parseCaptions } from "./captions.js";
 import { NoTranscriptError, TranscriptFetchError } from "./errors.js";
-const TIMEDTEXT_BASE = "https://www.youtube.com/api/timedtext";
-async function listCaptionTracks(videoId, fetchImpl) {
-    const res = await fetchImpl(`${TIMEDTEXT_BASE}?type=list&v=${encodeURIComponent(videoId)}`);
-    if (!res.ok) {
-        throw new TranscriptFetchError(`YouTube caption list request failed (HTTP ${res.status}).`);
+const PLAYER_ENDPOINT = "https://www.youtube.com/youtubei/v1/player?prettyPrint=false";
+/**
+ * Client versions rot: YouTube eventually refuses one outright, and the
+ * symptom is a non-OK playabilityStatus for every video at once. Bump these.
+ */
+const CLIENTS = [
+    {
+        name: "ANDROID",
+        userAgent: "com.google.android.youtube/20.10.38 (Linux; U; Android 14) gzip",
+        context: { clientName: "ANDROID", clientVersion: "20.10.38", androidSdkVersion: 34, hl: "en", gl: "US" },
+    },
+    {
+        name: "IOS",
+        userAgent: "com.google.ios.youtube/21.26.4 (iPhone16,2; U; CPU iOS 18_3_2 like Mac OS X;)",
+        context: {
+            clientName: "IOS", clientVersion: "21.26.4", deviceMake: "Apple", deviceModel: "iPhone16,2",
+            osName: "iPhone", osVersion: "18.3.2.22D82", hl: "en", gl: "US",
+        },
+    },
+];
+function trackLabel(track) {
+    return track.name?.runs?.[0]?.text ?? track.name?.simpleText;
+}
+/**
+ * What the player said about a video that will not play for us. These are
+ * distinct from "has no captions", and saying so is the whole point: a
+ * bot check or an age gate used to be reported as an absent transcript.
+ */
+function playabilityFailure(status, reason) {
+    const detail = reason ? ` YouTube said: ${reason}` : "";
+    if (status === "LOGIN_REQUIRED") {
+        return new TranscriptFetchError(`YouTube would not serve this video without a sign-in.${detail}`);
+    }
+    if (status === "UNPLAYABLE" || status === "ERROR") {
+        return new TranscriptFetchError(`YouTube reports this video as unavailable.${detail}`);
     }
-    const xml = await res.text();
-    return [...xml.matchAll(/<track\b[^>]*\blang_code="([^"]+)"/g)].map((m) => m[1]);
+    return new TranscriptFetchError(`YouTube refused to describe this video (${status}).${detail}`);
 }
-async function fetchTitle(videoId, fetchImpl) {
-    try {
-        const watchUrl = `https://www.youtube.com/watch?v=${encodeURIComponent(videoId)}`;
-        const res = await fetchImpl(`https://www.youtube.com/oembed?url=${encodeURIComponent(watchUrl)}&format=json`);
-        if (!res.ok)
-            return null;
-        const data = (await res.json());
-        return data.title ?? null;
-    }
-    catch {
-        return null;
+async function requestPlayer(videoId, fetchImpl) {
+    let lastError;
+    for (const client of CLIENTS) {
+        let parsed;
+        try {
+            const res = await fetchImpl(PLAYER_ENDPOINT, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "User-Agent": client.userAgent },
+                body: JSON.stringify({ videoId, contentCheckOk: true, racyCheckOk: true, context: { client: client.context } }),
+            });
+            if (!res.ok) {
+                lastError = new TranscriptFetchError(`YouTube player request failed (HTTP ${res.status}).`);
+                continue;
+            }
+            parsed = (await res.json());
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new TranscriptFetchError("YouTube player request failed.");
+            continue;
+        }
+        const status = parsed.playabilityStatus?.status;
+        // A client that has aged out answers non-OK for everything, so try the
+        // next one before believing what it says about the video.
+        if (status && status !== "OK") {
+            lastError = playabilityFailure(status, parsed.playabilityStatus?.reason);
+            continue;
+        }
+        return parsed;
     }
+    throw lastError ?? new TranscriptFetchError("YouTube did not describe this video.");
+}
+/**
+ * Which track to read. Auto-dubbed videos are the reason this is not simply
+ * "the first English one": dubbing adds *audio* tracks, all pointing back at
+ * the same caption list, and the dub a viewer hears decides which caption
+ * track YouTube shows by default. So the default audio track's own choice
+ * wins, then a manual track in the wanted language, then anything manual,
+ * then auto-generated. There is no transcript of synthesised dub speech --
+ * only the original language's captions, hence no attempt to find one.
+ */
+export function selectCaptionTrack(tracks, audio, defaultAudioIndex, preferred) {
+    if (tracks.length === 0)
+        return undefined;
+    const manual = (t) => t.kind !== "asr";
+    const wanted = (t) => (t.languageCode ?? "").toLowerCase().startsWith(preferred);
+    const chosen = audio?.[defaultAudioIndex ?? 0]?.defaultCaptionTrackIndex;
+    if (chosen !== undefined && tracks[chosen])
+        return tracks[chosen];
+    return tracks.find((t) => manual(t) && wanted(t))
+        ?? tracks.find(wanted)
+        ?? tracks.find(manual)
+        ?? tracks[0];
+}
+/**
+ * Ask a signed caption URL for WebVTT. `fmt` is already present on the URL
+ * (as `srv3`), and a second one is ignored, so it has to be replaced rather
+ * than appended. The signature covers only the parameters named in
+ * `sparams`, which `fmt` is not, so rewriting it keeps the URL valid.
+ */
+export function captionUrlAsVtt(baseUrl) {
+    return /[?&]fmt=/.test(baseUrl)
+        ? baseUrl.replace(/([?&])fmt=[^&]*/, "$1fmt=vtt")
+        : `${baseUrl}${baseUrl.includes("?") ? "&" : "?"}fmt=vtt`;
+}
+/** True for the browser-issued URLs that need a proof-of-origin token. */
+function needsProofOfOrigin(baseUrl) {
+    const exp = /[?&]exp=([^&]*)/.exec(baseUrl)?.[1] ?? "";
+    return exp.split(",").some((value) => value === "xpe" || value === "xpv");
 }
-export async function getYouTubeTranscript(videoId, fetchImpl) {
-    const tracks = await listCaptionTracks(videoId, fetchImpl);
+export async function getYouTubeTranscript(videoId, fetchImpl, language = "en") {
+    const player = await requestPlayer(videoId, fetchImpl);
+    const renderer = player.captions?.playerCaptionsTracklistRenderer;
+    const tracks = (renderer?.captionTracks ?? []).filter((t) => typeof t?.baseUrl === "string" && t.baseUrl);
     if (tracks.length === 0) {
         throw new NoTranscriptError("This YouTube video has no caption tracks available.");
     }
-    const lang = tracks.find((t) => t.startsWith("en")) ?? tracks[0];
-    const res = await fetchImpl(`${TIMEDTEXT_BASE}?lang=${encodeURIComponent(lang)}&v=${encodeURIComponent(videoId)}&fmt=vtt`);
+    const track = selectCaptionTrack(tracks, renderer?.audioTracks, renderer?.defaultAudioTrackIndex, language);
+    if (!track) {
+        throw new NoTranscriptError("This YouTube video has no caption tracks available.");
+    }
+    if (needsProofOfOrigin(track.baseUrl)) {
+        throw new TranscriptFetchError("YouTube issued this caption track behind a proof-of-origin check this server cannot answer, " +
+            "so the captions could not be downloaded. The video may still have captions.");
+    }
+    const res = await fetchImpl(captionUrlAsVtt(track.baseUrl));
     if (!res.ok) {
         throw new TranscriptFetchError(`YouTube caption download failed (HTTP ${res.status}).`);
     }
-    const vtt = await res.text();
-    if (!vtt.trim()) {
-        throw new NoTranscriptError("This YouTube video has no caption tracks available.");
+    const body = await res.text();
+    // A caption URL that answers 200 with nothing is a refusal, not an absence:
+    // the track was listed a moment ago. Saying "no captions" here is what sent
+    // users looking for a transcript that was there all along.
+    if (!body.trim()) {
+        throw new TranscriptFetchError("YouTube listed a caption track for this video but served an empty response for it. " +
+            "This is usually a temporary block rather than a missing transcript; try again.");
     }
-    const { format, cues } = parseCaptions(vtt);
+    const { format, cues } = parseCaptions(body);
     if (cues.length === 0) {
-        throw new NoTranscriptError("This YouTube video has a caption track, but it contained no readable cues.");
+        throw new TranscriptFetchError("YouTube served a caption track for this video in a format that could not be read.");
     }
-    const title = await fetchTitle(videoId, fetchImpl);
-    return { cues, format, language: lang, title, durationSeconds: null };
+    const lengthSeconds = Number(player.videoDetails?.lengthSeconds);
+    return {
+        cues,
+        format,
+        language: trackLabel(track) ?? track.languageCode ?? null,
+        title: player.videoDetails?.title ?? null,
+        durationSeconds: Number.isFinite(lengthSeconds) && lengthSeconds > 0 ? lengthSeconds : null,
+    };
 }

package/package.json

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