brightspace-mcp-server 3.6.1 → 3.7.0

package/README.md

@@ -120,7 +120,8 @@ Run it from your home folder. On macOS, a terminal that lacks Files and Folders
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |
 | Video transcripts | "What did the professor say about pinch-off in Tuesday's lecture recording?" · "Summarize last week's BoilerCast video" — works for Kaltura and YouTube embeds; other platforms report that they aren't supported yet |
 | Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, and whether a credential is stored, without contacting Brightspace or revealing secrets |
-| Planning | "Build me a study schedule based on my upcoming due dates" · "Which class needs the most attention right now?" — pulls from assignments, quizzes, and graded discussion topics (any topic with a due date) |
+| Calendar | "When is my midterm?" · "What's on my calendar this week?" · "Is lab cancelled on Thursday?" — reads exams, labs, review sessions, and deadlines instructors put only on the course calendar |
+| Planning | "Build me a study schedule based on my upcoming due dates" · "Which class needs the most attention right now?" — pulls from assignments, quizzes, graded discussion topics (any topic with a due date), and course calendar events such as exams and labs |
 
 
 Licensed under the MIT License.

package/build/api/types.js

@@ -12,4 +12,5 @@ export const DEFAULT_CACHE_TTLS = {
     assignments: 600_000, // 10 min
     roster: 3_600_000, // 1 hour
     profile: 3_600_000, // 1 hour
+    calendar: 600_000, // 10 min
 };

package/build/index.js

