brightspace-mcp-server 3.15.4 → 4.0.1

package/build/tools/get-my-groups.js

@@ -27,7 +27,7 @@ export function registerGetMyGroups(server, apiClient) {
         try {
             log("DEBUG", "get_my_groups tool called", { args });
             const { courseId } = GetMyGroupsSchema.parse(args);
-            const { matches, categoriesUnavailable } = await fetchMyGroupMemberships(apiClient, courseId);
+            const { matches, categoriesUnavailable, unreadCategories } = await fetchMyGroupMemberships(apiClient, courseId);
             if (categoriesUnavailable) {
                 return toolResponse({
                     courseId,
@@ -35,6 +35,18 @@ export function registerGetMyGroups(server, apiClient) {
                     note: "No groups are visible for this course (it may not use groups, or group info isn't accessible).",
                 });
             }
+            const unreadNote = unreadCategories.length === 0 ? undefined
+                : `Couldn't read the groups in ${unreadCategories.map((c) => `"${c.Name || c.GroupCategoryId}"`).join(", ")}, ` +
+                    "so any group the current user has there is not listed.";
+            if (unreadNote) {
+                log("INFO", "get_my_groups: Some group categories could not be read", {
+                    courseId,
+                    categoryIds: unreadCategories.map((c) => c.GroupCategoryId),
+                });
+            }
+            if (matches.length === 0 && unreadNote) {
+                return toolResponse({ courseId, groups: [], note: unreadNote });
+            }
             if (matches.length === 0) {
                 log("INFO", `get_my_groups: User is not a member of any group in course ${courseId}`);
                 return toolResponse({
@@ -78,7 +90,7 @@ export function registerGetMyGroups(server, apiClient) {
                 };
             });
             log("INFO", `get_my_groups: Found ${groups.length} groups for course ${courseId}`);
-            return toolResponse({ courseId, groups });
+            return toolResponse({ courseId, groups, ...(unreadNote ? { note: unreadNote } : {}) });
         }
         catch (error) {
             return sanitizeError(error);

package/build/tools/group-membership.js

@@ -20,19 +20,24 @@ export async function fetchMyGroupMemberships(apiClient, courseId, categoryId) {
             : [{ GroupCategoryId: categoryId, Name: "" }];
     }
     catch (error) {
-        if (inaccessible(error))
-            return { matches: [], categoriesUnavailable: true };
+        if (inaccessible(error)) {
+            return { matches: [], categoriesUnavailable: true, unreadCategories: [] };
+        }
         throw error;
     }
     const matches = [];
+    // Categories whose groups answered 403/404: membership there is unknown, not "none".
+    const unreadCategories = [];
     for (const category of categories) {
         let groups;
         try {
             groups = await apiClient.get(apiClient.lp(`/${courseId}/groupcategories/${category.GroupCategoryId}/groups/`), { ttl: DEFAULT_CACHE_TTLS.roster });
         }
         catch (error) {
-            if (inaccessible(error))
+            if (inaccessible(error)) {
+                unreadCategories.push(category);
                 continue;
+            }
             throw error;
         }
         for (const group of groups) {
@@ -40,5 +45,5 @@ export async function fetchMyGroupMemberships(apiClient, courseId, categoryId) {
                 matches.push({ category, group });
         }
     }
-    return { matches, categoriesUnavailable: false };
+    return { matches, categoriesUnavailable: false, unreadCategories };
 }

package/build/utils/browser-install.js

@@ -13,10 +13,15 @@
  * "Authentication failed" by the auth runner, the actionable command is gone.
  * Matching the error lets us keep the fix attached to the failure.
  *
- * Matching reactively rather than probing for the executable up front keeps us
- * off Playwright's internals, and means no false positives: this only ever
- * fires after a launch has genuinely failed.
+ * Sign-in matches reactively, so it never reports a missing browser unless a
+ * launch really failed. `setup --prepare` and `doctor` check up front instead
+ * (chromiumStatus), through Playwright's public API only, and prepare installs
+ * a missing browser with the package's own Playwright (installChromium).
  */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createRequire } from "node:module";
 import { CLEAR_NPX_CACHE_COMMAND } from "./commands.js";
 export const PLAYWRIGHT_INSTALL_HINT = "Chromium is not installed, so sign-in cannot start. Your package manager " +
     "skipped this package's postinstall script, which is what normally downloads it " +
@@ -30,3 +35,72 @@ export function isMissingBrowserError(error) {
         return false;
     return /Executable doesn't exist|playwright install|Failed to launch.*because executable doesn't exist/i.test(message);
 }
+const defaultProbe = {
+    async launchHeadless() {
+        const { chromium } = await import("playwright");
+        const browser = await chromium.launch({ headless: true, timeout: 30000 });
+        await browser.close();
+    },
+    async executablePath() {
+        const { chromium } = await import("playwright");
+        return chromium.executablePath();
+    },
+    existsSync: fs.existsSync,
+};
+/** Whether both browsers sign-in can use are installed. Never opens a window. */
+export async function chromiumStatus(overrides = {}) {
+    const probe = { ...defaultProbe, ...overrides };
+    let headless = "present";
+    let detail;
+    try {
+        await probe.launchHeadless();
+    }
+    catch (error) {
+        if (isMissingBrowserError(error)) {
+            headless = "missing";
+        }
+        else {
+            headless = "unknown";
+            detail = (error instanceof Error ? error.message : String(error)).split("\n")[0].slice(0, 200);
+        }
+    }
+    let visible = false;
+    try {
+        visible = probe.existsSync(await probe.executablePath());
+    }
+    catch {
+        visible = false;
+    }
+    return { headless, visible, ...(detail ? { detail } : {}) };
+}
+/** True when sign-in has every browser it might need. */
+export function chromiumReady(status) {
+    return status.headless !== "missing" && status.visible;
+}
+/** The CLI of the Playwright this package depends on, so the browser revision matches. */
+export function playwrightCliPath() {
+    const require = createRequire(import.meta.url);
+    return path.join(path.dirname(require.resolve("playwright/package.json")), "cli.js");
+}
+/**
+ * Download Chromium with the package's own Playwright: `npx playwright` can
+ * resolve a different Playwright whose browser this package can't launch,
+ * and needs a shell on Windows. Never `--with-deps`, which needs sudo on
+ * Linux. Progress goes to stderr; stdin is closed so nothing can prompt.
+ */
+export function installChromium(options = {}) {
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const execPath = options.execPath ?? process.execPath;
+    let cliPath;
+    try {
+        cliPath = options.cliPath ?? playwrightCliPath();
+    }
+    catch (error) {
+        return Promise.resolve({ ok: false, message: error instanceof Error ? error.message : String(error) });
+    }
+    return new Promise((resolve) => {
+        const child = spawnImpl(execPath, [cliPath, "install", "chromium"], { stdio: ["ignore", 2, 2] });
+        child.once("error", (error) => resolve({ ok: false, message: error.message }));
+        child.once("close", (code) => resolve(code === 0 ? { ok: true } : { ok: false, message: `Playwright's installer exited with code ${code}.` }));
+    });
+}

package/build/utils/commands.js

@@ -14,6 +14,7 @@
  * Import these instead of writing the command inline. A release test greps the
  * source for untagged forms and fails the build if one reappears.
  */
+import { presetForBaseUrl } from "../setup/presets.js";
 export const PACKAGE_NAME = "brightspace-mcp-server";
 /** Re-authenticate. Always runs the current published release. */
 export const AUTH_COMMAND = `npx -y ${PACKAGE_NAME}@latest auth`;
@@ -27,3 +28,32 @@ export const DOCTOR_COMMAND = `npx -y ${PACKAGE_NAME}@latest doctor`;
 export const GLOBAL_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}@latest`;
 /** Drop cached npx copies so the next `@latest` genuinely refetches. */
 export const CLEAR_NPX_CACHE_COMMAND = "npx clear-npx-cache";
+/**
+ * The school's flag for a setup command, or `--url <origin>` for a school
+ * with no preset. An unreadable URL gives no school at all, which `setup`
+ * then fills from the saved configuration.
+ */
+function schoolArgument(baseUrl) {
+    if (!baseUrl)
+        return "";
+    const match = presetForBaseUrl(baseUrl);
+    if (match)
+        return ` --${match.flag}`;
+    try {
+        return ` --url ${new URL(baseUrl).origin}`;
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * The person's last setup step: enter the password, approve sign-in. Always
+ * runs the current published release.
+ */
+export function signInCommand(baseUrl) {
+    return `${SETUP_COMMAND}${schoolArgument(baseUrl)} --sign-in`;
+}
+/** The no-prompt setup an agent runs before handing over. Always runs the current published release. */
+export function prepareCommand(baseUrl) {
+    return `${SETUP_COMMAND}${schoolArgument(baseUrl)} --prepare`;
+}

package/build/utils/mcp-client-cli.js

@@ -11,6 +11,19 @@ function defaultRunCommand(command, args, stdio) {
     });
     return { status: result.error ? null : result.status, stdout: result.stdout ?? "" };
 }
+/**
+ * For `setup --prepare`, which an agent runs and reads as JSON: the client CLIs
+ * get no stdin, so they can never stop to ask anything, and what they print
+ * goes to stderr, so it can't corrupt the JSON on stdout.
+ */
+export const runCommandWithoutPrompts = (command, args, stdio) => {
+    const result = spawnSync(command, args, {
+        stdio: stdio === "pipe" ? ["ignore", "pipe", "ignore"] : stdio === "inherit" ? ["ignore", 2, 2] : "ignore",
+        encoding: "utf-8",
+        shell: process.platform === "win32",
+    });
+    return { status: result.error ? null : result.status, stdout: result.stdout ?? "" };
+};
 /** The command every client is registered with. */
 export function serverCommand(platform = process.platform) {
     // On Windows, npx is a .cmd shim that must be invoked through cmd.exe

package/build/utils/saved-session.js

@@ -0,0 +1,59 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * Read-only access to the saved sign-in, shared by `doctor` and
+ * `setup --prepare`. Lives apart from doctor.ts because importing that module
+ * runs the doctor command.
+ */
+import * as path from "node:path";
+import * as os from "node:os";
+import { accountSessionDirectory, expandTilde } from "./config.js";
+import { TokenManager } from "../auth/token-manager.js";
+import { SessionStore } from "../auth/session-store.js";
+/**
+ * doctor only ever reads a saved session — it must never write session.json,
+ * trash it, or take the write lock a v1-record migration uses (that lock can
+ * also throw AuthenticationInProgressError while a real sign-in holds it).
+ * SessionStore.peek() is the read-only sibling of load() that does none of
+ * that, so every write-shaped method here is a no-op and load() delegates to
+ * peek() instead of the real load(). Exported for tests, which pass a fake
+ * in place of a real SessionStore to prove the no-op wiring.
+ */
+export function readOnlySessionStore(store) {
+    return {
+        load: () => store.peek(),
+        save: async () => { },
+        clear: async () => { },
+        saveIfCurrent: async () => true,
+        clearIfCurrent: async () => true,
+    };
+}
+/** A TokenManager that can mint from a saved cookie but can never write, clear, or migrate session.json. */
+export function readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie) {
+    return new TokenManager({
+        baseUrl,
+        envAccessToken,
+        envSessionCookie,
+        sessionStore: readOnlySessionStore(new SessionStore(sessionDir)),
+    });
+}
+/** The saved sign-in's token, read-only: never a browser and never a write. Shared with `setup --prepare`. */
+export function readSavedSessionToken(baseUrl, sessionDir, envAccessToken, envSessionCookie) {
+    return readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie).getToken();
+}
+/** Where the saved session for this account lives, honouring D2L_SESSION_DIR and config.json's sessionDir. */
+export function sessionDirFor(env, store, baseUrl, username) {
+    const sessionRoot = env.D2L_SESSION_DIR
+        ? expandTilde(env.D2L_SESSION_DIR)
+        : store?.sessionDir
+            ? expandTilde(store.sessionDir)
+            : path.join(os.homedir(), ".d2l-session");
+    return accountSessionDirectory(sessionRoot, baseUrl, username);
+}
+/** True for the Node versions this package supports (20 and newer). */
+export function nodeVersionSupported(version) {
+    const major = Number(version.replace(/^v/, "").split(".")[0]);
+    return Number.isFinite(major) && major >= 20;
+}

package/package.json

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