brightspace-mcp-server 5.0.3 → 5.0.4

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/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.4",
   "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",