brightspace-mcp-server 3.13.17 → 3.13.18

package/README.md

@@ -68,7 +68,7 @@ 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?" |
-| Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" |
+| 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) |

package/build/tools/get-assignments.js

@@ -10,7 +10,7 @@ import { toolResponse, sanitizeError, isAuthUnavailable, authPendingNotice } fro
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
-import { gradebookUrl, quizUrl } from "../utils/deep-links.js";
+import { contentTopicUrl, gradebookUrl, quizUrl } from "../utils/deep-links.js";
 import { assignmentLinkResolver } from "./assignment-links.js";
 import { dueIn } from "../utils/due-in.js";
 import { feedbackText, FEEDBACK_UNAVAILABLE_NOTE } from "../utils/feedback.js";
@@ -24,36 +24,127 @@ function richTextHtml(field) {
     return nested ?? field.Html ?? null;
 }
 /**
- * The grade object types a student is actually scored on: 1 numeric,
- * 2 passfail, 3 selectbox, 4 text. The rest (category, calculated, formula,
- * final) are the gradebook's own arithmetic, not work anybody owes.
+ * The grade types a student is actually scored on. D2L documents exactly four
+ * GradeObject shapes, told apart by a string GradeType; anything else a
+ * gradebook lists (category, calculated, formula, final grade) is the
+ * gradebook's own arithmetic, not work anybody owes. Those are not documented
+ * as GradeType values, so a column is excluded when its GradeType is some
+ * other string, and a calculated column also carries no AssociatedTool.
  */
+const STUDENT_SCORED_TYPES = new Set(["numeric", "passfail", "selectbox", "text"]);
+/** The numeric GRADEOBJ_T values for the same four types: 1 numeric, 2 passfail, 3 selectbox, 4 text. */
 const STUDENT_SCORED = new Set([1, 2, 3, 4]);
