brightspace-mcp-server 5.0.2 → 5.0.4

package/README.md

@@ -69,14 +69,14 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 |-------|-----|
 | Grades | "Am I passing all my classes?" · "Compare my grades across courses" · "What did my professor say about Mini-Assignment 1?" (own assignment feedback is read from every route Brightspace documents for students) · "Is there feedback on my midterm?" (quiz-scored grades link to the quiz, since quiz feedback, including feedback only viewable in LockDown Browser, isn't readable through the API) |
 | Due dates | "What's due in the next 48 hours?" · "Build me a study schedule for the week" |
-| Assignments and rubrics | "What does the lab 4 spec actually ask for?" · "Why did I lose points on the analysis criterion?" |
+| Assignments and rubrics | "What does the lab 4 spec actually ask for?" · "Why did I lose points on the analysis criterion?" · "Did I turn in HW 3?" (if Brightspace won't give students their own submission list, the assignment's feedback page is checked instead; when neither shows a submission it's reported as unknown, never as missing) |
 | Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" (quizzes are collected from the quiz list, the course content, and the gradebook, so a closed quiz or one the list leaves out still shows up; each course says whether its quiz sources all answered, and if Brightspace refused one it's marked incomplete rather than passed off as everything; "complete" means every source answered, not that every quiz is guaranteed to be listed. A gradebook column linked to a quiz the list omits now shows up as a quiz with its dates and attempts instead of a bare grade-only row when the quiz can be read. Gradebook-only rows now also appear on tenants that send only the documented `GradeType` on grade columns; hidden grade columns, hidden assignments and inactive quizzes never produce one. Content quizzes beyond the first 30 per course are listed from the course content alone and the course is marked incomplete. Quiz rows may also say whether they are open, closed, or not yet open, and mark a quiz whose details Brightspace would not return; gradebook lookups for unlisted quizzes are capped at 20 per course, or 5 when the course's quiz tool can't be identified) |
 | Announcements | "Did any professor post something important today?" · "Read the file attached to today's announcement" |
 | Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "Search this course for office hours" · or just read a file inline instead of saving it |
 | 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-assignments.js

@@ -390,6 +390,23 @@ function quizCoverage(answered) {
 export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
     return (await fetchCourseInventory(apiClient, courseId, baseUrl)).assignments;
 }
+/**
+ * True when a student's own dropbox feedback page lists at least one
+ * submission. Brightspace renders each submission as a row of its
+ * submitted-files grid: the numeric submission ID in a <label>, then the
+ * submitted file links (span.dfl), then the date. This reads that structure,
+ * not the column titles, which are translated and are present even as headers
+ * of an otherwise empty grid. A page with "No submissions made for this
+ * assignment", a login page, or any other page has no such row.
+ */
+function feedbackPageListsSubmission(html) {
+    for (const row of html.matchAll(/<tr\b[^>]*>([\s\S]*?)<\/tr>/gi)) {
+        const cells = row[1];
+        if (/^\s*<td\b[^>]*>\s*<label>\s*\d+\s*<\/label>\s*<\/td>/i.test(cells) && /class="dfl"/i.test(cells))
+            return true;
+    }
+    return false;
+}
 /** A course's assignments and quizzes, with whether its quiz list is complete. */
 async function fetchCourseInventory(apiClient, courseId, baseUrl) {
     const assignments = [];
@@ -456,6 +473,22 @@ async function fetchCourseInventory(apiClient, courseId, baseUrl) {
                     log("DEBUG", `Could not determine submission state for folder ${folder.Id}`, error);
                 }
             }
+            // When the API refuses the list, the student's own feedback page may
+            // still show it. Only a listed submission counts: a page with none, or
+            // no page at all, leaves the state unknown rather than "not submitted".
+            let submissionSource = null;
+            if (!submissionsKnown && (folder.GroupTypeId === null || folder.GroupTypeId === undefined)) {
+                try {
+                    const html = await apiClient.getPage(`/d2l/lms/dropbox/user/folder_user_view_feedback.d2l?db=${folder.Id}&grpid=0&ou=${courseId}`);
+                    if (html !== null && feedbackPageListsSubmission(html))
+                        submissionSource = "feedbackPage";
+                }
+                catch (error) {
+                    if (isAuthUnavailable(error))
+                        throw error;
+                    log("DEBUG", `Feedback-page fallback failed for folder ${folder.Id}`, error);
+                }
+            }
             // Fetch feedback independently of submissions
             let feedback = null;
             let feedbackStatus = "unavailable";
@@ -550,12 +583,18 @@ async function fetchCourseInventory(apiClient, courseId, baseUrl) {
                 // when nothing is known, but submissionStatus tells apart "nothing
                 // was submitted" (404, a known answer) from "the answer is denied"
                 // (any other error), so a caller never states real work as missing.
-                submissionStatus: !submissionsKnown
-                    ? "unknown"
-                    : submissions.length > 0
-                        ? "submitted"
-                        : "not_submitted",
-                ...(submissionsKnown ? {} : {
+                submissionStatus: submissionSource
+                    ? "submitted"
+                    : !submissionsKnown
+                        ? "unknown"
+                        : submissions.length > 0
+                            ? "submitted"
+                            : "not_submitted",
+                ...(submissionSource ? {
+                    submissionSource,
+                    submissionStatusNote: "Brightspace did not return this assignment's submission list, but its feedback page lists a " +
+                        "submission, so it was submitted. File details are only shown on that page.",
+                } : submissionsKnown ? {} : {
                     submissionStatusNote: "Brightspace did not return this assignment's submission list, so whether it was submitted " +
                         "is unknown. Do not report it as missing or unsubmitted - tell the user to check Brightspace directly.",
                 }),

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.2",
+  "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",