brightspace-mcp-server 5.0.12 → 5.1.4

package/build/utils/course-files.js

@@ -6,10 +6,12 @@
 import { tagAttributes } from "./html-attributes.js";
 import { toBrightspacePath } from "./transcript/lti.js";
 export const QUICKLINK_PATH = "/d2l/common/dialogs/quickLink/quickLink.d2l";
+const ENFORCED_PREFIX = "/content/enforced/";
 /**
  * Reduce a coursePath argument to a plain course-file path ("Notes/a.pdf").
- * Accepts that path or the quickLink URL a module description carries, and
- * refuses anything that could name a file outside the course file store, so
+ * Accepts that path, the quickLink URL a module description carries, or the
+ * `/content/enforced/<course folder>/...` href an assignment's instructions
+ * carry, and refuses anything that could name a file outside the course file store, so
  * the argument can only ever steer the request inside this course's files.
  * An absolute quickLink URL must be on `origin`; without one, only a
  * root-relative link is accepted.
@@ -19,16 +21,10 @@ export function parseCoursePath(input, courseId, origin) {
     // A plain course-file path never starts with "/" or names a scheme, so
     // anything that does is a link, however its file name reads.
     if (filePath.startsWith("/") || /^[a-z][a-z\d+.-]*:\/\//i.test(filePath)) {
-        const brightspacePath = toBrightspacePath(filePath, origin);
-        const link = brightspacePath === null ? null : new URL(brightspacePath, "https://placeholder.invalid");
-        if (link === null || link.pathname !== QUICKLINK_PATH || link.searchParams.get("type") !== "coursefile") {
-            return { error: "coursePath must be a course file path or a quickLink URL on this Brightspace with type=coursefile." };
-        }
-        const ou = link.searchParams.get("ou");
-        if (ou !== null && ou !== String(courseId)) {
-            return { error: `This quickLink belongs to course ${ou}, not course ${courseId}.` };
-        }
-        filePath = link.searchParams.get("fileId") ?? "";
+        const linked = enforcedFilePath(filePath, courseId, origin) ?? quickLinkFilePath(filePath, courseId, origin);
+        if (typeof linked !== "string")
+            return linked;
+        filePath = linked;
     }
     const segments = filePath.split("/");
     if (filePath === "" ||
@@ -40,6 +36,66 @@ export function parseCoursePath(input, courseId, origin) {
     }
     return filePath;
 }
+/** The course-file path a `quickLink.d2l?type=coursefile` link names, or why it can't be used. */
+function quickLinkFilePath(input, courseId, origin) {
+    const brightspacePath = toBrightspacePath(input, origin);
+    const link = brightspacePath === null ? null : new URL(brightspacePath, "https://placeholder.invalid");
+    if (link === null || link.pathname !== QUICKLINK_PATH || link.searchParams.get("type") !== "coursefile") {
+        return { error: "coursePath must be a course file path, a /content/enforced/ link, or a quickLink URL on this Brightspace with type=coursefile." };
+    }
+    const ou = link.searchParams.get("ou");
+    if (ou !== null && ou !== String(courseId)) {
+        return { error: `This quickLink belongs to course ${ou}, not course ${courseId}.` };
+    }
+    return link.searchParams.get("fileId") ?? "";
+}
+/**
+ * The course-file path a `/content/enforced/<course folder>/<path>` href
+ * names, an error when it names one unsafely, or null when the input is not
+ * such an href. Read from the raw text, not a parsed URL, because URL parsing
+ * would resolve a `..` (or `%2e%2e`) segment out of the course folder before
+ * it could be refused. A folder named `<ou>-...` must belong to this course.
+ */
+function enforcedFilePath(input, courseId, origin) {
+    let path = input;
+    if (!path.startsWith("/")) {
+        let link;
+        try {
+            link = new URL(path);
+        }
+        catch {
+            return null;
+        }
+        if (!origin || link.origin !== new URL(origin).origin || link.username || link.password)
+            return null;
+        path = path.slice(path.indexOf("/", path.indexOf("//") + 2));
+    }
+    if (!path.startsWith(ENFORCED_PREFIX))
+        return null;
+    // Brightspace serves a backslash in a course-file path as a folder separator
+    // (old imported courses link files as csfiles\home_dir\...), so it is read
+    // as one here, before the segments are checked.
+    const [folder, ...rest] = path.slice(ENFORCED_PREFIX.length).split(/[?#]/)[0].replace(/\\/g, "/").split("/");
+    const ou = /^(\d+)-/.exec(folder)?.[1];
+    if (ou !== undefined && ou !== String(courseId)) {
+        return { error: `This file belongs to course ${ou}, not course ${courseId}.` };
+    }
+    const segments = [];
+    for (const segment of rest) {
+        let decoded;
+        try {
+            decoded = decodeURIComponent(segment);
+        }
+        catch {
+            return { error: "coursePath is not a valid link: it has malformed percent-encoding." };
+        }
+        // An encoded "/" would let one segment smuggle in several, ".." among them.
+        if (decoded.includes("/"))
+            return { error: "coursePath must not hide a '/' inside a single path segment." };
+        segments.push(decoded);
+    }
+    return segments.join("/");
+}
 /**
  * The course file paths a module description links through
  * `quickLink.d2l?type=coursefile`, in page order, once each. Read from the raw

package/build/utils/dev-activity.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { AUTH_PHASES } from "../auth/auth-phases.js";
+import { ERROR_KINDS, errorKind, resultErrorKind } from "./error-kind.js";
 const calls = new AsyncLocalStorage();
 const runId = randomUUID();
 const MAX_BYTES = 5 * 1024 * 1024;
@@ -42,6 +43,8 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
         record.reason = fields.reason;
     if (AUTH_PHASES.includes(fields.phase ?? ""))
         record.phase = fields.phase;
+    if (ERROR_KINDS.includes(fields.errorKind ?? ""))
+        record.errorKind = fields.errorKind;
     try {
         mkdirSync(directory, { recursive: true, mode: 0o700 });
         const file = join(directory, `activity-${at.slice(0, 10)}-${process.pid}-${runId}.jsonl`);
@@ -77,16 +80,24 @@ export function trackToolActivity(server) {
         lastStart = started;
         return calls.run(context, async () => {
             let outcome = "error";
+            let kind;
             try {
                 const result = await callback(...args);
-                if (!result?.isError) {
+                if (result?.isError) {
+                    kind = resultErrorKind(result);
+                }
+                else {
                     outcome = "success";
                     lastSuccess = Date.now();
                 }
                 return result;
             }
+            catch (error) {
+                kind = errorKind(error);
+                throw error;
+            }
             finally {
-                write("tool_finished", { outcome, elapsedMs: Date.now() - started });
+                write("tool_finished", { outcome, errorKind: kind, elapsedMs: Date.now() - started });
             }
         });
     })));

package/build/utils/error-kind.js

@@ -0,0 +1,47 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * A diagnostic category for a failed tool call, chosen from a closed set this
+ * package controls. Derived from the error's type and status only, never from
+ * its message, so the dev activity log can say why a call failed without
+ * recording paths, URLs, arguments, or content.
+ */
+import { ZodError } from "zod";
+import { ApiError, NetworkError } from "../api/errors.js";
+import { AuthProcessError } from "../auth/auth-runner.js";
+import { DownloadError } from "./download-errors.js";
+export const ERROR_KINDS = ["invalidInput", "destination", "notFound", "permission", "auth", "rateLimited", "http",
+    "transport", "providerBlocked", "unsupportedFormat", "rejectedFile", "unknown"];
+const API_STATUS_KINDS = {
+    401: "auth", 403: "permission", 404: "notFound", 429: "rateLimited",
+};
+export function errorKind(error) {
+    if (error instanceof ZodError)
+        return "invalidInput";
+    if (error instanceof AuthProcessError)
+        return "auth";
+    if (error instanceof ApiError)
+        return API_STATUS_KINDS[error.status] ?? "http";
+    if (error instanceof NetworkError)
+        return "transport";
+    if (error instanceof DownloadError) {
+        return error.kind === "unsupportedType" || error.kind === "undetectableType" ? "unsupportedFormat" : "rejectedFile";
+    }
+    return "unknown";
+}
+const resultKinds = new WeakMap();
+/** Remembers which error a returned tool result describes. */
+export function withErrorKind(result, error) {
+    return tagErrorKind(result, errorKind(error));
+}
+/** Records the category of an error result a tool built itself. */
+export function tagErrorKind(result, kind) {
+    resultKinds.set(result, kind);
+    return result;
+}
+/** The category of a returned error result; "unknown" when no error was attached. */
+export function resultErrorKind(result) {
+    return (typeof result === "object" && result !== null && resultKinds.get(result)) || "unknown";
+}

package/build/utils/startup-phase.js

@@ -0,0 +1,37 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { log } from "./logger.js";
+/** How long a phase may run before one "still waiting" warning is logged. */
+const SLOW_PHASE_MS = 10_000;
+/**
+ * Run one startup step with timestamped stderr lines around it: one before
+ * the work starts, one with its duration when it ends, and a single warning
+ * if it is still running after SLOW_PHASE_MS. A client whose initialize
+ * request times out can then see which step the server was stuck in.
+ *
+ * The phase name is printed verbatim, so it must never carry a username,
+ * URL, or any other account detail.
+ */
+export async function startupPhase(name, work) {
+    log("INFO", `Startup: ${name}...`);
+    const started = Date.now();
+    const slow = setTimeout(() => {
+        log("WARN", `Startup: still ${name} after ${SLOW_PHASE_MS / 1000} s`);
+    }, SLOW_PHASE_MS);
+    slow.unref?.();
+    try {
+        const result = await work();
+        log("INFO", `Startup: ${name} done in ${Date.now() - started} ms`);
+        return result;
+    }
+    catch (error) {
+        log("WARN", `Startup: ${name} failed after ${Date.now() - started} ms`);
+        throw error;
+    }
+    finally {
+        clearTimeout(slow);
+    }
+}

package/package.json

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