brightspace-mcp-server 5.1.32 → 5.1.35

package/build/tools/get-course-content.js

@@ -5,7 +5,7 @@
  */
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetCourseContentSchema } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
 import { log } from "../utils/logger.js";
@@ -44,18 +44,37 @@ export async function fetchRootContent(apiClient, courseId) {
     return apiClient.get(apiClient.le(courseId, '/content/root/'), { ttl: DEFAULT_CACHE_TTLS.courseContent });
 }
 /**
- * Fetch a single module's structure, or null when the dedicated endpoint
- * fails (locked module, transient error) so the caller can fall back to
- * whatever structure the parent listing already embedded.
+ * Fetch a single module's structure, or say why it couldn't be read (locked
+ * module, transient error, an answer that is not a list) so the caller can
+ * fall back to whatever structure the parent listing already embedded. A
+ * pending or expired sign-in is rethrown: it fails every module the same way,
+ * and must fail the call so the user is told to sign in, not shown a course
+ * whose every module looks empty.
  */
 export async function fetchModuleStructure(apiClient, courseId, moduleId) {
+    let structure;
     try {
-        return await apiClient.get(apiClient.le(courseId, `/content/modules/${moduleId}/structure/`), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+        structure = await apiClient.get(apiClient.le(courseId, `/content/modules/${moduleId}/structure/`), { ttl: DEFAULT_CACHE_TTLS.courseContent });
     }
-    catch (e) {
-        log('DEBUG', `Failed to fetch children for module ${moduleId}: falling back to the embedded structure`);
-        return null;
+    catch (error) {
+        if (isAuthUnavailable(error))
+            throw error;
+        log('DEBUG', `Failed to fetch children for module ${moduleId}: falling back to the embedded structure`, error);
+        const status = typeof error?.status === 'number' ? error.status : null;
+        return {
+            status,
+            reason: status === 403
+                ? "Brightspace refused this account's request for this module's contents. It may hold items; open the module in a browser to see what this account can read."
+                : `Couldn't read this module's contents${status !== null ? ` (Brightspace answered ${status})` : ''}. It may hold items; try again.`,
+        };
     }
+    if (Array.isArray(structure))
+        return structure;
+    log('DEBUG', `Module ${moduleId} structure was not a list: falling back to the embedded structure`);
+    return {
+        status: null,
+        reason: "Brightspace answered with something other than a list of this module's contents. It may hold items; try again.",
+    };
 }
 /**
  * How deep the tree builder will descend when the caller names no maxDepth.
@@ -92,6 +111,7 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
         if (item.Type === 0) {
             // Module: fetch children recursively (unless the depth limit is reached)
             let processedChildren = [];
+            let childrenUnavailable;
             if (currentDepth < depthLimit) {
                 // The parent listing already embeds this module's immediate children
                 // in Structure. The dedicated endpoint is still asked first because it
@@ -100,17 +120,30 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                 // what the parent already handed us. Falling through to an empty list
                 // made a locked or erroring module look like an empty one, and under a
                 // typeFilter it dropped the module from the tree with no trace.
-                let children = await fetchModuleStructure(apiClient, courseId, item.Id);
-                if (!Array.isArray(children)) {
-                    children = Array.isArray(item.Structure) ? item.Structure : [];
+                // When neither copy is readable, the module's children are reported
+                // as null with a reason, never as [], so it can't pass for an empty
+                // module, and the module is kept under any typeFilter because nothing
+                // says it holds no matching items.
+                const structure = await fetchModuleStructure(apiClient, courseId, item.Id);
+                let children = null;
+                if (Array.isArray(structure)) {
+                    children = structure;
+                }
+                else if (Array.isArray(item.Structure)) {
+                    children = item.Structure;
+                }
+                else {
+                    childrenUnavailable = structure;
+                }
+                if (children) {
+                    processedChildren = await buildContentTree(apiClient, courseId, children, progressMap, typeFilter, maxDepth, currentDepth + 1, availability, now);
                 }
-                processedChildren = await buildContentTree(apiClient, courseId, children, progressMap, typeFilter, maxDepth, currentDepth + 1, availability, now);
             }
             else if (currentDepth >= MAX_CONTENT_DEPTH) {
                 log('DEBUG', `Content depth ceiling of ${MAX_CONTENT_DEPTH} reached at module ${item.Id}: not descending further`);
             }
             // Only include module if it has matching children (or filter is 'all')
-            if (typeFilter === 'all' || processedChildren.length > 0) {
+            if (typeFilter === 'all' || processedChildren.length > 0 || childrenUnavailable) {
                 const courseFiles = item.Description?.Html ? extractCourseFilePaths(item.Description.Html, courseId, apiClient.origin) : [];
                 tree.push({
                     type: 'module',
@@ -125,7 +158,8 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                     ...(item.IsLocked ? { isLocked: item.IsLocked } : {}),
                     ...availabilityFields(availability),
                     lastModified: item.LastModifiedDate ?? null,
-                    children: processedChildren,
+                    ...(childrenUnavailable ? { childrenUnavailable } : {}),
+                    children: childrenUnavailable ? null : processedChildren,
                 });
             }
         }
@@ -186,6 +220,12 @@ function filterTreeByModifiedSince(tree, cutoff) {
             }
         }
         else if (item.type === 'module') {
+            // A module whose children couldn't be read stays in, children null:
+            // nothing says none of them changed since the cutoff.
+            if (item.childrenUnavailable) {
+                result.push(item);
+                continue;
+            }
             const filteredChildren = filterTreeByModifiedSince(item.children ?? [], cutoff);
             const moduleMatches = matchesModifiedSince(item.lastModified, cutoff);
             if (moduleMatches || filteredChildren.length > 0) {
@@ -225,6 +265,21 @@ function countModules(tree) {
     }
     return count;
 }
+/**
+ * Count modules whose children couldn't be read (for the notice).
+ */
+export function countUnreadableModules(tree) {
+    let count = 0;
+    for (const item of tree) {
+        if (item.type === 'module') {
+            if (item.childrenUnavailable)
+                count++;
+            if (item.children)
+                count += countUnreadableModules(item.children);
+        }
+    }
+    return count;
+}
 /**
  * Register get_course_content tool
  */
@@ -276,7 +331,8 @@ export function registerGetCourseContent(server, apiClient) {
             }
             const topicCount = countTopics(contentTree);
             const moduleCount = countModules(contentTree);
-            log("INFO", `get_course_content: Retrieved ${moduleCount} modules and ${topicCount} topics for course ${courseId} (filter: ${typeFilter})`);
+            const unreadable = countUnreadableModules(contentTree);
+            log("INFO", `get_course_content: Retrieved ${moduleCount} modules and ${topicCount} topics for course ${courseId} (filter: ${typeFilter})${unreadable > 0 ? `, ${unreadable} module(s) unreadable` : ""}`);
             return toolResponse({
                 courseId,
                 typeFilter,
@@ -284,6 +340,13 @@ export function registerGetCourseContent(server, apiClient) {
                 topicCount,
                 moduleCount,
                 ...(modifiedSince ? { modifiedSince, returned: topicCount, filteredOut } : {}),
+                ...(unreadable > 0
+                    ? {
+                        notice: `The contents of ${unreadable} module(s) couldn't be read; they have children null and a ` +
+                            "childrenUnavailable reason. topicCount leaves out whatever they hold. Do not report " +
+                            "those modules as empty.",
+                    }
+                    : {}),
             });
         }
         catch (error) {

package/build/tools/get-discussions.js

@@ -5,7 +5,7 @@
  */
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetDiscussionsSchema } from "./schemas.js";
-import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { log } from "../utils/logger.js";
 import { discussionUrl } from "../utils/deep-links.js";
@@ -62,6 +62,21 @@ export function registerGetDiscussions(server, apiClient, baseUrl) {
         }
     });
 }
