brightspace-mcp-server 3.7.8 → 3.7.11

package/README.md

@@ -6,7 +6,7 @@ Talk to your Brightspace courses with AI. Ask about grades, due dates, quizzes,
 
 This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects your AI to D2L Brightspace so it can pull your grades, assignments, syllabus, and course content on demand.
 
-Connects to D2L Brightspace. Automatic login supports Purdue's Microsoft Entra flow and SUNY campus selection. Other schools need a compatible automated sign-in flow; unsupported login pages return an actionable error.
+Connects to D2L Brightspace. Automatic login supports Purdue's Microsoft Entra flow, SUNY campus selection, Western University, and TU Delft NetID via SURFconext. Other schools need a compatible automated sign-in flow; unsupported login pages return an actionable error.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/RohanMuppa/brightspace-mcp-server/main/docs/how-it-works.svg" alt="Architecture diagram" width="100%">
@@ -28,7 +28,7 @@ Paste this into Claude Code, Cursor, Windsurf, Copilot, Codex, or any AI coding
 ```
 Install brightspace-mcp-server for me by following
 https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
-(use --purdue if I'm at Purdue, or --suny if I'm at a SUNY campus).
+(use --purdue at Purdue, --suny at SUNY, or --tudelft at TU Delft).
 ```
 
 **Option 2: Run it yourself**
@@ -50,6 +50,14 @@ you're at and skips SUNY's campus picker when you sign in:
 npx -y brightspace-mcp-server@latest setup --suny
 ```
 
+TU Delft students can use `--tudelft` to select the Brightspace URL and NetID login:
+
+```bash
+npx -y brightspace-mcp-server@latest setup --tudelft
+```
+
+Use your NetID rather than your student email address. The TU Delft flow is headless NetID username and password sign-in only, including automatic re-authentication when the saved session expires; it does not support MFA or any other interactive step. If your account requires one, [open an issue](https://github.com/RohanMuppa/brightspace-mcp-server/issues) — that tenant isn't supported yet.
+
 The wizard saves your password in the native credential store and asks how you complete MFA. Authentication can wait for approval or number matching, prompt in the terminal for a code from Google Authenticator or another app, or open a visible browser for other interactive methods. The wizard can configure Claude Desktop, Cursor, Codex Desktop and CLI, and Claude Code when they are installed. Restart your AI client when it finishes.
 
 Any other D2L school: run `setup` without a flag and paste your Brightspace URL (for example `https://yourschool.brightspace.com`).
@@ -127,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/index.js

@@ -6,6 +6,7 @@
 export { BrowserAuth } from "./browser-auth.js";
 export { PurdueSSOFlow } from "./purdue-sso.js";
 export { SunySSOFlow, isSunyBrightspace } from "./suny-sso.js";
+export { TUDelftSSOFlow, isTUDelftBrightspace } from "./tudelft-sso.js";
 export { createSSOFlow } from "./sso-flow.js";
 export { TokenManager } from "./token-manager.js";
 export { SessionStore } from "./session-store.js";

package/build/auth/sso-flow.js

@@ -6,6 +6,7 @@
 import { PurdueSSOFlow } from "./purdue-sso.js";
 import { SunySSOFlow, isSunyBrightspace } from "./suny-sso.js";
 import { WesternSSOFlow, isWesternBrightspace } from "./western-sso.js";
