brightspace-mcp-server 4.1.0 → 5.0.1

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/brightspace-mcp-server.svg)](https://www.npmjs.com/package/brightspace-mcp-server)
 [![CI](https://img.shields.io/github/actions/workflow/status/RohanMuppa/brightspace-mcp-server/ci.yml?branch=main)](https://github.com/RohanMuppa/brightspace-mcp-server/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/github/license/RohanMuppa/brightspace-mcp-server.svg)](LICENSE)
-[![Node >= 20](https://img.shields.io/node/v/brightspace-mcp-server.svg)](package.json)
+[![Node >= 22](https://img.shields.io/node/v/brightspace-mcp-server.svg)](package.json)
 
 > **By [Rohan Muppa](https://github.com/rohanmuppa), ECE @ Purdue**
 
@@ -20,7 +20,7 @@ Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, and a
 
 ## Get started in 3 steps
 
-1. **Install [Node.js](https://nodejs.org/)** (version 20 or newer) if you don't have it. Download, run the installer, done.
+1. **Install [Node.js](https://nodejs.org/)** (version 22 or newer) if you don't have it. Download, run the installer, done.
 2. **Open a terminal and run the setup:**
    ```bash
    npx -y brightspace-mcp-server@latest setup

package/build/doctor.js

@@ -79,9 +79,9 @@ function problem(id, message) {
 // ── Individual checks ────────────────────────────────────────────────
 function checkNode(deps) {
     if (nodeVersionSupported(deps.nodeVersion)) {
-        return pass("node", `Node.js ${deps.nodeVersion} (20 or newer)`);
+        return pass("node", `Node.js ${deps.nodeVersion} (22 or newer)`);
     }
-    return problem("node", `Node.js ${deps.nodeVersion} is too old — install Node 20 or newer from https://nodejs.org/, then try again.`);
+    return problem("node", `Node.js ${deps.nodeVersion} is too old — install Node 22 or newer from https://nodejs.org/, then try again.`);
 }
 /**
  * Checks the resolved configuration — config.json AND the same env overrides

package/build/setup/prepare.js

@@ -98,8 +98,8 @@ export async function runPrepare(args, overrides = {}) {
     const steps = [];
     // ── Node ──
     steps.push(nodeVersionSupported(deps.nodeVersion)
-        ? ok("node", `Node.js ${deps.nodeVersion} (20 or newer)`)
-        : fail("node", `Node.js ${deps.nodeVersion} is too old — install Node 20 or newer from https://nodejs.org/`));
+        ? ok("node", `Node.js ${deps.nodeVersion} (22 or newer)`)
+        : fail("node", `Node.js ${deps.nodeVersion} is too old — install Node 22 or newer from https://nodejs.org/`));
     // ── School ──
     const existing = deps.readExistingConfig();
     let baseUrl;

package/build/tools/download-dropbox-submission-file.js

@@ -115,6 +115,7 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
             const result = await secureStreamDownload({
                 targetDir: downloadPath,
                 filename: effectiveFilename,
+                originalFilename,
                 body: response.body,
                 maxBytes: DISK_MAX_FILE_SIZE,
             });

package/build/tools/download-file.js

@@ -12,7 +12,7 @@ import { checkTopicAvailability } from "./topic-availability.js";
 // 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, DISK_MAX_FILE_SIZE, } from "../utils/file-validator.js";
+import { validateContentId, validateFileType, nameForType, MAX_FILE_SIZE, DISK_MAX_FILE_SIZE, } from "../utils/file-validator.js";
 import { secureStreamDownload, readBodyCapped } from "../utils/download-helpers.js";
 import { DownloadError } from "../utils/download-errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
@@ -114,7 +114,7 @@ async function respondInline(buffer, originalFilename, customFilename) {
     // validateFileTypeOfFile 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 { mime } = await validateFileType(buffer, undefined, effectiveFilename, originalFilename);
     const metadata = {
         mode: "inline",
         filename: effectiveFilename,
@@ -229,6 +229,7 @@ async function finishDownload(response, originalFilename, downloadPath, customFi
     const result = await secureStreamDownload({
         targetDir: downloadPath,
         filename: effectiveFilename,
+        originalFilename,
         body: response.body,
         maxBytes: DISK_MAX_FILE_SIZE,
     });
@@ -241,8 +242,25 @@ async function finishDownload(response, originalFilename, downloadPath, customFi
         mimeType: result.mime,
         originalFilename,
         message: `File downloaded successfully to ${result.path}`,
+        ...extensionNote(effectiveFilename, result),
     });
 }
+/**
+ * When the file was saved under a different extension than requested — a
+ * legacy .xls asked for as "Grades.xlsx" (#280) — say why, so the caller
+ * picks a reader for the format it really is. The saved extension comes from
+ * this package's own legacy Office table, never from the remote name.
+ */
+function extensionNote(requestedFilename, saved) {
+    const savedExt = path.extname(saved.path).toLowerCase();
+    const type = { mime: saved.mime, ext: savedExt.slice(1) };
+    if (nameForType(requestedFilename, type) === requestedFilename)
+        return {};
+    return {
+        note: `Saved with the ${savedExt} extension: this is a legacy Office 97-2003 file (${saved.mime}), ` +
+            `not the format the requested name implied. Open it with an application that reads ${savedExt} files.`,
+    };
+}
 /**
  * Register download_file tool
  */

package/build/utils/download-helpers.js

@@ -9,7 +9,7 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
-import { validateDownloadPath, validateFileType, validateFileTypeOfFile, MAX_FILE_SIZE, } from "./file-validator.js";
+import { validateDownloadPath, validateFileType, validateFileTypeOfFile, nameForType, MAX_FILE_SIZE, } from "./file-validator.js";
 import { DownloadError } from "./download-errors.js";
 import { log } from "./logger.js";
 /**
@@ -112,7 +112,7 @@ export async function secureDownload(options) {
  * @throws DownloadError("tooLarge") once the body passes maxBytes
  */
 export async function secureStreamDownload(options) {
-    const { targetDir, filename, body, maxBytes } = options;
+    const { targetDir, filename, originalFilename, body, maxBytes } = options;
     const safeFilename = path.basename(validateDownloadPath(targetDir, filename));
     const partialPath = path.join(targetDir, `.download-${randomUUID()}.part`);
     let size = 0;
@@ -129,8 +129,9 @@ export async function secureStreamDownload(options) {
     });
     try {
         await pipeline(Readable.fromWeb(body), limit, createWriteStream(partialPath, { flags: "wx" }));
-        const { mime } = await validateFileTypeOfFile(partialPath, undefined, safeFilename);
-        const finalPath = await publishExclusively(partialPath, targetDir, safeFilename);
+        const type = await validateFileTypeOfFile(partialPath, undefined, safeFilename, originalFilename);
+        const { mime } = type;
+        const finalPath = await publishExclusively(partialPath, targetDir, nameForType(safeFilename, type));
         log("INFO", `Downloaded file to ${finalPath} (${size} bytes, ${mime})`);
         return { path: finalPath, size, mime };
     }

package/build/utils/file-validator.js

@@ -20,6 +20,11 @@ import { DownloadError } from "./download-errors.js";
  * magic-byte allowlist exists to prevent. Reconcile against the declared
  * extension instead, which admits the formats the allowlist already intended
  * and still refuses everything else.
+ *
+ * The declared extension is the caller's customFilename when there is one, and
+ * that name is only a label: asking for "Grades.xlsx" does not make a legacy
+ * .xls OOXML (#280). So Brightspace's own name for the file is consulted too,
+ * and either one naming a legacy Office format admits it.
  */
 // file-type v21 is ESM-only and costs ~50ms; defer the import to first use
 // since validateFileType is already async.
@@ -148,7 +153,7 @@ export function validateDownloadPath(baseDir, filename) {
  * @returns Detected MIME type and extension
  * @throws Error if file type not allowed
  */
-export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES, filename) {
+export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES, filename, originalFilename) {
     // An empty body is not a text file. It reaches here when a fetch was
     // truncated or the server answered with nothing, and the UTF-8 fallback
     // below would otherwise wave it through as text/plain and write a zero-byte
@@ -160,7 +165,7 @@ export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES
     const { fileTypeFromBuffer } = await getFileType();
     const detected = await fileTypeFromBuffer(buffer);
     if (detected)
-        return allowDetectedType(detected, allowedTypes, filename);
+        return allowDetectedType(detected, allowedTypes, [filename, originalFilename]);
     return allowTextType(buffer, allowedTypes);
 }
 /**
@@ -170,7 +175,7 @@ export async function validateFileType(buffer, allowedTypes = ALLOWED_MIME_TYPES
  * same UTF-8 and NUL checks a chunk at a time, so plain text, CSV and JSON
  * are held to the disk download limit rather than to MAX_FILE_SIZE.
  */
-export async function validateFileTypeOfFile(filePath, allowedTypes = ALLOWED_MIME_TYPES, filename) {
+export async function validateFileTypeOfFile(filePath, allowedTypes = ALLOWED_MIME_TYPES, filename, originalFilename) {
     const { size } = await fs.stat(filePath);
     if (size === 0) {
         throw new DownloadError("undetectableType", "File is empty (0 bytes)");
@@ -178,26 +183,27 @@ export async function validateFileTypeOfFile(filePath, allowedTypes = ALLOWED_MI
     const { fileTypeFromFile } = await getFileType();
     const detected = await fileTypeFromFile(filePath);
     if (detected)
-        return allowDetectedType(detected, allowedTypes, filename);
+        return allowDetectedType(detected, allowedTypes, [filename, originalFilename]);
     return allowTextTypeOfFile(filePath, allowedTypes);
 }
-/** The allowlist decision for a type file-type recognised from magic bytes. */
-function allowDetectedType(detected, allowedTypes, filename) {
+/**
+ * The allowlist decision for a type file-type recognised from magic bytes.
+ * `names` are the file's candidate names, most authoritative first; only their
+ * extensions are read, and only to disambiguate a CFB or XML container.
+ */
+function allowDetectedType(detected, allowedTypes, names) {
     if (detected.mime === XML_MIME) {
-        const ext = filename ? path.extname(filename).toLowerCase() : "";
-        const resolved = XML_EXTENSION_MIMES[ext];
-        if (resolved && allowedTypes.includes(resolved)) {
-            return { mime: resolved, ext: ext.slice(1) };
-        }
+        const resolved = reconcileByExtension(XML_EXTENSION_MIMES, names, allowedTypes);
+        if (resolved)
+            return resolved;
         // Anything else falls through to the allowlist check, which refuses
         // application/xml the way it always has.
     }
     if (detected.mime === CFB_MIME) {
-        const ext = filename ? path.extname(filename).toLowerCase() : "";
-        const resolved = CFB_EXTENSION_MIMES[ext];
-        if (resolved && allowedTypes.includes(resolved)) {
-            return { mime: resolved, ext: ext.slice(1) };
-        }
+        const resolved = reconcileByExtension(CFB_EXTENSION_MIMES, names, allowedTypes);
+        if (resolved)
+            return resolved;
+        const ext = names[0] ? path.extname(names[0]).toLowerCase() : "";
         throw new DownloadError("unsupportedType", `Compound File Binary with extension '${ext || "none"}' is not an allowed Office format`, CFB_MIME);
     }
     if (!allowedTypes.includes(detected.mime)) {
@@ -205,6 +211,30 @@ function allowDetectedType(detected, allowedTypes, filename) {
     }
     return { mime: detected.mime, ext: detected.ext };
 }
+/** The first of `names` whose extension maps, through `table`, to an allowed type. */
+function reconcileByExtension(table, names, allowedTypes) {
+    for (const name of names) {
+        const ext = name ? path.extname(name).toLowerCase() : "";
+        const resolved = table[ext];
+        if (resolved && allowedTypes.includes(resolved)) {
+            return { mime: resolved, ext: ext.slice(1) };
+        }
+    }
+    return undefined;
+}
+/**
+ * The name to save a validated file under. Normally `filename` unchanged; but
+ * a legacy Office file whose requested name does not carry a matching
+ * extension (a .xls asked for as "Grades.xlsx", #280) gets its true extension,
+ * so nothing opens it expecting a format it is not.
+ */
+export function nameForType(filename, type) {
+    const isLegacyOffice = Object.values(CFB_EXTENSION_MIMES).includes(type.mime);
+    const ext = path.extname(filename);
+    if (!isLegacyOffice || CFB_EXTENSION_MIMES[ext.toLowerCase()] === type.mime)
+        return filename;
+    return `${filename.slice(0, filename.length - ext.length)}.${type.ext}`;
+}
 /**
  * Fallback for text-based files with no magic-byte signature: accept if the
  * buffer decodes as UTF-8 (rejecting binaries and NUL bytes), then sniff HTML.

package/build/utils/saved-session.js

@@ -52,8 +52,8 @@ export function sessionDirFor(env, store, baseUrl, username) {
             : path.join(os.homedir(), ".d2l-session");
     return accountSessionDirectory(sessionRoot, baseUrl, username);
 }
-/** True for the Node versions this package supports (20 and newer). */
+/** True for the Node versions this package supports (22 and newer). */
 export function nodeVersionSupported(version) {
     const major = Number(version.replace(/^v/, "").split(".")[0]);
-    return Number.isFinite(major) && major >= 20;
+    return Number.isFinite(major) && major >= 22;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "4.1.0",
+  "version": "5.0.1",
   "mcpName": "io.github.RohanMuppa/brightspace",
   "description": "MCP server for Brightspace (D2L). Check grades, due dates, assignments, announcements, syllabus, rosters and more via Claude, ChatGPT, Cursor, Windsurf, or any MCP client.",
   "type": "module",
@@ -30,7 +30,7 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@napi-rs/keyring": "^2.0.0",
     "dotenv": "^17.2.4",
-    "file-type": "^21.3.0",
+    "file-type": "^22.1.1",
     "playwright": "^1.58.2",
     "sanitize-filename": "^1.6.3",
     "trash": "^9.0.0",
@@ -45,7 +45,7 @@
     "vitest": "^5.0.3"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "license": "MIT",
   "author": "Rohan Muppa",