brightspace-mcp-server 3.8.14 → 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 |
 

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/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/package.json

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