brightspace-mcp-server 3.13.12 → 3.13.15

package/README.md

@@ -65,7 +65,7 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 
 | About | Try |
 |-------|-----|
-| Grades | "Am I passing all my classes?" · "Compare my grades across courses" · "Is there feedback on my midterm?" (quiz-scored grades link to the quiz, since quiz feedback, including feedback only viewable in LockDown Browser, isn't readable through the API) |
+| Grades | "Am I passing all my classes?" · "Compare my grades across courses" · "What did my professor say about Mini-Assignment 1?" (own assignment feedback is read from every route Brightspace documents for students) · "Is there feedback on my midterm?" (quiz-scored grades link to the quiz, since quiz feedback, including feedback only viewable in LockDown Browser, isn't readable through the API) |
 | Due dates | "What's due in the next 48 hours?" · "Build me a study schedule for the week" |
 | Assignments and rubrics | "What does the lab 4 spec actually ask for?" · "Why did I lose points on the analysis criterion?" |
 | Quizzes and exams | "Which quizzes close this week?" · "Is there a midterm in the gradebook that isn't on my assignments list?" |
@@ -76,7 +76,7 @@ School-specific quirks: [docs/sign-in.md](docs/sign-in.md#per-school-notes).
 | Discussions | "Summarize the latest posts in the final project thread" |
 | Lecture videos | "What did the professor say about pinch-off in Tuesday's recording?" (Kaltura, including BoilerCast LTI links, and YouTube) |
 | Calendar | "When is my midterm?" · "Is lab cancelled on Thursday?" |
-| For instructors and TAs | "Which students haven't submitted Lab 4 yet?" · "What feedback did I leave on this student's homework?" · "Download that student's submitted PDF" (students see a clear "instructor access required" note) |
+| For instructors and TAs | "Which students haven't submitted Lab 4 yet?" · "What feedback did I leave on this student's homework?" · "Download that student's submitted PDF" (students get a clear "instructor access required" note for these, but can read their own released feedback, below) |
 | Signing out | "Sign me out of Brightspace" (your AI app may ask you to confirm first; details under [When it asks you to sign in](#when-it-asks-you-to-sign-in)) |
 
 ## Prompts

package/build/tools/get-announcements.js

@@ -10,6 +10,7 @@ import { toolResponse, toolResponseWithNotice, sanitizeError, isAuthUnavailable,
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 import { matchesModifiedSince } from "../utils/modified-since.js";
+import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 function pageInfo(offset, count, returned, total, unavailableCourseIds = []) {
     const nextOffset = total !== null && offset + returned < total ? offset + returned : null;
     return { offset, count, returned, total, nextOffset, truncated: nextOffset !== null,
@@ -73,6 +74,20 @@ export async function fetchCourseNews(apiClient, courseId) {
         ttl: DEFAULT_CACHE_TTLS.announcements,
     });
 }
+/**
+ * The announcement text a reader should see. D2L's RichText.Text is only "the
+ * plaintext form of the text": it carries no link targets, and the API makes
+ * no promise that it is present or equal to Html. The Html is the post as the
+ * instructor wrote it, so it leads (as markdown, keeping links, lists and
+ * tables); Text is the fallback for a text-only post or Html with nothing
+ * readable in it.
+ */
+export function newsBodyText(body) {
+    if (!body)
+        return "";
+    const markdown = body.Html ? convertHtmlToMarkdown(body.Html).markdown.trim() : "";
+    return markdown || body.Text || "";
+}
 /**
  * Map a raw D2L news item to a clean announcement object.
  */
@@ -85,7 +100,7 @@ export function mapNewsItem(item) {
     return {
         id: item.Id,
         title: item.Title,
-        body: item.Body?.Text ?? "",
+        body: newsBodyText(item.Body),
         createdBy: item.CreatedBy?.DisplayName ?? "Unknown",
         date: effectiveDate(item),
         isPinned: item.IsPinned,
@@ -100,7 +115,7 @@ export function registerGetAnnouncements(server, apiClient, config) {
     server.registerTool("get_announcements", {
         title: "Get Announcements",
         annotations: { readOnlyHint: true },
-        description: "Fetch announcements from one course with courseId, or all courses when omitted, newest first. count is 1-50 per page. Continue with offset= pagination.nextOffset until it is null. Pagination metadata is in a separate JSON text block for array responses, or the pagination field with modifiedSince. A false coverageComplete means some courses were not fetched: retry from offset 0 after recovery. Offsets reflect the current filtered list; new posts can shift pages. Attachments are listed per announcement; fetch them with download_file (newsId + fileId) or read them with get_announcement_files.",
+        description: "Fetch announcements from one course with courseId, or all courses when omitted, newest first. count is 1-50 per page. Each body is the full announcement text as markdown (links kept); pagination.truncated only means more announcements remain, never that a body was cut. Continue with offset= pagination.nextOffset until it is null. Pagination metadata is in a separate JSON text block for array responses, or the pagination field with modifiedSince. A false coverageComplete means some courses were not fetched: retry from offset 0 after recovery. Offsets reflect the current filtered list; new posts can shift pages. Attachments are listed per announcement; fetch them with download_file (newsId + fileId) or read them with get_announcement_files.",
         inputSchema: GetAnnouncementsSchema,
     }, async (args) => {
         try {

package/build/tools/get-assignments.js

@@ -14,6 +14,7 @@ import { gradebookUrl, quizUrl } from "../utils/deep-links.js";
 import { assignmentLinkResolver } from "./assignment-links.js";
 import { dueIn } from "../utils/due-in.js";
 import { feedbackText, FEEDBACK_UNAVAILABLE_NOTE } from "../utils/feedback.js";
+import { fetchCurrentUserId } from "./group-membership.js";
 import { toOutputAssessment } from "./get-assignment-rubric.js";
 /** The display HTML of a quiz rich-text field, nested shape or flat. */
 function richTextHtml(field) {
@@ -144,9 +145,14 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
             // Adapted from JoshuaMontclair/brightspace-mcp-server (MIT).
             let submissions = [];
             let submissionsKnown = true;
+            let embeddedFeedback = null;
             try {
                 const submissionsRaw = await apiClient.get(apiClient.le(courseId, `/dropbox/folders/${folder.Id}/submissions/mysubmissions/`), { ttl: DEFAULT_CACHE_TTLS.assignments });
-                submissions = Array.isArray(submissionsRaw) ? submissionsRaw : submissionsRaw.Objects ?? [];
+                const entries = Array.isArray(submissionsRaw) ? submissionsRaw : submissionsRaw.Objects ?? [];
+                // D2L documents EntityDropbox ({ Feedback, Submissions: [...] }) for this
+                // route; older tenants answer with the flat submissions. Accept both.
+                embeddedFeedback = entries.find((e) => e.Feedback)?.Feedback ?? null;
+                submissions = entries.flatMap((e) => (Array.isArray(e.Submissions) ? e.Submissions : [e]));
             }
             catch (error) {
                 if (isAuthUnavailable(error))
@@ -175,6 +181,34 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                     log("DEBUG", `Failed to fetch feedback for folder ${folder.Id}`, error);
                 }
             }
+            // myFeedback is not one of D2L's documented entity types, so when it has
+            // nothing, read the student's own released feedback from the documented
+            // routes: the Feedback embedded in mysubmissions (already fetched), then
+            // feedback/user/{me}. Draft (IsGraded: false) feedback is not released.
+            let feedbackSource = feedback ? "myFeedback" : null;
+            if (!feedback && submissions.length > 0) {
+                if (embeddedFeedback && embeddedFeedback.IsGraded !== false) {
+                    feedback = embeddedFeedback;
+                    feedbackSource = "submission";
+                }
+                else if (folder.GroupTypeId === null || folder.GroupTypeId === undefined) {
+                    try {
+                        const myId = await fetchCurrentUserId(apiClient);
+                        const own = await apiClient.get(apiClient.le(courseId, `/dropbox/folders/${folder.Id}/feedback/user/${myId}`), { ttl: DEFAULT_CACHE_TTLS.assignments });
+                        if (own && own.IsGraded !== false) {
+                            feedback = own;
+                            feedbackSource = "user";
+                        }
+                    }
+                    catch (error) {
+                        if (isAuthUnavailable(error))
+                            throw error;
+                        log("DEBUG", `Own-feedback fallback failed for folder ${folder.Id}`, error);
+                    }
+                }
+                if (feedback)
+                    feedbackStatus = "retrieved";
+            }
             // Instructor-provided URL links attached to the folder. Omitted
             // entirely (rather than an empty array) when the folder has none, to
             // keep the common case's shape exactly as it was.
@@ -251,6 +285,7 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                     }
                     : null,
                 feedbackStatus,
+                ...(feedbackSource ? { feedbackSource } : {}),
                 feedbackCommentsStatus: commentsRetrieved ? "retrieved" : "unavailable",
                 feedbackUrl: baseUrl ? gradebookUrl(baseUrl, courseId) : null,
                 ...(commentsRetrieved ? {} : { feedbackStatusNote: FEEDBACK_UNAVAILABLE_NOTE }),

package/build/tools/get-dropbox-feedback.js

@@ -8,6 +8,7 @@ import { GetDropboxFeedbackSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { log } from "../utils/logger.js";
+import { fetchCurrentUserId } from "./group-membership.js";
 /**
  * Register get_dropbox_feedback tool.
  */
@@ -15,15 +16,26 @@ export function registerGetDropboxFeedback(server, apiClient) {
     server.registerTool("get_dropbox_feedback", {
         title: "Get Dropbox Feedback",
         annotations: { readOnlyHint: true },
-        description: "Retrieve the existing feedback already saved for a specific user or group in a dropbox folder, " +
-            "for an instructor or TA — score, graded state, feedback text, and rubric assessment detail. " +
-            "Use this before drafting new feedback to see what has already been recorded. Requires " +
-            "instructor or TA access to the course.",
+        description: "Retrieve the feedback saved for a dropbox folder — score, graded state, feedback text, and rubric " +
+            "assessment detail. Students: omit entityType and entityId to read your OWN released feedback on an " +
+            "assignment (it is not hidden; use this when get_assignments shows feedback unavailable). " +
+            "Instructors and TAs: pass entityType and entityId to read what is already saved for any user or " +
+            "group, e.g. before drafting new feedback; reading another user's feedback requires instructor or TA " +
+            "access to the course.",
         inputSchema: GetDropboxFeedbackSchema,
     }, async (args) => {
         try {
             log("DEBUG", "get_dropbox_feedback tool called", { args });
-            const { courseId, folderId, entityType, entityId } = GetDropboxFeedbackSchema.parse(args);
+            const parsed = GetDropboxFeedbackSchema.parse(args);
+            const { courseId, folderId } = parsed;
+            // Omitted entity = the signed-in user's own feedback, which Brightspace
+            // lets a student read once it is released.
+            const own = parsed.entityId === undefined;
+            if (own && parsed.entityType === "group") {
+                return errorResponse("entityId is required when entityType is group.");
+            }
+            const entityType = parsed.entityType ?? "user";
+            const entityId = parsed.entityId ?? await fetchCurrentUserId(apiClient);
             const feedbackPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/feedback/${entityType}/${entityId}`);
             let feedback;
             try {
@@ -31,8 +43,11 @@ export function registerGetDropboxFeedback(server, apiClient) {
             }
             catch (error) {
                 if (error instanceof ApiError && error.status === 403) {
-                    return errorResponse("Instructor or TA access required for this course. This tool reads another user's " +
-                        "grading feedback, which Brightspace only grants to course staff.");
+                    return errorResponse(own
+                        ? "Brightspace refused this read of your own feedback; it has not been released yet, or " +
+                            "this course does not expose it through the API. Check the assignment in Brightspace."
+                        : "Instructor or TA access required for this course. Reading another user's grading " +
+                            "feedback is only granted to course staff; to read your own, omit entityType and entityId.");
                 }
                 if (error instanceof ApiError && error.status === 404) {
                     return toolResponse({
@@ -41,7 +56,9 @@ export function registerGetDropboxFeedback(server, apiClient) {
                         entityType,
                         entityId,
                         feedback: null,
-                        note: "No feedback found. This submission has not been graded yet.",
+                        note: own
+                            ? "No feedback found. This submission has not been graded yet, or its feedback has not been released."
+                            : "No feedback found. This submission has not been graded yet.",
                     });
                 }
                 throw error;

package/build/tools/group-membership.js

@@ -2,12 +2,17 @@ import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { ApiError } from "../api/errors.js";
 const inaccessible = (error) => error instanceof ApiError
     && (error.status === 403 || error.status === 404);
-/** Shared membership lookup. API cache/coalescing bounds repeat reads; no classlist is needed. */
-export async function fetchMyGroupMemberships(apiClient, courseId, categoryId) {
+/** The signed-in user's id, from the cached whoami read. */
+export async function fetchCurrentUserId(apiClient) {
     const me = await apiClient.get(apiClient.lp("/users/whoami"), { ttl: DEFAULT_CACHE_TTLS.roster });
     const myId = Number(me.Identifier);
     if (!Number.isSafeInteger(myId) || myId <= 0)
         throw new Error("Brightspace returned an invalid current user identifier.");
+    return myId;
+}
+/** Shared membership lookup. API cache/coalescing bounds repeat reads; no classlist is needed. */
+export async function fetchMyGroupMemberships(apiClient, courseId, categoryId) {
+    const myId = await fetchCurrentUserId(apiClient);
     let categories;
     try {
         categories = categoryId === undefined

package/build/tools/schemas.js

@@ -196,10 +196,10 @@ export const GetDropboxFeedbackSchema = z.object({
         .describe("Course ID the dropbox folder belongs to."),
     folderId: z.coerce.number().int().positive()
         .describe("Dropbox folder ID."),
-    entityType: z.enum(["user", "group"])
-        .describe("Whether entityId identifies an individual user or a group."),
-    entityId: z.coerce.number().int().positive()
-        .describe("User ID or group ID whose existing feedback to retrieve."),
+    entityType: z.enum(["user", "group"]).optional()
+        .describe("Whether entityId identifies an individual user or a group. Omit both entityType and entityId to read your own feedback."),
+    entityId: z.coerce.number().int().positive().optional()
+        .describe("User ID or group ID whose existing feedback to retrieve. Omit to read the signed-in user's own feedback."),
 });
 export const GetRubricsForObjectSchema = z.object({
     courseId: z.coerce.number().int().positive()

package/build/utils/html-converter.js

@@ -15,6 +15,15 @@ function getTurndownService() {
         turndownService = new TurndownService({
             headingStyle: "atx",
             codeBlockStyle: "fenced",
+            // Turndown routes any element with no text (an <object>, say) to the
+            // blank rule before the rules above are consulted, so an embedded
+            // object has to be recognised here to keep its address.
+            blankReplacement: (_content, node) => {
+                const el = node;
+                if (EMBEDDED_TAGS.includes(el.nodeName))
+                    return embeddedLink(el);
+                return node.isBlock ? "\n\n" : "";
+            },
         });
         // Turndown has no rule for <script>, <style> or <noscript>, so it falls
         // back to emitting their text: a D2L description carrying an inline
@@ -81,6 +90,14 @@ function getTurndownService() {
                 return `[${content}](${cleaned}${titlePart})`;
             },
         });
+        // Embedded frames and media carry no text, so Turndown dropped them
+        // whole: a post whose details sat in an embedded PDF or video read as if
+        // that part did not exist. Keep the address as a link so the model can
+        // see that something was embedded and where it lives.
+        turndownService.addRule("embeddedContent", {
+            filter: ["iframe", "object", "embed", "video", "audio"],
+            replacement: (_content, node) => embeddedLink(node),
+        });
         turndownService.addRule("imageSessionTokens", {
             filter: "img",
             replacement: (_content, node) => {
@@ -95,6 +112,16 @@ function getTurndownService() {
     }
     return turndownService;
 }
+const EMBEDDED_TAGS = ["IFRAME", "OBJECT", "EMBED", "VIDEO", "AUDIO"];
+/** A link to an embedded frame or media file; empty when it has no usable address. */
+function embeddedLink(el) {
+    const raw = el.getAttribute("src") ?? el.getAttribute("data") ?? "";
+    if (!raw.trim() || isUnsafeHref(raw))
+        return "";
+    const label = (el.getAttribute("title") || el.getAttribute("aria-label") || "Embedded content")
+        .replace(/[\[\]]/g, "");
+    return `[${label}](${stripD2lSessionParams(raw).replace(/([()])/g, "\\$1")})`;
+}
 /** True for `javascript:`/`data:` hrefs -- never a legitimate content link. */
 function isUnsafeHref(href) {
     return /^\s*(javascript|data):/i.test(href);

package/package.json

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