brightspace-mcp-server 3.10.13 → 3.10.16

package/README.md

@@ -65,12 +65,13 @@ 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, including BoilerCast LTI links, and YouTube) |
@@ -105,7 +106,7 @@ All optional, set in your AI app's MCP `env` config or your shell. The full list
 
 ## When it asks you to sign in
 
-There's no separate login — asking a question signs you in, and it stays signed in on its own most days. When your school wants two-factor again, the number to approve shows up right in the answer; approve it on your phone and ask again. If your AI client shows tool progress messages, the number appears while the question is still running instead, and approving within 45 seconds (less if sign-in was slow to reach two-factor) finishes the original answer without asking again. If it ever gets stuck, run this in a terminal:
+There's no separate login — asking a question signs you in, and it stays signed in on its own most days. When your school wants two-factor again, the number to approve shows up right in the answer; approve it on your phone and the assistant keeps checking on its own — each check waits up to 45 seconds and the original question completes as soon as the sign-in does, without you having to say you've approved it. If your AI client shows tool progress messages, the number appears while the question is still running instead. If it ever gets stuck, run this in a terminal:
 
 ```bash
 npx -y brightspace-mcp-server@latest auth

package/build/auth/auth-runner.js

@@ -21,18 +21,13 @@ import { devActivity } from "../utils/dev-activity.js";
 const AUTH_TIMEOUT_MS = 8 * 60 * 1000;
 const KILL_GRACE_MS = 5000;
 /**
- * How long a caller that joins a background child already reported as
- * mfaPending waits for it before re-answering with the same challenge.
- * Long enough for an already-approved login to finish its next ~2s poll and
- * mint a token; short enough that a not-yet-approved one still answers
- * within this tool call instead of blocking for the rest of the 5-minute
- * approval window.
- */
-const JOIN_GRACE_MS = 5000;
-/**
- * How long a caller that can be told the challenge mid-call (see run()'s
- * onChallenge) keeps waiting for the background sign-in after the challenge
- * appears: long enough to find a phone and approve.
+ * How long a caller keeps waiting for the background sign-in once the
+ * challenge is known: long enough to find a phone and approve. Applies both
+ * to a caller told the challenge mid-call (see run()'s onChallenge) and to a
+ * retry that joins the background child after an early answer. The retry
+ * used to wait only 5 s, so on clients that send no progress token (Claude
+ * Desktop) every retry re-answered "enter the number" and the model asked
+ * the user to confirm by hand instead of the server polling for the approval.
  */
 const MFA_POLL_MS = 45000;
 /**
@@ -182,18 +177,20 @@ export class AuthRunner {
      * Authenticate, joining the login this process already started if there is
      * one. Returns true on success and throws a useful error on failure.
      *
-     * Without onChallenge, an MFA challenge answers the caller at once with an
-     * mfaPending error. With it, the caller is handed the challenge (the
-     * number to enter, if any) and keeps waiting on the background sign-in for
-     * up to MFA_POLL_MS, and never past CALL_BUDGET_MS from the call, so an
-     * approval within that window completes the caller's original request;
-     * past it, the caller gets the same mfaPending answer it would have had up
-     * front.
+     * Without onChallenge, a NEW sign-in answers the caller at once when an MFA
+     * challenge appears (an mfaPending error carrying the number to enter: the
+     * user cannot see it any other way), and the next call joins the background
+     * sign-in and polls it for up to MFA_POLL_MS, never past CALL_BUDGET_MS from
+     * that call. With onChallenge, the caller is handed the challenge mid-call
+     * and the first call itself keeps waiting the same way. Either way an
+     * approval within the window completes the caller's original request; past
+     * it, the caller gets the same mfaPending answer again and is expected to
+     * call once more.
      */
     async run(onChallenge) {
         const startedAt = Date.now();
         try {
-            return await this.runOnce();
+            return await this.runOnce(startedAt);
         }
         catch (error) {
             const childDone = this.childDone;
@@ -209,7 +206,7 @@ export class AuthRunner {
             return this.awaitBackgroundChild(childDone, windowMs);
         }
     }
-    runOnce() {
+    runOnce(startedAt) {
         if (this.inFlight) {
             log("DEBUG", "Joining the authentication already in flight");
             return this.inFlight;
@@ -220,7 +217,7 @@ export class AuthRunner {
         // cross-process lock and return "busy".
         if (this.childDone) {
             log("DEBUG", "Joining the background sign-in still running from an earlier call");
-            return this.joinBackgroundChild(this.childDone);
+            return this.joinBackgroundChild(this.childDone, startedAt);
         }
         // The latch is released by the flow that owns it, as it settles, so a
         // failed login is never replayed: the tool call after a declined MFA
@@ -237,23 +234,23 @@ export class AuthRunner {
     /**
      * Join a background child from an earlier early-answered call instead of
      * spawning a new one. A joiner must not simply await childDone: that
-     * blocks for whatever is left of the 5-minute approval window, exactly the
-     * problem run() otherwise fixes, since the caller usually retries right
-     * after reading "call this tool again" and well before actually approving.
+     * blocks for whatever is left of the 5-minute approval window, past the
+     * client's request timeout.
      *
      * If no challenge has been reported yet (the child hasn't reached MFA),
      * wait for one — or for the child to finish on its own. Once a challenge
-     * is known, race the child against a short grace window: fast enough for
-     * an already-approved login to land, short enough to re-answer with the
-     * same challenge rather than block.
+     * is known, poll the child for the rest of this call's budget: the user
+     * read the number from the previous answer and is approving right now, so
+     * this is the call that should carry the result. A still-unapproved
+     * sign-in re-answers with the latest challenge and the caller tries again.
      */
-    async joinBackgroundChild(childDone) {
+    async joinBackgroundChild(childDone, startedAt) {
         if (!this.pendingChallenge && this.challengeSignal) {
             await Promise.race([childDone.catch(() => { }), this.challengeSignal]);
         }
         if (!this.pendingChallenge)
             return childDone;
-        return this.awaitBackgroundChild(childDone, JOIN_GRACE_MS);
+        return this.awaitBackgroundChild(childDone, Math.max(0, pollWindowMs(Date.now() - startedAt)));
     }
     /**
      * Race a background child already past its MFA challenge against a wait

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/tool-helpers.js

@@ -98,8 +98,10 @@ const AUTH_FAILURE_GUIDANCE = {
         `Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to complete it with the number visible.`,
     failed: `The sign-in did not complete. Run \`${AUTH_COMMAND}\` in a terminal (from your home folder) to see why, ` +
         "or `brightspace-setup` if your saved school or username is wrong.",
