brightspace-mcp-server 3.11.7 → 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-announcements.js

@@ -10,6 +10,18 @@ import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable,
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
+function pageInfo(offset, count, returned, total, unavailableCourseIds = []) {
+    const nextOffset = total !== null && offset + returned < total ? offset + returned : null;
+    return { offset, count, returned, total, nextOffset, truncated: nextOffset !== null,
+        coverageComplete: total !== null && unavailableCourseIds.length === 0, unavailableCourseIds };
+}
+// Preserve the original array in content[0] and existing auth notices, while
+// exposing machine-readable continuation metadata in a separate text block.
+function arrayPage(items, pagination, notice) {
+    const result = notice ? toolResponseWithNotice(items, notice) : toolResponse(items);
+    result.content.push({ type: "text", text: JSON.stringify({ pagination }) });
+    return result;
+}
 /**
  * A date the runtime can actually order, or null. Unreadable and absent are the
  * same answer, so a caller can fall through to the next best.
@@ -87,13 +99,13 @@ export function mapNewsItem(item) {
 export function registerGetAnnouncements(server, apiClient, config) {
     server.registerTool("get_announcements", {
         title: "Get Announcements",
-        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said. Attachments are listed per announcement; fetch them with download_file (newsId + fileId) or read them with get_announcement_files.",
+        description: "Fetch announcements from one course with courseId, or all courses when omitted, newest first. count is 1-50 per page. Continue with offset= pagination.nextOffset until it is null. Pagination metadata is in a separate JSON text block for array responses, or the pagination field with modifiedSince. A false coverageComplete means some courses were not fetched: retry from offset 0 after recovery. Offsets reflect the current filtered list; new posts can shift pages. Attachments are listed per announcement; fetch them with download_file (newsId + fileId) or read them with get_announcement_files.",
         inputSchema: GetAnnouncementsSchema,
     }, async (args) => {
         try {
             log("DEBUG", "get_announcements tool called", { args });
             // Parse and validate input
-            const { courseId, count, modifiedSince } = GetAnnouncementsSchema.parse(args);
+            const { courseId, count, offset, modifiedSince } = GetAnnouncementsSchema.parse(args);
             const cutoff = modifiedSince ? new Date(modifiedSince) : null;
             // Single course case
             if (courseId) {
@@ -104,16 +116,18 @@ export function registerGetAnnouncements(server, apiClient, config) {
                     const matched = cutoff
                         ? published.filter((a) => matchesModifiedSince(a.lastModified, cutoff))
                         : published;
-                    const announcements = matched.sort(newestFirst).slice(0, count);
+                    const announcements = matched.sort(newestFirst).slice(offset, offset + count);
+                    const pagination = pageInfo(offset, count, announcements.length, matched.length);
                     log("INFO", `get_announcements: Retrieved ${announcements.length} announcements for course ${courseId}`);
-                    return toolResponse(modifiedSince
-                        ? {
+                    return modifiedSince
+                        ? toolResponse({
                             announcements,
+                            pagination,
                             modifiedSince,
                             returned: announcements.length,
                             filteredOut: published.length - matched.length,
-                        }
-                        : announcements);
+                        })
+                        : arrayPage(announcements, pagination);
                 }
                 catch (error) {
                     // A pending sign-in is not an empty course: the route never
@@ -137,10 +151,11 @@ export function registerGetAnnouncements(server, apiClient, config) {
                                 returned: 0,
                                 filteredOut: 0,
                                 authPending: true,
+                                pagination: pageInfo(offset, count, 0, null, [courseId]),
                                 notice,
                             });
                         }
-                        return toolResponseWithNotice([], notice);
+                        return arrayPage([], pageInfo(offset, count, 0, null, [courseId]), notice);
                     }
                     throw error;
                 }
@@ -181,7 +196,7 @@ export function registerGetAnnouncements(server, apiClient, config) {
                     // 403 means no access (past course, etc) - log and skip
                     if (error?.status === 403) {
                         log("DEBUG", `get_announcements: 403 Forbidden for course ${item.OrgUnit.Id} (${item.OrgUnit.Name}) - skipping`);
-                        return [];
+                        return { unavailable: true, courseId: item.OrgUnit.Id };
                     }
                     // A pending sign-in only means this course's route never
                     // answered — it says nothing about the other courses, whose
@@ -201,13 +216,16 @@ export function registerGetAnnouncements(server, apiClient, config) {
                 .map((r) => r.value);
             const pending = settled.filter((v) => !Array.isArray(v) && v?.authPending === true);
             const allAnnouncements = settled.filter((v) => Array.isArray(v)).flat();
+            const unavailableCourseIds = results.flatMap((result, index) => result.status === "rejected" || (!Array.isArray(result.value) && result.value?.courseId)
+                ? [filteredEnrollments[index].OrgUnit.Id] : []);
             const allMatched = cutoff
                 ? allAnnouncements.filter((a) => matchesModifiedSince(a.lastModified, cutoff))
                 : allAnnouncements;
             // Sort by the scheduled date and slice to count
             const announcements = allMatched
                 .sort(newestFirst)
-                .slice(0, count);
+                .slice(offset, offset + count);
+            const pagination = pageInfo(offset, count, announcements.length, allMatched.length, unavailableCourseIds);
             log("INFO", `get_announcements: Retrieved ${announcements.length} announcements (out of ${allAnnouncements.length} total ` +
                 `across ${enrollmentItems.length} courses${pending.length > 0 ? `, ${pending.length} pending sign-in` : ""})`);
             // With modifiedSince the response is already an object (the shape
@@ -218,14 +236,15 @@ export function registerGetAnnouncements(server, apiClient, config) {
             // the notice instead of changing content[0].
             if (!modifiedSince) {
                 if (pending.length === 0)
-                    return toolResponse(announcements);
-                return toolResponseWithNotice(announcements, "Sign-in to Brightspace is still in progress, so announcements for " +
+                    return arrayPage(announcements, pagination);
+                return arrayPage(announcements, pagination, "Sign-in to Brightspace is still in progress, so announcements for " +
                     `${pending.length} course(s) (${pending.map((c) => c.courseId).join(", ")}) could not be ` +
                     `fetched yet. ${authPendingNotice(pending[0].authError)} Call get_announcements again once ` +
                     "sign-in finishes.");
             }
             const response = {
                 announcements,
+                pagination,
                 modifiedSince,
                 returned: announcements.length,
                 filteredOut: allAnnouncements.length - allMatched.length,

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/tools/schemas.js

@@ -37,7 +37,8 @@ export const GetMyGradesSchema = z.object({
 });
 export const GetAnnouncementsSchema = z.object({
     courseId: z.coerce.number().int().positive().optional().describe("Course ID to get announcements for. If omitted, returns recent announcements across all courses."),
-    count: z.coerce.number().int().min(1).max(50).default(10).describe("Maximum number of announcements to return, newest first (1-50, default 10). There is no pagination or offset: when more announcements exist than count, only the newest are returned. To get fuller coverage, call once per course with courseId so courses do not compete for the same slots, and use modifiedSince to return only announcements changed since a cutoff."),
+    count: z.coerce.number().int().min(1).max(50).default(10).describe("Announcements per page: 1-50 (default 10)."),
+    offset: z.coerce.number().int().min(0).default(0).describe("Announcement offset after filtering and sorting. Continue with pagination.nextOffset; restart at 0 after a failed course becomes available."),
     modifiedSince: z.string().datetime({ offset: true, message: "modifiedSince must be an ISO 8601 datetime, e.g. 2026-01-15T00:00:00Z" }).optional()
         .describe("Only return announcements last modified at or after this ISO 8601 datetime (e.g. 2026-01-15T00:00:00Z). Announcements with no modified timestamp are always included. When set, the response reports how many announcements were filtered out."),
 });

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.7",
+  "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",