brightspace-mcp-server 3.11.8 → 3.11.9

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-assignments.js

@@ -10,7 +10,8 @@ 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";
 /** The display HTML of a quiz rich-text field, nested shape or flat. */
 function richTextHtml(field) {
@@ -100,6 +101,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
@@ -178,14 +180,14 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 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,

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/package.json

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