brightspace-mcp-server 3.10.6 → 3.10.9

package/README.md

@@ -101,6 +101,7 @@ All optional, set in your AI app's MCP `env` config or your shell. The full list
 | `D2L_INCLUDE_COURSES` / `D2L_EXCLUDE_COURSES` | Limit which courses the AI sees, by course id |
 | `D2L_ACTIVE_ONLY=false` | Include courses whose enrollment has ended |
 | `D2L_NO_UPDATE_CHECK=1` | Turn off the new-version notice |
+| `D2L_DEV_MODE=true` | Write a local, content-free log of tool calls and sign-in events, for debugging session problems ([how](docs/dev-mode.md)) |
 
 ## When it asks you to sign in
 

package/build/api/client.js

@@ -11,6 +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";
 /** An ordinary course HTML link to the login page is not an expired session. */
 function isExpiredSessionRedirect(body, baseUrl) {
     const expiredTarget = (target) => {
@@ -307,6 +308,7 @@ export class D2LApiClient {
     }
     /** Buckets one observed HTTP status into statsData.statusClasses. */
     recordStatus(status) {
+        devActivity("http_response", { status });
         const classes = this.statsData.statusClasses;
         if (status >= 200 && status < 300)
             classes["2xx"]++;
@@ -341,6 +343,7 @@ export class D2LApiClient {
      * If successful, returns the fresh token. Otherwise throws 401 ApiError.
      */
     async tryAutoReauth(path, rejectedAccessToken) {
+        devActivity("auth_required");
         if (this.onAuthExpired) {
             log("INFO", "Attempting auto-reauthentication...");
             const success = await this.onAuthExpired();

package/build/auth/auth-runner.js

@@ -9,6 +9,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";
 /**
  * Timeout for the auth process. It has to outlast the child's own MFA wait,
  * which is five minutes: a person has to find their phone, unlock it, and read
@@ -292,6 +293,8 @@ export class AuthRunner {
      * child's real completion is tracked separately on this.childDone.
      */
     async spawnAuth() {
+        const started = Date.now();
+        devActivity("recovery_started");
         log("INFO", "Auto-launching brightspace-auth...");
         return await new Promise((resolve, reject) => {
             const child = spawn(process.execPath, // use the same Node binary
@@ -384,6 +387,8 @@ export class AuthRunner {
             // fresh joiner sees it — see MFA_PENDING_MARKER's own comment.
             const publishChallenge = (matched) => {
                 const firstChallenge = this.pendingChallenge === null;
+                if (firstChallenge)
+                    devActivity("mfa_observed", { elapsedMs: Date.now() - started });
                 if (firstChallenge || matched) {
                     this.pendingChallenge = { numberMatch: matched ?? this.pendingChallenge?.numberMatch };
                 }
@@ -400,6 +405,7 @@ export class AuthRunner {
                 if (childFinished)
                     return;
                 childFinished = true;
+                devActivity("recovery_finished", { outcome: error ? "error" : "success", reason: error?.kind, elapsedMs: Date.now() - started });
                 clearTimeout(timer);
                 if (killTimer)
                     clearTimeout(killTimer);

package/build/auth/token-manager.js

@@ -7,6 +7,7 @@ import { SessionStore } from "./session-store.js";
 import { mintAccessToken } from "./token-mint.js";
 import { log } from "../utils/logger.js";
 import { TokenRefreshError } from "../api/errors.js";
+import { devActivity } from "../utils/dev-activity.js";
 /**
  * Token refresh buffer - tokens within this time of expiry are considered invalid.
  * This prevents using tokens that might expire during a request.
@@ -140,6 +141,8 @@ export class TokenManager {
         return inFlight;
     }
     async runMint(stale) {
+        const started = Date.now();
+        devActivity("token_mint_started");
         log("DEBUG", "Trying to mint an access token from the session cookie");
         let result;
         try {
@@ -150,8 +153,13 @@ export class TokenManager {
             });
         }
         catch (error) {
+            devActivity("token_mint_finished", { outcome: "transport", elapsedMs: Date.now() - started });
             throw new TokenRefreshError("token service request failed", error instanceof Error ? error : undefined);
         }
+        devActivity("token_mint_finished", {
+            outcome: result.ok ? "success" : result.reason === "sessionExpired" ? "sessionExpired" : "error",
+            elapsedMs: Date.now() - started,
+        });
         // The auth CLI or another MCP process can finish a login while HTTP minting
         // is in flight. Its newer session wins over either result of this request.
         const current = await this.sessionStore.load();

package/build/index.js

@@ -9,10 +9,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { enableStdoutGuard, log } from "./utils/logger.js";
+import { guardServerProcess } from "./utils/process-guard.js";
 import { loadConfig } from "./utils/config.js";
 import { TokenManager, AuthRunner } from "./auth/index.js";
 import { D2LApiClient } from "./api/index.js";
 import { startUpdateChecks } from "./utils/update-checker.js";
+import { configureDevActivity, trackToolActivity } from "./utils/dev-activity.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
@@ -44,14 +46,14 @@ else {
     // ── MCP Server (default) ────────────────────────────────────────────
     // CRITICAL: Enable stdout guard IMMEDIATELY to prevent corruption of stdio transport
     enableStdoutGuard();
-    // Unhandled rejection handler
-    process.on('unhandledRejection', (reason) => {
-        log('ERROR', 'Unhandled promise rejection', reason);
-    });
+    // A stray exception or a closed pipe must not silently drop the client's
+    // transport; see guardServerProcess.
+    guardServerProcess();
     async function main() {
         try {
             // Load configuration
             const config = await loadConfig();
+            configureDevActivity(config.sessionDir);
             log("DEBUG", "Configuration loaded", { sessionDir: config.sessionDir });
             // Create MCP server instance
             const server = new McpServer({
@@ -122,6 +124,7 @@ else {
             // shows an MFA challenge mid-call and waits for the approval instead of
             // asking to be called again (see relayMfaChallenges).
             relayMfaChallenges(server);
+            trackToolActivity(server);
             registerGetMyCourses(server, apiClient, config);
             registerGetUpcomingDueDates(server, apiClient, config);
             registerGetCalendarEvents(server, apiClient, config);

package/build/utils/dev-activity.js

@@ -0,0 +1,88 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+const calls = new AsyncLocalStorage();
+const runId = randomUUID();
+const MAX_BYTES = 5 * 1024 * 1024;
+let directory;
+let warned = false;
+let lastStart;
+let lastSuccess;
+/** Explicit opt-in; separate from ordinary stderr debugging. */
+export function configureDevActivity(sessionDir) {
+    directory = process.env.D2L_DEV_MODE === "true" ? join(sessionDir, "dev-activity") : undefined;
+    lastStart = lastSuccess = undefined;
+    warned = false;
+}
+/** 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) {
+    if (!directory)
+        return;
+    if (!["tool_started", "tool_finished", "http_response", "auth_required", "token_mint_started",
+        "token_mint_finished", "recovery_started", "mfa_observed", "recovery_finished"].includes(event))
+        return;
+    const at = new Date().toISOString();
+    const record = { at, runId, pid: process.pid, event };
+    if (context)
+        Object.assign(record, context);
+    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;
+    }
+    if (["success", "error", "sessionExpired", "transport"].includes(fields.outcome ?? ""))
+        record.outcome = fields.outcome;
+    if (["busy", "cooldown", "unsupported", "secureStorage", "transport", "timeout", "failed", "mfaPending"].includes(fields.reason ?? ""))
+        record.reason = fields.reason;
+    try {
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const file = join(directory, `activity-${at.slice(0, 10)}-${process.pid}-${runId}.jsonl`);
+        let size = 0;
+        try {
+            size = statSync(file).size;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        const line = JSON.stringify(record) + "\n";
+        if (size + Buffer.byteLength(line) <= MAX_BYTES)
+            appendFileSync(file, line, { mode: 0o600 });
+    }
+    catch {
+        if (!warned) {
+            warned = true;
+            console.error("[WARN] Dev activity could not be saved; tool execution continues.");
+        }
+    }
+}
+/** Wraps registered handlers, composing with the MFA progress relay. */
+export function trackToolActivity(server) {
+    if (!directory)
+        return;
+    const register = server.registerTool.bind(server);
+    server.registerTool = ((name, config, callback) => register(name, config, (async (...args) => {
+        // Tool names come from registration, never the client's arguments.
+        const context = { callId: randomUUID(), tool: /^[a-zA-Z0-9_-]{1,100}$/.test(name) ? name : "other" };
+        const started = Date.now();
+        write("tool_started", {}, context, lastStart === undefined ? undefined : started - lastStart, lastSuccess === undefined ? undefined : started - lastSuccess);
+        lastStart = started;
+        return calls.run(context, async () => {
+            let outcome = "error";
+            try {
+                const result = await callback(...args);
+                if (!result?.isError) {
+                    outcome = "success";
+                    lastSuccess = Date.now();
+                }
+                return result;
+            }
+            finally {
+                write("tool_finished", { outcome, elapsedMs: Date.now() - started });
+            }
+        });
+    })));
+}

package/build/utils/process-guard.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.
+ */
+import { log } from "./logger.js";
+const RECONNECT_HINT = "Restart or reconnect the Brightspace MCP server in your MCP client to continue " +
+    "(for example, toggle it off and on in the client's MCP settings, or restart the client).";
+/**
+ * Keep one bad moment from silently killing a stdio MCP server.
+ *
+ * Each MCP client launches its own server process. When that process dies,
+ * the client only ever reports "Transport closed" for every later call, even
+ * calls that never touch the network, while another client's process carries
+ * on fine. Node's defaults are what kill it: an exception thrown from any
+ * event listener, or an EPIPE on stdout with no 'error' listener, ends the
+ * process with nothing useful in the client's log.
+ *
+ * So: a stray exception is logged and the server keeps serving; a stdout pipe
+ * the client has already closed ends the process cleanly, since there is no
+ * one left to answer; and every other way the process stops says why on
+ * stderr, which MCP clients keep as the server's log.
+ */
+export function guardServerProcess(proc = process) {
+    proc.on("uncaughtException", (error) => {
+        log("ERROR", "Uncaught exception; the server is still running", error);
+    });
+    proc.on("unhandledRejection", (reason) => {
+        log("ERROR", "Unhandled promise rejection", reason);
+    });
+    proc.stdout.on("error", (error) => {
+        if (error.code === "EPIPE") {
+            log("INFO", "The MCP client closed the connection (stdout pipe closed); shutting down");
+            proc.exit(0);
+            return;
+        }
+        log("ERROR", "Writing to the MCP client failed", error);
+    });
+    proc.stdin.on("end", () => {
+        log("INFO", "The MCP client closed stdin; the server will stop");
+    });
+    proc.on("exit", (code) => {
+        if (code === 0)
+            return;
+        log("ERROR", `Brightspace MCP server exited with code ${code}. ${RECONNECT_HINT}`);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "3.10.6",
+  "version": "3.10.9",
   "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",
@@ -40,7 +40,6 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "@types/sanitize-filename": "^1.1.28",
     "@types/turndown": "^5.0.6",
     "typescript": "^5.9.0",
     "vitest": "^4.0.0"