brightspace-mcp-server 3.11.6 → 3.11.8

package/build/auth/auth-phases.js

@@ -0,0 +1,21 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+/**
+ * The browser sign-in stages whose durations the automatic child reports to
+ * the server (issue #182). A fixed list, so a stage name is never arbitrary
+ * child output by the time it reaches the dev activity log.
+ */
+export const AUTH_PHASES = ["launch", "navigation", "silentSso", "credentials", "approvalWait", "token"];
+const PHASE_MARKER = new RegExp(`^AUTH_PHASE:(${AUTH_PHASES.join("|")}):(\\d{1,9})$`);
+/** The stdout line the automatic child prints when a stage ends. */
+export function formatPhaseMarker(phase, elapsedMs) {
+    return `AUTH_PHASE:${phase}:${Math.max(0, Math.round(elapsedMs))}`;
+}
+/** The stage and duration from a whole stdout line, or null for anything else. */
+export function parsePhaseMarker(line) {
+    const match = PHASE_MARKER.exec(line);
+    return match ? { phase: match[1], elapsedMs: Number(match[2]) } : null;
+}

package/build/auth/auth-runner.js

@@ -10,6 +10,7 @@ import { log } from "../utils/logger.js";
 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";
 /**
  * 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
@@ -31,12 +32,13 @@ const KILL_GRACE_MS = 5000;
  */
 const MFA_POLL_MS = 45000;
 /**
- * The latest a polling caller is answered, counted from when it called run().
+ * The latest any caller is answered, counted from when it called run().
  * Browser launch and the SSO pages can take half a minute before the
- * challenge even appears, so the poll is cut short to fit this budget. It
- * stays under the 60-second request timeout MCP clients commonly apply, so a
- * client that never shows the mid-call notice still gets the number in the
- * answer.
+ * challenge even appears, so the poll is cut short to fit this budget, and a
+ * sign-in that has not reached MFA by then answers "still signing in" while
+ * it keeps running. It stays under the 60-second request timeout MCP clients
+ * commonly apply, so a client that never shows the mid-call notice still gets
+ * the number in the answer.
  */
 const CALL_BUDGET_MS = 55000;
 /** How long to poll after a challenge seen elapsedMs into the call. */
@@ -44,11 +46,12 @@ function pollWindowMs(elapsedMs) {
     return Math.min(MFA_POLL_MS, CALL_BUDGET_MS - elapsedMs);
 }
 /**
- * The only two lines auth-cli.ts is allowed to hand back as structured data.
- * Deliberately strict (whole line, 1-3 digits or the literal word) so this
- * can never become a channel for arbitrary child-process text to reach a
- * tool response — anything that doesn't match exactly is just another log
- * line.
+ * The only two lines auth-cli.ts is allowed to hand back as structured data
+ * for a tool response; parsePhaseMarker adds stage timings for the dev
+ * activity log only. Deliberately strict (whole line, 1-3 digits or the
+ * literal word) so this can never become a channel for arbitrary
+ * child-process text to reach a tool response — anything that doesn't match
+ * exactly is just another log line.
  */
 const MFA_NUMBER_MARKER = /^MFA_NUMBER:(\d{1,3})$/;
 const MFA_PENDING_MARKER = /^MFA_PENDING$/;
@@ -75,6 +78,19 @@ export class AuthProcessError extends AuthError {
         this.name = "AuthProcessError";
     }
 }
