brightspace-mcp-server 3.9.4 → 3.9.5

package/README.md

@@ -172,6 +172,7 @@ If this is a Docker or other headless setup with no `~/.brightspace-mcp/config.j
 | Announcements | "Did any professor post something important today?" · "What did my CS prof announce this week?" · "Any announcements since last Monday?" · "Read the file attached to today's announcement" · "Save the rubric my prof attached to that announcement" |
 | Course content | "Find the midterm review slides" · "Download every PDF from Module 5" · "What's new in this course since I last checked?" |
 | Roster | "Who are the TAs for ECE 264?" · "Get me my instructor's email" |
+| Groups | "Who is in my project group?" · "List my lab group members for this course" |
 | 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?" · "What timezone are my due dates being computed in?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, whether a credential is stored, the server's local timezone and UTC offset (`localTimezone`, `utcOffsetMinutes`), who the session is signed in as when known (`signedInAs: { uniqueName, displayName }`), what Microsoft remembered (`microsoftSession`: stay-signed-in and its expiry, plus whether "Don't ask again" was ticked, already on, not offered, or left off because `D2L_REMEMBER_MFA` isn't set), and `requests` (lightweight counters: responses by status class, network errors, cache hits/misses, coalesced in-flight joins, and token refreshes), without contacting Brightspace or revealing secrets |

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, registerGetCalendarEvents, 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, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -128,11 +128,12 @@ else {
             registerDownloadFile(server, apiClient);
             registerGetClasslistEmails(server, apiClient);
             registerGetRoster(server, apiClient);
+            registerGetMyGroups(server, apiClient);
             registerGetSyllabus(server, apiClient);
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION, apiClient);
-            log("DEBUG", "MCP tools registered (16 tools)");
+            log("DEBUG", "MCP tools registered (17 tools)");
             // Register MCP prompts — surfaced in clients (e.g. Claude Desktop) as a
             // picker, distinct from tools. Each one is a canned user message that
             // names our own tools by name, so a client with no idea what to ask
@@ -145,7 +146,7 @@ else {
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (16 tools, 4 prompts registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (17 tools, 4 prompts registered)");
             log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
         }
         catch (error) {

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

@@ -0,0 +1,122 @@
+/**
+ * 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 { ApiError } from "../api/errors.js";
+import { GetMyGroupsSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { fetchClasslistUsers } from "./get-roster.js";
+import { log } from "../utils/logger.js";
+/** True when a group/category endpoint simply isn't there for this course or user. */
+function isMissingOrForbidden(error) {
+    return error instanceof ApiError && (error.status === 403 || error.status === 404);
+}
+/**
+ * Register get_my_groups tool
+ */
+export function registerGetMyGroups(server, apiClient) {
+    server.registerTool("get_my_groups", {
+        title: "Get My Groups",
+        description: "List the current user's project/discussion groups in a course, with each group's members. " +
+            "Use this when a student asks who is in their project group, lab group, or discussion group.",
+        inputSchema: GetMyGroupsSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_my_groups tool called", { args });
+            const { courseId } = GetMyGroupsSchema.parse(args);
+            const me = await apiClient.get(apiClient.lp("/users/whoami"));
+            const myId = Number(me.Identifier);
+            let categories;
+            try {
+                categories = await apiClient.get(apiClient.lp(`/${courseId}/groupcategories/`), { ttl: DEFAULT_CACHE_TTLS.roster });
+            }
+            catch (error) {
+                if (isMissingOrForbidden(error)) {
+                    log("INFO", "get_my_groups: No group categories visible for course", { courseId });
+                    return toolResponse({
+                        courseId,
+                        groups: [],
+                        note: "No groups are visible for this course (it may not use groups, or group info isn't accessible).",
+                    });
+                }
+                throw error;
+            }
+            // Membership is determined first, from GroupDto.Enrollments alone —
+            // no classlist needed for that. The classlist (for member names) is
+            // fetched lazily, only once we know the user is actually in at least
+            // one group, so a user in no groups never pays for a roster fetch.
+            const matches = [];
+            for (const category of categories) {
+                let categoryGroups;
+                try {
+                    categoryGroups = await apiClient.get(apiClient.lp(`/${courseId}/groupcategories/${category.GroupCategoryId}/groups/`), { ttl: DEFAULT_CACHE_TTLS.roster });
+                }
+                catch (error) {
+                    if (isMissingOrForbidden(error)) {
+                        log("WARN", "get_my_groups: Groups not accessible for category, skipping", {
+                            courseId,
+                            categoryId: category.GroupCategoryId,
+                        });
+                        continue;
+                    }
+                    throw error;
+                }
+                for (const group of categoryGroups) {
+                    const enrollments = group.Enrollments ?? [];
+                    if (!enrollments.includes(myId))
+                        continue;
+                    matches.push({ category, group });
+                }
+            }
+            if (matches.length === 0) {
+                log("INFO", `get_my_groups: User is not a member of any group in course ${courseId}`);
+                return toolResponse({
+                    courseId,
+                    groups: [],
+                    note: "Group categories exist for this course, but the current user is not a member of any group.",
+                });
+            }
+            // Best-effort classlist for member names. A course where the current
+            // user lacks classlist access still returns groups, just with
+            // member names left null instead of failing the whole request.
+            // Identifier comes back from D2L as a string on real tenants, even
+            // though it looks numeric, so it must be coerced before it can be
+            // used as a key alongside the numeric Enrollments ids.
+            let classlistById = new Map();
+            try {
+                const classlist = await fetchClasslistUsers(apiClient, courseId);
+                classlistById = new Map(classlist.map((u) => [Number(u.Identifier), u]));
+            }
+            catch (error) {
+                if (isMissingOrForbidden(error)) {
+                    log("INFO", "get_my_groups: Classlist not accessible, member names will be null", { courseId });
+                }
+                else {
+                    throw error;
+                }
+            }
+            const groups = matches.map(({ category, group }) => {
+                const enrollments = group.Enrollments ?? [];
+                const members = enrollments.map((userId) => ({
+                    userId,
+                    name: classlistById.get(userId)?.DisplayName ?? null,
+                }));
+                return {
+                    categoryId: category.GroupCategoryId,
+                    categoryName: category.Name,
+                    groupId: group.GroupId,
+                    groupName: group.Name,
+                    ...(group.Code ? { groupCode: group.Code } : {}),
+                    members,
+                };
+            });
+            log("INFO", `get_my_groups: Found ${groups.length} groups for course ${courseId}`);
+            return toolResponse({ courseId, groups });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-roster.js

@@ -14,9 +14,13 @@ import { log } from "../utils/logger.js";
 const INSTRUCTOR_ROLE_ID = 109;
 const TA_ROLE_ID = 135;
 /**
- * Fetch every classlist user matching the optional filters, across all pages
+ * Fetch every classlist user matching the optional filters, across all pages.
+ *
+ * Exported so other tools that need names for a course's enrolled users
+ * (e.g. get_my_groups resolving group membership) can reuse this instead of
+ * re-implementing the paged classlist fetch.
  */
-async function fetchClasslistUsers(apiClient, courseId, options) {
+export async function fetchClasslistUsers(apiClient, courseId, options) {
     const params = new URLSearchParams();
     if (options?.roleId !== undefined) {
         params.append("roleId", options.roleId.toString());

package/build/tools/index.js

@@ -16,6 +16,7 @@ export { registerGetCourseContent } from "./get-course-content.js";
 export { registerDownloadFile } from "./download-file.js";
 export { registerGetClasslistEmails } from "./get-classlist-emails.js";
 export { registerGetRoster } from "./get-roster.js";
+export { registerGetMyGroups } from "./get-my-groups.js";
 export { registerGetSyllabus } from "./get-syllabus.js";
 export { registerGetDiscussions } from "./get-discussions.js";
 export { registerGetVideoTranscript } from "./get-video-transcript.js";

package/build/tools/schemas.js

@@ -137,4 +137,8 @@ export const GetRosterSchema = z.object({
     limit: z.coerce.number().int().positive().max(1000).default(100)
         .describe("Maximum users to return. Default 100. The response reports the true total and whether it was truncated."),
 });
+export const GetMyGroupsSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to list the current user's project/discussion groups for."),
+});
 export const GetServerInfoSchema = z.object({});

package/package.json

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