brightspace-mcp-server 3.9.19 → 3.9.21

package/README.md

@@ -66,7 +66,7 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 | Assignments and rubrics | "What does the lab 4 spec actually ask for?" · "Why did I lose points on the analysis criterion?" |
 | Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" |
 | Announcements | "Did any professor post something important today?" · "Read the file attached to today's announcement" |
-| Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "Search this course for office hours" |
+| Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "Search this course for office hours" · or just read a file inline instead of saving it |
 | People | "Who are the TAs for ECE 264?" · "Who is in my project group?" |
 | Discussions | "Summarize the latest posts in the final project thread" |
 | Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura and YouTube) |

package/build/tools/download-file.js

@@ -5,23 +5,213 @@
  */
 import { ApiError } from "../api/index.js";
 import { DownloadFileSchema } from "./schemas.js";
-import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, errorResponse, withUpdateNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { checkTopicAvailability } from "./topic-availability.js";
-// Path containment and magic-byte checks belong to secureDownload, which both
-// download paths below go through; importing them here only made it look as
-// though this file validated anything itself.
-import { validateContentId, MAX_FILE_SIZE } from "../utils/file-validator.js";
+// Path containment checks belong to secureDownload, which disk-mode downloads
+// go through; importing it here only made it look as though this file
+// validated anything itself. Inline mode never writes to disk, so it calls
+// validateFileType directly to enforce the same magic-byte allowlist.
+import { validateContentId, validateFileType, MAX_FILE_SIZE } from "../utils/file-validator.js";
 import { secureDownload } from "../utils/download-helpers.js";
