brightspace-mcp-server 5.1.33 → 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/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.33",
+  "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",