brightspace-mcp-server 5.1.35 → 5.1.37

package/build/auth/auth-runner.js

@@ -225,7 +225,7 @@ function descendantPids(parentPid) {
 function forceStop(pid) {
     if (process.platform === "win32") {
         try {
-            execFileSync("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore", timeout: 5000 });
+            execFileSync("taskkill", ["/pid", String(pid), "/t", "/f"], { stdio: "ignore", timeout: 5000, windowsHide: true });
         }
         catch { /* Already exited. */ }
         return;
@@ -900,7 +900,7 @@ export class AuthRunner {
                 try {
                     if (child.pid && process.platform === "win32") {
                         execFileSync("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
-                            stdio: "ignore", timeout: 5000,
+                            stdio: "ignore", timeout: 5000, windowsHide: true,
                         });
                     }
                     else if (child.pid) {

package/build/auth/session-store.js

@@ -10,7 +10,7 @@ import * as os from "node:os";
 import { SessionStoreError } from "../utils/errors.js";
 import { acquireProcessLock, AuthenticationInProgressError } from "./auth-lock.js";
 import { hasSessionEncryptionKey, NativeCredentialStoreError } from "./credential-store.js";
-import { decrypt, readEncryptedRecord, saveEncryptedRecord, trashFile } from "./encrypted-store.js";
+import { decrypt, readEncryptedRecord, saveEncryptedRecord } from "./encrypted-store.js";
 const DEFAULT_SESSION_DIR = path.join(os.homedir(), ".d2l-session");
 /** The saved access token, relative to its session directory. */
 export const SESSION_FILE = "session.json";
@@ -223,6 +223,11 @@ export class SessionStore {
             this.storeError("load", error);
         }
     }
+    /**
+     * Delete the saved session once it reads back. Not moved to Trash: nothing
+     * restores a session, and on Windows Trash's console helper opens a terminal
+     * window from the shared runtime, which has no console to run it in.
+     */
     async clear() {
         try {
             await this.withWriteLock(async () => {
@@ -230,7 +235,7 @@ export class SessionStore {
                 if (!current)
                     return;
                 await this.decode(current);
-                await trashFile(this.sessionFilePath, this.options);
+                await fs.rm(this.sessionFilePath, { force: true });
             });
         }
         catch (error) {
@@ -281,7 +286,7 @@ export class SessionStore {
             return await this.withWriteLock(async () => {
                 if (!equalToken(await this.loadUnlocked(), expected))
                     return false;
-                await trashFile(this.sessionFilePath, this.options);
+                await fs.rm(this.sessionFilePath, { force: true });
                 return true;
             });
         }

package/build/index.js

@@ -138,7 +138,7 @@ else {
             const { resolveHttpPort, resolveHttpToken, startHttpServer } = await import("./http-server.js");
             const running = await startHttpServer({ runtime, token: resolveHttpToken(), port: resolveHttpPort() });
             stopServing = running.close;
-            log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (26 tools, 4 prompts registered)`);
+            log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (28 tools, 4 prompts registered)`);
             log("INFO", "Leave this running; every MCP client on this computer connects to that URL. Press Ctrl+C to stop.");
         }
         catch (error) {

package/build/server.js

@@ -9,7 +9,7 @@ import { D2LApiClient } from "./api/index.js";
 import { trackToolActivity } from "./utils/dev-activity.js";
 import { log } from "./utils/logger.js";
 import { envCredentialRejectedMessage, ENV_COOKIE_REJECTED } from "./utils/commands.js";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, COURSE_FILE_NEEDS_COOKIE, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerSignIn, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, COURSE_FILE_NEEDS_COOKIE, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetAvailableGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerSignIn, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 /**
  * Build the shared runtime. Nothing here reaches Brightspace: API versions
@@ -88,6 +88,7 @@ export function createMcpServer(runtime) {
     registerGetClasslistEmails(server, apiClient);
     registerGetRoster(server, apiClient);
     registerGetMyGroups(server, apiClient);
+    registerGetAvailableGroups(server, apiClient, config);
     registerGetSyllabus(server, apiClient);
     registerGetDiscussions(server, apiClient, config.baseUrl);
     registerGetVideoTranscript(server, apiClient);
@@ -102,7 +103,7 @@ export function createMcpServer(runtime) {
     registerGetDropboxFeedback(server, apiClient);
     registerGetRubricsForObject(server, apiClient);
     registerDownloadDropboxSubmissionFile(server, apiClient);
-    log("DEBUG", "MCP tools registered (26 tools)");
+    log("DEBUG", "MCP tools registered (28 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

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

@@ -0,0 +1,166 @@
+/**
+ * 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 { GetAvailableGroupsSchema } from "./schemas.js";
+import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
+import { fetchCurrentUserId } from "./group-membership.js";
+import { resolveCourses } from "./resolve-courses.js";
+import { log } from "../utils/logger.js";
+/** D2L's GRPENROLL_T values whose groups students pick themselves. */
+const SELF_ENROLLMENT_STYLES = new Set([3, 4, 5]);
+/** Without a courseId, courses that started longer ago than this are skipped unless includeOlder is set. */
+const RECENT_COURSE_MS = 365 * 24 * 60 * 60 * 1000;
+const inaccessible = (error) => error instanceof ApiError && (error.status === 403 || error.status === 404);
+const text = (value) => value?.Text?.trim() || undefined;
+/**
+ * Brightspace shows a category on the "Available Groups" page while its
+ * sign-up window is open; a missing start or expiry date leaves that side open.
+ */
+function signUpOpen(category, now) {
+    if (!SELF_ENROLLMENT_STYLES.has(category.EnrollmentStyle))
+        return false;
+    const start = category.SelfEnrollmentStartDate ? Date.parse(category.SelfEnrollmentStartDate) : -Infinity;
+    const end = category.SelfEnrollmentExpiryDate ? Date.parse(category.SelfEnrollmentExpiryDate) : Infinity;
+    return start <= now && now <= end;
+}
+async function fetchCourseGroups(apiClient, course, myId, now) {
+    const result = { courseId: course.id, courseName: course.name, categories: [], alreadyInGroup: [] };
+    let categories;
+    try {
+        categories = await apiClient.get(apiClient.lp(`/${course.id}/groupcategories/`), { ttl: DEFAULT_CACHE_TTLS.roster });
+    }
+    catch (error) {
+        if (inaccessible(error))
+            return result;
+        throw error;
+    }
+    const unread = [];
+    for (const category of categories.filter((c) => signUpOpen(c, now))) {
+        let groups;
+        try {
+            groups = await apiClient.get(apiClient.lp(`/${course.id}/groupcategories/${category.GroupCategoryId}/groups/`), { ttl: DEFAULT_CACHE_TTLS.roster });
+        }
+        catch (error) {
+            if (inaccessible(error)) {
+                unread.push(category.Name);
+                continue;
+            }
+            throw error;
+        }
+        // Self-enrollment allows one group per category, as on the Available Groups page.
+        const mine = groups.find((g) => g.Enrollments?.some((id) => Number(id) === myId));
+        if (mine) {
+            result.alreadyInGroup.push({ categoryId: category.GroupCategoryId, name: category.Name, groupName: mine.Name });
+            continue;
+        }
+        const max = category.MaxUsersPerGroup ?? null;
+        const showDescriptions = category.DescriptionsVisibleToEnrolees !== false;
+        const open = groups
+            .map((g) => {
+            const members = g.Enrollments?.length ?? 0;
+            const description = showDescriptions ? text(g.Description) : undefined;
+            return {
+                groupId: g.GroupId,
+                name: g.Name,
+                members,
+                spotsLeft: max === null ? null : Math.max(0, max - members),
+                ...(description ? { description } : {}),
+            };
+        })
+            .filter((g) => g.spotsLeft === null || g.spotsLeft > 0);
+        if (open.length === 0)
+            continue;
+        const description = text(category.Description);
+        result.categories.push({
+            categoryId: category.GroupCategoryId,
+            name: category.Name,
+            ...(description ? { description } : {}),
+            signUpCloses: category.SelfEnrollmentExpiryDate ?? null,
+            maxPerGroup: max,
+            groups: open,
+        });
+    }
+    if (unread.length > 0)
+        result.unreadCategories = unread;
+    return result;
+}
+/**
+ * Register get_available_groups tool
+ */
+export function registerGetAvailableGroups(server, apiClient, config) {
+    server.registerTool("get_available_groups", {
+        title: "Get Available Groups",
+        annotations: { readOnlyHint: true },
+        description: "List the groups the current user can still join themselves (self-enrollment), with spots left " +
+            "and when sign-up closes. Use this when a student asks which project or lab groups are open. " +
+            "This tool only reads; joining happens in Brightspace under Groups > Available Groups.",
+        inputSchema: GetAvailableGroupsSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_available_groups tool called", { args });
+            const { courseId, includeOlder } = GetAvailableGroupsSchema.parse(args);
+            const now = Date.now();
+            const myId = await fetchCurrentUserId(apiClient);
+            const enrolled = await resolveCourses(apiClient, config, courseId);
+            // Some schools give courses a start date but never an end date and never
+            // close them, so every past course still counts as active and its old
+            // sign-ups without an expiry still look open. The start date is the only
+            // signal of which courses are current.
+            const courses = courseId || includeOlder ? enrolled : enrolled.filter((course) => {
+                const start = course.startDate ? Date.parse(course.startDate) : NaN;
+                return Number.isFinite(start) && start >= now - RECENT_COURSE_MS;
+            });
+            const olderSkipped = enrolled.length - courses.length;
+            const results = await Promise.allSettled(courses.map((course) => fetchCourseGroups(apiClient, course, myId, now)));
+            const pendingCourseIds = [];
+            const failedCourseIds = [];
+            let firstAuthError = null;
+            const found = results.flatMap((result, i) => {
+                if (result.status === "fulfilled")
+                    return [result.value];
+                if (isAuthUnavailable(result.reason)) {
+                    if (courseId)
+                        throw result.reason;
+                    pendingCourseIds.push(courses[i].id);
+                    firstAuthError ??= result.reason;
+                }
+                else {
+                    if (courseId)
+                        throw result.reason;
+                    failedCourseIds.push(courses[i].id);
+                    log("DEBUG", "get_available_groups: skipping course after fetch failure", result.reason);
+                }
+                return [];
+            });
+            // A course with nothing open is left out so the list stays about choices.
+            const withChoices = found.filter((c) => c.categories.length > 0 || c.alreadyInGroup.length > 0 || c.unreadCategories);
+            const openGroups = withChoices.reduce((n, c) => n + c.categories.reduce((m, cat) => m + cat.groups.length, 0), 0);
+            log("INFO", `get_available_groups: ${openGroups} open groups across ${courses.length} course(s)`);
+            const notes = [];
+            if (withChoices.length === 0)
+                notes.push("No group sign-ups are open in these courses right now.");
+            if (olderSkipped > 0) {
+                notes.push(`Checked the courses that started in the last 12 months; pass includeOlder: true to also check the other ${olderSkipped}.`);
+            }
+            if (failedCourseIds.length > 0) {
+                notes.push(`Couldn't read groups for course(s) ${failedCourseIds.join(", ")}, so open sign-ups there aren't listed.`);
+            }
+            const data = {
+                coursesChecked: courses.length,
+                courses: withChoices,
+                ...(notes.length > 0 ? { note: notes.join(" ") } : {}),
+                ...(pendingCourseIds.length > 0 ? { authPending: true, unavailableCourseIds: pendingCourseIds } : {}),
+            };
+            return pendingCourseIds.length > 0
+                ? toolResponseWithNotice(data, authPendingNotice(firstAuthError))
+                : toolResponse(data);
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-classlist-emails.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllObjects } from "../api/paginate.js";
 import { GetClasslistEmailsSchema } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, toolResponseWithNotice, sanitizeError } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 /**
  * Register get_classlist_emails tool
@@ -37,6 +37,16 @@ export function registerGetClasslistEmails(server, apiClient) {
                 role: user.ClasslistRoleDisplayName,
             }));
             log("INFO", `get_classlist_emails: ${emails.length} emails from ${users.length} users in course ${courseId}`);
+            // People whose email Brightspace hides are left out of the list. Say
+            // so, or a partial list reads as the whole class and an all-hidden
+            // course reads as an empty one.
+            const hidden = users.length - emails.length;
+            if (hidden > 0) {
+                const who = hidden === 1 ? "person" : "people";
+                const has = hidden === 1 ? "has" : "have";
+                return toolResponseWithNotice(emails, `${hidden} of ${users.length} ${who} in this course ${has} no email visible to you ` +
+                    `(Brightspace hides it), so they are not listed.`);
+            }
             return toolResponse(emails);
         }
         catch (error) {

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

@@ -5,10 +5,28 @@
  */
 import { ApiError } from "../api/errors.js";
 import { GetMyGroupsSchema } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable } from "./tool-helpers.js";
 import { fetchClasslistUsers } from "./get-roster.js";
 import { log } from "../utils/logger.js";
 import { fetchMyGroupMemberships } from "./group-membership.js";
+import { decodeEntities } from "../utils/html-attributes.js";
+/**
+ * Names on a group's "View Members" page (group_member_list.d2l), or null when
+ * the page doesn't have the member table. Each data row holds one name in a
+ * single cell; the header row is the only one with a class.
+ */
+export function memberNamesFromPage(html) {
+    const table = /<table\b[^>]*\bd2l-grid\b[^>]*>([\s\S]*?)<\/table>/i.exec(html);
+    if (!table)
+        return null;
+    const names = [];
+    for (const row of table[1].matchAll(/<tr>\s*<td\b[^>]*>([\s\S]*?)<\/td>\s*<\/tr>/gi)) {
+        const name = decodeEntities(row[1].replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+        if (name)
+            names.push(name);
+    }
+    return names;
+}
 /** 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);
@@ -76,6 +94,25 @@ export function registerGetMyGroups(server, apiClient) {
                     throw error;
                 }
             }
+            // Students who can't read the classlist can still open each of their
+            // groups' "View Members" page, so read the names from there. The page
+            // carries no user ids, so the names stay a separate list.
+            const pageNames = new Map();
+            if (namesUnavailable) {
+                for (const { group } of matches) {
+                    try {
+                        const html = await apiClient.getPage(`/d2l/lms/group/group_member_list.d2l?ou=${courseId}&groupId=${group.GroupId}`);
+                        const names = html === null ? null : memberNamesFromPage(html);
+                        if (names)
+                            pageNames.set(group.GroupId, names);
+                    }
+                    catch (error) {
+                        if (isAuthUnavailable(error))
+                            throw error;
+                        log("DEBUG", `get_my_groups: Couldn't read the member page for group ${group.GroupId}`, error);
+                    }
+                }
+            }
             const groups = matches.map(({ category, group }) => {
                 const enrollments = group.Enrollments ?? [];
                 const members = enrollments.map((userId) => ({
@@ -89,15 +126,19 @@ export function registerGetMyGroups(server, apiClient) {
                     groupName: group.Name,
                     ...(group.Code ? { groupCode: group.Code } : {}),
                     members,
+                    ...(pageNames.has(group.GroupId) ? { memberNames: pageNames.get(group.GroupId) } : {}),
                 };
             });
             log("INFO", `get_my_groups: Found ${groups.length} groups for course ${courseId}`);
             // Null names are only meaningful with a reason attached: without one,
             // a caller can't tell "the classlist couldn't be read" from "these
             // members have no names", and may report the group as anonymous.
-            const namesNote = namesUnavailable
-                ? "Couldn't read this course's classlist, so member names are null; only user ids are listed."
-                : undefined;
+            const namesNote = !namesUnavailable ? undefined
+                : pageNames.size === matches.length
+                    ? "Couldn't read this course's classlist, so member names are null; memberNames lists each group's " +
+                        "members from its member page, which doesn't say which name belongs to which user id."
+                    : "Couldn't read this course's classlist, so member names are null; only user ids are listed" +
+                        (pageNames.size > 0 ? ", except where memberNames lists a group's members from its member page." : ".");
             const note = [unreadNote, namesNote].filter(Boolean).join(" ") || undefined;
             return toolResponse({ courseId, groups, ...(note ? { note } : {}) });
         }

package/build/tools/index.js

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

package/build/tools/resolve-courses.js

@@ -33,7 +33,7 @@ export async function resolveCourses(apiClient, config, courseId) {
     }
     if (courseId) {
         const match = items.find((item) => item.OrgUnit.Id === courseId);
-        return [{ id: courseId, name: match?.OrgUnit.Name ?? null }];
+        return [{ id: courseId, name: match?.OrgUnit.Name ?? null, startDate: match?.Access.StartDate ?? null }];
     }
     const filtered = applyCourseFilter(items.map((item) => ({
         id: item.OrgUnit.Id,
@@ -44,5 +44,5 @@ export async function resolveCourses(apiClient, config, courseId) {
         startDate: item.Access.StartDate,
         endDate: item.Access.EndDate,
     })), config.courseFilter);
-    return filtered.map((course) => ({ id: course.id, name: course.name }));
+    return filtered.map((course) => ({ id: course.id, name: course.name, startDate: course.startDate }));
 }

package/build/tools/schemas.js

@@ -160,6 +160,12 @@ 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 GetAvailableGroupsSchema = z.object({
+    courseId: z.coerce.number().int().positive().optional()
+        .describe("Course ID to list joinable groups for. If omitted, checks courses that started in the last 12 months."),
+    includeOlder: z.boolean().default(false)
+        .describe("Without courseId, also check older and undated courses. Schools that never close a course keep years of finished courses whose sign-ups still look open."),
+});
 export const GetServerInfoSchema = z.object({});
 export const SignOutSchema = z.object({});
 export const SignInSchema = z.object({

package/package.json

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