+import { extractPdfText } from "../utils/pdf-extractor.js";
+import { officeDocumentText } from "../utils/zip-extract.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+/**
+ * Maximum bytes of a file we'll embed inline in a tool response. Base64
+ * encoding (for images) adds ~33% overhead, so this stays well under typical
+ * MCP response-size limits. A file over this cap still works — the caller
+ * just needs to pass an absolute `downloadPath` to save it to disk instead.
+ */
+const INLINE_MAX_SIZE = 10 * 1024 * 1024; // 10 MB
+/**
+ * Maximum bytes of an image specifically that we'll embed inline as an MCP
+ * ImageContent block. Base64 encoding adds ~33% overhead, so a file right up
+ * against INLINE_MAX_SIZE (10 MB) would base64-encode to ~13.6 MB — comfortably
+ * over the model API's ~5 MB per-image limit, which fails the *entire* tool
+ * response, not just the image block. A tighter cap here (3.5 MB raw, ~4.7 MB
+ * base64) keeps every inlined image under that limit; a larger image falls
+ * through to the binary_description_only branch with a note to use
+ * downloadPath instead.
+ */
+const INLINE_IMAGE_MAX_SIZE = 3.5 * 1024 * 1024; // 3.5 MB
+/**
+ * Maximum characters of extracted text (PDF, Office document, or plain text)
+ * inlined into a single tool response. ~400,000 characters is roughly 100k
+ * tokens — enough for most course documents — and a hard cap keeps one
+ * runaway file from dominating the conversation.
+ */
+const INLINE_TEXT_MAX_CHARS = 400_000;
+/**
+ * MCP ImageContent blocks are passed to Anthropic's vision pipeline, which
+ * accepts JPEG, PNG, GIF, and WebP. Any other image mime (SVG, BMP, TIFF)
+ * falls back to the generic "can't display inline" path below.
+ */
+const INLINE_IMAGE_MIMES = new Set([
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+]);
+/** OOXML formats `officeDocumentText` (zip-extract.ts) knows how to read. */
+const INLINE_OFFICE_MIMES = new Set([
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document", // .docx
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", // .xlsx
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation", // .pptx
+]);
+/** Mime types whose bytes are safe to decode as UTF-8 and inline verbatim. */
+const INLINE_TEXT_MIMES = new Set(["text/plain", "text/csv", "text/html", "application/json"]);
+/** Truncate text to `max` characters, noting how much was cut and why. */
+function truncateForInline(text, max) {
+    if (text.length <= max)
+        return { body: text, truncated: false };
+    const remaining = text.length - max;
+    return {
+        body: text.slice(0, max) +
+            `\n\n[...truncated at ${max} characters; ${remaining} more characters exist in the source file. ` +
+            "Re-run with an absolute downloadPath to save the full file to disk instead...]",
+        truncated: true,
+    };
+}
+/**
+ * Inline mode: return the file directly in the tool response instead of
+ * writing it to disk. This is the right mode inside clients like Claude
+ * Desktop, where the MCP server's host filesystem is not the same filesystem
+ * its analysis/sandbox tools see — a file `download_file` wrote to disk there
+ * was simply unreachable from the rest of the conversation.
+ *
+ * Deliberately emits only TextContent and, for a handful of image mimes,
+ * ImageContent — never an MCP EmbeddedResource. Claude Desktop feeds an
+ * EmbeddedResource with mimeType `application/pdf` into Anthropic's document
+ * pipeline, which rejects PDFs containing JBIG2-compressed images (common in
+ * scanned academic PDFs) and can fail the *entire* tool response, even next
+ * to perfectly good TextContent blocks. Extracted text sidesteps that
+ * pipeline entirely. (Adapted from LunaParker/brightspace-mcp-server, MIT.)
+ */
+async function respondInline(buffer, originalFilename, customFilename) {
+    const effectiveFilename = customFilename || originalFilename;
+    if (buffer.length > INLINE_MAX_SIZE) {
+        return errorResponse(`File too large for inline delivery (${Math.round(buffer.length / 1024 / 1024)}MB, inline max ${INLINE_MAX_SIZE / 1024 / 1024}MB). Provide an absolute downloadPath to save it to disk instead.`);
+    }
+    // Enforces the same magic-byte allowlist as disk mode (secureDownload calls
+    // validateFileType internally); inline mode never writes to disk, so it has
+    // to call this itself. Throws DownloadError on an unsupported or
+    // undetectable type, handled by the caller's sanitizeError.
+    const { mime } = await validateFileType(buffer, undefined, effectiveFilename);
+    const metadata = {
+        mode: "inline",
+        filename: effectiveFilename,
+        originalFilename,
+        mimeType: mime,
+        size: buffer.length,
+    };
+    const content = [];
+    if (mime === "application/pdf") {
+        const extracted = await extractPdfText(buffer);
+        if (!extracted || !extracted.text) {
+            metadata.representation = "pdf_text_extraction_failed";
+            metadata.note =
+                "No text layer found in this PDF (it may be a scan). Re-run with an absolute downloadPath to save the raw file to disk.";
+            content.push({ type: "text", text: JSON.stringify(metadata) });
+            return withUpdateNotice(content);
+        }
+        const { body, truncated } = truncateForInline(extracted.text, INLINE_TEXT_MAX_CHARS);
+        metadata.representation = "extracted_text";
+        metadata.pages = extracted.totalPages;
+        metadata.truncated = truncated;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({
+            type: "text",
+            text: `--- Extracted PDF text (${extracted.totalPages} page${extracted.totalPages === 1 ? "" : "s"})${truncated ? ", truncated" : ""} ---\n${body}`,
+        });
+    }
+    else if (INLINE_IMAGE_MIMES.has(mime)) {
+        if (buffer.length > INLINE_IMAGE_MAX_SIZE) {
+            // Base64-encoding a file this size would exceed the model API's image
+            // limit and fail the whole response, so this falls back to the same
+            // "can't display inline" path as an unsupported binary format rather
+            // than emitting an oversized ImageContent block.
+            metadata.representation = "binary_description_only";
+            metadata.note = `This image is too large to inline (${Math.round(buffer.length / 1024 / 1024)}MB, inline image max ${INLINE_IMAGE_MAX_SIZE / 1024 / 1024}MB). Re-run download_file with an absolute downloadPath to save it to disk instead.`;
+            content.push({ type: "text", text: JSON.stringify(metadata) });
+            return withUpdateNotice(content);
+        }
+        metadata.representation = "image";
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({ type: "image", data: buffer.toString("base64"), mimeType: mime });
+    }
+    else if (INLINE_OFFICE_MIMES.has(mime)) {
+        // Reuses the same zip-based text extraction get_assignment_files and
+        // get_announcement_files already rely on (attachment-reader.ts) rather
+        // than duplicating it here.
+        const text = officeDocumentText(buffer);
+        if (!text) {
+            metadata.representation = "office_text_extraction_failed";
+            metadata.note =
+                "No readable text found in this Office document. Re-run with an absolute downloadPath to save the raw file to disk.";
+            content.push({ type: "text", text: JSON.stringify(metadata) });
+            return withUpdateNotice(content);
+        }
+        const { body, truncated } = truncateForInline(text, INLINE_TEXT_MAX_CHARS);
+        metadata.representation = "extracted_text";
+        metadata.truncated = truncated;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({ type: "text", text: `--- Extracted text (${effectiveFilename}) ---\n${body}` });
+    }
+    else if (INLINE_TEXT_MIMES.has(mime)) {
+        const raw = buffer.toString("utf-8");
+        const { body, truncated } = truncateForInline(raw, INLINE_TEXT_MAX_CHARS);
+        metadata.representation = "text";
+        metadata.truncated = truncated;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({ type: "text", text: `--- File contents (${effectiveFilename}) ---\n${body}` });
+    }
+    else {
+        // Binary formats we can't meaningfully show in the conversation (zip,
+        // legacy .doc/.ppt/.xls, video, audio, svg, ...). Emitting an
+        // EmbeddedResource here would put us back in the PDF-rejection failure
+        // mode described above, so this just points the caller at disk mode.
+        metadata.representation = "binary_description_only";
+        metadata.note = `This file type (${mime}) cannot be displayed inline. Re-run download_file with an absolute downloadPath to save it to disk instead.`;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+    }
+    return withUpdateNotice(content);
+}
+/**
+ * Finish a download once the bytes are in hand: write to disk when
+ * `downloadPath` is given (unchanged response shape, plus a new `mode: "disk"`
+ * field), otherwise return the file inline in the tool response.
+ */
+async function finishDownload(buffer, originalFilename, downloadPath, customFilename, sourceLabel) {
+    if (downloadPath === undefined) {
+        return respondInline(buffer, originalFilename, customFilename);
+    }
+    const effectiveFilename = customFilename || originalFilename;
+    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
+    const result = await secureDownload({
+        targetDir: downloadPath,
+        filename: effectiveFilename,
+        data: buffer,
+    });
+    log("INFO", `${sourceLabel} downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
+    return toolResponse({
+        mode: "disk",
+        success: true,
+        filePath: result.path,
+        fileSize: result.size,
+        mimeType: result.mime,
+        originalFilename,
+        message: `File downloaded successfully to ${result.path}`,
+    });
+}
 /**
  * Register download_file tool
  */
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content, assignment submissions, or an announcement's attachments to a local directory. Use this when the user wants to download, save, or get a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool. Never guess or assume a download directory. After identifying the file to download, suggest a clean readable filename to the user (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and ask if they'd like to rename it. Pass their preferred name as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
+        description: "Download a file from course content, assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {
@@ -30,22 +220,27 @@ export function registerDownloadFile(server, apiClient) {
             const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename } = DownloadFileSchema.parse(args);
             // Validate courseId
             validateContentId(courseId);
-            // Validate download path is absolute
-            if (!path.isAbsolute(downloadPath)) {
-                return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)");
-            }
-            // Validate download directory exists and is a directory
-            try {
-                const stats = await fs.stat(downloadPath);
-                if (!stats.isDirectory()) {
-                    return errorResponse(`Download path is not a directory: ${downloadPath}`);
+            // downloadPath is optional: omitting it means "return the file
+            // inline" (see respondInline), so there is nothing on the host
+            // filesystem to validate in that case.
+            if (downloadPath !== undefined) {
+                // Validate download path is absolute
+                if (!path.isAbsolute(downloadPath)) {
+                    return errorResponse("Download path must be an absolute path (e.g., /Users/username/Downloads on Mac or C:\\Users\\username\\Downloads on Windows)");
                 }
-            }
-            catch (error) {
-                if (error?.code === "ENOENT") {
-                    return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                // Validate download directory exists and is a directory
+                try {
+                    const stats = await fs.stat(downloadPath);
+                    if (!stats.isDirectory()) {
+                        return errorResponse(`Download path is not a directory: ${downloadPath}`);
+                    }
+                }
+                catch (error) {
+                    if (error?.code === "ENOENT") {
+                        return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                    }
+                    throw error;
                 }
-                throw error;
             }
             // Determine download source
             if (topicId !== undefined) {
@@ -134,24 +329,8 @@ async function downloadContentFile(apiClient, courseId, topicId, downloadPath, c
     if (buffer.length > MAX_FILE_SIZE) {
         return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
     }
-    // Use custom filename if provided, otherwise use Content-Disposition filename
     const originalFilename = filename;
-    const effectiveFilename = customFilename || filename;
-    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
-    const result = await secureDownload({
-        targetDir: downloadPath,
-        filename: effectiveFilename,
-        data: buffer,
-    });
-    log("INFO", `File downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
-    return toolResponse({
-        success: true,
-        filePath: result.path,
-        fileSize: result.size,
-        mimeType: result.mime,
-        originalFilename,
-        message: `File downloaded successfully to ${result.path}`,
-    });
+    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Content file");
 }
 /**
  * Download a submission/feedback file using folderId + fileId
@@ -203,24 +382,8 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
     if (buffer.length > MAX_FILE_SIZE) {
         return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
     }
-    // Use custom filename if provided, otherwise use original submission filename
     const originalFilename = file.FileName;
-    const effectiveFilename = customFilename || file.FileName;
-    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
-    const result = await secureDownload({
-        targetDir: downloadPath,
-        filename: effectiveFilename,
-        data: buffer,
-    });
-    log("INFO", `Submission file downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
-    return toolResponse({
-        success: true,
-        filePath: result.path,
-        fileSize: result.size,
-        mimeType: result.mime,
-        originalFilename,
-        message: `File downloaded successfully to ${result.path}`,
-    });
+    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Submission file");
 }
 /**
  * Download an announcement attachment using newsId + fileId
@@ -252,20 +415,5 @@ async function downloadNewsAttachment(apiClient, courseId, newsId, fileId, downl
         return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
     }
     const originalFilename = filename;
-    const effectiveFilename = customFilename || filename;
-    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
-    const result = await secureDownload({
-        targetDir: downloadPath,
-        filename: effectiveFilename,
-        data: buffer,
-    });
-    log("INFO", `Announcement attachment downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
-    return toolResponse({
-        success: true,
-        filePath: result.path,
-        fileSize: result.size,
-        mimeType: result.mime,
-        originalFilename,
-        message: `File downloaded successfully to ${result.path}`,
-    });
+    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Announcement attachment");
 }

package/build/tools/get-announcements.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllItems } from "../api/paginate.js";
 import { GetAnnouncementsSchema, } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
@@ -97,22 +97,53 @@ export function registerGetAnnouncements(server, apiClient, config) {
             const cutoff = modifiedSince ? new Date(modifiedSince) : null;
             // Single course case
             if (courseId) {
-                const newsItems = await fetchCourseNews(apiClient, courseId);
-                // Drop drafts, then map to clean objects
-                const published = newsItems.filter(isPublishedNewsItem).map(mapNewsItem);
-                const matched = cutoff
-                    ? published.filter((a) => matchesModifiedSince(a.lastModified, cutoff))
-                    : published;
-                const announcements = matched.sort(newestFirst).slice(0, count);
-                log("INFO", `get_announcements: Retrieved ${announcements.length} announcements for course ${courseId}`);
-                return toolResponse(modifiedSince
-                    ? {
-                        announcements,
-                        modifiedSince,
-                        returned: announcements.length,
-                        filteredOut: published.length - matched.length,
+                try {
+                    const newsItems = await fetchCourseNews(apiClient, courseId);
+                    // Drop drafts, then map to clean objects
+                    const published = newsItems.filter(isPublishedNewsItem).map(mapNewsItem);
+                    const matched = cutoff
+                        ? published.filter((a) => matchesModifiedSince(a.lastModified, cutoff))
+                        : published;
+                    const announcements = matched.sort(newestFirst).slice(0, count);
+                    log("INFO", `get_announcements: Retrieved ${announcements.length} announcements for course ${courseId}`);
+                    return toolResponse(modifiedSince
+                        ? {
+                            announcements,
+                            modifiedSince,
+                            returned: announcements.length,
+                            filteredOut: published.length - matched.length,
+                        }
+                        : announcements);
+                }
+                catch (error) {
+                    // A pending sign-in is not an empty course: the route never
+                    // answered, so the result says so instead of reporting zero
+                    // announcements as if that were a real measurement.
+                    if (isAuthUnavailable(error)) {
+                        log("DEBUG", `get_announcements: sign-in pending for course ${courseId}`, error);
+                        const notice = "Sign-in to Brightspace is still in progress, so announcements for this course " +
+                            `could not be fetched yet. ${authPendingNotice(error)} Call get_announcements again ` +
+                            "once sign-in finishes.";
+                        // With modifiedSince the response is already an object (that is
+                        // the shape those callers already get), so authPending/notice
+                        // join the rest of the JSON there. Without it the response is
+                        // always a bare array — a shape change would break every
+                        // existing caller — so the empty array stays content[0] and the
+                        // notice becomes a second content block instead.
+                        if (modifiedSince) {
+                            return toolResponse({
+                                announcements: [],
+                                modifiedSince,
+                                returned: 0,
+                                filteredOut: 0,
+                                authPending: true,
+                                notice,
+                            });
+                        }
+                        return toolResponseWithNotice([], notice);
                     }
-                    : announcements);
+                    throw error;
+                }
             }
             // All courses case
             // First, fetch enrolled courses. isActive=true is the configured
@@ -152,13 +183,24 @@ export function registerGetAnnouncements(server, apiClient, config) {
                         log("DEBUG", `get_announcements: 403 Forbidden for course ${item.OrgUnit.Id} (${item.OrgUnit.Name}) - skipping`);
                         return [];
                     }
+                    // A pending sign-in only means this course's route never
+                    // answered — it says nothing about the other courses, whose
+                    // requests may already have gone out independently. Mark this
+                    // one rather than failing the whole call and losing every
+                    // course that *did* answer.
+                    if (isAuthUnavailable(error)) {
+                        log("DEBUG", `get_announcements: sign-in pending for course ${item.OrgUnit.Id} (${item.OrgUnit.Name})`);
+                        return { authPending: true, courseId: item.OrgUnit.Id, authError: error };
+                    }
                     throw error; // Re-throw other errors
                 }
             });
             const results = await Promise.allSettled(announcementPromises);
-            const allAnnouncements = results
+            const settled = results
                 .filter((r) => r.status === "fulfilled")
-                .flatMap((r) => r.value);
+                .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 allMatched = cutoff
                 ? allAnnouncements.filter((a) => matchesModifiedSince(a.lastModified, cutoff))
                 : allAnnouncements;
@@ -166,15 +208,38 @@ export function registerGetAnnouncements(server, apiClient, config) {
             const announcements = allMatched
                 .sort(newestFirst)
                 .slice(0, count);
-            log("INFO", `get_announcements: Retrieved ${announcements.length} announcements (out of ${allAnnouncements.length} total across ${enrollmentItems.length} courses)`);
-            return toolResponse(modifiedSince
-                ? {
-                    announcements,
-                    modifiedSince,
-                    returned: announcements.length,
-                    filteredOut: allAnnouncements.length - allMatched.length,
-                }
-                : announcements);
+            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
+            // those callers already get), so authPending/unavailableCourseIds/
+            // notice join the rest of the JSON there. Without it the response is
+            // always a bare array — a shape change would break every existing
+            // caller — so a pending course adds a second content block carrying
+            // 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 " +
+                    `${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,
+                modifiedSince,
+                returned: announcements.length,
+                filteredOut: allAnnouncements.length - allMatched.length,
+            };
+            if (pending.length > 0) {
+                response.authPending = true;
+                response.unavailableCourseIds = pending.map((c) => c.courseId);
+                response.notice =
+                    "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.";
+            }
+            return toolResponse(response);
         }
         catch (error) {
             return sanitizeError(error);

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

@@ -4,7 +4,7 @@
  * Licensed under MIT — see LICENSE file for details.
  */
 import { GetCalendarEventsSchema } from "./schemas.js";
-import { toolResponse, errorResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, toolResponseWithNotice, errorResponse, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { resolveCourses } from "./resolve-courses.js";
 import { fetchCourseCalendarEvents } from "./calendar-events.js";
@@ -31,17 +31,39 @@ export function registerGetCalendarEvents(server, apiClient, config) {
             }
             const courses = await resolveCourses(apiClient, config, courseId);
             const results = await Promise.allSettled(courses.map((course) => fetchCourseCalendarEvents(apiClient, config.baseUrl, course, windowStart, windowEnd)));
+            // A pending sign-in only means that course's route never answered —
+            // it says nothing about the other courses, whose requests may already
+            // have gone out independently. Collect it rather than failing the
+            // whole call and losing every course that *did* answer.
+            const pendingCourseIds = [];
+            let firstAuthError = null;
             const events = results
                 .flatMap((result, i) => {
                 if (result.status === "fulfilled")
                     return result.value;
+                if (isAuthUnavailable(result.reason)) {
+                    pendingCourseIds.push(courses[i].id);
+                    firstAuthError ??= result.reason;
+                    log("DEBUG", `get_calendar_events: sign-in pending for course ${courses[i].id}`, result.reason);
+                    return [];
+                }
                 log("DEBUG", `get_calendar_events: skipping course ${courses[i].id} after fetch failure`, result.reason);
                 return [];
             })
                 .filter((event) => includeGenerated || !event.generatedFrom)
                 .sort((a, b) => new Date(a.start).getTime() - new Date(b.start).getTime());
-            log("INFO", `get_calendar_events: Retrieved ${events.length} events across ${courses.length} courses`);
-            return toolResponse(events);
+            log("INFO", `get_calendar_events: Retrieved ${events.length} events across ${courses.length} courses` +
+                (pendingCourseIds.length > 0 ? ` (${pendingCourseIds.length} pending sign-in)` : ""));
+            // The response is always a bare array, pending sign-in or not — a
+            // shape change would break every existing caller. A pending course
+            // instead adds a second content block carrying the notice, which
+            // names which course ids are unavailable.
+            if (pendingCourseIds.length === 0) {
+                return toolResponse(events);
+            }
+            return toolResponseWithNotice(events, "Sign-in to Brightspace is still in progress, so calendar events for " +
+                `${pendingCourseIds.length} course(s) (${pendingCourseIds.join(", ")}) could not be fetched ` +
+                `yet. ${authPendingNotice(firstAuthError)} Call get_calendar_events again once sign-in finishes.`);
         }
         catch (error) {
             return sanitizeError(error);

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

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllItems } from "../api/paginate.js";
 import { GetMyGradesSchema, } from "./schemas.js";
-import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable, authPendingNotice, } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { gradebookUrl } from "../utils/deep-links.js";
@@ -45,6 +45,23 @@ export function registerGetMyGrades(server, apiClient, config) {
                         return errorResponse("Your institution restricts grade API access for this course. " +
                             `View your grades directly in Brightspace: ${url}`);
                     }