-    mfaPending: "Approve the sign-in request on your phone (Microsoft Authenticator or Duo), " +
-        "then call this tool again — the sign-in is finishing in the background.",
+    mfaPending: "Approve the sign-in request on your phone (Microsoft Authenticator or Duo). " +
+        "Tell the user that, then call this tool again right away without waiting for them to " +
+        "confirm: each call waits up to 45 seconds for the approval and returns the result as soon " +
+        "as the sign-in completes. Keep calling until it succeeds or reports a different error.",
 };
 /**
  * mfaPending is the one kind whose guidance is partly dynamic: `numberMatch`
@@ -110,8 +112,10 @@ const AUTH_FAILURE_GUIDANCE = {
  */
 function authFailureMessage(error) {
     if (error.kind === "mfaPending" && error.numberMatch) {
-        return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes, ` +
-            "then call this tool again — the sign-in is finishing in the background.";
+        return `Open Microsoft Authenticator and enter ${error.numberMatch} within 5 minutes. ` +
+            "Tell the user that number, then call this tool again right away without waiting for them " +
+            "to confirm: each call waits up to 45 seconds for the approval and returns the result as " +
+            "soon as the sign-in completes. Keep calling until it succeeds or reports a different error.";
     }
     return AUTH_FAILURE_GUIDANCE[error.kind];
 }

package/package.json

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