brightspace-mcp-server 4.0.7 → 5.0.0

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/brightspace-mcp-server.svg)](https://www.npmjs.com/package/brightspace-mcp-server)
 [![CI](https://img.shields.io/github/actions/workflow/status/RohanMuppa/brightspace-mcp-server/ci.yml?branch=main)](https://github.com/RohanMuppa/brightspace-mcp-server/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/github/license/RohanMuppa/brightspace-mcp-server.svg)](LICENSE)
-[![Node >= 20](https://img.shields.io/node/v/brightspace-mcp-server.svg)](package.json)
+[![Node >= 22](https://img.shields.io/node/v/brightspace-mcp-server.svg)](package.json)
 
 > **By [Rohan Muppa](https://github.com/rohanmuppa), ECE @ Purdue**
 
@@ -20,7 +20,7 @@ Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, and a
 
 ## Get started in 3 steps
 
-1. **Install [Node.js](https://nodejs.org/)** (version 20 or newer) if you don't have it. Download, run the installer, done.
+1. **Install [Node.js](https://nodejs.org/)** (version 22 or newer) if you don't have it. Download, run the installer, done.
 2. **Open a terminal and run the setup:**
    ```bash
    npx -y brightspace-mcp-server@latest setup
@@ -109,6 +109,36 @@ All optional, set in your AI app's MCP `env` config or your shell. The full list
 | `D2L_NO_UPDATE_CHECK=1` | Turn off the new-version notice |
 | `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)
+
+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.
+
+1. **Make a secret token, once.** Chats must present it, so other programs and web pages can't read your grades. Generate one:
+   ```bash
+   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+   ```
+   Save it as a user environment variable named `D2L_HTTP_TOKEN`, where both the server and Codex can see it. On Windows: Start → "Edit environment variables for your account" → New, paste it as the value (apps and terminals opened afterwards see it). On macOS or Linux: add `export D2L_HTTP_TOKEN=<token>` to your shell profile (`~/.zshrc`, `~/.bashrc`); a Codex app launched from the Dock or a desktop menu may not read that profile, so start it from a terminal. The server never prints the token.
+2. **Start the server and leave it running** in a terminal of its own:
+   ```bash
+   npx -y brightspace-mcp-server@latest http
+   ```
+   This needs a release with HTTP support; to try it from a source checkout first, run `npm run build`, then `node build/index.js http`. It listens on `http://127.0.0.1:18765/mcp`, on this computer only. Pick another port with `--port 18766` or `D2L_HTTP_PORT`, and use that same port in the URL in step 3. Start it once per login: chats do not start it, and a second copy on the same port stops at once with "already in use" rather than running alongside the first. Nothing signs in at startup.
+3. **Point Codex at it.** In `~/.codex/config.toml`, replace the `command` and `args` lines of your `[mcp_servers.brightspace]` entry with:
+   ```toml
+   [mcp_servers.brightspace]
+   url = "http://127.0.0.1:18765/mcp"
+   bearer_token_env_var = "D2L_HTTP_TOKEN"
+   ```
+   (`env_http_headers = { "Authorization" = "D2L_HTTP_AUTHORIZATION" }` also works, if that variable holds `Bearer <token>`.) A project's own `.codex/config.toml` overrides this one, so remove any `brightspace` entry there or change it the same way. If you rerun `setup` later, say no when it offers to replace the Codex entry.
+4. **Restart Codex.** Chats that were already open keep the old per-chat server until Codex restarts. If you stop or restart the shared server, calls fail until it is back; if they still fail after that, start a new chat or restart Codex.
+
+Things that change:
+- **Settings go to the server, not to Codex.** A URL entry has no process to pass an `env` table to, so `D2L_*` settings (the [table above](#settings-you-might-want)) are set in the terminal that runs `http`, in a `.env` file in the directory you start it from, or saved by `setup`.
+- **Sign-in messages show up in the server's terminal.** The number to approve still comes back in the chat's answer, and, in clients that show tool progress, while the question is running.
+- **Stopping it:** press Ctrl+C. Questions already running finish first; press Ctrl+C again to stop at once.
+
+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 (rerunning `setup` does it) and stop the shared server.
+
 ## When it asks you to sign in
 
 There's no separate login — asking a question signs you in, and it stays signed in on its own most days. When your school wants two-factor again, the number to approve shows up right in the answer; approve it on your phone and the assistant keeps checking on its own — each check waits up to 45 seconds and the original question completes as soon as the sign-in does, without you having to say you've approved it. If your AI client shows tool progress messages, the number appears while the question is still running instead. If it ever gets stuck, run this in a terminal:

package/build/doctor.js

@@ -79,9 +79,9 @@ function problem(id, message) {
 // ── Individual checks ────────────────────────────────────────────────
 function checkNode(deps) {
     if (nodeVersionSupported(deps.nodeVersion)) {
-        return pass("node", `Node.js ${deps.nodeVersion} (20 or newer)`);
+        return pass("node", `Node.js ${deps.nodeVersion} (22 or newer)`);
     }
-    return problem("node", `Node.js ${deps.nodeVersion} is too old — install Node 20 or newer from https://nodejs.org/, then try again.`);
+    return problem("node", `Node.js ${deps.nodeVersion} is too old — install Node 22 or newer from https://nodejs.org/, then try again.`);
 }
 /**
  * Checks the resolved configuration — config.json AND the same env overrides

package/build/http-server.js

@@ -0,0 +1,198 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { createServer } from "node:http";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpServer } from "./server.js";
+import { readEnvSecret } from "./utils/config.js";
+import { log } from "./utils/logger.js";
+/** The only address the shared server listens on. Never a LAN interface. */
+export const HTTP_HOST = "127.0.0.1";
+export const DEFAULT_HTTP_PORT = 18765;
+export const MCP_PATH = "/mcp";
+/** A tools/call body is a few hundred bytes; this leaves ample room. */
+export const MAX_BODY_BYTES = 1024 * 1024;
+/** 32 characters of hex is 128 bits, which no one guesses. */
+export const MIN_TOKEN_LENGTH = 32;
+const TOKEN_HINT = `Set D2L_HTTP_TOKEN to a random secret of at least ${MIN_TOKEN_LENGTH} characters, for example the output of ` +
+    `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`;
+/**
+ * The bearer token every request must carry. Required: this server answers
+ * with private grades and rosters, and any local program (or web page that
+ * got past the Host and Origin checks) could otherwise read them.
+ */
+export function resolveHttpToken(env = process.env) {
+    const token = readEnvSecret(env.D2L_HTTP_TOKEN, "D2L_HTTP_TOKEN");
+    if (!token)
+        throw new Error(`D2L_HTTP_TOKEN is not set. ${TOKEN_HINT}`);
+    if (token.length < MIN_TOKEN_LENGTH)
+        throw new Error(`D2L_HTTP_TOKEN is too short. ${TOKEN_HINT}`);
+    return token;
+}
+/** `--port N` or `--port=N`, then D2L_HTTP_PORT, then the default. */
+export function resolveHttpPort(argv = process.argv, env = process.env) {
+    let raw;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--port")
+            raw = argv[i + 1] ?? "";
+        else if (argv[i].startsWith("--port="))
+            raw = argv[i].slice("--port=".length);
+    }
+    raw ??= env.D2L_HTTP_PORT || undefined;
+    if (raw === undefined)
+        return DEFAULT_HTTP_PORT;
+    const port = /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : NaN;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid port ${JSON.stringify(raw)}: expected a whole number from 1 to 65535.`);
+    }
+    return port;
+}
+function sendError(res, status, message, headers = {}) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    res.writeHead(status, { "Content-Type": "application/json", ...headers });
+    res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: status === 400 ? -32700 : -32000, message }, id: null }));
+}
+class BodyTooLarge extends Error {
+}
+/** The request body, refusing anything over MAX_BODY_BYTES as it arrives. */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const declared = Number(req.headers["content-length"]);
+        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+            reject(new BodyTooLarge());
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        const onData = (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                req.off("data", onData);
+                reject(new BodyTooLarge());
+                return;
+            }
+            chunks.push(chunk);
+        };
+        req.on("data", onData);
+        req.once("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.once("error", reject);
+    });
+}
+/**
+ * Serve MCP over Streamable HTTP on 127.0.0.1, for every client on this
+ * computer at once.
+ *
+ * Each POST gets its own McpServer and stateless transport, as the SDK
+ * requires (a stateless transport refuses a second request), but they all
+ * share the one runtime: the saved session, the single sign-in, and the API
+ * cache and rate limiter. There are no MCP sessions to track. GET (a
+ * standalone notification stream) and DELETE (ending a session) have nothing
+ * to do in stateless mode and answer 405, which clients treat as "not
+ * offered".
+ *
+ * Before any MCP handling, a request must name this server in Host (a web
+ * page reaching 127.0.0.1 through DNS rebinding carries its own host name),
+ * 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 }) {
+    const expectedToken = createHash("sha256").update(token).digest();
+    const authorized = (header) => {
+        const match = /^Bearer[ ]+(\S+)[ ]*$/i.exec(header ?? "");
+        return match !== null && timingSafeEqual(createHash("sha256").update(match[1]).digest(), expectedToken);
+    };
+    let allowedHosts = new Set();
+    let allowedOrigins = new Set();
+    let closing = false;
+    let active = 0;
+    const handle = async (req, res) => {
+        if (!allowedHosts.has(req.headers.host ?? ""))
+            return sendError(res, 403, "Forbidden: unexpected Host header");
+        const origin = req.headers.origin;
+        if (origin !== undefined && !allowedOrigins.has(origin))
+            return sendError(res, 403, "Forbidden: unexpected Origin header");
+        const path = (req.url ?? "").split("?")[0];
+        if (path !== MCP_PATH)
+            return sendError(res, 404, "Not found");
+        if (!authorized(req.headers.authorization)) {
+            return sendError(res, 401, "Unauthorized: missing or wrong bearer token", { "WWW-Authenticate": "Bearer" });
+        }
+        if (req.method !== "POST")
+            return sendError(res, 405, "Method not allowed", { Allow: "POST" });
+        if (closing)
+            return sendError(res, 503, "The server is shutting down", { Connection: "close" });
+        const contentType = (req.headers["content-type"] ?? "").split(";")[0].trim().toLowerCase();
+        if (contentType !== "application/json")
+            return sendError(res, 415, "Unsupported Media Type: expected application/json");
+        let body;
+        try {
+            body = JSON.parse(await readBody(req));
+        }
+        catch (error) {
+            if (error instanceof BodyTooLarge) {
+                // Discard the rest without buffering it. Closing the socket on unread
+                // data would reset it before the client reads the 413. Only a client
+                // holding the token gets this far, and Node's request timeout bounds
+                // a body that never ends.
+                req.removeAllListeners("data");
+                req.resume();
+                return sendError(res, 413, `Request body exceeds ${MAX_BODY_BYTES} bytes`);
+            }
+            return sendError(res, 400, "Parse error: the body is not valid JSON");
+        }
+        const server = createMcpServer(runtime);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.once("close", () => {
+            void transport.close().catch(() => { });
+            void server.close().catch(() => { });
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    };
+    const httpServer = createServer((req, res) => {
+        active += 1;
+        res.once("close", () => {
+            active -= 1;
+            // A keep-alive connection that just finished its last request would
+            // otherwise hold a closing server open until it timed out.
+            if (closing)
+                setImmediate(() => httpServer.closeIdleConnections());
+        });
+        handle(req, res).catch((error) => {
+            log("ERROR", "Shared HTTP server failed to handle a request", error);
+            sendError(res, 500, "Internal server error");
+        });
+    });
+    return new Promise((resolve, reject) => {
+        httpServer.once("error", (error) => {
+            reject(error.code === "EADDRINUSE"
+                ? new Error(`Port ${port} on ${HTTP_HOST} is already in use. If the Brightspace HTTP server is already running, ` +
+                    `connect to it instead of starting another; otherwise choose a different port with --port or D2L_HTTP_PORT.`)
+                : error);
+        });
+        httpServer.listen({ host: HTTP_HOST, port, exclusive: true }, () => {
+            const bound = httpServer.address().port;
+            allowedHosts = new Set([`${HTTP_HOST}:${bound}`, `localhost:${bound}`]);
+            allowedOrigins = new Set([`http://${HTTP_HOST}:${bound}`, `http://localhost:${bound}`]);
+            httpServer.on("error", (error) => log("ERROR", "Shared HTTP server error", error));
+            resolve({
+                url: `http://${HTTP_HOST}:${bound}${MCP_PATH}`,
+                port: bound,
+                server: httpServer,
+                close: () => new Promise((done) => {
+                    closing = true;
+                    if (active > 0)
+                        log("INFO", `Waiting for ${active} request(s) in progress to finish`);
+                    httpServer.close(() => done());
+                    httpServer.closeIdleConnections();
+                }),
+            });
+        });
+    });
+}

package/build/index.js

@@ -6,21 +6,17 @@
  *
  * https://github.com/rohanmuppa/brightspace-mcp-server
  */
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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 { TokenManager, AuthRunner } from "./auth/index.js";
-import { D2LApiClient } from "./api/index.js";
 import { startUpdateChecks } from "./utils/update-checker.js";
-import { configureDevActivity, trackToolActivity } from "./utils/dev-activity.js";
+import { configureDevActivity } from "./utils/dev-activity.js";
+import { createMcpServer, createRuntime } from "./server.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
-import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_VERSION = (() => {
@@ -44,12 +40,15 @@ else if (subcommand === 'doctor') {
     await import('./doctor.js');
 }
 else {
-    // ── MCP Server (default) ────────────────────────────────────────────
+    // ── MCP Server (default: stdio; `http`: one shared localhost server) ──
+    const http = subcommand === 'http';
     // 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();
+    guardServerProcess(process, !http);
+    /** Set once the HTTP server is listening; shutdown waits on it. */
+    let stopHttp;
     async function main() {
         try {
             // Load configuration
@@ -59,12 +58,6 @@ else {
             // who have neither turned on. Booleans only; the key is never passed.
             setActiveShortcuts({ rememberMfa: config.rememberMfa === true, keySaved: Boolean(config.totpUri) });
             log("DEBUG", "Configuration loaded", { sessionDir: config.sessionDir });
-            // Create MCP server instance
-            const server = new McpServer({
-                name: "brightspace",
-                version: PKG_VERSION,
-                description: "Brightspace MCP Server — by Rohan Muppa (github.com/rohanmuppa/brightspace-mcp-server)",
-            }, { capabilities: { logging: {} } });
             log("INFO", "");
             log("INFO", "========================================");
             log("INFO", `  Brightspace MCP Server v${PKG_VERSION}`);
@@ -72,47 +65,13 @@ else {
             log("INFO", "  github.com/rohanmuppa/brightspace-mcp-server");
             log("INFO", "========================================");
             log("INFO", "");
-            // Create TokenManager for reading cached tokens
-            const tokenManager = new TokenManager({
-                sessionDir: config.sessionDir,
-                baseUrl: config.baseUrl,
-                tokenTtl: config.tokenTtl,
-                envAccessToken: config.envAccessToken,
-                envSessionCookie: config.envSessionCookie,
+            // 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(() => { });
             });
-            // D2L_ACCESS_TOKEN / D2L_SESSION_COOKIE are opt-in browser-free sign-in
-            // escape hatches (Docker, headless Linux, WSL, hardware-key MFA
-            // tenants). When either is set, AuthRunner is never created: there is
-            // no stored credential to drive a browser login from, and a rejected
-            // pasted credential should fail with a clear "paste a fresh one"
-            // message rather than spawning auth-cli.
-            const envAuthActive = Boolean(config.envAccessToken || config.envSessionCookie);
-            const authRunner = envAuthActive
-                ? undefined
-                : new AuthRunner({
-                    sessionDir: config.sessionDir,
-                    onProgress: (message) => {
-                        void server.sendLoggingMessage({ level: "info", logger: "brightspace-auth", data: message }).catch(() => { });
-                    },
-                });
-            // Create D2L API Client with auto-reauth support
-            const apiClient = new D2LApiClient({
-                baseUrl: config.baseUrl,
-                tokenManager,
-                onAuthExpired: authRunner ? () => authRunner.run(currentMfaAnnouncer()) : undefined,
-                authExpiredMessage: config.envAccessToken
-                    ? "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set."
-                    : config.envSessionCookie
-                        ? "The pasted D2L_SESSION_COOKIE has expired. Copy a fresh d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser and update the environment variable; this server does not fall back to a browser login while D2L_SESSION_COOKIE is set."
-                        : undefined,
-            });
-            // Nothing here reaches Brightspace. API versions are discovered by the
-            // first request that needs them, and the first request with no saved
-            // session authenticates on its own (see D2LApiClient.withAuthentication).
-            // A server that signed in at startup would open an MFA prompt on the
-            // user's phone every time their editor restarted, whether or not they
-            // ever asked about a course, and a tenant that was briefly unreachable
-            // would take the whole server down with it.
             // 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
             // interval is unref'd and cannot hold the process open.
@@ -125,54 +84,18 @@ else {
                     activeOnly: config.courseFilter.activeOnly,
                 });
             }
-            // A client may leave `arguments` off a call to a tool that takes none;
-            // SDK 1.26-1.31 reject that. Must run before the first registration.
-            acceptOmittedArguments(server);
-            // Register MCP tools. Each one, when its client sends a progress token,
-            // shows an MFA challenge mid-call and waits for the approval instead of
-            // asking to be called again (see relayMfaChallenges).
-            relayMfaChallenges(server);
-            trackToolActivity(server);
-            registerGetMyCourses(server, apiClient, config);
-            registerGetUpcomingDueDates(server, apiClient, config);
-            registerGetCalendarEvents(server, apiClient, config);
-            registerGetMyGrades(server, apiClient, config);
-            registerGetAnnouncements(server, apiClient, config);
-            registerGetAssignments(server, apiClient, config);
-            registerGetAssignmentRubric(server, apiClient);
-            registerGetAssignmentFiles(server, apiClient, config.baseUrl);
-            registerGetAnnouncementFiles(server, apiClient);
-            registerGetCourseContent(server, apiClient);
-            registerDownloadFile(server, apiClient);
-            registerGetClasslistEmails(server, apiClient);
-            registerGetRoster(server, apiClient);
-            registerGetMyGroups(server, apiClient);
-            registerGetSyllabus(server, apiClient);
-            registerGetDiscussions(server, apiClient);
-            registerGetVideoTranscript(server, apiClient);
-            registerGetServerInfo(server, config, PKG_VERSION, apiClient);
-            registerSearchCourse(server, apiClient);
-            registerSignOut(server, config, apiClient, tokenManager, authRunner);
-            // Instructor / TA dropbox tools (read-only) — 403 for a student account.
-            registerGetDropboxFolders(server, apiClient);
-            registerGetDropboxSubmissions(server, apiClient);
-            registerGetDropboxUserSubmissions(server, apiClient);
-            registerGetDropboxFeedback(server, apiClient);
-            registerGetRubricsForObject(server, apiClient);
-            registerDownloadDropboxSubmissionFile(server, apiClient);
-            log("DEBUG", "MCP tools registered (26 tools)");
-            // Register MCP prompts — surfaced in clients (e.g. Claude Desktop) as a
-            // picker, distinct from tools. Each one is a canned user message that
-            // names our own tools by name, so a client with no idea what to ask
-            // for still gets a one-click starting point.
-            registerWeeklyBriefingPrompt(server);
-            registerGradeAuditPrompt(server);
-            registerStudyPlannerPrompt(server);
-            registerCourseSummaryPrompt(server);
-            log("DEBUG", "MCP prompts registered (4 prompts)");
+            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;
+            }
             // Connect stdio transport
+            stdioServer = createMcpServer(runtime);
             const transport = new StdioServerTransport();
-            await server.connect(transport);
+            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.)");
         }
@@ -181,14 +104,19 @@ else {
             process.exit(1);
         }
     }
-    // Graceful shutdown
-    process.on('SIGINT', () => {
-        log('INFO', 'Shutting down MCP server');
-        process.exit(0);
-    });
-    process.on('SIGTERM', () => {
-        log('INFO', 'Shutting down MCP server');
-        process.exit(0);
-    });
+    // Graceful shutdown. The HTTP server first answers the calls already in
+    // progress (other chats may be mid-call); a second signal stops at once.
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown || !stopHttp) {
+            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));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
     main();
 }

package/build/server.js

@@ -0,0 +1,118 @@
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TokenManager, AuthRunner } from "./auth/index.js";
+import { D2LApiClient } from "./api/index.js";
+import { trackToolActivity } from "./utils/dev-activity.js";
+import { log } from "./utils/logger.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
+import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
+/**
+ * Build the shared runtime. Nothing here reaches Brightspace: API versions
+ * are discovered by the first request that needs them, and the first request
+ * with no saved session authenticates on its own (see
+ * D2LApiClient.withAuthentication). A server that signed in at startup would
+ * open an MFA prompt on the user's phone every time their editor restarted,
+ * 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).
+ */
+export function createRuntime(config, version, onAuthProgress) {
+    const tokenManager = new TokenManager({
+        sessionDir: config.sessionDir,
+        baseUrl: config.baseUrl,
+        tokenTtl: config.tokenTtl,
+        envAccessToken: config.envAccessToken,
+        envSessionCookie: config.envSessionCookie,
+    });
+    // D2L_ACCESS_TOKEN / D2L_SESSION_COOKIE are opt-in browser-free sign-in
+    // escape hatches (Docker, headless Linux, WSL, hardware-key MFA
+    // tenants). When either is set, AuthRunner is never created: there is
+    // no stored credential to drive a browser login from, and a rejected
+    // pasted credential should fail with a clear "paste a fresh one"
+    // message rather than spawning auth-cli.
+    const envAuthActive = Boolean(config.envAccessToken || config.envSessionCookie);
+    const authRunner = envAuthActive
+        ? undefined
+        : new AuthRunner({ sessionDir: config.sessionDir, onProgress: onAuthProgress });
+    // 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({
+        baseUrl: config.baseUrl,
+        tokenManager,
+        onAuthExpired: authRunner ? () => authRunner.run(currentMfaAnnouncer()) : undefined,
+        authExpiredMessage: config.envAccessToken
+            ? "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set."
+            : config.envSessionCookie
+                ? "The pasted D2L_SESSION_COOKIE has expired. Copy a fresh d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser and update the environment variable; this server does not fall back to a browser login while D2L_SESSION_COOKIE is set."
+                : undefined,
+    });
+    return { config, version, tokenManager, apiClient, authRunner };
+}
+/**
+ * An MCP server with every tool and prompt registered against the shared
+ * runtime. stdio builds one; the HTTP server builds one per request, which is
+ * cheap (registration only) and is what the SDK's stateless transport
+ * requires. All state worth keeping lives in the runtime, not here.
+ */
+export function createMcpServer(runtime) {
+    const { config, version, tokenManager, apiClient, authRunner } = runtime;
+    const server = new McpServer({
+        name: "brightspace",
+        version,
+        description: "Brightspace MCP Server — by Rohan Muppa (github.com/rohanmuppa/brightspace-mcp-server)",
+    }, { capabilities: { logging: {} } });
+    // A client may leave `arguments` off a call to a tool that takes none;
+    // SDK 1.26-1.31 reject that. Must run before the first registration.
+    acceptOmittedArguments(server);
+    // Register MCP tools. Each one, when its client sends a progress token,
+    // shows an MFA challenge mid-call and waits for the approval instead of
+    // asking to be called again (see relayMfaChallenges).
+    relayMfaChallenges(server);
+    trackToolActivity(server);
+    registerGetMyCourses(server, apiClient, config);
+    registerGetUpcomingDueDates(server, apiClient, config);
+    registerGetCalendarEvents(server, apiClient, config);
+    registerGetMyGrades(server, apiClient, config);
+    registerGetAnnouncements(server, apiClient, config);
+    registerGetAssignments(server, apiClient, config);
+    registerGetAssignmentRubric(server, apiClient);
+    registerGetAssignmentFiles(server, apiClient, config.baseUrl);
+    registerGetAnnouncementFiles(server, apiClient);
+    registerGetCourseContent(server, apiClient);
+    registerDownloadFile(server, apiClient);
+    registerGetClasslistEmails(server, apiClient);
+    registerGetRoster(server, apiClient);
+    registerGetMyGroups(server, apiClient);
+    registerGetSyllabus(server, apiClient);
+    registerGetDiscussions(server, apiClient);
+    registerGetVideoTranscript(server, apiClient);
+    registerGetServerInfo(server, config, version, apiClient);
+    registerSearchCourse(server, apiClient);
+    registerSignOut(server, config, apiClient, tokenManager, authRunner);
+    // Instructor / TA dropbox tools (read-only) — 403 for a student account.
+    registerGetDropboxFolders(server, apiClient);
+    registerGetDropboxSubmissions(server, apiClient);
+    registerGetDropboxUserSubmissions(server, apiClient);
+    registerGetDropboxFeedback(server, apiClient);
+    registerGetRubricsForObject(server, apiClient);
+    registerDownloadDropboxSubmissionFile(server, apiClient);
+    log("DEBUG", "MCP tools registered (26 tools)");
+    // Register MCP prompts — surfaced in clients (e.g. Claude Desktop) as a
+    // picker, distinct from tools. Each one is a canned user message that
+    // names our own tools by name, so a client with no idea what to ask
+    // for still gets a one-click starting point.
+    registerWeeklyBriefingPrompt(server);
+    registerGradeAuditPrompt(server);
+    registerStudyPlannerPrompt(server);
+    registerCourseSummaryPrompt(server);
+    log("DEBUG", "MCP prompts registered (4 prompts)");
+    return server;
+}

package/build/setup/prepare.js

@@ -98,8 +98,8 @@ export async function runPrepare(args, 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/`));
+        ? ok("node", `Node.js ${deps.nodeVersion} (22 or newer)`)
+        : fail("node", `Node.js ${deps.nodeVersion} is too old — install Node 22 or newer from https://nodejs.org/`));
     // ── School ──
     const existing = deps.readExistingConfig();
     let baseUrl;

package/build/tools/tool-helpers.js

@@ -129,13 +129,14 @@ const AUTH_FAILURE_GUIDANCE = {
  * auth-runner.ts MFA_NUMBER_MARKER) — a bounded, pre-validated value, not
  * arbitrary child output, so it is safe to interpolate here.
  */
-const MFA_ALREADY_REPORTED = "Brightspace sign-in is already in progress; another call in this batch has the number to " +
-    "approve. Retry this call once the sign-in completes.";
-const AUTOMATIC_ALREADY_REPORTED = "Brightspace sign-in is already in progress, answering its own verification code; another call " +
-    "in this batch has the details. Retry this call once the sign-in completes. Don't ask the user " +
-    "to approve anything.";
+const MFA_ALREADY_REPORTED = "Brightspace sign-in is already in progress; another call, possibly in another open chat, has the " +
+    "number to approve. Retry this call once the sign-in completes.";
+const AUTOMATIC_ALREADY_REPORTED = "Brightspace sign-in is already in progress, answering its own verification code; another call, " +
+    "possibly in another open chat, has the details. Retry this call once the sign-in completes. " +
+    "Don't ask the user to approve anything.";
 function authFailureMessage(error) {
-    // Another call in this parallel batch already carries the number and the
+    // Another call in this parallel batch (which, behind the shared HTTP
+    // server, may be another chat's) already carries the number and the
     // instructions (issue #212). Repeating them in every response made a batch
     // unreadable; one short line is enough for this call.
     if (error.kind === "mfaPending" && error.duplicate)

package/build/utils/process-guard.js

@@ -20,14 +20,24 @@ const RECONNECT_HINT = "Restart or reconnect the Brightspace MCP server in your
  * the client has already closed ends the process cleanly, since there is no
  * one left to answer; and every other way the process stops says why on
  * stderr, which MCP clients keep as the server's log.
+ *
+ * The shared HTTP server passes stdio = false: its clients are not on stdin
+ * and stdout, so a closed terminal pipe says nothing about them.
  */
-export function guardServerProcess(proc = process) {
+export function guardServerProcess(proc = process, stdio = true) {
     proc.on("uncaughtException", (error) => {
         log("ERROR", "Uncaught exception; the server is still running", error);
     });
     proc.on("unhandledRejection", (reason) => {
         log("ERROR", "Unhandled promise rejection", reason);
     });
+    proc.on("exit", (code) => {
+        if (code === 0)
+            return;
+        log("ERROR", `Brightspace MCP server exited with code ${code}. ${RECONNECT_HINT}`);
+    });
+    if (!stdio)
+        return;
     proc.stdout.on("error", (error) => {
         if (error.code === "EPIPE") {
             log("INFO", "The MCP client closed the connection (stdout pipe closed); shutting down");
@@ -39,9 +49,4 @@ export function guardServerProcess(proc = process) {
     proc.stdin.on("end", () => {
         log("INFO", "The MCP client closed stdin; the server will stop");
     });
-    proc.on("exit", (code) => {
-        if (code === 0)
-            return;
-        log("ERROR", `Brightspace MCP server exited with code ${code}. ${RECONNECT_HINT}`);
-    });
 }

package/build/utils/saved-session.js

@@ -52,8 +52,8 @@ export function sessionDirFor(env, store, baseUrl, username) {
             : path.join(os.homedir(), ".d2l-session");
     return accountSessionDirectory(sessionRoot, baseUrl, username);
 }
-/** True for the Node versions this package supports (20 and newer). */
+/** True for the Node versions this package supports (22 and newer). */
 export function nodeVersionSupported(version) {
     const major = Number(version.replace(/^v/, "").split(".")[0]);
-    return Number.isFinite(major) && major >= 20;
+    return Number.isFinite(major) && major >= 22;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-mcp-server",
-  "version": "4.0.7",
+  "version": "5.0.0",
   "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",
@@ -30,7 +30,7 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@napi-rs/keyring": "^2.0.0",
     "dotenv": "^17.2.4",
-    "file-type": "^21.3.0",
+    "file-type": "^22.1.1",
     "playwright": "^1.58.2",
     "sanitize-filename": "^1.6.3",
     "trash": "^9.0.0",
@@ -45,7 +45,7 @@
     "vitest": "^5.0.3"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "license": "MIT",
   "author": "Rohan Muppa",