brightspace-mcp-server 3.8.13 → 3.9.0

package/README.md

@@ -143,7 +143,7 @@ Run it from your home folder — macOS blocks `npx` from Documents, Desktop, or
 | Roster | "Who are the TAs for ECE 264?" · "Get me my instructor's email" |
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |
 | Video transcripts | "What did the professor say about pinch-off in Tuesday's lecture recording?" · "Summarize last week's BoilerCast video" — works for Kaltura and YouTube embeds; other platforms report that they aren't supported yet |
-| Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, whether a credential is stored, and what Microsoft remembered (`microsoftSession`: stay-signed-in and its expiry, plus whether "Don't ask again" was ticked, already on, not offered, or left off because `D2L_REMEMBER_MFA` isn't set), without contacting Brightspace or revealing secrets |
+| Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, whether a credential is stored, what Microsoft remembered (`microsoftSession`: stay-signed-in and its expiry, plus whether "Don't ask again" was ticked, already on, not offered, or left off because `D2L_REMEMBER_MFA` isn't set), and `requests` (lightweight counters: responses by status class, network errors, cache hits/misses, coalesced in-flight joins, and token refreshes), without contacting Brightspace or revealing secrets |
 | Calendar | "When is my midterm?" · "What's on my calendar this week?" · "Is lab cancelled on Thursday?" — reads exams, labs, review sessions, and deadlines instructors put only on the course calendar |
 | Planning | "Build me a study schedule based on my upcoming due dates" · "Which class needs the most attention right now?" — pulls from assignments, quizzes, graded discussion topics (any topic with a due date), and course calendar events such as exams and labs |
 
@@ -151,5 +151,6 @@ Run it from your home folder — macOS blocks `npx` from Documents, Desktop, or
 
 When a content-file download returns 403 or 404, `download_file` checks topic metadata and the course table of contents. Confirmed restrictions return `{ success: false, available: false, reason, message, startDate, endDate }` so the assistant can explain when content opens or why it has closed. Unexplained 404s and server/network failures retain their original errors.
 
+When course content or announcements are converted to markdown, `javascript:`/`data:` links are rendered as plain text (the link itself is dropped, not followed) and D2L's per-session query parameters (`d2lSessionVal`, `d2lSecureSessionVal`, and the cache-busting `_`) are stripped from any remaining links and images before they reach the assistant.
 
 Licensed under the MIT License.

package/build/api/client.js

@@ -80,6 +80,27 @@ export class D2LApiClient {
     versions = null;
     /** Single in-flight discovery, so concurrent first requests share one fetch. */
     versionsInFlight = null;
+    /**
+     * GETs keyed by the unresolved template path + query (the same string
+     * get() caches under), so a second caller asking for the same resource
+     * while the first is still in flight joins that promise instead of
+     * issuing its own request. Claude Desktop fans out tool calls in
+     * parallel and our tools fan out per course, so identical paths are
+     * often requested within milliseconds of each other. One client, one
+     * token manager, so every GET it issues already shares one auth
+     * identity — nothing further to key on.
+     *
+     * Adapted from JhostinAleck/brightspace-mcp (MIT) — RequestCoalescer.ts.
+     */
+    pendingGets = new Map();
+    statsData = {
+        statusClasses: { "2xx": 0, "401": 0, "403": 0, "404": 0, "429": 0, "5xx": 0, other: 0 },
+        networkErrors: 0,
+        cacheHits: 0,
+        cacheMisses: 0,
+        coalescedJoins: 0,
+        tokenRefreshes: 0,
+    };
     constructor(options) {
         // HTTPS-only enforcement, on a parsed URL rather than a string prefix so
         // a malformed base cannot slip through as "not http".
@@ -196,16 +217,34 @@ export class D2LApiClient {
             const age = this.cache.ageOf(path);
             if (age !== undefined && age <= options.ttl) {
                 log("DEBUG", `Cache hit: ${path}`);
+                this.statsData.cacheHits++;
                 return this.cache.get(path);
             }
+            this.statsData.cacheMisses++;
         }
-        const resolved = await this.resolvePath(path);
-        const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token));
-        if (options?.ttl) {
-            this.cache.set(path, data, options.ttl);
-            log("DEBUG", `Cached response for ${path} (TTL: ${options.ttl}ms)`);
+        // Join an identical GET already in flight rather than issuing a second
+        // one. Keyed on the same unresolved path the cache above uses, so the
+        // join happens before version discovery or a token is even touched.
+        const pending = this.pendingGets.get(path);
+        if (pending) {
+            this.statsData.coalescedJoins++;
+            log("DEBUG", `Coalescing GET onto an in-flight request: ${path}`);
+            return pending;
         }
-        return data;
+        const inFlight = (async () => {
+            const resolved = await this.resolvePath(path);
+            const data = await this.withAuthentication(resolved, token => this.makeRequest(resolved, token));
+            if (options?.ttl) {
+                this.cache.set(path, data, options.ttl);
+                log("DEBUG", `Cached response for ${path} (TTL: ${options.ttl}ms)`);
+            }
+            return data;
+        })().finally(() => {
+            if (this.pendingGets.get(path) === inFlight)
+                this.pendingGets.delete(path);
+        });
+        this.pendingGets.set(path, inFlight);
+        return inFlight;
     }
     /**
      * Make a GET request to the D2L API and return raw Response object.
@@ -242,8 +281,15 @@ export class D2LApiClient {
         // A rejected JWT does not prove its underlying cookie is expired. Read a
         // token written by another process or mint over HTTP before opening login.
         // TokenRefreshError propagates here, so a temporary outage never starts MFA.
+        // One 401-recovery cascade counts as one refresh even when it takes both a
+        // mint attempt and a browser login to land a token the server accepts --
+        // `refreshed` tracks whether this cascade has already been counted so the
+        // fallback to tryAutoReauth below doesn't count it a second time.
         const fresh = await this.tokenManager.getToken(token.accessToken);
+        let refreshed = false;
         if (fresh && fresh.accessToken !== token.accessToken) {
+            this.statsData.tokenRefreshes++;
+            refreshed = true;
             try {
                 return await send(fresh);
             }
@@ -253,8 +299,28 @@ export class D2LApiClient {
             }
         }
         const loggedIn = await this.tryAutoReauth(path, fresh?.accessToken ?? token.accessToken);
+        if (!refreshed)
+            this.statsData.tokenRefreshes++;
         return send(loggedIn);
     }
+    /** Buckets one observed HTTP status into statsData.statusClasses. */
+    recordStatus(status) {
+        const classes = this.statsData.statusClasses;
+        if (status >= 200 && status < 300)
+            classes["2xx"]++;
+        else if (status === 401)
+            classes["401"]++;
+        else if (status === 403)
+            classes["403"]++;
+        else if (status === 404)
+            classes["404"]++;
+        else if (status === 429)
+            classes["429"]++;
+        else if (status >= 500)
+            classes["5xx"]++;
+        else
+            classes.other++;
+    }
     /** One rate limiter token per attempt. */
     async throttled(fn) {
         await this.rateLimiter.consume();
@@ -300,6 +366,7 @@ export class D2LApiClient {
                 headers,
                 signal: AbortSignal.timeout(this.timeoutMs),
             });
+            this.recordStatus(response.status);
             // Preserve cookie material: a 401 only rejects this access token.
             if (response.status === 401) {
                 throw new ApiError(401, path, "Brightspace rejected the access token.");
@@ -346,6 +413,7 @@ export class D2LApiClient {
                 throw error;
             }
             // Wrap network/fetch errors
+            this.statsData.networkErrors++;
             const message = error instanceof Error ? error.message : String(error);
             throw new NetworkError(`Request to ${path} failed: ${message}`, error instanceof Error ? error : undefined);
         }
@@ -363,6 +431,7 @@ export class D2LApiClient {
                 headers,
                 signal: AbortSignal.timeout(this.timeoutMs),
             });
+            this.recordStatus(response.status);
             // Preserve cookie material for the shared HTTP refresh path.
             if (response.status === 401) {
                 throw new ApiError(401, path, "Brightspace rejected the access token.");
@@ -416,6 +485,7 @@ export class D2LApiClient {
                 throw error;
             }
             // Wrap network/fetch errors
+            this.statsData.networkErrors++;
             const message = error instanceof Error ? error.message : String(error);
             throw new NetworkError(`Request to ${path} failed: ${message}`, error instanceof Error ? error : undefined);
         }
@@ -483,4 +553,20 @@ export class D2LApiClient {
     get cacheSize() {
         return this.cache.size;
     }
+    /**
+     * Read-only snapshot of this client's lightweight request counters. A
+     * fresh object every call, so a caller holding onto it never sees later
+     * updates and can't mutate the client's own counts. Never carries a URL,
+     * username, or token.
+     */
+    stats() {
+        return {
+            statusClasses: { ...this.statsData.statusClasses },
+            networkErrors: this.statsData.networkErrors,
+            cacheHits: this.statsData.cacheHits,
+            cacheMisses: this.statsData.cacheMisses,
+            coalescedJoins: this.statsData.coalescedJoins,
+            tokenRefreshes: this.statsData.tokenRefreshes,
+        };
+    }
 }

package/build/api/paginate.js

@@ -78,16 +78,47 @@ export async function fetchAllObjects(apiClient, firstPath, options) {
     }
     return objects;
 }
