brightspace-mcp-server 3.15.3 → 4.0.0

package/build/tools/search-course.js

@@ -232,9 +232,10 @@ export function registerSearchCourse(server, apiClient) {
                     }
                     catch (error) {
                         // One forum's topics failing (e.g. no access) shouldn't drop
-                        // every other forum — same graceful-degradation rule
-                        // get_discussions already follows for this exact call.
+                        // every other forum, but it still has to be named in `note` so
+                        // a search missing those topics never reads as complete.
                         log("DEBUG", `search_course: topics fetch failed for forum ${forum.ForumId}`, error);
+                        notes.push(`discussions: topics in "${forum.Name}" ${describeFailure(error)}`);
                     }
                 }
             }

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.3",
+  "version": "4.0.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",