brightspace-mcp-server 3.9.4 → 3.9.6

package/README.md

@@ -168,10 +168,12 @@ If this is a Docker or other headless setup with no `~/.brightspace-mcp/config.j
 | Assignments | "What's due in the next 48 hours?" · "Summarize every assignment I haven't turned in yet" · "Give me the link to submit HW 4" |
 | Quizzes | "Which quizzes close this week?" · "Is Quiz 3 timed, and does it have a grace period?" |
 | Assignment files | "What does the lab 4 spec actually ask for?" · "Summarize the rubric attached to the project" |
+| Rubrics | "What does the rubric for Lab 4 actually want?" · "Why did I lose points on the analysis criterion?" — `get_assignment_rubric` returns the full criteria groups, levels, and point values for a dropbox assignment, plus your own graded outcome per criterion when the tenant exposes it |
 | Exams | "Is there a midterm in the gradebook that isn't on my assignments list?" |
 | 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, registerGetAssignmentRubric, 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);
@@ -122,17 +122,19 @@ else {
             registerGetMyGrades(server, apiClient, config);
             registerGetAnnouncements(server, apiClient, config);
             registerGetAssignments(server, apiClient, config);
+            registerGetAssignmentRubric(server, apiClient);
             registerGetAssignmentFiles(server, apiClient, config.baseUrl);
             registerGetAnnouncementFiles(server, apiClient);
             registerGetCourseContent(server, apiClient);
             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 (18 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 +147,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 (18 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-assignment-rubric.js

@@ -0,0 +1,276 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { ApiError, DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { GetAssignmentRubricSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { convertHtmlToMarkdown } from "../utils/html-converter.js";
+import { log } from "../utils/logger.js";
+// D2L's documented SCORING_M enumeration
+// (https://docs.valence.desire2learn.com/res/assessment.html). Only values
+// that source confirms are named; an unrecognized value is left as the raw
+// number with no scoringMethodName.
+const SCORING_METHOD_NAMES = {
+    0: "TextOnly",
+    1: "Points",
+    2: "TextAndNumeric",
+    3: "CustomPoints",
+};
+/** Rich text to plain markdown, or undefined when there is nothing to say. */
+function textOf(rt) {
+    if (!rt)
+        return undefined;
+    const text = rt.Html ? convertHtmlToMarkdown(rt.Html).markdown : rt.Text ?? undefined;
+    return text && text.trim().length > 0 ? text : undefined;
+}
+/** The groups a rubric carries, normalizing the grouped and flattened shapes. */
+function groupsOf(rubric) {
+    if (rubric.CriteriaGroups?.length)
+        return rubric.CriteriaGroups;
+    if (rubric.Criteria?.length)
+        return [{ Criteria: rubric.Criteria }];
+    return [];
+}
+/** A criterion's levels, joining the Cells/Levels split or reading them flat. */
+function levelsOfCriterion(group, criterion) {
+    if (criterion.Cells?.length) {
+        const groupLevels = new Map((group.Levels ?? []).map((l) => [l.Id, l]));
+        return criterion.Cells.map((cell) => {
+            const groupLevel = groupLevels.get(cell.LevelId);
+            const points = cell.Points ?? groupLevel?.Points ?? undefined;
+            const out = { name: groupLevel?.Name ?? `Level ${cell.LevelId}` };
+            if (points !== null && points !== undefined)
+                out.points = points;
+            const description = textOf(cell.Description);
+            if (description)
+                out.description = description;
+            return out;
+        });
+    }
+    return (criterion.Levels ?? []).map((level) => {
+        const out = { name: level.Name };
+        if (level.Points !== null && level.Points !== undefined)
+            out.points = level.Points;
+        const description = textOf(level.Description);
+        if (description)
+            out.description = description;
+        return out;
+    });
+}
+function criteriaGroupsOf(rubric) {
+    return groupsOf(rubric).map((group) => ({
+        name: group.Name ?? "",
+        criteria: (group.Criteria ?? []).map((criterion) => ({
+            name: criterion.Name,
+            levels: levelsOfCriterion(group, criterion),
+        })),
+    }));
+}
+/**
+ * Sum of each criterion's best achievable points. A criterion with no
+ * numeric level (a text-only rubric) contributes nothing; the whole field is
+ * left off the response only when every criterion is like that.
+ */
+function totalPointsOf(groups) {
+    let total;
+    for (const group of groups) {
+        for (const criterion of group.criteria) {
+            const points = criterion.levels
+                .map((l) => l.points)
+                .filter((p) => typeof p === "number");
+            if (points.length === 0)
+                continue;
+            total = (total ?? 0) + Math.max(...points);
+        }
+    }
+    return total;
+}
+/** Criterion id -> name, across either rubric shape. */
+function criterionNamesOf(rubric) {
+    const map = new Map();
+    for (const group of groupsOf(rubric)) {
+        for (const criterion of group.Criteria ?? []) {
+            if (typeof criterion.Id === "number")
+                map.set(criterion.Id, criterion.Name);
+        }
+    }
+    return map;
+}
+/** Level id -> name, across either rubric shape. */
+function levelNamesOf(rubric) {
+    const map = new Map();
+    for (const group of rubric.CriteriaGroups ?? []) {
+        for (const level of group.Levels ?? []) {
+            if (typeof level.Id === "number")
+                map.set(level.Id, level.Name);
+        }
+    }
+    for (const criterion of rubric.Criteria ?? []) {
+        for (const level of criterion.Levels ?? []) {
+            const id = level.Id ?? level.LevelId;
+            if (typeof id === "number")
+                map.set(id, level.Name);
+        }
+    }
+    return map;
+}
+/**
+ * The student's own graded outcome on this rubric, resolved against the
+ * rubric's own criterion/level names rather than re-sent by the assessment.
+ */
+function toOutputAssessment(rubric, assessment) {
+    const criterionNames = criterionNamesOf(rubric);
+    const levelNames = levelNamesOf(rubric);
+    const out = { criteria: [] };
+    // Documented Dropbox RubricAssessment carries OverallScore/OverallLevel/
+    // OverallFeedback instead of a nested OverallOutcome; fall back to those
+    // when OverallOutcome itself is absent.
+    const overall = assessment.OverallOutcome ?? {
+        Score: assessment.OverallScore,
+        LevelId: assessment.OverallLevel,
+        Feedback: assessment.OverallFeedback,
+    };
+    if (overall) {
+        if (typeof overall.Score === "number")
+            out.score = overall.Score;
+        const levelName = overall.LevelId != null ? levelNames.get(overall.LevelId) : undefined;
+        if (levelName)
+            out.levelName = levelName;
+        const feedback = textOf(overall.Feedback);
+        if (feedback)
+            out.feedback = feedback;
+    }
+    out.criteria = (assessment.CriteriaOutcome ?? []).map((outcome) => {
+        const entry = {
+            criterionName: criterionNames.get(outcome.CriterionId) ?? `Criterion ${outcome.CriterionId}`,
+        };
+        const levelName = outcome.LevelId != null ? levelNames.get(outcome.LevelId) : undefined;
+        if (levelName)
+            entry.levelName = levelName;
+        if (typeof outcome.Score === "number")
+            entry.score = outcome.Score;
+        const feedback = textOf(outcome.Feedback);
+        if (feedback)
+            entry.feedback = feedback;
+        return entry;
+    });
+    return out;
+}
+function toOutputRubric(rubric, assessment) {
+    const criteriaGroups = criteriaGroupsOf(rubric);
+    const out = {
+        rubricId: rubric.RubricId,
+        name: rubric.Name,
+        criteriaGroups,
+    };
+    const description = textOf(rubric.Description);
+    if (description)
+        out.description = description;
+    if (typeof rubric.ScoringMethod === "number") {
+        out.scoringMethod = rubric.ScoringMethod;
+        const name = SCORING_METHOD_NAMES[rubric.ScoringMethod];
+        if (name)
+            out.scoringMethodName = name;
+    }
+    const totalPoints = totalPointsOf(criteriaGroups);
+    if (totalPoints !== undefined)
+        out.totalPoints = totalPoints;
+    if (assessment)
+        out.rubricAssessment = toOutputAssessment(rubric, assessment);
+    return out;
+}
+/**
+ * Fetch every rubric attached to a dropbox assignment, with the student's own
+ * graded outcome merged in where it is available.
+ *
+ * Rubrics normally ride along embedded in the folder's own
+ * `Assessment.Rubrics`; a tenant/version that omits them there is asked
+ * directly via the rubrics listing endpoint. The student's outcome comes from
+ * `myFeedback`'s `RubricAssessments` — the same route get-assignments.ts
+ * already calls for grade/feedback — never from the unstable rubric
+ * assessment route, which this tool does not call.
+ */
+export async function fetchAssignmentRubrics(apiClient, courseId, assignmentId) {
+    let folder;
+    try {
+        folder = await apiClient.get(apiClient.le(courseId, `/dropbox/folders/${assignmentId}`), { ttl: DEFAULT_CACHE_TTLS.assignments });
+    }
+    catch (error) {
+        if (error instanceof ApiError && error.status === 403) {
+            return {
+                rubrics: [],
+                note: "You do not have permission to view this assignment.",
+            };
+        }
+        if (error instanceof ApiError && error.status === 404) {
+            return {
+                rubrics: [],
+                note: "This assignment was not found. It may not exist or may have been removed.",
+            };
+        }
+        throw error;
+    }
+    let rubrics = folder.Assessment?.Rubrics ?? [];
+    if (rubrics.length === 0) {
+        try {
+            const raw = await apiClient.get(apiClient.le(courseId, `/rubrics?objectType=Dropbox&objectId=${assignmentId}`), { ttl: DEFAULT_CACHE_TTLS.assignments });
+            rubrics = Array.isArray(raw) ? raw : raw?.Objects ?? [];
+        }
+        catch (error) {
+            if (error instanceof ApiError && (error.status === 403 || error.status === 404)) {
+                rubrics = [];
+            }
+            else {
+                log("DEBUG", `Failed to fetch rubrics for assignment ${assignmentId} via the rubrics endpoint`, error);
+                rubrics = [];
+            }
+        }
+    }
+    if (rubrics.length === 0) {
+        return { rubrics: [], note: "This assignment has no rubric attached." };
+    }
+    // Best-effort: the student's outcome is a bonus, not a requirement for the
+    // rubric table itself, and a course that hides feedback should not turn
+    // "here's how it's graded" into an error.
+    const assessmentsByRubricId = new Map();
+    try {
+        const feedback = await apiClient.get(apiClient.le(courseId, `/dropbox/folders/${assignmentId}/feedback/myFeedback/`), { ttl: DEFAULT_CACHE_TTLS.assignments });
+        for (const assessment of feedback?.RubricAssessments ?? []) {
+            if (typeof assessment?.RubricId === "number") {
+                assessmentsByRubricId.set(assessment.RubricId, assessment);
+            }
+        }
+    }
+    catch (error) {
+        if (!(error instanceof ApiError && (error.status === 403 || error.status === 404))) {
+            log("DEBUG", `Failed to fetch rubric assessment feedback for assignment ${assignmentId}`, error);
+            throw error;
+        }
+    }
+    return {
+        rubrics: rubrics.map((r) => toOutputRubric(r, assessmentsByRubricId.get(r.RubricId))),
+    };
+}
+/**
+ * Register get_assignment_rubric tool
+ */
+export function registerGetAssignmentRubric(server, apiClient) {
+    server.registerTool("get_assignment_rubric", {
+        title: "Get Assignment Rubric",
+        description: "Fetch the full grading rubric for a dropbox assignment: every criteria group, criterion, and achievement level with its points and description, plus the student's own graded outcome per criterion once it has been released. Use this when the user asks what a rubric wants, how an assignment will be graded, or why they got a particular score on a criterion.",
+        inputSchema: GetAssignmentRubricSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_assignment_rubric tool called", { args });
+            const { courseId, assignmentId } = GetAssignmentRubricSchema.parse(args);
+            const result = await fetchAssignmentRubrics(apiClient, courseId, assignmentId);
+            log("INFO", `get_assignment_rubric: Retrieved ${result.rubrics.length} rubric(s) for assignment ${assignmentId} in course ${courseId}`);
+            return toolResponse({ courseId, assignmentId, ...result });
+        }
+        catch (error) {
+            return sanitizeError(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

@@ -10,12 +10,14 @@ 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";
+export { registerGetAssignmentRubric } from "./get-assignment-rubric.js";
 export { registerGetAssignmentFiles } from "./get-assignment-files.js";
 export { registerGetAnnouncementFiles } from "./get-announcement-files.js";
 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,14 @@ 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 GetAssignmentRubricSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID the assignment belongs to."),
+    assignmentId: z.coerce.number().int().positive()
+        .describe("Assignment (dropbox folder) ID, as returned by get_assignments."),
+});
+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.6",
   "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",