brightspace-mcp-server 3.11.8 → 3.11.10

package/build/tools/assignment-links.js

@@ -0,0 +1,43 @@
+import { assignmentUrl } from "../utils/deep-links.js";
+import { fetchMyGroupMemberships } from "./group-membership.js";
+import { isAuthUnavailable } from "./tool-helpers.js";
+/** Resolve only the folder's category, once per category per tool call. */
+export function assignmentLinkResolver(apiClient, baseUrl, courseId) {
+    const groups = new Map();
+    return async (folder) => {
+        if (!baseUrl)
+            return { url: null };
+        // D2L defines both missing and null GroupTypeId as individual folders:
+        // https://docs.valence.desire2learn.com/res/dropbox.html#Dropbox.DropboxFolder
+        if (folder.GroupTypeId === null || folder.GroupTypeId === undefined) {
+            return { url: assignmentUrl(baseUrl, courseId, folder.Id), urlKind: "assignment" };
+        }
+        const categoryId = folder.GroupTypeId;
+        let groupId = null;
+        if (categoryId !== undefined && Number.isSafeInteger(categoryId) && categoryId > 0) {
+            if (!groups.has(categoryId)) {
+                groups.set(categoryId, (async () => {
+                    try {
+                        const { matches } = await fetchMyGroupMemberships(apiClient, courseId, categoryId);
+                        const ids = [...new Set(matches.map(({ group }) => group.GroupId))]
+                            .filter((id) => Number.isSafeInteger(id) && id > 0);
+                        return ids.length === 1 ? ids[0] : null;
+                    }
+                    catch (error) {
+                        if (isAuthUnavailable(error))
+                            throw error;
+                        return null;
+                    }
+                })());
+            }
+            groupId = await groups.get(categoryId);
+        }
+        if (groupId !== null)
+            return { url: assignmentUrl(baseUrl, courseId, folder.Id, groupId), urlKind: "assignment" };
+        return {
+            url: `${baseUrl.replace(/\/+$/, "")}/d2l/home/${courseId}`,
+            urlKind: "course-home",
+            urlNote: "Brightspace did not identify a unique group for this assignment. Open Assignments from the course home to select the folder.",
+        };
+    };
+}

package/build/tools/get-assignment-files.js

@@ -7,7 +7,7 @@ import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetAssignmentFilesSchema } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
 import { describeAttachment, readAttachment, } from "./attachment-reader.js";
-import { assignmentUrl } from "../utils/deep-links.js";
+import { assignmentLinkResolver } from "./assignment-links.js";
 import { log } from "../utils/logger.js";
 export { fileKind } from "./attachment-reader.js";
 /** D2L list endpoints return either a paged { Objects: [...] } or a flat array. */
@@ -33,6 +33,7 @@ export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
             log("DEBUG", "get_assignment_files tool called", { args });
             const { courseId, folderId, fileId, extractText, maxChars } = GetAssignmentFilesSchema.parse(args);
             const folders = await listFolders(apiClient, courseId, folderId);
+            const assignmentLink = assignmentLinkResolver(apiClient, baseUrl, courseId);
             if (folderId !== undefined && folders.length === 0) {
                 return toolResponse({
                     courseId,
@@ -65,23 +66,23 @@ export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
                     courseId,
                     folderId,
                     folderName: folder.Name,
-                    url: baseUrl ? assignmentUrl(baseUrl, courseId, folderId) : null,
+                    ...await assignmentLink(folder),
                     file,
                 });
             }
             // Discovery: which assignments have files, without downloading any.
