brightspace-mcp-server 3.9.18 → 3.9.20

package/README.md

@@ -66,7 +66,7 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 | Assignments and rubrics | "What does the lab 4 spec actually ask for?" · "Why did I lose points on the analysis criterion?" |
 | Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" |
 | Announcements | "Did any professor post something important today?" · "Read the file attached to today's announcement" |
-| Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "Search this course for office hours" |
+| Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "Search this course for office hours" · or just read a file inline instead of saving it |
 | People | "Who are the TAs for ECE 264?" · "Who is in my project group?" |
 | Discussions | "Summarize the latest posts in the final project thread" |
 | Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura and YouTube) |

package/build/tools/download-file.js

@@ -5,23 +5,213 @@
  */
 import { ApiError } from "../api/index.js";
 import { DownloadFileSchema } from "./schemas.js";
-import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, errorResponse, withUpdateNotice } 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.
-import { validateContentId, MAX_FILE_SIZE } from "../utils/file-validator.js";
+// Path containment checks belong to secureDownload, which disk-mode downloads
+// go through; importing it here only made it look as though this file
+// validated anything itself. Inline mode never writes to disk, so it calls
+// validateFileType directly to enforce the same magic-byte allowlist.
+import { validateContentId, validateFileType, MAX_FILE_SIZE } from "../utils/file-validator.js";
 import { secureDownload } from "../utils/download-helpers.js";
+import { extractPdfText } from "../utils/pdf-extractor.js";
+import { officeDocumentText } from "../utils/zip-extract.js";
 import fs from "node:fs/promises";
 import path from "node:path";
