brightspace-mcp-server 3.11.4 → 3.11.5

package/build/tools/download-file.js

@@ -247,13 +247,16 @@ async function finishDownload(response, originalFilename, downloadPath, customFi
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content, assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
+        description: "Download a file from course content, instructor assignment attachments (source: assignmentAttachment with folderId + fileId), assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {
             log("DEBUG", "download_file tool called", { args });
             // Parse and validate input
-            const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename } = DownloadFileSchema.parse(args);
+            const { courseId, topicId, folderId, newsId, fileId, downloadPath, customFilename, source } = DownloadFileSchema.parse(args);
+            if (source !== undefined && (topicId !== undefined || newsId !== undefined || folderId === undefined || fileId === undefined)) {
+                return errorResponse("source requires folderId and fileId and cannot be combined with topicId or newsId.");
+            }
             // Validate courseId
             validateContentId(courseId);
             // downloadPath is optional: omitting it means "return the file
@@ -288,7 +291,7 @@ export function registerDownloadFile(server, apiClient) {
                 // Submission file download
                 validateContentId(folderId);
                 validateContentId(fileId);
-                return await downloadSubmissionFile(apiClient, courseId, folderId, fileId, downloadPath, customFilename);
+                return await (source === "assignmentAttachment" ? downloadAssignmentAttachment : downloadSubmissionFile)(apiClient, courseId, folderId, fileId, downloadPath, customFilename);
             }
             else if (newsId !== undefined && fileId !== undefined) {
                 // Announcement attachment download
@@ -305,6 +308,23 @@ export function registerDownloadFile(server, apiClient) {
         }
     });
 }
+/** Download an instructor-provided handout, independently of student submissions. */
+async function downloadAssignmentAttachment(apiClient, courseId, folderId, fileId, downloadPath, customFilename) {
+    const raw = await apiClient.get(apiClient.le(courseId, "/dropbox/folders/"));
+    const folders = Array.isArray(raw) ? raw : raw?.Objects ?? [];
+    const folder = folders.find((candidate) => candidate.Id === folderId && candidate.IsHidden !== true);
+    if (!folder)
+        return errorResponse(`No visible assignment with id ${folderId} in course ${courseId}.`);
+    const attachments = folder.Attachments ?? [];
+    const file = attachments.find((candidate) => candidate.FileId === fileId);
+    if (!file)
+        return errorResponse(`File ID ${fileId} not found on this assignment. Available files: ${attachments.map((candidate) => `${candidate.FileName} (ID: ${candidate.FileId})`).join(", ")}`);
+    if (file.Size > maxFileSize(downloadPath))
+        return tooLargeResponse(file.Size, downloadPath);
+    const response = await apiClient.getRaw(apiClient.le(courseId, `/dropbox/folders/${folderId}/attachments/${fileId}`));
+    const filename = parseContentDispositionFilename(response.headers.get("Content-Disposition") ?? "") ?? file.FileName;
+    return finishDownload(response, filename, downloadPath, customFilename, "Assignment attachment");
+}
 /**
  * Extract a filename from a Content-Disposition header.
  */

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

@@ -60,6 +60,7 @@ export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
                     });
                 }
                 const file = await readAttachment(apiClient, apiClient.le(courseId, `/dropbox/folders/${folderId}/attachments/${fileId}`), attachment, extractText, maxChars);
+                file.downloadArgs = { courseId, folderId, fileId, source: "assignmentAttachment" };
                 return toolResponse({
                     courseId,
                     folderId,
@@ -76,7 +77,10 @@ export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
                 folderName: folder.Name,
                 dueDate: folder.DueDate,
                 url: baseUrl ? assignmentUrl(baseUrl, courseId, folder.Id) : null,
-                attachments: (folder.Attachments ?? []).map(describeAttachment),
+                attachments: (folder.Attachments ?? []).map((attachment) => ({
+                    ...describeAttachment(attachment),
+                    downloadArgs: { courseId, folderId: folder.Id, fileId: attachment.FileId, source: "assignmentAttachment" },
+                })),
             }));
             log("INFO", `get_assignment_files: ${withFiles.length} assignments with attachments in course ${courseId}`);
             return toolResponse({

package/build/tools/schemas.js

@@ -62,14 +62,16 @@ export const GetClasslistEmailsSchema = z.object({
         .describe("Course ID to get emails for."),
 });
 export const DownloadFileSchema = z.object({
+    source: z.enum(["submission", "assignmentAttachment"]).optional()
+        .describe("For folderId + fileId: assignmentAttachment downloads an instructor-provided handout from get_assignment_files; submission (default) downloads your own submitted file. Do not combine source with topicId or newsId."),
     courseId: z.coerce.number().int().positive()
         .describe("Course ID the file belongs to."),
     topicId: z.coerce.number().int().positive().optional()
         .describe("Content topic ID to download (for course content files)."),
     folderId: z.coerce.number().int().positive().optional()
-        .describe("Dropbox folder ID (for submission/feedback file downloads)."),
+        .describe("Dropbox folder ID. Downloads your submission by default; set source to assignmentAttachment for an instructor-provided handout."),
     fileId: z.coerce.number().int().positive().optional()
-        .describe("Specific file ID within a dropbox submission, or an announcement attachment's file ID (with newsId)."),
+        .describe("Specific file ID within a dropbox submission, instructor assignment attachment (with source: assignmentAttachment), or announcement attachment (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).optional()

package/package.json

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