brightspace-mcp-server 3.7.10 → 3.7.12

package/README.md

@@ -99,7 +99,7 @@ There is nothing to log into first. Ask for your grades and the sign-in happens
 
 Returning the next day normally requires no action. The server renews short-lived API tokens over HTTPS using the saved Brightspace session. If that session ends, a browser restores your saved Microsoft session and tries silent SSO. Approval and code-based modes stay headless; when an automatic run needs a code, run the auth command below to enter it securely in the terminal.
 
-If visible-browser mode is configured, the window stays open for up to five minutes so you can finish credentials and MFA manually when automatic sign-in cannot continue. Rerunning setup preserves your previous hidden or visible choice as the prompt default.
+If visible-browser mode is configured, the auth command opens a window that stays open for up to five minutes so you can finish credentials and MFA manually when automatic sign-in cannot continue. Background recovery during a tool call always runs headless so it never opens a browser over your work; set `D2L_HEADLESS=false` in the server's environment to let it open one too. Rerunning setup preserves your previous hidden or visible choice as the prompt default.
 
 Your school's policy controls when MFA is required. There is no local 24-hour cutoff, and the server no longer discards browser state after one hour. A network outage preserves the saved session and returns a temporary error.
 
@@ -135,5 +135,9 @@ The number in that response can go stale if the request times out or you tap Den
 | Calendar | "When is my midterm?" · "What's on my calendar this week?" · "Is lab cancelled on Thursday?" — reads exams, labs, review sessions, and deadlines instructors put only on the course calendar |
 | Planning | "Build me a study schedule based on my upcoming due dates" · "Which class needs the most attention right now?" — pulls from assignments, quizzes, graded discussion topics (any topic with a due date), and course calendar events such as exams and labs |
 
+`get_course_content` reports `isAvailable`, `availabilityStatus` (`available`, `not_yet_open`, `ended`, `hidden`, or `locked`), `availabilityMessage`, `startDate`, and `endDate` for modules and topics. The effective release window includes restrictions inherited from enclosing modules.
+
+When a content-file download returns 403 or 404, `download_file` checks topic metadata and the course table of contents. Confirmed restrictions return `{ success: false, available: false, reason, message, startDate, endDate }` so the assistant can explain when content opens or why it has closed. Unexplained 404s and server/network failures retain their original errors.
+
 
 Licensed under the MIT License.

package/build/auth/auth-runner.js

