brightspace-mcp-server 5.0.6 → 5.0.8

package/README.md

@@ -136,6 +136,7 @@ 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.
 

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/update.js

@@ -7,7 +7,7 @@
  * https://github.com/rohanmuppa/brightspace-mcp-server
  */
 import { execSync } from "node:child_process";
-import { readFileSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import dotenv from "dotenv";
@@ -15,6 +15,7 @@ dotenv.config({ quiet: true });
 // ANSI color helpers
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
 const red = (s) => `\x1b[31m${s}\x1b[0m`;
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -27,10 +28,50 @@ function run(cmd, opts) {
         }).trim();
     }
     catch (err) {
+        // tsc reports compile errors on stdout and npm adds its summary on
+        // stderr, so a failure keeps both.
         const error = err;
-        throw new Error(error.stderr || error.message || "Command failed");
+        const output = [error.stdout, error.stderr].filter((s) => s?.trim()).join("\n");
+        throw new Error(output || error.message || "Command failed");
     }
 }
+/** How many trailing lines of a failed command's output are worth showing. */
+const FAILURE_TAIL_LINES = 20;
+/**
+ * The end of a failed command's output, fit for a terminal: escape sequences
+ * and control characters stripped, blank lines dropped, long logs cut to the
+ * last few lines (where npm and tsc put the actual error).
+ */
+export function failureDetail(err) {
+    if (err === undefined || err === null)
+        return [];
+    const text = err instanceof Error ? err.message : String(err);
+    const lines = text
+        .replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "")
+        .replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "")
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line.trim() !== "");
+    return lines.slice(-FAILURE_TAIL_LINES);
+}
+/** Print a failed step with its cause and how to recover, then exit. */
+function fail(summary, err, recovery) {
+    console.error(red(`  Error: ${summary}`));
+    const detail = failureDetail(err);
+    if (detail.length > 0) {
+        console.error("");
+        for (const line of detail)
+            console.error(dim(`    ${line}`));
+        console.error("");
+    }
+    for (const line of recovery)
+        console.error(`  ${line}`);
+    process.exit(1);
+}
+const RETRY_HINT = [
+    "The update is not finished. Fix the problem above, then run `npm run update` again;",
+    "it will redo the install and build even though the new code is already pulled.",
+];
 function getVersion() {
     const pkg = JSON.parse(readFileSync(join(projectRoot, "package.json"), "utf-8"));
     return pkg.version || "unknown";
@@ -117,12 +158,6 @@ export function chooseRelease(registry, nodeVersion) {
     }
     return { ok: true, version, commit: gitHead };
 }