+                    // A pending sign-in is not an empty gradebook: the route never
+                    // answered, so the result says so instead of reporting zero grades
+                    // as if that were a real measurement. The envelope stays a
+                    // success — existing callers that only read `grades` keep
+                    // working — with authPending/notice added for callers that want
+                    // to tell "no grades" apart from "couldn't check".
+                    if (isAuthUnavailable(error)) {
+                        log("DEBUG", `get_my_grades: sign-in pending for course ${courseId}`, error);
+                        return toolResponse({
+                            courseId,
+                            grades: [],
+                            authPending: true,
+                            notice: "Sign-in to Brightspace is still in progress, so grades for this course " +
+                                `could not be fetched yet. ${authPendingNotice(error)} Call get_my_grades again ` +
+                                "once sign-in finishes.",
+                        });
+                    }
                     throw error;
                 }
                 // Map to clean objects
@@ -120,6 +137,20 @@ export function registerGetMyGrades(server, apiClient, config) {
                             gradeUrl: gradebookUrl(config.baseUrl, item.OrgUnit.Id),
                         };
                     }
+                    // A pending sign-in only means this course's route never
+                    // answered — it says nothing about the other courses, whose
+                    // requests may already have gone out independently. Mark this one
+                    // rather than failing the whole call and losing every course that
+                    // *did* answer.
+                    if (isAuthUnavailable(error)) {
+                        log("DEBUG", `get_my_grades: sign-in pending for course ${item.OrgUnit.Id} (${item.OrgUnit.Name})`);
+                        return {
+                            courseId: item.OrgUnit.Id,
+                            courseName: item.OrgUnit.Name,
+                            authPending: true,
+                            authError: error,
+                        };
+                    }
                     throw error; // Re-throw other errors
                 }
             });
