brightspace-mcp-server 5.0.13 → 5.1.5

package/build/utils/dev-activity.js

@@ -3,6 +3,47 @@ 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 API = String.raw `^/d2l/api/l[pe]/[^/]+/`;
+const COURSE = API + String.raw `\d+/`;
+/** First match wins; a path that matches none is "other". Matched on the path alone, query dropped. */
+const HTTP_OPERATIONS = [
+    ["versions", "^/d2l/api/versions/"],
+    ["whoami", API + "users/whoami"],
+    ["enrollments", API + "enrollments/"],
+    ["groups", COURSE + String.raw `groupcategories/\d+/groups/`],
+    ["groupCategories", COURSE + "groupcategories/"],
+    ["ltiLinks", API + "lti/link/"],
+    ["quizList", COURSE + "quizzes/?$"],
+    ["quizAttempts", COURSE + String.raw `quizzes/\d+/attempts/`],
+    ["quiz", COURSE + "quizzes/"],
+    ["dropboxFolders", COURSE + "dropbox/folders/?$"],
+    ["dropboxSubmissions", COURSE + String.raw `dropbox/folders/\d+/submissions/`],
+    ["dropboxFeedback", COURSE + String.raw `dropbox/folders/\d+/feedback/`],
+    ["dropboxAttachment", COURSE + String.raw `dropbox/folders/\d+/attachments/`],
+    ["dropboxFolder", COURSE + "dropbox/folders/"],
+    ["dropboxFeedbackPage", "^/d2l/lms/dropbox/user/folder_user_view_feedback"],
+    ["rubrics", COURSE + "rubrics"],
+    ["grades", COURSE + "grades/"],
+    ["contentFile", COURSE + String.raw `content/topics/\d+/file`],
+    ["content", COURSE + "content/"],
+    ["newsAttachment", COURSE + String.raw `news/\d+/attachments/`],
+    ["news", COURSE + "news/"],
+    ["discussions", COURSE + "discussions/"],
+    ["overviewAttachment", COURSE + "overview/attachment"],
+    ["overview", COURSE + "overview"],
+    ["classlist", COURSE + "classlist/"],
+    ["quickLink", "^/d2l/common/dialogs/quickLink/"],
+    // The LTI launch page a video quickLink leads to (get_video_transcript).
+    ["ltiLaunch", String.raw `^/d2l/le/lti/\d+/toolLaunch/`],
+];
+const OPERATION_PATTERNS = HTTP_OPERATIONS.map(([name, pattern]) => [name, new RegExp(pattern)]);
+const OPERATION_NAMES = [...HTTP_OPERATIONS.map(([name]) => name), "other"];
+/** Names what a request was for without keeping its endpoint, IDs or query. */
+export function httpOperation(path) {
+    const bare = path.split(/[?#]/, 1)[0];
+    return OPERATION_PATTERNS.find(([, pattern]) => pattern.test(bare))?.[0] ?? "other";
+}
 const calls = new AsyncLocalStorage();
 const runId = randomUUID();
 const MAX_BYTES = 5 * 1024 * 1024;
@@ -42,6 +83,10 @@ 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;
+    if (OPERATION_NAMES.includes(fields.operation ?? ""))
+        record.operation = fields.operation;
     try {
         mkdirSync(directory, { recursive: true, mode: 0o700 });
         const file = join(directory, `activity-${at.slice(0, 10)}-${process.pid}-${runId}.jsonl`);
@@ -77,16 +122,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.13",
+  "version": "5.1.5",
   "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",