brightspace-mcp-server 3.15.4 → 4.0.0

package/README.md

@@ -25,7 +25,7 @@ Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, and a
    ```bash
    npx -y brightspace-mcp-server@latest setup
    ```
-   It asks for your school's Brightspace address, your username and password, and how you normally do two-factor sign-in (phone approval, authenticator code, or a browser window). Your password goes into your computer's own password store (Keychain on Mac, Credential Manager on Windows), never into a file. At the end it connects itself to Claude Desktop, Cursor, Antigravity, Codex, or Claude Code if you have them. If one of them already has a `brightspace` entry pointing somewhere else (an old local build, a fork), setup shows you that entry and asks before replacing it.
+   It asks for your school's Brightspace address, your username and password, and how you confirm it's you when you sign in (a phone app, or another way like a text message). Your password goes into your computer's own password store (Keychain on Mac, Credential Manager on Windows), never into a file. Before signing you in, it connects itself to Claude Desktop, Cursor, Antigravity, Codex, or Claude Code if you have them. If one of them already has a `brightspace` entry pointing somewhere else (an old local build, a fork), setup shows you that entry and asks before replacing it.
 
    **On a Mac:** when Keychain asks whether `node` may use the saved Brightspace password, choose **Always Allow**, not just Allow. That lets later sign-ins (the `auth` command and questions from your AI app) read it without asking again.
 3. **Restart your AI app and ask it something** — the first question signs you in. If your phone asks you to approve a sign-in, approve it and ask again.
@@ -40,6 +40,8 @@ https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
 (use --purdue at Purdue, --suny at SUNY, --tudelft at TU Delft, --cuny at CUNY, --leiden at Leiden, --mcgill at McGill, --ngeeann at Ngee Ann Polytechnic, or --javeriana at Javeriana Cali).
 ```
 
+The AI does everything it can by itself: it checks your computer, downloads the browser sign-in uses, and connects your AI apps. Then it gives you one command to run in a terminal. That command asks for your password and waits for you to approve the sign-in on your phone. That's the only part that needs you. Afterwards the AI checks that it can see your courses.
+
 Using a different AI app? Add the command `npx -y brightspace-mcp-server@latest` to its MCP settings (on Windows: `cmd /c npx -y brightspace-mcp-server@latest`). Exact steps for each app: [docs/troubleshooting.md](docs/troubleshooting.md).
 
 ## Does my school work?
@@ -125,7 +127,7 @@ 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, 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.
 - **`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).
 - **Which version do I have?** Ask your AI "which version of the Brightspace server am I running?"

package/build/auth/browser-auth.js