@@ -127,15 +158,42 @@ export function registerGetMyGrades(server, apiClient, config) {
             const settled = results
                 .filter((r) => r.status === "fulfilled")
                 .map((r) => r.value);
-            const courses = settled
-                .filter((r) => !r.restricted)
-                .map(({ restricted: _restricted, ...rest }) => rest);
+            const pending = settled.filter((c) => c.authPending);
             const restrictedCourses = settled
-                .filter((r) => r.restricted)
+                .filter((c) => c.restricted)
                 .map(({ restricted: _restricted, ...rest }) => rest);
+            const courses = settled
+                .filter((c) => !c.authPending && !c.restricted)
+                .map(({ courseId, courseName, grades }) => ({ courseId, courseName, grades }));
             log("INFO", `get_my_grades: Retrieved grades for ${courses.length} courses, ` +
-                `${restrictedCourses.length} restricted (out of ${enrollmentItems.length} enrolled)`);
-            return toolResponse({ courses, restrictedCourses });
+                `${restrictedCourses.length} restricted (out of ${enrollmentItems.length} enrolled` +
+                `${pending.length > 0 ? `, ${pending.length} pending sign-in` : ""})`);
+            // Pending courses keep `grades: []` so callers that read
+            // `courses[i].grades` still get an array; authPending marks it as
+            // unchecked rather than empty. `restrictedCourses` is always present
+            // (even empty) so callers can rely on the field existing.
+            const response = {
+                courses: [
+                    ...courses,
+                    ...pending.map(({ courseId, courseName }) => ({
+                        courseId,
+                        courseName,
+                        grades: [],
+                        authPending: true,
+                    })),
+                ],
+                restrictedCourses,
+            };
+            if (pending.length > 0) {
+                response.authPending = true;
+                response.unavailableCourseIds = pending.map((c) => c.courseId);
+                response.notice =
+                    "Sign-in to Brightspace is still in progress, so grades for " +
+                        `${pending.length} course(s) (${pending.map((c) => c.courseId).join(", ")}) could not be ` +
+                        `fetched yet. ${authPendingNotice(pending[0].authError)} Call get_my_grades again once ` +
+                        "sign-in finishes.";
+            }
+            return toolResponse(response);
         }
         catch (error) {
             return sanitizeError(error);

package/build/tools/get-roster.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllObjects } from "../api/paginate.js";
 import { GetRosterSchema, } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 // Purdue-specific role IDs. These are institution-specific values.
 // If using at another institution, you may need to adjust these.