@@ -16,7 +16,7 @@ import { startUpdateChecks } from "./utils/update-checker.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_VERSION = (() => {
@@ -102,6 +102,7 @@ else {
             // Register MCP tools
             registerGetMyCourses(server, apiClient, config);
             registerGetUpcomingDueDates(server, apiClient, config);
+            registerGetCalendarEvents(server, apiClient, config);
             registerGetMyGrades(server, apiClient, config);
             registerGetAnnouncements(server, apiClient, config);
             registerGetAssignments(server, apiClient, config);
@@ -115,11 +116,11 @@ else {
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION);
-            log("DEBUG", "MCP tools registered (15 tools)");
+            log("DEBUG", "MCP tools registered (16 tools)");
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (15 tools registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (16 tools registered)");
             log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
         }
         catch (error) {

package/build/tools/calendar-events.js

@@ -0,0 +1,79 @@
+/**
+ * Purdue Brightspace MCP Server
+ * 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 { fetchAllObjects } from "../api/paginate.js";
+import { convertHtmlToMarkdown } from "../utils/html-converter.js";
+import { calendarUrl } from "../utils/deep-links.js";
+/**
+ * The item a calendar event was generated from. The types an existing tool
+ * already reports use that tool's own `type` names, so a caller can match an
+ * event to the item it came from.
+ */
+const ENTITY_TYPES = {
+    "D2L.LE.Dropbox.Dropbox": "assignment",
+    "D2L.LE.Quizzing.Quiz": "quiz",
+    "D2L.LE.Discussions.DiscussionTopic": "discussion",
+    "D2L.LE.Discussions.DiscussionForum": "forum",
+    "D2L.LE.Content.ContentObject.ModuleCO": "module",
+    "D2L.LE.Content.ContentObject.TopicCO": "topic",
+    "D2L.LE.Grades.GradeObject": "grade",
+    "D2L.LE.Checklist.ChecklistItem": "checklist",
+    "D2L.LE.Survey.Survey": "survey",
+};
+const HOUR_MS = 60 * 60 * 1000;
+function descriptionMarkdown(description) {
+    const html = typeof description === "string" ? description : description?.Html || description?.Text || "";
+    return convertHtmlToMarkdown(html).markdown.trim();
+}
+/** One raw event as a CalendarEvent, or null when it has no start at all. */
+function toCalendarEvent(raw, baseUrl, course) {
+    // All-day events carry their dates in StartDay/EndDay instead.
+    const start = raw.StartDateTime ?? raw.StartDay ?? null;
+    if (!start)
+        return null;
+    const end = raw.EndDateTime ?? raw.EndDay ?? null;
+    const location = raw.LocationName?.trim();
+    const description = descriptionMarkdown(raw.Description);
+    const entity = raw.AssociatedEntity;
+    return {
+        id: raw.CalendarEventId,
+        title: raw.Title,
+        courseId: course.id,
+        courseName: course.name,
+        start,
+        ...(end ? { end } : {}),
+        ...(location ? { location } : {}),
+        ...(description ? { description } : {}),
+        url: calendarUrl(baseUrl, course.id),
+        ...(entity
+            ? {
+                generatedFrom: {
+                    type: ENTITY_TYPES[entity.AssociatedEntityType] ?? entity.AssociatedEntityType,
+                    id: entity.AssociatedEntityId,
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * Every calendar event in one course that starts inside [from, to] (epoch ms).
+ *
+ * The request window is widened to whole hours so repeated calls within the
+ * cache TTL share one cached response; the exact window is applied here.
+ */
+export async function fetchCourseCalendarEvents(apiClient, baseUrl, course, from, to) {
+    const requestFrom = new Date(Math.floor(from / HOUR_MS) * HOUR_MS).toISOString();
+    const requestTo = new Date(Math.ceil(to / HOUR_MS) * HOUR_MS).toISOString();
+    const raw = await fetchAllObjects(apiClient, apiClient.le(course.id, `/calendar/events/myEvents/?startDateTime=${encodeURIComponent(requestFrom)}&endDateTime=${encodeURIComponent(requestTo)}`), { ttl: DEFAULT_CACHE_TTLS.calendar });
+    return raw
+        .map((event) => toCalendarEvent(event, baseUrl, course))
+        .filter((event) => {
+        if (!event)
+            return false;
+        const start = new Date(event.start).getTime();
+        return Number.isFinite(start) && start >= from && start <= to;
+    });
+}

package/build/tools/get-calendar-events.js

@@ -0,0 +1,44 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { GetCalendarEventsSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+import { resolveCourses } from "./resolve-courses.js";
+import { fetchCourseCalendarEvents } from "./calendar-events.js";
+const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Register get_calendar_events tool
+ */
+export function registerGetCalendarEvents(server, apiClient, config) {
+    server.registerTool("get_calendar_events", {
+        title: "Get Calendar Events",
+        description: "Fetch course calendar events — exams, midterms, labs, recitations, review sessions, schedule changes, and deadlines instructors typed straight onto the calendar — across all your courses or one course, in a time window (default: the next 7 days). Use this when the user asks when an exam is, what's on their calendar, or what's happening this week.",
+        inputSchema: GetCalendarEventsSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_calendar_events tool called", { args });
+            const { courseId, from, to, includeGenerated } = GetCalendarEventsSchema.parse(args);
+            const windowStart = from ? new Date(from).getTime() : Date.now();
+            const windowEnd = to ? new Date(to).getTime() : windowStart + DEFAULT_WINDOW_MS;
+            const courses = await resolveCourses(apiClient, config, courseId);
+            const results = await Promise.allSettled(courses.map((course) => fetchCourseCalendarEvents(apiClient, config.baseUrl, course, windowStart, windowEnd)));
+            const events = results
+                .flatMap((result, i) => {
+                if (result.status === "fulfilled")
+                    return result.value;
+                log("DEBUG", `get_calendar_events: skipping course ${courses[i].id} after fetch failure`, result.reason);
+                return [];
+            })
+                .filter((event) => includeGenerated || !event.generatedFrom)
+                .sort((a, b) => new Date(a.start).getTime() - new Date(b.start).getTime());
+            log("INFO", `get_calendar_events: Retrieved ${events.length} events across ${courses.length} courses`);
+            return toolResponse(events);
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-upcoming-due-dates.js

@@ -4,53 +4,16 @@
  * Licensed under MIT — see LICENSE file for details.
  */
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
-import { fetchAllItems } from "../api/paginate.js";
 import { GetUpcomingDueDatesSchema, } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
-import { applyCourseFilter } from "../utils/course-filter.js";
 import { assignmentUrl, quizUrl, discussionUrl } from "../utils/deep-links.js";
+import { resolveCourses } from "./resolve-courses.js";
+import { fetchCourseCalendarEvents } from "./calendar-events.js";
 /** D2L list endpoints return either a paged { Objects: [...] } or a flat array. */
 function unwrapList(raw) {
     return Array.isArray(raw) ? raw : (raw?.Objects ?? []);
 }
-/**
- * Resolve which courses to query, and their names.
- *
- * A tool-level courseId bypasses the configured course filter, but enrollments
- * are still fetched so the course can be named.
- */
-async function resolveCourses(apiClient, config, courseId) {
-    let items = [];
-    try {
-        // isActive=true tracks the configured policy rather than being pinned on:
-        // a user who set activeOnly:false is asking to see archived courses, and a
-        // query that withholds them leaves applyCourseFilter nothing to let
-        // through. Enrollments are paged, so follow the bookmark chain — a long
-        // enrollment history would otherwise lose every course past the first page,
-        // and every deadline in those courses with it.
-        items = await fetchAllItems(apiClient, apiClient.lp(`/enrollments/myenrollments/?orgUnitTypeId=3${config.courseFilter.activeOnly ? "&isActive=true" : ""}`), { ttl: DEFAULT_CACHE_TTLS.enrollments });
-    }
-    catch (error) {
-        // Without enrollments there is no course list to walk, so only the explicit
-        // single-course case can continue (with an unnamed course).
-        if (!courseId)
-            throw error;
-        log("DEBUG", "get_upcoming_due_dates: could not fetch enrollments for course name", error);
-    }
-    if (courseId) {
-        const match = items.find((item) => item.OrgUnit.Id === courseId);
-        return [{ id: courseId, name: match?.OrgUnit.Name ?? null }];
-    }
-    const filtered = applyCourseFilter(items.map((item) => ({
-        id: item.OrgUnit.Id,
-        name: item.OrgUnit.Name,
-        code: item.OrgUnit.Code,
-        isActive: item.Access.IsActive,
-        canAccess: item.Access.CanAccess,
-    })), config.courseFilter);
-    return filtered.map((course) => ({ id: course.id, name: course.name }));
-}
 /**
  * Collect every graded, dated discussion topic for one course.
  *
@@ -77,19 +40,42 @@ async function fetchDiscussionDueTopics(apiClient, courseId) {
     return topics;
 }
 /**
- * Collect every dated assignment, quiz, and graded discussion topic for one
- * course.
+ * Calendar events as upcoming items, minus the ones Brightspace generated from
+ * an item already in `items` — that item is the better record of the same
+ * deadline. Hand-made events (exams, labs) have no source item and always stay.
+ */
+function calendarItems(events, items) {
+    const listed = new Set(items.map((item) => `${item.type}:${item.id}`));
+    return events
+        .filter((event) => !event.generatedFrom || !listed.has(`${event.generatedFrom.type}:${event.generatedFrom.id}`))
+        .map((event) => ({
+        type: "event",
+        id: event.id,
+        title: event.title,
+        courseId: event.courseId,
+        courseName: event.courseName,
+        dueDate: event.start,
+        startDate: null,
+        endDate: event.end ?? null,
+        ...(event.location ? { location: event.location } : {}),
+        url: event.url,
+    }));
+}
+/**
+ * Collect every dated assignment, quiz, graded discussion topic, and calendar
+ * event starting in [from, to] for one course.
  *
  * No submissions or attempts: the due date lives on the item itself, which is
  * what makes this cheap enough to run across all enrolled courses. A
  * discussion topic counts only when it has a DueDate — an ungraded chat forum
  * has none and should not clutter the list.
  */
-async function fetchCourseDueItems(apiClient, baseUrl, course) {
-    const [dropboxResult, quizResult, discussionResult] = await Promise.allSettled([
+async function fetchCourseDueItems(apiClient, baseUrl, course, from, to) {
+    const [dropboxResult, quizResult, discussionResult, calendarResult] = await Promise.allSettled([
         apiClient.get(apiClient.le(course.id, "/dropbox/folders/"), { ttl: DEFAULT_CACHE_TTLS.assignments }),
         apiClient.get(apiClient.le(course.id, "/quizzes/"), { ttl: DEFAULT_CACHE_TTLS.assignments }),
         fetchDiscussionDueTopics(apiClient, course.id),
+        fetchCourseCalendarEvents(apiClient, baseUrl, course, from, to),
     ]);
     const items = [];
     if (dropboxResult.status === "fulfilled") {
@@ -161,6 +147,12 @@ async function fetchCourseDueItems(apiClient, baseUrl, course) {
     else {
         log("DEBUG", `get_upcoming_due_dates: failed to fetch discussions for course ${course.id}`, discussionResult.reason);
     }
+    if (calendarResult.status === "fulfilled") {
+        items.push(...calendarItems(calendarResult.value, items));
+    }
+    else {
+        log("DEBUG", `get_upcoming_due_dates: failed to fetch calendar events for course ${course.id}`, calendarResult.reason);
+    }
     return items;
 }
 /**
@@ -169,7 +161,7 @@ async function fetchCourseDueItems(apiClient, baseUrl, course) {
 export function registerGetUpcomingDueDates(server, apiClient, config) {
     server.registerTool("get_upcoming_due_dates", {
         title: "Get Upcoming Due Dates",
-        description: "Fetch upcoming due dates across all your courses, derived from the due dates on assignments (dropbox folders), quizzes, and graded discussion topics themselves. Use this when the user asks about deadlines, what's due, upcoming work, or what they need to do this week.",
+        description: "Fetch upcoming due dates across all your courses, derived from the due dates on assignments (dropbox folders), quizzes, and graded discussion topics themselves, plus course calendar events such as exams and labs (type: event). Use this when the user asks about deadlines, what's due, upcoming work, or what they need to do this week.",
         inputSchema: GetUpcomingDueDatesSchema,
     }, async (args) => {
         try {
@@ -182,7 +174,7 @@ export function registerGetUpcomingDueDates(server, apiClient, config) {
             const courses = await resolveCourses(apiClient, config, courseId);
             log("DEBUG", `get_upcoming_due_dates: querying ${courses.length} course(s), window=${daysAhead} days`);
             // Fetch every course in parallel; the API client rate limits itself
-            const results = await Promise.allSettled(courses.map((course) => fetchCourseDueItems(apiClient, config.baseUrl, course)));
+            const results = await Promise.allSettled(courses.map((course) => fetchCourseDueItems(apiClient, config.baseUrl, course, now, windowEnd)));
             const items = results.flatMap((result) => {
                 if (result.status === "fulfilled")
                     return result.value;

package/build/tools/index.js

@@ -6,6 +6,7 @@
 // Tool registration functions - barrel export
 export { registerGetMyCourses } from "./get-my-courses.js";
 export { registerGetUpcomingDueDates } from "./get-upcoming-due-dates.js";
+export { registerGetCalendarEvents } from "./get-calendar-events.js";
 export { registerGetMyGrades } from "./get-my-grades.js";
 export { registerGetAnnouncements } from "./get-announcements.js";
 export { registerGetAssignments } from "./get-assignments.js";

package/build/tools/resolve-courses.js

@@ -0,0 +1,46 @@
+/**
+ * Purdue Brightspace MCP Server
+ * 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 { fetchAllItems } from "../api/paginate.js";
+import { log } from "../utils/logger.js";
+import { applyCourseFilter } from "../utils/course-filter.js";
+/**
+ * Resolve which courses to query, and their names.
+ *
+ * A tool-level courseId bypasses the configured course filter, but enrollments
+ * are still fetched so the course can be named.
+ */
+export async function resolveCourses(apiClient, config, courseId) {
+    let items = [];
+    try {
+        // isActive=true tracks the configured policy rather than being pinned on:
+        // a user who set activeOnly:false is asking to see archived courses, and a
+        // query that withholds them leaves applyCourseFilter nothing to let
+        // through. Enrollments are paged, so follow the bookmark chain — a long
+        // enrollment history would otherwise lose every course past the first page,
+        // and every deadline in those courses with it.
+        items = await fetchAllItems(apiClient, apiClient.lp(`/enrollments/myenrollments/?orgUnitTypeId=3${config.courseFilter.activeOnly ? "&isActive=true" : ""}`), { ttl: DEFAULT_CACHE_TTLS.enrollments });
+    }
+    catch (error) {
+        // Without enrollments there is no course list to walk, so only the explicit
+        // single-course case can continue (with an unnamed course).
+        if (!courseId)
+            throw error;
+        log("DEBUG", "resolveCourses: could not fetch enrollments for course name", error);
+    }
+    if (courseId) {
+        const match = items.find((item) => item.OrgUnit.Id === courseId);
+        return [{ id: courseId, name: match?.OrgUnit.Name ?? null }];
+    }
+    const filtered = applyCourseFilter(items.map((item) => ({
+        id: item.OrgUnit.Id,
+        name: item.OrgUnit.Name,
+        code: item.OrgUnit.Code,
+        isActive: item.Access.IsActive,
+        canAccess: item.Access.CanAccess,
+    })), config.courseFilter);
+    return filtered.map((course) => ({ id: course.id, name: course.name }));
+}

package/build/tools/schemas.js

@@ -22,6 +22,16 @@ export const GetUpcomingDueDatesSchema = z.object({
     daysAhead: z.coerce.number().int().min(1).max(90).default(7).describe("Number of days ahead to look for due dates"),
     courseId: z.coerce.number().int().positive().optional().describe("Filter to a specific course ID"),
 });
+export const GetCalendarEventsSchema = z.object({
+    courseId: z.coerce.number().int().positive().optional()
+        .describe("Course ID to get calendar events for. If omitted, returns events across all enrolled courses."),
+    from: z.string().datetime({ offset: true, message: "from must be an ISO 8601 datetime, e.g. 2026-01-15T00:00:00Z" }).optional()
+        .describe("Start of the window, ISO 8601 (e.g. 2026-01-15T00:00:00Z). Defaults to now."),
+    to: z.string().datetime({ offset: true, message: "to must be an ISO 8601 datetime, e.g. 2026-01-22T00:00:00Z" }).optional()
+        .describe("End of the window, ISO 8601 (e.g. 2026-01-22T00:00:00Z). Defaults to 7 days after from."),
+    includeGenerated: z.boolean().default(false)
+        .describe("Include the events Brightspace generates from assignment, quiz, and discussion due dates (marked with generatedFrom). Off by default because get_upcoming_due_dates and get_assignments already report those."),
+});
 export const GetMyGradesSchema = z.object({
     courseId: z.coerce.number().int().positive().optional().describe("Course ID to get grades for. If omitted, returns grades for all enrolled courses."),
 });

package/build/utils/deep-links.js

@@ -46,3 +46,10 @@ export function gradebookUrl(baseUrl, courseId) {
 export function discussionUrl(baseUrl, courseId, topicId) {
     return `${trimBaseUrl(baseUrl)}/d2l/lms/discussions/threadlist.d2l?ou=${courseId}&tId=${topicId}`;
 }
+/**
+ * Link to a course's calendar. Calendar events have no per-event student page
+ * the API names, so every event in a course shares this one link.
+ */
+export function calendarUrl(baseUrl, courseId) {
+    return `${trimBaseUrl(baseUrl)}/d2l/le/calendar/${courseId}`;
+}

package/package.json

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