brightspace-mcp-server 3.14.0 → 3.15.1

package/build/api/client.js

@@ -327,11 +327,20 @@ export class D2LApiClient {
      * read by a read-only tool is not worth an MFA prompt.
      */
     async getPage(path) {
+        const response = await this.getPageRaw(path);
+        return response ? await response.text() : null;
+    }
+    /**
+     * Like getPage, but returns the response itself so a binary body (a course
+     * file reached through a quickLink or /content/enforced path) is not decoded
+     * as text. Same cookie, same origin check, same null on a dead session.
+     */
+    async getPageRaw(path) {
         // The cookie belongs to this Brightspace alone. A path that would make
         // `${baseUrl}${path}` name another host (`@evil.example/`, `.evil.example/`,
         // `//evil.example/`) is refused before the cookie is ever read.
         if (!this.isSameOriginPath(path)) {
-            log("WARN", "getPage refused a path outside the Brightspace origin");
+            log("WARN", "getPageRaw refused a path outside the Brightspace origin");
             return null;
         }
         const token = await this.tokenManager.getToken();
@@ -339,8 +348,7 @@ export class D2LApiClient {
             return null;
         const cookieToken = { ...token, accessToken: `cookie:${token.cookieHeader}` };
         try {
-            const response = await this.retrying(() => this.throttled(() => this.makeRawRequest(path, cookieToken)));
-            return await response.text();
+            return await this.retrying(() => this.throttled(() => this.makeRawRequest(path, cookieToken)));
         }
         catch (error) {
             if (error instanceof ApiError && error.status === 401)

package/build/tools/download-file.js

@@ -15,6 +15,8 @@ import { checkTopicAvailability } from "./topic-availability.js";
 import { validateContentId, validateFileType, MAX_FILE_SIZE, DISK_MAX_FILE_SIZE, } from "../utils/file-validator.js";
 import { secureStreamDownload, readBodyCapped } from "../utils/download-helpers.js";
 import { DownloadError } from "../utils/download-errors.js";
+import { AUTH_COMMAND } from "../utils/commands.js";
+import { parseCoursePath, QUICKLINK_PATH } from "../utils/course-files.js";
 import { extractPdfText } from "../utils/pdf-extractor.js";
 import { officeDocumentText } from "../utils/zip-extract.js";
 import fs from "node:fs/promises";
@@ -247,13 +249,16 @@ async function finishDownload(response, originalFilename, downloadPath, customFi
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content, instructor assignment attachments (source: assignmentAttachment with folderId + fileId), 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).",
+        description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), 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 {
             log("DEBUG", "download_file tool called", { args });
             // Parse and validate input
-            const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename, source } = DownloadFileSchema.parse(args);
+            const { courseId, topicId, coursePath, folderId, newsId, fileId, downloadPath, customFilename, source } = DownloadFileSchema.parse(args);
+            if (coursePath !== undefined && (topicId !== undefined || folderId !== undefined || newsId !== undefined || fileId !== undefined || source !== undefined)) {
+                return errorResponse("coursePath cannot be combined with topicId, folderId, newsId, fileId, or source.");
+            }
             if (source !== undefined && (topicId !== undefined || newsId !== undefined || folderId === undefined || fileId === undefined)) {
                 return errorResponse("source requires folderId and fileId and cannot be combined with topicId or newsId.");
             }
@@ -282,7 +287,13 @@ export function registerDownloadFile(server, apiClient) {
                 }
             }
             // Determine download source
-            if (topicId !== undefined) {
+            if (coursePath !== undefined) {
+                const filePath = parseCoursePath(coursePath, courseId);
+                if (typeof filePath !== "string")
+                    return errorResponse(filePath.error);
+                return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename);
+            }
+            else if (topicId !== undefined) {
                 // Content file download
                 validateContentId(topicId);
                 return await downloadContentFile(apiClient, courseId, topicId, downloadPath, customFilename);
@@ -308,6 +319,22 @@ export function registerDownloadFile(server, apiClient) {
         }
     });
 }
