brightspace-mcp-server 3.9.17 → 3.9.18

package/README.md

@@ -110,6 +110,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.
 - **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?"
 - **Still stuck?** [Open an issue](https://github.com/RohanMuppa/brightspace-mcp-server/issues) and paste what the terminal printed.

package/build/doctor.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * `doctor` — a beginner-facing diagnostic. It runs a fixed, ordered list of
+ * checks (Node version, saved setup, credential store, school reachability,
+ * saved sign-in, one real API call, installed version) and prints one line
+ * per check: a checkmark plus a short description, or a cross plus exactly
+ * one plain-English next step.
+ *
+ * Every check after "setup found" depends on the ones before it, so a
+ * missing config or a broken sign-in is reported once, with everything
+ * downstream marked "skipped" instead of printing a cascade of confusing
+ * errors for the same root cause.
+ *
+ * Like `setup` and `auth`, this never prints a secret: no password, token,
+ * or cookie value appears in any line.
+ */
+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, expandTilde, readEnvSecret, parseSessionCookieEnv } from "./utils/config.js";
+import { getStoredPassword } from "./auth/credential-store.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";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function readInstalledVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(path.resolve(__dirname, "..", "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        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,
+        platform: process.platform,
+        env: process.env,
+        configStoreExists,
+        loadConfigStore,
+        getStoredPassword,
+        discoverVersions,
+        getSessionToken: (baseUrl, sessionDir, envAccessToken, envSessionCookie) => readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie).getToken(),
+        countCourses: async (baseUrl, sessionDir, envAccessToken, envSessionCookie) => {
+            const apiClient = new D2LApiClient({
+                baseUrl,
+                tokenManager: readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie),
+            });
+            const coursesPath = apiClient.lp("/enrollments/myenrollments/?orgUnitTypeId=3");
+            const response = await apiClient.get(coursesPath);
+            return { count: response?.Items?.length ?? 0, hasMore: Boolean(response?.PagingInfo?.HasMoreItems) };
+        },
+        fetchLatestVersion,
+        installKind: installKindOf(),
+        installedVersion: readInstalledVersion(),
+    };
+}
+function pass(id, message) {
+    return { id, ok: true, line: `✓ ${message}` };
+}
+function problem(id, message) {
+    return { id, ok: false, line: `✗ ${message}` };
+}
+// ── Individual checks ────────────────────────────────────────────────
+function checkNode(deps) {
+    const major = Number(deps.nodeVersion.replace(/^v/, "").split(".")[0]);
+    if (Number.isFinite(major) && major >= 20) {
+        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.`);
+}
+/**
+ * Checks the resolved configuration — config.json AND the same env overrides
+ * loadConfig() honours (D2L_BASE_URL, D2L_USERNAME, D2L_ACCESS_TOKEN,
+ * D2L_SESSION_COOKIE) — since a Docker/headless setup legitimately has no
+ * config.json at all and is configured entirely through the environment.
+ * "Neither config.json nor the environment says anything" is the single most
+ * common first-run state for everyone else.
+ */
+function checkConfig(deps) {
+    let store = null;
+    try {
+        if (deps.configStoreExists())
+            store = deps.loadConfigStore();
+    }
+    catch {
+        store = null;
+    }
+    let envAccessToken;
+    let envSessionCookie;
+    try {
+        envAccessToken = readEnvSecret(deps.env.D2L_ACCESS_TOKEN, "D2L_ACCESS_TOKEN");
+        const rawCookie = readEnvSecret(deps.env.D2L_SESSION_COOKIE, "D2L_SESSION_COOKIE");
+        envSessionCookie = rawCookie ? parseSessionCookieEnv(rawCookie) : undefined;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            result: problem("config", error instanceof Error ? error.message : "D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE is malformed."),
+        };
+    }
+    const rawBaseUrl = deps.env.D2L_BASE_URL || store?.baseUrl;
+    const username = deps.env.D2L_USERNAME || store?.username;
+    const hasEnvCredential = Boolean(envAccessToken || envSessionCookie);
+    // A username is required only for the normal stored-password flow: an env
+    // credential signs in on its own and never needs one.
+    if (!rawBaseUrl || (!username && !hasEnvCredential)) {
+        return { ok: false, result: problem("config", `No setup found — run: ${SETUP_COMMAND}`) };
+    }
+    let baseUrl;
+    try {
+        baseUrl = new URL(rawBaseUrl).origin;
+    }
+    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 label = username ? `signed in as ${username} at ${baseUrl}` : `configured for ${baseUrl} via environment variables`;
+    return {
+        ok: true,
+        result: pass("config", `Setup found — ${label}`),
+        baseUrl,
+        username,
+        sessionDir,
+        envAccessToken,
+        envSessionCookie,
+    };
+}
+async function checkCredential(deps, baseUrl, username, envAccessToken, envSessionCookie) {
+    // Never print the value — only which variable is supplying it.
+    if (envAccessToken)
+        return pass("credential", "Signed in via the D2L_ACCESS_TOKEN environment variable (no password needed)");
+    if (envSessionCookie)
+        return pass("credential", "Signed in via the D2L_SESSION_COOKIE environment variable (no password needed)");
+    if (!username)
+        return problem("credential", `No username configured — run: ${SETUP_COMMAND}`);
+    try {
+        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}`);
+    }
+    catch (error) {
+        // On Linux the store itself (secret-tool / an unlocked Secret Service)
+        // is usually the problem, and the thrown error already explains that in
+        // plain English. Elsewhere, re-running setup is the one fix that covers
+        // every native-store failure a student could hit.
+        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}`);
+    }
+}
+async function checkNetwork(deps, baseUrl) {
+    try {
+        await deps.discoverVersions(baseUrl);
+        return pass("network", `${baseUrl} is reachable`);
+    }
+    catch {
+        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}`;
+    try {
+        const token = await deps.getSessionToken(baseUrl, sessionDir, envAccessToken, envSessionCookie);
+        if (token)
+            return { ok: true, result: pass("session", "Saved sign-in works — a token was issued without opening a browser") };
+        return { ok: false, result: problem("session", failMessage) };
+    }
+    catch {
+        return { ok: false, result: problem("session", failMessage) };
+    }
+}
+/**
+ * Trims an upstream error message down to something safe to show a beginner:
+ * a 403/404 body can be a whole HTML page, and either way the raw text can
+ * carry the endpoint URL. Collapses newlines, drops URLs, and caps length.
+ */
+function sanitizeErrorDetail(message) {
+    const noUrls = message.replace(/https?:\/\/\S+/gi, "");
+    const singleLine = noUrls.replace(/\s+/g, " ").trim();
+    const LIMIT = 120;
+    return singleLine.length > LIMIT ? `${singleLine.slice(0, LIMIT).trimEnd()}…` : singleLine;
+}
+async function checkCourses(deps, baseUrl, sessionDir, envAccessToken, envSessionCookie) {
+    try {
+        const { count, hasMore } = await deps.countCourses(baseUrl, sessionDir, envAccessToken, envSessionCookie);
+        const label = hasMore ? `at least ${count}` : `${count}`;
+        return pass("courses", `Found ${label} course${count === 1 ? "" : "s"} on Brightspace`);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? sanitizeErrorDetail(error.message) : "an unknown error";
+        return problem("courses", `Could not load your courses (${detail}) — run doctor again after checking your connection.`);
+    }
+}
+async function checkVersion(deps) {
+    let latest = null;
+    try {
+        latest = await deps.fetchLatestVersion();
+    }
+    catch {
+        latest = null;
+    }
+    const sourceNote = deps.installKind === "source-checkout" ? " (source checkout)" : "";
+    // Offline, or the registry hiccuped: never treat "couldn't check" as a
+    // failure — there is nothing actionable to tell a student here.
+    if (latest === null) {
+        return pass("version", `Running v${safeVersionLabel(deps.installedVersion)}${sourceNote} — could not check for a newer version (you may be offline)`);
+    }
+    if (!isNewerVersion(latest, deps.installedVersion)) {
+        return pass("version", `Running the latest version (v${safeVersionLabel(deps.installedVersion)})${sourceNote}`);
+    }
+    const from = safeVersionLabel(deps.installedVersion);
+    const to = safeVersionLabel(latest);
+    const nextStep = deps.installKind === "source-checkout"
+        ? "pull the latest changes and run npm run build"
+        : deps.installKind === "npm-install"
+            ? `run: ${GLOBAL_INSTALL_COMMAND}`
+            : `it updates automatically next time, or run: ${CLEAR_NPX_CACHE_COMMAND}`;
+    return problem("version", `A newer version is available (v${from} to v${to}) — ${nextStep}.`);
+}
+// ── Orchestration ────────────────────────────────────────────────────
+/** Human-readable name for each check, used to prefix its "Skipped" line. */
+const CHECK_NAMES = {
+    node: "Node.js version",
+    config: "Setup",
+    credential: "Credential store",
+    network: "Brightspace reachability",
+    session: "Saved sign-in",
+    courses: "Course list",
+    version: "Version",
+};
+const SKIPPED_SETUP = `finish setup first, then run doctor again: ${SETUP_COMMAND}`;
+const SKIPPED_SESSION = "fix the saved sign-in step above first, then run doctor again.";
+function skip(id, reason) {
+    return problem(id, `${CHECK_NAMES[id]}: Skipped — ${reason}`);
+}
+export async function runDoctorChecks(overrides = {}) {
+    const deps = { ...defaultDoctorDeps(), ...overrides };
+    const checks = [];
+    checks.push(checkNode(deps));
+    const config = checkConfig(deps);
+    checks.push(config.result);
+    if (!config.ok) {
+        checks.push(skip("credential", SKIPPED_SETUP));
+        checks.push(skip("network", SKIPPED_SETUP));
+        checks.push(skip("session", SKIPPED_SETUP));
+        checks.push(skip("courses", SKIPPED_SETUP));
+    }
+    else {
+        checks.push(await checkCredential(deps, config.baseUrl, config.username, config.envAccessToken, config.envSessionCookie));
+        checks.push(await checkNetwork(deps, config.baseUrl));
+        const session = await checkSession(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie);
+        checks.push(session.result);
+        if (session.ok) {
+            checks.push(await checkCourses(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie));
+        }
+        else {
+            checks.push(skip("courses", SKIPPED_SESSION));
+        }
+    }
+    checks.push(await checkVersion(deps));
+    return { checks, allOk: checks.every((c) => c.ok) };
+}
+// ── CLI entry point ──────────────────────────────────────────────────
+async function main() {
+    const result = await runDoctorChecks();
+    console.log("");
+    console.log("Brightspace MCP Server — doctor");
+    console.log("");
+    for (const check of result.checks)
+        console.log(`  ${check.line}`);
+    console.log("");
+    console.log(result.allOk
+        ? "Everything looks good — open your AI app and ask a question."
+        : "Fix the ✗ items above, then run doctor again.");
+    console.log("");
+    process.exitCode = result.allOk ? 0 : 1;
+}
+// VITEST is set only by the test runner, which imports this module for the
+// functions above and must never run the real checks against this machine.
+if (!process.env.VITEST) {
+    main().catch((err) => {
+        console.error("doctor failed:", err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    });
+}

package/build/index.js

@@ -37,6 +37,9 @@ if (subcommand === 'setup') {
 else if (subcommand === 'auth') {
     await import('./auth-cli.js');
 }
+else if (subcommand === 'doctor') {
+    await import('./doctor.js');
+}
 else {
     // ── MCP Server (default) ────────────────────────────────────────────
     // CRITICAL: Enable stdout guard IMMEDIATELY to prevent corruption of stdio transport

package/build/setup.js

@@ -15,7 +15,7 @@ import { fileURLToPath } from "node:url";
 import { configStoreExists, getConfigStorePath, loadConfigStore, } from "./utils/config-store.js";
 import { saveSecureConfig } from "./utils/secure-config.js";
 import { writeFileAtomicSync } from "./utils/atomic-write.js";
-import { AUTH_COMMAND } from "./utils/commands.js";
+import { AUTH_COMMAND, DOCTOR_COMMAND } from "./utils/commands.js";
 import { cliMcpClients, configureCliMcpClient, isCliAvailable, } from "./utils/mcp-client-cli.js";
 // ANSI helpers
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -387,11 +387,12 @@ async function main() {
         console.log("");
     }
     else {
+        console.log(dim("  Your school's Brightspace address — the web address you open to see your courses."));
         while (!baseUrl) {
-            const raw = await ask(rl, "What is your Brightspace URL? (e.g., purdue.brightspace.com): ");
+            const raw = await ask(rl, "What is your Brightspace address? (e.g., purdue.brightspace.com): ");
             const normalized = normalizeUrl(raw);
             if (!raw || !isValidUrl(normalized)) {
-                console.log(yellow("  Please enter a valid URL (e.g., purdue.brightspace.com)"));
+                console.log(yellow("  Please enter a valid address, like purdue.brightspace.com"));
                 continue;
             }
             baseUrl = normalized;
@@ -416,10 +417,13 @@ async function main() {
     // ── Step 2: Username ─────────────────────────────────────────────
     const usernamePrompt = preset
         ? `What is your ${preset.usernameLabel}? `
-        : "What is your Brightspace username? ";
+        : "What username do you use to sign in to Brightspace? ";
     if (preset?.usernameHint) {
         console.log(dim(`  ${preset.usernameHint}`));
     }
+    else {
+        console.log(dim("  The same username you type on your school's Brightspace sign-in page."));
+    }
     let username = "";
     while (!username) {
         username = await ask(rl, usernamePrompt);
@@ -431,6 +435,7 @@ async function main() {
     // ── Step 3: Password (hidden) ────────────────────────────────────
     // Close the rl temporarily since askPassword manages its own
     rl.close();
+    console.log(dim("  The password you use to sign in. It won't be shown as you type — asterisks stand in for each character."));
     const passwordPrompt = preset
         ? `What is your ${preset.name} password? `
         : "What is your Brightspace password? ";
@@ -449,20 +454,21 @@ async function main() {
     });
     const configuredClients = [];
     // ── Step 4: MFA info ─────────────────────────────────────────────
+    console.log(dim("  Your school may ask you to approve the sign-in a second way — on your phone, with a code, or something else."));
     if (preset) {
-        console.log(dim(`  MFA: ${preset.mfaNote}`));
+        console.log(dim(`  ${preset.mfaNote}`));
     }
     else {
-        console.log(dim("  MFA: You will be prompted to approve the sign-in on your phone during auth."));
+        console.log(dim("  You'll be prompted to approve the sign-in on your phone during auth."));
     }
     console.log("");
     // Only two outcomes exist: a hidden browser or a visible one. Which kind of
     // MFA you have is detected at sign-in time, so offering "approve a prompt"
     // and "type a code" as separate choices would be a distinction the code does
     // not make, and picking between them would change nothing on disk.
-    console.log("  How do you complete MFA?");
-    console.log("    1. On your phone, or by typing a code here (recommended)");
-    console.log("    2. In a visible browser window");
+    console.log("  When your school asks you to approve the sign-in, how will you do it?");
+    console.log("    1. I approve on my phone, or I type a code from an authenticator app (recommended)");
+    console.log("    2. Something else — open a browser window I can use");
     let savedHeadless;
     try {
         savedHeadless = configStoreExists() ? loadConfigStore().headless : undefined;
@@ -495,23 +501,23 @@ async function main() {
     console.log(green("  Config saved to: " + getConfigStorePath()));
     console.log("");
     // ── Step 6: Authenticate now? ────────────────────────────────────
-    const authNow = await ask(rl2, "Would you like to authenticate now? (yes/no): ");
+    const authNow = await ask(rl2, "Sign in now, so everything is ready to go? (yes/no): ");
     if (/^y(es)?$/i.test(authNow)) {
         rl2.close();
         console.log("");
-        console.log(dim("  Starting authentication..."));
+        console.log(dim("  Signing you in..."));
         console.log("");
         const ok = await runAuth();
         rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
         if (ok) {
-            console.log(green("\n  Authentication successful!"));
+            console.log(green("\n  Signed in!"));
         }
         else {
-            console.log(yellow(`\n  Authentication failed. You can retry later with: ${AUTH_COMMAND}`));
+            console.log(yellow(`\n  Sign-in didn't finish. You can try again later by running: ${AUTH_COMMAND}`));
         }
     }
     else {
-        console.log(dim(`  You can authenticate later by running: ${AUTH_COMMAND}`));
+        console.log(dim(`  You can sign in later by running: ${AUTH_COMMAND}`));
     }
     console.log("");
     // ── Step 7: Claude Desktop auto-config ───────────────────────────
@@ -590,14 +596,16 @@ async function main() {
     console.log("  Next steps:");
     if (configuredClients.length > 0) {
         console.log(`  1. Restart ${configuredClients.join(", ")}`);
-        console.log("  2. Ask your AI client about your Brightspace courses");
+        console.log(`  2. Ask it: "What's due this week?"`);
         console.log("     Sign-in runs automatically if your saved session has expired.");
     }
     else {
         console.log("  1. Register the MCP server in your AI client using the command in README.md");
-        console.log("  2. Restart your AI client and ask about your Brightspace courses");
+        console.log(`  2. Restart your AI client, then ask it: "What's due this week?"`);
     }
     console.log("");
+    console.log(dim(`  If something doesn't work, run: ${DOCTOR_COMMAND}`));
+    console.log("");
 }
 // Both entry points — the `brightspace-setup` bin and `brightspace-mcp-server
 // setup`, which imports this module — start the wizard here. VITEST is set

package/build/utils/commands.js

@@ -19,6 +19,8 @@ export const PACKAGE_NAME = "brightspace-mcp-server";
 export const AUTH_COMMAND = `npx -y ${PACKAGE_NAME}@latest auth`;
 /** Re-run the setup wizard. Always runs the current published release. */
 export const SETUP_COMMAND = `npx -y ${PACKAGE_NAME}@latest setup`;
+/** Diagnose a broken setup. Always runs the current published release. */
+export const DOCTOR_COMMAND = `npx -y ${PACKAGE_NAME}@latest doctor`;
 /** Bring a global install up to date. The only fix for a stale `npm i -g` copy. */
 export const GLOBAL_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}@latest`;
 /** Drop cached npx copies so the next `@latest` genuinely refetches. */

package/build/utils/config.js

@@ -211,7 +211,8 @@ export function parseSessionCookieEnv(raw) {
     }
     throw new Error(SESSION_COOKIE_FORMAT_ERROR);
 }
-function expandTilde(filePath) {
+/** Exported for the `doctor` CLI, which resolves the same session directory without loading the full app config. */
+export function expandTilde(filePath) {
     if (filePath.startsWith("~")) {
         return path.join(os.homedir(), filePath.slice(1));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "3.9.17",
+  "version": "3.9.18",
   "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",