brightspace-mcp-server 5.0.13 → 5.1.4

package/README.md

@@ -107,11 +107,18 @@ All optional, set in your AI app's MCP `env` config or your shell. The full list
 | `D2L_ACTIVE_ONLY=false` | Include courses whose enrollment has ended |
 | `D2L_CURRENT_ONLY=true` | Only show courses in their current enrollment window, like Brightspace's "Current Courses" widget |
 | `D2L_NO_UPDATE_CHECK=1` | Turn off the new-version notice |
+| `D2L_RUNTIME_IDLE_SECONDS` | How long the shared background server waits with no question running before it stops (default 600) |
 | `D2L_DEV_MODE=true` | Write a local, content-free log of tool calls and sign-in events, for debugging session problems ([how](docs/dev-mode.md)) |
 
-## One server for all your chats (optional)
+## One server for all your chats
 
-Normally every chat starts its own copy of the server. With many Codex chats open that is many copies, each roughly 70 MB of memory. Instead you can run **one** copy yourself and point every chat at it by URL. It uses the same saved password, saved session, and sign-in as before; a question that needs a sign-in still signs in once, for every chat.
+Every chat already shares one Brightspace server, with nothing to set up. Each chat still launches the usual command, but that command is now only a small relay: the first question from any chat starts one shared background server for this computer, and every other chat (Claude Desktop, Codex, Cursor, …) uses that same one. That means one sign-in, one saved session, and one cache for all of them. Two chats starting at the same moment still end up with one server. Closing a chat never interrupts another chat's question. After 10 minutes with no question running, the shared server stops by itself, and the next question starts it again.
+
+Chats share a server only when they use the same settings and the same version of this package. A chat started with different `D2L_*` settings, or after an update, gets its own. Because the background server isn't attached to any chat, its log goes to `runtime.log` under `~/.d2l-session/…/shared-runtime/`. Set `D2L_RUNTIME_IDLE_SECONDS` to change how long it waits before stopping.
+
+### Running the shared server yourself (optional)
+
+You can also run **one** copy yourself and point every chat at it by URL. It uses the same saved password, saved session, and sign-in as before; a question that needs a sign-in still signs in once, for every chat.
 
 1. **Make a secret token, once.** Chats must present it, so other programs and web pages can't read your grades. Generate one:
    ```bash
@@ -138,7 +145,7 @@ Things that change:
 - **Stopping it:** press Ctrl+C. Questions already running finish first; press Ctrl+C again to stop at once.
 - **Updating it:** restart the server, not Codex. Restarting a client only reconnects it to the server that is already running the old version. Stop the server and start the same `http` command again with the same `D2L_HTTP_TOKEN`, port, and settings; from a source checkout, run `npm run update` first. Update notices from a shared server say this too.
 
-Any other MCP client that can connect to a Streamable HTTP URL with a bearer token can share the same server. To go back to one copy per chat, put the `command`/`args` entry back (rerun `setup` and say yes when it offers to switch Codex back to its own copy per chat) and stop the shared server.
+Any other MCP client that can connect to a Streamable HTTP URL with a bearer token can share the same server. To go back to the automatic shared server, put the `command`/`args` entry back (rerun `setup` and say yes when it offers to switch Codex back) and stop the server you started.
 
 ## When it asks you to sign in
 
@@ -161,6 +168,7 @@ How often you're asked is up to your school, not this tool. Everything else abou
 - 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).
+- **The app says the server timed out while starting:** open the app's MCP server log. Each startup step prints a timestamped `Startup: ...` line before it begins and `done in N ms` when it ends, and a step still running after 10 seconds prints `Startup: still ...` once. The last such line names the step it was stuck in, often the saved-password lookup in your password store. These lines never include your username, password, or cookies.
 - **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/http-server.js

@@ -101,7 +101,7 @@ function readBody(req) {
  * carry no Origin other than this server's own (a page in a browser always
  * sends one), and present the bearer token.
  */
-export function startHttpServer({ runtime, token, port }) {
+export function startHttpServer({ runtime, token, port, onActiveChange }) {
     const expectedToken = createHash("sha256").update(token).digest();
     const authorized = (header) => {
         const match = /^Bearer[ ]+(\S+)[ ]*$/i.exec(header ?? "");
@@ -157,8 +157,10 @@ export function startHttpServer({ runtime, token, port }) {
     };
     const httpServer = createServer((req, res) => {
         active += 1;
+        onActiveChange?.(active);
         res.once("close", () => {
             active -= 1;
+            onActiveChange?.(active);
             // A keep-alive connection that just finished its last request would
             // otherwise hold a closing server open until it timed out.
             if (closing)

package/build/index.js

@@ -6,14 +6,10 @@
  *
  * https://github.com/rohanmuppa/brightspace-mcp-server
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { enableStdoutGuard, log } from "./utils/logger.js";
 import { guardServerProcess } from "./utils/process-guard.js";
 import { loadConfig } from "./utils/config.js";
-import { setActiveShortcuts } from "./utils/two-factor-shortcuts.js";
-import { startUpdateChecks } from "./utils/update-checker.js";
-import { configureDevActivity } from "./utils/dev-activity.js";
-import { createMcpServer, createRuntime } from "./server.js";
+import { startupPhase } from "./utils/startup-phase.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
@@ -30,7 +26,7 @@ const PKG_VERSION = (() => {
 })();
 // ── Subcommand routing (before any MCP initialization) ──────────────
 const subcommand = process.argv[2];
-const COMMANDS = ['setup', 'auth', 'doctor', 'http'];
+const COMMANDS = ['setup', 'auth', 'doctor', 'http', 'runtime'];
 // A mistyped command (`htp`) must not quietly start a stdio server that sits
 // waiting on stdin. Flags alone still mean the default stdio server.
 if (subcommand !== undefined && !subcommand.startsWith('-') && !COMMANDS.includes(subcommand)) {
@@ -54,23 +50,26 @@ else if (subcommand === 'doctor') {
     await import('./doctor.js');
 }
 else {
-    // ── MCP Server (default: stdio; `http`: one shared localhost server) ──
-    const http = subcommand === 'http';
+    // ── MCP Server ──────────────────────────────────────────────────────
+    // default: stdio, relayed to the one shared runtime, started on demand;
+    // `runtime <dir>`: that shared runtime (started by the default command);
+    // `http`: one shared localhost server the user runs and connects to by URL.
+    const mode = subcommand === 'http' ? 'http' : subcommand === 'runtime' ? 'runtime' : 'stdio';
     // CRITICAL: Enable stdout guard IMMEDIATELY to prevent corruption of stdio transport
     enableStdoutGuard();
     // A stray exception or a closed pipe must not silently drop the client's
     // transport; see guardServerProcess.
-    guardServerProcess(process, !http);
-    /** Set once the HTTP server is listening; shutdown waits on it. */
-    let stopHttp;
+    guardServerProcess(process, mode === 'stdio');
+    /** Set once the HTTP server or shared runtime is listening; shutdown waits on it. */
+    let stopServing;
     async function main() {
         try {
-            // Load configuration
-            const config = await loadConfig();
-            configureDevActivity(config.sessionDir);
-            // Lets the MFA approval message mention the setup options only to users
-            // who have neither turned on. Booleans only; the key is never passed.
-            setActiveShortcuts({ rememberMfa: config.rememberMfa === true, keySaved: Boolean(config.totpUri) });
+            // Announce startup before any await: loading the configuration reads the
+            // OS credential store, which can stall, and a client that times out
+            // needs these timestamped lines to see where. No account details.
+            log("INFO", `Brightspace MCP Server v${PKG_VERSION} starting (Node ${process.version}, ${process.platform}, ${mode})`);
+            // The relay leaves the credential store to the runtime; see loadConfig.
+            const config = await startupPhase("loading configuration", () => loadConfig({ credentials: mode !== "stdio" }));
             log("DEBUG", "Configuration loaded", { sessionDir: config.sessionDir });
             log("INFO", "");
             log("INFO", "========================================");
@@ -79,17 +78,36 @@ else {
             log("INFO", "  github.com/rohanmuppa/brightspace-mcp-server");
             log("INFO", "========================================");
             log("INFO", "");
-            // The one stdio client hears the sign-in's progress lines as logging
-            // messages. The HTTP server has many clients and tells none of them;
-            // see createRuntime.
-            let stdioServer;
-            const runtime = createRuntime(config, PKG_VERSION, http ? undefined : (message) => {
-                void stdioServer?.sendLoggingMessage({ level: "info", logger: "brightspace-auth", data: message }).catch(() => { });
-            });
-            // Check for updates now, then every few hours. A stdio server can stay
-            // alive for days, so a boot-only check would never see a release. The
+            if (mode === 'stdio') {
+                // Every MCP client on this computer that launches this command with
+                // the same settings shares one runtime: one sign-in, one cache, one
+                // rate limiter. The first request starts it; it stops when idle.
+                // Each chat runs one of these, so it loads only the relay, never the
+                // tools, API client or browser code the runtime itself needs.
+                const { runtimeDirectory } = await import("./shared-runtime.js");
+                const { relaySharedRuntime, spawnSharedRuntime, stdioLines } = await import("./runtime-relay.js");
+                const dir = runtimeDirectory(config, PKG_VERSION);
+                await relaySharedRuntime(stdioLines(), { dir, startRuntime: () => spawnSharedRuntime(__filename, dir) });
+                log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio, sharing one Brightspace runtime with this computer's other MCP clients");
+                log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
+                return;
+            }
+            const { configureDevActivity } = await import("./utils/dev-activity.js");
+            const { setActiveShortcuts } = await import("./utils/two-factor-shortcuts.js");
+            const { startUpdateChecks } = await import("./utils/update-checker.js");
+            const { createRuntime } = await import("./server.js");
+            configureDevActivity(config.sessionDir);
+            // Lets the MFA approval message mention the setup options only to users
+            // who have neither turned on. Booleans only; the key is never passed.
+            setActiveShortcuts({ rememberMfa: config.rememberMfa === true, keySaved: Boolean(config.totpUri) });
+            // Both serve many clients, so the sign-in's progress lines go to this
+            // process's log and to none of them; see createRuntime. Each call's MFA
+            // challenge still reaches the client that made the call.
+            const runtime = createRuntime(config, PKG_VERSION);
+            // Check for updates now, then every few hours. A server can stay alive
+            // for days, so a boot-only check would never see a release. The
             // interval is unref'd and cannot hold the process open.
-            startUpdateChecks({ transport: http ? "http" : "stdio" });
+            startUpdateChecks({ transport: mode === "http" ? "http" : "stdio" });
             // Log active course filter config if any filter is set
             if (config.courseFilter.includeCourseIds || config.courseFilter.excludeCourseIds || !config.courseFilter.activeOnly) {
                 log("DEBUG", "Course filter config", {
@@ -98,37 +116,43 @@ else {
                     activeOnly: config.courseFilter.activeOnly,
                 });
             }
-            if (http) {
-                const { resolveHttpPort, resolveHttpToken, startHttpServer } = await import("./http-server.js");
-                const running = await startHttpServer({ runtime, token: resolveHttpToken(), port: resolveHttpPort() });
-                stopHttp = running.close;
-                log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (26 tools, 4 prompts registered)`);
-                log("INFO", "Leave this running; every MCP client on this computer connects to that URL. Press Ctrl+C to stop.");
-                return;
+            if (mode === 'runtime') {
+                const { DEFAULT_IDLE_MS, runtimeDirectory, serveSharedRuntime } = await import("./shared-runtime.js");
+                const idleSeconds = Number(process.env.D2L_RUNTIME_IDLE_SECONDS);
+                const idleMs = Number.isFinite(idleSeconds) && idleSeconds > 0 ? idleSeconds * 1000 : DEFAULT_IDLE_MS;
+                const dir = process.argv[3] ?? runtimeDirectory(config, PKG_VERSION);
+                const shared = await serveSharedRuntime(runtime, { dir, idleMs });
+                if (!shared) {
+                    log("INFO", "Another shared runtime is already serving these settings; exiting");
+                    process.exit(0);
+                }
+                stopServing = shared.stop;
+                log("INFO", `Shared runtime listening on ${shared.address.url} (pid ${process.pid}); stops after ${Math.round(idleMs / 1000)}s idle`);
+                await shared.stopped;
+                process.exit(0);
             }