@@ -111,7 +111,8 @@ function forwardLines(stream, emit) {
  * re-authenticate when the current session has expired.
  *
  * The child inherits the parent's resolved environment and working directory,
- * so both processes read the same account configuration and .env file.
+ * so both processes read the same account configuration and .env file. It
+ * runs headless unless D2L_HEADLESS is set explicitly.
  *
  * run() settles as soon as the child reports an MFA challenge (with or
  * without a number to display) rather than waiting for the child to exit —
@@ -241,9 +242,13 @@ export class AuthRunner {
             const child = spawn(process.execPath, // use the same Node binary
             [this.scriptPath, "--automatic"], {
                 cwd: process.cwd(),
-                env: { ...process.env },
+                // Background recovery never opens a browser over the user's work
+                // unless D2L_HEADLESS explicitly asks for one; the saved
+                // visible-browser preference applies to manual sign-in only.
+                env: { D2L_HEADLESS: "true", ...process.env },
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: process.platform !== "win32",
+                windowsHide: true,
             });
             let timedOut = false;
             // Whether the caller-facing promise above (resolve/reject) has

package/build/tools/content-availability.js

@@ -0,0 +1,50 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+const ISO_8601_PATTERN = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+function validDate(value) {
+    return typeof value === "string" &&
+        ISO_8601_PATTERN.test(value.trim()) &&
+        Number.isFinite(Date.parse(value))
+        ? value
+        : null;
+}
+function limitDate(own, parent, latest) {
+    if (!own)
+        return parent;
+    if (!parent)
+        return own;
+    return (Date.parse(own) > Date.parse(parent)) === latest ? own : parent;
+}
+/** Dates explain a scheduled lock more precisely than the generic IsLocked flag. */
+export function contentAvailability(item, now = new Date(), parent) {
+    const ownStart = validDate(item.ModuleStartDate) ?? validDate(item.StartDate) ?? validDate(item.StartDateTime);
+    const ownEnd = validDate(item.ModuleEndDate) ?? validDate(item.EndDate) ?? validDate(item.EndDateTime);
+    const startDate = limitDate(ownStart, parent?.startDate ?? null, true);
+    const endDate = limitDate(ownEnd, parent?.endDate ?? null, false);
+    let availabilityStatus = "available";
+    let availabilityMessage = "Available";
+    if (item.IsHidden === true || parent?.availabilityStatus === "hidden") {
+        availabilityStatus = "hidden";
+        availabilityMessage = "This content is hidden by the instructor.";
+    }
+    else if (endDate && Date.parse(endDate) <= now.getTime()) {
+        availabilityStatus = "ended";
+        availabilityMessage = `This content's availability window has ended (closed at ${endDate}).`;
+    }
+    else if (item.IsLocked === true || parent?.availabilityStatus === "locked") {
+        availabilityStatus = "locked";
+        availabilityMessage = "This content is locked by the instructor or an enclosing module.";
+    }
+    else if (startDate && endDate && Date.parse(startDate) >= Date.parse(endDate)) {
+        availabilityStatus = "locked";
+        availabilityMessage = "The content and its enclosing modules have no overlapping availability window.";
+    }
+    else if (startDate && Date.parse(startDate) > now.getTime()) {
+        availabilityStatus = "not_yet_open";
+        availabilityMessage = `This content has not been released by the instructor yet (available from ${startDate}).`;
+    }
+    return { isAvailable: availabilityStatus === "available", availabilityStatus, availabilityMessage, startDate, endDate };
+}

package/build/tools/download-file.js

@@ -3,9 +3,11 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import { ApiError } from "../api/index.js";
 import { DownloadFileSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse } 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.
@@ -19,7 +21,7 @@ import path from "node:path";
 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.",
+        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).",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {
@@ -103,8 +105,20 @@ async function downloadContentFile(apiClient, courseId, topicId, downloadPath, c
     log("INFO", `Downloading content file: courseId=${courseId}, topicId=${topicId}`);
     // Build download URL using D2L API path helper
     const apiPath = apiClient.le(courseId, `/content/topics/${topicId}/file`);
-    // Fetch file using getRaw (returns Response object, not parsed JSON)
-    const response = await apiClient.getRaw(apiPath);
+    // 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);
+    }
+    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);
+        }
+        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) {

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 { contentAvailability } from "./content-availability.js";
 // Topic type mapping
 const TOPIC_TYPE_MAP = {
     1: 'file',
@@ -39,13 +40,32 @@ function matchesTypeFilter(item, filter) {
  * recursion would never come back.
  */
 const MAX_CONTENT_DEPTH = 12;
+/**
+ * Availability fields are additive, matching the isHidden/isLocked convention
+ * above: an available item carries none of them (absence = available), and a
+ * restricted one omits startDate/endDate when there is no actual bound
+ * rather than emitting a null.
+ */
+function availabilityFields(availability) {
+    if (availability.isAvailable)
+        return {};
+    const { isAvailable, availabilityStatus, availabilityMessage, startDate, endDate } = availability;
+    return {
+        isAvailable,
+        availabilityStatus,
+        availabilityMessage,
+        ...(startDate ? { startDate } : {}),
+        ...(endDate ? { endDate } : {}),
+    };
+}
 /**
  * Recursively build the content tree with progress tracking.
  */
-async function buildContentTree(apiClient, courseId, modules, progressMap, typeFilter, maxDepth, currentDepth = 0) {
+async function buildContentTree(apiClient, courseId, modules, progressMap, typeFilter, maxDepth, currentDepth = 0, parentAvailability, now = new Date()) {
     const tree = [];
     const depthLimit = Math.min(maxDepth ?? MAX_CONTENT_DEPTH, MAX_CONTENT_DEPTH);
     for (const item of modules) {
+        const availability = contentAvailability(item, now, parentAvailability);
         if (item.Type === 0) {
             // Module: fetch children recursively (unless the depth limit is reached)
             let processedChildren = [];
@@ -67,7 +87,7 @@ async function buildContentTree(apiClient, courseId, modules, progressMap, typeF
                 if (!Array.isArray(children)) {
                     children = Array.isArray(item.Structure) ? item.Structure : [];
                 }
-                processedChildren = await buildContentTree(apiClient, courseId, children, progressMap, typeFilter, maxDepth, currentDepth + 1);
+                processedChildren = await buildContentTree(apiClient, courseId, children, progressMap, typeFilter, maxDepth, currentDepth + 1, availability, now);
             }
             else if (currentDepth >= MAX_CONTENT_DEPTH) {
                 log('DEBUG', `Content depth ceiling of ${MAX_CONTENT_DEPTH} reached at module ${item.Id}: not descending further`);
@@ -82,6 +102,7 @@ async function buildContentTree(apiClient, courseId, modules, progressMap, typeF
                     ...(item.ModuleDueDate ? { dueDate: item.ModuleDueDate } : {}),
                     ...(item.IsHidden ? { isHidden: item.IsHidden } : {}),
                     ...(item.IsLocked ? { isLocked: item.IsLocked } : {}),
+                    ...availabilityFields(availability),
                     lastModified: item.LastModifiedDate ?? null,
                     children: processedChildren,
                 });
@@ -102,6 +123,7 @@ async function buildContentTree(apiClient, courseId, modules, progressMap, typeF
                 title: item.Title,
                 ...(item.IsHidden ? { isHidden: item.IsHidden } : {}),
                 ...(item.IsLocked ? { isLocked: item.IsLocked } : {}),
+                ...availabilityFields(availability),
                 ...(item.DueDate ? { dueDate: item.DueDate } : {}),
                 lastModified: item.LastModifiedDate ?? null,
                 isCompleted: topicProgress?.IsRead ?? false,
@@ -188,7 +210,7 @@ function countModules(tree) {
 export function registerGetCourseContent(server, apiClient) {
     server.registerTool("get_course_content", {
         title: "Get Course Content",
-        description: "Fetch the content tree for a course showing modules, topics, files, and links. Use this when the user asks about course materials, lecture slides, uploaded files, content structure, or what's in a course module. Use moduleTitle to filter to a specific module (e.g. 'Labs', 'Staff', 'Homeworks') instead of fetching the entire tree. Use maxDepth to limit recursion depth for a table-of-contents view.",
+        description: "Fetch the content tree for a course showing modules, topics, files, and links. Use this when the user asks about course materials, lecture slides, uploaded files, content structure, or what's in a course module. Use moduleTitle to filter to a specific module (e.g. 'Labs', 'Staff', 'Homeworks') instead of fetching the entire tree. Use maxDepth to limit recursion depth for a table-of-contents view. A module or topic that isn't currently available carries isAvailable/availabilityStatus/availabilityMessage (and startDate/endDate when known) explaining why; absence of these fields means it's available now.",
         inputSchema: GetCourseContentSchema,
     }, async (args) => {
         try {

package/build/tools/topic-availability.js

@@ -0,0 +1,94 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { ApiError, DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { contentAvailability } from "./content-availability.js";
+import { log } from "../utils/logger.js";
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function matchesTopic(value, topicId) {
+    return [value.TopicId, value.Identifier, value.Id].some(id => (typeof id === "number" || (typeof id === "string" && /^\d+$/.test(id))) && Number(id) === topicId);
+}
+/** A bounded iterative traversal also tolerates incomplete TOC responses. */
+function findTopic(toc, topicId, now) {
+    const modules = record(toc)?.Modules;
+    if (!Array.isArray(modules))
+        return null;
+    const queue = modules.map(module => ({ module }));
+    const visited = new Set();
+    for (let index = 0; index < queue.length && index < 10_000; index++) {
+        const entry = queue[index];
+        const module = record(entry.module);
+        if (!module || visited.has(module))
+            continue;
+        visited.add(module);
+        const availability = contentAvailability(module, now, entry.parent);
+        if (Array.isArray(module.Topics)) {
+            for (const raw of module.Topics) {
+                const topic = record(raw);
+                if (topic && matchesTopic(topic, topicId)) {
+                    return { metadata: topic, availability: contentAvailability(topic, now, availability) };
+                }
+            }
+        }
+        if (Array.isArray(module.Modules)) {
+            for (const nested of module.Modules)
+                queue.push({ module: nested, parent: availability });
+        }
+    }
+    return null;
+}
+/** Explain only restrictions backed by topic/TOC metadata; preserve unexplained download errors. */
+export async function checkTopicAvailability(client, courseId, topicId, httpStatus) {
+    if (httpStatus !== 403 && httpStatus !== 404)
+        return null;
+    const now = new Date();
+    let direct = null;
+    try {
+        const raw = record(await client.get(client.le(courseId, `/content/topics/${topicId}`), {
+            ttl: DEFAULT_CACHE_TTLS.courseContent,
+        }));
+        if (raw && matchesTopic(raw, topicId))
+            direct = raw;
+    }
+    catch (error) {
+        if (!(error instanceof ApiError) || (error.status !== 403 && error.status !== 404)) {
+            log("DEBUG", "Topic availability lookup failed unexpectedly; preserving the download error", error);
+            return null;
+        }
+    }
+    let fromToc = null;
+    try {
+        const toc = await client.get(client.le(courseId, "/content/toc"), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+        fromToc = findTopic(toc, topicId, now);
+    }
+    catch (error) {
+        log("DEBUG", "TOC availability lookup failed; using direct topic metadata if present", error);
+    }
+    if (!direct && !fromToc)
+        return null;
+    const metadata = direct ?? fromToc.metadata;
+    // A link or quiz has no file endpoint even after release. Preserve that
+    // failure instead of promising that its file will become downloadable.
+    const isNonFile = (item) => Boolean(item && (item.TopicType === 2 || item.TopicType === 3 ||
+        (typeof item.TypeIdentifier === "string" && ["link", "quiz", "discussion", "dropbox", "assignment"].includes(item.TypeIdentifier.toLowerCase()))));
+    if (isNonFile(direct) || isNonFile(fromToc?.metadata))
+        return null;
+    const availability = direct ? contentAvailability(direct, now, fromToc?.availability) : fromToc.availability;
+    const title = typeof metadata.Title === "string" ? metadata.Title
+        : typeof fromToc?.metadata.Title === "string" ? fromToc.metadata.Title : undefined;
+    // Additive only: if the metadata itself says the topic is available, it
+    // doesn't explain the download failure — keep the original error instead
+    // of manufacturing a misleading "restricted" response.
+    if (availability.isAvailable)
+        return null;
+    return {
+        success: false, available: false, courseId, topicId, ...(title ? { title } : {}),
+        reason: availability.availabilityStatus,
+        startDate: availability.startDate, endDate: availability.endDate,
+        message: availability.availabilityMessage,
+    };
+}

package/package.json

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