brightspace-mcp-server 5.0.7 → 5.0.9

package/README.md

@@ -129,15 +129,16 @@ Normally every chat starts its own copy of the server. With many Codex chats ope
    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.
+   (`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. Rerunning `setup` recognizes this entry and keeps it, token settings included.
 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.
+- **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 (rerunning `setup` does it) 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 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.
 
 ## When it asks you to sign in
 

package/build/index.js

@@ -75,7 +75,7 @@ else {
             // 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.
-            startUpdateChecks();
+            startUpdateChecks({ transport: 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", {

package/build/setup/clients.js

@@ -163,7 +163,8 @@ export function detectMcpClients(overrides = {}) {
 }
 /**
  * Register the server in every given app without asking. An entry that runs
- * something else is left alone unless `replace` is set, and a write that
+ * something else, or connects to the shared server by URL, is left alone
+ * unless `replace` is set, and a write that
  * fails (an agent's sandbox may block another app's settings folder) is
  * reported for that app instead of stopping the rest.
  */
@@ -174,13 +175,16 @@ export function registerAll(targets, { replace }) {
             const existing = target.inspect();
             if (existing.state === "current")
                 return { ...base, outcome: "current" };
+            if (existing.state === "shared_http" && !replace)
+                return { ...base, outcome: "shared_http", url: existing.url };
             if (existing.state === "different" && !replace) {
                 return { ...base, outcome: "different_left", current: existing.current };
             }
-            if (!target.write(existing.state === "different")) {
+            const replacing = existing.state !== "missing";
+            if (!target.write(replacing)) {
                 return { ...base, outcome: "failed", message: `${target.name} did not accept the registration.` };
             }
-            return { ...base, outcome: existing.state === "different" ? "replaced" : "added" };
+            return { ...base, outcome: replacing ? "replaced" : "added" };
         }
         catch (error) {
             return { ...base, outcome: "failed", message: error instanceof Error ? error.message : String(error) };

package/build/setup/prepare.js

@@ -87,6 +87,8 @@ function appLine(outcome) {
             return ok("app", `${outcome.name}: old "brightspace" entry replaced`, false);
         case "current":
             return ok("app", `${outcome.name}: already set up`, false);
+        case "shared_http":
+            return ok("app", `${outcome.name}: already set up to use the shared server at ${outcome.url}`, false);
         case "different_left":
             return fail("app", `${outcome.name}: "brightspace" already runs ${outcome.current} — left as is (pass --replace to change it)`, false);
         case "failed":

package/build/setup.js

@@ -151,34 +151,43 @@ export function planQuestions(mode, known) {
 // ── Registering with one app ───────────────────────────────────────
 /**
  * Registers Brightspace in one app, 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 app ends up running the expected entry.
+ * that points somewhere else: a matching entry is left alone, an entry using
+ * the shared server by URL is kept unless the person asks to switch back, and
+ * a different one is printed (so it can be restored) and replaced only on a yes.
+ * Resolves true when the app ends up set up.
  */
-async function registerWithClient(rl, target) {
+export async function registerWithClient(target, askLine, log = console.log) {
     const existing = target.inspect();
     if (existing.state === "current") {
-        console.log(green(`  ${target.name} already has Brightspace configured.`));
+        log(green(`  ${target.name} already has Brightspace configured.`));
         return true;
     }
+    if (existing.state === "shared_http") {
+        log(green(`  ${target.name} uses the shared Brightspace server at ${existing.url}.`));
+        const switchBack = await askLine(`  Switch it back to its own copy per chat (${serverCommand().join(" ")})? (yes/no): `);
+        if (!/^y(es)?$/i.test(switchBack)) {
+            log(dim(`  Kept ${target.name} on the shared server.`));
+            return true;
+        }
+    }
     if (existing.state === "different") {
-        console.log(yellow(`  ${target.name} has "brightspace" pointing at:`));
-        console.log(`    ${existing.current}`);
-        const replace = await ask(rl, `  Replace it with ${serverCommand().join(" ")}? (yes/no): `);
+        log(yellow(`  ${target.name} has "brightspace" pointing at:`));
+        log(`    ${existing.current}`);
+        const replace = await askLine(`  Replace it with ${serverCommand().join(" ")}? (yes/no): `);
         if (!/^y(es)?$/i.test(replace)) {
-            console.log(dim(`  Left ${target.name} unchanged.`));
+            log(dim(`  Left ${target.name} unchanged.`));
             return false;
         }
     }
     try {
-        if (target.write(existing.state === "different")) {
-            console.log(green(`  ${target.name} configured!`));
+        if (target.write(existing.state !== "missing")) {
+            log(green(`  ${target.name} configured!`));
             return true;
         }
-        console.log(yellow(`  Could not configure ${target.name}. See README.md for the manual command.`));
+        log(yellow(`  Could not configure ${target.name}. See README.md for the manual command.`));
     }
     catch (err) {
-        console.log(yellow(`  Could not configure ${target.name}: ${err instanceof Error ? err.message : String(err)}`));
+        log(yellow(`  Could not configure ${target.name}: ${err instanceof Error ? err.message : String(err)}`));
     }
     return false;
 }
@@ -474,7 +483,7 @@ async function interactive(args) {
     if (plan.registerApps) {
         for (const target of detectMcpClients()) {
             const answer = await ask(rl2, target.question);
-            if (/^y(es)?$/i.test(answer) && await registerWithClient(rl2, target)) {
+            if (/^y(es)?$/i.test(answer) && await registerWithClient(target, (question) => ask(rl2, question))) {
                 configuredClients.push(target.name);
             }
             console.log("");

package/build/update.js

@@ -312,6 +312,11 @@ export function main() {
     }
     console.log("");
     console.log("  Restart your MCP client to use the latest version.");
+    console.log("  If you run the shared HTTP server, restart the server instead: a client restart only");
+    console.log("  reconnects to the old process. Stop it, start node build/index.js http again with the");
+    console.log("  same D2L_HTTP_TOKEN, port, and D2L_* settings, and reconnect any client that does not.");
+    console.log(dim("  A chat already connected over stdio keeps its own copy and cannot move onto the shared"));
+    console.log(dim("  server mid-session; restart its client to load the new build."));
     console.log("");
 }
 // `npm run update` runs this file directly. VITEST is set only by the test

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

@@ -31,13 +31,33 @@ export function serverCommand(platform = process.platform) {
         ? ["cmd", "/c", "npx", "-y", `${PACKAGE_NAME}@latest`]
         : ["npx", "-y", `${PACKAGE_NAME}@latest`];
 }
+/**
+ * Whether a URL is where the shared server listens: plain http on this
+ * computer, at the MCP path (see HTTP_HOST and MCP_PATH in http-server.ts,
+ * which also accepts "localhost"). Any other URL is some other server.
+ */
+function isSharedServerUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    return parsed.protocol === "http:"
+        && (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost")
+        && parsed.pathname === "/mcp";
+}
 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;
+    const { command, args, url } = entry;
+    if (typeof command !== "string" && typeof url === "string") {
+        return isSharedServerUrl(url) ? { state: "shared_http", url } : { state: "different", current: url };
+    }
     if (typeof command !== "string") {
         return { state: "different", current: JSON.stringify(entry) };
     }

package/build/utils/update-checker.js

@@ -20,7 +20,11 @@
  *
  * A source checkout gets different advice: installing the npm package would
  * update some other copy, and for a fork it would mean leaving its changes
- * behind. Such a checkout is told to pull and rebuild, or to opt out.
+ * behind. Such a checkout is told to run its own updater, or to opt out.
+ *
+ * What to restart depends on the transport: a stdio server dies with its
+ * client, but the shared HTTP server outlives every client and must itself be
+ * restarted.
  *
  * Set D2L_NO_UPDATE_CHECK to any value to switch the check off entirely.
  */
@@ -162,13 +166,37 @@ export async function fetchLatestVersion(fetchImpl = fetch) {
         return null;
     }
 }
+/** The command that starts the shared HTTP server from each kind of install. */
+const HTTP_START_COMMAND = {
+    "npx-cache": `npx -y ${PACKAGE_NAME}@latest http`,
+    "npm-install": `${PACKAGE_NAME} http`,
+    "source-checkout": "node build/index.js http",
+};
+/**
+ * What to restart so the new version actually runs. A stdio server lives as
+ * long as its client, so restarting the client is enough. The shared HTTP
+ * server outlives every client: restarting one only reconnects it to the same
+ * old process, so the server itself has to be restarted, with the token and
+ * port its clients already use.
+ */
+function reloadStep(installKind, transport, to, afterAStep) {
+    // "Then" only follows an update step; an npx install with no stale cache to
+    // clear has none, so the restart is the first thing to do.
+    const restart = afterAStep ? "Then restart" : "Restart";
+    if (transport === "stdio")
+        return `${restart} your MCP client to pick up v${to}.`;
+    return `${restart} the shared HTTP server to pick up v${to}: restarting an MCP client only reconnects it ` +
+        `to this running server. Stop it (Ctrl+C where it runs, or stop its service), then start it again with ` +
+        `${HTTP_START_COMMAND[installKind]}, using the same D2L_HTTP_TOKEN, port, and D2L_* settings, ` +
+        `and reconnect any client that does not reconnect on its own.`;
+}
 /**
  * Run one update check. Never throws and never blocks the caller for long:
  * the registry request is bounded by a timeout and every failure is
  * swallowed, because a version check must not affect the server.
  */
 export async function initUpdateChecker(deps = {}) {
-    const { fetchImpl = fetch, env = process.env, installedVersion = getInstalledVersion(), installKind = installKindOf(), clearCaches = () => clearAllNpxCaches(), } = deps;
+    const { fetchImpl = fetch, env = process.env, installedVersion = getInstalledVersion(), installKind = installKindOf(), clearCaches = () => clearAllNpxCaches(), transport = "stdio", } = deps;
     if (env.D2L_NO_UPDATE_CHECK)
         return;
     try {
@@ -180,24 +208,27 @@ export async function initUpdateChecker(deps = {}) {
         const from = safeVersionLabel(installedVersion);
         const to = safeVersionLabel(latest);
         const headline = `Update available: v${from} to v${to}.`;
-        let text;
+        let update;
         if (installKind === "npx-cache") {
             const count = await clearCaches();
-            const cleanup = count > 0
+            update = count > 0
                 ? `Cleared ${count} stale npx cache director${count === 1 ? "y" : "ies"} for ${PACKAGE_NAME} ` +
-                    `(kept the one this server is running from). `
+                    `(kept the one this server is running from).`
                 : "";
-            text = `${headline} ${cleanup}Restart your MCP client to pick up v${to}.`;
         }
         else if (installKind === "source-checkout") {
-            text = `${headline} This server runs from a source checkout, so update that checkout ` +
-                `(git pull, then npm run build) and restart your MCP client. ` +
-                `If it is a fork you maintain, set D2L_NO_UPDATE_CHECK=1 to turn off upstream update notices.`;
+            update = `This server runs from a source checkout, so update that checkout with npm run update ` +
+                `(it pulls, installs dependencies, and rebuilds).`;
         }
         else {
-            text = `${headline} Run: ${GLOBAL_INSTALL_COMMAND}` +
-                `, then ${CLEAR_NPX_CACHE_COMMAND} and restart your MCP client.`;
+            update = `Run: ${GLOBAL_INSTALL_COMMAND}, then ${CLEAR_NPX_CACHE_COMMAND}.`;
         }
+        const optOut = installKind === "source-checkout"
+            ? " If it is a fork you maintain, set D2L_NO_UPDATE_CHECK=1 to turn off upstream update notices."
+            : "";
+        const text = [headline, update, `${reloadStep(installKind, transport, to, update !== "")}${optOut}`]
+            .filter(Boolean)
+            .join(" ");
         // Preserve lastShownAt when the text is unchanged, so a periodic re-check
         // does not reset the throttle and start repeating the same line.
         state = state?.text === text ? state : { text, lastShownAt: null };

package/package.json

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