+/**
+ * Download a file from the course file store. Instructors often link these
+ * from a module or page description instead of adding them as content
+ * topics, so they have no topicId. Brightspace serves them to the signed-in
+ * web session, not to the API token, so this goes through the session cookie.
+ */
+async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename) {
+    log("INFO", `Downloading course file: courseId=${courseId}, path=${filePath}`);
+    const response = await apiClient.getPageRaw(`${QUICKLINK_PATH}?ou=${courseId}&type=coursefile&fileId=${encodeURIComponent(filePath)}`);
+    if (!response) {
+        return errorResponse(`Course files need a Brightspace web session cookie, and none is available. Sign in with \`${AUTH_COMMAND}\` and retry. A server that runs on D2L_ACCESS_TOKEN alone has no cookie: set D2L_SESSION_COOKIE as well, or sign in through the browser.`);
+    }
+    const disposition = response.headers.get("Content-Disposition") ?? "";
+    const filename = parseContentDispositionFilename(disposition) ?? filePath.split("/").pop() ?? "download";
+    return finishDownload(response, filename, downloadPath, customFilename, "Course file");
+}
 /** Download an instructor-provided handout, independently of student submissions. */
 async function downloadAssignmentAttachment(apiClient, courseId, folderId, fileId, downloadPath, customFilename) {
     const raw = await apiClient.get(apiClient.le(courseId, "/dropbox/folders/"));

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

@@ -37,6 +37,7 @@ export function registerGetCalendarEvents(server, apiClient, config) {
             // have gone out independently. Collect it rather than failing the
             // whole call and losing every course that *did* answer.
             const pendingCourseIds = [];
+            const failedCourseIds = [];
             let firstAuthError = null;
             const events = results
                 .flatMap((result, i) => {
@@ -48,23 +49,37 @@ export function registerGetCalendarEvents(server, apiClient, config) {
                     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);
+                // Anything else (a 404, a 5xx, a dropped connection) still must
+                // not make the course vanish: an exam missing from a list that
+                // looks complete reads as "no exam" (#262).
+                failedCourseIds.push(courses[i].id);
+                log("DEBUG", `get_calendar_events: calendar unavailable for course ${courses[i].id}`, 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` +
-                (pendingCourseIds.length > 0 ? ` (${pendingCourseIds.length} pending sign-in)` : ""));
+                (pendingCourseIds.length > 0 ? ` (${pendingCourseIds.length} pending sign-in)` : "") +
+                (failedCourseIds.length > 0 ? ` (${failedCourseIds.length} failed)` : ""));
             // 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) {
+            // shape change would break every existing caller. A pending or failed
+            // course instead adds a second content block carrying the notice,
+            // which names which course ids are unavailable.
+            const notices = [];
+            if (pendingCourseIds.length > 0) {
+                notices.push("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.`);
+            }
+            if (failedCourseIds.length > 0) {
+                notices.push(`Calendar events for ${failedCourseIds.length} course(s) (${failedCourseIds.join(", ")}) ` +
+                    "could not be read from Brightspace, so they are missing from this list. Do not report " +
+                    "these courses as having no events: call get_calendar_events again with that courseId.");
+            }
+            if (notices.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.`);
+            return toolResponseWithNotice(events, notices.join(" "));
         }
         catch (error) {
             return sanitizeError(error);

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

@@ -9,6 +9,7 @@ import { toolResponse, sanitizeError } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
 import { log } from "../utils/logger.js";
+import { extractCourseFilePaths } from "../utils/course-files.js";
 import { contentAvailability } from "./content-availability.js";
 // Topic type mapping
 const TOPIC_TYPE_MAP = {
@@ -108,6 +109,7 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
             else if (currentDepth >= MAX_CONTENT_DEPTH) {
                 log('DEBUG', `Content depth ceiling of ${MAX_CONTENT_DEPTH} reached at module ${item.Id}: not descending further`);
             }
+            const courseFiles = item.Description?.Html ? extractCourseFilePaths(item.Description.Html, courseId) : [];
             // Only include module if it has matching children (or filter is 'all')
             if (typeFilter === 'all' || processedChildren.length > 0) {
                 tree.push({
@@ -117,6 +119,7 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                     description: item.Description?.Html?.trim()
                         ? convertHtmlToMarkdown(item.Description.Html).markdown
                         : item.Description?.Text ?? null,
+                    ...(courseFiles.length > 0 ? { courseFiles } : {}),
                     ...(item.ModuleDueDate ? { dueDate: item.ModuleDueDate } : {}),
                     ...(item.IsHidden ? { isHidden: item.IsHidden } : {}),
                     ...(item.IsLocked ? { isLocked: item.IsLocked } : {}),

package/build/tools/schemas.js

@@ -69,6 +69,8 @@ export const DownloadFileSchema = z.object({
         .describe("Course ID the file belongs to."),
     topicId: z.coerce.number().int().positive().optional()
         .describe("Content topic ID to download (for course content files)."),
+    coursePath: z.string().min(1).max(1024).optional()
+        .describe("A file in the course's file store, for files an instructor linked inside a module or page description instead of adding as a content topic (get_course_content lists them as courseFiles on the module). Pass one of those paths (e.g. 'Notes/Lecture 1.pdf') or the whole quickLink URL. Not combined with topicId, folderId, or newsId."),
     folderId: z.coerce.number().int().positive().optional()
         .describe("Dropbox folder ID. Downloads your submission by default; set source to assignmentAttachment for an instructor-provided handout."),
     fileId: z.coerce.number().int().positive().optional()

package/build/utils/course-files.js

@@ -0,0 +1,56 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+export const QUICKLINK_PATH = "/d2l/common/dialogs/quickLink/quickLink.d2l";
+/**
+ * Reduce a coursePath argument to a plain course-file path ("Notes/a.pdf").
+ * Accepts that path or the quickLink URL a module description carries, and
+ * refuses anything that could name a file outside the course file store, so
+ * the argument can only ever steer the request inside this course's files.
+ */
+export function parseCoursePath(input, courseId) {
+    let filePath = input.trim();
+    if (filePath.includes("quickLink.d2l")) {
+        let link;
+        try {
+            link = new URL(filePath, "https://placeholder.invalid");
+        }
+        catch {
+            return { error: "coursePath is not a valid quickLink URL." };
+        }
+        if (link.pathname !== QUICKLINK_PATH || link.searchParams.get("type") !== "coursefile") {
+            return { error: "coursePath must be a course file path or a quickLink URL with type=coursefile." };
+        }
+        const ou = link.searchParams.get("ou");
+        if (ou !== null && ou !== String(courseId)) {
+            return { error: `This quickLink belongs to course ${ou}, not course ${courseId}.` };
+        }
+        filePath = link.searchParams.get("fileId") ?? "";
+    }
+    const segments = filePath.split("/");
+    if (filePath === "" ||
+        filePath.startsWith("/") ||
+        filePath.includes("\\") ||
+        filePath.includes("://") ||
+        segments.some(segment => segment === ".." || segment === "." || segment === "")) {
+        return { error: "coursePath must be a relative path inside the course files (e.g. 'Notes/Lecture 1.pdf'), without '..' segments." };
+    }
+    return filePath;
+}
+/**
+ * The course file paths a module description links through
+ * `quickLink.d2l?type=coursefile`, in page order, once each. Read from the raw
+ * HTML because the Markdown conversion escapes parentheses in file names.
+ * Anything parseCoursePath would refuse, and links to other courses, are left out.
+ */
+export function extractCourseFilePaths(html, courseId) {
+    const found = [];
+    for (const [, href] of html.matchAll(/href\s*=\s*["']([^"']*quickLink\.d2l[^"']*)["']/gi)) {
+        const parsed = parseCoursePath(href.replace(/&/g, "&"), courseId);
+        if (typeof parsed === "string" && !found.includes(parsed))
+            found.push(parsed);
+    }
+    return found;
+}

package/package.json

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