brightspace-mcp-server 3.11.7 → 3.11.8

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

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