+/**
+ * Maximum bytes of a file we'll embed inline in a tool response. Base64
+ * encoding (for images) adds ~33% overhead, so this stays well under typical
+ * MCP response-size limits. A file over this cap still works — the caller
+ * just needs to pass an absolute `downloadPath` to save it to disk instead.
+ */
+const INLINE_MAX_SIZE = 10 * 1024 * 1024; // 10 MB
+/**
+ * Maximum bytes of an image specifically that we'll embed inline as an MCP
+ * ImageContent block. Base64 encoding adds ~33% overhead, so a file right up
+ * against INLINE_MAX_SIZE (10 MB) would base64-encode to ~13.6 MB — comfortably
+ * over the model API's ~5 MB per-image limit, which fails the *entire* tool
+ * response, not just the image block. A tighter cap here (3.5 MB raw, ~4.7 MB
+ * base64) keeps every inlined image under that limit; a larger image falls
+ * through to the binary_description_only branch with a note to use
+ * downloadPath instead.
+ */
+const INLINE_IMAGE_MAX_SIZE = 3.5 * 1024 * 1024; // 3.5 MB
+/**
+ * Maximum characters of extracted text (PDF, Office document, or plain text)
+ * inlined into a single tool response. ~400,000 characters is roughly 100k
+ * tokens — enough for most course documents — and a hard cap keeps one
+ * runaway file from dominating the conversation.
+ */
+const INLINE_TEXT_MAX_CHARS = 400_000;
+/**
+ * MCP ImageContent blocks are passed to Anthropic's vision pipeline, which
+ * accepts JPEG, PNG, GIF, and WebP. Any other image mime (SVG, BMP, TIFF)
+ * falls back to the generic "can't display inline" path below.
+ */
+const INLINE_IMAGE_MIMES = new Set([
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+]);
+/** OOXML formats `officeDocumentText` (zip-extract.ts) knows how to read. */
+const INLINE_OFFICE_MIMES = new Set([
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document", // .docx
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", // .xlsx
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation", // .pptx
+]);
+/** Mime types whose bytes are safe to decode as UTF-8 and inline verbatim. */
+const INLINE_TEXT_MIMES = new Set(["text/plain", "text/csv", "text/html", "application/json"]);
+/** Truncate text to `max` characters, noting how much was cut and why. */
+function truncateForInline(text, max) {
+    if (text.length <= max)
+        return { body: text, truncated: false };
+    const remaining = text.length - max;
+    return {
+        body: text.slice(0, max) +
+            `\n\n[...truncated at ${max} characters; ${remaining} more characters exist in the source file. ` +
+            "Re-run with an absolute downloadPath to save the full file to disk instead...]",
+        truncated: true,
+    };
+}
+/**
+ * Inline mode: return the file directly in the tool response instead of
+ * writing it to disk. This is the right mode inside clients like Claude
+ * Desktop, where the MCP server's host filesystem is not the same filesystem
+ * its analysis/sandbox tools see — a file `download_file` wrote to disk there
+ * was simply unreachable from the rest of the conversation.
+ *
+ * Deliberately emits only TextContent and, for a handful of image mimes,
+ * ImageContent — never an MCP EmbeddedResource. Claude Desktop feeds an
+ * EmbeddedResource with mimeType `application/pdf` into Anthropic's document
+ * pipeline, which rejects PDFs containing JBIG2-compressed images (common in
+ * scanned academic PDFs) and can fail the *entire* tool response, even next
+ * to perfectly good TextContent blocks. Extracted text sidesteps that
+ * pipeline entirely. (Adapted from LunaParker/brightspace-mcp-server, MIT.)
+ */
+async function respondInline(buffer, originalFilename, customFilename) {
+    const effectiveFilename = customFilename || originalFilename;
+    if (buffer.length > INLINE_MAX_SIZE) {
+        return errorResponse(`File too large for inline delivery (${Math.round(buffer.length / 1024 / 1024)}MB, inline max ${INLINE_MAX_SIZE / 1024 / 1024}MB). Provide an absolute downloadPath to save it to disk instead.`);
+    }
+    // Enforces the same magic-byte allowlist as disk mode (secureDownload calls
+    // validateFileType internally); inline mode never writes to disk, so it has
+    // to call this itself. Throws DownloadError on an unsupported or
+    // undetectable type, handled by the caller's sanitizeError.
+    const { mime } = await validateFileType(buffer, undefined, effectiveFilename);
+    const metadata = {
+        mode: "inline",
+        filename: effectiveFilename,
+        originalFilename,
+        mimeType: mime,
+        size: buffer.length,
+    };
+    const content = [];
+    if (mime === "application/pdf") {
+        const extracted = await extractPdfText(buffer);
+        if (!extracted || !extracted.text) {
+            metadata.representation = "pdf_text_extraction_failed";
+            metadata.note =
+                "No text layer found in this PDF (it may be a scan). Re-run with an absolute downloadPath to save the raw file to disk.";
+            content.push({ type: "text", text: JSON.stringify(metadata) });
+            return withUpdateNotice(content);
+        }
+        const { body, truncated } = truncateForInline(extracted.text, INLINE_TEXT_MAX_CHARS);
+        metadata.representation = "extracted_text";
+        metadata.pages = extracted.totalPages;
+        metadata.truncated = truncated;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({
+            type: "text",
+            text: `--- Extracted PDF text (${extracted.totalPages} page${extracted.totalPages === 1 ? "" : "s"})${truncated ? ", truncated" : ""} ---\n${body}`,
+        });
+    }
+    else if (INLINE_IMAGE_MIMES.has(mime)) {
+        if (buffer.length > INLINE_IMAGE_MAX_SIZE) {
+            // Base64-encoding a file this size would exceed the model API's image
+            // limit and fail the whole response, so this falls back to the same
+            // "can't display inline" path as an unsupported binary format rather
+            // than emitting an oversized ImageContent block.
+            metadata.representation = "binary_description_only";
+            metadata.note = `This image is too large to inline (${Math.round(buffer.length / 1024 / 1024)}MB, inline image max ${INLINE_IMAGE_MAX_SIZE / 1024 / 1024}MB). Re-run download_file with an absolute downloadPath to save it to disk instead.`;
+            content.push({ type: "text", text: JSON.stringify(metadata) });
+            return withUpdateNotice(content);
+        }
+        metadata.representation = "image";
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({ type: "image", data: buffer.toString("base64"), mimeType: mime });
+    }
+    else if (INLINE_OFFICE_MIMES.has(mime)) {
+        // Reuses the same zip-based text extraction get_assignment_files and
+        // get_announcement_files already rely on (attachment-reader.ts) rather
+        // than duplicating it here.
+        const text = officeDocumentText(buffer);
+        if (!text) {
+            metadata.representation = "office_text_extraction_failed";
+            metadata.note =
+                "No readable text found in this Office document. Re-run with an absolute downloadPath to save the raw file to disk.";
+            content.push({ type: "text", text: JSON.stringify(metadata) });
+            return withUpdateNotice(content);
+        }
+        const { body, truncated } = truncateForInline(text, INLINE_TEXT_MAX_CHARS);
+        metadata.representation = "extracted_text";
+        metadata.truncated = truncated;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({ type: "text", text: `--- Extracted text (${effectiveFilename}) ---\n${body}` });
+    }
+    else if (INLINE_TEXT_MIMES.has(mime)) {
+        const raw = buffer.toString("utf-8");
+        const { body, truncated } = truncateForInline(raw, INLINE_TEXT_MAX_CHARS);
+        metadata.representation = "text";
+        metadata.truncated = truncated;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+        content.push({ type: "text", text: `--- File contents (${effectiveFilename}) ---\n${body}` });
+    }
+    else {
+        // Binary formats we can't meaningfully show in the conversation (zip,
+        // legacy .doc/.ppt/.xls, video, audio, svg, ...). Emitting an
+        // EmbeddedResource here would put us back in the PDF-rejection failure
+        // mode described above, so this just points the caller at disk mode.
+        metadata.representation = "binary_description_only";
+        metadata.note = `This file type (${mime}) cannot be displayed inline. Re-run download_file with an absolute downloadPath to save it to disk instead.`;
+        content.push({ type: "text", text: JSON.stringify(metadata) });
+    }
+    return withUpdateNotice(content);
+}
+/**
+ * Finish a download once the bytes are in hand: write to disk when
+ * `downloadPath` is given (unchanged response shape, plus a new `mode: "disk"`
+ * field), otherwise return the file inline in the tool response.
+ */
+async function finishDownload(buffer, originalFilename, downloadPath, customFilename, sourceLabel) {
+    if (downloadPath === undefined) {
+        return respondInline(buffer, originalFilename, customFilename);
+    }
+    const effectiveFilename = customFilename || originalFilename;
+    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
+    const result = await secureDownload({
+        targetDir: downloadPath,
+        filename: effectiveFilename,
+        data: buffer,
+    });
+    log("INFO", `${sourceLabel} downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
+    return toolResponse({
+        mode: "disk",
+        success: true,
+        filePath: result.path,
+        fileSize: result.size,
+        mimeType: result.mime,
+        originalFilename,
+        message: `File downloaded successfully to ${result.path}`,
+    });
+}
 /**
  * Register download_file tool
  */
 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. 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, 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 {
@@ -30,22 +220,27 @@ export function registerDownloadFile(server, apiClient) {
             const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename } = DownloadFileSchema.parse(args);
             // Validate courseId
             validateContentId(courseId);
-            // Validate download path is absolute
-            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)");
-            }
-            // Validate download directory exists and is a directory
-            try {
-                const stats = await fs.stat(downloadPath);
-                if (!stats.isDirectory()) {
-                    return errorResponse(`Download path is not a directory: ${downloadPath}`);
+            // downloadPath is optional: omitting it means "return the file
+            // inline" (see respondInline), so there is nothing on the host
+            // filesystem to validate in that case.
+            if (downloadPath !== undefined) {
+                // Validate download path is absolute
+                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)");
                 }
-            }
-            catch (error) {
-                if (error?.code === "ENOENT") {
-                    return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                // Validate download directory exists and is a directory
+                try {
+                    const stats = await fs.stat(downloadPath);
+                    if (!stats.isDirectory()) {
+                        return errorResponse(`Download path is not a directory: ${downloadPath}`);
+                    }
+                }
+                catch (error) {
+                    if (error?.code === "ENOENT") {
+                        return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                    }
+                    throw error;
                 }
-                throw error;
             }
             // Determine download source
             if (topicId !== undefined) {
@@ -134,24 +329,8 @@ async function downloadContentFile(apiClient, courseId, topicId, downloadPath, c
     if (buffer.length > MAX_FILE_SIZE) {
         return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
     }
-    // Use custom filename if provided, otherwise use Content-Disposition filename
     const originalFilename = filename;
-    const effectiveFilename = customFilename || filename;
-    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
-    const result = await secureDownload({
-        targetDir: downloadPath,
-        filename: effectiveFilename,
-        data: buffer,
-    });
-    log("INFO", `File downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
-    return toolResponse({
-        success: true,
-        filePath: result.path,
-        fileSize: result.size,
-        mimeType: result.mime,
-        originalFilename,
-        message: `File downloaded successfully to ${result.path}`,
-    });
+    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Content file");
 }
 /**
  * Download a submission/feedback file using folderId + fileId
@@ -203,24 +382,8 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
     if (buffer.length > MAX_FILE_SIZE) {
         return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
     }
-    // Use custom filename if provided, otherwise use original submission filename
     const originalFilename = file.FileName;
-    const effectiveFilename = customFilename || file.FileName;
-    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
-    const result = await secureDownload({
-        targetDir: downloadPath,
-        filename: effectiveFilename,
-        data: buffer,
-    });
-    log("INFO", `Submission file downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
-    return toolResponse({
-        success: true,
-        filePath: result.path,
-        fileSize: result.size,
-        mimeType: result.mime,
-        originalFilename,
-        message: `File downloaded successfully to ${result.path}`,
-    });
+    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Submission file");
 }
 /**
  * Download an announcement attachment using newsId + fileId
@@ -252,20 +415,5 @@ async function downloadNewsAttachment(apiClient, courseId, newsId, fileId, downl
         return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
     }
     const originalFilename = filename;
-    const effectiveFilename = customFilename || filename;
-    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
-    const result = await secureDownload({
-        targetDir: downloadPath,
-        filename: effectiveFilename,
-        data: buffer,
-    });
-    log("INFO", `Announcement attachment downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
-    return toolResponse({
-        success: true,
-        filePath: result.path,
-        fileSize: result.size,
-        mimeType: result.mime,
-        originalFilename,
-        message: `File downloaded successfully to ${result.path}`,
-    });
+    return finishDownload(buffer, originalFilename, downloadPath, customFilename, "Announcement attachment");
 }

package/build/tools/get-announcements.js

@@ -130,6 +130,8 @@ export function registerGetAnnouncements(server, apiClient, config) {
                 code: item.OrgUnit.Code,
                 isActive: item.Access.IsActive,
                 canAccess: item.Access.CanAccess,
+                startDate: item.Access.StartDate,
+                endDate: item.Access.EndDate,
                 ...item,
             })), config.courseFilter);
             // Fetch announcements for each course (handle 403s gracefully)

package/build/tools/get-assignments.js

@@ -457,6 +457,8 @@ export function registerGetAssignments(server, apiClient, config) {
                 code: item.OrgUnit.Code,
                 isActive: item.Access.IsActive,
                 canAccess: item.Access.CanAccess,
+                startDate: item.Access.StartDate,
+                endDate: item.Access.EndDate,
                 ...item,
             })), config.courseFilter);
             // Fetch assignments for each course (handle 403s gracefully)

package/build/tools/get-my-courses.js

@@ -42,6 +42,8 @@ export function registerGetMyCourses(server, apiClient, config) {
                 role: item.Access.ClasslistRoleName,
                 isActive: item.Access.IsActive,
                 canAccess: item.Access.CanAccess,
+                startDate: item.Access.StartDate,
+                endDate: item.Access.EndDate,
                 lastAccessed: item.Access.LastAccessed,
             })), { ...config.courseFilter, activeOnly });
             log("INFO", `get_my_courses: Retrieved ${courses.length} courses`);

package/build/tools/get-my-grades.js

@@ -77,6 +77,8 @@ export function registerGetMyGrades(server, apiClient, config) {
                 code: item.OrgUnit.Code,
                 isActive: item.Access.IsActive,
                 canAccess: item.Access.CanAccess,
+                startDate: item.Access.StartDate,
+                endDate: item.Access.EndDate,
                 ...item,
             })), config.courseFilter);
             // Fetch grades for each course (handle 403s gracefully)

package/build/tools/resolve-courses.js

@@ -41,6 +41,8 @@ export async function resolveCourses(apiClient, config, courseId) {
         code: item.OrgUnit.Code,
         isActive: item.Access.IsActive,
         canAccess: item.Access.CanAccess,
+        startDate: item.Access.StartDate,
+        endDate: item.Access.EndDate,
     })), config.courseFilter);
     return filtered.map((course) => ({ id: course.id, name: course.name }));
 }

package/build/tools/schemas.js

@@ -72,8 +72,8 @@ export const DownloadFileSchema = z.object({
         .describe("Specific file ID within a dropbox submission, or an announcement attachment's file ID (with newsId)."),
     newsId: z.coerce.number().int().positive().optional()
         .describe("Announcement (news item) ID whose attachment to download. Requires fileId."),
-    downloadPath: z.string().min(1)
-        .describe("Absolute path to the directory where the file should be saved."),
+    downloadPath: z.string().min(1).optional()
+        .describe("Absolute path to the directory where the file should be saved on disk. Omit this to receive the file inline in the tool response instead — the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see files an MCP server writes to its own host filesystem. Inline mode returns extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, and a short description (pointing back to disk mode) for anything else, capped at 10MB and 400,000 characters of extracted text."),
     customFilename: z.string().max(255).optional()
         .describe("Custom filename for the downloaded file (include extension). If not provided, uses the original filename from Brightspace."),
 });

package/build/tools/tool-helpers.js

@@ -11,26 +11,36 @@ import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { getUpdateNotice } from "../utils/update-checker.js";
 import { DownloadError, isSafeDetail, } from "../utils/download-errors.js";
+/**
+ * Append an available-update notice to an already-built content array and
+ * wrap it as a CallToolResult. This is the one place an update notice can
+ * reach a user regardless of which tool (or which response mode within a
+ * tool) they happen to hit, and it is throttled inside getUpdateNotice so a
+ * busy session is not spammed. `toolResponse` and any hand-built multi-block
+ * result (e.g. download_file's inline mode) both funnel through here so
+ * neither path can silently drop the notice.
+ */
+export function withUpdateNotice(content) {
+    const notice = getUpdateNotice();
+    if (notice)
+        content.push({ type: "text", text: notice });
+    return { content };
+}
 /**
  * Wrap data as MCP-compatible tool result.
  *
  * Every tool returns through here, which makes it the one place an update
  * notice can reach a user regardless of which tool they happen to call. The
  * notice is appended as a separate content block so content[0].text stays a
- * pure JSON document for anything parsing it, and it is throttled inside
- * getUpdateNotice so a busy session is not spammed.
+ * pure JSON document for anything parsing it.
  */
 export function toolResponse(data) {
-    const content = [
+    return withUpdateNotice([
         {
             type: "text",
             text: JSON.stringify(data),
         },
-    ];
-    const notice = getUpdateNotice();
-    if (notice)
-        content.push({ type: "text", text: notice });
-    return { content };
+    ]);
 }
 /**
  * Wrap error message as MCP-compatible tool result

package/build/utils/config.js

@@ -67,6 +67,12 @@ export async function loadConfig() {
     const activeOnly = envBoolean(process.env.D2L_ACTIVE_ONLY, "D2L_ACTIVE_ONLY")
         ?? store?.activeOnly
         ?? true;
+    // Resolve currentOnly: env > store > default (false). When true, a course
+    // only passes the filter if Access.StartDate <= now <= Access.EndDate,
+    // matching Brightspace's "Current Courses" widget.
+    const currentOnly = envBoolean(process.env.D2L_CURRENT_ONLY, "D2L_CURRENT_ONLY")
+        ?? store?.currentOnly
+        ?? false;
     // D2L_ACCESS_TOKEN beats D2L_SESSION_COOKIE beats the normal stored-credential
     // browser flow; both are validated whenever present regardless of which one
     // wins, so a typo in the losing variable still fails loudly at startup.
@@ -100,6 +106,7 @@ export async function loadConfig() {
             includeCourseIds,
             excludeCourseIds,
             activeOnly,
+            currentOnly,
         },
     };
 }

package/build/utils/course-filter.js

@@ -4,18 +4,49 @@
  * Licensed under MIT — see LICENSE file for details.
  */
 import { log } from "./logger.js";
+/**
+ * True if `now` falls within [startDate, endDate].
+ *
+ * When both dates are null the course has no enrollment window at all — it's
+ * almost certainly an informational org unit (e.g. "Waterloo Campus",
+ * "Academic Integrity") rather than a term-bound course, so we return false.
+ * A single null side is treated as open-ended (start-only means "not yet
+ * ended", end-only means "already started"). A malformed date string is
+ * likewise treated as open-ended on that side rather than excluding the
+ * course outright.
+ *
+ * Adapted from LunaParker/brightspace-mcp-server (MIT), src/utils/course-filter.ts.
+ */
+function isCurrentlyInWindow(startDate, endDate, now) {
+    // Both null → undated org unit, not a current semester course.
+    if (!startDate && !endDate)
+        return false;
+    if (startDate) {
+        const start = Date.parse(startDate);
+        if (!Number.isNaN(start) && start > now)
+            return false;
+    }
+    if (endDate) {
+        const end = Date.parse(endDate);
+        if (!Number.isNaN(end) && end < now)
+            return false;
+    }
+    return true;
+}
 /**
  * Apply course filtering based on environment variable configuration.
  *
  * Filter priority:
  * 1. activeOnly — exclude inactive courses (default: true)
- * 2. includeCourseIds — whitelist (only these courses)
- * 3. excludeCourseIds — blacklist (remove these courses)
+ * 2. currentOnly — exclude courses outside their Access.StartDate/EndDate
+ *    window, matching Brightspace's "Current Courses" widget (default: false)
+ * 3. includeCourseIds — whitelist (only these courses)
+ * 4. excludeCourseIds — blacklist (remove these courses)
  *
  * Tool-level courseId params bypass this filter entirely —
  * if user explicitly requests courseId=X, honor it regardless of config.
  */
-export function applyCourseFilter(courses, config) {
+export function applyCourseFilter(courses, config, now = Date.now()) {
     let filtered = courses;
     const originalCount = courses.length;
     if (config.activeOnly) {
@@ -26,6 +57,9 @@ export function applyCourseFilter(courses, config) {
         // removes about 70 percent of the requests an all-courses call would make.
         filtered = filtered.filter(c => c.canAccess !== false);
     }
+    if (config.currentOnly) {
+        filtered = filtered.filter(c => isCurrentlyInWindow(c.startDate, c.endDate, now));
+    }
     if (config.includeCourseIds && config.includeCourseIds.length > 0) {
         filtered = filtered.filter(c => config.includeCourseIds.includes(c.id));
     }
@@ -35,6 +69,7 @@ export function applyCourseFilter(courses, config) {
     if (filtered.length !== originalCount) {
         log("DEBUG", `Course filter: ${originalCount} -> ${filtered.length} courses`, {
             activeOnly: config.activeOnly,
+            currentOnly: config.currentOnly,
             include: config.includeCourseIds,
             exclude: config.excludeCourseIds,
         });

package/package.json

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