brightspace-mcp-server 3.10.9 → 3.10.11

package/build/api/client.js

@@ -54,6 +54,43 @@ function isExpiredSessionRedirect(body, baseUrl) {
  * Braces are used because D2L paths never contain them, so a substitution can
  * never collide with a real path segment.
  */
+/**
+ * An abort signal that fires after `ms` without progress. Each touch() restarts
+ * the countdown, so a slow transfer that keeps moving is never cut off while a
+ * stalled one still fails.
+ */
+function idleTimeout(ms) {
+    const controller = new AbortController();
+    let timer;
+    const clear = () => clearTimeout(timer);
+    const touch = () => {
+        clear();
+        timer = setTimeout(() => controller.abort(new DOMException("The operation was aborted due to timeout", "TimeoutError")), ms);
+    };
+    touch();
+    return { signal: controller.signal, touch, clear };
+}
+/** Restart the idle timer on every chunk of the body; stop it at the end. */
+function touchOnProgress(response, idle) {
+    if (!response.body) {
+        idle.clear();
+        return response;
+    }
+    const body = response.body.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            idle.touch();
+            controller.enqueue(chunk);
+        },
+        flush() {
+            idle.clear();
+        },
+    }));
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
 const LP_VERSION = "{lp}";
 const LE_VERSION = "{le}";
 /**
@@ -429,12 +466,15 @@ export class D2LApiClient {
     async makeRawRequest(path, token) {
         const url = `${this.baseUrl}${path}`;
         const headers = this.buildAuthHeaders(token);
+        // A file can take far longer than timeoutMs to arrive. Time out on a
+        // stall rather than on total duration, for the headers and the body alike.
+        const idle = idleTimeout(this.timeoutMs);
         try {
             log("DEBUG", `Requesting GET ${path} (raw)`);
             const response = await fetch(url, {
                 method: "GET",
                 headers,
-                signal: AbortSignal.timeout(this.timeoutMs),
+                signal: idle.signal,
             });
             this.recordStatus(response.status);
             // Preserve cookie material for the shared HTTP refresh path.
@@ -473,6 +513,7 @@ export class D2LApiClient {
                 }
                 // A legitimate HTML page: hand back an equivalent response with the
                 // body we already consumed.
+                idle.clear();
                 return new Response(body, {
                     status: response.status,
                     statusText: response.statusText,
@@ -480,9 +521,10 @@ export class D2LApiClient {
                 });
             }
             // Return raw response for caller to process
-            return response;
+            return touchOnProgress(response, idle);
         }
         catch (error) {
+            idle.clear();
             // Re-throw our own errors
             if (error instanceof ApiError ||
                 error instanceof RateLimitError ||

package/build/tools/download-file.js

@@ -8,16 +8,35 @@ import { DownloadFileSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse, withUpdateNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { checkTopicAvailability } from "./topic-availability.js";
-// Path containment checks belong to secureDownload, which disk-mode downloads
+// Path containment checks belong to secureStreamDownload, 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 { secureStreamDownload } from "../utils/download-helpers.js";
+import { DownloadError } from "../utils/download-errors.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 disk mode will save. Disk downloads stream straight
+ * to the file, so memory no longer bounds them the way MAX_FILE_SIZE (50 MB)
+ * bounds inline mode; this only stops a runaway body filling the disk.
+ * Lecture decks and recordings routinely pass 50 MB.
+ */
+const DISK_MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024; // 2 GB
+/** The size cap for a download: inline mode buffers the file, disk mode streams it. */
+function maxFileSize(downloadPath) {
+    return downloadPath === undefined ? MAX_FILE_SIZE : DISK_MAX_FILE_SIZE;
+}
+/** The refusal for a file over its mode's cap, pointing inline callers at disk mode. */
+function tooLargeResponse(bytes, downloadPath) {
+    const hint = downloadPath === undefined
+        ? " Provide an absolute downloadPath to save it to disk instead."
+        : "";
+    return errorResponse(`File too large (${Math.round(bytes / 1024 / 1024)}MB). Maximum allowed: ${maxFileSize(downloadPath) / 1024 / 1024}MB.${hint}`);
+}
 /**
  * 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
@@ -94,8 +113,8 @@ async function respondInline(buffer, originalFilename, customFilename) {
     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
+    // Enforces the same magic-byte allowlist as disk mode (secureStreamDownload calls
+    // validateFileTypeOfFile 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);
@@ -179,20 +198,35 @@ async function respondInline(buffer, originalFilename, customFilename) {
     return withUpdateNotice(content);
 }
 /**
- * Finish a download once the bytes are in hand: write to disk when
+ * Finish a download once the response is in hand: stream it to disk when
  * `downloadPath` is given (unchanged response shape, plus a new `mode: "disk"`
- * field), otherwise return the file inline in the tool response.
+ * field), otherwise buffer it and return the file inline in the tool response.
  */
