brightspace-mcp-server 3.10.11 → 3.10.15

package/README.md

@@ -65,15 +65,16 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 
 | About | Try |
 |-------|-----|
-| Grades | "Am I passing all my classes?" · "Compare my grades across courses" |
+| Grades | "Am I passing all my classes?" · "Compare my grades across courses" · "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?" |
 | Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" |
 | 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 and YouTube) |
+| Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura, including BoilerCast LTI links, and YouTube) |
 | 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 see a clear "instructor access required" note) |
 

package/build/api/client.js

@@ -300,6 +300,28 @@ export class D2LApiClient {
         const resolved = await this.resolvePath(path);
         return this.withAuthentication(resolved, token => this.makeRawRequest(resolved, token));
     }
+    /**
+     * Fetch a Brightspace web page (not an API route) as the signed-in user.
+     * Pages check the session cookie and ignore a Bearer token, so this sends
+     * the stored cookie. Returns null when no cookie is stored or the page
+     * answers with the login redirect: it never starts a login, since a page
+     * read by a read-only tool is not worth an MFA prompt.
+     */
+    async getPage(path) {
+        const token = await this.tokenManager.getToken();
+        if (!token?.cookieHeader)
+            return null;
+        const cookieToken = { ...token, accessToken: `cookie:${token.cookieHeader}` };
+        try {
+            const response = await this.retrying(() => this.throttled(() => this.makeRawRequest(path, cookieToken)));
+            return await response.text();
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 401)
+                return null;
+            throw error;
+        }
+    }
     /** One HTTP refresh and at most one browser login per caller. */
     async withAuthentication(path, request) {
         let token = await this.tokenManager.getToken();

package/build/tools/get-my-grades.js

@@ -9,7 +9,58 @@ import { GetMyGradesSchema, } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable, authPendingNotice, } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
-import { gradebookUrl } from "../utils/deep-links.js";
+import { gradebookUrl, quizUrl } from "../utils/deep-links.js";
+/**
+ * The quiz a grade row is scored from can hold feedback the gradebook does
+ * not, and the student API cannot read it: quiz attempts are refused to
+ * students, and some quizzes only show feedback inside a restricted viewer.
+ */
+const QUIZ_FEEDBACK_NOTE = "The gradebook has no comment for this item, but it is scored from a quiz, and quiz " +
+    "feedback lives on the quiz's own submissions page, which Brightspace does not expose " +
+    "to the student API. Feedback may exist there, sometimes viewable only in a restricted " +
+    "browser such as Respondus LockDown Browser. Open feedbackUrl to check; do not report " +
+    "this item as having no feedback.";
+/**
+ * The course's quizzes, or none when the route refuses or fails. A missing
+ * quiz list only costs the feedback links, never the grades themselves.
+ */
+async function fetchQuizzes(apiClient, courseId) {
+    try {
+        const raw = await apiClient.get(apiClient.le(courseId, "/quizzes/"), { ttl: DEFAULT_CACHE_TTLS.assignments });
+        return Array.isArray(raw) ? raw : raw?.Objects ?? [];
+    }
+    catch (error) {
+        log("DEBUG", `get_my_grades: quiz list unavailable for course ${courseId}`, error);
+        return [];
+    }
+}
+/**
+ * Clean grade rows. Rows scored from a quiz also carry feedbackUrl, and a
+ * feedbackNote when the gradebook comment is empty; other rows are unchanged.
+ */
+function toGradeItems(gradeValues, quizzes, baseUrl, courseId) {
+    const quizByGradeItem = new Map(quizzes
+        .filter((q) => q.GradeItemId != null)
+        .map((q) => [String(q.GradeItemId), q.QuizId]));
+    return gradeValues.map((gv) => {
+        const comments = gv.Comments?.Text || null;
+        const quizId = quizByGradeItem.get(String(gv.GradeObjectIdentifier));
+        return {
+            name: gv.GradeObjectName,
+            displayGrade: gv.DisplayedGrade,
+            pointsNumerator: gv.PointsNumerator,
+            pointsDenominator: gv.PointsDenominator,
+            weightedNumerator: gv.WeightedNumerator,
+            weightedDenominator: gv.WeightedDenominator,
+            comments,
+            lastModified: gv.LastModified,
+            ...(quizId === undefined ? {} : {
+                feedbackUrl: quizUrl(baseUrl, courseId, quizId),
+                ...(comments ? {} : { feedbackNote: QUIZ_FEEDBACK_NOTE }),
+            }),
+        };
+    });
+}
 /**
  * Register get_my_grades tool
  */