@@ -55,91 +55,134 @@ export function registerGetRoster(server, apiClient) {
             log("DEBUG", "get_roster tool called", { args });
             // Parse and validate input
             const { courseId, includeStudents, searchTerm, limit } = GetRosterSchema.parse(args);
-            const allUsers = [];
-            let roleFallbackUsed = false;
-            if (!includeStudents) {
-                // Fetch instructors and TAs in parallel
-                const [instructorResult, taResult] = await Promise.allSettled([
-                    fetchClasslistUsers(apiClient, courseId, {
-                        roleId: INSTRUCTOR_ROLE_ID,
-                        searchTerm,
-                    }),
-                    fetchClasslistUsers(apiClient, courseId, {
-                        roleId: TA_ROLE_ID,
-                        searchTerm,
-                    }),
-                ]);
-                // Merge results
-                if (instructorResult.status === "fulfilled") {
-                    allUsers.push(...instructorResult.value);
-                }
-                else {
-                    log("WARN", "get_roster: Failed to fetch instructors", {
-                        error: instructorResult.reason,
-                    });
-                }
-                if (taResult.status === "fulfilled") {
-                    allUsers.push(...taResult.value);
+            try {
+                const allUsers = [];
+                let authFailure;
+                let roleFallbackUsed = false;
+                if (!includeStudents) {
+                    // Fetch instructors and TAs in parallel
+                    const [instructorResult, taResult] = await Promise.allSettled([
+                        fetchClasslistUsers(apiClient, courseId, {
+                            roleId: INSTRUCTOR_ROLE_ID,
+                            searchTerm,
+                        }),
+                        fetchClasslistUsers(apiClient, courseId, {
+                            roleId: TA_ROLE_ID,
+                            searchTerm,
+                        }),
+                    ]);
+                    // A pending sign-in means that route can't be trusted to have
+                    // actually asked Brightspace anything — unlike a role group that
+                    // is genuinely empty, which is a real measurement. Note it rather
+                    // than quietly reporting half the roster as the whole answer, but
+                    // keep whichever route *did* answer instead of discarding it: a
+                    // roster that lost its TAs to a pending sign-in should still show
+                    // the instructor it already has.
+                    authFailure = [instructorResult, taResult].find((r) => r.status === "rejected" && isAuthUnavailable(r.reason));
+                    // Merge results
+                    if (instructorResult.status === "fulfilled") {
+                        allUsers.push(...instructorResult.value);
+                    }
+                    else {
+                        log("WARN", "get_roster: Failed to fetch instructors", {
+                            error: instructorResult.reason,
+                        });
+                    }
+                    if (taResult.status === "fulfilled") {
+                        allUsers.push(...taResult.value);
+                    }
+                    else {
+                        log("WARN", "get_roster: Failed to fetch TAs", {
+                            error: taResult.reason,
+                        });
+                    }
+                    // Purdue's role IDs found nobody — on a non-Purdue tenant they
+                    // likely mean a different role, or none. Fall back to one
+                    // unfiltered classlist fetch and match on the role display name
+                    // the tenant itself reports instead of an institution-specific ID.
+                    // A genuine failure of this fetch is intentionally not caught
+                    // here: it should surface as a tool error rather than silently
+                    // producing an empty staff list.
+                    if (allUsers.length === 0) {
+                        const everyone = await fetchClasslistUsers(apiClient, courseId, {
+                            searchTerm,
+                        });
+                        allUsers.push(...everyone.filter(isTeachingRoleByName));
+                        roleFallbackUsed = true;
+                    }
                 }
                 else {
-                    log("WARN", "get_roster: Failed to fetch TAs", {
-                        error: taResult.reason,
-                    });
+                    // Fetch all users
+                    allUsers.push(...(await fetchClasslistUsers(apiClient, courseId, { searchTerm })));
                 }
-                // Purdue's role IDs found nobody — on a non-Purdue tenant they
-                // likely mean a different role, or none. Fall back to one
-                // unfiltered classlist fetch and match on the role display name
-                // the tenant itself reports instead of an institution-specific ID.
-                // A genuine failure of this fetch is intentionally not caught
-                // here: it should surface as a tool error rather than silently
-                // producing an empty staff list.
-                if (allUsers.length === 0) {
-                    const everyone = await fetchClasslistUsers(apiClient, courseId, {
-                        searchTerm,
+                // A very large roster would swamp the response, so it is capped. The
+                // cap is reported in the payload rather than only in a log line the
+                // model never sees: a 340 person lecture used to look like a 100
+                // person one, with nothing to say otherwise.
+                const total = allUsers.length;
+                const truncated = total > limit;
+                const kept = truncated ? allUsers.slice(0, limit) : allUsers;
+                if (truncated) {
+                    log("WARN", "get_roster: Result set exceeds the limit, truncating", {
+                        total,
+                        returned: kept.length,
                     });
-                    allUsers.push(...everyone.filter(isTeachingRoleByName));
-                    roleFallbackUsed = true;
                 }
-            }
-            else {
-                // Fetch all users
-                allUsers.push(...(await fetchClasslistUsers(apiClient, courseId, { searchTerm })));
-            }
-            // A very large roster would swamp the response, so it is capped. The
-            // cap is reported in the payload rather than only in a log line the
-            // model never sees: a 340 person lecture used to look like a 100
-            // person one, with nothing to say otherwise.
-            const total = allUsers.length;
-            const truncated = total > limit;
-            const kept = truncated ? allUsers.slice(0, limit) : allUsers;
-            if (truncated) {
-                log("WARN", "get_roster: Result set exceeds the limit, truncating", {
+                // Map to clean output
+                const users = kept.map((user) => ({
+                    name: user.DisplayName,
+                    email: user.Email || null,
+                    role: user.ClasslistRoleDisplayName,
+                }));
+                log("INFO", `get_roster: Retrieved ${users.length} users for course ${courseId}` +
+                    (authFailure ? " (sign-in pending for one route)" : ""));
+                return toolResponse({
+                    courseId,
                     total,
-                    returned: kept.length,
+                    returned: users.length,
+                    truncated,
+                    ...(truncated
+                        ? { note: `Showing ${users.length} of ${total}. Raise the limit argument to see more.` }
+                        : {}),
+                    ...(roleFallbackUsed
+                        ? {
+                            roleFilter: "No users matched the default instructor/TA role IDs, so staff were found by matching role display names (instructor, professor, lecturer, teaching assistant, coordinator, grader, TA) instead.",
+                        }
+                        : {}),
+                    users,
+                    ...(authFailure
+                        ? {
+                            authPending: true,
+                            notice: "Sign-in to Brightspace is still in progress, so part of the roster for this " +
+                                `course could not be fetched yet. ${authPendingNotice(authFailure.reason)} Call ` +
+                                "get_roster again once sign-in finishes.",
+                        }
+                        : {}),
                 });
             }
-            // Map to clean output
-            const users = kept.map((user) => ({
-                name: user.DisplayName,
-                email: user.Email || null,
-                role: user.ClasslistRoleDisplayName,
-            }));
-            log("INFO", `get_roster: Retrieved ${users.length} users for course ${courseId}`);
-            return toolResponse({
-                courseId,
-                total,
-                returned: users.length,
-                truncated,
-                ...(truncated
-                    ? { note: `Showing ${users.length} of ${total}. Raise the limit argument to see more.` }
-                    : {}),
-                ...(roleFallbackUsed
-                    ? {
-                        roleFilter: "No users matched the default instructor/TA role IDs, so staff were found by matching role display names (instructor, professor, lecturer, teaching assistant, coordinator, grader, TA) instead.",
-                    }
-                    : {}),
-                users,
-            });
+            catch (error) {
+                // A pending sign-in is not an empty roster: the route never
+                // answered, so the result says so instead of reporting zero users
+                // as if that were a real measurement. The envelope stays a success
+                // — existing callers that only read `users` keep working — with
+                // authPending/notice added for callers that want to tell "empty
+                // roster" apart from "couldn't check".
+                if (isAuthUnavailable(error)) {
+                    log("DEBUG", `get_roster: sign-in pending for course ${courseId}`, error);
+                    return toolResponse({
+                        courseId,
+                        total: 0,
+                        returned: 0,
+                        truncated: false,
+                        users: [],
+                        authPending: true,
+                        notice: "Sign-in to Brightspace is still in progress, so the roster for this course " +
+                            `could not be fetched yet. ${authPendingNotice(error)} Call get_roster again once ` +
+                            "sign-in finishes.",
+                    });
+                }
+                throw error;
+            }
         }
         catch (error) {
             return sanitizeError(error);

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

@@ -5,7 +5,7 @@
  */
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetUpcomingDueDatesSchema, } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { assignmentUrl, quizUrl, discussionUrl } from "../utils/deep-links.js";
 import { dueIn } from "../utils/due-in.js";
@@ -35,6 +35,8 @@ async function fetchDiscussionDueTopics(apiClient, courseId) {
             topics.push(...unwrapList(forumTopics));
         }
         catch (error) {
+            if (isAuthUnavailable(error))
+                throw error;
             log("DEBUG", `get_upcoming_due_dates: failed to fetch topics for forum ${forum.ForumId} in course ${courseId}`, error);
         }
     }
@@ -79,6 +81,12 @@ async function fetchCourseDueItems(apiClient, baseUrl, course, from, to) {
         fetchDiscussionDueTopics(apiClient, course.id),
         fetchCourseCalendarEvents(apiClient, baseUrl, course, from, to),
     ]);
+    // Each route may fail on its own without costing the others, but a failed
+    // sign-in means none of them answered: report that, not an empty course.
+    for (const result of [dropboxResult, quizResult, discussionResult, calendarResult]) {
+        if (result.status === "rejected" && isAuthUnavailable(result.reason))
+            throw result.reason;
+    }
     const items = [];
     if (dropboxResult.status === "fulfilled") {
         for (const folder of unwrapList(dropboxResult.value)) {
@@ -180,9 +188,21 @@ export function registerGetUpcomingDueDates(server, apiClient, config) {
             log("DEBUG", `get_upcoming_due_dates: querying ${courses.length} course(s), window=${daysAhead} days`);
             // Fetch every course in parallel; the API client rate limits itself
             const results = await Promise.allSettled(courses.map((course) => fetchCourseDueItems(apiClient, config.baseUrl, course, now, windowEnd)));
-            const items = results.flatMap((result) => {
+            // A pending sign-in only means that course's routes never answered —
+            // it says nothing about the other courses, whose requests may already
+            // have gone out independently. Collect it rather than failing the
+            // whole call and losing every course that *did* answer.
+            const pendingCourseIds = [];
+            let firstAuthError = null;
+            const items = results.flatMap((result, i) => {
                 if (result.status === "fulfilled")
                     return result.value;
+                if (isAuthUnavailable(result.reason)) {
+                    pendingCourseIds.push(courses[i].id);
+                    firstAuthError ??= result.reason;
+                    log("DEBUG", `get_upcoming_due_dates: sign-in pending for course ${courses[i].id}`, result.reason);
+                    return [];
+                }
                 log("DEBUG", "get_upcoming_due_dates: skipping course after fetch failure", result.reason);
                 return [];
             });
@@ -193,8 +213,18 @@ export function registerGetUpcomingDueDates(server, apiClient, config) {
                 return Number.isFinite(due) && due >= now && due <= windowEnd;
             })
                 .sort((a, b) => new Date(a.dueDate).getTime() - new Date(b.dueDate).getTime());
-            log("INFO", `get_upcoming_due_dates: Retrieved ${upcoming.length} items across ${courses.length} courses`);
-            return toolResponse(upcoming);
+            log("INFO", `get_upcoming_due_dates: Retrieved ${upcoming.length} items across ${courses.length} courses` +
+                (pendingCourseIds.length > 0 ? ` (${pendingCourseIds.length} pending sign-in)` : ""));
+            // The response is always a bare array, pending sign-in or not — a
+            // shape change would break every existing caller. A pending course
+            // instead adds a second content block carrying the notice, which
+            // names which course ids are unavailable.
+            if (pendingCourseIds.length === 0) {
+                return toolResponse(upcoming);
+            }
+            return toolResponseWithNotice(upcoming, "Sign-in to Brightspace is still in progress, so upcoming due dates for " +
+                `${pendingCourseIds.length} course(s) (${pendingCourseIds.join(", ")}) could not be fetched ` +
+                `yet. ${authPendingNotice(firstAuthError)} Call get_upcoming_due_dates again once sign-in finishes.`);
         }
         catch (error) {
             return sanitizeError(error);

package/build/tools/schemas.js

@@ -72,8 +72,8 @@ export const DownloadFileSchema = z.object({
         .describe("Specific file ID within a dropbox submission, or an announcement attachment's file ID (with newsId)."),
     newsId: z.coerce.number().int().positive().optional()
         .describe("Announcement (news item) ID whose attachment to download. Requires fileId."),
-    downloadPath: z.string().min(1)
-        .describe("Absolute path to the directory where the file should be saved."),
+    downloadPath: z.string().min(1).optional()
+        .describe("Absolute path to the directory where the file should be saved on disk. Omit this to receive the file inline in the tool response instead — the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see files an MCP server writes to its own host filesystem. Inline mode returns extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, and a short description (pointing back to disk mode) for anything else, capped at 10MB and 400,000 characters of extracted text."),
     customFilename: z.string().max(255).optional()
         .describe("Custom filename for the downloaded file (include extension). If not provided, uses the original filename from Brightspace."),
 });

package/build/tools/tool-helpers.js

@@ -11,26 +11,52 @@ import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { getUpdateNotice } from "../utils/update-checker.js";
 import { DownloadError, isSafeDetail, } from "../utils/download-errors.js";
+/**
+ * Append an available-update notice to an already-built content array and
+ * wrap it as a CallToolResult. This is the one place an update notice can
+ * reach a user regardless of which tool (or which response mode within a
+ * tool) they happen to hit, and it is throttled inside getUpdateNotice so a
+ * busy session is not spammed. `toolResponse` and any hand-built multi-block
+ * result (e.g. download_file's inline mode) both funnel through here so
+ * neither path can silently drop the notice.
+ */
+export function withUpdateNotice(content) {
+    const notice = getUpdateNotice();
+    if (notice)
+        content.push({ type: "text", text: notice });
+    return { content };
+}
 /**
  * Wrap data as MCP-compatible tool result.
  *
  * Every tool returns through here, which makes it the one place an update
  * notice can reach a user regardless of which tool they happen to call. The
  * notice is appended as a separate content block so content[0].text stays a
- * pure JSON document for anything parsing it, and it is throttled inside
- * getUpdateNotice so a busy session is not spammed.
+ * pure JSON document for anything parsing it.
  */
 export function toolResponse(data) {
-    const content = [
+    return withUpdateNotice([
         {
             type: "text",
             text: JSON.stringify(data),
         },
-    ];
-    const notice = getUpdateNotice();
-    if (notice)
-        content.push({ type: "text", text: notice });
-    return { content };
+    ]);
+}
+/**
+ * Wrap data as an MCP-compatible tool result, with a notice appended as a
+ * second content block.
+ *
+ * Some callers already depend on content[0] being a specific shape (a bare
+ * array, for instance) and must not see that shape change just because there
+ * is something to tell the user — a pending sign-in, say. This keeps
+ * content[0] exactly what toolResponse(data) alone would have produced and
+ * puts `notice` in content[1], ahead of (and separate from) any update notice
+ * toolResponse would itself append.
+ */
+export function toolResponseWithNotice(data, notice) {
+    const result = toolResponse(data);
+    result.content.push({ type: "text", text: notice });
+    return result;
 }
 /**
  * Wrap error message as MCP-compatible tool result

package/package.json

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