-            const withFiles = folders
+            const withFiles = await Promise.all(folders
                 .filter((folder) => (folder.Attachments ?? []).length > 0)
-                .map((folder) => ({
+                .map(async (folder) => ({
                 folderId: folder.Id,
                 folderName: folder.Name,
                 dueDate: folder.DueDate,
-                url: baseUrl ? assignmentUrl(baseUrl, courseId, folder.Id) : null,
+                ...await assignmentLink(folder),
                 attachments: (folder.Attachments ?? []).map((attachment) => ({
                     ...describeAttachment(attachment),
                     downloadArgs: { courseId, folderId: folder.Id, fileId: attachment.FileId, source: "assignmentAttachment" },
                 })),
-            }));
+            })));
             log("INFO", `get_assignment_files: ${withFiles.length} assignments with attachments in course ${courseId}`);
             return toolResponse({
                 courseId,

package/build/tools/get-assignment-rubric.js

@@ -6,7 +6,7 @@
 import { ApiError, DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetAssignmentRubricSchema } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
-import { convertHtmlToMarkdown } from "../utils/html-converter.js";
+import { feedbackText } from "../utils/feedback.js";
 import { log } from "../utils/logger.js";
 // D2L's documented SCORING_M enumeration
 // (https://docs.valence.desire2learn.com/res/assessment.html). Only values
@@ -20,10 +20,7 @@ const SCORING_METHOD_NAMES = {
 };
 /** Rich text to plain markdown, or undefined when there is nothing to say. */
 function textOf(rt) {
-    if (!rt)
-        return undefined;
-    const text = rt.Html ? convertHtmlToMarkdown(rt.Html).markdown : rt.Text ?? undefined;
-    return text && text.trim().length > 0 ? text : undefined;
+    return feedbackText(rt) ?? undefined;
 }
 /** The groups a rubric carries, normalizing the grouped and flattened shapes. */
 function groupsOf(rubric) {
@@ -120,7 +117,7 @@ function levelNamesOf(rubric) {
  * The student's own graded outcome on this rubric, resolved against the
  * rubric's own criterion/level names rather than re-sent by the assessment.
  */
-function toOutputAssessment(rubric, assessment) {
+export function toOutputAssessment(rubric, assessment) {
     const criterionNames = criterionNamesOf(rubric);
     const levelNames = levelNamesOf(rubric);
     const out = { criteria: [] };

package/build/tools/get-assignments.js

@@ -10,8 +10,11 @@ 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 { assignmentUrl, gradebookUrl, quizUrl } from "../utils/deep-links.js";
+import { 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";
+import { toOutputAssessment } from "./get-assignment-rubric.js";
 /** The display HTML of a quiz rich-text field, nested shape or flat. */
 function richTextHtml(field) {
     if (!field)
@@ -100,6 +103,7 @@ async function recoverContentQuizzes(apiClient, courseId, toc, listedIds) {
  */
 export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
     const assignments = [];
+    const assignmentLink = assignmentLinkResolver(apiClient, baseUrl, courseId);
     // Fetch dropbox folders, quizzes, and the gradebook in parallel. The
     // gradebook is fetched alongside them but read last: a heads-up row is a
     // column that nothing the other two returned matched, so the comparison
@@ -152,13 +156,18 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
             }
             // Fetch feedback independently of submissions
             let feedback = null;
+            let feedbackStatus = "unavailable";
             try {
                 feedback = await apiClient.get(apiClient.le(courseId, `/dropbox/folders/${folder.Id}/feedback/myFeedback/`), { ttl: DEFAULT_CACHE_TTLS.assignments });
+                feedbackStatus = feedback ? "retrieved" : "unavailable";
             }
             catch (error) {
                 if (isAuthUnavailable(error))
                     throw error;
-                // 404/403 means no feedback available (or no access) - that's fine
+                // Permission failures, missing API records, and transport failures
+                // do not establish whether published feedback exists in the UI.
+                feedbackStatus = error?.status === 403 ? "restricted"
+                    : error?.status === 404 ? "unavailable" : "error";
                 if (error?.status !== 404 && error?.status !== 403) {
                     log("DEBUG", `Failed to fetch feedback for folder ${folder.Id}`, error);
                 }
@@ -174,18 +183,27 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 .filter((l) => Boolean(l.Href))
                 .map((l) => ({ name: l.LinkName ?? l.Title ?? l.Href ?? null, url: l.Href }));
             // Build assignment object
+            const overallFeedback = feedbackText(feedback?.Feedback);
+            const rubricAssessments = (feedback?.RubricAssessments ?? []).map((assessment) => {
+                const rubric = folder.Assessment?.Rubrics?.find((r) => r.RubricId === assessment.RubricId);
+                return {
+                    rubricId: assessment.RubricId,
+                    ...toOutputAssessment((rubric ?? { RubricId: assessment.RubricId, Name: "" }), assessment),
+                };
+            });
+            const commentsRetrieved = Boolean(overallFeedback || rubricAssessments.some((rubric) => rubric.feedback || rubric.criteria.some((criterion) => criterion.feedback)));
             const assignment = {
                 type: "assignment",
                 id: folder.Id,
                 name: folder.Name,
-                url: baseUrl ? assignmentUrl(baseUrl, courseId, folder.Id) : null,
+                ...await assignmentLink(folder),
                 instructions: folder.CustomInstructions?.Html
                     ? convertHtmlToMarkdown(folder.CustomInstructions.Html).markdown
                     : "",
                 dueDate: folder.DueDate,
                 dueIn: dueIn(folder.DueDate),
                 points: folder.Assessment?.ScoreDenominator ?? null,
-                isGroup: folder.GroupTypeId !== null,
+                isGroup: folder.GroupTypeId !== null && folder.GroupTypeId !== undefined,
                 ...(linkAttachments.length > 0 ? { linkAttachments } : {}),
                 rubric: folder.Assessment?.Rubrics?.map((r) => ({
                     name: r.Name,
@@ -225,11 +243,14 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 feedback: feedback
                     ? {
                         score: feedback.Score,
-                        feedback: feedback.Feedback?.Html
-                            ? convertHtmlToMarkdown(feedback.Feedback.Html).markdown
-                            : null,
+                        feedback: overallFeedback,
+                        rubricAssessments,
                     }
                     : null,
+                feedbackStatus,
+                feedbackCommentsStatus: commentsRetrieved ? "retrieved" : "unavailable",
+                feedbackUrl: baseUrl ? gradebookUrl(baseUrl, courseId) : null,
+                ...(commentsRetrieved ? {} : { feedbackStatusNote: FEEDBACK_UNAVAILABLE_NOTE }),
             };
             assignments.push(assignment);
         }

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

@@ -10,6 +10,7 @@ import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable, authPend
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { gradebookUrl, quizUrl } from "../utils/deep-links.js";
+import { feedbackText, FEEDBACK_UNAVAILABLE_NOTE } from "../utils/feedback.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
@@ -35,15 +36,15 @@ async function fetchQuizzes(apiClient, courseId) {
     }
 }
 /**
- * Clean grade rows. Rows scored from a quiz also carry feedbackUrl, and a
- * feedbackNote when the gradebook comment is empty; other rows are unchanged.
+ * Normalize public comments and report their retrieval status. Quiz-linked
+ * rows keep the quiz source URL and note; other rows link to the gradebook.
  */
 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 comments = feedbackText(gv.Comments);
         const quizId = quizByGradeItem.get(String(gv.GradeObjectIdentifier));
         return {
             name: gv.GradeObjectName,
@@ -52,12 +53,13 @@ function toGradeItems(gradeValues, quizzes, baseUrl, courseId) {
             pointsDenominator: gv.PointsDenominator,
             weightedNumerator: gv.WeightedNumerator,
             weightedDenominator: gv.WeightedDenominator,
+            gradeObjectId: gv.GradeObjectIdentifier,
             comments,
+            feedbackStatus: comments ? "retrieved" : "unavailable",
+            feedbackUrl: quizId === undefined ? gradebookUrl(baseUrl, courseId) : quizUrl(baseUrl, courseId, quizId),
+            ...(comments ? {} : { feedbackStatusNote: FEEDBACK_UNAVAILABLE_NOTE }),
             lastModified: gv.LastModified,
-            ...(quizId === undefined ? {} : {
-                feedbackUrl: quizUrl(baseUrl, courseId, quizId),
-                ...(comments ? {} : { feedbackNote: QUIZ_FEEDBACK_NOTE }),
-            }),
+            ...(quizId !== undefined && !comments ? { feedbackNote: QUIZ_FEEDBACK_NOTE } : {}),
         };
     });
 }

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

@@ -3,12 +3,12 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
-import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { ApiError } from "../api/errors.js";
 import { GetMyGroupsSchema } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
 import { fetchClasslistUsers } from "./get-roster.js";
 import { log } from "../utils/logger.js";
+import { fetchMyGroupMemberships } from "./group-membership.js";
 /** True when a group/category endpoint simply isn't there for this course or user. */
 function isMissingOrForbidden(error) {
     return error instanceof ApiError && (error.status === 403 || error.status === 404);
@@ -26,49 +26,13 @@ export function registerGetMyGroups(server, apiClient) {
         try {
             log("DEBUG", "get_my_groups tool called", { args });
             const { courseId } = GetMyGroupsSchema.parse(args);
-            const me = await apiClient.get(apiClient.lp("/users/whoami"));
-            const myId = Number(me.Identifier);
-            let categories;
-            try {
-                categories = await apiClient.get(apiClient.lp(`/${courseId}/groupcategories/`), { ttl: DEFAULT_CACHE_TTLS.roster });
-            }
-            catch (error) {
-                if (isMissingOrForbidden(error)) {
-                    log("INFO", "get_my_groups: No group categories visible for course", { courseId });
-                    return toolResponse({
-                        courseId,
-                        groups: [],
-                        note: "No groups are visible for this course (it may not use groups, or group info isn't accessible).",
-                    });
-                }
-                throw error;
-            }
-            // Membership is determined first, from GroupDto.Enrollments alone —
-            // no classlist needed for that. The classlist (for member names) is
-            // fetched lazily, only once we know the user is actually in at least
-            // one group, so a user in no groups never pays for a roster fetch.
-            const matches = [];
-            for (const category of categories) {
-                let categoryGroups;
-                try {
-                    categoryGroups = await apiClient.get(apiClient.lp(`/${courseId}/groupcategories/${category.GroupCategoryId}/groups/`), { ttl: DEFAULT_CACHE_TTLS.roster });
-                }
-                catch (error) {
-                    if (isMissingOrForbidden(error)) {
-                        log("WARN", "get_my_groups: Groups not accessible for category, skipping", {
-                            courseId,
-                            categoryId: category.GroupCategoryId,
-                        });
-                        continue;
-                    }
-                    throw error;
-                }
-                for (const group of categoryGroups) {
-                    const enrollments = group.Enrollments ?? [];
-                    if (!enrollments.includes(myId))
-                        continue;
-                    matches.push({ category, group });
-                }
+            const { matches, categoriesUnavailable } = await fetchMyGroupMemberships(apiClient, courseId);
+            if (categoriesUnavailable) {
+                return toolResponse({
+                    courseId,
+                    groups: [],
+                    note: "No groups are visible for this course (it may not use groups, or group info isn't accessible).",
+                });
             }
             if (matches.length === 0) {
                 log("INFO", `get_my_groups: User is not a member of any group in course ${courseId}`);

package/build/tools/get-upcoming-due-dates.js

@@ -7,7 +7,8 @@ import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetUpcomingDueDatesSchema, } from "./schemas.js";
 import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
-import { assignmentUrl, quizUrl, discussionUrl } from "../utils/deep-links.js";
+import { quizUrl, discussionUrl } from "../utils/deep-links.js";
+import { assignmentLinkResolver } from "./assignment-links.js";
 import { dueIn } from "../utils/due-in.js";
 import { resolveCourses } from "./resolve-courses.js";
 import { fetchCourseCalendarEvents } from "./calendar-events.js";
@@ -88,12 +89,14 @@ async function fetchCourseDueItems(apiClient, baseUrl, course, from, to) {
             throw result.reason;
     }
     const items = [];
+    const assignmentLink = assignmentLinkResolver(apiClient, baseUrl, course.id);
     if (dropboxResult.status === "fulfilled") {
         for (const folder of unwrapList(dropboxResult.value)) {
             if (folder.IsHidden === true)
                 continue;
             if (!folder.DueDate)
                 continue;
+            const link = await assignmentLink(folder);
             items.push({
                 type: "assignment",
                 id: folder.Id,
@@ -104,7 +107,8 @@ async function fetchCourseDueItems(apiClient, baseUrl, course, from, to) {
                 dueIn: dueIn(folder.DueDate),
                 startDate: null,
                 endDate: null,
-                url: assignmentUrl(baseUrl, course.id, folder.Id),
+                ...link,
+                url: link.url,
             });
         }
     }

package/build/tools/group-membership.js

@@ -0,0 +1,39 @@
+import { DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { ApiError } from "../api/errors.js";
+const inaccessible = (error) => error instanceof ApiError
+    && (error.status === 403 || error.status === 404);
+/** Shared membership lookup. API cache/coalescing bounds repeat reads; no classlist is needed. */
+export async function fetchMyGroupMemberships(apiClient, courseId, categoryId) {
+    const me = await apiClient.get(apiClient.lp("/users/whoami"), { ttl: DEFAULT_CACHE_TTLS.roster });
+    const myId = Number(me.Identifier);
+    if (!Number.isSafeInteger(myId) || myId <= 0)
+        throw new Error("Brightspace returned an invalid current user identifier.");
+    let categories;
+    try {
+        categories = categoryId === undefined
+            ? await apiClient.get(apiClient.lp(`/${courseId}/groupcategories/`), { ttl: DEFAULT_CACHE_TTLS.roster })
+            : [{ GroupCategoryId: categoryId, Name: "" }];
+    }
+    catch (error) {
+        if (inaccessible(error))
+            return { matches: [], categoriesUnavailable: true };
+        throw error;
+    }
+    const matches = [];
+    for (const category of categories) {
+        let groups;
+        try {
+            groups = await apiClient.get(apiClient.lp(`/${courseId}/groupcategories/${category.GroupCategoryId}/groups/`), { ttl: DEFAULT_CACHE_TTLS.roster });
+        }
+        catch (error) {
+            if (inaccessible(error))
+                continue;
+            throw error;
+        }
+        for (const group of groups) {
+            if (group.Enrollments?.some((id) => Number(id) === myId))
+                matches.push({ category, group });
+        }
+    }
+    return { matches, categoriesUnavailable: false };
+}

package/build/utils/deep-links.js

@@ -22,8 +22,8 @@ function trimBaseUrl(baseUrl) {
     return baseUrl.replace(/\/+$/, "");
 }
 /** Link to the submit-files page of a dropbox folder. */
-export function assignmentUrl(baseUrl, courseId, folderId) {
-    return `${trimBaseUrl(baseUrl)}/d2l/lms/dropbox/user/folder_submit_files.d2l?db=${folderId}&grpid=0&ou=${courseId}`;
+export function assignmentUrl(baseUrl, courseId, folderId, groupId = 0) {
+    return `${trimBaseUrl(baseUrl)}/d2l/lms/dropbox/user/folder_submit_files.d2l?db=${folderId}&grpid=${groupId}&ou=${courseId}`;
 }
 /** Link to the summary page of a quiz. */
 export function quizUrl(baseUrl, courseId, quizId) {

package/build/utils/feedback.js

@@ -0,0 +1,12 @@
+/** Public instructor feedback only; never substitute private comments. */
+import { convertHtmlToMarkdown } from "./html-converter.js";
+export function feedbackText(value) {
+    if (!value)
+        return null;
+    const markdown = value.Html ? convertHtmlToMarkdown(value.Html).markdown : null;
+    if (markdown?.trim())
+        return markdown;
+    return value.Text?.trim() ? value.Text : null;
+}
+export const FEEDBACK_UNAVAILABLE_NOTE = "Brightspace did not return instructor comments through this API. Published feedback may still " +
+    "be available in Brightspace; do not interpret null as no feedback. Check the source URL.";

package/package.json

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