brightspace-mcp-server 5.0.3 → 5.0.5

package/README.md

@@ -76,7 +76,7 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 | Syllabus | "What's the late policy in ECE 264's syllabus?" (if the course keeps its syllabus in an external tool such as Simple Syllabus, you get the link to open instead) |
 | People | "Who are the TAs for ECE 264?" · "Who is in my project group?" |
 | Discussions | "Summarize the latest posts in the final project thread" |
-| Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura, including BoilerCast LTI links, and YouTube) |
+| Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura, including BoilerCast LTI links, and YouTube. When YouTube asks for a sign-in or a "not a bot" check, the answer says so, with the video link and how to get the transcript yourself: open the link in your browser, choose "Show transcript", and paste it in. The server never gets past that check for you) |
 | Calendar | "When is my midterm?" · "Is lab cancelled on Thursday?" |
 | For instructors and TAs | "Which students haven't submitted Lab 4 yet?" · "What feedback did I leave on this student's homework?" · "Download that student's submitted PDF" (students get a clear "instructor access required" note for these, but can read their own released feedback, below) |
 | Signing out | "Sign me out of Brightspace" (your AI app may ask you to confirm first; details under [When it asks you to sign in](#when-it-asks-you-to-sign-in)) |

package/build/tools/get-video-transcript.js

@@ -11,7 +11,7 @@ import { detectVideoPlatform, extractKalturaIds, extractYouTubeVideoId, } from "
 import { readLtiLaunchPage, toBrightspacePath } from "../utils/transcript/lti.js";
 import { getKalturaTranscript } from "../utils/transcript/kaltura.js";
 import { getYouTubeTranscript } from "../utils/transcript/youtube.js";
-import { NoTranscriptError, TranscriptFetchError } from "../utils/transcript/errors.js";
+import { NoTranscriptError, TranscriptFetchError, } from "../utils/transcript/errors.js";
 import { log } from "../utils/logger.js";
 import { stripD2lSessionParams } from "../utils/session-params.js";
 const UNSUPPORTED_PLATFORM_LABEL = {
@@ -48,6 +48,24 @@ async function followLtiLaunch(apiClient, path) {
     }
     return null;
 }
+/**
+ * What a person can do about each failure. A sign-in or bot check is never
+ * worked around here: the way past it is the user's own browser, and the
+ * result says plainly that nothing was read.
+ */
+function transcriptRecovery(reason, videoUrl) {
+    switch (reason) {
+        case "sign_in_required":
+        case "access_blocked":
+            return (`Open ${videoUrl} in your own browser and complete any sign-in or "not a bot" check it shows. ` +
+                'Then choose "Show transcript" (on YouTube, below the video description) and paste the text into ' +
+                "this conversation. This server does not get past those checks, and no transcript was read from this video.");
+        case "unavailable":
+            return `Open ${videoUrl} in your browser to see whether the video was removed or made private.`;
+        case "fetch_failed":
+            return `Try again in a moment. If it keeps failing, open ${videoUrl} in your browser.`;
+    }
+}
 async function fetchTranscript(platform, videoUrl, fetchImpl) {
     switch (platform) {
         case "kaltura": {
@@ -55,6 +73,7 @@ async function fetchTranscript(platform, videoUrl, fetchImpl) {
             if (!ids) {
                 return {
                     failed: `Could not find a Kaltura entry ID and partner ID in this URL: ${stripD2lSessionParams(videoUrl)}`,
+                    reason: "fetch_failed",
                 };
             }
             try {
@@ -67,6 +86,7 @@ async function fetchTranscript(platform, videoUrl, fetchImpl) {
                     return {
                         failed: `${error.message} This can happen when the video needs an authenticated Kaltura ` +
                             "session rather than an anonymous one. Open it in Brightspace directly.",
+                        reason: error.reason,
                     };
                 }
                 throw error;
@@ -75,7 +95,10 @@ async function fetchTranscript(platform, videoUrl, fetchImpl) {
         case "youtube": {
             const videoId = extractYouTubeVideoId(videoUrl);
             if (!videoId) {
-                return { failed: `Could not find a YouTube video ID in this URL: ${stripD2lSessionParams(videoUrl)}` };
+                return {
+                    failed: `Could not find a YouTube video ID in this URL: ${stripD2lSessionParams(videoUrl)}`,
+                    reason: "fetch_failed",
+                };
             }
             try {
                 return { result: await getYouTubeTranscript(videoId, fetchImpl) };
@@ -84,7 +107,7 @@ async function fetchTranscript(platform, videoUrl, fetchImpl) {
                 if (error instanceof NoTranscriptError)
                     return { noTranscript: error.message };
                 if (error instanceof TranscriptFetchError)
-                    return { failed: error.message };
+                    return { failed: error.message, reason: error.reason };
                 throw error;
             }
         }
@@ -114,7 +137,8 @@ export function registerGetVideoTranscript(server, apiClient, fetchImpl = fetch)
             "Call it with courseId and topicId from get_course_content (typeFilter: 'video' or 'other'), or with videoUrl " +
             "directly if you already have the link. Returns transcript text with timestamps, plus title and duration when " +
             "available. Currently supports Kaltura (e.g. BoilerCast, including its Brightspace LTI links) and YouTube; other platforms return a clear message " +
-            "naming what isn't supported yet. Each call returns at most maxChars characters (up to 100000); to read a whole " +
+            "naming what isn't supported yet. A failure returns its message plus a JSON block with reason (e.g. sign_in_required " +
+            "for a YouTube bot check) and recovery steps for the user; never present a failed call as a read transcript. Each call returns at most maxChars characters (up to 100000); to read a whole " +
             "transcript, call again with offset set to the returned nextOffset until truncated is false. Read only — this " +
             "never marks the video as watched.",
         inputSchema: GetVideoTranscriptSchema,
@@ -178,11 +202,27 @@ export function registerGetVideoTranscript(server, apiClient, fetchImpl = fetch)
                     videoUrl: publicUrl,
                     platform,
                     hasTranscript: false,
+                    reason: "no_captions",
                     message: outcome.noTranscript,
                 });
             }
             if ("failed" in outcome) {
-                return errorResponse(outcome.failed);
+                // The message stays the first block, as it always was; the second
+                // carries the same failure in a shape a caller can branch on.
+                const failure = errorResponse(outcome.failed);
+                failure.content.push({
+                    type: "text",
+                    text: JSON.stringify({
+                        courseId,
+                        topicId,
+                        videoUrl: publicUrl,
+                        platform,
+                        hasTranscript: false,
+                        reason: outcome.reason,
+                        recovery: transcriptRecovery(outcome.reason, publicUrl),
+                    }),
+                });
+                return failure;
             }
             const { result } = outcome;
             const fullText = cuesToText(result.cues);

package/build/update.js

@@ -50,6 +50,74 @@ export function samePath(a, b) {
     };
     return canonical(a) === canonical(b);
 }
+const STABLE_VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
+function versionTriple(version) {
+    const m = STABLE_VERSION.exec(version.trim().replace(/^v/, ""));
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function compareTriples(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    return 0;
+}
+/**
+ * Whether `nodeVersion` meets an `engines.node` range. Only plain
+ * comparator sets (">=20.0.0", ">=20 <23") are understood; anything else
+ * yields null so the caller refuses instead of guessing.
+ */
+function satisfiesNodeRange(range, nodeVersion) {
+    const have = versionTriple(nodeVersion);
+    const comparators = range.trim().split(/\s+/);
+    if (!have || comparators.length === 0)
+        return null;
+    for (const comparator of comparators) {
+        const m = /^(>=|<=|>|<|=)?v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(comparator);
+        if (!m)
+            return null;
+        const want = [Number(m[2]), Number(m[3] ?? 0), Number(m[4] ?? 0)];
+        const cmp = compareTriples(have, want);
+        const ok = { ">=": cmp >= 0, "<=": cmp <= 0, ">": cmp > 0, "<": cmp < 0, "=": cmp === 0 }[m[1] ?? "="];
+        if (!ok)
+            return false;
+    }
+    return true;
+}
+/**
+ * Decide which commit a checkout should move to, from what npm reports as the
+ * `latest` release. Only a stable version, published from a known commit, whose
+ * Node.js requirement this runtime meets, is a target; anything else is refused
+ * so the update fails closed.
+ */
+export function chooseRelease(registry, nodeVersion) {
+    const info = (registry ?? {});
+    const { version, gitHead } = info;
+    if (typeof version !== "string" || !versionTriple(version)) {
+        return { ok: false, reason: "npm did not report a stable release version." };
+    }
+    if (typeof gitHead !== "string" || !COMMIT_SHA.test(gitHead)) {
+        return { ok: false, reason: `npm does not record which commit ${version} was published from.` };
+    }
+    const nodeRange = info.engines?.node;
+    if (nodeRange !== undefined) {
+        const satisfied = typeof nodeRange === "string" ? satisfiesNodeRange(nodeRange, nodeVersion) : null;
+        if (satisfied === null) {
+            return { ok: false, reason: `Cannot check ${version}'s Node.js requirement (${String(nodeRange)}).` };
+        }
+        if (!satisfied) {
+            return { ok: false, reason: `${version} requires Node.js ${nodeRange}; this is Node.js ${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 ==="));
@@ -88,18 +156,44 @@ export function main() {
         console.log(dim("  The update will proceed, but your local changes may conflict."));
         console.log("");
     }
-    // Fetch latest from remote
-    console.log(dim("  Fetching latest changes..."));
+    // Resolve the latest published release: the checkout follows what npm
+    // ships, never the unreleased tip of main.
+    console.log(dim("  Checking the latest release on npm..."));
+    let registry;
+    try {
+        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.");
+        return;
+    }
+    const release = chooseRelease(registry, process.version);
+    if (!release.ok) {
+        fail("No release this checkout can safely update to.", release.reason);
+        return;
+    }
+    const { version: targetVersion, commit } = release;
+    // Fetch, then confirm the published commit really is that release on main.
+    console.log(dim(`  Fetching release ${targetVersion}...`));
     try {
         run("git fetch origin main", { silent: true });
     }
     catch {
-        console.error(red("  Error: Failed to fetch from remote."));
-        console.error("  Check your network connection and try again.");
-        process.exit(1);
+        fail("Failed to fetch from remote.", "Check your network connection and try again.");
+        return;
+    }
+    try {
+        run(`git merge-base --is-ancestor ${commit} origin/main`, { silent: true });
+        const released = JSON.parse(run(`git show ${commit}:package.json`, { silent: true }));
+        if (released.version !== targetVersion)
+            throw new Error("version mismatch");
+    }
+    catch {
+        fail(`Could not verify release ${targetVersion} (commit ${commit.slice(0, 7)}) on origin/main.`, "Nothing was changed.");
+        return;
     }
     // Check if we're behind
-    const behindCount = run("git rev-list --count HEAD..origin/main", { silent: true });
+    const behindCount = run(`git rev-list --count HEAD..${commit}`, { silent: true });
     if (behindCount === "0") {
         console.log("");
         console.log(green("  Already up to date!"));
@@ -108,22 +202,21 @@ export function main() {
     }
     // Show what's new
     console.log("");
-    console.log(bold(`  ${behindCount} new commit${behindCount === "1" ? "" : "s"}:`));
+    console.log(bold(`  ${behindCount} new commit${behindCount === "1" ? "" : "s"} in ${targetVersion}:`));
     console.log("");
-    const log = run("git log HEAD..origin/main --oneline", { silent: true });
+    const log = run(`git log HEAD..${commit} --oneline`, { silent: true });
     for (const line of log.split("\n")) {
         console.log(`    ${dim("•")} ${line}`);
     }
     console.log("");
-    // Pull changes
-    console.log(dim("  Pulling changes..."));
+    // Move to the release
+    console.log(dim(`  Updating to ${targetVersion}...`));
     try {
-        run("git pull origin main", { silent: true });
+        run(`git merge --ff-only ${commit}`, { silent: true });
     }
     catch {
-        console.error(red("  Error: Failed to pull changes."));
-        console.error("  You may have merge conflicts. Resolve them manually and try again.");
-        process.exit(1);
+        fail(`Failed to update to ${targetVersion}.`, "Your checkout has local commits or changes in the way. Resolve them and try again.");
+        return;
     }
     // Install dependencies
     console.log(dim("  Installing dependencies..."));

package/build/utils/transcript/errors.js

@@ -12,8 +12,10 @@ export class NoTranscriptError extends Error {
 }
 /** The platform's API could not be reached or rejected the request. */
 export class TranscriptFetchError extends Error {
-    constructor(message) {
+    reason;
+    constructor(message, reason = "fetch_failed") {
         super(message);
+        this.reason = reason;
         this.name = "TranscriptFetchError";
     }
 }

package/build/utils/transcript/youtube.js

@@ -51,10 +51,10 @@ function trackLabel(track) {
 function playabilityFailure(status, reason) {
     const detail = reason ? ` YouTube said: ${reason}` : "";
     if (status === "LOGIN_REQUIRED") {
-        return new TranscriptFetchError(`YouTube would not serve this video without a sign-in.${detail}`);
+        return new TranscriptFetchError(`YouTube would not serve this video without a sign-in.${detail}`, "sign_in_required");
     }
     if (status === "UNPLAYABLE" || status === "ERROR") {
-        return new TranscriptFetchError(`YouTube reports this video as unavailable.${detail}`);
+        return new TranscriptFetchError(`YouTube reports this video as unavailable.${detail}`, "unavailable");
     }
     return new TranscriptFetchError(`YouTube refused to describe this video (${status}).${detail}`);
 }
@@ -140,7 +140,7 @@ export async function getYouTubeTranscript(videoId, fetchImpl, language = "en")
     }
     if (needsProofOfOrigin(track.baseUrl)) {
         throw new TranscriptFetchError("YouTube issued this caption track behind a proof-of-origin check this server cannot answer, " +
-            "so the captions could not be downloaded. The video may still have captions.");
+            "so the captions could not be downloaded. The video may still have captions.", "access_blocked");
     }
     const res = await fetchImpl(captionUrlAsVtt(track.baseUrl));
     if (!res.ok) {
@@ -152,7 +152,7 @@ export async function getYouTubeTranscript(videoId, fetchImpl, language = "en")
     // users looking for a transcript that was there all along.
     if (!body.trim()) {
         throw new TranscriptFetchError("YouTube listed a caption track for this video but served an empty response for it. " +
-            "This is usually a temporary block rather than a missing transcript; try again.");
+            "This is usually a temporary block rather than a missing transcript; try again.", "access_blocked");
     }
     const { format, cues } = parseCaptions(body);
     if (cues.length === 0) {

package/package.json

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