brightspace-mcp-server 5.1.44 → 5.2.1

package/build/tools/download-course-files.js

@@ -0,0 +1,86 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { DownloadCourseFilesSchema } from "./schemas.js";
+import { errorResponse, sanitizeError, withUpdateNotice } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+import { validateContentId } from "../utils/file-validator.js";
+import { SyncInputError, syncCourse } from "../sync/course-sync.js";
+import { summarizeSync } from "../sync/summary.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+/**
+ * Register download_course_files tool
+ */
+export function registerDownloadCourseFiles(server, apiClient) {
+    server.registerTool("download_course_files", {
+        title: "Download Course Files",
+        description: "Download every file in a course's Content area to a folder on the host computer, in sub-folders named after the course's modules. Use this when the user wants a whole course (or one module) saved, instead of calling download_file once per file. Ask the user where to save it before calling; never guess a directory. It is safe to run again: files already on disk are skipped by default, so a rerun fetches only what is new and never overwrites the user's annotated copies. Use dryRun first to preview a large course. The answer counts what was downloaded, skipped, failed and not attempted, and what was not a file (web links, embedded videos, broken items, locked items), so do not report those as missing. If the Brightspace session expires mid-run it stops with sign-in instructions and the files already saved are kept; sign in and call it again.",
+        inputSchema: DownloadCourseFilesSchema,
+    }, async (args, extra) => {
+        try {
+            log("DEBUG", "download_course_files tool called", { args });
+            const { courseId, downloadPath, existing, moduleId, dryRun, maxFiles, maxMinutes, maxTotalMB } = DownloadCourseFilesSchema.parse(args);
+            validateContentId(courseId);
+            // Same rules as download_file's disk mode: an absolute path to a directory that exists.
+            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)", "invalidInput");
+            }
+            try {
+                if (!(await fs.stat(downloadPath)).isDirectory()) {
+                    return errorResponse(`Download path is not a directory: ${downloadPath}`, "destination");
+                }
+            }
+            catch (error) {
+                if (error?.code === "ENOENT") {
+                    return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
+                }
+                throw error;
+            }
+            let result;
+            try {
+                // A client that sent a progress token sees each file as it is handled, and a
+                // client that cancels the call (or a deadline) ends the run cleanly.
+                const progressToken = extra?._meta?.progressToken;
+                result = await syncCourse(apiClient, {
+                    courseId,
+                    destination: downloadPath,
+                    existing,
+                    moduleId,
+                    dryRun,
+                    maxFiles,
+                    maxTotalBytes: maxTotalMB * 1024 * 1024,
+                    deadlineMs: maxMinutes * 60_000,
+                    signal: extra?.signal,
+                    onProgress: progressToken === undefined || typeof extra?.sendNotification !== "function"
+                        ? undefined
+                        : (event) => {
+                            void extra.sendNotification({
+                                method: "notifications/progress",
+                                params: {
+                                    progressToken,
+                                    progress: event.done,
+                                    total: event.total,
+                                    message: `${event.type} ${JSON.stringify(event.path)}`,
+                                },
+                            }).catch(() => { });
+                        },
+                });
+            }
+            catch (error) {
+                if (error instanceof SyncInputError)
+                    return errorResponse(error.message, "invalidInput");
+                throw error;
+            }
+            const response = withUpdateNotice([{ type: "text", text: summarizeSync(result) }]);
+            if (result.authError)
+                response.isError = true;
+            return response;
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/download-dropbox-submission-file.js

@@ -6,9 +6,10 @@
 import { ApiError } from "../api/index.js";
 import { DownloadDropboxSubmissionFileSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { sensitiveDestination, sensitiveDestinationMessage } from "../utils/sensitive-paths.js";
 import { log } from "../utils/logger.js";
 import { validateContentId, DISK_MAX_FILE_SIZE } from "../utils/file-validator.js";
-import { secureStreamDownload } from "../utils/download-helpers.js";
+import { secureStreamDownload, expectedLength } from "../utils/download-helpers.js";
 import { DownloadError } from "../utils/download-errors.js";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -53,6 +54,10 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
                 }
                 throw error;
             }
+            const protectedReason = await sensitiveDestination(downloadPath);
+            if (protectedReason) {
+                return errorResponse(sensitiveDestinationMessage(downloadPath, protectedReason), "destination");
+            }
             // Fetch submission metadata to get the file list and validate fileId.
             const submissionsPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/`);
             let targetFile = null;
@@ -119,6 +124,7 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
                 originalFilename,
                 body: response.body,
                 maxBytes: DISK_MAX_FILE_SIZE,
+                expectedBytes: expectedLength(response),
             });
             log("INFO", `download_dropbox_submission_file: saved ${result.path} (${result.size} bytes, ${result.mime})`);
             return toolResponse({

package/build/tools/download-file.js

@@ -13,8 +13,9 @@ import { checkTopicAvailability } from "./topic-availability.js";
 // validated anything itself. Inline mode never writes to disk, so it calls
 // validateFileType directly to enforce the same magic-byte allowlist.
 import { validateContentId, validateFileType, nameForType, MAX_FILE_SIZE, DISK_MAX_FILE_SIZE, } from "../utils/file-validator.js";
-import { secureStreamDownload, readBodyCapped } from "../utils/download-helpers.js";
+import { secureStreamDownload, readBodyCapped, expectedLength } from "../utils/download-helpers.js";
 import { DownloadError } from "../utils/download-errors.js";
+import { sensitiveDestination, sensitiveDestinationMessage } from "../utils/sensitive-paths.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { parseCoursePath, QUICKLINK_PATH } from "../utils/course-files.js";
 import { extractPdfText } from "../utils/pdf-extractor.js";
@@ -232,6 +233,7 @@ async function finishDownload(response, originalFilename, downloadPath, customFi
         originalFilename,
         body: response.body,
         maxBytes: DISK_MAX_FILE_SIZE,
+        expectedBytes: expectedLength(response),
     });
     log("INFO", `${sourceLabel} downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
     return toolResponse({
@@ -314,6 +316,10 @@ cookieRejectedMessage) {
                     }
                     throw error;
                 }
+                const protectedReason = await sensitiveDestination(downloadPath);
+                if (protectedReason) {
+                    return errorResponse(sensitiveDestinationMessage(downloadPath, protectedReason), "destination");
+                }
             }
             // Determine download source
             if (coursePath !== undefined) {
@@ -416,26 +422,35 @@ export function parseContentDispositionFilename(disposition) {
     return null;
 }
 /**
- * Download a content file using topicId
+ * Request a content topic's file. Returns the response, or why the topic is
+ * not available: unreleased files can answer 403 or 404, and a release
+ * restriction is only explained when the metadata supports it, so every other
+ * failure is thrown intact. Shared with the course sync.
  */
-async function downloadContentFile(apiClient, courseId, topicId, downloadPath, customFilename) {
-    log("INFO", `Downloading content file: courseId=${courseId}, topicId=${topicId}`);
+export async function openContentTopic(apiClient, courseId, topicId, signal) {
     // Build download URL using D2L API path helper
     const apiPath = apiClient.le(courseId, `/content/topics/${topicId}/file`);
-    // Unreleased files can return 404 as well as 403. Only explain a release
-    // restriction when the metadata supports it; keep other failures intact.
-    let response;
     try {
-        response = await apiClient.getRaw(apiPath);
+        return { response: await apiClient.getRaw(apiPath, signal ? { signal } : undefined) };
     }
     catch (error) {
         if (error instanceof ApiError && (error.status === 403 || error.status === 404)) {
             const unavailable = await checkTopicAvailability(apiClient, courseId, topicId, error.status);
             if (unavailable)
-                return toolResponse(unavailable);
+                return { unavailable };
         }
         throw error;
     }
+}
+/**
+ * Download a content file using topicId
+ */
+async function downloadContentFile(apiClient, courseId, topicId, downloadPath, customFilename) {
+    log("INFO", `Downloading content file: courseId=${courseId}, topicId=${topicId}`);
+    const opened = await openContentTopic(apiClient, courseId, topicId);
+    if ("unavailable" in opened)
+        return toolResponse(opened.unavailable);
+    const { response } = opened;
     // Get filename from Content-Disposition header
     const disposition = response.headers.get("Content-Disposition") ?? "";
     const filename = parseContentDispositionFilename(disposition) ?? "download";

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

@@ -170,7 +170,9 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
             if (typeFilter !== 'all' && !matchesTypeFilter(item, typeFilter)) {
                 continue;
             }
-            const topicProgress = progressMap.get(item.Id);
+            // A null map means progress couldn't be read: completion is unknown,
+            // not false, so a failed read can't pass for "nothing completed".
+            const topicProgress = progressMap?.get(item.Id);
             const topic = {
                 type: 'topic',
                 topicType,
@@ -181,7 +183,7 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                 ...availabilityFields(availability),
                 ...(item.DueDate ? { dueDate: item.DueDate } : {}),
                 lastModified: item.LastModifiedDate ?? null,
-                isCompleted: topicProgress?.IsRead ?? false,
+                isCompleted: progressMap === null ? null : topicProgress?.IsRead ?? false,
                 ...(topicProgress?.DateCompleted ? { completedDate: topicProgress.DateCompleted } : {}),
             };
             // Add type-specific content
@@ -194,6 +196,12 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                 // Link topic — include URL
                 topic.url = item.Url ?? null;
             }
+            // An embedded video (D2L's ContentService type) has no file behind it.
+            // Said outright so it is not taken for a file that is missing.
+            if (typeof item.TypeIdentifier === 'string' && item.TypeIdentifier.toLowerCase() === 'contentservice') {
+                topic.embeddedMedia = true;
+                topic.note = 'Embedded media: download_file cannot fetch it. Open it in Brightspace, or use get_video_transcript for its transcript.';
+            }
             // HTML content — include body converted to markdown
             if (item.Description?.Html) {
                 topic.content = convertHtmlToMarkdown(item.Description.Html).markdown;
@@ -301,22 +309,25 @@ export function registerGetCourseContent(server, apiClient) {
                 const searchTerm = moduleTitle.toLowerCase();
                 rootModules = rootModules.filter(m => m.Title.toLowerCase().includes(searchTerm));
             }
-            // Fetch user progress for the course (graceful degradation)
-            let progressArray = [];
+            // Fetch user progress for the course (graceful degradation). 403/404
+            // means this course has no progress data for the user. Any other
+            // failure leaves completion unknown, so the map stays null and every
+            // topic reports isCompleted: null rather than false.
+            let progressMap = new Map();
             try {
-                progressArray = await apiClient.get(apiClient.le(courseId, '/content/userprogress/'), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+                const progressArray = await apiClient.get(apiClient.le(courseId, '/content/userprogress/'), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+                for (const p of Array.isArray(progressArray) ? progressArray : []) {
+                    progressMap.set(p.ContentObjectId, p);
+                }
             }
             catch (error) {
-                // 404/403 means no progress data available - not an error
+                if (isAuthUnavailable(error))
+                    throw error;
                 if (error?.status !== 404 && error?.status !== 403) {
                     log('DEBUG', `Failed to fetch progress for course ${courseId}`, error);
+                    progressMap = null;
                 }
             }
-            // Build progress map for O(1) lookups
-            const progressMap = new Map();
-            for (const p of progressArray) {
-                progressMap.set(p.ContentObjectId, p);
-            }
             // Recursively build content tree
             let contentTree = await buildContentTree(apiClient, courseId, rootModules, progressMap, typeFilter, maxDepth);
             // Apply modifiedSince filter, if requested, after the tree is built:
@@ -340,6 +351,12 @@ export function registerGetCourseContent(server, apiClient) {
                 topicCount,
                 moduleCount,
                 ...(modifiedSince ? { modifiedSince, returned: topicCount, filteredOut } : {}),
+                ...(progressMap === null
+                    ? {
+                        progressUnavailable: "Couldn't read this user's completion progress, so every topic has isCompleted null. " +
+                            "Do not report topics as not completed; try again later.",
+                    }
+                    : {}),
                 ...(unreadable > 0
                     ? {
                         notice: `The contents of ${unreadable} module(s) couldn't be read; they have children null and a ` +

package/build/tools/get-syllabus.js

@@ -13,6 +13,7 @@ import { DownloadError } from "../utils/download-errors.js";
 import { MAX_FILE_SIZE } from "../utils/file-validator.js";
 import { extractPdfText } from "../utils/pdf-extractor.js";
 import { parseContentDispositionFilename } from "./download-file.js";
+import { sensitiveDestination, sensitiveDestinationMessage } from "../utils/sensitive-paths.js";
 import { log } from "../utils/logger.js";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -137,6 +138,10 @@ export function registerGetSyllabus(server, apiClient) {
                     }
                     throw error;
                 }
+                const protectedReason = await sensitiveDestination(downloadPath);
+                if (protectedReason) {
+                    return errorResponse(sensitiveDestinationMessage(downloadPath, protectedReason), "destination");
+                }
             }
             // Fetch overview text
             let overview = null;

package/build/tools/index.js

@@ -15,6 +15,7 @@ export { registerGetAssignmentFiles } from "./get-assignment-files.js";
 export { registerGetAnnouncementFiles } from "./get-announcement-files.js";
 export { registerGetCourseContent } from "./get-course-content.js";
 export { registerDownloadFile, COURSE_FILE_NEEDS_COOKIE } from "./download-file.js";
+export { registerDownloadCourseFiles } from "./download-course-files.js";
 export { registerGetClasslistEmails } from "./get-classlist-emails.js";
 export { registerGetRoster } from "./get-roster.js";
 export { registerGetMyGroups } from "./get-my-groups.js";

package/build/tools/schemas.js

@@ -82,6 +82,24 @@ export const DownloadFileSchema = z.object({
     customFilename: z.string().max(255).optional()
         .describe("Custom filename for the downloaded file (include extension). If not provided, uses the original filename from Brightspace."),
 });
+export const DownloadCourseFilesSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to download every file from."),
+    downloadPath: z.string().min(1)
+        .describe("Absolute path to an existing directory on the HOST filesystem where the course is saved. The directory must already exist; it is not created for you, so create it first if needed. Folders named after the course's modules are created inside it. Ask the user where to save the course before calling this; never guess a directory."),
+    existing: z.enum(["skip", "replace", "keep_both"]).default("skip")
+        .describe("What to do with a file that is already on disk. skip (default): leave it alone, so running this again only fetches what is new and never overwrites the user's annotated copies. replace: download it again over the old one. keep_both: save the new copy as 'name (1).ext' beside it, unless a copy of the same size is already there."),
+    moduleId: z.coerce.number().int().positive().optional()
+        .describe("Only download this module and the modules inside it (a module id from get_course_content). Omit to download the whole course."),
+    dryRun: z.boolean().default(false)
+        .describe("List the files that would be downloaded without downloading anything or creating any folder. Use it first on a large course."),
+    maxFiles: z.coerce.number().int().min(1).max(5000).default(300)
+        .describe("Most files to download in one call (default 300). Files already on disk do not count. The rest are reported as not attempted: call again to continue, since existing files are skipped."),
+    maxMinutes: z.coerce.number().int().min(1).max(120).default(8)
+        .describe("Wall-clock limit for this call in minutes (default 8). When it passes, the call stops cleanly and reports the rest as not attempted; call it again to continue, since files already on disk are skipped. Raise it only if the client allows long tool calls."),
+    maxTotalMB: z.coerce.number().int().min(1).max(1048576).default(5120)
+        .describe("Most megabytes to download in one call (default 5120, i.e. 5 GB). The rest is reported as not attempted; call again to continue."),
+});
 export const GetSyllabusSchema = z.object({
     courseId: z.coerce.number().int().positive()
         .describe("Course ID to get syllabus for."),

package/build/tools/tool-helpers.js

@@ -240,6 +240,11 @@ const DOWNLOAD_FAILURE_GUIDANCE = {
         "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.",
+    incomplete: "Download incomplete: the connection closed before the whole file arrived, so nothing was saved. " +
+        "Try again.",
+    empty: "The file is empty (0 bytes) on Brightspace, so nothing was saved.",
+    forbiddenDestination: "That folder is not an allowed place to save files: it is the home folder itself, a drive root, a hidden folder, a system folder or an application-data folder. " +
+        "Choose a folder such as ~/Documents/Brightspace, or have the person who runs the server add the folder to D2L_DOWNLOAD_ROOTS.",
 };
 /**
  * True when an error means the session itself is unusable, not that one

package/build/utils/download-helpers.js

@@ -12,6 +12,16 @@ import { pipeline } from "node:stream/promises";
 import { validateDownloadPath, validateFileType, validateFileTypeOfFile, nameForType, MAX_FILE_SIZE, } from "./file-validator.js";
 import { DownloadError } from "./download-errors.js";
 import { log } from "./logger.js";
+import { sensitiveDestination } from "./sensitive-paths.js";
+/**
+ * Every write to disk starts here, so the protected-destination rule is
+ * enforced once for all tools (see sensitiveDestination).
+ */
+async function assertAllowedDestination(targetDir) {
+    if (await sensitiveDestination(targetDir)) {
+        throw new DownloadError("forbiddenDestination", "Destination folder is not allowed");
+    }
+}
 /**
  * Resolve filename conflicts by appending (1), (2), etc.
  *
@@ -57,6 +67,7 @@ export async function resolveFilenameConflict(dir, filename) {
 export async function secureDownload(options) {
     const { targetDir, filename, data, allowedTypes } = options;
     log("DEBUG", `secureDownload: starting download of ${filename} to ${targetDir}`);
+    await assertAllowedDestination(targetDir);
     // Validate target directory exists and is a directory
     try {
         const stats = await fs.stat(targetDir);
@@ -102,6 +113,14 @@ export async function secureDownload(options) {
         mime,
     };
 }
+/** A planned name, checked to be exactly one safe path component and nothing else. */
+function verbatimComponent(targetDir, name) {
+    const unsafe = name === "" || name === "." || name === ".." || /[/\\\u0000]/.test(name) || path.basename(name) !== name || Buffer.byteLength(name) > 255;
+    const rel = path.relative(path.resolve(targetDir), path.resolve(targetDir, name));
+    if (unsafe || rel !== name)
+        throw new DownloadError("badFilename", "Invalid filename");
+    return name;
+}
 /**
  * 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
@@ -109,11 +128,18 @@ export async function secureDownload(options) {
  * type-checked there, and only then published under its final name; a refused or
  * failed download leaves nothing behind.
  *
+ * With `expectedBytes` (the response's Content-Length, see expectedLength), a
+ * body that ends short of it fails and leaves nothing behind: a dropped
+ * connection must not publish a truncated file that a later sync would take
+ * for the whole one.
+ *
  * @throws DownloadError("tooLarge") once the body passes maxBytes
+ * @throws DownloadError("incomplete") when fewer than expectedBytes arrive
  */
 export async function secureStreamDownload(options) {
-    const { targetDir, filename, originalFilename, body, maxBytes } = options;
-    const safeFilename = path.basename(validateDownloadPath(targetDir, filename));
+    const { targetDir, filename, originalFilename, body, maxBytes, expectedBytes, replaceExisting, replaceGuard, signal, verbatimName } = options;
+    await assertAllowedDestination(targetDir);
+    const safeFilename = verbatimName ? verbatimComponent(targetDir, filename) : path.basename(validateDownloadPath(targetDir, filename));
     const partialPath = path.join(targetDir, `.download-${randomUUID()}.part`);
     let size = 0;
     const limit = new Transform({
@@ -127,11 +153,34 @@ export async function secureStreamDownload(options) {
             }
         },
     });
+    const incomplete = () => new DownloadError("incomplete", `Download incomplete: ${size} of ${expectedBytes} bytes arrived`);
     try {
-        await pipeline(Readable.fromWeb(body), limit, createWriteStream(partialPath, { flags: "wx" }));
+        try {
+            await pipeline(Readable.fromWeb(body), limit, createWriteStream(partialPath, { flags: "wx" }), ...(signal ? [{ signal }] : []));
+        }
+        catch (error) {
+            // fetch reports a connection cut mid-body as a bare "terminated".
+            if (expectedBytes !== undefined && size < expectedBytes && !(error instanceof DownloadError)) {
+                throw incomplete();
+            }
+            throw error;
+        }
+        if (expectedBytes !== undefined && size < expectedBytes)
+            throw incomplete();
+        if (size === 0)
+            throw new DownloadError("empty", "File is empty (0 bytes)");
         const type = await validateFileTypeOfFile(partialPath, undefined, safeFilename, originalFilename);
         const { mime } = type;
-        const finalPath = await publishExclusively(partialPath, targetDir, nameForType(safeFilename, type));
+        const finalName = nameForType(safeFilename, type);
+        let finalPath;
+        const replaceTarget = path.join(targetDir, finalName);
+        if (replaceExisting && finalName === safeFilename && (!replaceGuard || (await replaceGuard(replaceTarget)))) {
+            finalPath = replaceTarget;
+            await fs.rename(partialPath, finalPath);
+        }
+        else {
+            finalPath = await publishExclusively(partialPath, targetDir, finalName);
+        }
         log("INFO", `Downloaded file to ${finalPath} (${size} bytes, ${mime})`);
         return { path: finalPath, size, mime };
     }
@@ -139,6 +188,20 @@ export async function secureStreamDownload(options) {
         await fs.rm(partialPath, { force: true });
     }
 }
+/**
+ * The byte count a response promises, or undefined when it promises none we
+ * can hold it to: no Content-Length, or a Content-Encoding, where fetch hands
+ * back the decoded body and the header counts the encoded one.
+ */
+export function expectedLength(response) {
+    const encoding = (response.headers.get("Content-Encoding") ?? "").trim().toLowerCase();
+    if (encoding && encoding !== "identity")
+        return undefined;
+    const header = response.headers.get("Content-Length");
+    if (header === null || !/^\d+$/.test(header.trim()))
+        return undefined;
+    return Number(header);
+}
 /**
  * Give a finished temporary file its final name without ever replacing an
  * existing file. resolveFilenameConflict only reports a name that was free a