+/**
+ * Settle with work's outcome, or with inProgress once CALL_BUDGET_MS has
+ * passed since startedAt. Only the caller stops waiting: work carries on.
+ */
+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."));
+        }, Math.max(0, CALL_BUDGET_MS - (Date.now() - startedAt)));
+        budgetTimer.unref?.();
+        work.then((value) => { clearTimeout(budgetTimer); resolve(value); }, (error) => { clearTimeout(budgetTimer); reject(error); });
+    });
+}
 /** Chromium can lead a separate process group, so a forced stop needs its PID. */
 function descendantPids(parentPid) {
     const rows = execFileSync("ps", ["-eo", "pid=,ppid="], {
@@ -185,12 +201,14 @@ export class AuthRunner {
      * and the first call itself keeps waiting the same way. Either way an
      * approval within the window completes the caller's original request; past
      * it, the caller gets the same mfaPending answer again and is expected to
-     * call once more.
+     * call once more. No caller waits past CALL_BUDGET_MS: a sign-in still
+     * short of its challenge by then answers inProgress and keeps running for
+     * the next call to join.
      */
     async run(onChallenge) {
         const startedAt = Date.now();
         try {
-            return await this.runOnce(startedAt);
+            return await withinCallBudget(this.runOnce(startedAt), startedAt);
         }
         catch (error) {
             const childDone = this.childDone;
@@ -440,7 +458,11 @@ export class AuthRunner {
             // immediately, without killing the child — see the class doc comment.
             forwardLines(child.stdout, (line) => {
                 const numberMarker = MFA_NUMBER_MARKER.exec(line);
-                if (numberMarker) {
+                const phaseMarker = parsePhaseMarker(line);
+                if (phaseMarker) {
+                    devActivity("auth_phase", phaseMarker);
+                }
+                else if (numberMarker) {
                     numberMatch = numberMarker[1];
                     publishChallenge(numberMatch);
                 }

package/build/auth/browser-auth.js

@@ -51,12 +51,37 @@ export class BrowserAuth {
     ssoFlow;
     stateStore;
     cooldown;
+    onPhase;
+    /** When the current login first reported an MFA challenge; splits credentials from approvalWait. */
+    challengeSeenAt;
     constructor(config, options = {}) {
         this.config = config;
-        this.ssoFlow = createSSOFlow(config, options.requestMfaCode, options.onMfaChallenge);
+        this.onPhase = options.onPhase;
+        const { onMfaChallenge } = options;
+        this.ssoFlow = createSSOFlow(config, options.requestMfaCode, onMfaChallenge && ((number) => {
+            this.challengeSeenAt ??= Date.now();
+            onMfaChallenge(number);
+        }));
         this.stateStore = new BrowserStateStore(config.sessionDir);
         this.cooldown = new AuthCooldown(config.sessionDir);
     }
+    /** Report a stage that ran from startedAt to endedAt; a listener failure never interrupts sign-in. */
+    phaseEnded(phase, startedAt, endedAt = Date.now()) {
+        try {
+            this.onPhase?.(phase, endedAt - startedAt);
+        }
+        catch { /* Reporting must not interrupt authentication. */ }
+    }
+    /** Run one stage and report its duration however it ends. */
+    async timed(phase, work) {
+        const startedAt = Date.now();
+        try {
+            return await work();
+        }
+        finally {
+            this.phaseEnded(phase, startedAt);
+        }
+    }
     static isWSLOrDocker() {
         try {
             if (/microsoft|wsl/i.test(readFileSync("/proc/version", "utf8")))
@@ -100,6 +125,7 @@ export class BrowserAuth {
         let interrupted = false;
         let state;
         let stateSaved = false;
+        let tokenStartedAt;
         const closeOnSignal = () => {
             interrupted = true;
             void browser?.close().catch(() => { });
@@ -112,7 +138,7 @@ export class BrowserAuth {
                 args.push("--no-sandbox", "--disable-setuid-sandbox");
             // Use Playwright's own timeout, which cleans up an unsuccessful launch.
             try {
-                browser = await chromium.launch({ headless: this.config.headless, timeout: 60000, args });
+                browser = await this.timed("launch", () => chromium.launch({ headless: this.config.headless, timeout: 60000, args }));
             }
             catch (launchError) {
                 // Keep the remedy attached to the failure. Without this the hint is
@@ -142,6 +168,7 @@ export class BrowserAuth {
             // away newly renewed Entra or Brightspace cookies.
             await this.saveBrowserState(await context.storageState());
             stateSaved = true;
+            tokenStartedAt = Date.now();
             const material = await this.harvestSessionMaterial(page, context);
             let token = null;
             if (material.cookieHeader && material.csrfToken) {
@@ -182,6 +209,8 @@ export class BrowserAuth {
             throw error;
         }
         finally {
+            if (tokenStartedAt !== undefined)
+                this.phaseEnded("token", tokenStartedAt);
             process.removeListener("SIGINT", closeOnSignal);
             process.removeListener("SIGTERM", closeOnSignal);
             if (page && listener)
@@ -327,10 +356,10 @@ export class BrowserAuth {
         let navigationError;
         let response;
         try {
-            response = await page.goto(`${this.config.baseUrl}/d2l/home`, {
+            response = await this.timed("navigation", () => page.goto(`${this.config.baseUrl}/d2l/home`, {
                 waitUntil: "domcontentloaded",
                 timeout: INITIAL_NAVIGATION_TIMEOUT_MS,
-            });
+            }));
         }
         catch (error) {
             // Brightspace Bar tolerates a navigation timeout because SAML may keep
@@ -347,7 +376,7 @@ export class BrowserAuth {
         if (response && (response.status() >= 500 || response.status() === 429)) {
             throw new BrowserAuthTransportError(`Brightspace temporarily returned HTTP ${response.status()}. Saved state is preserved.`);
         }
-        if (await this.awaitSilentSSO(page)) {
+        if (await this.timed("silentSso", () => this.awaitSilentSSO(page))) {
             log("INFO", "Saved session is active");
             return true;
         }
@@ -368,6 +397,8 @@ export class BrowserAuth {
             }
             throw new BrowserAuthTransportError("The sign-in page has not settled on a supported login challenge. Retry shortly; saved state is preserved.", navigationError === undefined ? undefined : { cause: navigationError });
         }
+        const loginStartedAt = Date.now();
+        this.challengeSeenAt = undefined;
         try {
             if (!await this.ssoFlow.login(page)) {
                 throw new UnsupportedAuthenticationError("The identity provider could not complete automatic sign-in.");
@@ -378,6 +409,14 @@ export class BrowserAuth {
                 await this.cooldown.recordMfaFailure();
             throw error;
         }
+        finally {
+            if (this.challengeSeenAt === undefined)
+                this.phaseEnded("credentials", loginStartedAt);
+            else {
+                this.phaseEnded("credentials", loginStartedAt, this.challengeSeenAt);
+                this.phaseEnded("approvalWait", this.challengeSeenAt);
+            }
+        }
         if (!await this.hasLiveSession(page)) {
             throw new BrowserAuthError("Sign-in did not produce a verified Brightspace session.", "session_validation");
         }

package/build/auth-cli.js

@@ -10,6 +10,7 @@ import { BrowserAuth, TokenManager } from "./auth/index.js";
 import { MfaApprovalError } from "./auth/sso-flow.js";
 import { NativeCredentialStoreError } from "./auth/credential-store.js";
 import { retireLegacyProfile } from "./auth/legacy-profile.js";
+import { formatPhaseMarker } from "./auth/auth-phases.js";
 import { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
 import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
 import { reexecLatestIfStale } from "./utils/self-update.js";
@@ -63,7 +64,11 @@ async function main() {
         const onMfaChallenge = automatic
             ? (number) => console.log(number ? `MFA_NUMBER:${number}` : "MFA_PENDING")
             : undefined;
-        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge }).authenticate({
+        // Stage timings for the server's dev activity log, same stdout channel.
+        const onPhase = automatic
+            ? (phase, elapsedMs) => console.log(formatPhaseMarker(phase, elapsedMs))
+            : undefined;
+        await new BrowserAuth(config, { requestMfaCode: codePrompt, onMfaChallenge, onPhase }).authenticate({
             automatic,
             onAuthenticated: async (token) => {
                 await tokenManager.setToken(token);

package/build/tools/get-announcements.js

@@ -10,6 +10,18 @@ import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable,
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
+function pageInfo(offset, count, returned, total, unavailableCourseIds = []) {
+    const nextOffset = total !== null && offset + returned < total ? offset + returned : null;
+    return { offset, count, returned, total, nextOffset, truncated: nextOffset !== null,
+        coverageComplete: total !== null && unavailableCourseIds.length === 0, unavailableCourseIds };
+}
+// Preserve the original array in content[0] and existing auth notices, while
+// exposing machine-readable continuation metadata in a separate text block.
+function arrayPage(items, pagination, notice) {
+    const result = notice ? toolResponseWithNotice(items, notice) : toolResponse(items);
+    result.content.push({ type: "text", text: JSON.stringify({ pagination }) });
+    return result;
+}
 /**
  * A date the runtime can actually order, or null. Unreadable and absent are the
  * same answer, so a caller can fall through to the next best.
@@ -87,13 +99,13 @@ export function mapNewsItem(item) {
 export function registerGetAnnouncements(server, apiClient, config) {
     server.registerTool("get_announcements", {
         title: "Get Announcements",
-        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said. Attachments are listed per announcement; fetch them with download_file (newsId + fileId) or read them with get_announcement_files.",
+        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) => {
         try {
             log("DEBUG", "get_announcements tool called", { args });
             // Parse and validate input
-            const { courseId, count, modifiedSince } = GetAnnouncementsSchema.parse(args);
+            const { courseId, count, offset, modifiedSince } = GetAnnouncementsSchema.parse(args);
             const cutoff = modifiedSince ? new Date(modifiedSince) : null;
             // Single course case
             if (courseId) {
@@ -104,16 +116,18 @@ export function registerGetAnnouncements(server, apiClient, config) {
                     const matched = cutoff
                         ? published.filter((a) => matchesModifiedSince(a.lastModified, cutoff))
                         : published;
-                    const announcements = matched.sort(newestFirst).slice(0, count);
+                    const announcements = matched.sort(newestFirst).slice(offset, offset + count);
+                    const pagination = pageInfo(offset, count, announcements.length, matched.length);
                     log("INFO", `get_announcements: Retrieved ${announcements.length} announcements for course ${courseId}`);
-                    return toolResponse(modifiedSince
-                        ? {
+                    return modifiedSince
+                        ? toolResponse({
                             announcements,
+                            pagination,
                             modifiedSince,
                             returned: announcements.length,
                             filteredOut: published.length - matched.length,
-                        }
-                        : announcements);
+                        })
+                        : arrayPage(announcements, pagination);
                 }
                 catch (error) {
                     // A pending sign-in is not an empty course: the route never
@@ -137,10 +151,11 @@ export function registerGetAnnouncements(server, apiClient, config) {
                                 returned: 0,
                                 filteredOut: 0,
                                 authPending: true,
+                                pagination: pageInfo(offset, count, 0, null, [courseId]),
                                 notice,
                             });
                         }
-                        return toolResponseWithNotice([], notice);
+                        return arrayPage([], pageInfo(offset, count, 0, null, [courseId]), notice);
                     }
                     throw error;
                 }
@@ -181,7 +196,7 @@ export function registerGetAnnouncements(server, apiClient, config) {
                     // 403 means no access (past course, etc) - log and skip
                     if (error?.status === 403) {
                         log("DEBUG", `get_announcements: 403 Forbidden for course ${item.OrgUnit.Id} (${item.OrgUnit.Name}) - skipping`);
-                        return [];
+                        return { unavailable: true, courseId: item.OrgUnit.Id };
                     }
                     // A pending sign-in only means this course's route never
                     // answered — it says nothing about the other courses, whose
@@ -201,13 +216,16 @@ export function registerGetAnnouncements(server, apiClient, config) {
                 .map((r) => r.value);
             const pending = settled.filter((v) => !Array.isArray(v) && v?.authPending === true);
             const allAnnouncements = settled.filter((v) => Array.isArray(v)).flat();
+            const unavailableCourseIds = results.flatMap((result, index) => result.status === "rejected" || (!Array.isArray(result.value) && result.value?.courseId)
+                ? [filteredEnrollments[index].OrgUnit.Id] : []);
             const allMatched = cutoff
                 ? allAnnouncements.filter((a) => matchesModifiedSince(a.lastModified, cutoff))
                 : allAnnouncements;
             // Sort by the scheduled date and slice to count
             const announcements = allMatched
                 .sort(newestFirst)
-                .slice(0, count);
+                .slice(offset, offset + count);
+            const pagination = pageInfo(offset, count, announcements.length, allMatched.length, unavailableCourseIds);
             log("INFO", `get_announcements: Retrieved ${announcements.length} announcements (out of ${allAnnouncements.length} total ` +
                 `across ${enrollmentItems.length} courses${pending.length > 0 ? `, ${pending.length} pending sign-in` : ""})`);
             // With modifiedSince the response is already an object (the shape
@@ -218,14 +236,15 @@ export function registerGetAnnouncements(server, apiClient, config) {
             // the notice instead of changing content[0].
             if (!modifiedSince) {
                 if (pending.length === 0)
-                    return toolResponse(announcements);
-                return toolResponseWithNotice(announcements, "Sign-in to Brightspace is still in progress, so announcements for " +
+                    return arrayPage(announcements, pagination);
+                return arrayPage(announcements, pagination, "Sign-in to Brightspace is still in progress, so announcements for " +
                     `${pending.length} course(s) (${pending.map((c) => c.courseId).join(", ")}) could not be ` +
                     `fetched yet. ${authPendingNotice(pending[0].authError)} Call get_announcements again once ` +
                     "sign-in finishes.");
             }
             const response = {
                 announcements,
+                pagination,
                 modifiedSince,
                 returned: announcements.length,
                 filteredOut: allAnnouncements.length - allMatched.length,

package/build/tools/schemas.js

@@ -37,7 +37,8 @@ export const GetMyGradesSchema = z.object({
 });
 export const GetAnnouncementsSchema = z.object({
     courseId: z.coerce.number().int().positive().optional().describe("Course ID to get announcements for. If omitted, returns recent announcements across all courses."),
-    count: z.coerce.number().int().min(1).max(50).default(10).describe("Maximum number of announcements to return, newest first (1-50, default 10). There is no pagination or offset: when more announcements exist than count, only the newest are returned. To get fuller coverage, call once per course with courseId so courses do not compete for the same slots, and use modifiedSince to return only announcements changed since a cutoff."),
+    count: z.coerce.number().int().min(1).max(50).default(10).describe("Announcements per page: 1-50 (default 10)."),
+    offset: z.coerce.number().int().min(0).default(0).describe("Announcement offset after filtering and sorting. Continue with pagination.nextOffset; restart at 0 after a failed course becomes available."),
     modifiedSince: z.string().datetime({ offset: true, message: "modifiedSince must be an ISO 8601 datetime, e.g. 2026-01-15T00:00:00Z" }).optional()
         .describe("Only return announcements last modified at or after this ISO 8601 datetime (e.g. 2026-01-15T00:00:00Z). Announcements with no modified timestamp are always included. When set, the response reports how many announcements were filtered out."),
 });

package/build/tools/tool-helpers.js

@@ -102,6 +102,10 @@ const AUTH_FAILURE_GUIDANCE = {
         "Tell the user that, then call this tool again right away without waiting for them to " +
         "confirm: each call waits up to 45 seconds for the approval and returns the result as soon " +
         "as the sign-in completes. Keep calling until it succeeds or reports a different error.",
+    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.",
 };
 /**
  * mfaPending is the one kind whose guidance is partly dynamic: `numberMatch`

package/build/utils/dev-activity.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { AUTH_PHASES } from "../auth/auth-phases.js";
 const calls = new AsyncLocalStorage();
 const runId = randomUUID();
 const MAX_BYTES = 5 * 1024 * 1024;
@@ -23,7 +24,7 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
     if (!directory)
         return;
     if (!["tool_started", "tool_finished", "http_response", "auth_required", "token_mint_started",
-        "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished"].includes(event))
+        "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished", "auth_phase"].includes(event))
         return;
     const at = new Date().toISOString();
     const record = { at, runId, pid: process.pid, event };
@@ -37,6 +38,8 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
         record.outcome = fields.outcome;
     if (["busy", "cooldown", "unsupported", "secureStorage", "transport", "timeout", "failed", "mfaPending"].includes(fields.reason ?? ""))
         record.reason = fields.reason;
+    if (AUTH_PHASES.includes(fields.phase ?? ""))
+        record.phase = fields.phase;
     try {
         mkdirSync(directory, { recursive: true, mode: 0o700 });
         const file = join(directory, `activity-${at.slice(0, 10)}-${process.pid}-${runId}.jsonl`);

package/package.json

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