-/** A Next value resolved to a request path. */
+/**
+ * A Next value resolved to a request path, or null when it should not be
+ * followed.
+ *
+ * Adapted from JhostinAleck/brightspace-mcp (MIT): beyond dropping an
+ * absolute Next's host (the client always prefixes its own configured base
+ * URL, so a hostile/garbled Next cannot redirect requests elsewhere), anything
+ * -- absolute or server-relative -- whose path falls outside `/d2l/api/` is
+ * rejected rather than followed, since that is the only space these paginated
+ * endpoints legitimately point back into.
+ */
 function nextPath(firstPath, next) {
     if (/^https?:\/\//i.test(next)) {
         const url = new URL(next);
+        if (!isApiPath(url.pathname)) {
+            log("INFO", "Pagination stopped: Next link left the D2L API", {
+                firstPath,
+                nextPath: url.pathname,
+            });
+            return null;
+        }
         return `${url.pathname}${url.search}`;
     }
     // A Next that begins with a slash is already a path, not a bookmark.
     // Appending it as one would ask for a page that does not exist.
     if (next.startsWith("/")) {
+        const nextPathOnly = next.split("?")[0] ?? next;
+        if (!isApiPath(nextPathOnly)) {
+            log("INFO", "Pagination stopped: Next link left the D2L API", {
+                firstPath,
+                // Log only the path, not the query string: a rejected server-relative
+                // Next can carry a `d2lSessionVal=` token in its query.
+                nextPath: nextPathOnly,
+            });
+            return null;
+        }
         return next;
     }
     return withBookmark(firstPath, next);
 }
