brightspace-mcp-server 5.1.6 → 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/download-dropbox-submission-file.js

@@ -23,7 +23,8 @@ function tooLargeResponse(bytes) {
 export function registerDownloadDropboxSubmissionFile(server, apiClient) {
     server.registerTool("download_dropbox_submission_file", {
         title: "Download Dropbox Submission File",
-        description: "Download a specific file from a student's (or group's) dropbox submission to a local directory, " +
+        description: "Download a specific file from a student's (or group's) dropbox submission to an existing local directory " +
+            "(it is not created for you), " +
             "for an instructor or TA. Use get_dropbox_submissions or get_dropbox_user_submissions first to " +
             "find submissionId and fileId. Requires instructor or TA access to the course. " +
             "IMPORTANT: Ask the user where they want to save the file before calling this tool. " +
@@ -48,7 +49,7 @@ export function registerDownloadDropboxSubmissionFile(server, apiClient) {
             }
             catch (error) {
                 if (error?.code === "ENOENT") {
-                    return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
+                    return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
                 }
                 throw error;
             }

package/build/tools/download-file.js

@@ -267,7 +267,7 @@ function extensionNote(requestedFilename, saved) {
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
+        description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. The directory must already exist; it is not created for you. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {
@@ -299,7 +299,7 @@ export function registerDownloadFile(server, apiClient) {
                 }
                 catch (error) {
                     if (error?.code === "ENOENT") {
-                        return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
+                        return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
                     }
                     throw error;
                 }

package/build/tools/get-syllabus.js

@@ -110,7 +110,7 @@ async function discoverExternalSyllabusSources(apiClient, courseId) {
 export function registerGetSyllabus(server, apiClient) {
     server.registerTool("get_syllabus", {
         title: "Get Course Syllabus",
-        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. When the syllabus lives in an external LTI tool (e.g. Simple Syllabus), lists those sources in externalSyllabusSources; their contents cannot be read. If some of those lookups could not be completed (e.g. permission denied), externalSyllabusDiscovery says which, and an empty result is then not proof the course has no syllabus. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
+        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. When the syllabus lives in an external LTI tool (e.g. Simple Syllabus), lists those sources in externalSyllabusSources; their contents cannot be read. If some of those lookups could not be completed (e.g. permission denied), externalSyllabusDiscovery says which, and an empty result is then not proof the course has no syllabus. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF); the directory must already exist, since it is not created for you. IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
         inputSchema: GetSyllabusSchema,
     }, async (args) => {
         try {
@@ -129,7 +129,7 @@ export function registerGetSyllabus(server, apiClient) {
                 }
                 catch (error) {
                     if (error?.code === "ENOENT") {
-                        return errorResponse(`Download directory does not exist: ${downloadPath}`, "destination");
+                        return errorResponse(`Download directory does not exist: ${downloadPath}. Create it, then retry, or choose an existing directory.`, "destination");
                     }
                     throw error;
                 }

package/build/tools/schemas.js

@@ -78,7 +78,7 @@ export const DownloadFileSchema = z.object({
     newsId: z.coerce.number().int().positive().optional()
         .describe("Announcement (news item) ID whose attachment to download. Requires fileId."),
     downloadPath: z.string().min(1).optional()
-        .describe("Absolute path to the directory where the file should be saved on disk. Omit this to receive the file inline in the tool response instead — the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see files an MCP server writes to its own host filesystem. Inline mode returns extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, and a short description (pointing back to disk mode) for anything else, capped at 10MB and 400,000 characters of extracted text."),
+        .describe("Absolute path to an existing directory where the file should be saved on disk. The directory must already exist; it is not created for you, so create it first if needed. Omit this to receive the file inline in the tool response instead — the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see files an MCP server writes to its own host filesystem. Inline mode returns extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, and a short description (pointing back to disk mode) for anything else, capped at 10MB and 400,000 characters of extracted text."),
     customFilename: z.string().max(255).optional()
         .describe("Custom filename for the downloaded file (include extension). If not provided, uses the original filename from Brightspace."),
 });
@@ -86,7 +86,7 @@ export const GetSyllabusSchema = z.object({
     courseId: z.coerce.number().int().positive()
         .describe("Course ID to get syllabus for."),
     downloadPath: z.string().min(1).optional()
-        .describe("Absolute path to the directory where the attachment should be saved."),
+        .describe("Absolute path to an existing directory where the attachment should be saved. The directory must already exist; it is not created for you, so create it first if needed."),
 });
 export const GetDiscussionsSchema = z.object({
     courseId: z.coerce.number().int().positive()
@@ -219,7 +219,7 @@ export const DownloadDropboxSubmissionFileSchema = z.object({
     fileId: z.coerce.number().int().positive()
         .describe("File ID within that submission."),
     downloadPath: z.string().min(1)
-        .describe("Absolute path to the local directory where the file should be saved."),
+        .describe("Absolute path to an existing local directory where the file should be saved. The directory must already exist; it is not created for you, so create it first if needed."),
     customFilename: z.string().max(255).optional()
         .describe("Custom filename for the downloaded file (include extension). If omitted, uses the original submission filename."),
 });

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.6",
+  "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;
+  });