@@ -26,6 +77,7 @@ export function registerGetMyGrades(server, apiClient, config) {
             // Single course case
             if (courseId) {
                 const path = apiClient.le(courseId, "/grades/values/myGradeValues/");
+                const quizzesPromise = fetchQuizzes(apiClient, courseId);
                 let gradeValues;
                 try {
                     gradeValues = await apiClient.get(path, {
@@ -65,16 +117,7 @@ export function registerGetMyGrades(server, apiClient, config) {
                     throw error;
                 }
                 // Map to clean objects
-                const grades = gradeValues.map((gv) => ({
-                    name: gv.GradeObjectName,
-                    displayGrade: gv.DisplayedGrade,
-                    pointsNumerator: gv.PointsNumerator,
-                    pointsDenominator: gv.PointsDenominator,
-                    weightedNumerator: gv.WeightedNumerator,
-                    weightedDenominator: gv.WeightedDenominator,
-                    comments: gv.Comments?.Text || null,
-                    lastModified: gv.LastModified,
-                }));
+                const grades = toGradeItems(gradeValues, await quizzesPromise, config.baseUrl, courseId);
                 log("INFO", `get_my_grades: Retrieved ${grades.length} grade items for course ${courseId}`);
                 return toolResponse({ courseId, grades });
             }
@@ -102,19 +145,11 @@ export function registerGetMyGrades(server, apiClient, config) {
             const gradePromises = filteredEnrollments.map(async (item) => {
                 try {
                     const path = apiClient.le(item.OrgUnit.Id, "/grades/values/myGradeValues/");
-                    const gradeValues = await apiClient.get(path, {
-                        ttl: DEFAULT_CACHE_TTLS.grades,
-                    });
-                    const grades = gradeValues.map((gv) => ({
-                        name: gv.GradeObjectName,
-                        displayGrade: gv.DisplayedGrade,
-                        pointsNumerator: gv.PointsNumerator,
-                        pointsDenominator: gv.PointsDenominator,
-                        weightedNumerator: gv.WeightedNumerator,
-                        weightedDenominator: gv.WeightedDenominator,
-                        comments: gv.Comments?.Text || null,
-                        lastModified: gv.LastModified,
-                    }));
+                    const [gradeValues, quizzes] = await Promise.all([
+                        apiClient.get(path, { ttl: DEFAULT_CACHE_TTLS.grades }),
+                        fetchQuizzes(apiClient, item.OrgUnit.Id),
+                    ]);
+                    const grades = toGradeItems(gradeValues, quizzes, config.baseUrl, item.OrgUnit.Id);
                     return {
                         restricted: false,
                         courseId: item.OrgUnit.Id,

package/build/tools/get-syllabus.js

@@ -13,13 +13,61 @@ import { extractPdfText } from "../utils/pdf-extractor.js";
 import { log } from "../utils/logger.js";
 import path from "node:path";
 import fs from "node:fs/promises";
+const SYLLABUS_PATTERN = /syllab/i;
+const LTI_LAUNCH_PATTERN = /[?&]type=lti\b|\/d2l\/le\/lti\//i;
+const EXTERNAL_SYLLABUS_NOTE = "This course links its syllabus through an external LTI tool. The server lists these sources but cannot launch LTI tools, so their contents are not included; open the link in Brightspace to read it.";
+/** Launch URL without its query string, which can carry launch parameters. */
+function stripQuery(url) {
+    return url.split(/[?#]/)[0];
+}
+/**
+ * Pick the syllabus-related LTI sources out of the course's LTI links and
+ * content tree. Pure: the caller fetches, this only decides.
+ */
+function findExternalSyllabusSources(ltiLinks, toc) {
+    const sources = ltiLinks
+        .filter((l) => l.IsVisible !== false && (SYLLABUS_PATTERN.test(l.Title) || SYLLABUS_PATTERN.test(l.Url)))
+        .map((l) => ({ title: l.Title, location: "lti-link", url: stripQuery(l.Url) }));
+    const walk = (modules) => {
+        for (const m of modules) {
+            for (const t of m.Topics ?? []) {
+                if (t.Url && LTI_LAUNCH_PATTERN.test(t.Url) && SYLLABUS_PATTERN.test(t.Title)) {
+                    sources.push({ title: t.Title, location: "content", url: t.Url });
+                }
+            }
+            walk(m.Modules ?? []);
+        }
+    };
+    walk(toc);
+    return sources;
+}
+/** Fetch a lookup that students may not be permitted to make; failure means "none". */
+async function fetchOrEmpty(fetch, fallback, what) {
+    try {
+        return await fetch();
+    }
+    catch (error) {
+        log("DEBUG", `get_syllabus: could not read ${what}`, error);
+        return fallback;
+    }
+}
+async function discoverExternalSyllabusSources(apiClient, courseId) {
+    const [ltiLinks, toc] = await Promise.all([
+        fetchOrEmpty(() => apiClient.get(apiClient.leGlobal(`/lti/link/${courseId}/`), { ttl: DEFAULT_CACHE_TTLS.courseContent }), [], "LTI links"),
+        fetchOrEmpty(() => apiClient.get(apiClient.le(courseId, "/content/toc"), { ttl: DEFAULT_CACHE_TTLS.courseContent }), {}, "content table of contents"),
+    ]);
+    const sources = findExternalSyllabusSources(ltiLinks ?? [], toc?.Modules ?? []);
+    return sources.length > 0
+        ? { externalSyllabusSources: sources, externalSyllabusNote: EXTERNAL_SYLLABUS_NOTE }
+        : {};
+}
 /**
  * Register get_syllabus tool
  */
 export function registerGetSyllabus(server, apiClient) {
     server.registerTool("get_syllabus", {
         title: "Get Course Syllabus",
-        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
+        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. When the syllabus lives in an external LTI tool (e.g. Simple Syllabus), lists those sources in externalSyllabusSources; their contents cannot be read. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
         inputSchema: GetSyllabusSchema,
     }, async (args) => {
         try {
@@ -55,6 +103,7 @@ export function registerGetSyllabus(server, apiClient) {
                         description: null,
                         hasAttachment: false,
                         message: "No syllabus/overview found for this course.",
+                        ...(await discoverExternalSyllabusSources(apiClient, courseId)),
                     });
                 }
                 throw error;
@@ -152,6 +201,7 @@ export function registerGetSyllabus(server, apiClient) {
             if (download) {
                 result.download = download;
             }
+            Object.assign(result, await discoverExternalSyllabusSources(apiClient, courseId));
             return toolResponse(result);
         }
         catch (error) {

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

@@ -8,6 +8,7 @@ import { GetVideoTranscriptSchema } from "./schemas.js";
 import { toolResponse, errorResponse, sanitizeError } from "./tool-helpers.js";
 import { cuesToText, paginateText } from "../utils/transcript/captions.js";
 import { detectVideoPlatform, extractKalturaIds, extractYouTubeVideoId, } from "../utils/transcript/platform.js";
+import { isBrightspaceRelativeLink, readLtiLaunchPage } 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";
@@ -28,6 +29,24 @@ async function resolveVideoUrl(apiClient, courseId, topicId) {
     }
     return { url: topic.Url };
 }
+/** The quickLink itself, plus one Brightspace page it frames (the tool launch). */
+const MAX_LTI_PAGES = 2;
+/** Request a Brightspace LTI link as the user and read its launch for the video it opens. */
+async function followLtiLaunch(apiClient, path) {
+    let next = path;
+    for (let page = 0; page < MAX_LTI_PAGES; page++) {
+        const html = await apiClient.getPage(next);
+        if (html === null)
+            return null;
+        const finding = readLtiLaunchPage(html);
+        if (!finding)
+            return null;
+        if ("videoUrl" in finding)
+            return finding.videoUrl;
+        next = finding.nextPath;
+    }
+    return null;
+}
 async function fetchTranscript(platform, videoUrl, fetchImpl) {
     switch (platform) {
         case "kaltura": {
@@ -92,7 +111,7 @@ export function registerGetVideoTranscript(server, apiClient, fetchImpl = fetch)
         description: "Read the transcript of a video embedded in course content, such as a recorded lecture or explainer clip. " +
             "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) and YouTube; other platforms return a clear message " +
+            "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. Use offset/maxChars to page through a long transcript. Read only — this " +
             "never marks the video as watched.",
         inputSchema: GetVideoTranscriptSchema,
@@ -114,6 +133,22 @@ export function registerGetVideoTranscript(server, apiClient, fetchImpl = fetch)
             else {
                 return errorResponse("Provide either videoUrl, or both courseId and topicId to look up the video from course content.");
             }
+            if (isBrightspaceRelativeLink(resolvedUrl)) {
+                const launchedUrl = await followLtiLaunch(apiClient, resolvedUrl);
+                if (!launchedUrl) {
+                    return toolResponse({
+                        courseId,
+                        topicId,
+                        videoUrl: resolvedUrl,
+                        platform: "unknown",
+                        hasTranscript: false,
+                        message: `This is a Brightspace LTI link (${resolvedUrl}), and its launch did not reveal which video it opens. ` +
+                            "Some tools only hand over the video after a browser sign-in to the tool itself, which this server " +
+                            "can't do. The video platform itself may still be supported. Open it in Brightspace directly.",
+                    });
+                }
+                resolvedUrl = launchedUrl;
+            }
             const platform = detectVideoPlatform(resolvedUrl);
             const outcome = await fetchTranscript(platform, resolvedUrl, fetchImpl);
             if ("unsupported" in outcome) {

package/build/utils/transcript/lti.js

@@ -0,0 +1,86 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+/**
+ * Brightspace hands out an LTI tool (BoilerCast's Kaltura KAF, for one) as a
+ * relative quickLink such as `/d2l/common/dialogs/quickLink/quickLink.d2l?type=lti&rcode=...`,
+ * which names no video at all. Requesting it with the user's session yields
+ * the LTI launch page: an auto-submitting form whose action, or one of whose
+ * hidden fields, is the tool URL that does name the video. This reads that
+ * page; fetching it is the caller's job.
+ */
+import { detectVideoPlatform, extractKalturaIds, extractYouTubeVideoId } from "./platform.js";
+/** A link into the user's own Brightspace, which only an authenticated request can follow. */
+export function isBrightspaceRelativeLink(url) {
+    return url.startsWith("/d2l/");
+}
+function decodeEntities(value) {
+    return value
+        .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(parseInt(hex, 16)))
+        .replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(parseInt(dec, 10)))
+        .replace(/"/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+function tagAttributes(html, tag) {
+    return [...html.matchAll(new RegExp(`<${tag}\\b[^>]*>`, "gi"))].map(element => new Map([...element[0].matchAll(/([\w-]+)\s*=\s*(["'])([\s\S]*?)\2/g)].map(match => [
+        match[1].toLowerCase(),
+        decodeEntities(match[3]),
+    ])));
+}
+/** True when an adapter could fetch a transcript from `url`, or name the platform it can't yet. */
+function namesVideo(url) {
+    switch (detectVideoPlatform(url)) {
+        case "unknown":
+            return false;
+        case "kaltura":
+            return extractKalturaIds(url) !== null;
+        case "youtube":
+            return extractYouTubeVideoId(url) !== null;
+        default:
+            return true;
+    }
+}
+/**
+ * Kaltura KAF's LTI consumer key is the school's Kaltura partner ID, and a
+ * school-branded KAF launch URL often carries only the entry ID, so the key
+ * fills in the `wid` the URL left out.
+ */
+function asVideoUrl(candidate, consumerKey) {
+    if (!/^https?:\/\//i.test(candidate))
+        return null;
+    if (namesVideo(candidate))
+        return candidate;
+    if (!consumerKey || !/^\d+$/.test(consumerKey))
+        return null;
+    let withPartner;
+    try {
+        withPartner = new URL(candidate);
+    }
+    catch {
+        return null;
+    }
+    if (withPartner.searchParams.has("wid"))
+        return null;
+    withPartner.searchParams.set("wid", `_${consumerKey}`);
+    return namesVideo(withPartner.href) ? withPartner.href : null;
+}
+export function readLtiLaunchPage(html) {
+    const inputs = tagAttributes(html, "input");
+    const consumerKey = inputs.find(input => input.get("name") === "oauth_consumer_key")?.get("value");
+    const candidates = [
+        ...tagAttributes(html, "form").map(form => form.get("action")),
+        ...tagAttributes(html, "iframe").map(frame => frame.get("src")),
+        ...inputs.map(input => input.get("value")),
+    ].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        const videoUrl = asVideoUrl(candidate, consumerKey);
+        if (videoUrl)
+            return { videoUrl };
+    }
+    const nextPath = candidates.find(isBrightspaceRelativeLink);
+    return nextPath ? { nextPath } : null;
+}

package/package.json

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