+/** Whether a Next path stays inside the D2L API namespace these endpoints page through. */
+function isApiPath(pathname) {
+    return pathname.startsWith("/d2l/api/");
+}

package/build/index.js

@@ -115,7 +115,7 @@ else {
             registerGetSyllabus(server, apiClient);
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
-            registerGetServerInfo(server, config, PKG_VERSION);
+            registerGetServerInfo(server, config, PKG_VERSION, apiClient);
             log("DEBUG", "MCP tools registered (16 tools)");
             // Connect stdio transport
             const transport = new StdioServerTransport();

package/build/tools/get-server-info.js

@@ -14,13 +14,15 @@ import { toolResponse } from "./tool-helpers.js";
  * trigger a sign-in. hasStoredCredential reflects the keychain lookup made at
  * startup, which is the credential this process actually holds.
  * microsoftSession comes from the plain summary saved beside the browser
- * state and is omitted when there is no saved state. Nothing secret —
- * password, username, token, cookie — is ever included.
+ * state and is omitted when there is no saved state. requests is the
+ * client's own lightweight counters (apiClient.stats()) — a snapshot of
+ * what has happened so far this process, not a network call of its own.
+ * Nothing secret — password, username, token, cookie — is ever included.
  */
-export function registerGetServerInfo(server, config, version) {
+export function registerGetServerInfo(server, config, version, apiClient) {
     server.registerTool("get_server_info", {
         title: "Get Server Info",
-        description: "Report which version of the Brightspace MCP server is running, the Node.js runtime, platform, config file path, session state directory, configured school URL, whether a credential is stored, and (once a browser sign-in has been saved) what Microsoft remembered: stay-signed-in and the Don't ask again MFA checkbox. Use this for troubleshooting or when the user asks which version they have. Never contacts Brightspace and never returns secrets.",
+        description: "Report which version of the Brightspace MCP server is running, the Node.js runtime, platform, config file path, session state directory, configured school URL, whether a credential is stored, (once a browser sign-in has been saved) what Microsoft remembered: stay-signed-in and the Don't ask again MFA checkbox, and this process's request counters (requests: responses by status class, network errors, cache hits/misses, coalesced joins, and token refreshes). Use this for troubleshooting or when the user asks which version they have. Never contacts Brightspace and never returns secrets.",
         inputSchema: GetServerInfoSchema,
     }, async () => {
         const microsoftSession = await readMicrosoftSession(config.sessionDir);
@@ -34,6 +36,7 @@ export function registerGetServerInfo(server, config, version) {
             schoolUrl: config.baseUrl,
             hasStoredCredential: config.password !== undefined,
             ...(microsoftSession && { microsoftSession }),
+            requests: apiClient.stats(),
         });
     });
 }

package/build/utils/html-converter.js

@@ -60,9 +60,70 @@ function getTurndownService() {
                 return body ? `\n\n${body}\n\n` : "";
             },
         });
