brightspace-mcp-server 3.15.4 → 4.0.1

package/build/setup/prepare.js

@@ -0,0 +1,298 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * `setup --prepare`: every install step an AI agent can do on its own, so the
+ * person is needed only for the last one (their password and sign-in
+ * approval). It never reads stdin, never reads or writes a password, and
+ * never starts a sign-in. Safe to run again: a second run changes nothing.
+ */
+import { spawnSync } from "node:child_process";
+import { nodeVersionSupported, readSavedSessionToken, sessionDirFor } from "../utils/saved-session.js";
+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 { 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";
+import { detectMcpClients, registerAll } from "./clients.js";
+import { presetForBaseUrl } from "./presets.js";
+/**
+ * Whether the native credential store can be used, without unlocking or
+ * reading anything: a keychain read on macOS can pop an "allow access" dialog
+ * and a Linux lookup can ask to unlock the keyring, and prepare must never
+ * stop for the person. The store is really used at sign-in, which says so if
+ * it is locked.
+ */
+export function probeCredentialStore(platform) {
+    if (platform === "darwin")
+        return { ok: true, line: "Passwords will be kept in the macOS Keychain" };
+    if (platform === "win32")
+        return { ok: true, line: "Passwords will be kept in Windows Credential Manager" };
+    if (platform !== "linux")
+        return { ok: false, line: `No supported credential store on ${platform}` };
+    // `search` without --unlock only lists, and stdout is discarded: for an
+    // unlocked item it would include the secret itself.
+    const result = spawnSync("secret-tool", ["search", "--all", "service", "brightspace-mcp-server"], {
+        stdio: ["ignore", "ignore", "ignore"],
+        timeout: 10_000,
+    });
+    if (result.error) {
+        return { ok: false, line: "secret-tool is not installed — install libsecret-tools (Debian/Ubuntu) or your distribution's libsecret tools" };
+    }
+    if (result.status !== 0) {
+        return { ok: false, line: "The Secret Service isn't running — unlock your desktop keyring, then run prepare again" };
+    }
+    return { ok: true, line: "Passwords will be kept in the Secret Service (libsecret)" };
+}
+function defaultPrepareDeps(json) {
+    const progress = json ? (line) => console.error(line) : (line) => console.log(line);
+    return {
+        nodeVersion: process.version,
+        platform: process.platform,
+        env: process.env,
+        readExistingConfig,
+        saveSecureConfig,
+        configPath: getConfigStorePath,
+        probeCredentialStore,
+        discoverVersions,
+        chromiumStatus: () => chromiumStatus(),
+        installChromium: () => installChromium(),
+        detectClients: () => detectMcpClients({ runCommand: runCommandWithoutPrompts, warn: progress }),
+        getSessionToken: (baseUrl, sessionDir) => readSavedSessionToken(baseUrl, sessionDir),
+        progress,
+    };
+}
+/** Key order doesn't matter when deciding whether the saved settings changed. */
+function sameSettings(a, b) {
+    const canonical = (value) => Array.isArray(value)
+        ? value.map(canonical)
+        : value && typeof value === "object"
+            ? Object.fromEntries(Object.entries(value)
+                .filter(([, v]) => v !== undefined)
+                .sort(([x], [y]) => x.localeCompare(y))
+                .map(([k, v]) => [k, canonical(v)]))
+            : value;
+    return a !== null && JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+}
+const ok = (id, line, blocking = true) => ({ id, ok: true, blocking, line: `✓ ${line}` });
+const fail = (id, line, blocking = true) => ({ id, ok: false, blocking, line: `✗ ${line}` });
+function appLine(outcome) {
+    switch (outcome.outcome) {
+        case "added":
+            return ok("app", `${outcome.name}: Brightspace added`, false);
+        case "replaced":
+            return ok("app", `${outcome.name}: old "brightspace" entry replaced`, false);
+        case "current":
+            return ok("app", `${outcome.name}: already set up`, false);
+        case "different_left":
+            return fail("app", `${outcome.name}: "brightspace" already runs ${outcome.current} — left as is (pass --replace to change it)`, false);
+        case "failed":
+            return fail("app", `${outcome.name}: could not register (${outcome.message})`, false);
+    }
+}
+export async function runPrepare(args, overrides = {}) {
+    const deps = { ...defaultPrepareDeps(args.json), ...overrides };
+    const steps = [];
+    // ── Node ──
+    steps.push(nodeVersionSupported(deps.nodeVersion)
+        ? ok("node", `Node.js ${deps.nodeVersion} (20 or newer)`)
+        : fail("node", `Node.js ${deps.nodeVersion} is too old — install Node 20 or newer from https://nodejs.org/`));
+    // ── School ──
+    const existing = deps.readExistingConfig();
+    let baseUrl;
+    let invalidUrl = false;
+    let schoolName;
+    if (args.preset) {
+        baseUrl = args.preset.baseUrl;
+        schoolName = args.preset.name;
+    }
+    else if (args.url) {
+        const normalized = normalizeUrl(args.url);
+        if (isValidUrl(normalized))
+            baseUrl = new URL(normalized).origin;
+        else
+            invalidUrl = true;
+        if (invalidUrl)
+            steps.push(fail("school", `"${args.url}" isn't a valid Brightspace address — pass it like --url purdue.brightspace.com`));
+    }
+    else if (existing?.baseUrl) {
+        baseUrl = existing.baseUrl;
+    }
+    if (baseUrl) {
+        schoolName ??= presetForBaseUrl(baseUrl)?.preset.name;
+        steps.push(ok("school", schoolName ? `School: ${schoolName} (${baseUrl})` : `School: ${baseUrl}`));
+    }
+    else if (!args.url) {
+        steps.push(fail("school", "No school given — pass your school's flag (for example --purdue) or --url <your Brightspace address>"));
+    }
+    // ── Credential store ──
+    const store = deps.probeCredentialStore(deps.platform);
+    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) {
+        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;
+        if (!installed.ok && installed.message)
+            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"));
+    }
+    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"));
+    }
+    // ── Network, settings, session (need a school) ──
+    let signedIn = false;
+    if (baseUrl) {
+        let reachable = true;
+        try {
+            await deps.discoverVersions(baseUrl);
+            steps.push(ok("network", `${baseUrl} is reachable`));
+        }
+        catch {
+            reachable = false;
+            steps.push(fail("network", `Could not reach ${baseUrl} — check the internet connection and the school address`));
+        }
+        const carried = existing && sameSchool(existing.baseUrl, baseUrl) ? existing : null;
+        const username = args.username ?? carried?.username;
+        const campus = args.campus ?? carried?.campus;
+        const config = buildConfigToSave(existing, {
+            baseUrl,
+            username: username ?? "",
+            // No password: the keychain is left exactly as it is.
+            password: undefined,
+            headless: carried?.headless ?? true,
+            rememberMfa: undefined,
+            campus,
+        });
+        if (!username)
+            delete config.username;
+        // Never a secret: the keychain is the person's step, at sign-in.
+        delete config.password;
+        delete config.totpUri;
+        const notes = [];
+        if (carried?.username && args.username && carried.username !== args.username) {
+            notes.push(`was ${carried.username}; sign-in starts fresh for the new account`);
+        }
+        if (!username)
+            notes.push("sign-in will ask for the username");
+        const preset = presetForBaseUrl(baseUrl)?.preset;
+        if (preset?.campusPrompt && !campus)
+            notes.push("sign-in will ask which campus");
+        const noteText = notes.length ? ` (${notes.join("; ")})` : "";
+        if (!reachable) {
+            // A mistyped --url must not replace a working setup: nothing is saved
+            // until the school answers.
+            steps.push(fail("settings", "Settings not saved, because the school couldn't be reached — the saved setup is unchanged"));
+        }
+        else if (existing?.password) {
+            // A password from before v2 still sits in config.json, and loading the
+            // config moves it into the credential store. Rewriting the file here
+            // would drop the only copy, so it is left exactly as it is.
+            steps.push(ok("settings", "Settings left as they are: this computer still has a password from an older version, which the next sign-in moves to the credential store"));
+        }
+        else if (sameSettings(existing, config)) {
+            steps.push(ok("settings", `Settings already saved, no password stored by prepare${noteText}`));
+        }
+        else {
+            try {
+                await deps.saveSecureConfig(config);
+                steps.push(ok("settings", `Settings saved to ${deps.configPath()}, no password${noteText}`));
+            }
+            catch (error) {
+                steps.push(fail("settings", `Could not save settings: ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+        if (username) {
+            try {
+                const token = await deps.getSessionToken(baseUrl, sessionDirFor(deps.env, config, baseUrl, username));
+                signedIn = Boolean(token);
+            }
+            catch {
+                signedIn = false;
+            }
+            steps.push(signedIn
+                ? ok("session", "Already signed in — a saved sign-in still works", false)
+                : ok("session", "Not signed in yet — that's the person's step", false));
+        }
+    }
+    // ── AI apps ──
+    const targets = deps.detectClients().filter((target) => target.detected);
+    const apps = registerAll(targets, { replace: args.replace });
+    steps.push(...apps.map(appLine));
+    if (targets.length === 0) {
+        steps.push(fail("app", "No supported AI app found — register `npx -y brightspace-mcp-server@latest` in your app by hand", false));
+    }
+    const restart = apps.filter((a) => a.outcome === "added" || a.outcome === "replaced").map((a) => a.name);
+    // ── Outcome ──
+    const blocked = steps.some((step) => !step.ok && step.blocking && step.id !== "school");
+    const state = !baseUrl ? "needs_input" : blocked ? "blocked" : signedIn ? "signed_in" : "ready_for_sign_in";
+    const restartText = restart.length ? `Restart ${restart.join(", ")} so it loads the server. ` : "";
+    const next = state === "ready_for_sign_in"
+        ? {
+            command: signInCommand(baseUrl),
+            needsHuman: true,
+            instructions: "Have the person run this in a terminal they can type in, not a background shell. It asks for their " +
+                "password (shown as asterisks) and how they confirm sign-in, then waits for their approval on their phone. " +
+                `It is finished when it prints "Setup complete!". Then run: ${DOCTOR_COMMAND} --json. ${restartText}`.trimEnd(),
+        }
+        : state === "signed_in"
+            ? {
+                command: `${DOCTOR_COMMAND} --json`,
+                needsHuman: false,
+                instructions: `Already signed in. ${restartText}Then ask it a question, such as "What's due this week?"`,
+            }
+            : state === "blocked"
+                ? {
+                    command: prepareCommand(baseUrl),
+                    needsHuman: false,
+                    instructions: "Fix each ✗ step above, then run prepare again.",
+                }
+                : {
+                    needsHuman: true,
+                    instructions: invalidUrl
+                        ? "The address given with --url isn't a valid Brightspace address. Ask the person for the address they open to see their courses, then run prepare again with --url <that address>."
+                        : "Ask the person which school they're at, then run prepare again with its flag (for example --purdue) or --url <their Brightspace address>.",
+                };
+    return {
+        state,
+        ...(baseUrl ? { school: { baseUrl, ...(schoolName ? { name: schoolName } : {}) } } : {}),
+        steps,
+        apps,
+        restart,
+        next,
+    };
+}
+/** The result as a person (or an agent without --json) reads it. */
+export function formatPrepare(result) {
+    const lines = ["", "Brightspace MCP Server — prepare", ""];
+    for (const step of result.steps)
+        lines.push(`  ${step.line}`);
+    lines.push("");
+    if (result.state === "ready_for_sign_in") {
+        lines.push("Ready for sign-in. The last step is for the person, in a terminal:");
+    }
+    else if (result.state === "signed_in") {
+        lines.push("Ready to use.");
+    }
+    else if (result.state === "blocked") {
+        lines.push("Not ready yet.");
+    }
+    else {
+        lines.push("Need the school first.");
+    }
+    if (result.next.command)
+        lines.push(`  ${result.next.command}`);
+    lines.push(`  ${result.next.instructions}`);
+    lines.push("");
+    return lines;
+}

package/build/setup/presets.js

@@ -0,0 +1,91 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+export const SCHOOL_PRESETS = {
+    tudelft: {
+        name: "TU Delft",
+        baseUrl: "https://brightspace.tudelft.nl",
+        usernameLabel: "TU Delft NetID",
+        mfaNote: "NetID sign-in normally runs headlessly without MFA.",
+        usernameHint: "Use your NetID, not your student email address.",
+    },
+    leiden: {
+        name: "Leiden University",
+        baseUrl: "https://brightspace.universiteitleiden.nl",
+        usernameLabel: "Leiden University username",
+        mfaNote: "Leiden usually asks for a code from your authenticator app, which you can type here.",
+        usernameHint: "Use the full address you sign in to Microsoft with, e.g. s1234567@vuw.leidenuniv.nl.",
+    },
+    purdue: {
+        name: "Purdue University",
+        baseUrl: "https://purdue.brightspace.com",
+        usernameLabel: "Purdue career account username or full email",
+        mfaNote: "Microsoft Authenticator number matching can run without a browser window.",
+    },
+    suny: {
+        name: "SUNY",
+        baseUrl: "https://mylearning.suny.edu",
+        usernameLabel: "SUNY campus username",
+        mfaNote: "Approve the sign-in request from your campus MFA app.",
+        campusPrompt: "Which SUNY campus are you at? (e.g. SUNY Poly)",
+        usernameHint: "Most campuses want the full sign-in address, e.g. abc123@sunypoly.edu",
+    },
+    western: {
+        name: "Western University",
+        baseUrl: "https://westernu.brightspace.com",
+        usernameLabel: "Western account username or full email",
+        mfaNote: "Approve the sign-in request from your MFA app.",
+        usernameHint: "Use your full sign-in address if your Western account requires it.",
+    },
+    cuny: {
+        name: "CUNY",
+        baseUrl: "https://brightspace.cuny.edu",
+        usernameLabel: "CUNY Login username",
+        mfaNote: "Type the 6-digit code from your authenticator app when prompted.",
+        usernameHint: "Use your full CUNY Login address, e.g. firstname.lastname01@login.cuny.edu",
+    },
+    ngeeann: {
+        name: "Ngee Ann Polytechnic",
+        baseUrl: "https://nplms.polite.edu.sg",
+        usernameLabel: "Ngee Ann Polytechnic account username or full email",
+        mfaNote: "Approve the sign-in request from your MFA app.",
+        usernameHint: "Use your full sign-in address if your Ngee Ann Polytechnic account requires it.",
+    },
+    mcgill: {
+        name: "McGill University",
+        baseUrl: "https://mycourses2.mcgill.ca",
+        usernameLabel: "McGill username or full email",
+        mfaNote: "Approve the sign-in request from your MFA app.",
+        usernameHint: "Use your full sign-in address if your McGill account requires it.",
+    },
+    javeriana: {
+        name: "Pontificia Universidad Javeriana Cali",
+        baseUrl: "https://auladigital.javerianacali.edu.co",
+        usernameLabel: "Javeriana username",
+        mfaNote: "OneGate asks for a code from your authenticator app when you sign in.",
+    },
+};
+/** The preset whose school runs at `baseUrl`, compared by origin. */
+export function presetForBaseUrl(baseUrl) {
+    let origin;
+    try {
+        origin = new URL(baseUrl).origin;
+    }
+    catch {
+        return undefined;
+    }
+    for (const [flag, preset] of Object.entries(SCHOOL_PRESETS)) {
+        if (new URL(preset.baseUrl).origin === origin)
+            return { flag, preset };
+    }
+    return undefined;
+}
+/** The preset named by `flag` (no leading dashes), own properties only. */
+export function presetForFlag(flag) {
+    const key = flag.toLowerCase();
+    // A bare index would make `--constructor` or `--__proto__` resolve to
+    // something off `Object.prototype` and hand setup an object with no `baseUrl`.
+    return Object.prototype.hasOwnProperty.call(SCHOOL_PRESETS, key) ? SCHOOL_PRESETS[key] : undefined;
+}