+import { TUDelftSSOFlow, isTUDelftBrightspace } from "./tudelft-sso.js";
 import { BrowserAuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 export class UnsupportedAuthenticationError extends BrowserAuthError {
@@ -44,6 +45,9 @@ export function createSSOFlow(config, requestMfaCode, onMfaChallenge) {
         requestMfaCode,
         onMfaChallenge,
     };
+    if (isTUDelftBrightspace(config.baseUrl)) {
+        return new TUDelftSSOFlow(credentials);
+    }
     if (isSunyBrightspace(config.baseUrl)) {
         return new SunySSOFlow({ ...credentials, campus: config.campus });
     }

package/build/auth/tudelft-sso.js

@@ -0,0 +1,144 @@
+/** TU Delft NetID login via SURFconext. Licensed under MIT; see LICENSE. */
+import { UnsupportedAuthenticationError } from "./sso-flow.js";
+import { BrowserAuthError } from "../utils/errors.js";
+import { log } from "../utils/logger.js";
+const BRIGHTSPACE_HOST = "brightspace.tudelft.nl";
+const NETID_HOST = "login.tudelft.nl";
+const SURFCONEXT_HOST = "engine.surfconext.nl";
+const LOGIN_TIMEOUT_MS = 60_000;
+// Give the login page time to settle after submission before trusting any
+// alert banner as a rejection: a 1 second margin, or two polls, whichever a
+// given test/runtime environment can observe.
+const REJECTION_SETTLE_MS = 1_000;
+const REJECTION_SETTLE_POLLS = 2;
+const REJECTION_TEXT_PATTERN = /invalid|incorrect|rejected|wrong|failed|onjuist|ongeldig/i;
+export function isTUDelftBrightspace(baseUrl) {
+    try {
+        return new URL(baseUrl).hostname.toLowerCase() === BRIGHTSPACE_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+async function firstVisible(page, selectors) {
+    for (const selector of selectors) {
+        const locator = page.locator(selector).first();
+        if (await locator.isVisible().catch(() => false))
+            return locator;
+    }
+    return null;
+}
+function isNetID(url) {
+    return url.protocol === "https:" && url.hostname.toLowerCase() === NETID_HOST;
+}
+/**
+ * Only a specific error container counts as a rejection on its own. A bare
+ * `[role="alert"]` is also common for benign, standing banners (maintenance
+ * notices, cookie prompts) that have nothing to do with the credentials just
+ * submitted, so it only counts when its text reads like a rejection.
+ */
+async function findRejectionAlert(page) {
+    const specific = await firstVisible(page, ['.form-error', '.login-error', '.alert-danger', '#error', '[role="alert"].error']);
+    if (specific)
+        return specific;
+    const generic = await firstVisible(page, ['[role="alert"]']);
+    if (generic) {
+        const text = (await generic.textContent().catch(() => null)) ?? "";
+        if (REJECTION_TEXT_PATTERN.test(text))
+            return generic;
+    }
+    return null;
+}
+/** NetID uses a simultaneous username/password form and normally requires no MFA. */
+export class TUDelftSSOFlow {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    hasCredentials() {
+        return Boolean(this.config.username && this.config.password);
+    }
+    async login(page) {
+        if (!this.hasCredentials())
+            return false;
+        log("INFO", "Starting TU Delft NetID sign-in");
+        let submitted = false;
+        let submittedAt = null;
+        let pollsSinceSubmit = 0;
+        let consentSubmitted = false;
+        const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+        try {
+            do {
+                let current;
+                try {
+                    current = new URL(page.url());
+                }
+                catch {
+                    // Not a parseable URL (e.g. a transient navigation state). Give it
+                    // another poll instead of treating it as a fatal unknown host.
+                    await page.waitForTimeout(250);
+                    continue;
+                }
+                if (current.protocol !== "https:" && current.protocol !== "http:") {
+                    // about:blank and similar interstitial pages show up between
+                    // navigations; they're not an identity-provider page to evaluate.
+                    await page.waitForTimeout(250);
+                    continue;
+                }
+                if (current.origin === `https://${BRIGHTSPACE_HOST}` && /^\/d2l\/home(?:\/|$)/.test(current.pathname)) {
+                    return true;
+                }
+                if (isNetID(current)) {
+                    if (!submitted) {
+                        const username = await firstVisible(page, ['input#username', 'input[name="username"]', 'input[name="j_username"]']);
+                        const password = await firstVisible(page, ['input#password', 'input[name="password"]', 'input[name="j_password"]']);
+                        const submit = await firstVisible(page, ['#submit_button', 'button[name="_eventId_proceed"]', 'button[type="submit"]', 'input[type="submit"]']);
+                        if (username && password && submit) {
+                            await username.fill(this.config.username);
+                            // Recheck after the account field: a navigation must never send
+                            // the password to a different origin using a stale locator.
+                            if (!isNetID(new URL(page.url()))) {
+                                throw new UnsupportedAuthenticationError("TU Delft sign-in left the trusted NetID page before password entry.");
+                            }
+                            await password.fill(this.config.password);
+                            await submit.click();
+                            submitted = true;
+                            submittedAt = Date.now();
+                        }
+                    }
+                    else {
+                        pollsSinceSubmit++;
+                        const settled = pollsSinceSubmit >= REJECTION_SETTLE_POLLS
+                            || (submittedAt !== null && Date.now() - submittedAt >= REJECTION_SETTLE_MS);
+                        // Recheck the host: the alert lookup is async and must not act on
+                        // a page that has since navigated away from NetID.
+                        if (settled && isNetID(new URL(page.url())) && await findRejectionAlert(page)) {
+                            throw new UnsupportedAuthenticationError("TU Delft NetID sign-in was rejected. Check the saved NetID and password.");
+                        }
+                    }
+                }
+                else if (current.protocol === "https:" && current.hostname.toLowerCase() === SURFCONEXT_HOST) {
+                    // A user's first visit may require consent to share information with
+                    // Brightspace. No credentials are entered on SURFconext itself.
+                    if (!consentSubmitted) {
+                        const consent = await firstVisible(page, ['#consent_accept', 'button[name="confirm"]', 'input[name="confirm"]', 'input[name="yes"]']);
+                        if (consent) {
+                            await consent.click();
+                            consentSubmitted = true;
+                        }
+                    }
+                }
+                else if (current.origin !== `https://${BRIGHTSPACE_HOST}`) {
+                    throw new UnsupportedAuthenticationError("TU Delft sign-in reached an unsupported identity-provider page. No credentials were entered there.");
+                }
+                await page.waitForTimeout(250);
+            } while (Date.now() < deadline);
+            throw new UnsupportedAuthenticationError("TU Delft NetID sign-in did not reach Brightspace within 60 seconds. Check the saved credentials or retry with D2L_HEADLESS=false for an interactive sign-in.");
+        }
+        catch (error) {
+            if (error instanceof BrowserAuthError)
+                throw error;
+            throw new UnsupportedAuthenticationError("TU Delft NetID sign-in could not complete automatically.", error);
+        }
+    }
+}

package/build/setup.js

@@ -24,6 +24,13 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 const thisDir = path.dirname(fileURLToPath(import.meta.url));
 export const SCHOOL_PRESETS = {
+    tudelft: {
+        name: "TU Delft",
+        baseUrl: "https://brightspace.tudelft.nl",
+        usernameLabel: "TU Delft NetID",
+        mfaNote: "NetID sign-in normally runs headlessly without MFA.",
+        usernameHint: "Use your NetID, not your student email address.",
+    },
     purdue: {
         name: "Purdue University",
         baseUrl: "https://purdue.brightspace.com",

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.8",
+  "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",