brightspace-mcp-server 3.7.10 → 3.7.11

package/README.md

@@ -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/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.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",