brightspace-mcp-server 5.1.4 → 5.1.6

package/build/api/client.js

@@ -11,7 +11,7 @@ import { ApiError, RateLimitError, NetworkError } from "./errors.js";
 import { withRetry, isRetryableFailure, retryAfterMsFrom, parseRetryAfter, } from "./retry.js";
 import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
-import { devActivity } from "../utils/dev-activity.js";
+import { devActivity, httpOperation } from "../utils/dev-activity.js";
 /**
  * True when a followed redirect ended on this Brightspace's sign-in page. A
  * web route asked with a dead cookie 302s there rather than serving the
@@ -426,8 +426,8 @@ export class D2LApiClient {
         return send(loggedIn);
     }
     /** Buckets one observed HTTP status into statsData.statusClasses. */
-    recordStatus(status) {
-        devActivity("http_response", { status });
+    recordStatus(status, path) {
+        devActivity("http_response", { status, operation: httpOperation(path) });
         const classes = this.statsData.statusClasses;
         if (status >= 200 && status < 300)
             classes["2xx"]++;
@@ -490,7 +490,7 @@ export class D2LApiClient {
                 headers,
                 signal: AbortSignal.timeout(this.timeoutMs),
             });
-            this.recordStatus(response.status);
+            this.recordStatus(response.status, path);
             // Preserve cookie material: a 401 only rejects this access token.
             if (response.status === 401) {
                 throw new ApiError(401, path, "Brightspace rejected the access token.");
@@ -558,7 +558,7 @@ export class D2LApiClient {
                 headers,
                 signal: idle.signal,
             });
-            this.recordStatus(response.status);
+            this.recordStatus(response.status, path);
             // Preserve cookie material for the shared HTTP refresh path.
             if (response.status === 401) {
                 throw new ApiError(401, path, "Brightspace rejected the access token.");

package/build/auth/auth-runner.js

@@ -10,7 +10,7 @@ import * as path from "node:path";
 import { log } from "../utils/logger.js";
 import { AuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
-import { devActivity } from "../utils/dev-activity.js";
+import { devActivity, newRecoveryId, RECOVERY_ID_ENV } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
 import { AUTOMATIC_PENDING_MARKER, RELAYED_CHALLENGE_MARKER, RELAYED_STARTING_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
 import { inspectLockOwner } from "./auth-lock.js";
@@ -693,7 +693,8 @@ export class AuthRunner {
      */
     async spawnAuth() {
         const started = Date.now();
-        devActivity("recovery_started");
+        const recoveryId = newRecoveryId();
+        devActivity("recovery_started", { recoveryId });
         log("INFO", "Auto-launching brightspace-auth...");
         return await new Promise((resolve, reject) => {
             const child = spawn(process.execPath, // use the same Node binary
@@ -702,7 +703,8 @@ export class AuthRunner {
                 // Background recovery never opens a browser over the user's work
                 // unless D2L_HEADLESS explicitly asks for one; the saved
                 // visible-browser preference applies to manual sign-in only.
-                env: { D2L_HEADLESS: "true", ...process.env },
+                // The recovery id lets the child's dev activity join this recovery.
+                env: { D2L_HEADLESS: "true", ...process.env, [RECOVERY_ID_ENV]: recoveryId },
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: process.platform !== "win32",
                 windowsHide: true,
@@ -831,7 +833,7 @@ export class AuthRunner {
                 const firstChallenge = this.pendingChallenge === null || this.pendingChallenge.kind === "automaticPending";
                 startWatching();
                 if (firstChallenge)
-                    devActivity("mfa_observed", { elapsedMs: Date.now() - started });
+                    devActivity("mfa_observed", { elapsedMs: Date.now() - started, recoveryId });
                 if (firstChallenge || matched) {
                     this.pendingChallenge = { kind: "mfaPending", numberMatch: matched ?? this.pendingChallenge?.numberMatch };
                 }
@@ -872,7 +874,7 @@ export class AuthRunner {
                 if (childFinished)
                     return;
                 childFinished = true;
-                devActivity("recovery_finished", { outcome: error ? "error" : "success", reason: error?.kind, elapsedMs: Date.now() - started });
+                devActivity("recovery_finished", { outcome: error ? "error" : "success", reason: error?.kind, elapsedMs: Date.now() - started, recoveryId });
                 clearTimeout(timer);
                 if (killTimer)
                     clearTimeout(killTimer);
@@ -914,7 +916,7 @@ export class AuthRunner {
                 const numberMarker = MFA_NUMBER_MARKER.exec(line);
                 const phaseMarker = parsePhaseMarker(line);
                 if (phaseMarker) {
-                    devActivity("auth_phase", phaseMarker);
+                    devActivity("auth_phase", { ...phaseMarker, recoveryId });
                 }
                 else if (numberMarker) {
                     numberMatch = numberMarker[1];

package/build/auth-cli.js

@@ -59,7 +59,7 @@ async function main() {
         const config = await loadConfig();
         // The sign-in itself runs here, not in the server, so the dev activity log
         // only sees its MFA events if this process is configured for them too.
-        configureDevActivity(config.sessionDir);
+        configureDevActivity(config.sessionDir, { version: pkg.version, role: "auth" });
         console.error(`\n=== Brightspace Authentication v${pkg.version} ===\n`);
         console.error(config.headless
             ? "Authentication runs headlessly. MFA numbers and code prompts appear here."

package/build/index.js

@@ -96,7 +96,7 @@ else {
             const { setActiveShortcuts } = await import("./utils/two-factor-shortcuts.js");
             const { startUpdateChecks } = await import("./utils/update-checker.js");
             const { createRuntime } = await import("./server.js");
-            configureDevActivity(config.sessionDir);
+            configureDevActivity(config.sessionDir, { version: PKG_VERSION, role: "server" });
             // Lets the MFA approval message mention the setup options only to users
             // who have neither turned on. Booleans only; the key is never passed.
             setActiveShortcuts({ rememberMfa: config.rememberMfa === true, keySaved: Boolean(config.totpUri) });

package/build/utils/dev-activity.js

@@ -4,27 +4,80 @@ 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";
+}
+/** Names one background recovery; the parent passes it to its auth child so their events join. */
+export const RECOVERY_ID_ENV = "D2L_RECOVERY_ID";
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const calls = new AsyncLocalStorage();
 const runId = randomUUID();
 const MAX_BYTES = 5 * 1024 * 1024;
 let directory;
 let warned = false;
+/** Set in an auth child: the parent recovery every event of this process belongs to. */
+let processRecoveryId;
 let lastStart;
 let lastSuccess;
 /** Explicit opt-in; separate from ordinary stderr debugging. */
-export function configureDevActivity(sessionDir) {
+export function configureDevActivity(sessionDir, run) {
     directory = process.env.D2L_DEV_MODE === "true" ? join(sessionDir, "dev-activity") : undefined;
     lastStart = lastSuccess = undefined;
     warned = false;
+    const inherited = process.env[RECOVERY_ID_ENV];
+    processRecoveryId = inherited && ID.test(inherited) ? inherited : undefined;
+    if (run)
+        write("run_started", {}, undefined, undefined, undefined, run);
+}
+/** A fresh, non-secret id for one recovery; see RECOVERY_ID_ENV. */
+export function newRecoveryId() {
+    return randomUUID();
 }
 /** No arbitrary text, errors, URLs, request arguments or response content. */
 export function devActivity(event, fields = {}) {
     write(event, fields);
 }
-function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs) {
+function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs, run) {
     if (!directory)
         return;
-    if (!["tool_started", "tool_finished", "http_response", "auth_required", "token_mint_started",
+    if (!["run_started", "tool_started", "tool_finished", "http_response", "auth_required", "token_mint_started",
         "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished", "auth_phase",
         "mfa_method_selected", "mfa_code_submitted"].includes(event))
         return;
@@ -32,6 +85,17 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
     const record = { at, runId, pid: process.pid, event };
     if (context)
         Object.assign(record, context);
+    // A child's inherited id wins: it is the one its parent recorded.
+    const recoveryId = processRecoveryId ?? fields.recoveryId;
+    if (recoveryId && ID.test(recoveryId))
+        record.recoveryId = recoveryId;
+    if (run) {
+        if (/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]{1,40})?$/.test(run.version))
+            record.version = run.version;
+        record.node = process.versions.node;
+        if (run.role === "server" || run.role === "auth")
+            record.role = run.role;
+    }
     for (const [key, value] of Object.entries({ elapsedMs: fields.elapsedMs, status: fields.status, idleMs, sinceSuccessMs })) {
         if (typeof value === "number" && Number.isFinite(value) && value >= 0)
             record[key] = value;
@@ -45,6 +109,8 @@ function write(event, fields, context = calls.getStore(), idleMs, sinceSuccessMs
         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`);

package/package.json

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