+        // D2L appends per-session query params (d2lSessionVal, d2lSecureSessionVal,
+        // a `_` cache-buster) to in-content hrefs. Left alone, the markdown we hand
+        // the model echoes a live session token into the chat transcript. These
+        // two rules are unshifted ahead of Turndown's built-in link/image rules
+        // (addRule always inserts at the front of the rule list), so they run
+        // first and the defaults never see the raw attribute.
+        turndownService.addRule("linkSessionTokens", {
+            filter: (node) => node.nodeName === "A" && !!node.getAttribute("href"),
+            replacement: (content, node) => {
+                const href = node.getAttribute("href") ?? "";
+                // javascript:/data: hrefs aren't content links; drop the link but
+                // keep whatever text was inside it.
+                if (isUnsafeHref(href))
+                    return content;
+                const cleaned = stripSessionParams(href).replace(/([()])/g, "\\$1");
+                const title = node.getAttribute("title");
+                const titlePart = title ? ` "${title.replace(/"/g, '\\"')}"` : "";
+                return `[${content}](${cleaned}${titlePart})`;
+            },
+        });
+        turndownService.addRule("imageSessionTokens", {
+            filter: "img",
+            replacement: (_content, node) => {
+                const el = node;
+                const alt = el.getAttribute("alt") ?? "";
+                const src = stripSessionParams(el.getAttribute("src") ?? "");
+                const title = el.getAttribute("title");
+                const titlePart = title ? ` "${title}"` : "";
+                return src ? `![${alt}](${src}${titlePart})` : "";
+            },
+        });
     }
     return turndownService;
 }
+const SESSION_QUERY_PARAMS = new Set(["d2lsessionval", "d2lsecuresessionval", "_"]);
+/**
+ * Strip D2L's per-session query params (`d2lSessionVal`, `d2lSecureSessionVal`,
+ * and the `_` cache-buster) from a URL. Everything else about the URL --
+ * scheme, path, other params -- is left untouched, including a relative href,
+ * which is returned as-is apart from this filtering.
+ */
+function stripSessionParams(url) {
+    const queryStart = url.indexOf("?");
+    if (queryStart < 0)
+        return url;
+    const earlyHash = url.indexOf("#");
+    if (earlyHash >= 0 && earlyHash < queryStart) {
+        // The "?" falls inside the fragment (e.g. "#frag?x=1"), not a real query
+        // string -- nothing to strip, and treating it as one would mangle the
+        // fragment.
+        return url;
+    }
+    const hashStart = url.indexOf("#", queryStart);
+    const query = url.slice(queryStart + 1, hashStart < 0 ? undefined : hashStart);
+    const hash = hashStart < 0 ? "" : url.slice(hashStart);
+    const kept = query
+        .split("&")
+        .filter((param) => param !== "" && !SESSION_QUERY_PARAMS.has(param.split("=")[0].toLowerCase()));
+    return url.slice(0, queryStart) + (kept.length > 0 ? `?${kept.join("&")}` : "") + hash;
+}
+/** True for `javascript:`/`data:` hrefs -- never a legitimate content link. */
+function isUnsafeHref(href) {
+    return /^\s*(javascript|data):/i.test(href);
+}
 /** A cell's text, flattened so one table cell stays one table cell. */
 function cellText(content) {
     return content

package/package.json

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