brightspace-mcp-server 5.1.7 → 5.1.8

package/README.md

@@ -165,7 +165,10 @@ How often you're asked is up to your school, not this tool. Everything else abou
 
 ## Something not working?
 
-- Run `npx -y brightspace-mcp-server@latest doctor` first — it checks your Node version, the sign-in browser, saved setup, credential store, Brightspace connectivity, saved sign-in, and installed version, and tells you exactly what to fix.
+- Run `npx -y brightspace-mcp-server@latest doctor` first — it checks your Node version, the sign-in browser, saved setup, credential store, Brightspace connectivity, saved sign-in, and installed version, and tells you exactly what to fix. For a global installation, use `brightspace-mcp-server doctor` to check the copy your client launches.
+- **Browser removed during disk cleanup?** Sign-in restores a missing Chromium download once and retries automatically. It uses the installed Playwright dependency's browser revision and preserves saved credentials, MFA enrollment and sessions. Downloads have a two-minute limit; offline or failed repairs return an actionable installation error instead of asking you to reset credentials.
+- **Repair without signing in or changing client configuration:** run `brightspace-mcp-server repair` for a global install, or `npx -y brightspace-mcp-server@latest repair` for an npx installation. Add `--json` for automation. Diagnostics print an absolute command for the exact installation being checked. Repair verifies both the full browser executable and a real headless launch and close. It does not register clients, update school settings, or start SSO/MFA.
+- Browser downloads are disposable; files inside an installed package's `node_modules` are dependency code. If those files were deleted, diagnostics give an installation-scoped npm command to restore the package's declared dependencies first. Browser repair does not run npm or upgrade packages automatically.
 - **`Authentication failed: The native credential store is locked or unavailable.`** Your password store is locked or hasn't let this server read the saved password. Unlock it (on a Mac, log in or unlock Keychain Access), then run `npx -y brightspace-mcp-server@latest auth` again, or `setup` if that still fails, and choose **Always Allow** when Keychain asks.
 - **It works in the terminal but not in the app:** the app starts it separately and may not see your password store yet — see [docs/troubleshooting.md](docs/troubleshooting.md).
 - **The app says the server timed out while starting:** open the app's MCP server log. Each startup step prints a timestamped `Startup: ...` line before it begins and `done in N ms` when it ends, and a step still running after 10 seconds prints `Startup: still ...` once. The last such line names the step it was stuck in, often the saved-password lookup in your password store. These lines never include your username, password, or cookies.

package/build/auth/auth-runner.js