-            // Connect stdio transport
-            stdioServer = createMcpServer(runtime);
-            const transport = new StdioServerTransport();
-            await stdioServer.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (26 tools, 4 prompts registered)");
-            log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
+            const { resolveHttpPort, resolveHttpToken, startHttpServer } = await import("./http-server.js");
+            const running = await startHttpServer({ runtime, token: resolveHttpToken(), port: resolveHttpPort() });
+            stopServing = running.close;
+            log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (26 tools, 4 prompts registered)`);
+            log("INFO", "Leave this running; every MCP client on this computer connects to that URL. Press Ctrl+C to stop.");
         }
         catch (error) {
             log("ERROR", "MCP Server failed to start", error);
             process.exit(1);
         }
     }
-    // Graceful shutdown. The HTTP server first answers the calls already in
-    // progress (other chats may be mid-call); a second signal stops at once.
+    // Graceful shutdown. A server shared by other chats first answers the
+    // calls already in progress; a second signal stops at once.
     let shuttingDown = false;
     const shutdown = () => {
-        if (shuttingDown || !stopHttp) {
+        if (shuttingDown || !stopServing) {
             log('INFO', 'Shutting down MCP server');
             process.exit(0);
         }
         shuttingDown = true;
         log('INFO', 'Shutting down MCP server after the calls in progress finish (press Ctrl+C again to stop now)');
-        void stopHttp().then(() => process.exit(0));
+        void stopServing().then(() => process.exit(0));
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);

package/build/runtime-relay.js

@@ -0,0 +1,290 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { closeSync, mkdirSync, openSync, readFileSync, statSync, truncateSync } from "node:fs";
+import * as path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { readRuntimeAddress } from "./shared-runtime.js";
+import { log } from "./utils/logger.js";
+import { startupPhase } from "./utils/startup-phase.js";
+/** How long a chat waits for a runtime it started to publish its address. */
+const DEFAULT_START_TIMEOUT_MS = 30_000;
+/** One try, and one more on a runtime started fresh after the first could not be reached. */
+const MAX_ATTEMPTS = 2;
+const RUNTIME_LOG = "runtime.log";
+/** The runtime log is kept across restarts until it grows past this. */
+const MAX_LOG_BYTES = 1024 * 1024;
+/** The request never reached a runtime: try again on a fresh one. */
+class Unreachable extends Error {
+}
+/**
+ * Relay one MCP client's messages to the shared runtime for `dir`, starting
+ * one when none is running or the published one does not answer.
+ *
+ * This is what the default command does on stdio. Nothing starts until the
+ * client's first message, so an editor that launches the server and never
+ * uses it never starts a runtime. Each request is one POST; its reply and the
+ * notifications that belong to it (an MFA challenge's progress) come back on
+ * that POST's stream and go straight to this client and no other. When this
+ * client goes away its requests in progress are dropped, which ends only
+ * those requests in the runtime.
+ */
+export async function relaySharedRuntime(transport, { dir, startRuntime, startTimeoutMs = DEFAULT_START_TIMEOUT_MS }) {
+    const disconnected = new AbortController();
+    let current;
+    let locating;
+    /** The address to use, after `failed` (if given) did not answer. */
+    const locate = (failed) => {
+        if (current && current.token !== failed?.token)
+            return Promise.resolve(current);
+        locating ??= (async () => {
+            const published = await readRuntimeAddress(dir);
+            if (published && published.token !== failed?.token)
+                return published;
+            // A runtime that exits with 0 lost the race to another one, which will
+            // publish; any other exit before an address appears is a failed start.
+            let exited;
+            void startRuntime()?.then((exit) => { exited = exit; });
+            // The runtime logs its own startup to runtime.log, which the client
+            // never sees; these lines put the wait for it in the client's log.
+            return startupPhase("starting the shared runtime", async () => {
+                const deadline = Date.now() + startTimeoutMs;
+                while (Date.now() < deadline && !disconnected.signal.aborted) {
+                    await delay(50);
+                    const started = await readRuntimeAddress(dir);
+                    if (started && started.token !== failed?.token)
+                        return started;
+                    if (exited && exited.code !== 0) {
+                        const why = exited.reason ? `: ${exited.reason.replace(/\.$/, "")}` : ` (exit code ${exited.code})`;
+                        throw new Error(`The shared Brightspace runtime stopped while starting${why}. Its log is ${path.join(dir, RUNTIME_LOG)}.`);
+                    }
+                }
+                throw new Error(`The shared Brightspace runtime did not start within ${Math.round(startTimeoutMs / 1000)}s. ` +
+                    `Its log is ${path.join(dir, RUNTIME_LOG)}.`);
+            });
+        })().then((address) => (current = address)).finally(() => { locating = undefined; });
+        return locating;
+    };
+    const forward = async (message) => {
+        const id = "method" in message && "id" in message ? message.id : undefined;
+        let answered = false;
+        const reply = (out) => {
+            if (id !== undefined && "id" in out && out.id === id && !("method" in out))
+                answered = true;
+            void transport.send(out).catch(() => { });
+        };
+        try {
+            let failed;
+            for (let attempt = 1;; attempt += 1) {
+                const address = await locate(failed);
+                try {
+                    await post(address, message, disconnected.signal, reply);
+                    if (id !== undefined && !answered)
+                        throw new Error("the runtime ended the call without answering it");
+                    return;
+                }
+                catch (error) {
+                    if (!(error instanceof Unreachable) || attempt >= MAX_ATTEMPTS)
+                        throw error;
+                    log("INFO", `Shared runtime did not answer (${error.message}); starting a fresh one`);
+                    failed = address;
+                }
+            }
+        }
+        catch (error) {
+            if (disconnected.signal.aborted)
+                return;
+            log("ERROR", "Relaying to the shared runtime failed", error);
+            if (id !== undefined && !answered)
+                reply(failure(id, error));
+        }
+    };
+    transport.onmessage = (message) => { void forward(message); };
+    transport.onclose = () => disconnected.abort();
+    await transport.start();
+}
+function failure(id, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32603, message: `Could not reach the shared Brightspace runtime: ${reason}` },
+    };
+}
+/**
+ * POST one message and hand every message that comes back to `reply`.
+ * Throws Unreachable when the runtime never took the request: nothing
+ * listening, shutting down (503), or a different runtime now holding the
+ * address (401, a token from a runtime that has since been replaced).
+ */
+async function post(address, message, signal, reply) {
+    let response;
+    try {
+        response = await fetch(address.url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${address.token}`,
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+            },
+            body: JSON.stringify(message),
+            signal,
+        });
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        throw new Unreachable(error instanceof Error ? String(error.cause?.message ?? error.message) : String(error));
+    }
+    if (response.status === 503 || response.status === 401) {
+        await response.body?.cancel();
+        throw new Unreachable(`HTTP ${response.status}`);
+    }
+    if (!response.ok)
+        throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    if (response.status === 202 || !response.body)
+        return;
+    const type = response.headers.get("content-type") ?? "";
+    if (!type.includes("text/event-stream")) {
+        const body = JSON.parse(await response.text());
+        for (const item of Array.isArray(body) ? body : [body])
+            reply(item);
+        return;
+    }
+    const decoder = new TextDecoder();
+    let buffered = "";
+    for await (const chunk of response.body) {
+        buffered += decoder.decode(chunk, { stream: true });
+        const { events, rest } = splitEvents(buffered);
+        buffered = rest;
+        for (const data of events)
+            reply(JSON.parse(data));
+    }
+}
+/**
+ * The complete server-sent events in `buffered`, as the joined text of each
+ * event's `data:` lines, and whatever incomplete event is left over. Events
+ * with no data (comments, priming events) are dropped.
+ */
+function splitEvents(buffered) {
+    const blocks = buffered.split(/\r?\n\r?\n/);
+    const rest = blocks.pop() ?? "";
+    const events = blocks
+        .map((block) => block
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).replace(/^ /, ""))
+        .join("\n"))
+        .filter((data) => data.length > 0);
+    return { events, rest };
+}
+/**
+ * Start `brightspace-mcp-server runtime <dir>` detached, so it outlives the
+ * chat that started it and serves every other one. Its log goes to
+ * runtime.log in `dir`, since no MCP client is listening to its stderr.
+ * Resolves with how it exited if it exits while this chat is still open.
+ */
+export function spawnSharedRuntime(entry, dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const logFile = path.join(dir, RUNTIME_LOG);
+    try {
+        if (statSync(logFile).size > MAX_LOG_BYTES)
+            truncateSync(logFile);
+    }
+    catch {
+        // No log yet.
+    }
+    const logFd = openSync(logFile, "a", 0o600);
+    // Where this run's lines start, so a failure is read from this run only.
+    const offset = statSync(logFile).size;
+    // The runtime outlives the chat that started it, so it runs in its own
+    // directory: Windows will not delete or rename a folder that a live process
+    // is working in, and that chat's project folder would stay locked until the
+    // runtime idled out. The settings it needs, .env included, are already in
+    // this process's environment; a relative session directory is pinned to
+    // where this chat resolved it.
+    const env = { ...process.env };
+    const sessionDir = env.D2L_SESSION_DIR;
+    if (sessionDir && !sessionDir.startsWith("~") && !path.isAbsolute(sessionDir))
+        env.D2L_SESSION_DIR = path.resolve(sessionDir);
+    try {
+        const child = spawn(process.execPath, [entry, "runtime", path.resolve(dir)], {
+            cwd: dir,
+            detached: true,
+            stdio: ["ignore", "ignore", logFd],
+            env,
+            windowsHide: true,
+        });
+        child.once("error", (error) => log("ERROR", "Could not start the shared runtime", error));
+        child.unref();
+        return new Promise((resolve) => {
+            child.once("exit", (code) => {
+                let reason;
+                if (code !== 0) {
+                    try {
+                        reason = startupFailure(readFileSync(logFile).subarray(offset).toString("utf-8"));
+                    }
+                    catch {
+                        // No log to read; the exit code alone is reported.
+                    }
+                }
+                resolve({ code, reason });
+            });
+            child.once("error", () => resolve({ code: null }));
+        });
+    }
+    finally {
+        closeSync(logFd);
+    }
+}
+/**
+ * The relay's side of stdio: one JSON-RPC message per line, as the MCP stdio
+ * transport frames them. The SDK's own transport validates every message
+ * with its schemas, which is the memory the relay exists to save; a line that
+ * is not JSON is dropped, since the runtime would reject it anyway.
+ */
+export function stdioLines(input = process.stdin, output = process.stdout) {
+    const transport = {
+        async start() {
+            const lines = createInterface({ input });
+            lines.on("line", (line) => {
+                if (!line.trim())
+                    return;
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                transport.onmessage?.(message);
+            });
+            lines.once("close", () => transport.onclose?.());
+        },
+        async send(message) {
+            output.write(JSON.stringify(message) + "\n");
+        },
+        async close() {
+            transport.onclose?.();
+        },
+    };
+    return transport;
+}
+/**
+ * The error a runtime logged when it failed to start ("MCP Server failed to
+ * start", in index.ts), without its stack, from the given part of its log.
+ * The logger has already redacted it, as it does every line.
+ */
+export function startupFailure(logText) {
+    const marker = "MCP Server failed to start ";
+    const line = logText.split(/\r?\n/).reverse().find((candidate) => candidate.includes(marker));
+    if (!line)
+        return undefined;
+    const error = line.slice(line.indexOf(marker) + marker.length);
+    const message = /^(.*?)\s+at\s+\S*:\d+:\d+/.exec(error)?.[1] ?? /^(.*?)\s+at\s+\S+\s+\(/.exec(error)?.[1] ?? error;
+    return message.trim().slice(0, 300) || undefined;
+}

package/build/server.js

@@ -19,12 +19,11 @@ import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPl
  * whether or not they ever asked about a course, and a tenant that was
  * briefly unreachable would take the whole server down with it.
  *
- * onAuthProgress receives the sign-in child's progress lines. Over stdio they
- * go to the one client as logging messages; the HTTP server passes none, so
- * they reach only its own log, never a client that did not ask. Each call's
- * MFA challenge still reaches that call's client (see relayMfaChallenges).
+ * The runtime serves many clients, so the sign-in child's progress lines go
+ * only to its own log, never to a client that did not ask. Each call's MFA
+ * challenge still reaches that call's client (see relayMfaChallenges).
  */
-export function createRuntime(config, version, onAuthProgress) {
+export function createRuntime(config, version) {
     const tokenManager = new TokenManager({
         sessionDir: config.sessionDir,
         baseUrl: config.baseUrl,
@@ -41,7 +40,7 @@ export function createRuntime(config, version, onAuthProgress) {
     const envAuthActive = Boolean(config.envAccessToken || config.envSessionCookie);
     const authRunner = envAuthActive
         ? undefined
-        : new AuthRunner({ sessionDir: config.sessionDir, onProgress: onAuthProgress });
+        : new AuthRunner({ sessionDir: config.sessionDir });
     // currentMfaAnnouncer() is read inside the tool call that hit the expired
     // session, so the challenge is announced to that call's client only.
     const apiClient = new D2LApiClient({