brightspace-mcp-server 3.9.5 → 3.9.6

package/README.md

@@ -168,6 +168,7 @@ 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?" |

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, registerGetMyGroups, 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,6 +122,7 @@ 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);
@@ -133,7 +134,7 @@ else {
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION, apiClient);
-            log("DEBUG", "MCP tools registered (17 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
@@ -146,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 (17 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/index.js

@@ -10,6 +10,7 @@ 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";

package/build/tools/schemas.js

@@ -137,6 +137,12 @@ 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."),

package/package.json

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