brightspace-mcp-server 3.11.12 → 3.11.14

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, Codex, or Claude Code if you have them.
+   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.
 
    **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.

package/build/auth/auth-lock.js

@@ -38,8 +38,15 @@ async function renameThroughContention(from, to) {
     }
     return false;
 }
+/**
+ * The MFA challenge the lock owner's sign-in is showing, published inside the
+ * lock directory so it lives and dies with the lock (see mfa-challenge.ts).
+ */
+export const CHALLENGE_FILE = "challenge.json";
 export class AuthenticationInProgressError extends Error {
     code = "AUTH_IN_PROGRESS";
+    /** The owner's MFA challenge, when the caller looked it up (see BrowserAuth.authenticate). */
+    challenge;
     constructor() {
         super("Authentication already in progress. Retry after the current authentication finishes.");
         this.name = "AuthenticationInProgressError";
@@ -89,6 +96,7 @@ export const lockOps = {
 /** Remove only our fixed metadata names, after the directory was retired. */
 async function cleanRetired(lockPath) {
     await fs.unlink(path.join(lockPath, "owner.json")).catch(() => { });
+    await fs.unlink(path.join(lockPath, CHALLENGE_FILE)).catch(() => { });
     await cleanChild(path.join(lockPath, "reclaim.lock"));
     await fs.rmdir(lockPath).catch(() => { });
 }

package/build/auth/auth-runner.js

@@ -11,6 +11,7 @@ import { AuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 import { devActivity } from "../utils/dev-activity.js";
 import { parsePhaseMarker } from "./auth-phases.js";
+import { authLockPath, challengeRelayedAt } from "./mfa-challenge.js";
 /**
  * Timeout for the auth process. It has to outlast the child's own MFA wait,
  * which is five minutes: a person has to find their phone, unlock it, and read
@@ -41,6 +42,25 @@ const MFA_POLL_MS = 45000;
  * the number in the answer.
  */
 const CALL_BUDGET_MS = 55000;
+/**
+ * How long a background sign-in past its MFA challenge keeps running once
+ * nobody is waiting on it (issue #199). The answer carrying the number can be
+ * cancelled, or held in a parallel batch the user never sees; the child then
+ * kept its browser and the cross-process lock for the whole 5-minute MFA
+ * window, and every server sharing the session was stuck behind it. A user
+ * who did see the number calls again, which polls for another MFA_POLL_MS, so
+ * the same span without any caller (in this process, or relaying the number
+ * from another one) means nobody is approving.
+ */
+const ABANDON_MS = MFA_POLL_MS;
+/**
+ * Milliseconds until a background sign-in counts as abandoned; zero or less
+ * means it already is. A caller still waiting keeps it alive outright;
+ * otherwise the clock runs from the latest moment anyone attended to it.
+ */
+function abandonDelayMs(waiting, attendedAt, now) {
+    return waiting > 0 ? ABANDON_MS : attendedAt + ABANDON_MS - now;
+}
 /** How long to poll after a challenge seen elapsedMs into the call. */
 function pollWindowMs(elapsedMs) {
     return Math.min(MFA_POLL_MS, CALL_BUDGET_MS - elapsedMs);
@@ -179,15 +199,21 @@ export class AuthRunner {
     pendingChallenge = null;
     /** Resolves on the next marker from the current child; null between children. */
     challengeSignal = null;
+    /** Callers inside run() right now. */
+    waiting = 0;
+    /** When the last caller left run(). */
+    lastAttendedAt = 0;
     scriptPath;
     timeoutMs;
     onProgress;
+    sessionDir;
     constructor(options = {}) {
         // Resolve paths relative to this file's compiled location (build/auth/auth-runner.js)
         const thisDir = path.dirname(fileURLToPath(import.meta.url));
         this.scriptPath = path.resolve(thisDir, "..", "auth-cli.js");
         this.timeoutMs = options.timeoutMs ?? AUTH_TIMEOUT_MS;
         this.onProgress = options.onProgress;
+        this.sessionDir = options.sessionDir;
     }
     /**
      * Authenticate, joining the login this process already started if there is
@@ -206,6 +232,16 @@ export class AuthRunner {
      * the next call to join.
      */
     async run(onChallenge) {
+        this.waiting += 1;
+        try {
+            return await this.attend(onChallenge);
+        }
+        finally {
+            this.waiting -= 1;
+            this.lastAttendedAt = Date.now();
+        }
+    }
+    async attend(onChallenge) {
         const startedAt = Date.now();
         try {
             return await withinCallBudget(this.runOnce(startedAt), startedAt);
@@ -333,6 +369,8 @@ export class AuthRunner {
             // against double cleanup.
             let childFinished = false;
             let numberMatch;
+            let challengeSeen = false;
+            let abandonTimer;
             let killTimer;
             const kill = (signal) => {
                 try {
@@ -400,8 +438,30 @@ export class AuthRunner {
             // joinBackgroundChild. Idempotent on the "already known" question, but
             // a later number still overwrites a numberless pendingChallenge so a
             // fresh joiner sees it — see MFA_PENDING_MARKER's own comment.
+            // Once the child is past its challenge, stop it when nobody is waiting
+            // on it any more (see ABANDON_MS). SIGKILL rather than SIGTERM: a
+            // graceful stop runs the MFA loop's failure path, which records the
+            // cooldown, and the user never had a chance to answer. The dead owner
+            // leaves a stale lock the next sign-in reclaims.
+            const watchAttention = () => {
+                if (childFinished)
+                    return;
+                const relayedAt = this.sessionDir ? challengeRelayedAt(authLockPath(this.sessionDir)) ?? 0 : 0;
+                const delayMs = abandonDelayMs(this.waiting, Math.max(this.lastAttendedAt, relayedAt), Date.now());
+                if (delayMs > 0) {
+                    abandonTimer = setTimeout(watchAttention, delayMs);
+                    abandonTimer.unref?.();
+                    return;
+                }
+                log("WARN", "Stopping a background sign-in nobody is waiting on; its MFA prompt went unanswered");
+                kill("SIGKILL");
+                finishChild(new AuthProcessError("timeout", `The sign-in was stopped because nobody approved its MFA prompt. Try again, or run ${AUTH_COMMAND}.`));
+            };
             const publishChallenge = (matched) => {
+                challengeSeen = true;
                 const firstChallenge = this.pendingChallenge === null;
+                if (firstChallenge)
+                    watchAttention();
                 if (firstChallenge)
                     devActivity("mfa_observed", { elapsedMs: Date.now() - started });
                 if (firstChallenge || matched) {
@@ -424,6 +484,8 @@ export class AuthRunner {
                 clearTimeout(timer);
                 if (killTimer)
                     clearTimeout(killTimer);
+                if (abandonTimer)
+                    clearTimeout(abandonTimer);
                 process.off("exit", onExit);
                 const answeredEarly = callerSettled;
                 settleCaller(error);
@@ -500,6 +562,10 @@ export class AuthRunner {
                         6: ["transport", "Brightspace authentication is temporarily unavailable because of a network or server failure. Your saved session was preserved. Try again later."],
                         7: mfaPendingFailure(numberMatch),
                     };
+                    // Busy, but the owning sign-in's challenge came through: the caller
+                    // was told what to approve, so answer with that, not "busy".
+                    if (code === 2 && challengeSeen)
+                        failures[2] = mfaPendingFailure(numberMatch);
                     const [kind, message] = failures[code ?? -1] ?? ["failed", `Authentication failed. Run ${AUTH_COMMAND} to try again.`];
                     kill("SIGKILL");
                     finishChild(new AuthProcessError(kind, message, kind === "mfaPending" ? numberMatch : undefined));

package/build/auth/browser-auth.js

@@ -3,7 +3,6 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT: see LICENSE file for details.
  */
-import * as path from "node:path";
 import { readFileSync, accessSync } from "node:fs";
 import { BrowserAuthError } from "../utils/errors.js";
 import { log } from "../utils/logger.js";
@@ -11,7 +10,8 @@ import { createSSOFlow, UnsupportedAuthenticationError, MfaApprovalError } from
 import { isDuoPrompt } from "./duo-mfa.js";
 import { BrowserStateStore } from "./browser-state-store.js";
 import { hasNewerEntraState, recordMicrosoftSession } from "./microsoft-session.js";
-import { acquireProcessLock } from "./auth-lock.js";
+import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
+import { authLockPath, 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";
@@ -54,12 +54,19 @@ export class BrowserAuth {
     onPhase;
     /** When the current login first reported an MFA challenge; splits credentials from approvalWait. */
     challengeSeenAt;
+    lockPath;
+    /** The latest challenge write, awaited before the lock is released so none lands after it. */
+    publishing = Promise.resolve();
     constructor(config, options = {}) {
         this.config = config;
         this.onPhase = options.onPhase;
         const { onMfaChallenge } = options;
+        this.lockPath = authLockPath(config.sessionDir);
         this.ssoFlow = createSSOFlow(config, options.requestMfaCode, onMfaChallenge && ((number) => {
             this.challengeSeenAt ??= Date.now();
+            // Other server processes sharing this session cannot see our caller's
+            // tool response; the lock directory is where they look instead.
+            this.publishing = this.publishing.then(() => publishChallenge(this.lockPath, number)).catch(() => { });
             onMfaChallenge(number);
         }));
         this.stateStore = new BrowserStateStore(config.sessionDir);
@@ -101,7 +108,13 @@ export class BrowserAuth {
         }
     }
     async authenticate(options = {}) {
-        const release = await acquireProcessLock(path.join(this.config.sessionDir, ".auth.lock"), { mode: options.automatic ? "automatic" : "explicit" });
+        const release = await acquireProcessLock(this.lockPath, { mode: options.automatic ? "automatic" : "explicit" }).catch(async (error) => {
+            // Hand back the number the owner is showing, so this caller's user can
+            // approve that sign-in instead of being told only to wait for it.
+            if (error instanceof AuthenticationInProgressError)
+                error.challenge = await relayChallenge(this.lockPath);
+            throw error;
+        });
         try {
             // Even a cookie-only SAML redirect can issue an MFA push. Suppress all
             // automatic browser attempts during cooldown; HTTP token refresh runs
@@ -114,6 +127,7 @@ export class BrowserAuth {
             return token;
         }
         finally {
+            await this.publishing;
             await release();
         }
     }

package/build/auth/mfa-challenge.js

@@ -0,0 +1,61 @@
+/**
+ * Brightspace MCP Server. Copyright (c) 2026 Rohan Muppa. MIT licensed.
+ *
+ * The MFA challenge a sign-in is showing, shared with every process that
+ * shares its session store (issue #199).
+ *
+ * Several server processes, one per open MCP client, can share one session
+ * directory, and only the one holding the sign-in lock can sign in. The number
+ * to enter used to reach the user only through the one tool call that started
+ * that sign-in. The owner now writes its challenge into the lock directory, so
+ * it disappears with the lock, and a contender reads it back and relays it.
+ * Relaying touches the file, which tells the owner's server that someone is
+ * still waiting on the sign-in (see AuthRunner's abandonment check).
+ */
+import * as fs from "node:fs/promises";
+import { statSync } from "node:fs";
+import * as path from "node:path";
+import { CHALLENGE_FILE } from "./auth-lock.js";
+/** Same bound the auth child's stdout marker enforces: 1-3 digits and nothing else. */
+const NUMBER_MATCH = /^\d{1,3}$/;
+export function authLockPath(sessionDir) {
+    return path.join(sessionDir, ".auth.lock");
+}
+/** Record the challenge this process's sign-in is showing. Call only while holding the lock. */
+export async function publishChallenge(lockPath, numberMatch) {
+    const challenge = numberMatch && NUMBER_MATCH.test(numberMatch) ? { numberMatch } : {};
+    await fs.writeFile(path.join(lockPath, CHALLENGE_FILE), JSON.stringify(challenge), { mode: 0o600 });
+}
+/**
+ * The challenge the lock owner is showing, or undefined when it has published
+ * none. Marks the challenge as just relayed, so the owner keeps waiting.
+ */
+export async function relayChallenge(lockPath) {
+    const file = path.join(lockPath, CHALLENGE_FILE);
+    let challenge;
+    try {
+        challenge = JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof challenge !== "object" || challenge === null)
+        return undefined;
+    const now = new Date();
+    await fs.utimes(file, now, now).catch(() => { });
+    const numberMatch = challenge.numberMatch;
+    return typeof numberMatch === "string" && NUMBER_MATCH.test(numberMatch) ? { numberMatch } : {};
+}
+/** When the lock's challenge was last published or relayed, or undefined when there is none. */
+export function challengeRelayedAt(lockPath) {
+    try {
+        return statSync(path.join(lockPath, CHALLENGE_FILE)).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The stdout marker AuthRunner parses for a challenge. */
+export function challengeMarker(numberMatch) {
+    return numberMatch ? `MFA_NUMBER:${numberMatch}` : "MFA_PENDING";
+}

package/build/auth-cli.js

@@ -11,6 +11,8 @@ import { MfaApprovalError } from "./auth/sso-flow.js";
 import { NativeCredentialStoreError } from "./auth/credential-store.js";
 import { retireLegacyProfile } from "./auth/legacy-profile.js";
 import { formatPhaseMarker } from "./auth/auth-phases.js";
+import { AuthenticationInProgressError } from "./auth/auth-lock.js";
+import { challengeMarker } from "./auth/mfa-challenge.js";
 import { AUTH_COMMAND, SETUP_COMMAND } from "./utils/commands.js";
 import { initUpdateChecker, peekUpdateNotice } from "./utils/update-checker.js";
 import { reexecLatestIfStale } from "./utils/self-update.js";
@@ -62,7 +64,7 @@ async function main() {
         // seconds instead of waiting out the whole approval window. Stdout only
         // — the parent parses stdout for structured markers, never stderr.
         const onMfaChallenge = automatic
-            ? (number) => console.log(number ? `MFA_NUMBER:${number}` : "MFA_PENDING")
+            ? (number) => console.log(challengeMarker(number))
             : undefined;
         // Stage timings for the server's dev activity log, same stdout channel.
         const onPhase = automatic
@@ -88,7 +90,12 @@ async function main() {
         // where they were scraped — can cross the process boundary as data
         // rather than free-form text.
         if (error instanceof MfaApprovalError && error.numberMatch) {
-            console.log(`MFA_NUMBER:${error.numberMatch}`);
+            console.log(challengeMarker(error.numberMatch));
+        }
+        // Another process's sign-in holds the lock and is showing a challenge:
+        // pass it on, so this caller can tell its user what to approve.
+        if (automatic && error instanceof AuthenticationInProgressError && error.challenge) {
+            console.log(challengeMarker(error.challenge.numberMatch));
         }
         process.exitCode = error instanceof NativeCredentialStoreError ? 5
             : code === "AUTH_IN_PROGRESS" ? 2

package/build/index.js

@@ -86,6 +86,7 @@ else {
             const authRunner = envAuthActive
                 ? undefined
                 : new AuthRunner({
+                    sessionDir: config.sessionDir,
                     onProgress: (message) => {
                         void server.sendLoggingMessage({ level: "info", logger: "brightspace-auth", data: message }).catch(() => { });
                     },

package/build/setup.js

@@ -16,7 +16,7 @@ import { configStoreExists, getConfigStorePath, loadConfigStore, } from "./utils
 import { saveSecureConfig } from "./utils/secure-config.js";
 import { writeFileAtomicSync } from "./utils/atomic-write.js";
 import { AUTH_COMMAND, DOCTOR_COMMAND } from "./utils/commands.js";
-import { cliMcpClients, configureCliMcpClient, isCliAvailable, } from "./utils/mcp-client-cli.js";
+import { classifyRegistration, cliMcpClients, inspectCliMcpClient, isCliAvailable, registerCliMcpClient, serverCommand, } from "./utils/mcp-client-cli.js";
 // ANSI helpers
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
@@ -240,6 +240,9 @@ function isChatGPTInstalled() {
 function getCursorConfigPath() {
     return path.join(os.homedir(), ".cursor", "mcp.json");
 }
+function getAntigravityConfigPath() {
+    return path.join(os.homedir(), ".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
@@ -248,6 +251,19 @@ function getCursorConfigPath() {
 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) {
     let config = {};
     // Read existing config if present
@@ -276,17 +292,8 @@ export function configureMcpClient(configPath) {
     const servers = isJsonObject(config.mcpServers) ? config.mcpServers : {};
     config.mcpServers = servers;
     // Add/update brightspace entry
-    // On Windows, npx is a .cmd shim that must be invoked through cmd.exe
-    const isWindows = process.platform === "win32";
-    servers["brightspace"] = isWindows
-        ? {
-            command: "cmd",
-            args: ["/c", "npx", "-y", "brightspace-mcp-server@latest"],
-        }
-        : {
-            command: "npx",
-            args: ["-y", "brightspace-mcp-server@latest"],
-        };
+    const [command, ...args] = serverCommand();
+    servers["brightspace"] = { command, args };
     // Ensure parent directory exists
     const dir = path.dirname(configPath);
     if (!fs.existsSync(dir)) {
@@ -362,6 +369,38 @@ export function buildConfigToSave(existing, answers) {
     return config;
 }
 // ── Auth spawn ─────────────────────────────────────────────────────
+/**
+ * Registers Brightspace in one client, never silently replacing an entry
+ * that points somewhere else: a matching entry is left alone, and a different
+ * one is printed (so it can be restored) and replaced only on a yes.
+ * Resolves true when the client ends up running the expected entry.
+ */
+async function registerWithClient(rl, displayName, existing, write) {
+    if (existing.state === "current") {
+        console.log(green(`  ${displayName} already has Brightspace configured.`));
+        return true;
+    }
+    if (existing.state === "different") {
+        console.log(yellow(`  ${displayName} has "brightspace" pointing at:`));
+        console.log(`    ${existing.current}`);
+        const replace = await ask(rl, `  Replace it with ${serverCommand().join(" ")}? (yes/no): `);
+        if (!/^y(es)?$/i.test(replace)) {
+            console.log(dim(`  Left ${displayName} unchanged.`));
+            return false;
+        }
+    }
+    try {
+        if (write(existing.state === "different")) {
+            console.log(green(`  ${displayName} configured!`));
+            return true;
+        }
+        console.log(yellow(`  Could not configure ${displayName}. See README.md for the manual command.`));
+    }
+    catch (err) {
+        console.log(yellow(`  Could not configure ${displayName}: ${err instanceof Error ? err.message : String(err)}`));
+    }
+    return false;
+}
 function runAuth() {
     const scriptPath = path.resolve(thisDir, "auth-cli.js");
     return new Promise((resolve) => {
@@ -557,15 +596,9 @@ async function main() {
     const claudePath = getClaudeDesktopConfigPath();
     if (claudePath) {
         const configClaude = await ask(rl2, "Would you like to automatically configure Claude Desktop? (yes/no): ");
-        if (/^y(es)?$/i.test(configClaude)) {
-            try {
-                configureMcpClient(claudePath);
-                configuredClients.push("Claude Desktop");
-                console.log(green("  Claude Desktop configured! Restart Claude Desktop to connect."));
-            }
-            catch (err) {
-                console.log(yellow(`  Could not configure Claude Desktop: ${err instanceof Error ? err.message : String(err)}`));
-            }
+        if (/^y(es)?$/i.test(configClaude) &&
+            await registerWithClient(rl2, "Claude Desktop", inspectMcpClient(claudePath), () => configureMcpClient(claudePath))) {
+            configuredClients.push("Claude Desktop");
         }
         console.log("");
     }
@@ -574,15 +607,19 @@ async function main() {
     const cursorExists = fs.existsSync(path.dirname(cursorPath));
     if (cursorExists) {
         const configCursor = await ask(rl2, "Cursor detected. Would you like to configure it too? (yes/no): ");
-        if (/^y(es)?$/i.test(configCursor)) {
-            try {
-                configureMcpClient(cursorPath);
-                configuredClients.push("Cursor");
-                console.log(green("  Cursor configured! Restart Cursor to connect."));
-            }
-            catch (err) {
-                console.log(yellow(`  Could not configure Cursor: ${err instanceof Error ? err.message : String(err)}`));
-            }
+        if (/^y(es)?$/i.test(configCursor) &&
+            await registerWithClient(rl2, "Cursor", inspectMcpClient(cursorPath), () => configureMcpClient(cursorPath))) {
+            configuredClients.push("Cursor");
+        }
+        console.log("");
+    }
+    // ── Antigravity auto-config ──────────────────────────────────────
+    const antigravityPath = getAntigravityConfigPath();
+    if (fs.existsSync(path.dirname(antigravityPath))) {
+        const configAntigravity = await ask(rl2, "Antigravity detected. Would you like to configure it too? (yes/no): ");
+        if (/^y(es)?$/i.test(configAntigravity) &&
+            await registerWithClient(rl2, "Antigravity", inspectMcpClient(antigravityPath), () => configureMcpClient(antigravityPath))) {
+            configuredClients.push("Antigravity");
         }
         console.log("");
     }
@@ -591,18 +628,9 @@ async function main() {
         if (!isCliAvailable(client))
             continue;
         const configureClient = await ask(rl2, `${client.displayName} detected. Configure it automatically? (yes/no): `);
-        if (/^y(es)?$/i.test(configureClient)) {
-            const result = configureCliMcpClient(client);
-            if (result === "failed") {
-                console.log(yellow(`  Could not configure ${client.displayName}. See README.md for the manual command.`));
-            }
-            else {
-                configuredClients.push(client.displayName);
-                const message = result === "already-configured"
-                    ? `  ${client.displayName} already has Brightspace configured.`
-                    : `  ${client.displayName} configured!`;
-                console.log(green(message));
-            }
+        if (/^y(es)?$/i.test(configureClient) &&
+            await registerWithClient(rl2, client.displayName, inspectCliMcpClient(client), (replace) => registerCliMcpClient(client, { replace }))) {
+            configuredClients.push(client.displayName);
         }
         console.log("");
     }

package/build/tools/tool-helpers.js

@@ -82,6 +82,13 @@ export function errorResponse(message) {
  * nothing is derived from the caught message, so a child process cannot put
  * words in the response. The full error still goes to the log.
  */
+/**
+ * Issue #199: a client running calls in a parallel batch can hold the answer
+ * carrying the number until the whole batch finishes, and the user never sees
+ * it in time. Ask the model to relay it on its own and call one tool at a time.
+ */
+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 = {
     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.`,
@@ -101,7 +108,8 @@ const AUTH_FAILURE_GUIDANCE = {
     mfaPending: "Approve the sign-in request on your phone (Microsoft Authenticator or Duo). " +
         "Tell the user that, then call this tool again right away without waiting for them to " +
         "confirm: each call waits up to 45 seconds for the approval and returns the result as soon " +
-        "as the sign-in completes. Keep calling until it succeeds or reports a different error.",
+        "as the sign-in completes. Keep calling until it succeeds or reports a different error. " +
+        MFA_SOLO_CALL,
     inProgress: "Brightspace sign-in is still starting in the background (opening the browser and the " +
         "school's login pages). Call this tool again right away: the next call joins the same " +
         "sign-in, so it sends no second MFA prompt, and returns the number to approve as soon as " +
@@ -119,7 +127,8 @@ function authFailureMessage(error) {
         return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes. ` +
             "Tell the user that number, then call this tool again right away without waiting for them " +
             "to confirm: each call waits up to 45 seconds for the approval and returns the result as " +
-            "soon as the sign-in completes. Keep calling until it succeeds or reports a different error.";
+            "soon as the sign-in completes. Keep calling until it succeeds or reports a different error. " +
+            MFA_SOLO_CALL;
     }
     return AUTH_FAILURE_GUIDANCE[error.kind];
 }

package/build/utils/mcp-client-cli.js

@@ -1,41 +1,111 @@
 import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { PACKAGE_NAME } from "./commands.js";
 function defaultRunCommand(command, args, stdio) {
     const result = spawnSync(command, args, {
-        stdio,
+        stdio: stdio === "pipe" ? ["ignore", "pipe", "ignore"] : stdio,
+        encoding: "utf-8",
         shell: process.platform === "win32",
     });
-    return result.error ? null : result.status;
+    return { status: result.error ? null : result.status, stdout: result.stdout ?? "" };
 }
-export function cliMcpClients(platform = process.platform) {
-    const serverCommand = platform === "win32"
+/** The command every client is registered with. */
+export function serverCommand(platform = process.platform) {
+    // On Windows, npx is a .cmd shim that must be invoked through cmd.exe
+    return platform === "win32"
         ? ["cmd", "/c", "npx", "-y", `${PACKAGE_NAME}@latest`]
         : ["npx", "-y", `${PACKAGE_NAME}@latest`];
+}
+export function classifyRegistration(entry, platform = process.platform) {
+    if (entry === undefined)
+        return { state: "missing" };
+    if (entry === null || typeof entry !== "object") {
+        return { state: "different", current: "(an entry setup could not read)" };
+    }
+    const { command, args } = entry;
+    if (typeof command !== "string") {
+        return { state: "different", current: JSON.stringify(entry) };
+    }
+    const argv = [command, ...(Array.isArray(args) ? args.map(String) : [])];
+    const expected = serverCommand(platform);
+    if (argv.length === expected.length && argv.every((part, i) => part === expected[i])) {
+        return { state: "current" };
+    }
+    return { state: "different", current: argv.join(" ") };
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Codex keeps one global registry; `--json` exposes the entry's command. */
+function readCodexEntry(runCommand) {
+    const lookup = runCommand("codex", ["mcp", "get", "brightspace", "--json"], "pipe");
+    if (lookup.status === 0) {
+        try {
+            const parsed = JSON.parse(lookup.stdout);
+            return parsed.transport ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // A Codex too old for `--json` still answers the plain lookup.
+    return runCommand("codex", ["mcp", "get", "brightspace"], "ignore").status === 0
+        ? null
+        : undefined;
+}
+/**
+ * Claude Code's `mcp get` resolves local, then project, then user scope from
+ * the current directory, so a project's `.mcp.json` can answer for a user
+ * registration that doesn't exist. Setup registers at user scope, which lives
+ * in the top-level `mcpServers` of `.claude.json`; read that directly.
+ */
+function readClaudeCodeEntry() {
+    const configDir = process.env.CLAUDE_CONFIG_DIR || os.homedir();
+    const config = readJsonFile(path.join(configDir, ".claude.json"));
+    const servers = config?.mcpServers;
+    return servers && typeof servers === "object" ? servers.brightspace : undefined;
+}
+export function cliMcpClients(platform = process.platform) {
+    const command = serverCommand(platform);
     return [
         {
             id: "codex",
             displayName: "Codex Desktop and CLI",
             command: "codex",
-            getArgs: ["mcp", "get", "brightspace"],
-            addArgs: ["mcp", "add", "brightspace", "--", ...serverCommand],
+            addArgs: ["mcp", "add", "brightspace", "--", ...command],
+            removeArgs: ["mcp", "remove", "brightspace"],
+            readEntry: readCodexEntry,
         },
         {
             id: "claude-code",
             displayName: "Claude Code",
             command: "claude",
-            getArgs: ["mcp", "get", "brightspace"],
-            addArgs: ["mcp", "add", "--scope", "user", "brightspace", "--", ...serverCommand],
+            addArgs: ["mcp", "add", "--scope", "user", "brightspace", "--", ...command],
+            removeArgs: ["mcp", "remove", "--scope", "user", "brightspace"],
+            readEntry: readClaudeCodeEntry,
         },
     ];
 }
 export function isCliAvailable(client, runCommand = defaultRunCommand) {
-    return runCommand(client.command, ["--version"], "ignore") === 0;
+    return runCommand(client.command, ["--version"], "ignore").status === 0;
+}
+export function inspectCliMcpClient(client, runCommand = defaultRunCommand) {
+    return classifyRegistration(client.readEntry(runCommand));
 }
-export function configureCliMcpClient(client, runCommand = defaultRunCommand) {
-    if (runCommand(client.command, client.getArgs, "ignore") === 0) {
-        return "already-configured";
+/**
+ * Writes the expected entry. With `replace`, the existing one is removed
+ * first, since `claude mcp add` refuses a name that is already taken.
+ */
+export function registerCliMcpClient(client, { replace }, runCommand = defaultRunCommand) {
+    if (replace && runCommand(client.command, client.removeArgs, "inherit").status !== 0) {
+        return false;
     }
-    return runCommand(client.command, client.addArgs, "inherit") === 0
-        ? "configured"
-        : "failed";
+    return runCommand(client.command, client.addArgs, "inherit").status === 0;
 }

package/package.json

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