brightspace-mcp-server 5.1.17 → 5.1.19

package/build/auth/token-manager.js

@@ -5,6 +5,7 @@
  */
 import { SessionStore } from "./session-store.js";
 import { mintAccessToken } from "./token-mint.js";
+import { fetchXsrfToken } from "./xsrf-fetch.js";
 import { log } from "../utils/logger.js";
 import { TokenRefreshError } from "../api/errors.js";
 import { devActivity } from "../utils/dev-activity.js";
@@ -15,6 +16,8 @@ import { devActivity } from "../utils/dev-activity.js";
 const REFRESH_BUFFER_MS = 5 * 60 * 1000; // 5 minutes
 /** Matches the tokenTtl default in the app config. */
 const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+/** How long a D2L_SESSION_COOKIE mint that failed in transit waits before trying again. */
+const ENV_MINT_RETRY_MS = 60 * 1000;
 /**
  * TokenManager manages token lifecycle with in-memory caching and disk persistence.
  * Handles expiry detection with a configurable refresh buffer.
@@ -25,8 +28,18 @@ export class TokenManager {
     baseUrl;
     tokenTtl;
     mint;
+    fetchXsrf;
     envAccessToken;
     envSessionCookie;
+    mintEnvCookie;
+    /** The Bearer JWT minted from envSessionCookie, memory only. */
+    envMinted = null;
+    /** The XSRF token that last minted successfully, reused for the hourly re-mint. */
+    envCsrfToken;
+    /** Set once the env cookie is known not to mint, so later calls skip straight to the passthrough. */
+    envMintDisabled = false;
+    envMintRetryAt = 0;
+    envMintInFlight = null;
     /** Single in-flight mint, so concurrent callers share one request. */
     mintInFlight = null;
     rejectedAccessToken = null;
@@ -53,8 +66,10 @@ export class TokenManager {
         this.baseUrl = options.baseUrl ? new URL(options.baseUrl).origin : undefined;
         this.tokenTtl = options.tokenTtl ?? DEFAULT_TOKEN_TTL_SECONDS;
         this.mint = options.mint ?? mintAccessToken;
+        this.fetchXsrf = options.fetchXsrf ?? fetchXsrfToken;
         this.envAccessToken = options.envAccessToken;
         this.envSessionCookie = options.envSessionCookie;
+        this.mintEnvCookie = options.mintEnvCookie ?? false;
     }
     /**
      * Get the current token if valid, otherwise null.
@@ -72,6 +87,11 @@ export class TokenManager {
         // value again. (See D2LApiClient.tryAutoReauth / authExpiredMessage for
         // the user-facing "paste a fresh one" error this produces.)
         if (this.envAccessToken || this.envSessionCookie) {
+            if (!this.envAccessToken && this.mintEnvCookie && this.baseUrl) {
+                const minted = await this.envCookieBearer(rejectedAccessToken);
+                if (minted)
+                    return minted;
+            }
             const token = this.buildEnvToken();
             if (rejectedAccessToken && token.accessToken === rejectedAccessToken) {
                 log("DEBUG", "The env-provided credential was rejected; no replacement is available");
@@ -255,6 +275,75 @@ export class TokenManager {
             cookieHeader: this.envSessionCookie,
         };
     }
+    /**
+     * The Bearer JWT minted from envSessionCookie, minting one when there is
+     * none or it expired or was just rejected. Null means use the cookie
+     * passthrough instead, which also keeps the existing "paste a fresh one"
+     * error for a dead cookie.
+     */
+    async envCookieBearer(rejectedAccessToken) {
+        if (this.envMinted && rejectedAccessToken === this.envMinted.accessToken) {
+            log("DEBUG", "The JWT minted from D2L_SESSION_COOKIE was rejected; minting again");
+            this.envMinted = null;
+        }
+        if (this.envMinted && this.isValid(this.envMinted))
+            return this.envMinted;
+        if (this.envMintDisabled || Date.now() < this.envMintRetryAt)
+            return null;
+        this.envMintInFlight ??= this.runEnvMint().finally(() => {
+            this.envMintInFlight = null;
+        });
+        return this.envMintInFlight;
+    }
+    async runEnvMint() {
+        const baseUrl = this.baseUrl;
+        const cookieHeader = this.envSessionCookie;
+        let csrfToken = this.envCsrfToken;
+        if (!csrfToken) {
+            const xsrf = await this.fetchXsrf({ baseUrl, cookieHeader });
+            if (!xsrf.ok)
+                return this.envMintFailed(xsrf.reason, xsrf.detail);
+            csrfToken = xsrf.csrfToken;
+        }
+        let result;
+        try {
+            result = await this.mint({ baseUrl, cookieHeader, csrfToken });
+        }
+        catch (error) {
+            return this.envMintFailed("transport", error instanceof Error ? error.message : String(error));
+        }
+        if (!result.ok) {
+            // A stale XSRF token is one cause of a refused mint; read a fresh one next time.
+            this.envCsrfToken = undefined;
+            return this.envMintFailed(result.reason, result.detail);
+        }
+        const now = Date.now();
+        this.envCsrfToken = csrfToken;
+        this.envMinted = {
+            accessToken: result.accessToken,
+            tenantOrigin: this.baseUrl,
+            capturedAt: now,
+            expiresAt: now + this.tokenTtl * 1000,
+            source: "env",
+            cookieHeader,
+        };
+        log("INFO", "Minted a Bearer token from D2L_SESSION_COOKIE without a browser");
+        return this.envMinted;
+    }
+    /**
+     * A dead cookie or a page with no XSRF token will not mint later either, so
+     * stop trying; a transport failure is retried after ENV_MINT_RETRY_MS.
+     */
+    envMintFailed(reason, detail) {
+        if (reason === "transport") {
+            this.envMintRetryAt = Date.now() + ENV_MINT_RETRY_MS;
+        }
+        else {
+            this.envMintDisabled = true;
+        }
+        log("DEBUG", `Could not mint from D2L_SESSION_COOKIE (${reason}${detail ? `: ${detail}` : ""}); using the cookie as-is`);
+        return null;
+    }
     /**
      * Only use persisted session material, including updates from other processes.
      */

