brightspace-mcp-server 3.5.0 → 3.6.0

package/README.md

@@ -114,7 +114,7 @@ Run it from your home folder. On macOS, a terminal that lacks Files and Folders
 | 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" |
 | 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?" |
+| 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" |
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |

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, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PKG_VERSION = (() => {
@@ -106,6 +106,7 @@ else {
             registerGetAnnouncements(server, apiClient, config);
             registerGetAssignments(server, apiClient, config);
             registerGetAssignmentFiles(server, apiClient, config.baseUrl);
+            registerGetAnnouncementFiles(server, apiClient);
             registerGetCourseContent(server, apiClient);
             registerDownloadFile(server, apiClient);
             registerGetClasslistEmails(server, apiClient);
@@ -114,11 +115,11 @@ else {
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION);
-            log("DEBUG", "MCP tools registered (14 tools)");
+            log("DEBUG", "MCP tools registered (15 tools)");
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (14 tools registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (15 tools registered)");
             log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
         }
         catch (error) {

package/build/tools/attachment-reader.js

@@ -0,0 +1,83 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT. See LICENSE file for details.
+ */
+import { extractPdfText } from "../utils/pdf-extractor.js";
+import { officeDocumentText } from "../utils/zip-extract.js";
+const KIND_BY_EXTENSION = {
+    pdf: "pdf",
+    docx: "docx",
+    doc: "other",
+    xlsx: "xlsx",
+    xls: "other",
+    pptx: "pptx",
+    ppt: "other",
+    png: "image",
+    jpg: "image",
+    jpeg: "image",
+    gif: "image",
+    webp: "image",
+    txt: "text",
+    md: "text",
+    csv: "text",
+    json: "text",
+};
+export function fileKind(fileName) {
+    const extension = fileName.split(".").pop()?.toLowerCase() ?? "";
+    return KIND_BY_EXTENSION[extension] ?? "other";
+}
+export function describeAttachment(attachment) {
+    return {
+        fileId: attachment.FileId,
+        fileName: attachment.FileName,
+        size: attachment.Size,
+        kind: fileKind(attachment.FileName),
+    };
+}
+/**
+ * Read one attachment from the path that serves its bytes. The text is best
+ * effort: a scanned PDF or an image yields nothing, and that is reported
+ * rather than treated as a failure.
+ */
+export async function readAttachment(apiClient, sourcePath, attachment, extract, maxChars) {
+    const base = describeAttachment(attachment);
+    if (!extract)
+        return { ...base, text: null, note: "Text extraction was not requested." };
+    const response = await apiClient.getRaw(sourcePath);
+    const buffer = Buffer.from(await response.arrayBuffer());
+    let text = null;
+    let note;
+    switch (base.kind) {
+        case "pdf": {
+            const extracted = await extractPdfText(buffer);
+            text = extracted?.text?.trim() || null;
+            if (!text)
+                note = "No text layer in this PDF. It may be a scan.";
+            break;
+        }
+        case "docx":
+        case "xlsx":
+        case "pptx": {
+            text = officeDocumentText(buffer);
+            if (!text)
+                note = "No readable text found in this Office document.";
+            break;
+        }
+        case "text": {
+            text = buffer.toString("utf-8").trim() || null;
+            break;
+        }
+        default: {
+            note = `Cannot extract text from a ${base.kind} file. Use download_file to save it.`;
+        }
+    }
+    const truncated = text !== null && text.length > maxChars;
+    return {
+        ...base,
+        bytes: buffer.length,
+        text: truncated ? text.slice(0, maxChars) : text,
+        truncated,
+        ...(note ? { note } : {}),
+    };
+}

package/build/tools/download-file.js

@@ -19,13 +19,13 @@ import path from "node:path";
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content or assignment submissions to a local directory. Use this when the user wants to download, save, or get a file from Brightspace course content or dropbox submissions. IMPORTANT: You MUST ask the user where they want to save the file before calling this tool. Never guess or assume a download directory. After identifying the file to download, suggest a clean readable filename to the user (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and ask if they'd like to rename it. Pass their preferred name as customFilename, or omit it to keep the original.",
+        description: "Download a file from course content, assignment submissions, or an announcement's attachments to a local directory. Use this when the user wants to download, save, or get a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool. Never guess or assume a download directory. After identifying the file to download, suggest a clean readable filename to the user (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and ask if they'd like to rename it. Pass their preferred name as customFilename, or omit it to keep the original.",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {
             log("DEBUG", "download_file tool called", { args });
             // Parse and validate input
-            const { courseId, topicId, folderId, fileId, downloadPath, customFilename } = DownloadFileSchema.parse(args);
+            const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename } = DownloadFileSchema.parse(args);
             // Validate courseId
             validateContentId(courseId);
             // Validate download path is absolute
@@ -57,8 +57,14 @@ export function registerDownloadFile(server, apiClient) {
                 validateContentId(fileId);
                 return await downloadSubmissionFile(apiClient, courseId, folderId, fileId, downloadPath, customFilename);
             }
+            else if (newsId !== undefined && fileId !== undefined) {
+                // Announcement attachment download
+                validateContentId(newsId);
+                validateContentId(fileId);
+                return await downloadNewsAttachment(apiClient, courseId, newsId, fileId, downloadPath, customFilename);
+            }
             else {
-                return errorResponse("Either topicId (for content files) or both folderId and fileId (for submission files) must be provided");
+                return errorResponse("Either topicId (for content files), both folderId and fileId (for submission files), or both newsId and fileId (for announcement attachments) must be provided");
             }
         }
         catch (error) {
@@ -202,3 +208,50 @@ async function downloadSubmissionFile(apiClient, courseId, folderId, fileId, dow
         message: `File downloaded successfully to ${result.path}`,
     });
 }
+/**
+ * Download an announcement attachment using newsId + fileId
+ */
+async function downloadNewsAttachment(apiClient, courseId, newsId, fileId, downloadPath, customFilename) {
+    log("INFO", `Downloading announcement attachment: courseId=${courseId}, newsId=${newsId}, fileId=${fileId}`);
+    const newsItem = await apiClient.get(apiClient.le(courseId, `/news/${newsId}`));
+    const attachments = newsItem?.Attachments ?? [];
+    const file = attachments.find((f) => f.FileId === fileId);
+    if (!file) {
+        return errorResponse(`File ID ${fileId} not found on this announcement. Available files: ${attachments.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ")}`);
+    }
+    if (file.Size > MAX_FILE_SIZE) {
+        return errorResponse(`File too large (${Math.round(file.Size / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    }
+    // GET /d2l/api/le/(version)/(orgUnitId)/news/(newsItemId)/attachments/(fileId)
+    const response = await apiClient.getRaw(apiClient.le(courseId, `/news/${newsId}/attachments/${fileId}`));
+    // Check Content-Length BEFORE downloading body (prevent memory exhaustion)
+    const contentLength = parseInt(response.headers.get("Content-Length") ?? "0", 10);
+    if (contentLength > MAX_FILE_SIZE) {
+        return errorResponse(`File too large (${Math.round(contentLength / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    }
+    const disposition = response.headers.get("Content-Disposition") ?? "";
+    const filename = parseContentDispositionFilename(disposition) ?? file.FileName;
+    // Download body as buffer
+    const buffer = Buffer.from(await response.arrayBuffer());
+    // Double-check actual size
+    if (buffer.length > MAX_FILE_SIZE) {
+        return errorResponse(`File too large (${Math.round(buffer.length / 1024 / 1024)}MB). Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+    }
+    const originalFilename = filename;
+    const effectiveFilename = customFilename || filename;
+    // Use secureDownload for path traversal prevention, file type validation, and conflict resolution
+    const result = await secureDownload({
+        targetDir: downloadPath,
+        filename: effectiveFilename,
+        data: buffer,
+    });
+    log("INFO", `Announcement attachment downloaded successfully: ${result.path} (${result.size} bytes, ${result.mime})`);
+    return toolResponse({
+        success: true,
+        filePath: result.path,
+        fileSize: result.size,
+        mimeType: result.mime,
+        originalFilename,
+        message: `File downloaded successfully to ${result.path}`,
+    });
+}

package/build/tools/get-announcement-files.js

@@ -0,0 +1,89 @@
+/**
+ * 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 { GetAnnouncementFilesSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { describeAttachment, readAttachment } from "./attachment-reader.js";
+import { effectiveDate, isPublishedNewsItem } from "./get-announcements.js";
+import { log } from "../utils/logger.js";
+/**
+ * The files an instructor attached to an announcement: field-notes prompts,
+ * a rubric, an updated schedule. They hang off the news item, not course
+ * content, so get_course_content never lists them. Same shape as
+ * get_assignment_files: list first, then read one file by id.
+ */
+/** Every posted announcement in the course, narrowed to one when newsId is given. */
+async function listNews(apiClient, courseId, newsId) {
+    const items = await apiClient.get(apiClient.le(courseId, "/news/"), {
+        ttl: DEFAULT_CACHE_TTLS.announcements,
+    });
+    return items
+        .filter(isPublishedNewsItem)
+        .filter((item) => (newsId === undefined ? true : item.Id === newsId));
+}
+export function registerGetAnnouncementFiles(server, apiClient) {
+    server.registerTool("get_announcement_files", {
+        title: "Get Announcement Files",
+        description: "Read the files an instructor attached to an announcement: prompt questions, a rubric, an updated schedule, slides. Call it with just courseId to see which announcements have attachments, then with newsId and fileId to read one. Use this when the user asks what a file attached to an announcement says. Returns the text itself. Use download_file (newsId + fileId) instead when the user wants the file saved to disk.",
+        inputSchema: GetAnnouncementFilesSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_announcement_files tool called", { args });
+            const { courseId, newsId, fileId, extractText, maxChars } = GetAnnouncementFilesSchema.parse(args);
+            if (fileId !== undefined && newsId === undefined) {
+                return toolResponse({
+                    courseId,
+                    error: "newsId is required when fileId is given.",
+                });
+            }
+            const items = await listNews(apiClient, courseId, newsId);
+            if (newsId !== undefined && items.length === 0) {
+                return toolResponse({
+                    courseId,
+                    newsId,
+                    error: `No announcement with id ${newsId} in course ${courseId}.`,
+                });
+            }
+            // Read one file.
+            if (fileId !== undefined) {
+                const item = items[0];
+                const attachments = item.Attachments ?? [];
+                const attachment = attachments.find((a) => a.FileId === fileId);
+                if (!attachment) {
+                    return toolResponse({
+                        courseId,
+                        newsId,
+                        fileId,
+                        error: `No attachment with id ${fileId} on announcement "${item.Title}".`,
+                        available: attachments.map(describeAttachment),
+                    });
+                }
+                const file = await readAttachment(apiClient, apiClient.le(courseId, `/news/${item.Id}/attachments/${fileId}`), attachment, extractText, maxChars);
+                return toolResponse({ courseId, newsId, title: item.Title, file });
+            }
+            // Discovery: which announcements have files, without downloading any.
+            const withFiles = items
+                .filter((item) => (item.Attachments ?? []).length > 0)
+                .map((item) => ({
+                newsId: item.Id,
+                title: item.Title,
+                date: effectiveDate(item),
+                attachments: (item.Attachments ?? []).map(describeAttachment),
+            }));
+            log("INFO", `get_announcement_files: ${withFiles.length} announcements with attachments in course ${courseId}`);
+            return toolResponse({
+                courseId,
+                announcements: withFiles,
+                ...(withFiles.length === 0
+                    ? { note: "No announcement in this course has an attached file." }
+                    : {}),
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-announcements.js

@@ -56,6 +56,11 @@ export function newestFirst(a, b) {
  * Map a raw D2L news item to a clean announcement object.
  */
 export function mapNewsItem(item) {
+    const attachments = (item.Attachments ?? []).map((file) => ({
+        fileId: file.FileId,
+        fileName: file.FileName,
+        size: file.Size,
+    }));
     return {
         id: item.Id,
         title: item.Title,
@@ -64,6 +69,7 @@ export function mapNewsItem(item) {
         date: effectiveDate(item),
         isPinned: item.IsPinned,
         lastModified: item.LastModifiedDate ?? null,
+        ...(attachments.length > 0 ? { attachments } : {}),
     };
 }
 /**
@@ -72,7 +78,7 @@ export function mapNewsItem(item) {
 export function registerGetAnnouncements(server, apiClient, config) {
     server.registerTool("get_announcements", {
         title: "Get Announcements",
-        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said.",
+        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said. 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-assignment-files.js

@@ -6,44 +6,14 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetAssignmentFilesSchema } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
-import { extractPdfText } from "../utils/pdf-extractor.js";
-import { officeDocumentText } from "../utils/zip-extract.js";
+import { describeAttachment, readAttachment, } from "./attachment-reader.js";
 import { assignmentUrl } from "../utils/deep-links.js";
 import { log } from "../utils/logger.js";
+export { fileKind } from "./attachment-reader.js";
 /** D2L list endpoints return either a paged { Objects: [...] } or a flat array. */
 function unwrapList(raw) {
     return Array.isArray(raw) ? raw : (raw?.Objects ?? []);
 }
-const KIND_BY_EXTENSION = {
-    pdf: "pdf",
-    docx: "docx",
-    doc: "other",
-    xlsx: "xlsx",
-    xls: "other",
-    pptx: "pptx",
-    ppt: "other",
-    png: "image",
-    jpg: "image",
-    jpeg: "image",
-    gif: "image",
-    webp: "image",
-    txt: "text",
-    md: "text",
-    csv: "text",
-    json: "text",
-};
-export function fileKind(fileName) {
-    const extension = fileName.split(".").pop()?.toLowerCase() ?? "";
-    return KIND_BY_EXTENSION[extension] ?? "other";
-}
-function describeAttachment(attachment) {
-    return {
-        fileId: attachment.FileId,
-        fileName: attachment.FileName,
-        size: attachment.Size,
-        kind: fileKind(attachment.FileName),
-    };
-}
 /** Every visible folder in the course that has at least one attachment. */
 async function listFolders(apiClient, courseId, folderId) {
     const raw = await apiClient.get(apiClient.le(courseId, "/dropbox/folders/"), {
@@ -53,51 +23,6 @@ async function listFolders(apiClient, courseId, folderId) {
         .filter((folder) => folder.IsHidden !== true)
         .filter((folder) => (folderId === undefined ? true : folder.Id === folderId));
 }
-/**
- * Read one attachment. The text is best effort: a scanned PDF or an image
- * yields nothing, and that is reported rather than treated as a failure.
- */
-async function readAttachment(apiClient, courseId, folderId, attachment, extract, maxChars) {
-    const base = describeAttachment(attachment);
-    if (!extract)
-        return { ...base, text: null, note: "Text extraction was not requested." };
-    const response = await apiClient.getRaw(apiClient.le(courseId, `/dropbox/folders/${folderId}/attachments/${attachment.FileId}`));
-    const buffer = Buffer.from(await response.arrayBuffer());
-    let text = null;
-    let note;
-    switch (base.kind) {
-        case "pdf": {
-            const extracted = await extractPdfText(buffer);
-            text = extracted?.text?.trim() || null;
-            if (!text)
-                note = "No text layer in this PDF. It may be a scan.";
-            break;
-        }
-        case "docx":
-        case "xlsx":
-        case "pptx": {
-            text = officeDocumentText(buffer);
-            if (!text)
-                note = "No readable text found in this Office document.";
-            break;
-        }
-        case "text": {
-            text = buffer.toString("utf-8").trim() || null;
-            break;
-        }
-        default: {
-            note = `Cannot extract text from a ${base.kind} file. Use download_file to save it.`;
-        }
-    }
-    const truncated = text !== null && text.length > maxChars;
-    return {
-        ...base,
-        bytes: buffer.length,
-        text: truncated ? text.slice(0, maxChars) : text,
-        truncated,
-        ...(note ? { note } : {}),
-    };
-}
 export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
     server.registerTool("get_assignment_files", {
         title: "Get Assignment Files",
@@ -134,7 +59,7 @@ export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
                         available: (folder.Attachments ?? []).map(describeAttachment),
                     });
                 }
-                const file = await readAttachment(apiClient, courseId, folderId, attachment, extractText, maxChars);
+                const file = await readAttachment(apiClient, apiClient.le(courseId, `/dropbox/folders/${folderId}/attachments/${fileId}`), attachment, extractText, maxChars);
                 return toolResponse({
                     courseId,
                     folderId,

package/build/tools/index.js

@@ -10,6 +10,7 @@ export { registerGetMyGrades } from "./get-my-grades.js";
 export { registerGetAnnouncements } from "./get-announcements.js";
 export { registerGetAssignments } from "./get-assignments.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";

package/build/tools/schemas.js

@@ -59,7 +59,9 @@ export const DownloadFileSchema = z.object({
     folderId: z.coerce.number().int().positive().optional()
         .describe("Dropbox folder ID (for submission/feedback file downloads)."),
     fileId: z.coerce.number().int().positive().optional()
-        .describe("Specific file ID within a dropbox submission."),
+        .describe("Specific file ID within a dropbox submission, or an announcement attachment's file ID (with newsId)."),
+    newsId: z.coerce.number().int().positive().optional()
+        .describe("Announcement (news item) ID whose attachment to download. Requires fileId."),
     downloadPath: z.string().min(1)
         .describe("Absolute path to the directory where the file should be saved."),
     customFilename: z.string().max(255).optional()
@@ -91,6 +93,18 @@ export const GetAssignmentFilesSchema = z.object({
     maxChars: z.coerce.number().int().positive().max(100000).default(12000)
         .describe("Maximum characters of extracted text to return. The response reports whether it was truncated."),
 });
+export const GetAnnouncementFilesSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID whose announcement attachments to look at."),
+    newsId: z.coerce.number().int().positive().optional()
+        .describe("Announcement (news item) ID. Omit to list every announcement in the course that has attachments."),
+    fileId: z.coerce.number().int().positive().optional()
+        .describe("Attachment file ID to read. Requires newsId. Omit to list the files without reading them."),
+    extractText: z.boolean().default(true)
+        .describe("Extract readable text from the file. Works for PDF, DOCX, XLSX, PPTX, and plain text."),
+    maxChars: z.coerce.number().int().positive().max(100000).default(12000)
+        .describe("Maximum characters of extracted text to return. The response reports whether it was truncated."),
+});
 export const GetVideoTranscriptSchema = z.object({
     courseId: z.coerce.number().int().positive().optional()
         .describe("Course ID the video belongs to. Required together with topicId unless videoUrl is given directly."),

package/package.json

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