@@ -10,6 +10,7 @@ import * as path from "node:path";
 import { log } from "../utils/logger.js";
 import { AuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
+import { dependencyRepairHint, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
 import { devActivity, newRecoveryId, RECOVERY_ID_ENV } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
 import { AUTOMATIC_PENDING_MARKER, RELAYED_CHALLENGE_MARKER, RELAYED_STARTING_MARKER, authLockPath, challengeRelayedAt, relayChallenge } from "./mfa-challenge.js";
@@ -969,6 +970,8 @@ export class AuthRunner {
                 }
                 else {
                     const failures = {
+                        8: ["browserInstall", PLAYWRIGHT_INSTALL_HINT],
+                        9: ["dependencyMissing", dependencyRepairHint()],
                         2: ["busy", `Authentication already in progress in another process. Complete that attempt, then retry, or run \`${AUTH_COMMAND}\` in a terminal to take over that background attempt.`],
                         3: ["cooldown", `Automatic MFA is paused after an unsuccessful attempt. Run ${AUTH_COMMAND} to retry immediately.`],
                         4: ["unsupported", "This identity provider cannot complete headless authentication. See the authentication logs."],

package/build/auth/browser-auth.js

@@ -14,7 +14,7 @@ import { acquireProcessLock, AuthenticationInProgressError, inspectLockOwner } f
 import { authLockPath, publishAutomaticProgress, publishChallenge, relayChallenge } from "./mfa-challenge.js";
 import { AuthCooldown } from "./auth-cooldown.js";
 import { mintAccessToken } from "./token-mint.js";
-import { isMissingBrowserError, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
+import { launchWithBrowserRecovery } from "../utils/browser-install.js";
 import { signInCommand } from "../utils/commands.js";
 const SILENT_SSO_TIMEOUT_MS = 30000;
 const SILENT_SSO_POLL_MS = 1000;
@@ -164,22 +164,14 @@ export class BrowserAuth {
         };
         try {
             state = await this.stateStore.load();
-            const { chromium } = await import("playwright");
             const args = ["--disable-blink-features=AutomationControlled"];
             if (BrowserAuth.isWSLOrDocker())
                 args.push("--no-sandbox", "--disable-setuid-sandbox");
             // Use Playwright's own timeout, which cleans up an unsuccessful launch.
-            try {
-                browser = await this.timed("launch", () => chromium.launch({ headless: this.config.headless, timeout: 60000, args }));
-            }
-            catch (launchError) {
-                // Keep the remedy attached to the failure. Without this the hint is
-                // lost when the auth runner flattens errors into "Authentication failed".
-                if (isMissingBrowserError(launchError)) {
-                    throw new BrowserAuthError(PLAYWRIGHT_INSTALL_HINT, "browser_missing", launchError);
-                }
-                throw launchError;
-            }
+            browser = await this.timed("launch", () => launchWithBrowserRecovery(async () => {
+                const { chromium } = await import("playwright");
+                return chromium.launch({ headless: this.config.headless, timeout: 60000, args });
+            }));
             process.once("SIGINT", closeOnSignal);
             process.once("SIGTERM", closeOnSignal);
             context = await browser.newContext({ viewport: { width: 1280, height: 720 }, storageState: state });

package/build/auth-cli.js

@@ -19,6 +19,7 @@ import { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
 import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
 import { reexecLatestIfStale } from "./utils/self-update.js";
 import { detectSkew } from "./utils/install-sites.js";
+import { BrowserInstallError } from "./utils/browser-install.js";
 dotenv.config({ quiet: true });
 const pkg = JSON.parse(readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
 async function requestMfaCode() {
@@ -118,15 +119,18 @@ async function main() {
             for (const line of relayedLockLines(error.challenge, error.ownerMode))
                 console.log(line);
         }
-        process.exitCode = error instanceof NativeCredentialStoreError ? 5
-            : code === "AUTH_IN_PROGRESS" ? 2
-                : code === "AUTH_COOLDOWN" ? 3
-                    : code === "AUTH_UNSUPPORTED" ? 4
-                        : code === "AUTH_TRANSPORT" ? 6
-                            : error instanceof MfaApprovalError ? 7 : 1;
+        process.exitCode = error instanceof BrowserInstallError ? (error.dependencyMissing ? 9 : 8)
+            : error instanceof NativeCredentialStoreError ? 5
+                : code === "AUTH_IN_PROGRESS" ? 2
+                    : code === "AUTH_COOLDOWN" ? 3
+                        : code === "AUTH_UNSUPPORTED" ? 4
+                            : code === "AUTH_TRANSPORT" ? 6
+                                : error instanceof MfaApprovalError ? 7 : 1;
         console.error("\nAuthentication failed:", error instanceof Error ? error.message : "Unknown authentication error");
-        console.error(`Run \`${SETUP_COMMAND}\` to update saved credentials.`);
-        console.error(`Run \`${AUTH_COMMAND}\` to retry explicitly. This bypasses the automatic MFA cooldown.`);
+        if (!(error instanceof BrowserInstallError)) {
+            console.error(`Run \`${SETUP_COMMAND}\` to update saved credentials.`);
+            console.error(`Run \`${AUTH_COMMAND}\` to retry explicitly. This bypasses the automatic MFA cooldown.`);
+        }
     }
     finally {
         // The failure path is exactly where knowing you are out of date matters

package/build/doctor.js

@@ -29,7 +29,7 @@ import { discoverVersions } from "./api/version-discovery.js";
 import { D2LApiClient } from "./api/client.js";
 import { fetchLatestVersion, isNewerVersion, safeVersionLabel, installKindOf, } from "./utils/update-checker.js";
 import { SETUP_COMMAND, AUTH_COMMAND, GLOBAL_INSTALL_COMMAND, CLEAR_NPX_CACHE_COMMAND, prepareCommand, signInCommand, } from "./utils/commands.js";
-import { chromiumReady, chromiumStatus } from "./utils/browser-install.js";
+import { chromiumReady, chromiumStatus, dependencyRepairHint, BROWSER_REPAIR_COMMAND } from "./utils/browser-install.js";
 import { nodeVersionSupported, readOnlyTokenManager, readSavedSessionToken, sessionDirFor } from "./utils/saved-session.js";
 // Tests import this from doctor.ts.
 export { readOnlySessionStore } from "./utils/saved-session.js";
@@ -213,7 +213,11 @@ async function checkBrowser(deps) {
     }
     if (chromiumReady(status))
         return pass("browser", "Chromium is installed for sign-in");
-    return problem("browser", `Chromium is missing, so sign-in can't start — run: ${prepareCommand()}`);
+    if (status.headless === "dependency_missing")
+        return problem("browser", dependencyRepairHint());
+    if (status.headless === "unknown")
+        return problem("browser", `Chromium's test launch failed. Check operating system permissions and browser system dependencies — run: ${BROWSER_REPAIR_COMMAND}`);
+    return problem("browser", `Chromium is missing, so sign-in can't start — run: ${BROWSER_REPAIR_COMMAND}`);
 }
 async function checkNetwork(deps, baseUrl) {
     try {

package/build/index.js

@@ -26,7 +26,7 @@ const PKG_VERSION = (() => {
 })();
 // ── Subcommand routing (before any MCP initialization) ──────────────
 const subcommand = process.argv[2];
-const COMMANDS = ['setup', 'auth', 'doctor', 'http', 'runtime'];
+const COMMANDS = ['setup', 'auth', 'doctor', 'repair', 'http', 'runtime'];
 // A mistyped command (`htp`) must not quietly start a stdio server that sits
 // waiting on stdin. Flags alone still mean the default stdio server.
 if (subcommand !== undefined && !subcommand.startsWith('-') && !COMMANDS.includes(subcommand)) {
@@ -37,7 +37,8 @@ if (subcommand !== undefined && !subcommand.startsWith('-') && !COMMANDS.include
         '  http     run one shared MCP server on localhost\n' +
         '  setup    configure your school and sign-in\n' +
         '  auth     sign in to Brightspace now\n' +
-        '  doctor   check the install and configuration\n');
+        '  doctor   check the install and configuration\n' +
+        '  repair   restore and verify this installation\'s Chromium\n');
     process.exit(2);
 }
 if (subcommand === 'setup') {
@@ -49,6 +50,9 @@ else if (subcommand === 'auth') {
 else if (subcommand === 'doctor') {
     await import('./doctor.js');
 }
+else if (subcommand === 'repair') {
+    await (await import('./repair.js')).main();
+}
 else {
     // ── MCP Server ──────────────────────────────────────────────────────
     // default: stdio, relayed to the one shared runtime, started on demand;

package/build/repair.js

@@ -0,0 +1,37 @@
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import { chromiumStatus, chromiumReady, installChromium, dependencyRepairHint, BROWSER_REPAIR_COMMAND } from "./utils/browser-install.js";
+/** Browser maintenance only: no config, credential-store, client or sign-in imports. */
+export async function runRepair(deps = { status: chromiumStatus, install: installChromium }) {
+    let status = await deps.status();
+    if (status.headless === "dependency_missing")
+        return { ok: false, message: dependencyRepairHint() };
+    if (status.headless === "missing" || !status.visible) {
+        const installed = await deps.install();
+        if (!installed.ok)
+            return { ok: false, message: `Chromium installation failed. Check your connection and retry: ${BROWSER_REPAIR_COMMAND}` };
+        status = await deps.status();
+    }
+    return chromiumReady(status)
+        ? { ok: true, message: "Chromium is installed and a headless launch and close succeeded." }
+        : { ok: false, message: "Chromium could not launch. Check operating system permissions and browser system dependencies, then run repair again." };
+}
+export async function main() {
+    const args = process.argv.slice(3);
+    if (args.some(arg => arg !== "--json")) {
+        console.error("Usage: brightspace-mcp-server repair [--json]");
+        process.exitCode = 2;
+        return;
+    }
+    try {
+        const result = await runRepair();
+        console.log(args.includes("--json") ? JSON.stringify(result) : result.message);
+        process.exitCode = result.ok ? 0 : 1;
+    }
+    catch {
+        console.error(`Browser repair failed. Run: ${BROWSER_REPAIR_COMMAND}`);
+        process.exitCode = 1;
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url))
+    void main();

package/build/setup/prepare.js

@@ -13,7 +13,7 @@ import { nodeVersionSupported, readSavedSessionToken, sessionDirFor } from "../u
 import { discoverVersions } from "../api/version-discovery.js";
 import { getConfigStorePath } from "../utils/config-store.js";
 import { saveSecureConfig } from "../utils/secure-config.js";
-import { chromiumReady, chromiumStatus, installChromium, PLAYWRIGHT_INSTALL_HINT, } from "../utils/browser-install.js";
+import { chromiumReady, chromiumStatus, dependencyRepairHint, installChromium, PLAYWRIGHT_INSTALL_HINT, } from "../utils/browser-install.js";
 import { DOCTOR_COMMAND, prepareCommand, signInCommand } from "../utils/commands.js";
 import { runCommandWithoutPrompts } from "../utils/mcp-client-cli.js";
 import { buildConfigToSave, isValidUrl, normalizeUrl, readExistingConfig, sameSchool } from "./config.js";
@@ -135,7 +135,7 @@ export async function runPrepare(args, overrides = {}) {
     steps.push(store.ok ? ok("credential-store", store.line) : fail("credential-store", store.line));
     // ── Chromium ──
     let browser = await deps.chromiumStatus();
-    if (!chromiumReady(browser) && args.installBrowser) {
+    if (!chromiumReady(browser) && args.installBrowser && browser.headless !== "dependency_missing" && browser.headless !== "unknown") {
         deps.progress("  Downloading Chromium for sign-in (this can take a few minutes)...");
         const installed = await deps.installChromium();
         browser = installed.ok ? await deps.chromiumStatus() : browser;
@@ -143,14 +143,14 @@ export async function runPrepare(args, overrides = {}) {
             deps.progress(`  ${installed.message}`);
     }
     if (chromiumReady(browser)) {
-        steps.push(ok("browser", browser.headless === "unknown"
-            ? `Chromium is installed (a test launch didn't work here: ${browser.detail ?? "unknown reason"}; sign-in in a terminal normally still works)`
-            : "Chromium is installed for sign-in"));
+        steps.push(ok("browser", "Chromium is installed for sign-in"));
     }
     else {
-        steps.push(fail("browser", args.installBrowser
-            ? `Chromium could not be installed. ${PLAYWRIGHT_INSTALL_HINT}`
-            : "Chromium is missing — run prepare again without --no-browser-install"));
+        steps.push(fail("browser", browser.headless === "dependency_missing" ? dependencyRepairHint()
+            : browser.headless === "unknown" ? "Chromium's test launch failed. Check operating system permissions and browser system dependencies."
+                : args.installBrowser
+                    ? `Chromium could not be installed. ${PLAYWRIGHT_INSTALL_HINT}`
+                    : "Chromium is missing — run prepare again without --no-browser-install"));
     }
     // ── Network, settings, session (need a school) ──
     let signedIn = false;

package/build/tools/tool-helpers.js

@@ -9,6 +9,7 @@ import { TokenRefreshError } from "../api/errors.js";
 import { AuthProcessError } from "../auth/auth-runner.js";
 import { log } from "../utils/logger.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
+import { dependencyRepairHint, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
 import { getUpdateNotice } from "../utils/update-checker.js";
 import { mfaShortcutTip } from "../utils/two-factor-shortcuts.js";
 import { DownloadError, isSafeDetail, } from "../utils/download-errors.js";
@@ -94,6 +95,8 @@ export function errorResponse(message, kind) {
 const MFA_SOLO_CALL = "Don't run other Brightspace calls in parallel until the sign-in completes: a batched " +
     "answer can reach the user too late to approve. Make one call at a time.";
 const AUTH_FAILURE_GUIDANCE = {
+    browserInstall: PLAYWRIGHT_INSTALL_HINT,
+    dependencyMissing: dependencyRepairHint(),
     busy: "A sign-in is already running in another process. Let it finish, then try again, " +
         `or run \`${AUTH_COMMAND}\` in a terminal to take over that background attempt.`,
     cooldown: "Automatic sign-in is paused because an MFA prompt went unanswered. " +

package/build/utils/browser-install.js

@@ -1,39 +1,46 @@
 /**
  * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
  *
- * Recognising a missing Playwright browser.
- *
- * This package's postinstall downloads Chromium. npm skips postinstall under
- * `--ignore-scripts` and under the newer allow-scripts policy, both of which
- * are common on global installs, so the package can land without a browser and
- * fail only later, at first sign-in.
- *
- * Playwright's own message does say what to run, but by the time it has been
- * wrapped in BrowserAuthError and then flattened into a generic
- * "Authentication failed" by the auth runner, the actionable command is gone.
- * Matching the error lets us keep the fix attached to the failure.
- *
- * 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).
+ * Browser downloads are disposable; installed dependency code is not.
+ * Repair downloads through this installation's own Playwright CLI. Sign-in
+ * repairs only a missing executable and retries once; it never runs npm.
  */
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } 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 " +
-    "(common with --ignore-scripts or an allow-scripts policy). Run: " +
-    "npx playwright install chromium" +
-    `. If that does not help, reinstall and clear caches with ${CLEAR_NPX_CACHE_COMMAND}.`;
+import { fileURLToPath } from "node:url";
+/** Run the installation that reported the error, even from another project. */
+export const BROWSER_REPAIR_COMMAND = `node "${fileURLToPath(new URL("../index.js", import.meta.url)).replaceAll("\\", "/")}" repair`;
+export function dependencyRepairHint() {
+    const root = fileURLToPath(new URL("../../", import.meta.url)).replaceAll("\\", "/");
+    const reinstall = root.split("/").includes("node_modules")
+        ? `npm install --prefix "${root}" --omit=dev`
+        : `npm ci --prefix "${root}", then npm run build in that directory`;
+    return "Playwright's package code is missing. Restore this installation's declared dependencies with " +
+        `${reinstall}, then run: ${BROWSER_REPAIR_COMMAND}`;
+}
+export class BrowserInstallError extends Error {
+    dependencyMissing;
+    constructor(dependencyMissing = false) {
+        super(dependencyMissing ? dependencyRepairHint() : PLAYWRIGHT_INSTALL_HINT);
+        this.dependencyMissing = dependencyMissing;
+        this.name = "BrowserInstallError";
+    }
+}
+export function isMissingPlaywrightError(error) {
+    const code = error?.code;
+    return (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") &&
+        /playwright/.test(error instanceof Error ? error.message : "");
+}
+export const PLAYWRIGHT_INSTALL_HINT = "Chromium is missing or could not be restored. It may have been removed after installation, " +
+    `or the install script may have been skipped. Run: ${BROWSER_REPAIR_COMMAND}`;
 /** True when an error is Playwright reporting that no browser binary exists. */
 export function isMissingBrowserError(error) {
     const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
     if (!message)
         return false;
-    return /Executable doesn't exist|playwright install|Failed to launch.*because executable doesn't exist/i.test(message);
+    return /Executable doesn't exist|Failed to launch.*because executable doesn't exist/i.test(message);
 }
 const defaultProbe = {
     async launchHeadless() {
@@ -56,7 +63,10 @@ export async function chromiumStatus(overrides = {}) {
         await probe.launchHeadless();
     }
     catch (error) {
-        if (isMissingBrowserError(error)) {
+        if (isMissingPlaywrightError(error)) {
+            headless = "dependency_missing";
+        }
+        else if (isMissingBrowserError(error)) {
             headless = "missing";
         }
         else {
@@ -75,7 +85,42 @@ export async function chromiumStatus(overrides = {}) {
 }
 /** True when sign-in has every browser it might need. */
 export function chromiumReady(status) {
-    return status.headless !== "missing" && status.visible;
+    return status.headless === "present" && status.visible;
+}
+/** One repair and one retry; unrelated launch failures never download anything.
+ * Authentication already holds its process lock; Playwright's installer also
+ * locks the shared browser cache across installations and accounts.
+ */
+export async function launchWithBrowserRecovery(launch, install = installChromium, progress = () => console.error("Restoring Chromium for Brightspace sign-in...")) {
+    try {
+        return await launch();
+    }
+    catch (error) {
+        if (isMissingPlaywrightError(error))
+            throw new BrowserInstallError(true);
+        if (!isMissingBrowserError(error))
+            throw error;
+    }
+    progress();
+    let installed;
+    try {
+        installed = await install();
+    }
+    catch {
+        throw new BrowserInstallError();
+    }
+    if (!installed.ok)
+        throw new BrowserInstallError();
+    try {
+        return await launch();
+    }
+    catch (error) {
+        if (isMissingPlaywrightError(error))
+            throw new BrowserInstallError(true);
+        if (isMissingBrowserError(error))
+            throw new BrowserInstallError();
+        throw error;
+    }
 }
 /** The CLI of the Playwright this package depends on, so the browser revision matches. */
 export function playwrightCliPath() {
@@ -99,7 +144,30 @@ export function installChromium(options = {}) {
         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] });
+        const child = spawnImpl(execPath, [cliPath, "install", "chromium"], {
+            stdio: ["ignore", 2, 2], detached: process.platform !== "win32",
+        });
+        const timer = setTimeout(() => {
+            // Include Playwright's download worker, so a timeout cannot leave an
+            // orphan downloading into the cache or holding its installation lock.
+            try {
+                if (child.pid && process.platform === "win32") {
+                    execFileSync("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore", timeout: 5000 });
+                }
+                else if (child.pid) {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                else
+                    child.kill("SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+            resolve({ ok: false, message: "Chromium installation timed out. Check your connection and run repair again." });
+        }, options.timeoutMs ?? 120_000);
+        timer.unref();
+        child.once("close", () => clearTimeout(timer));
+        child.once("error", () => clearTimeout(timer));
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "5.1.7",
+  "version": "5.1.8",
   "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",
@@ -12,6 +12,7 @@
   },
   "files": [
     "build",
+    "scripts/install-browser.cjs",
     "README.md",
     "LICENSE"
   ],
@@ -24,7 +25,8 @@
     "dev": "tsc --watch",
     "test": "vitest",
     "test:run": "vitest run",
-    "postinstall": "npx playwright install chromium"
+    "test:install": "node scripts/install-smoke.mjs",
+    "postinstall": "node scripts/install-browser.cjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",

package/scripts/install-browser.cjs

@@ -0,0 +1,18 @@
+// Works in both a source checkout (before build) and the published tarball.
+// Resolve this package's dependency, never a Playwright from the caller's cwd.
+const { spawnSync } = require("node:child_process");
+const { dirname, join } = require("node:path");
+const cli = join(dirname(require.resolve("playwright/package.json")), "cli.js");
+const result = spawnSync(process.execPath, [cli, "install", "chromium"], {
+  stdio: "inherit",
+});
+if (result.error || result.status !== 0) {
+  console.error("Chromium installation failed. Retry with brightspace-mcp-server repair after installation completes.");
+  process.exit(1);
+}
+require("playwright").chromium.launch({ headless: true, timeout: 30_000 })
+  .then(browser => browser.close())
+  .catch(() => {
+    console.error("Chromium was downloaded but could not launch. Check operating system permissions and browser system dependencies.");
+    process.exitCode = 1;
+  });