brightspace-mcp-server 5.2.3 → 5.2.5

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

@@ -14,6 +14,8 @@ import { log } from "../utils/logger.js";
 const SELF_ENROLLMENT_STYLES = new Set([3, 4, 5]);
 /** Without a courseId, courses that started longer ago than this are skipped unless includeOlder is set. */
 const RECENT_COURSE_MS = 365 * 24 * 60 * 60 * 1000;
+/** Why a category's groups couldn't be read, in words an agent can relay. */
+const unreadReason = (status) => status === 403 ? "Brightspace refused access (403)" : "Brightspace found no group list (404)";
 const inaccessible = (error) => error instanceof ApiError && (error.status === 403 || error.status === 404);
 const text = (value) => value?.Text?.trim() || undefined;
 /**
@@ -27,7 +29,7 @@ function signUpOpen(category, now) {
     const end = category.SelfEnrollmentExpiryDate ? Date.parse(category.SelfEnrollmentExpiryDate) : Infinity;
     return start <= now && now <= end;
 }
-async function fetchCourseGroups(apiClient, course, myId, now) {
+async function fetchCourseGroups(apiClient, course, myId, now, unreadOut) {
     const result = { courseId: course.id, courseName: course.name, categories: [], alreadyInGroup: [] };
     let categories;
     try {
@@ -47,6 +49,7 @@ async function fetchCourseGroups(apiClient, course, myId, now) {
         catch (error) {
             if (inaccessible(error)) {
                 unread.push(category.Name);
+                unreadOut.push({ courseId: course.id, name: category.Name, status: error.status });
                 continue;
             }
             throw error;
@@ -115,7 +118,8 @@ export function registerGetAvailableGroups(server, apiClient, config) {
                 return Number.isFinite(start) && start >= now - RECENT_COURSE_MS;
             });
             const olderSkipped = enrolled.length - courses.length;
-            const results = await Promise.allSettled(courses.map((course) => fetchCourseGroups(apiClient, course, myId, now)));
+            const unreadCategories = [];
+            const results = await Promise.allSettled(courses.map((course) => fetchCourseGroups(apiClient, course, myId, now, unreadCategories)));
             const pendingCourseIds = [];
             const failedCourseIds = [];
             let firstAuthError = null;
@@ -149,6 +153,16 @@ export function registerGetAvailableGroups(server, apiClient, config) {
             if (failedCourseIds.length > 0) {
                 notes.push(`Couldn't read groups for course(s) ${failedCourseIds.join(", ")}, so open sign-ups there aren't listed.`);
             }
+            // Without a reason attached, a bare unreadCategories list reads like a
+            // category with nothing open, so name each one and say why it's there (#433).
+            const shownCourseIds = new Set(withChoices.map((c) => c.courseId));
+            const unread = unreadCategories.filter((u) => shownCourseIds.has(u.courseId));
+            if (unread.length > 0) {
+                const where = unread.map((u) => `"${u.name}" in course ${u.courseId}: ${unreadReason(u.status)}`).join("; ");
+                notes.push(`Couldn't read the groups in these open sign-ups, so any open groups there aren't listed ` +
+                    `(see unreadCategories): ${where}. Don't report them as full or closed; ` +
+                    "check Groups > Available Groups in Brightspace.");
+            }
             const data = {
                 coursesChecked: courses.length,
                 courses: withChoices,

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

@@ -45,14 +45,23 @@ export function registerGetMyGroups(server, apiClient) {
         try {
             log("DEBUG", "get_my_groups tool called", { args });
             const { courseId } = GetMyGroupsSchema.parse(args);
-            const { matches, categoriesUnavailable, unreadCategories } = await fetchMyGroupMemberships(apiClient, courseId);
+            const { matches, categoriesUnavailable, categoriesStatus, unreadCategories } = await fetchMyGroupMemberships(apiClient, courseId);
+            // An empty `groups` here means "not read", not "none": the field lets a
+            // caller tell the two apart without parsing the note (#442).
             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).",
+                    groupsUnavailable: { status: categoriesStatus ?? null },
+                    note: categoriesStatus === 403
+                        ? "Brightspace refused this course's group list (403), so whether the current user is in a group " +
+                            "is unknown. Don't tell them they have no group; they can check Groups in Brightspace."
+                        : "No groups are visible for this course (it may not use groups, or group info isn't accessible), " +
+                            "so whether the current user is in a group is unknown.",
                 });
             }
+            const unreadNames = unreadCategories.map((c) => c.Name || String(c.GroupCategoryId));
+            const unreadField = unreadNames.length > 0 ? { unreadCategories: unreadNames } : {};
             const unreadNote = unreadCategories.length === 0 ? undefined
                 : `Couldn't read the groups in ${unreadCategories.map((c) => `"${c.Name || c.GroupCategoryId}"`).join(", ")}, ` +
                     "so any group the current user has there is not listed.";
@@ -63,7 +72,7 @@ export function registerGetMyGroups(server, apiClient) {
                 });
             }
             if (matches.length === 0 && unreadNote) {
-                return toolResponse({ courseId, groups: [], note: unreadNote });
+                return toolResponse({ courseId, groups: [], ...unreadField, note: unreadNote });
             }
             if (matches.length === 0) {
                 log("INFO", `get_my_groups: User is not a member of any group in course ${courseId}`);
@@ -140,7 +149,7 @@ export function registerGetMyGroups(server, apiClient) {
                     : "Couldn't read this course's classlist, so member names are null; only user ids are listed" +
                         (pageNames.size > 0 ? ", except where memberNames lists a group's members from its member page." : ".");
             const note = [unreadNote, namesNote].filter(Boolean).join(" ") || undefined;
-            return toolResponse({ courseId, groups, ...(note ? { note } : {}) });
+            return toolResponse({ courseId, groups, ...unreadField, ...(note ? { note } : {}) });
         }
         catch (error) {
             return sanitizeError(error);

package/build/tools/group-membership.js

@@ -21,7 +21,12 @@ export async function fetchMyGroupMemberships(apiClient, courseId, categoryId) {
     }
     catch (error) {
         if (inaccessible(error)) {
-            return { matches: [], categoriesUnavailable: true, unreadCategories: [] };
+            return {
+                matches: [],
+                categoriesUnavailable: true,
+                categoriesStatus: error.status,
+                unreadCategories: [],
+            };
         }
         throw error;
     }
@@ -45,5 +50,5 @@ export async function fetchMyGroupMemberships(apiClient, courseId, categoryId) {
                 matches.push({ category, group });
         }
     }
-    return { matches, categoriesUnavailable: false, unreadCategories };
+    return { matches, categoriesUnavailable: false, categoriesStatus: undefined, unreadCategories };
 }

package/package.json

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