package/build/auth/xsrf-fetch.js

@@ -0,0 +1,76 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT: see LICENSE file for details.
+ */
+import { log } from "../utils/logger.js";
+/** Same marker token-mint.ts keys on: a dead session gets a 200 redirect stub. */
+const EXPIRED_MARKER = "/d2l/login?sessionExpired=1";
+/** Same identity the API client sends, see buildAuthHeaders in api/client.ts. */
+const USER_AGENT = "BrightspaceMCP/1.0 (Rohan Muppa; github.com/rohanmuppa/brightspace-mcp-server)";
+const DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * Where a Brightspace page carries its XSRF token, most specific first.
+ *
+ * The browser path reads D2L.LP.Web.Authentication.Xsrf.GetXsrfToken(), whose
+ * value is the one the page also writes to localStorage as "XSRF.Token"
+ * (the same 32 characters). Measured against purdue.brightspace.com: the
+ * cookie-only HTML carries it in an inline
+ * `localStorage.setItem('XSRF.Token','...')`, so that is the first place to
+ * look; the meta tag is the browser path's own fallback.
+ */
+const XSRF_PATTERNS = [
+    /XSRF\.Token\\?["']\s*,\s*\\?["']([A-Za-z0-9_-]{16,})\\?["']/,
+    /<meta[^>]*name=["']d2l-xsrf-token["'][^>]*content=["']([A-Za-z0-9_-]{16,})["']/i,
+    /<meta[^>]*content=["']([A-Za-z0-9_-]{16,})["'][^>]*name=["']d2l-xsrf-token["']/i,
+];
+/** Pull the XSRF token out of a Brightspace page's HTML, or null when absent. */
+export function parseXsrfToken(html) {
+    for (const pattern of XSRF_PATTERNS) {
+        const match = pattern.exec(html);
+        if (match)
+            return match[1];
+    }
+    return null;
+}
+/**
+ * Read the XSRF token the token mint needs from /d2l/home over plain HTTP,
+ * using only the session cookies. This is what lets a pasted
+ * D2L_SESSION_COOKIE be traded for a Bearer JWT without a browser.
+ */
+export async function fetchXsrfToken({ baseUrl, cookieHeader, fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS, }) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/d2l/home`;
+    let status;
+    let body;
+    let location;
+    try {
+        const response = await fetchImpl(url, {
+            method: "GET",
+            headers: { cookie: cookieHeader, "User-Agent": USER_AGENT, accept: "text/html" },
+            signal: AbortSignal.timeout(timeoutMs),
+            redirect: "manual",
+        });
+        status = response.status;
+        body = await response.text();
+        location = response.headers?.get("location") ?? null;
+    }
+    catch (error) {
+        return { ok: false, reason: "transport", detail: error instanceof Error ? error.message : String(error) };
+    }
+    if (status >= 500 || status === 429)
+        return { ok: false, reason: "transport", detail: `HTTP ${status}` };
+    // A dead session either redirects to the login page or answers 200 with the
+    // redirect stub. Either way the cookie is no good for minting.
+    if (status === 401 || body.includes(EXPIRED_MARKER) || (status >= 300 && status < 400 && location?.includes("/d2l/login"))) {
+        log("DEBUG", "The home page answered as a signed-out session");
+        return { ok: false, reason: "sessionExpired" };
+    }
+    if (status < 200 || status >= 300)
+        return { ok: false, reason: "transport", detail: `HTTP ${status}` };
+    const csrfToken = parseXsrfToken(body);
+    if (!csrfToken) {
+        log("DEBUG", "No XSRF token found in the home page HTML");
+        return { ok: false, reason: "notFound" };
+    }
+    return { ok: true, csrfToken };
+}

package/build/server.js

@@ -30,6 +30,7 @@ export function createRuntime(config, version) {
         tokenTtl: config.tokenTtl,
         envAccessToken: config.envAccessToken,
         envSessionCookie: config.envSessionCookie,
+        mintEnvCookie: true,
     });
     // D2L_ACCESS_TOKEN / D2L_SESSION_COOKIE are opt-in browser-free sign-in
     // escape hatches (Docker, headless Linux, WSL, hardware-key MFA
@@ -91,7 +92,7 @@ export function createMcpServer(runtime) {
     registerGetRoster(server, apiClient);
     registerGetMyGroups(server, apiClient);
     registerGetSyllabus(server, apiClient);
-    registerGetDiscussions(server, apiClient);
+    registerGetDiscussions(server, apiClient, config.baseUrl);
     registerGetVideoTranscript(server, apiClient);
     registerGetServerInfo(server, config, version, apiClient);
     registerSearchCourse(server, apiClient);

package/build/tools/get-discussions.js

@@ -8,6 +8,7 @@ import { GetDiscussionsSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { log } from "../utils/logger.js";
+import { discussionUrl } from "../utils/deep-links.js";
 /**
  * Fetch a course's discussion forums. Shared with search_course so both
  * tools hit the same endpoint (and cache entry) instead of duplicating it.
@@ -31,7 +32,7 @@ export async function fetchForumTopics(apiClient, courseId, forumId) {
 /**
  * Register get_discussions tool
  */
-export function registerGetDiscussions(server, apiClient) {
+export function registerGetDiscussions(server, apiClient, baseUrl) {
     server.registerTool("get_discussions", {
         title: "Get Discussions",
         annotations: { readOnlyHint: true },
@@ -47,7 +48,7 @@ export function registerGetDiscussions(server, apiClient) {
             }
             // Specific topic — get posts
             if (forumId !== undefined && topicId !== undefined) {
-                return await getTopicPosts(apiClient, courseId, forumId, topicId);
+                return await getTopicPosts(apiClient, courseId, forumId, topicId, baseUrl);
             }
             // Specific forum — get its topics + posts
             if (forumId !== undefined) {
@@ -169,40 +170,82 @@ async function getForumDetail(apiClient, courseId, forumId) {
     });
 }
 /**
- * Get all posts for a specific topic.
+ * Fetch one topic's metadata. The forum's topic list comes first: it is the
+ * route get_discussions already lists topics from (and caches), and some
+ * tenants refuse a student the per-topic route for a topic that list shows
+ * (#364). The per-topic route is the fallback for a topic the list omits or
+ * a list the tenant refuses.
  */
-async function getTopicPosts(apiClient, courseId, forumId, topicId) {
-    // Fetch topic info
+async function fetchTopic(apiClient, courseId, forumId, topicId) {
+    try {
+        const listed = (await fetchForumTopics(apiClient, courseId, forumId)).find((t) => t.TopicId === topicId);
+        if (listed)
+            return listed;
+    }
+    catch (error) {
+        log("DEBUG", `Topic list for forum ${forumId} unavailable, trying topic ${topicId} directly`, error);
+    }
     const topicPath = apiClient.le(courseId, `/discussions/forums/${forumId}/topics/${topicId}`);
-    const topic = await apiClient.get(topicPath, {
+    return apiClient.get(topicPath, {
         ttl: DEFAULT_CACHE_TTLS.courseContent,
     });
-    // Fetch posts
+}
+/**
+ * Get all posts for a specific topic. A posts read the tenant refuses (403)
+ * still returns the topic, with posts null and postsUnavailable naming the
+ * failed step, so a permission restriction never reads as "no posts".
+ */
+async function getTopicPosts(apiClient, courseId, forumId, topicId, baseUrl) {
+    const topic = await fetchTopic(apiClient, courseId, forumId, topicId);
     const postsPath = apiClient.le(courseId, `/discussions/forums/${forumId}/topics/${topicId}/posts/`);
-    const posts = await apiClient.get(postsPath, {
-        ttl: DEFAULT_CACHE_TTLS.announcements,
-    });
+    let posts;
+    try {
+        posts = await apiClient.get(postsPath, {
+            ttl: DEFAULT_CACHE_TTLS.announcements,
+        });
+    }
+    catch (error) {
+        if (error?.status !== 403)
+            throw error;
+        log("INFO", `get_discussions: Posts for topic ${topicId} in forum ${forumId} refused (403)`);
+        return toolResponse({
+            courseId,
+            forumId,
+            topic: formatTopic(topic),
+            postCount: null,
+            posts: null,
+            postsUnavailable: {
+                operation: "listPosts",
+                status: 403,
+                reason: "Brightspace refused this account's request for the topic's posts. The posts may exist; open the topic in a browser to see what this account can read.",
+                url: baseUrl ? discussionUrl(baseUrl, courseId, topicId) : null,
+            },
+        });
+    }
     // Count what is returned: formatPosts drops deleted posts.
     const formatted = formatPosts(posts);
     log("INFO", `get_discussions: Retrieved ${formatted.length} posts for topic ${topicId} in forum ${forumId}`);
     return toolResponse({
         courseId,
         forumId,
-        topic: {
-            topicId: topic.TopicId,
-            name: topic.Name,
-            description: topic.Description?.Html
-                ? convertHtmlToMarkdown(topic.Description.Html).markdown
-                : topic.Description?.Text ?? null,
-            dueDate: topic.DueDate,
-            isLocked: topic.IsLocked,
-            mustPostToParticipate: topic.MustPostToParticipate,
-            scoreOutOf: topic.ScoreOutOf,
-        },
+        topic: formatTopic(topic),
         postCount: formatted.length,
         posts: formatted,
     });
 }
+function formatTopic(topic) {
+    return {
+        topicId: topic.TopicId,
+        name: topic.Name,
+        description: topic.Description?.Html
+            ? convertHtmlToMarkdown(topic.Description.Html).markdown
+            : topic.Description?.Text ?? null,
+        dueDate: topic.DueDate,
+        isLocked: topic.IsLocked,
+        mustPostToParticipate: topic.MustPostToParticipate,
+        scoreOutOf: topic.ScoreOutOf,
+    };
+}
 /**
  * Format posts into a clean thread structure.
  */

package/build/utils/deep-links.js

@@ -6,16 +6,11 @@
 /**
  * Deep links into the Brightspace web UI.
  *
- * The dropbox, quiz and gradebook templates were harvested from live
- * Brightspace markup: they are the same URLs the course pages themselves link
- * to, so they open the item directly.
- *
- * `discussionUrl` was NOT -- it was written from the shape of the others
- * without live markup to check it against, and no one has confirmed it against
- * a real tenant since. Treat it as unverified: if a student reports that a
- * discussion link lands on the wrong page or a "not found", harvest the real
- * URL from a course's own discussion list and fix the template here rather
- * than assuming this one is right.
+ * Every template here was harvested from live Brightspace markup: they are
+ * the same URLs the course pages themselves link to, so they open the item
+ * directly. The discussion template was first written from the shape of the
+ * others and answered 404 on a real tenant; it now uses the link the course's
+ * own Discussions List page gives each topic.
  */
 /** Drop trailing slashes so the templates below join cleanly. */
 function trimBaseUrl(baseUrl) {
@@ -40,15 +35,9 @@ export function contentTopicUrl(baseUrl, courseId, topicId) {
 export function gradebookUrl(baseUrl, courseId) {
     return `${trimBaseUrl(baseUrl)}/d2l/lms/grades/my_grades/main.d2l?ou=${courseId}`;
 }
-/**
- * Link to the thread list of a discussion topic.
- *
- * Unverified against a live tenant -- see the note at the top of this file.
- * The topic's forum id is available at every call site, so if the real
- * template turns out to need one, it can be threaded through.
- */
+/** Link to a discussion topic's page, which lists its threads. */
 export function discussionUrl(baseUrl, courseId, topicId) {
-    return `${trimBaseUrl(baseUrl)}/d2l/lms/discussions/threadlist.d2l?ou=${courseId}&tId=${topicId}`;
+    return `${trimBaseUrl(baseUrl)}/d2l/le/${courseId}/discussions/topics/${topicId}/View`;
 }
 /**
  * Link to a course's calendar. Calendar events have no per-event student page

package/package.json

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