-/** Quiz topics visible in course content but absent from the quiz listing. */
-function missingContentQuizTopics(raw, listedIds) {
+function isStudentScored(column) {
+    if (!column || typeof column !== "object")
+        return false;
+    if (typeof column.GradeType === "string" && STUDENT_SCORED_TYPES.has(column.GradeType.toLowerCase()))
+        return true;
+    return STUDENT_SCORED.has(column.GradeObjectTypeId);
+}
+/** The columns a student is scored on, from whatever the grades route returned. */
+function studentScoredColumns(gradebook) {
+    if (!Array.isArray(gradebook))
+        return [];
+    return gradebook.filter((c) => isStudentScored(c) && typeof c.Id === "number");
+}
+/** The quiz id a content topic points at, or null when it carries none. */
+function contentQuizId(topic) {
+    const candidates = [
+        topic.ToolItemId,
+        Number(topic.ActivityId),
+        // quiz_summary.d2l?qi=N and quiz_start_frame_auto.d2l?qi=N: the same qi
+        // parameter quizUrl() builds, present when ToolItemId is not.
+        Number(/(?:[?&]|&)qi=(\d+)(?:[&#]|$)/i.exec(topic.Url ?? "")?.[1]),
+    ];
+    for (const id of candidates) {
+        if (typeof id === "number" && Number.isSafeInteger(id) && id > 0)
+            return id;
+    }
+    return null;
+}
+/** Titles compare by words, not by case or spacing, so a topic can be matched to a listed quiz. */
+function normalizedTitle(title) {
+    return typeof title === "string" ? title.trim().replace(/\s+/g, " ").toLowerCase() : "";
+}
+/** Every quiz topic in a table of contents, depth first, hidden or broken ones included. */
+function quizTopicsOf(raw) {
     if (!raw || typeof raw !== "object")
         return [];
-    const found = new Map();
-    const visit = (modules) => {
-        if (!Array.isArray(modules))
+    const found = [];
+    const visit = (modules, depth) => {
+        if (!Array.isArray(modules) || depth > 50)
             return;
         for (const module of modules) {
             for (const topic of module.Topics ?? []) {
                 const isQuiz = topic.ActivityType === 4
                     || topic.TypeIdentifier?.toLowerCase() === "quiz"
-                    || /(?:[?&]|&)type=quiz(?:[&#]|$)/i.test(topic.Url ?? "");
-                if (!isQuiz || topic.IsHidden || topic.IsBroken || topic.IsExempt)
-                    continue;
-                const activityId = topic.ToolItemId ?? Number(topic.ActivityId);
-                if (!Number.isSafeInteger(activityId) || activityId <= 0 || listedIds.has(activityId))
-                    continue;
-                if (!found.has(activityId))
-                    found.set(activityId, topic);
+                    || /(?:[?&]|&amp;)type=quiz(?:[&#]|$)/i.test(topic.Url ?? "")
+                    || /\/lms\/quizzing\/user\/quiz_/i.test(topic.Url ?? "");
+                if (isQuiz)
+                    found.push(topic);
             }
-            visit(module.Modules);
+            visit(module.Modules, depth + 1);
         }
     };
-    visit(raw.Modules);
+    visit(raw.Modules, 0);
+    return found;
+}
+/**
+ * The quiz tool's id as content quiz topics report it (ToolId, documented on
+ * every ToC topic). Tells the gradebook probe which columns belong to quizzes.
+ */
+function contentQuizToolIds(raw) {
+    return new Set(quizTopicsOf(raw)
+        .map((topic) => topic.ToolId)
+        .filter((id) => typeof id === "number" && Number.isSafeInteger(id) && id > 0));
+}
+/**
+ * The quiz id behind a topic that names none, when the grade column the topic
+ * writes to (GradeItemId, documented on ToC topics) is linked to a tool item.
+ * A column of a different tool than the topic's is not the topic's quiz.
+ */
+function quizIdFromGradeColumn(topic, columnsById) {
+    if (typeof topic.GradeItemId !== "number")
+        return null;
+    const tool = columnsById.get(topic.GradeItemId)?.AssociatedTool;
+    const itemId = tool?.ToolItemId;
+    if (typeof itemId !== "number" || !Number.isSafeInteger(itemId) || itemId <= 0)
+        return null;
+    if (typeof topic.ToolId === "number" && typeof tool?.ToolId === "number" && topic.ToolId !== tool.ToolId) {
+        return null;
+    }
+    return itemId;
+}
+/**
+ * Quiz topics visible in course content but absent from the quiz listing.
+ * Topics are returned once each. Those that name a quiz (directly, or through
+ * their grade column) are keyed by id; one that names none is kept only if no
+ * listed quiz carries its title, and one linked from several modules is kept
+ * once, recognized by its title and link.
+ */
+function missingContentQuizTopics(raw, listedIds, listedTitles, columnsById) {
+    const found = new Map();
+    for (const topic of quizTopicsOf(raw)) {
+        // A hidden or broken topic is not something the student can open. An
+        // exempt one (IsExempt: the user is exempt from the topic, per the
+        // content docs) is still listed, and flagged as exempt on its row.
+        if (topic.IsHidden || topic.IsBroken)
+            continue;
+        const quizId = contentQuizId(topic) ?? quizIdFromGradeColumn(topic, columnsById);
+        if (quizId !== null) {
+            if (listedIds.has(quizId))
+                continue;
+        }
+        else if (listedTitles.has(normalizedTitle(topic.Title))) {
+            continue;
+        }
+        const url = (topic.Url ?? "").trim();
+        const key = quizId !== null
+            ? `quiz:${quizId}`
+            : url !== "" ? `link:${normalizedTitle(topic.Title)}|${url}` : `topic:${topic.TopicId}`;
+        if (!found.has(key))
+            found.set(key, { topic, quizId });
+    }
     return [...found.values()];
 }
 /**
@@ -62,40 +153,234 @@ function missingContentQuizTopics(raw, listedIds) {
  * us the normal full shape. If that route is also unavailable, the content
  * topic still provides enough information to avoid silently hiding the work.
  */
-async function recoverContentQuizzes(apiClient, courseId, toc, listedIds) {
-    return Promise.all(missingContentQuizTopics(toc, listedIds).map(async (topic) => {
-        const quizId = topic.ToolItemId ?? Number(topic.ActivityId);
-        try {
-            return await apiClient.get(apiClient.le(courseId, `/quizzes/${quizId}`), {
-                ttl: DEFAULT_CACHE_TTLS.assignments,
-            });
-        }
-        catch (error) {
-            if (isAuthUnavailable(error))
-                throw error;
-            log("DEBUG", `Failed to fetch content-linked quiz ${quizId}: using content metadata`, error);
+async function recoverContentQuizzes(apiClient, courseId, toc, listedIds, listedTitles, columnsById) {
+    const topics = missingContentQuizTopics(toc, listedIds, listedTitles, columnsById);
+    // Only the first topics are asked for their details; the rest are listed
+    // from the table of contents alone, so a huge course costs a bounded number
+    // of requests and no quiz is dropped.
+    const readable = Math.min(topics.length, MAX_CONTENT_QUIZ_RECOVERIES);
+    const found = await Promise.all(topics.map(async ({ topic, quizId }, index) => {
+        const exempt = topic.IsExempt === true ? { exempt: true } : {};
+        const mayRead = index < MAX_CONTENT_QUIZ_RECOVERIES;
+        if (mayRead && quizId !== null) {
+            try {
+                const quiz = await apiClient.get(apiClient.le(courseId, `/quizzes/${quizId}`), {
+                    ttl: DEFAULT_CACHE_TTLS.assignments,
+                });
+                return { quiz, source: "courseContent", topicId: topic.TopicId, ...exempt };
+            }
+            catch (error) {
+                if (isAuthUnavailable(error))
+                    throw error;
+                log("DEBUG", `Failed to fetch content-linked quiz ${quizId}: using content metadata`, error);
+            }
         }
         let detail = topic;
+        if (mayRead) {
+            try {
+                detail = await apiClient.get(apiClient.le(courseId, `/content/topics/${topic.TopicId}`), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+            }
+            catch (error) {
+                if (isAuthUnavailable(error))
+                    throw error;
+                log("DEBUG", `Failed to fetch content topic ${topic.TopicId}: using table-of-contents metadata`, error);
+            }
+        }
+        return {
+            source: "courseContent",
+            topicId: topic.TopicId,
+            ...exempt,
+            quiz: {
+                QuizId: quizId,
+                Name: detail.Title || topic.Title,
+                Description: detail.Description ?? null,
+                StartDate: detail.StartDate ?? detail.StartDateTime ?? topic.StartDateTime ?? null,
+                EndDate: detail.EndDate ?? detail.EndDateTime ?? topic.EndDateTime ?? null,
+                DueDate: detail.DueDate ?? null,
+                IsActive: true,
+                AttemptsAllowed: null,
+                ContentMetadataOnly: true,
+            },
+        };
+    }));
+    return { found, considered: topics.length, read: readable };
+}
+/**
+ * Content quizzes per course whose own record (and, failing that, content
+ * topic) is read. Each may cost two requests, so a course costs at most 60.
+ * Past the cap a quiz is still listed, from the table of contents alone, and
+ * the course's quizCoverage says the cap applied.
+ */
+const MAX_CONTENT_QUIZ_RECOVERIES = 30;
+/**
+ * Probes per course. A course whose quiz tool is known (a listed or content
+ * quiz sits on it) is asked about that tool's other columns, up to 20. With no
+ * known quiz tool every non-dropbox column is a candidate, so far fewer are
+ * asked: most of them are discussions, surveys or manual items.
+ */
+const MAX_GRADEBOOK_QUIZ_PROBES = 20;
+const MAX_UNTARGETED_GRADEBOOK_QUIZ_PROBES = 5;
+/**
+ * A quiz read that answered 404 or 403 will answer the same again soon, so it
+ * is not repeated for ten minutes. Kept per client (so per signed-in account)
+ * and only for those two answers: a 401 is a sign-in matter and a 5xx or a
+ * network failure may pass.
+ */
+const PROBE_REFUSAL_TTL_MS = 10 * 60 * 1000;
+const refusedProbes = new WeakMap();
+function probeRecentlyRefused(apiClient, path, now) {
+    const until = refusedProbes.get(apiClient)?.get(path);
+    if (until === undefined)
+        return false;
+    if (until > now)
+        return true;
+    refusedProbes.get(apiClient).delete(path);
+    return false;
+}
+function rememberRefusedProbe(apiClient, path, now) {
+    let paths = refusedProbes.get(apiClient);
+    if (!paths) {
+        paths = new Map();
+        refusedProbes.set(apiClient, paths);
+    }
+    paths.set(path, now + PROBE_REFUSAL_TTL_MS);
+}
+/**
+ * Quizzes behind gradebook columns that nothing else accounted for. A column
+ * linked to a tool item (AssociatedTool) the quiz list and content both omit
+ * may still be a quiz the student can read by id, so it is asked for once.
+ * The answer is accepted only when the quiz names that very column as its
+ * GradeItemId: a discussion or survey that happens to share the id answers
+ * 404 or names a different column, and stays a bare gradebook row.
+ *
+ * A column the instructor hid from students is not asked. The folder ids
+ * include hidden folders, whose columns are never asked either.
+ * Tools already seen on a dropbox folder are not asked; once a quiz tool is
+ * known (from a listed or content quiz), only that tool's other columns are.
+ * A column named like an id-less content quiz is that quiz, not a new one.
+ */
+async function recoverGradebookQuizzes(apiClient, courseId, columns, folderIds, quizIds, contentQuizTools, idlessQuizTitles) {
+    const toolIdsOf = (ids) => new Set(columns
+        .filter((c) => ids.has(c.AssociatedTool?.ToolItemId))
+        .map((c) => c.AssociatedTool.ToolId));
+    const quizTools = new Set([...toolIdsOf(quizIds), ...contentQuizTools]);
+    const folderTools = toolIdsOf(folderIds);
+    const now = Date.now();
+    const candidates = columns
+        .filter((c) => {
+        const itemId = c.AssociatedTool?.ToolItemId;
+        if (typeof itemId !== "number" || !Number.isSafeInteger(itemId) || itemId <= 0)
+            return false;
+        if (c.IsHidden === true)
+            return false;
+        if (quizIds.has(itemId) || folderIds.has(itemId))
+            return false;
+        if (idlessQuizTitles.has(normalizedTitle(c.Name)))
+            return false;
+        if (probeRecentlyRefused(apiClient, apiClient.le(courseId, `/quizzes/${itemId}`), now))
+            return false;
+        if (quizTools.size > 0)
+            return quizTools.has(c.AssociatedTool.ToolId);
+        return !folderTools.has(c.AssociatedTool.ToolId);
+    })
+        .slice(0, quizTools.size > 0 ? MAX_GRADEBOOK_QUIZ_PROBES : MAX_UNTARGETED_GRADEBOOK_QUIZ_PROBES);
+    const found = await Promise.all(candidates.map(async (column) => {
+        const itemId = column.AssociatedTool.ToolItemId;
+        const path = apiClient.le(courseId, `/quizzes/${itemId}`);
         try {
-            detail = await apiClient.get(apiClient.le(courseId, `/content/topics/${topic.TopicId}`), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+            const quiz = await apiClient.get(path, { ttl: DEFAULT_CACHE_TTLS.assignments });
+            if (quiz?.QuizId === itemId && quiz.GradeItemId === column.Id) {
+                return { quiz, source: "gradebook" };
+            }
         }
         catch (error) {
             if (isAuthUnavailable(error))
                 throw error;
-            log("DEBUG", `Failed to fetch content topic ${topic.TopicId}: using table-of-contents metadata`, error);
+            if (error?.status === 404 || error?.status === 403)
+                rememberRefusedProbe(apiClient, path, now);
+            log("DEBUG", `Gradebook column ${column.Id} is not a readable quiz (${itemId})`, error);
         }
-        return {
-            QuizId: quizId,
-            Name: detail.Title || topic.Title,
-            Description: detail.Description ?? null,
-            StartDate: detail.StartDate ?? detail.StartDateTime ?? topic.StartDateTime ?? null,
-            EndDate: detail.EndDate ?? detail.EndDateTime ?? topic.EndDateTime ?? null,
-            DueDate: detail.DueDate ?? null,
-            IsActive: true,
-            AttemptsAllowed: null,
-            ContentMetadataOnly: true,
-        };
+        return null;
     }));
+    return found.filter((item) => item !== null);
+}
+/**
+ * The content table of contents with date-restricted items included. D2L's
+ * default view omits modules and topics outside their date window, which is
+ * exactly where a closed (or not yet opened) quiz sits; ignoreDateRestrictions
+ * is documented to be open to students, and supported from LE 1.67, which the
+ * client's latest version covers. D2L documents that unsupported parameters
+ * are ignored, so the plain view is only a fallback for a request the tenant
+ * rejects outright (400, 403, 404), reported as such so coverage is not
+ * overstated. Anything else (429, a 5xx, a dropped connection) says nothing
+ * about the parameter, so it is not retried here: the content counts as unread.
+ */
+async function fetchContentToc(apiClient, courseId) {
+    try {
+        const toc = await apiClient.get(apiClient.le(courseId, "/content/toc?ignoreDateRestrictions=true&ignoreModuleDateRestrictions=true"), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+        return { toc, datesIncluded: true };
+    }
+    catch (error) {
+        if (isAuthUnavailable(error))
+            throw error;
+        const status = error?.status;
+        if (status !== 400 && status !== 403 && status !== 404)
+            throw error;
+        log("DEBUG", `Content table of contents with date restrictions ignored was refused (${status}) for course ${courseId}: using the default view`, error);
+    }
+    const toc = await apiClient.get(apiClient.le(courseId, "/content/toc"), {
+        ttl: DEFAULT_CACHE_TTLS.courseContent,
+    });
+    return { toc, datesIncluded: false };
+}
+const DETAILS_UNAVAILABLE_NOTE = "Brightspace showed this quiz in the course content but would not return its details to you; " +
+    "it may be closed, not yet open, or limited to certain students. Open the link to check.";
+/**
+ * Whether a quiz is open, from its own start and end dates alone: before the
+ * start it is not yet open, after the end it is closed. With neither date
+ * (or none that parses) nothing is said, and a due date never closes a quiz.
+ */
+function availabilityField(startDate, endDate, now = Date.now()) {
+    const start = startDate ? new Date(startDate).getTime() : NaN;
+    const end = endDate ? new Date(endDate).getTime() : NaN;
+    if (!Number.isFinite(start) && !Number.isFinite(end))
+        return {};
+    if (Number.isFinite(start) && now < start)
+        return { availability: "notYetOpen" };
+    if (Number.isFinite(end) && now > end)
+        return { availability: "closed" };
+    return { availability: "open" };
+}
+/**
+ * Coverage of the three routes quizzes are found through. Any one that did
+ * not answer may hide quizzes the others cannot see, so the inventory is only
+ * complete when all three did.
+ */
+function quizCoverage(answered) {
+    const unread = [
+        answered.quizList ? null : "the course's quiz list",
+        answered.content === "full" ? null
+            : answered.content === "dateRestricted"
+                ? "the course content with date-restricted items included (quizzes whose module or access window has not opened or has closed are hidden from the default view)"
+                : "the course content (checked for quizzes the quiz list omits)",
+        answered.gradebook ? null : "the gradebook (checked for graded work the quiz list omits)",
+    ].filter((source) => source !== null);
+    const recovery = answered.contentRecovery;
+    const truncated = recovery !== undefined && recovery.read < recovery.considered;
+    if (unread.length === 0 && !truncated)
+        return { quizCoverage: "complete" };
+    return {
+        quizCoverage: "incomplete",
+        quizCoverageNote: (unread.length > 0
+            ? `Brightspace did not return ${unread.join(", or ")}, so this course may have quizzes not listed here. `
+            : "") +
+            (truncated
+                ? `Brightspace read the details of only the first ${recovery.read} of ${recovery.considered} quizzes found in the course content; ` +
+                    "the rest are listed from the course content alone, without their details or attempts. "
+                : "") +
+            "Do not treat the listed quizzes as all of them, and do not report an unlisted quiz as missing or not taken - " +
+            "tell the user to check Brightspace directly.",
+    };
 }
 /**
  * Fetch assignments (dropbox + quizzes) for a single course
@@ -103,6 +388,10 @@ async function recoverContentQuizzes(apiClient, courseId, toc, listedIds) {
  * baseUrl is optional: without it the items carry a null url.
  */
 export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
+    return (await fetchCourseInventory(apiClient, courseId, baseUrl)).assignments;
+}
+/** A course's assignments and quizzes, with whether its quiz list is complete. */
+async function fetchCourseInventory(apiClient, courseId, baseUrl) {
     const assignments = [];
     const assignmentLink = assignmentLinkResolver(apiClient, baseUrl, courseId);
     // Fetch dropbox folders, quizzes, and the gradebook in parallel. The
@@ -118,9 +407,7 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
         apiClient.get(apiClient.le(courseId, "/grades/"), {
             ttl: DEFAULT_CACHE_TTLS.assignments,
         }),
-        apiClient.get(apiClient.le(courseId, "/content/toc"), {
-            ttl: DEFAULT_CACHE_TTLS.courseContent,
-        }),
+        fetchContentToc(apiClient, courseId),
     ]);
     // Each route may fail on its own without costing the others, but a failed
     // sign-in means none of them answered: report that, not an empty course.
@@ -128,15 +415,21 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
         if (result.status === "rejected" && isAuthUnavailable(result.reason))
             throw result.reason;
     }
+    // Ids of folders and quizzes the instructor hid or inactivated and that are
+    // therefore left out on purpose; their grade columns are not "uncovered".
+    const skippedIds = new Set();
     // Process Dropbox folders
     if (dropboxResult.status === "fulfilled") {
         // D2L dropbox endpoint may return paged { Objects: [...] } or flat array
         const dropboxRaw = dropboxResult.value;
         const folders = Array.isArray(dropboxRaw) ? dropboxRaw : dropboxRaw.Objects ?? [];
         for (const folder of folders) {
-            // Skip hidden folders
-            if (folder.IsHidden)
+            // Skip hidden folders. Their ids are remembered: the instructor hid the
+            // work, so its grade column must not resurface as a gradebook row.
+            if (folder.IsHidden) {
+                skippedIds.add(folder.Id);
                 continue;
+            }
             // Fetch submissions for this folder. Some tenants deny students access
             // to mysubmissions outright (403), in which case an empty list would be
             // indistinguishable from genuinely unsubmitted work — track whether the
@@ -299,32 +592,50 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
     }
     // Process quizzes. Content discovery remains useful when the list route is
     // forbidden or unavailable, so a failed list starts from an empty set.
-    let quizzes = [];
+    const quizzes = [];
     if (quizResult.status === "fulfilled") {
-        quizzes = quizResult.value;
+        quizzes.push(...quizResult.value.map((quiz) => ({ quiz, source: "quizList" })));
     }
     else {
         log("DEBUG", `Failed to fetch quizzes for course ${courseId}`, quizResult.reason);
     }
+    const knownQuizIds = () => new Set(quizzes.map((found) => found.quiz.QuizId).filter((id) => typeof id === "number"));
+    const knownQuizTitles = () => new Set(quizzes.map((found) => normalizedTitle(found.quiz.Name)));
+    const gradebookColumns = gradebookResult.status === "fulfilled"
+        ? studentScoredColumns(gradebookResult.value)
+        : [];
+    let contentRecovery;
     if (contentResult.status === "fulfilled") {
-        const listedIds = new Set(quizzes.map((quiz) => quiz.QuizId));
-        quizzes.push(...await recoverContentQuizzes(apiClient, courseId, contentResult.value, listedIds));
+        const recovered = await recoverContentQuizzes(apiClient, courseId, contentResult.value.toc, knownQuizIds(), knownQuizTitles(), new Map(gradebookColumns.map((column) => [column.Id, column])));
+        quizzes.push(...recovered.found);
+        contentRecovery = { considered: recovered.considered, read: recovered.read };
     }
     else {
         log("DEBUG", `Failed to fetch course content for quiz discovery in course ${courseId}`, contentResult.reason);
     }
+    if (gradebookResult.status === "fulfilled") {
+        const folderIds = new Set([
+            ...assignments.map((item) => item.id).filter((id) => typeof id === "number"),
+            ...skippedIds,
+        ]);
+        quizzes.push(...await recoverGradebookQuizzes(apiClient, courseId, gradebookColumns, folderIds, knownQuizIds(), contentResult.status === "fulfilled" ? contentQuizToolIds(contentResult.value.toc) : new Set(), new Set(quizzes.filter((found) => found.quiz.QuizId === null).map((found) => normalizedTitle(found.quiz.Name)))));
+    }
     // Students on this tenant get 403 from /quizzes/{id}/attempts/. Once the
     // first quiz of a course proves that, the remaining quizzes are not asked:
     // the answer would be the same 403, at one wasted request each.
     let attemptsForbidden = false;
-    for (const quiz of quizzes) {
-        // Skip inactive quizzes
-        if (!quiz.IsActive)
+    for (const { quiz, source, topicId, exempt } of quizzes) {
+        // Skip quizzes the instructor marked inactive. A row that does not say
+        // is not inactive: only an explicit false hides a quiz.
+        if (quiz.IsActive === false) {
+            if (typeof quiz.QuizId === "number")
+                skippedIds.add(quiz.QuizId);
             continue;
+        }
         // Fetch quiz attempts. null means "not measured", which is different
         // from an empty list, and the output says which one it was.
         let attempts = null;
-        if (!attemptsForbidden && !quiz.ContentMetadataOnly) {
+        if (!attemptsForbidden && !quiz.ContentMetadataOnly && quiz.QuizId !== null) {
             try {
                 const attemptsRaw = await apiClient.get(apiClient.le(courseId, `/quizzes/${quiz.QuizId}/attempts/`), { ttl: DEFAULT_CACHE_TTLS.assignments });
                 // D2L attempts endpoint may return paged { Objects: [...] } or flat array
@@ -334,8 +645,14 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 if (isAuthUnavailable(error))
                     throw error;
                 if (error?.status === 404) {
-                    // 404 means no attempts yet, which is a measurement of zero
-                    attempts = [];
+                    // For a quiz the course's quiz list returned, 404 means no
+                    // attempts yet: a measurement of zero. A quiz that list did not
+                    // return is one the quiz API is already hiding from this student,
+                    // so the same 404 may be that, and says nothing about attempts.
+                    if (source === "quizList")
+                        attempts = [];
+                    else
+                        log("DEBUG", `Attempts for quiz ${quiz.QuizId} answered 404 and it is not a listed quiz: leaving them unknown`);
                 }
                 else if (error?.status === 403) {
                     attemptsForbidden = true;
@@ -370,8 +687,17 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
         const quizAssignment = {
             type: "quiz",
             id: quiz.QuizId,
+            ...(quiz.QuizId === null && topicId !== undefined ? { topicId } : {}),
             name: quiz.Name,
-            url: baseUrl ? quizUrl(baseUrl, courseId, quiz.QuizId) : null,
+            // A content quiz with no quiz id links to its content topic instead.
+            url: !baseUrl
+                ? null
+                : quiz.QuizId !== null
+                    ? quizUrl(baseUrl, courseId, quiz.QuizId)
+                    : topicId !== undefined ? contentTopicUrl(baseUrl, courseId, topicId) : null,
+            // Which route found this quiz: the course's quiz list, a quiz topic
+            // in the course content, or a gradebook column linked to it.
+            source,
             instructions: descriptionHtml
                 ? convertHtmlToMarkdown(descriptionHtml).markdown
                 : "",
@@ -404,17 +730,40 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 : null,
             gracePeriodMinutes: quiz.SubmissionGracePeriod ?? null,
             hasPassword: Boolean(quiz.Password),
+            // Additive fields, each emitted only when it has something to say.
+            // availability is computed from the quiz's own start and end dates.
+            ...availabilityField(quiz.StartDate, quiz.EndDate),
+            // A row built from the table of contents alone: the quiz's own record
+            // was refused, or the topic names no quiz id to ask for.
+            ...(quiz.ContentMetadataOnly ? {
+                detailsStatus: "unavailable",
+                detailsStatusNote: DETAILS_UNAVAILABLE_NOTE,
+            } : {}),
+            // The topic's IsExempt: the user is exempt from the topic. Kept
+            // listed, since exempt does not mean it cannot be opened.
+            ...(exempt ? { exempt: true } : {}),
         };
         assignments.push(quizAssignment);
     }
     // Process the gradebook last, once the fetched items are known.
     if (gradebookResult.status === "fulfilled") {
-        assignments.push(...gradebookHeadsUp(gradebookResult.value, assignments, courseId, baseUrl));
+        assignments.push(...gradebookHeadsUp(gradebookResult.value, assignments, courseId, baseUrl, skippedIds));
     }
     else {
         log("DEBUG", `Failed to fetch the gradebook for course ${courseId}`, gradebookResult.reason);
     }
-    return assignments;
+    return {
+        assignments,
+        ...quizCoverage({
+            // A 404 on the list means the course has no quiz tool: answered, and empty.
+            quizList: quizResult.status === "fulfilled" || quizResult.reason?.status === 404,
+            content: contentResult.status !== "fulfilled"
+                ? "failed"
+                : contentResult.value.datesIncluded ? "full" : "dateRestricted",
+            gradebook: gradebookResult.status === "fulfilled",
+            contentRecovery,
+        }),
+    };
 }
 /**
  * Gradebook columns describing work that no other route already offered.
@@ -429,18 +778,32 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
  * A column with no id or no name is skipped rather than fatal: one malformed
  * row should cost its own line, not the course's other heads-up rows.
  */
-function gradebookHeadsUp(raw, fetched, courseId, baseUrl) {
+function gradebookHeadsUp(raw, fetched, courseId, baseUrl, skippedIds = new Set()) {
     if (!Array.isArray(raw))
         return [];
-    const covered = new Set(fetched.map((item) => item.id).filter((id) => typeof id === "number"));
+    // Fetched items, plus the hidden folders and inactive quizzes that were left
+    // out on purpose: a column of one of those is not work the tool missed.
+    const covered = new Set([
+        ...fetched.map((item) => item.id).filter((id) => typeof id === "number"),
+        ...skippedIds,
+    ]);
+    // A content quiz that names no id cannot be matched to its column by id, so
+    // a column carrying the same title is taken to be that quiz.
+    const idlessQuizTitles = new Set(fetched
+        .filter((item) => item.type === "quiz" && item.id === null)
+        .map((item) => normalizedTitle(item.name)));
     const rows = [];
     for (const column of raw) {
-        if (!STUDENT_SCORED.has(column?.GradeObjectTypeId))
+        if (!isStudentScored(column))
+            continue;
+        if (column.IsHidden === true)
             continue;
         if (covered.has(column.AssociatedTool?.ToolItemId))
             continue;
         if (typeof column.Id !== "number" || typeof column.Name !== "string")
             continue;
+        if (idlessQuizTitles.has(normalizedTitle(column.Name)))
+            continue;
         rows.push({
             type: "gradeOnly",
             id: column.Id,
@@ -462,7 +825,13 @@ export function registerGetAssignments(server, apiClient, config) {
         title: "Get Assignments",
         annotations: { readOnlyHint: true },
         description: "Fetch assignments and quizzes for a specific course or all enrolled courses. Shows dropbox submissions and quizzes with due dates, status, and rubric info. Use this when the user asks about assignments, homework, what to submit, quizzes, or assignment details and rubrics. " +
-            "Read submissionStatus/attemptStatus, not just submission/attemptsUsed, to decide whether something was turned in: some tenants deny students access to submission or attempt data, in which case the status is \"unknown\" even though submission is null or attemptsUsed is 0. Never report an \"unknown\" item as missing, unsubmitted, or not attempted - say it could not be verified and point the user to Brightspace.",
+            "Read submissionStatus/attemptStatus, not just submission/attemptsUsed, to decide whether something was turned in: some tenants deny students access to submission or attempt data, in which case the status is \"unknown\" even though submission is null or attemptsUsed is 0. Never report an \"unknown\" item as missing, unsubmitted, or not attempted - say it could not be verified and point the user to Brightspace. " +
+            "Quizzes come from the quiz list, the course content, and the gradebook; each quiz row says which in source. A quiz with id null was found only as a content topic. " +
+            "A quiz row with detailsStatus \"unavailable\" was shown in the course content but Brightspace would not return its details (it may be closed, not yet open, or limited to certain students), so its dates and attempts may be missing: point the user to its link. " +
+            "availability (notYetOpen, open, closed) is worked out from the quiz's own start and end dates and is left out when it has none. exempt: true means Brightspace marks the user exempt from that quiz's topic; the quiz is still listed. " +
+            "Each course also carries quizCoverage. \"complete\" means every quiz source answered, not that every quiz is guaranteed to be listed; \"incomplete\" means a quiz source could not be read, so the course may have quizzes not listed. " +
+            "Never conclude that a quiz was missed or not taken because it is absent, and never present the listed quizzes as all of them. " +
+            "A gradeOnly row named like a quiz is a quiz whose details could not be read.",
         inputSchema: GetAssignmentsSchema,
     }, async (args) => {
         try {
@@ -472,9 +841,9 @@ export function registerGetAssignments(server, apiClient, config) {
             // Single course case
             if (courseId) {
                 try {
-                    const assignments = await fetchCourseAssignments(apiClient, courseId, config.baseUrl);
-                    log("INFO", `get_assignments: Retrieved ${assignments.length} assignments for course ${courseId}`);
-                    return toolResponse({ courseId, assignments });
+                    const inventory = await fetchCourseInventory(apiClient, courseId, config.baseUrl);
+                    log("INFO", `get_assignments: Retrieved ${inventory.assignments.length} assignments for course ${courseId}`);
+                    return toolResponse({ courseId, ...inventory });
                 }
                 catch (error) {
                     // A pending sign-in is not an empty course: the routes never
@@ -520,11 +889,11 @@ export function registerGetAssignments(server, apiClient, config) {
             // Fetch assignments for each course (handle 403s gracefully)
             const assignmentPromises = filteredEnrollments.map(async (item) => {
                 try {
-                    const assignments = await fetchCourseAssignments(apiClient, item.OrgUnit.Id, config.baseUrl);
+                    const inventory = await fetchCourseInventory(apiClient, item.OrgUnit.Id, config.baseUrl);
                     return {
                         courseId: item.OrgUnit.Id,
                         courseName: item.OrgUnit.Name,
-                        assignments,
+                        ...inventory,
                     };
                 }
                 catch (error) {
@@ -557,7 +926,7 @@ export function registerGetAssignments(server, apiClient, config) {
             const pending = settled.filter((c) => c.authPending);
             const courses = settled
                 .filter((c) => !c.authPending)
-                .map(({ courseId, courseName, assignments }) => ({ courseId, courseName, assignments }));
+                .map(({ authPending: _authPending, authError: _authError, ...course }) => course);
             log("INFO", `get_assignments: Retrieved assignments for ${courses.length} courses ` +
                 `(out of ${enrollmentItems.length} enrolled${pending.length > 0 ? `, ${pending.length} pending sign-in` : ""})`);
             // Pending courses keep `assignments: []` so callers that read

package/build/utils/deep-links.js

@@ -29,6 +29,10 @@ export function assignmentUrl(baseUrl, courseId, folderId, groupId = 0) {
 export function quizUrl(baseUrl, courseId, quizId) {
     return `${trimBaseUrl(baseUrl)}/d2l/lms/quizzing/user/quiz_summary.d2l?qi=${quizId}&ou=${courseId}`;
 }
+/** Link to a topic in the course content viewer. */
+export function contentTopicUrl(baseUrl, courseId, topicId) {
+    return `${trimBaseUrl(baseUrl)}/d2l/le/content/${courseId}/viewContent/${topicId}/View`;
+}
 /**
  * Link to a course's own grades page. There is no per-column page a student
  * may open, so every gradebook row in a course shares this one link.

package/package.json

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