-async function finishDownload(buffer, originalFilename, downloadPath, customFilename, sourceLabel) {
+async function finishDownload(response, originalFilename, downloadPath, customFilename, sourceLabel) {
+    // Check Content-Length BEFORE reading the body (prevent memory exhaustion)
+    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
+    if (contentLength > maxFileSize(downloadPath)) {
+        return tooLargeResponse(contentLength, downloadPath);
+    }
     if (downloadPath === undefined) {
+        const buffer = Buffer.from(await response.arrayBuffer());
+        // Double-check actual size
+        if (buffer.length > MAX_FILE_SIZE) {
+            return tooLargeResponse(buffer.length, downloadPath);
+        }
         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({
+    if (!response.body) {
+        throw new DownloadError("undetectableType", "File is empty (0 bytes)");
+    }
+    // Streams to disk with path traversal prevention, file type validation,
+    // conflict resolution, and the disk size cap
+    const result = await secureStreamDownload({
         targetDir: downloadPath,
         filename: effectiveFilename,
-        data: buffer,
+        body: response.body,
+        maxBytes: DISK_MAX_FILE_SIZE,
     });
     log("INFO", `${sourceLabel} downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
     return toolResponse({
@@ -314,23 +348,12 @@ async function downloadContentFile(apiClient, courseId, topicId, downloadPath, c
         }
         throw error;
     }
-    // Check Content-Length BEFORE downloading body (prevent memory exhaustion)
-    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
-    if (contentLength > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
-    }
     // Get filename from Content-Disposition header
     const disposition = response.headers.get("Content-Disposition") ?? "";
     const filename = parseContentDispositionFilename(disposition) ?? "download";
     log("DEBUG", `Content-Disposition filename: ${filename}`);
-    // Download body as buffer
-    const buffer = Buffer.from(await response.arrayBuffer());
-    // Double-check actual size
-    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`);
-    }
     const originalFilename = filename;
-    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Content file");
+    return finishDownload(response, originalFilename, downloadPath, customFilename, "Content file");
 }
 /**
  * Download a submission/feedback file using folderId + fileId
@@ -368,22 +391,16 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
         return errorResponse(`File ID ${fileId} not found in submission. Available files: ${available.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
     }
     // Check file size before downloading
-    if (file.Size > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(file.Size / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    if (file.Size > maxFileSize(downloadPath)) {
+        return tooLargeResponse(file.Size, downloadPath);
     }
     // D2L file download URL pattern for submission files
     // GET /d2l/api/le/(version)/(orgUnitId)/dropbox/folders/(folderId)/submissions/(submissionId)/files/(fileId)/download
     const downloadApiPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/${submission.Id}/files/${fileId}/download`);
     // Fetch file
     const response = await apiClient.getRaw(downloadApiPath);
-    // Download body as buffer
-    const buffer = Buffer.from(await response.arrayBuffer());
-    // Double-check actual size
-    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`);
-    }
     const originalFilename = file.FileName;
-    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Submission file");
+    return finishDownload(response, originalFilename, downloadPath, customFilename, "Submission file");
 }
 /**
  * Download an announcement attachment using newsId + fileId
@@ -396,24 +413,13 @@ async function downloadNewsAttachment(apiClient, courseId, newsId, fileId, downl
     if (!file) {
         return errorResponse(`File ID ${fileId} not found on this announcement. Available files: ${attachments.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
     }
-    if (file.Size > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(file.Size / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    if (file.Size > maxFileSize(downloadPath)) {
+        return tooLargeResponse(file.Size, downloadPath);
     }
     // GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)
     const response = await apiClient.getRaw(apiClient.le(courseId, `/news/${newsId}/attachments/${fileId}`));
-    // Check Content-Length BEFORE downloading body (prevent memory exhaustion)
-    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
-    if (contentLength > MAX_FILE_SIZE) {
-        return errorResponse(`File too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
-    }
     const disposition = response.headers.get("Content-Disposition") ?? "";
     const filename = parseContentDispositionFilename(disposition) ?? file.FileName;
-    // Download body as buffer
-    const buffer = Buffer.from(await response.arrayBuffer());
-    // Double-check actual size
-    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`);
-    }
     const originalFilename = filename;
-    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Announcement attachment");
+    return finishDownload(response, originalFilename, downloadPath, customFilename, "Announcement attachment");
 }

package/build/tools/schemas.js

@@ -37,7 +37,7 @@ 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"),
+    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."),
     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

@@ -133,6 +133,8 @@ const DOWNLOAD_FAILURE_GUIDANCE = {
         "Pass customFilename to choose one yourself.",
     pathTraversal: "The name Brightspace gave this file pointed outside the download " +
         "directory and was refused. Pass customFilename to choose one yourself.",
+    tooLarge: "The file is larger than the download size limit. " +
+        "Open it from Brightspace in a browser instead.",
 };
 /**
  * True when an error means the session itself is unusable, not that one

package/build/utils/download-helpers.js

@@ -4,8 +4,13 @@
  * Licensed under MIT — see LICENSE file for details.
  */
 import fs from "node:fs/promises";
+import { createWriteStream } from "node:fs";
 import path from "node:path";
-import { validateDownloadPath, validateFileType, MAX_FILE_SIZE } from "./file-validator.js";
+import { randomUUID } from "node:crypto";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { validateDownloadPath, validateFileType, validateFileTypeOfFile, MAX_FILE_SIZE, } from "./file-validator.js";
+import { DownloadError } from "./download-errors.js";
 import { log } from "./logger.js";
 /**
  * Resolve filename conflicts by appending (1), (2), etc.
@@ -97,3 +102,42 @@ export async function secureDownload(options) {
         mime,
     };
 }
+/**
+ * secureDownload for a response body that is streamed to disk rather than
+ * held in memory, so a file's size is bounded by `maxBytes` instead of by
+ * MAX_FILE_SIZE. The body is written to a hidden temporary file in targetDir,
+ * type-checked there, and only then renamed to its final name; a refused or
+ * failed download leaves nothing behind.
+ *
+ * @throws DownloadError("tooLarge") once the body passes maxBytes
+ */
+export async function secureStreamDownload(options) {
+    const { targetDir, filename, body, maxBytes } = options;
+    const safeFilename = path.basename(validateDownloadPath(targetDir, filename));
+    const partialPath = path.join(targetDir, `.download-${randomUUID()}.part`);
+    let size = 0;
+    const limit = new Transform({
+        transform(chunk, _encoding, callback) {
+            size += chunk.length;
+            if (size > maxBytes) {
+                callback(new DownloadError("tooLarge", `File exceeds ${maxBytes} bytes`));
+            }
+            else {
+                callback(null, chunk);
+            }
+        },
+    });
+    try {
+        await pipeline(Readable.fromWeb(body), limit, createWriteStream(partialPath, { flags: "wx" }));
+        const { mime } = await validateFileTypeOfFile(partialPath, undefined, safeFilename);
+        const resolvedFilename = await resolveFilenameConflict(targetDir, safeFilename);
+        const finalPath = path.join(targetDir, resolvedFilename);
+        await fs.rename(partialPath, finalPath);
+        log("INFO", `Downloaded file to ${finalPath} (${size} bytes, ${mime})`);
+        return { path: finalPath, size, mime };
+    }
+    catch (error) {
+        await fs.rm(partialPath, { force: true });
+        throw error;
+    }
+}

package/build/utils/file-validator.js

@@ -3,6 +3,7 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import fs from "node:fs/promises";
 import path from "node:path";
 import sanitizeFilename from "sanitize-filename";
 import { DownloadError } from "./download-errors.js";
@@ -21,12 +22,12 @@ import { DownloadError } from "./download-errors.js";
  */
 // file-type v21 is ESM-only and costs ~50ms; defer the import to first use
 // since validateFileType is already async.
-let fileTypeFromBufferPromise;
-function getFileTypeFromBuffer() {
-    if (!fileTypeFromBufferPromise) {
-        fileTypeFromBufferPromise = import("file-type").then((m) => m.fileTypeFromBuffer);
+let fileTypePromise;
+function getFileType() {
+    if (!fileTypePromise) {
+        fileTypePromise = import("file-type");
     }
-    return fileTypeFromBufferPromise;
+    return fileTypePromise;
 }
 const CFB_MIME = "application/x-cfb";
 const CFB_EXTENSION_MIMES = {
@@ -147,33 +148,61 @@ export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES
         throw new DownloadError("undetectableType", "File is empty (0 bytes)");
     }
     // Try magic byte detection first
-    const fileTypeFromBuffer = await getFileTypeFromBuffer();
+    const { fileTypeFromBuffer } = await getFileType();
     const detected = await fileTypeFromBuffer(buffer);
-    if (detected) {
-        if (detected.mime === XML_MIME) {
-            const ext = filename ? path.extname(filename).toLowerCase() : "";
-            const resolved = XML_EXTENSION_MIMES[ext];
-            if (resolved && allowedTypes.includes(resolved)) {
-                return { mime: resolved, ext: ext.slice(1) };
-            }
-            // Anything else falls through to the allowlist check, which refuses
-            // application/xml the way it always has.
-        }
-        if (detected.mime === CFB_MIME) {
-            const ext = filename ? path.extname(filename).toLowerCase() : "";
-            const resolved = CFB_EXTENSION_MIMES[ext];
-            if (resolved && allowedTypes.includes(resolved)) {
-                return { mime: resolved, ext: ext.slice(1) };
-            }
-            throw new DownloadError("unsupportedType", `Compound File Binary with extension '${ext || "none"}' is not an allowed Office format`, CFB_MIME);
+    if (detected)
+        return allowDetectedType(detected, allowedTypes, filename);
+    return allowTextType(buffer, allowedTypes);
+}
+/**
+ * validateFileType for a file already on disk, so a download streamed there
+ * is never read back into memory whole. Magic bytes are read from the file
+ * itself; only a file with none, the text fallback's case, is read in, and
+ * only when it is within MAX_FILE_SIZE.
+ */
+export async function validateFileTypeOfFile(filePath, allowedTypes = ALLOWED_MIME_TYPES, filename) {
+    const { size } = await fs.stat(filePath);
+    if (size === 0) {
+        throw new DownloadError("undetectableType", "File is empty (0 bytes)");
+    }
+    const { fileTypeFromFile } = await getFileType();
+    const detected = await fileTypeFromFile(filePath);
+    if (detected)
+        return allowDetectedType(detected, allowedTypes, filename);
+    if (size > MAX_FILE_SIZE) {
+        throw new DownloadError("undetectableType", "Could not determine file type or type not allowed");
+    }
+    return allowTextType(await fs.readFile(filePath), allowedTypes);
+}
+/** The allowlist decision for a type file-type recognised from magic bytes. */
+function allowDetectedType(detected, allowedTypes, filename) {
+    if (detected.mime === XML_MIME) {
+        const ext = filename ? path.extname(filename).toLowerCase() : "";
+        const resolved = XML_EXTENSION_MIMES[ext];
+        if (resolved && allowedTypes.includes(resolved)) {
+            return { mime: resolved, ext: ext.slice(1) };
         }
-        if (!allowedTypes.includes(detected.mime)) {
-            throw new DownloadError("unsupportedType", `File type '${detected.mime}' not allowed`, detected.mime);
+        // Anything else falls through to the allowlist check, which refuses
+        // application/xml the way it always has.
+    }
+    if (detected.mime === CFB_MIME) {
+        const ext = filename ? path.extname(filename).toLowerCase() : "";
+        const resolved = CFB_EXTENSION_MIMES[ext];
+        if (resolved && allowedTypes.includes(resolved)) {
+            return { mime: resolved, ext: ext.slice(1) };
         }
-        return { mime: detected.mime, ext: detected.ext };
+        throw new DownloadError("unsupportedType", `Compound File Binary with extension '${ext || "none"}' is not an allowed Office format`, CFB_MIME);
+    }
+    if (!allowedTypes.includes(detected.mime)) {
+        throw new DownloadError("unsupportedType", `File type '${detected.mime}' not allowed`, detected.mime);
     }
-    // Fallback for text-based files with no magic-byte signature: accept if the
-    // buffer decodes as UTF-8 (rejecting binaries and NUL bytes), then sniff HTML.
+    return { mime: detected.mime, ext: detected.ext };
+}
+/**
+ * Fallback for text-based files with no magic-byte signature: accept if the
+ * buffer decodes as UTF-8 (rejecting binaries and NUL bytes), then sniff HTML.
+ */
+function allowTextType(buffer, allowedTypes) {
     if (!buffer.includes(0)) {
         let decoded = null;
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "3.10.9",
+  "version": "3.10.11",
   "mcpName": "io.github.RohanMuppa/brightspace",
   "description": "MCP server for Brightspace (D2L). Check grades, due dates, assignments, announcements, syllabus, rosters and more via Claude, ChatGPT, Cursor, Windsurf, or any MCP client.",
   "type": "module",