+/**
+ * Describe a failed per-item read, or rethrow it when the session itself is
+ * unusable. A pending or expired sign-in fails every item the same way, and
+ * must fail the call so the user is told to sign in, not shown a course
+ * whose every forum looks empty.
+ */
+function subListUnavailable(error, operation, what) {
+    if (isAuthUnavailable(error))
+        throw error;
+    const status = typeof error?.status === "number" ? error.status : null;
+    const reason = status === 403
+        ? `Brightspace refused this account's request for the ${what}. They may exist; open the discussion in a browser to see what this account can read.`
+        : `Couldn't read the ${what}${status !== null ? ` (Brightspace answered ${status})` : ""}. They may exist; try again.`;
+    return { operation, status, reason };
+}
 /**
  * Get all forums for a course with their topics (no posts).
  */
@@ -69,18 +84,17 @@ async function getForumsOverview(apiClient, courseId) {
     const forums = await fetchForums(apiClient, courseId);
     const result = [];
     for (const forum of forums) {
-        // Fetch topics for each forum
-        let topics = [];
+        // Fetch topics for each forum. A failed read is reported as null with a
+        // reason, never as [], so it can't pass for a forum with no topics.
+        let topics;
+        let topicsUnavailable;
         try {
             topics = await fetchForumTopics(apiClient, courseId, forum.ForumId);
         }
         catch (error) {
-            if (error?.status === 403) {
-                log("DEBUG", `No access to topics for forum ${forum.ForumId}, skipping`);
-            }
-            else {
-                log("DEBUG", `Failed to fetch topics for forum ${forum.ForumId}`, error);
-            }
+            topicsUnavailable = subListUnavailable(error, "listTopics", "topics");
+            log("INFO", `get_discussions: Topics for forum ${forum.ForumId} unavailable`, error);
+            topics = null;
         }
         result.push({
             forumId: forum.ForumId,
@@ -88,7 +102,8 @@ async function getForumsOverview(apiClient, courseId) {
             description: forum.Description?.Text ?? null,
             isLocked: forum.IsLocked,
             isHidden: forum.IsHidden,
-            topics: topics.map((t) => ({
+            ...(topicsUnavailable ? { topicsUnavailable } : {}),
+            topics: topics?.map((t) => ({
                 topicId: t.TopicId,
                 forumId: t.ForumId,
                 name: t.Name,
@@ -98,7 +113,7 @@ async function getForumsOverview(apiClient, courseId) {
                 isHidden: t.IsHidden,
                 mustPostToParticipate: t.MustPostToParticipate,
                 scoreOutOf: t.ScoreOutOf,
-            })),
+            })) ?? null,
         });
     }
     log("INFO", `get_discussions: Retrieved ${forums.length} forums for course ${courseId}`);
@@ -125,22 +140,21 @@ async function getForumDetail(apiClient, courseId, forumId) {
     // Fetch posts for each topic
     const topicsWithPosts = [];
     for (const topic of topics) {
-        let posts = [];
+        // A failed posts read is reported as null with a reason, never as an
+        // empty thread, matching the single-topic view.
+        let formatted;
+        let postsUnavailable;
         try {
             const postsPath = apiClient.le(courseId, `/discussions/forums/${forumId}/topics/${topic.TopicId}/posts/`);
-            posts = await apiClient.get(postsPath, {
+            formatted = formatPosts(await apiClient.get(postsPath, {
                 ttl: DEFAULT_CACHE_TTLS.announcements,
-            });
+            }));
         }
         catch (error) {
-            if (error?.status === 403) {
-                log("DEBUG", `No access to posts for topic ${topic.TopicId}, skipping`);
-            }
-            else {
-                log("DEBUG", `Failed to fetch posts for topic ${topic.TopicId}`, error);
-            }
+            postsUnavailable = subListUnavailable(error, "listPosts", "posts");
+            log("INFO", `get_discussions: Posts for topic ${topic.TopicId} unavailable`, error);
+            formatted = null;
         }
-        const formatted = formatPosts(posts);
         topicsWithPosts.push({
             topicId: topic.TopicId,
             name: topic.Name,
@@ -151,8 +165,9 @@ async function getForumDetail(apiClient, courseId, forumId) {
             isLocked: topic.IsLocked,
             mustPostToParticipate: topic.MustPostToParticipate,
             scoreOutOf: topic.ScoreOutOf,
-            postCount: formatted.length,
+            postCount: formatted?.length ?? null,
             posts: formatted,
+            ...(postsUnavailable ? { postsUnavailable } : {}),
         });
     }
     log("INFO", `get_discussions: Retrieved forum ${forumId} with ${topics.length} topics for course ${courseId}`);

package/build/tools/get-roster.js

@@ -21,6 +21,15 @@ const TEACHING_ROLE_NAME = /\b(instructor|professor|lecturer|teaching assistant|
 function isTeachingRoleByName(user) {
     return TEACHING_ROLE_NAME.test(user.ClasslistRoleDisplayName ?? "");
 }
+/**
+ * Whether a failed role route must be reported rather than skipped. A 403
+ * means the classlist is restricted for that role: nothing was missed.
+ * Anything else (a 404, a 5xx, a dropped connection) leaves a hole the caller
+ * would read as "this course has no TAs".
+ */
+function isReportableFailure(error) {
+    return error?.status !== 403;
+}
 /**
  * Fetch every classlist user matching the optional filters, across all pages.
  *
@@ -60,6 +69,7 @@ export function registerGetRoster(server, apiClient) {
                 const allUsers = [];
                 let authFailure;
                 let roleFallbackUsed = false;
+                let unavailable = [];
                 if (!includeStudents) {
                     // Fetch instructors and TAs in parallel
                     const [instructorResult, taResult] = await Promise.allSettled([
@@ -87,6 +97,10 @@ export function registerGetRoster(server, apiClient) {
                         allUsers.push(...instructorResult.value);
                     }
                     else {
+                        if (!isAuthUnavailable(instructorResult.reason) &&
+                            isReportableFailure(instructorResult.reason)) {
+                            unavailable.push("instructors");
+                        }
                         log("WARN", "get_roster: Failed to fetch instructors", {
                             error: instructorResult.reason,
                         });
@@ -95,6 +109,9 @@ export function registerGetRoster(server, apiClient) {
                         allUsers.push(...taResult.value);
                     }
                     else {
+                        if (!isAuthUnavailable(taResult.reason) && isReportableFailure(taResult.reason)) {
+                            unavailable.push("TAs");
+                        }
                         log("WARN", "get_roster: Failed to fetch TAs", {
                             error: taResult.reason,
                         });
@@ -112,6 +129,9 @@ export function registerGetRoster(server, apiClient) {
                         });
                         allUsers.push(...everyone.filter(isTeachingRoleByName));
                         roleFallbackUsed = true;
+                        // The unfiltered fetch covered every role, so nothing the
+                        // failed role routes would have returned is missing any more.
+                        unavailable = [];
                     }
                 }
                 else {
@@ -139,6 +159,17 @@ export function registerGetRoster(server, apiClient) {
                 }));
                 log("INFO", `get_roster: Retrieved ${users.length} users for course ${courseId}` +
                     (authFailure ? " (sign-in pending for one route)" : ""));
+                const notices = [];
+                if (unavailable.length > 0) {
+                    notices.push(`The ${unavailable.join(" and ")} for this course could not be read from ` +
+                        "Brightspace, so they may be missing from this list. Do not report this " +
+                        `course as having no ${unavailable.join(" or ")}; call get_roster again to retry.`);
+                }
+                if (authFailure) {
+                    notices.push("Sign-in to Brightspace is still in progress, so part of the roster for this " +
+                        `course could not be fetched yet. ${authPendingNotice(authFailure.reason)} Call ` +
+                        "get_roster again once sign-in finishes.");
+                }
                 return toolResponse({
                     courseId,
                     total,
@@ -153,14 +184,9 @@ export function registerGetRoster(server, apiClient) {
                         }
                         : {}),
                     users,
-                    ...(authFailure
-                        ? {
-                            authPending: true,
-                            notice: "Sign-in to Brightspace is still in progress, so part of the roster for this " +
-                                `course could not be fetched yet. ${authPendingNotice(authFailure.reason)} Call ` +
-                                "get_roster again once sign-in finishes.",
-                        }
-                        : {}),
+                    ...(unavailable.length > 0 ? { unavailable } : {}),
+                    ...(authFailure ? { authPending: true } : {}),
+                    ...(notices.length > 0 ? { notice: notices.join(" ") } : {}),
                 });
             }
             catch (error) {

package/build/tools/search-course.js

@@ -7,7 +7,7 @@ import { ApiError } from "../api/index.js";
 import { SearchCourseSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, isAuthUnavailable } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
-import { fetchRootContent, buildContentTree } from "./get-course-content.js";
+import { fetchRootContent, buildContentTree, countUnreadableModules } from "./get-course-content.js";
 import { fetchCourseNews, isPublishedNewsItem, mapNewsItem } from "./get-announcements.js";
 import { fetchForums, fetchForumTopics } from "./get-discussions.js";
 /** A query term matched in the title outranks the same term only in the body. */
@@ -186,6 +186,10 @@ export function registerSearchCourse(server, apiClient) {
                 const rootModules = await fetchRootContent(apiClient, courseId);
                 const tree = await buildContentTree(apiClient, courseId, rootModules, new Map(), "all");
                 entries.push(...flattenContentTree(tree));
+                const unreadable = countUnreadableModules(tree);
+                if (unreadable > 0) {
+                    notes.push(`content inside ${unreadable} module(s) whose contents couldn't be read`);
+                }
             }
             catch (error) {
                 // A pending or refused sign-in is not a source that failed: the

package/package.json

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