@@ -15,6 +15,7 @@ import { authLockPath, publishAutomaticProgress, publishChallenge, relayChalleng
 import { AuthCooldown } from "./auth-cooldown.js";
 import { mintAccessToken } from "./token-mint.js";
 import { isMissingBrowserError, PLAYWRIGHT_INSTALL_HINT } from "../utils/browser-install.js";
+import { signInCommand } from "../utils/commands.js";
 const SILENT_SSO_TIMEOUT_MS = 30000;
 const SILENT_SSO_POLL_MS = 1000;
 const INITIAL_NAVIGATION_TIMEOUT_MS = 60000;
@@ -419,7 +420,7 @@ export class BrowserAuth {
                 await this.waitForVisibleLogin(page);
                 return false;
             }
-            throw new UnsupportedAuthenticationError("Automatic sign-in requires saved credentials. Run brightspace-mcp-server setup.");
+            throw new UnsupportedAuthenticationError(`Automatic sign-in requires saved credentials. Run this in a terminal: ${signInCommand(this.config.baseUrl)}`);
         }
         if (!pendingMfa && !credentialPrompt) {
             if (this.config.headless === false) {

package/build/doctor.js

@@ -21,17 +21,18 @@
 import { readFileSync } from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import * as os from "node:os";
 import { configStoreExists, loadConfigStore, } from "./utils/config-store.js";
-import { accountSessionDirectory, envBoolean, expandTilde, readEnvSecret, parseSessionCookieEnv } from "./utils/config.js";
+import { envBoolean, readEnvSecret, parseSessionCookieEnv } from "./utils/config.js";
 import { getStoredPassword, getStoredTotpUri } from "./auth/credential-store.js";
 import { describeShortcuts } from "./utils/two-factor-shortcuts.js";
 import { discoverVersions } from "./api/version-discovery.js";
-import { TokenManager } from "./auth/token-manager.js";
-import { SessionStore } from "./auth/session-store.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, } from "./utils/commands.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 { nodeVersionSupported, readOnlyTokenManager, readSavedSessionToken, sessionDirFor } from "./utils/saved-session.js";
+// Tests import this from doctor.ts.
+export { readOnlySessionStore } from "./utils/saved-session.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function readInstalledVersion() {
@@ -43,33 +44,6 @@ function readInstalledVersion() {
         return "0.0.0";
     }
 }
-/**
- * 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. */
-function readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie) {
-    return new TokenManager({
-        baseUrl,
-        envAccessToken,
-        envSessionCookie,
-        sessionStore: readOnlySessionStore(new SessionStore(sessionDir)),
-    });
-}
 function defaultDoctorDeps() {
     return {
         nodeVersion: process.version,
@@ -80,7 +54,7 @@ function defaultDoctorDeps() {
         getStoredPassword,
         getStoredTotpUri: (baseUrl, username) => getStoredTotpUri(baseUrl, username),
         discoverVersions,
-        getSessionToken: (baseUrl, sessionDir, envAccessToken, envSessionCookie) => readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie).getToken(),
+        getSessionToken: readSavedSessionToken,
         countCourses: async (baseUrl, sessionDir, envAccessToken, envSessionCookie) => {
             const apiClient = new D2LApiClient({
                 baseUrl,
@@ -91,6 +65,7 @@ function defaultDoctorDeps() {
             return { count: response?.Items?.length ?? 0, hasMore: Boolean(response?.PagingInfo?.HasMoreItems) };
         },
         fetchLatestVersion,
+        chromiumStatus: () => chromiumStatus(),
         installKind: installKindOf(),
         installedVersion: readInstalledVersion(),
     };
@@ -103,8 +78,7 @@ function problem(id, message) {
 }
 // ── Individual checks ────────────────────────────────────────────────
 function checkNode(deps) {
-    const major = Number(deps.nodeVersion.replace(/^v/, "").split(".")[0]);
-    if (Number.isFinite(major) && major >= 20) {
+    if (nodeVersionSupported(deps.nodeVersion)) {
         return pass("node", `Node.js ${deps.nodeVersion} (20 or newer)`);
     }
     return problem("node", `Node.js ${deps.nodeVersion} is too old — install Node 20 or newer from https://nodejs.org/, then try again.`);
@@ -154,12 +128,7 @@ function checkConfig(deps) {
     catch {
         return { ok: false, result: problem("config", `The configured Brightspace URL is invalid — run: ${SETUP_COMMAND}`) };
     }
-    const sessionRoot = deps.env.D2L_SESSION_DIR
-        ? expandTilde(deps.env.D2L_SESSION_DIR)
-        : store?.sessionDir
-            ? expandTilde(store.sessionDir)
-            : path.join(os.homedir(), ".d2l-session");
-    const sessionDir = accountSessionDirectory(sessionRoot, baseUrl, username);
+    const sessionDir = sessionDirFor(deps.env, store, baseUrl, username);
     const label = username ? `signed in as ${username} at ${baseUrl}` : `configured for ${baseUrl} via environment variables`;
     return {
         ok: true,
@@ -183,7 +152,7 @@ async function checkCredential(deps, baseUrl, username, envAccessToken, envSessi
         const password = await deps.getStoredPassword(baseUrl, username);
         if (password)
             return pass("credential", "Password saved in your operating system's credential store");
-        return problem("credential", `No saved password found for this account — run: ${SETUP_COMMAND}`);
+        return problem("credential", `No saved password found for this account — run this in a terminal: ${signInCommand(baseUrl)}`);
     }
     catch (error) {
         // On Linux the store itself (secret-tool / an unlocked Secret Service)
@@ -193,7 +162,7 @@ async function checkCredential(deps, baseUrl, username, envAccessToken, envSessi
         if (deps.platform === "linux") {
             return problem("credential", error instanceof Error ? error.message : "The Linux credential store is locked or unavailable. Unlock your keyring and try again.");
         }
-        return problem("credential", `Run setup again: ${SETUP_COMMAND}`);
+        return problem("credential", `Run this in a terminal to save your password again: ${signInCommand(baseUrl)}`);
     }
 }
 /**
@@ -229,6 +198,23 @@ async function describeTwoFactorShortcuts(deps, baseUrl, username) {
     }
     return describeShortcuts({ rememberMfa, keySaved });
 }
+async function checkBrowser(deps) {
+    // An environment credential signs in without a browser, so a container
+    // with no Chromium is still a working install.
+    if (deps.env.D2L_ACCESS_TOKEN || deps.env.D2L_SESSION_COOKIE) {
+        return pass("browser", "Chromium not needed: signing in via an environment variable");
+    }
+    let status;
+    try {
+        status = await deps.chromiumStatus();
+    }
+    catch {
+        return problem("browser", `Could not check for Chromium — run: ${prepareCommand()}`);
+    }
+    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()}`);
+}
 async function checkNetwork(deps, baseUrl) {
     try {
         await deps.discoverVersions(baseUrl);
@@ -238,8 +224,12 @@ async function checkNetwork(deps, baseUrl) {
         return problem("network", `Could not reach ${baseUrl} — check your internet connection and the school address, then run doctor again.`);
     }
 }
-async function checkSession(deps, baseUrl, sessionDir, envAccessToken, envSessionCookie) {
-    const failMessage = `No working saved sign-in — open your AI app and ask a question to sign in, or run: ${AUTH_COMMAND}`;
+async function checkSession(deps, baseUrl, sessionDir, envAccessToken, envSessionCookie, passwordSaved) {
+    // Without a saved password (an install `setup --prepare` got ready), asking
+    // the AI app can't sign in on its own: the person has to run sign-in.
+    const failMessage = passwordSaved
+        ? `No working saved sign-in — open your AI app and ask a question to sign in, or run: ${AUTH_COMMAND}`
+        : `Not signed in yet — run this in a terminal: ${signInCommand(baseUrl)}`;
     try {
         const token = await deps.getSessionToken(baseUrl, sessionDir, envAccessToken, envSessionCookie);
         if (token)
@@ -302,6 +292,7 @@ async function checkVersion(deps) {
 /** Human-readable name for each check, used to prefix its "Skipped" line. */
 const CHECK_NAMES = {
     node: "Node.js version",
+    browser: "Chromium",
     config: "Setup",
     credential: "Credential store",
     network: "Brightspace reachability",
@@ -319,6 +310,7 @@ export async function runDoctorChecks(overrides = {}) {
     const checks = [];
     const notes = [];
     checks.push(checkNode(deps));
+    checks.push(await checkBrowser(deps));
     const config = checkConfig(deps);
     checks.push(config.result);
     if (!config.ok) {
@@ -328,10 +320,11 @@ export async function runDoctorChecks(overrides = {}) {
         checks.push(skip("courses", SKIPPED_SETUP));
     }
     else {
-        checks.push(await checkCredential(deps, config.baseUrl, config.username, config.envAccessToken, config.envSessionCookie));
+        const credential = await checkCredential(deps, config.baseUrl, config.username, config.envAccessToken, config.envSessionCookie);
+        checks.push(credential);
         notes.push(await describeTwoFactorShortcuts(deps, config.baseUrl, config.username));
         checks.push(await checkNetwork(deps, config.baseUrl));
-        const session = await checkSession(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie);
+        const session = await checkSession(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie, credential.ok);
         checks.push(session.result);
         if (session.ok) {
             checks.push(await checkCourses(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie));
@@ -346,6 +339,13 @@ export async function runDoctorChecks(overrides = {}) {
 // ── CLI entry point ──────────────────────────────────────────────────
 async function main() {
     const result = await runDoctorChecks();
+    // For agents finishing an install: the same result, machine-readable, and
+    // nothing else on stdout.
+    if (process.argv.includes("--json")) {
+        console.log(JSON.stringify(result, null, 2));
+        process.exitCode = result.allOk ? 0 : 1;
+        return;
+    }
     console.log("");
     console.log("Brightspace MCP Server — doctor");
     console.log("");

package/build/setup/args.js

@@ -0,0 +1,107 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * Command-line flags for `setup`. Three modes share one entry point:
+ *
+ * - wizard (no mode flag): the interactive setup a person runs start to finish.
+ * - `--prepare`: everything an AI agent can do without the person — checks,
+ *   Chromium, saved settings, registering the server in AI apps. Never reads
+ *   stdin and never asks for a password.
+ * - `--sign-in`: the person's last step. Uses what prepare saved and asks
+ *   only what needs them (password, how they confirm sign-in), then signs in.
+ */
+import { SCHOOL_PRESETS, presetForFlag } from "./presets.js";
+const VALUE_FLAGS = new Set(["url", "username", "campus"]);
+const BOOLEAN_FLAGS = new Set(["prepare", "sign-in", "json", "replace", "no-browser-install", "help"]);
+export const SETUP_USAGE = `Usage: brightspace-mcp-server setup [--<school>] [options]
+
+Schools: ${Object.keys(SCHOOL_PRESETS).map((flag) => `--${flag}`).join(", ")}
+
+Modes:
+  (none)                 Interactive setup, start to finish
+  --prepare              For AI agents: get everything ready without asking
+                         for a password or opening a sign-in (no prompts)
+  --sign-in              The last step, for the person: password and sign-in
+
+Options:
+  --url <address>        Your school's Brightspace address, when it has no flag above
+  --username <name>      The username you sign in with (prepare, sign-in)
+  --campus <name>        SUNY campus (prepare, sign-in)
+  --json                 Print the prepare result as JSON on stdout
+  --replace              Replace a "brightspace" entry that runs something else
+  --no-browser-install   Don't download Chromium during prepare
+  --help                 Show this help`;
+/**
+ * Read `setup`'s flags. `argv` is the full process.argv: the subcommand name
+ * is skipped when present (`brightspace-mcp-server setup ...`) and absent for
+ * the `brightspace-setup` bin. Both `--url x` and `--url=x` work. An unknown
+ * flag is an error rather than ignored, so an agent that mistypes `--prepare`
+ * is told so instead of landing in a wizard that waits for typing.
+ */
+export function parseSetupArgs(argv = process.argv) {
+    const tokens = argv.slice(2);
+    if (tokens[0] === "setup")
+        tokens.shift();
+    const args = { mode: "wizard", json: false, replace: false, installBrowser: true, help: false };
+    const modes = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === "-h") {
+            args.help = true;
+            continue;
+        }
+        if (!token.startsWith("--"))
+            return { ok: false, error: `Unexpected argument: ${token}` };
+        const eq = token.indexOf("=");
+        const name = (eq === -1 ? token.slice(2) : token.slice(2, eq)).toLowerCase();
+        const inline = eq === -1 ? undefined : token.slice(eq + 1);
+        if (VALUE_FLAGS.has(name)) {
+            const value = inline ?? tokens[++i];
+            if (value === undefined || value.startsWith("--") || !value.trim()) {
+                return { ok: false, error: `--${name} needs a value.` };
+            }
+            if (name === "url")
+                args.url = value.trim();
+            else if (name === "username")
+                args.username = value.trim();
+            else
+                args.campus = value.trim();
+            continue;
+        }
+        if (inline !== undefined)
+            return { ok: false, error: `--${name} does not take a value.` };
+        if (BOOLEAN_FLAGS.has(name)) {
+            if (name === "prepare")
+                modes.push("prepare");
+            else if (name === "sign-in")
+                modes.push("sign-in");
+            else if (name === "json")
+                args.json = true;
+            else if (name === "replace")
+                args.replace = true;
+            else if (name === "no-browser-install")
+                args.installBrowser = false;
+            else
+                args.help = true;
+            continue;
+        }
+        const preset = presetForFlag(name);
+        if (!preset)
+            return { ok: false, error: `Unknown option: --${name}` };
+        if (args.preset && args.preset !== preset)
+            return { ok: false, error: "Pass only one school flag." };
+        args.school = name;
+        args.preset = preset;
+    }
+    if (modes.length > 1)
+        return { ok: false, error: "Use either --prepare or --sign-in, not both." };
+    if (modes.length === 1)
+        args.mode = modes[0];
+    if (args.preset && args.url)
+        return { ok: false, error: "Pass either a school flag or --url, not both." };
+    if (args.json && args.mode !== "prepare")
+        return { ok: false, error: "--json works only with --prepare." };
+    return { ok: true, args };
+}

package/build/setup/clients.js

@@ -0,0 +1,189 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * The AI apps setup can register the server in. The interactive wizard asks
+ * about each one; `setup --prepare` registers every one it finds without
+ * asking. Both walk the same list from detectMcpClients.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { writeFileAtomicSync } from "../utils/atomic-write.js";
+import { classifyRegistration, cliMcpClients, inspectCliMcpClient, isCliAvailable, registerCliMcpClient, serverCommand, } from "../utils/mcp-client-cli.js";
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+export function getClaudeDesktopConfigPath(platform = os.platform(), home = os.homedir(), env = process.env) {
+    if (platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32") {
+        const appdata = env.APPDATA || path.join(home, "AppData", "Roaming");
+        return path.join(appdata, "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "linux") {
+        return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+    }
+    return null;
+}
+export function isChatGPTInstalled() {
+    const platform = os.platform();
+    if (platform === "darwin") {
+        return (fs.existsSync("/Applications/ChatGPT.app") ||
+            fs.existsSync(path.join(os.homedir(), "Applications", "ChatGPT.app")));
+    }
+    if (platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+        return fs.existsSync(path.join(localAppData, "Programs", "ChatGPT", "ChatGPT.exe"));
+    }
+    return false;
+}
+export function getCursorConfigPath(home = os.homedir()) {
+    return path.join(home, ".cursor", "mcp.json");
+}
+export function getAntigravityConfigPath(home = os.homedir()) {
+    return path.join(home, ".gemini", "antigravity", "mcp_config.json");
+}
+/**
+ * A JSON value we can safely merge a server entry into. An array passes
+ * `typeof x === "object"` but drops every added key when it is stringified
+ * again, so it has to be rejected alongside `null`.
+ */
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** How the client's existing "brightspace" entry compares with ours. */
+export function inspectMcpClient(configPath) {
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        // No file, or one configureMcpClient would replace anyway.
+        return { state: "missing" };
+    }
+    const servers = isJsonObject(config) ? config.mcpServers : undefined;
+    return classifyRegistration(isJsonObject(servers) ? servers.brightspace : undefined);
+}
+export function configureMcpClient(configPath, warn = console.log) {
+    let config = {};
+    // Read existing config if present
+    if (fs.existsSync(configPath)) {
+        let parsed;
+        let readable = true;
+        try {
+            parsed = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        }
+        catch {
+            readable = false;
+        }
+        if (isJsonObject(parsed)) {
+            config = parsed;
+        }
+        else {
+            // Unparseable, or valid JSON that is not an object (null, an array, a
+            // bare string). Merging into it would either throw or silently discard
+            // the entry we just reported as written, so start fresh and say so.
+            warn(yellow(`  Warning: existing config was ${readable ? "not a JSON object" : "invalid"}, creating new one.`));
+            config = {};
+        }
+    }
+    // Same reasoning for the servers map itself, which is hand-edited far more
+    // often than the file around it.
+    const servers = isJsonObject(config.mcpServers) ? config.mcpServers : {};
+    config.mcpServers = servers;
+    // Add/update brightspace entry
+    const [command, ...args] = serverCommand();
+    servers["brightspace"] = { command, args };
+    // Ensure parent directory exists
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    // This file holds every MCP server the user has configured, not just ours.
+    // A plain write truncates it first, so a write that fails part way through
+    // (a full disk, an I/O error) would leave the user with no MCP servers at
+    // all. Staging and renaming leaves either the old file or the new one.
+    // The existing permissions are carried over, since the rename would
+    // otherwise replace them with the umask default.
+    let mode;
+    try {
+        if (fs.existsSync(configPath))
+            mode = fs.statSync(configPath).mode & 0o777;
+    }
+    catch {
+        // Unreadable metadata is not a reason to skip the write.
+    }
+    writeFileAtomicSync(configPath, JSON.stringify(config, null, 2) + "\n", mode === undefined ? {} : { mode });
+    return true;
+}
+export function detectMcpClients(overrides = {}) {
+    const deps = {
+        platform: os.platform(),
+        home: os.homedir(),
+        env: process.env,
+        existsSync: fs.existsSync,
+        warn: console.log,
+        ...overrides,
+    };
+    const targets = [];
+    const fileTarget = (id, name, configPath, question) => ({
+        id,
+        name,
+        detected: deps.existsSync(path.dirname(configPath)),
+        question,
+        inspect: () => inspectMcpClient(configPath),
+        write: () => configureMcpClient(configPath, deps.warn),
+    });
+    const claudePath = getClaudeDesktopConfigPath(deps.platform, deps.home, deps.env);
+    if (claudePath) {
+        targets.push(fileTarget("claude-desktop", "Claude Desktop", claudePath, "Would you like to automatically configure Claude Desktop? Highly recommended. (yes/no): "));
+    }
+    const cursorPath = getCursorConfigPath(deps.home);
+    if (deps.existsSync(path.dirname(cursorPath))) {
+        targets.push(fileTarget("cursor", "Cursor", cursorPath, "Cursor detected. Would you like to configure it too? (yes/no): "));
+    }
+    const antigravityPath = getAntigravityConfigPath(deps.home);
+    if (deps.existsSync(path.dirname(antigravityPath))) {
+        targets.push(fileTarget("antigravity", "Antigravity", antigravityPath, "Antigravity detected. Would you like to configure it too? (yes/no): "));
+    }
+    for (const client of cliMcpClients(deps.platform)) {
+        if (!isCliAvailable(client, deps.runCommand))
+            continue;
+        targets.push({
+            id: client.id,
+            name: client.displayName,
+            detected: true,
+            question: `${client.displayName} detected. Configure it automatically? Highly recommended. (yes/no): `,
+            inspect: () => inspectCliMcpClient(client, deps.runCommand),
+            write: (replace) => registerCliMcpClient(client, { replace }, deps.runCommand),
+        });
+    }
+    return targets;
+}
+/**
+ * Register the server in every given app without asking. An entry that runs
+ * something else is left alone unless `replace` is set, and a write that
+ * fails (an agent's sandbox may block another app's settings folder) is
+ * reported for that app instead of stopping the rest.
+ */
+export function registerAll(targets, { replace }) {
+    return targets.map((target) => {
+        const base = { id: target.id, name: target.name };
+        try {
+            const existing = target.inspect();
+            if (existing.state === "current")
+                return { ...base, outcome: "current" };
+            if (existing.state === "different" && !replace) {
+                return { ...base, outcome: "different_left", current: existing.current };
+            }
+            if (!target.write(existing.state === "different")) {
+                return { ...base, outcome: "failed", message: `${target.name} did not accept the registration.` };
+            }
+            return { ...base, outcome: existing.state === "different" ? "replaced" : "added" };
+        }
+        catch (error) {
+            return { ...base, outcome: "failed", message: error instanceof Error ? error.message : String(error) };
+        }
+    });
+}

package/build/setup/config.js

@@ -0,0 +1,90 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * The settings setup saves, shared by the wizard, prepare and sign-in.
+ */
+import { configStoreExists, loadConfigStore } from "../utils/config-store.js";
+// ── URL validation ─────────────────────────────────────────────────
+export function normalizeUrl(input) {
+    let url = input.trim();
+    // Strip trailing slashes
+    url = url.replace(/\/+$/, "");
+    // Auto-prepend https://
+    if (!/^https?:\/\//i.test(url)) {
+        url = `https://${url}`;
+    }
+    // Upgrade http:// to https://
+    url = url.replace(/^http:\/\//i, "https://");
+    return url;
+}
+export function isValidUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" && !parsed.username && !parsed.password;
+    }
+    catch {
+        return false;
+    }
+}
+/** The settings already on disk, or null when there are none to read. */
+export function readExistingConfig() {
+    try {
+        return configStoreExists() ? loadConfigStore() : null;
+    }
+    catch {
+        // An unreadable config is replaced by the setup values.
+        return null;
+    }
+}
+export function sameSchool(stored, chosen) {
+    // A config that never recorded a school (environment-driven installs) is
+    // not a *different* school, so its settings are still ours to keep.
+    if (!stored)
+        return true;
+    try {
+        return new URL(stored).origin === new URL(chosen).origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Merge the wizard's answers over the settings already saved.
+ *
+ * `saveConfigStore` replaces the whole file, and setup is the documented way
+ * to update a saved password — so it runs again on configurations that carry
+ * settings it never prompts for: the SUNY campus, course filters, a custom
+ * session directory or token TTL. Writing only the answers deleted all of
+ * them; most visibly, a SUNY user who reran plain `setup` lost the campus
+ * that lets sign-in skip the shared campus picker.
+ *
+ * Settings are carried only within one school, since course ids and the
+ * campus belong to a single tenant.
+ */
+export function buildConfigToSave(existing, answers) {
+    const carried = existing && sameSchool(existing.baseUrl, answers.baseUrl) ? existing : null;
+    const config = {
+        ...carried,
+        baseUrl: answers.baseUrl,
+        username: answers.username,
+        // Always the freshly typed one: a carried v1 plaintext password would
+        // otherwise be the value written to the native store.
+        password: answers.password,
+        // Only ever the freshly typed one. Never read back out of `carried`: the
+        // enrollment lives in the credential store, never in config.json, so a
+        // value here could only have come from this run.
+        ...(answers.totpUri ? { totpUri: answers.totpUri } : {}),
+        headless: answers.headless,
+    };
+    if (answers.rememberMfa !== undefined)
+        config.rememberMfa = answers.rememberMfa;
+    // Setup no longer offers passwordless sign-in and always saves a password,
+    // so a carried `passwordless: true` would make sign-in ignore that password.
+    // D2L_PASSWORDLESS still turns it on for anyone who wants it.
+    delete config.passwordless;
+    if (answers.campus)
+        config.campus = answers.campus;
+    return config;
+}