-function fail(...lines) {
-    console.error(red(`  Error: ${lines[0]}`));
-    for (const line of lines.slice(1))
-        console.error(`  ${line}`);
-    process.exit(1);
-}
 export function main() {
     console.log("");
     console.log(bold("=== Brightspace MCP Server — Update ==="));
@@ -172,12 +207,12 @@ export function main() {
         registry = JSON.parse(run("npm view brightspace-mcp-server@latest version gitHead engines --json", { silent: true }));
     }
     catch {
-        fail("Could not read the latest release from npm.", "Check your network connection and try again.");
+        fail("Could not read the latest release from npm.", undefined, ["Check your network connection and try again."]);
         return;
     }
     const release = chooseRelease(registry, process.version);
     if (!release.ok) {
-        fail("No release this checkout can safely update to.", release.reason);
+        fail("No release this checkout can safely update to.", undefined, [release.reason]);
         return;
     }
     const { version: targetVersion, commit } = release;
@@ -186,8 +221,8 @@ export function main() {
     try {
         run("git fetch origin main", { silent: true });
     }
-    catch {
-        fail("Failed to fetch from remote.", "Check your network connection and try again.");
+    catch (err) {
+        fail("Failed to fetch from remote.", err, ["Check your network connection and try again."]);
         return;
     }
     try {
@@ -197,7 +232,7 @@ export function main() {
             throw new Error("version mismatch");
     }
     catch {
-        fail(`Could not verify release ${targetVersion} (commit ${commit.slice(0, 7)}) on origin/main.`, "Nothing was changed.");
+        fail(`Could not verify release ${targetVersion} (commit ${commit.slice(0, 7)}) on origin/main.`, undefined, ["Nothing was changed."]);
         return;
     }
     // Local commits on main that origin/main lacks would need a merge or rebase.
@@ -205,51 +240,69 @@ export function main() {
     if (aheadCount !== "0") {
         refuse(`Your main has ${aheadCount} commit${aheadCount === "1" ? "" : "s"} that origin/main does not.`, "Move them to another branch or reconcile main with origin/main yourself, then run the update again.");
     }
-    // Check if we're behind
+    // A marker in the git directory records that the code was updated but the
+    // install or build has not yet succeeded. Without it a retry would see no
+    // new commits and report "Already up to date" over a broken build.
+    const marker = resolve(projectRoot, run("git rev-parse --git-path brightspace-update-incomplete", { silent: true }));
+    const unfinished = existsSync(marker);
     const behindCount = run(`git rev-list --count HEAD..${commit}`, { silent: true });
-    if (behindCount === "0") {
+    if (behindCount === "0" && !unfinished) {
         console.log("");
         console.log(green("  Already up to date!"));
         console.log("");
         return;
     }
-    // Show what's new
-    console.log("");
-    console.log(bold(`  ${behindCount} new commit${behindCount === "1" ? "" : "s"} in ${targetVersion}:`));
-    console.log("");
-    const log = run(`git log HEAD..${commit} --oneline`, { silent: true });
-    for (const line of log.split("\n")) {
-        console.log(`    ${dim("•")} ${line}`);
-    }
-    console.log("");
-    // Fast-forward only, to the verified release: never a merge or rebase,
-    // whatever git's pull settings say, and no pull fallback if it fails.
-    console.log(dim(`  Updating to ${targetVersion}...`));
-    try {
-        run(`git merge --ff-only ${commit}`, { silent: true });
+    if (behindCount === "0") {
+        console.log(yellow("  The last update did not finish. Finishing it now."));
     }
-    catch {
-        fail(`Could not fast-forward to ${targetVersion}.`, "Nothing was changed. Check 'git status' and try again.");
-        return;
+    else {
+        // Show what's new
+        console.log("");
+        console.log(bold(`  ${behindCount} new commit${behindCount === "1" ? "" : "s"} in ${targetVersion}:`));
+        console.log("");
+        const log = run(`git log HEAD..${commit} --oneline`, { silent: true });
+        for (const line of log.split("\n")) {
+            console.log(`    ${dim("•")} ${line}`);
+        }
+        console.log("");
+        // Recorded before HEAD moves, and cleared only after the build succeeds.
+        writeFileSync(marker, `${new Date().toISOString()}\n`);
+        // Fast-forward only, to the verified release: never a merge or rebase,
+        // whatever git's pull settings say, and no pull fallback if it fails.
+        console.log(dim(`  Updating to ${targetVersion}...`));
+        try {
+            run(`git merge --ff-only ${commit}`, { silent: true });
+        }
+        catch (err) {
+            // HEAD did not move, so this run left nothing unfinished.
+            if (!unfinished)
+                rmSync(marker, { force: true });
+            fail(`Could not fast-forward to ${targetVersion}.`, err, ["Nothing was changed. Check 'git status' and try again."]);
+            return;
+        }
     }
     // Install dependencies
     console.log(dim("  Installing dependencies..."));
     try {
         run("npm install", { silent: true });
     }
-    catch {
-        console.error(red("  Error: Failed to install dependencies."));
-        process.exit(1);
+    catch (err) {
+        fail("Failed to install dependencies.", err, [
+            "If a file is locked (EBUSY/EPERM), close every MCP client using this server first.",
+            ...RETRY_HINT,
+        ]);
+        return;
     }
     // Build
     console.log(dim("  Building..."));
     try {
         run("npm run build", { silent: true });
     }
-    catch {
-        console.error(red("  Error: Build failed."));
-        process.exit(1);
+    catch (err) {
+        fail("Build failed.", err, RETRY_HINT);
+        return;
     }
+    rmSync(marker, { force: true });
     // Show new version
     const newVersion = getVersion();
     console.log("");
@@ -259,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/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.6",
+  "version": "5.0.8",
   "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",