brightspace-mcp-server 5.1.5 → 5.1.7

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/tools/download-dropbox-submission-file.js

@@ -23,7 +23,8 @@ function tooLargeResponse(bytes) {
 export function registerDownloadDropboxSubmissionFile(server, apiClient) {
     server.registerTool("download_dropbox_submission_file", {
         title: "Download Dropbox Submission File",
-        description: "Download a specific file from a student's (or group's) dropbox submission to a local directory, " +
+        description: "Download a specific file from a student's (or group's) dropbox submission to an existing local directory " +
+            "(it is not created for you), " +
             "for an instructor or TA. Use get_dropbox_submissions or get_dropbox_user_submissions first to " +
             "find submissionId and fileId. Requires instructor or TA access to the course. " +
             "IMPORTANT: Ask the user where they want to save the file before calling this tool. " +
@@ -48,7 +49,7 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
             }
             catch (error) {
                 if (error?.code === "ENOENT") {
-                    return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
+                    return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
                 }
                 throw error;
             }

package/build/tools/download-file.js

@@ -267,7 +267,7 @@ function extensionNote(requestedFilename, saved) {
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), 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).",
+        description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), 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. The directory must already exist; it is not created for you. 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 {
@@ -299,7 +299,7 @@ export function registerDownloadFile(server, apiClient) {
                 }
                 catch (error) {
                     if (error?.code === "ENOENT") {
-                        return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
+                        return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
                     }
                     throw error;
                 }

package/build/tools/get-syllabus.js

@@ -110,7 +110,7 @@ async function discoverExternalSyllabusSources(apiClient, courseId) {
 export function registerGetSyllabus(server, apiClient) {
     server.registerTool("get_syllabus", {
         title: "Get Course Syllabus",
-        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. When the syllabus lives in an external LTI tool (e.g. Simple Syllabus), lists those sources in externalSyllabusSources; their contents cannot be read. If some of those lookups could not be completed (e.g. permission denied), externalSyllabusDiscovery says which, and an empty result is then not proof the course has no syllabus. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
+        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. When the syllabus lives in an external LTI tool (e.g. Simple Syllabus), lists those sources in externalSyllabusSources; their contents cannot be read. If some of those lookups could not be completed (e.g. permission denied), externalSyllabusDiscovery says which, and an empty result is then not proof the course has no syllabus. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF); the directory must already exist, since it is not created for you. IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
         inputSchema: GetSyllabusSchema,
     }, async (args) => {
         try {
@@ -129,7 +129,7 @@ export function registerGetSyllabus(server, apiClient) {
                 }
                 catch (error) {
                     if (error?.code === "ENOENT") {
-                        return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
+                        return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
                     }
                     throw error;
                 }

package/build/tools/schemas.js

@@ -78,7 +78,7 @@ export const DownloadFileSchema = z.object({
     newsId: z.coerce.number().int().positive().optional()
         .describe("Announcement (news item) ID whose attachment to download. Requires fileId."),
     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."),
+        .describe("Absolute path to an existing directory where the file should be saved on disk. The directory must already exist; it is not created for you, so create it first if needed. 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."),
 });
@@ -86,7 +86,7 @@ export const GetSyllabusSchema = z.object({
     courseId: z.coerce.number().int().positive()
         .describe("Course ID to get syllabus for."),
     downloadPath: z.string().min(1).optional()
-        .describe("Absolute path to the directory where the attachment should be saved."),
+        .describe("Absolute path to an existing directory where the attachment should be saved. The directory must already exist; it is not created for you, so create it first if needed."),
 });
 export const GetDiscussionsSchema = z.object({
     courseId: z.coerce.number().int().positive()
@@ -219,7 +219,7 @@ export const DownloadDropboxSubmissionFileSchema = z.object({
     fileId: z.coerce.number().int().positive()
         .describe("File ID within that submission."),
     downloadPath: z.string().min(1)
-        .describe("Absolute path to the local directory where the file should be saved."),
+        .describe("Absolute path to an existing local directory where the file should be saved. The directory must already exist; it is not created for you, so create it first if needed."),
     customFilename: z.string().max(255).optional()
         .describe("Custom filename for the downloaded file (include extension). If omitted, uses the original submission filename."),
 });

package/build/utils/dev-activity.js

@@ -44,27 +44,40 @@ 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;
@@ -72,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;

package/package.json

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