brightspace-mcp-server 3.9.16 → 3.9.17

package/README.md

@@ -71,6 +71,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 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) |
 
 ## Prompts
 

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, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -135,7 +135,14 @@ else {
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION, apiClient);
             registerSearchCourse(server, apiClient);
-            log("DEBUG", "MCP tools registered (19 tools)");
+            // Instructor / TA dropbox tools (read-only) — 403 for a student account.
+            registerGetDropboxFolders(server, apiClient);
+            registerGetDropboxSubmissions(server, apiClient);
+            registerGetDropboxUserSubmissions(server, apiClient);
+            registerGetDropboxFeedback(server, apiClient);
+            registerGetRubricsForObject(server, apiClient);
+            registerDownloadDropboxSubmissionFile(server, apiClient);
+            log("DEBUG", "MCP tools registered (25 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
@@ -148,7 +155,7 @@ else {
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (19 tools, 4 prompts registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (25 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/download-dropbox-submission-file.js

@@ -0,0 +1,131 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { ApiError } from "../api/index.js";
+import { DownloadDropboxSubmissionFileSchema } from "./schemas.js";
+import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+import { validateContentId, MAX_FILE_SIZE } from "../utils/file-validator.js";
+import { secureDownload } from "../utils/download-helpers.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+/**
+ * Register download_dropbox_submission_file tool.
+ */
+export function registerDownloadDropboxSubmissionFile(server, apiClient) {
+    server.registerTool("download_dropbox_submission_file", {
+        title: "Download Dropbox Submission File",
+        description: "Download a specific file from a student's (or group's) dropbox submission to a local directory, " +
+            "for an instructor or TA. Use get_dropbox_submissions or get_dropbox_user_submissions first to " +
+            "find submissionId and fileId. Requires instructor or TA access to the course. " +
+            "IMPORTANT: Ask the user where they want to save the file before calling this tool. " +
+            "After identifying the file, suggest a clean readable filename and ask if they'd like to rename it.",
+        inputSchema: DownloadDropboxSubmissionFileSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "download_dropbox_submission_file tool called", { args });
+            const { courseId, folderId, submissionId, fileId, downloadPath, customFilename } = DownloadDropboxSubmissionFileSchema.parse(args);
+            validateContentId(courseId);
+            validateContentId(folderId);
+            validateContentId(submissionId);
+            validateContentId(fileId);
+            if (!path.isAbsolute(downloadPath)) {
+                return errorResponse("downloadPath must be an absolute path (e.g., /Users/username/Downloads or C:\\Users\\username\\Downloads)");
+            }
+            try {
+                const stats = await fs.stat(downloadPath);
+                if (!stats.isDirectory()) {
+                    return errorResponse(`downloadPath is not a directory: ${downloadPath}`);
+                }
+            }
+            catch (error) {
+                if (error?.code === "ENOENT") {
+                    return errorResponse(`Download directory does not exist: ${downloadPath}`);
+                }
+                throw error;
+            }
+            // Fetch submission metadata to get the file list and validate fileId.
+            const submissionsPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/`);
+            let targetFile = null;
+            try {
+                const raw = await apiClient.get(submissionsPath);
+                const allSubmissions = Array.isArray(raw) ? raw : raw.Objects ?? [];
+                const submission = allSubmissions.find((s) => s.Id === submissionId);
+                if (!submission) {
+                    return errorResponse(`Submission ${submissionId} not found in folder ${folderId}. ` +
+                        "Use get_dropbox_submissions to list available submissions.");
+                }
+                targetFile = submission.Files.find((f) => f.FileId === fileId) ?? null;
+                if (!targetFile) {
+                    const available = submission.Files.map((f) => `${f.FileName} (ID: ${f.FileId})`).join(", ");
+                    return errorResponse(`File ID ${fileId} not found in submission ${submissionId}. Available files: ${available}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 403) {
+                    return errorResponse("Instructor or TA access required for this course. This tool downloads another user's " +
+                        "dropbox submission file, which Brightspace only grants to course staff.");
+                }
+                if (error instanceof ApiError && error.status === 404) {
+                    return errorResponse(`Folder ${folderId} not found in course ${courseId}.`);
+                }
+                throw error;
+            }
+            // Check the size Brightspace reported before downloading anything.
+            if (targetFile.Size > MAX_FILE_SIZE) {
+                return errorResponse(`File too large (${Math.round(targetFile.Size / 1024 / 1024)}MB). ` +
+                    `Maximum allowed: ${MAX_FILE_SIZE / 1024 / 1024}MB`);
+            }
+            const downloadApiPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/${submissionId}/files/${fileId}/download`);
+            let response;
+            try {
+                response = await apiClient.getRaw(downloadApiPath);
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 403) {
+                    return errorResponse("Instructor or TA access required for this course. Brightspace refused this download.");
+                }
+                if (error instanceof ApiError && error.status === 404) {
+                    return errorResponse("File not found on the server. It may have been deleted.");
+                }
+                throw error;
+            }
+            // Check Content-Length before downloading the 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 buffer = Buffer.from(await response.arrayBuffer());
+            // Double-check the actual size once downloaded.
+            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 = targetFile.FileName;
+            const effectiveFilename = customFilename || originalFilename;
+            // secureDownload applies this project's path-containment and
+            // magic-byte file-type checks and resolves filename conflicts,
+            // rather than writing the fetched buffer straight to disk.
+            const result = await secureDownload({
+                targetDir: downloadPath,
+                filename: effectiveFilename,
+                data: buffer,
+            });
+            log("INFO", `download_dropbox_submission_file: saved ${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}`,
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-dropbox-feedback.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 { ApiError } from "../api/index.js";
+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";
+/**
+ * Register get_dropbox_feedback tool.
+ */
+export function registerGetDropboxFeedback(server, apiClient) {
+    server.registerTool("get_dropbox_feedback", {
+        title: "Get Dropbox Feedback",
+        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.",
+        inputSchema: GetDropboxFeedbackSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_dropbox_feedback tool called", { args });
+            const { courseId, folderId, entityType, entityId } = GetDropboxFeedbackSchema.parse(args);
+            const feedbackPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/feedback/${entityType}/${entityId}`);
+            let feedback;
+            try {
+                feedback = await apiClient.get(feedbackPath);
+            }
+            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.");
+                }
+                if (error instanceof ApiError && error.status === 404) {
+                    return toolResponse({
+                        courseId,
+                        folderId,
+                        entityType,
+                        entityId,
+                        feedback: null,
+                        note: "No feedback found. This submission has not been graded yet.",
+                    });
+                }
+                throw error;
+            }
+            const feedbackMarkdown = feedback.Feedback?.Html
+                ? convertHtmlToMarkdown(feedback.Feedback.Html).markdown
+                : null;
+            const rubricAssessments = feedback.RubricAssessments?.map((ra) => ({
+                rubricId: ra.RubricId,
+                rubricName: ra.Name,
+                totalPoints: ra.TotalPoints,
+                // Adapted from get-rubrics-for-object.ts's defensive ?? [] — some
+                // tenants return a null Criteria array on an unscored assessment.
+                criteria: (ra.Criteria ?? []).map((c) => ({
+                    criterionId: c.CriterionId,
+                    selectedLevelId: c.LevelId,
+                    points: c.Points,
+                    comments: c.Comments?.Text ?? null,
+                })),
+            })) ?? [];
+            log("INFO", `get_dropbox_feedback: retrieved feedback for ${entityType} ${entityId} in folder ${folderId}`);
+            return toolResponse({
+                courseId,
+                folderId,
+                entityType,
+                entityId,
+                feedback: {
+                    score: feedback.Score,
+                    isGraded: feedback.IsGraded,
+                    feedbackText: feedback.Feedback?.Text ?? null,
+                    feedbackMarkdown,
+                    rubricAssessments,
+                },
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

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

@@ -0,0 +1,86 @@
+/**
+ * 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 { GetDropboxFoldersSchema } from "./schemas.js";
+import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+/** Map SubmissionType integer to a readable label. */
+function submissionTypeLabel(t) {
+    switch (t) {
+        case 0: return "file";
+        case 1: return "text";
+        case 2: return "on_paper";
+        case 3: return "observed_in_person";
+        default: return "unknown";
+    }
+}
+/**
+ * Register get_dropbox_folders tool.
+ */
+export function registerGetDropboxFolders(server, apiClient) {
+    server.registerTool("get_dropbox_folders", {
+        title: "Get Dropbox Folders",
+        description: "List all assignment/dropbox folders for a course, for an instructor or TA. Returns folder ID, " +
+            "name, due date, start/end dates, submission type, visibility, and whether rubrics are attached. " +
+            "Use this to discover folderId values before calling get_dropbox_submissions, " +
+            "get_dropbox_user_submissions, get_dropbox_feedback, or get_rubrics_for_object. " +
+            "This reads the same folder listing a student's own client uses, so it is not gated to " +
+            "instructor/TA accounts the way get_dropbox_submissions, get_dropbox_feedback, and " +
+            "download_dropbox_submission_file are.",
+        inputSchema: GetDropboxFoldersSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_dropbox_folders tool called", { args });
+            const { courseId } = GetDropboxFoldersSchema.parse(args);
+            const apiPath = apiClient.le(courseId, "/dropbox/folders/");
+            let rawFolders;
+            try {
+                const response = await apiClient.get(apiPath, { ttl: DEFAULT_CACHE_TTLS.assignments });
+                rawFolders = Array.isArray(response) ? response : response.Objects ?? [];
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 403) {
+                    return errorResponse("Instructor or TA access required for this course. This tool reads every student's " +
+                        "dropbox folder metadata, which Brightspace only grants to course staff.");
+                }
+                if (error instanceof ApiError && error.status === 404) {
+                    return toolResponse({
+                        courseId,
+                        folders: [],
+                        note: "No dropbox folders found for this course.",
+                    });
+                }
+                throw error;
+            }
+            const folders = rawFolders.map((f) => ({
+                folderId: f.Id,
+                name: f.Name,
+                categoryId: f.CategoryId,
+                isHidden: f.IsHidden,
+                isGroup: f.GroupTypeId !== null,
+                submissionType: submissionTypeLabel(f.SubmissionType),
+                dueDate: f.DueDate ?? null,
+                startDate: f.StartDate ?? null,
+                endDate: f.EndDate ?? null,
+                maxScore: f.Assessment?.ScoreDenominator ?? null,
+                rubrics: f.Assessment?.Rubrics?.map((r) => ({
+                    rubricId: r.RubricId,
+                    name: r.Name,
+                })) ?? [],
+                hasRubrics: (f.Assessment?.Rubrics?.length ?? 0) > 0,
+            }));
+            log("INFO", `get_dropbox_folders: ${folders.length} folders for course ${courseId}`);
+            return toolResponse({
+                courseId,
+                folders,
+                ...(folders.length === 0 ? { note: "No dropbox folders found for this course." } : {}),
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

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

@@ -0,0 +1,163 @@
+/**
+ * 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 { GetDropboxSubmissionsSchema } from "./schemas.js";
+import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+// Per-submitter feedback lookup is one GET each; cap how many run at once so
+// a large dropbox folder can't fan out hundreds of concurrent requests.
+const FEEDBACK_FETCH_CONCURRENCY = 8;
+/** Run `fn` over `items`, at most `concurrency` in flight at a time. */
+async function mapWithConcurrency(items, concurrency, fn) {
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const item = items[next++];
+            await fn(item);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, worker));
+}
+/**
+ * Register get_dropbox_submissions tool.
+ */
+export function registerGetDropboxSubmissions(server, apiClient) {
+    server.registerTool("get_dropbox_submissions", {
+        title: "Get Dropbox Submissions",
+        description: "List every student's (or group's) submission to a dropbox folder, for an instructor or TA — " +
+            "submitter names, submission dates, late status, file lists, and feedback/grading status. " +
+            "Use get_dropbox_folders first to find folderId. Requires instructor or TA access; a student " +
+            "account gets a clear note instead of data (a student's own download_file / get_assignments " +
+            "already cover their own submission). Results are capped by limit (default 100, max 1000); " +
+            "a truncated response says so and only fetches feedback for the returned slice.",
+        inputSchema: GetDropboxSubmissionsSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_dropbox_submissions tool called", { args });
+            const { courseId, folderId, activeOnly, ignoreFeedback, limit } = GetDropboxSubmissionsSchema.parse(args);
+            const folderPath = apiClient.le(courseId, "/dropbox/folders/");
+            const submissionsPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/`);
+            let rawSubmissions;
+            let folder = null;
+            try {
+                const [foldersRaw, submissionsRaw] = await Promise.all([
+                    apiClient.get(folderPath, { ttl: DEFAULT_CACHE_TTLS.assignments }),
+                    apiClient.get(submissionsPath),
+                ]);
+                const allFolders = Array.isArray(foldersRaw) ? foldersRaw : foldersRaw.Objects ?? [];
+                folder = allFolders.find((f) => f.Id === folderId) ?? null;
+                rawSubmissions = Array.isArray(submissionsRaw) ? submissionsRaw : submissionsRaw.Objects ?? [];
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 403) {
+                    return errorResponse("Instructor or TA access required for this course. This tool reads every student's " +
+                        "dropbox submissions, which Brightspace only grants to course staff.");
+                }
+                if (error instanceof ApiError && error.status === 404) {
+                    return toolResponse({
+                        courseId,
+                        folderId,
+                        folderName: null,
+                        dueDate: null,
+                        submissions: [],
+                        note: `Dropbox folder ${folderId} not found in course ${courseId}.`,
+                    });
+                }
+                throw error;
+            }
+            if (rawSubmissions.length === 0) {
+                return toolResponse({
+                    courseId,
+                    folderId,
+                    folderName: folder?.Name ?? null,
+                    dueDate: folder?.DueDate ?? null,
+                    submissions: [],
+                    note: "No submissions found for this dropbox folder.",
+                });
+            }
+            // Cap the fan-out up front: a large dropbox folder could otherwise
+            // mean hundreds of concurrent per-submitter feedback GETs and an
+            // unbounded payload. Only the kept slice gets a feedback lookup.
+            const total = rawSubmissions.length;
+            const truncated = total > limit;
+            const kept = truncated ? rawSubmissions.slice(0, limit) : rawSubmissions;
+            // Optionally fetch feedback for each kept submitter, a bounded
+            // number at a time. Best-effort: a submitter with no feedback yet
+            // simply has none in the map.
+            const feedbackMap = new Map();
+            if (!ignoreFeedback) {
+                await mapWithConcurrency(kept, FEEDBACK_FETCH_CONCURRENCY, async (sub) => {
+                    try {
+                        const userId = sub.SubmittedBy.Identifier;
+                        const feedbackPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/feedback/user/${userId}`);
+                        const fb = await apiClient.get(feedbackPath);
+                        feedbackMap.set(userId, fb);
+                    }
+                    catch {
+                        // No feedback yet, or this submitter's feedback route
+                        // otherwise failed — silently skip, matching the "not
+                        // graded yet" default below.
+                    }
+                });
+            }
+            const dueDate = folder?.DueDate ? new Date(folder.DueDate) : null;
+            const maxScore = folder?.Assessment?.ScoreDenominator ?? null;
+            const submissions = kept.map((sub) => {
+                const userId = sub.SubmittedBy.Identifier;
+                const submittedAt = new Date(sub.SubmissionDate);
+                const isLate = dueDate !== null && submittedAt > dueDate;
+                const feedback = feedbackMap.get(userId) ?? null;
+                const entry = {
+                    submissionId: sub.Id,
+                    userId,
+                    displayName: sub.SubmittedBy.DisplayName,
+                    submittedDate: sub.SubmissionDate,
+                    isLate,
+                    files: sub.Files.map((f) => ({
+                        fileId: f.FileId,
+                        name: f.FileName,
+                        size: f.Size,
+                    })),
+                    comment: sub.Comment?.Text ?? null,
+                };
+                if (!ignoreFeedback) {
+                    entry.feedbackStatus = feedback
+                        ? {
+                            isGraded: feedback.IsGraded,
+                            score: feedback.Score,
+                            maxScore,
+                            hasFeedbackText: !!feedback.Feedback?.Text,
+                        }
+                        : { isGraded: false, score: null, maxScore, hasFeedbackText: false };
+                }
+                return entry;
+            });
+            // activeOnly: skip submissions that are already fully graded.
+            const filtered = activeOnly && !ignoreFeedback
+                ? submissions.filter((s) => !s.feedbackStatus?.isGraded)
+                : submissions;
+            log("INFO", `get_dropbox_submissions: ${filtered.length} submissions (of ${total} total) for folder ${folderId}`, { truncated });
+            return toolResponse({
+                courseId,
+                folderId,
+                folderName: folder?.Name ?? null,
+                dueDate: folder?.DueDate ?? null,
+                maxScore,
+                totalSubmissions: total,
+                returnedSubmissions: filtered.length,
+                truncated,
+                ...(truncated
+                    ? { note: `Showing ${kept.length} of ${total} submissions. Raise the limit argument to see more.` }
+                    : {}),
+                activeOnly,
+                submissions: filtered,
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-dropbox-user-submissions.js

@@ -0,0 +1,102 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { ApiError } from "../api/index.js";
+import { GetDropboxUserSubmissionsSchema } from "./schemas.js";
+import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+/**
+ * Register get_dropbox_user_submissions tool.
+ */
+export function registerGetDropboxUserSubmissions(server, apiClient) {
+    server.registerTool("get_dropbox_user_submissions", {
+        title: "Get Dropbox User Submissions",
+        description: "Retrieve all submissions made by one specific student (or group) in a dropbox folder, for an " +
+            "instructor or TA — useful for reviewing a single student's work before drafting feedback. " +
+            "Use get_dropbox_submissions or get_roster to find the userId first. Requires instructor or TA " +
+            "access to the course.",
+        inputSchema: GetDropboxUserSubmissionsSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_dropbox_user_submissions tool called", { args });
+            const { courseId, folderId, userId, ignoreFeedback } = GetDropboxUserSubmissionsSchema.parse(args);
+            const submissionsPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/submissions/users/${userId}`);
+            let rawSubmissions;
+            try {
+                const raw = await apiClient.get(submissionsPath);
+                rawSubmissions = Array.isArray(raw) ? raw : raw.Objects ?? [];
+            }
+            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 " +
+                        "dropbox submissions, which Brightspace only grants to course staff.");
+                }
+                if (error instanceof ApiError && error.status === 404) {
+                    return toolResponse({
+                        courseId,
+                        folderId,
+                        userId,
+                        submissions: [],
+                        note: `No submissions found for user ${userId} in dropbox folder ${folderId}. ` +
+                            "The user may not have submitted, or the folder may not exist.",
+                    });
+                }
+                throw error;
+            }
+            if (rawSubmissions.length === 0) {
+                return toolResponse({
+                    courseId,
+                    folderId,
+                    userId,
+                    submissions: [],
+                    note: "No submissions found for this user in the specified folder.",
+                });
+            }
+            let feedback = null;
+            if (!ignoreFeedback) {
+                try {
+                    const feedbackPath = apiClient.le(courseId, `/dropbox/folders/${folderId}/feedback/user/${userId}`);
+                    feedback = await apiClient.get(feedbackPath);
+                }
+                catch {
+                    // No feedback yet — silently skip, matching the "not graded yet" default below.
+                }
+            }
+            const submissions = rawSubmissions.map((sub) => ({
+                submissionId: sub.Id,
+                userId: sub.SubmittedBy.Identifier,
+                displayName: sub.SubmittedBy.DisplayName,
+                submittedDate: sub.SubmissionDate,
+                files: sub.Files.map((f) => ({
+                    fileId: f.FileId,
+                    name: f.FileName,
+                    size: f.Size,
+                })),
+                comment: sub.Comment?.Text ?? null,
+            }));
+            const feedbackStatus = ignoreFeedback
+                ? undefined
+                : feedback
+                    ? {
+                        isGraded: feedback.IsGraded,
+                        score: feedback.Score,
+                        hasFeedbackText: !!feedback.Feedback?.Text,
+                        feedbackText: feedback.Feedback?.Text ?? null,
+                    }
+                    : { isGraded: false, score: null, hasFeedbackText: false, feedbackText: null };
+            log("INFO", `get_dropbox_user_submissions: ${submissions.length} submissions for user ${userId} in folder ${folderId}`);
+            return toolResponse({
+                courseId,
+                folderId,
+                userId,
+                submissions,
+                feedbackStatus,
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/get-rubrics-for-object.js

@@ -0,0 +1,94 @@
+/**
+ * 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 { GetRubricsForObjectSchema } from "./schemas.js";
+import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { log } from "../utils/logger.js";
+/**
+ * Register get_rubrics_for_object tool.
+ */
+export function registerGetRubricsForObject(server, apiClient) {
+    server.registerTool("get_rubrics_for_object", {
+        title: "Get Rubrics for Dropbox Folder",
+        description: "Retrieve the full rubric table (criteria, levels, and point values) attached to a dropbox " +
+            "folder, for an instructor or TA. Use get_dropbox_folders first to find folderId. Like " +
+            "get_dropbox_folders, this reads the folder listing's embedded rubric data, so it is not " +
+            "gated to instructor/TA accounts the way get_dropbox_submissions and get_dropbox_feedback are.",
+        inputSchema: GetRubricsForObjectSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "get_rubrics_for_object tool called", { args });
+            const { courseId, folderId } = GetRubricsForObjectSchema.parse(args);
+            const apiPath = apiClient.le(courseId, "/dropbox/folders/");
+            let rawFolders;
+            try {
+                const response = await apiClient.get(apiPath, { ttl: DEFAULT_CACHE_TTLS.assignments });
+                rawFolders = Array.isArray(response) ? response : response.Objects ?? [];
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 403) {
+                    return errorResponse("Instructor or TA access required for this course. This tool reads dropbox rubric " +
+                        "metadata, which Brightspace only grants to course staff.");
+                }
+                if (error instanceof ApiError && error.status === 404) {
+                    return toolResponse({
+                        courseId,
+                        folderId,
+                        folderName: null,
+                        rubrics: [],
+                        note: `Course ${courseId} was not found.`,
+                    });
+                }
+                throw error;
+            }
+            const folder = rawFolders.find((f) => f.Id === folderId);
+            if (!folder) {
+                return toolResponse({
+                    courseId,
+                    folderId,
+                    folderName: null,
+                    rubrics: [],
+                    note: `Dropbox folder ${folderId} not found in course ${courseId}.`,
+                });
+            }
+            const rubrics = folder.Assessment?.Rubrics;
+            if (!rubrics || rubrics.length === 0) {
+                return toolResponse({
+                    courseId,
+                    folderId,
+                    folderName: folder.Name,
+                    rubrics: [],
+                    note: "No rubrics are attached to this dropbox folder.",
+                });
+            }
+            const formattedRubrics = rubrics.map((r) => ({
+                rubricId: r.RubricId,
+                name: r.Name,
+                criteria: (r.Criteria ?? []).map((c) => ({
+                    criterionId: c.CriterionId,
+                    name: c.Name,
+                    levels: (c.Levels ?? []).map((l) => ({
+                        levelId: l.LevelId,
+                        name: l.Name,
+                        points: l.Points,
+                        description: l.Description?.Text ?? null,
+                    })),
+                })),
+            }));
+            log("INFO", `get_rubrics_for_object: ${formattedRubrics.length} rubric(s) for folder ${folderId}`);
+            return toolResponse({
+                courseId,
+                folderId,
+                folderName: folder.Name,
+                maxScore: folder.Assessment?.ScoreDenominator ?? null,
+                rubrics: formattedRubrics,
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/build/tools/index.js

@@ -23,6 +23,13 @@ export { registerGetDiscussions } from "./get-discussions.js";
 export { registerGetVideoTranscript } from "./get-video-transcript.js";
 export { registerGetServerInfo } from "./get-server-info.js";
 export { registerSearchCourse } from "./search-course.js";
+// Instructor / TA dropbox tools (read-only)
+export { registerGetDropboxFolders } from "./get-dropbox-folders.js";
+export { registerGetDropboxSubmissions } from "./get-dropbox-submissions.js";
+export { registerGetDropboxUserSubmissions } from "./get-dropbox-user-submissions.js";
+export { registerGetDropboxFeedback } from "./get-dropbox-feedback.js";
+export { registerGetRubricsForObject } from "./get-rubrics-for-object.js";
+export { registerDownloadDropboxSubmissionFile } from "./download-dropbox-submission-file.js";
 // Re-export shared helpers and schemas for convenience
 export { toolResponse, errorResponse, sanitizeError } from "./tool-helpers.js";
 export * from "./schemas.js";

package/build/tools/schemas.js

@@ -156,3 +156,64 @@ export const GetMyGroupsSchema = z.object({
         .describe("Course ID to list the current user's project/discussion groups for."),
 });
 export const GetServerInfoSchema = z.object({});
+// ── Instructor / TA dropbox tools ──────────────────────────────────────────
+// Read-only, instructor/TA-side views of a course's dropbox (assignment)
+// folders and the submissions inside them. These answer "who has/hasn't
+// submitted" and "what feedback has already been given", distinct from the
+// student-facing tools above which only ever see the caller's own work.
+export const GetDropboxFoldersSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to list dropbox (assignment) folders for."),
+});
+export const GetDropboxSubmissionsSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID the dropbox folder belongs to."),
+    folderId: z.coerce.number().int().positive()
+        .describe("Dropbox folder ID to list submissions for. Use get_dropbox_folders to find it."),
+    activeOnly: z.boolean().default(false)
+        .describe("When true, skip submissions that have already been fully graded (feedback published with a score). Default false: returns every submission, graded and ungraded."),
+    ignoreFeedback: z.boolean().default(false)
+        .describe("When true, omit feedback status from each submission entry to reduce response size."),
+    limit: z.coerce.number().int().positive().max(1000).default(100)
+        .describe("Maximum submissions to return. Default 100. The response reports the true total and whether it was truncated; feedback is only fetched for the returned slice."),
+});
+export const GetDropboxUserSubmissionsSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID the dropbox folder belongs to."),
+    folderId: z.coerce.number().int().positive()
+        .describe("Dropbox folder ID."),
+    userId: z.coerce.number().int().positive()
+        .describe("Brightspace user ID (or group ID for a group folder) whose submissions to retrieve."),
+    ignoreFeedback: z.boolean().default(false)
+        .describe("When true, omit feedback status from the response."),
+});
+export const GetDropboxFeedbackSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .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."),
+});
+export const GetRubricsForObjectSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID the dropbox folder belongs to."),
+    folderId: z.coerce.number().int().positive()
+        .describe("Dropbox folder ID whose rubric(s) to retrieve full criteria/level detail for."),
+});
+export const DownloadDropboxSubmissionFileSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID the dropbox folder belongs to."),
+    folderId: z.coerce.number().int().positive()
+        .describe("Dropbox folder ID."),
+    submissionId: z.coerce.number().int().positive()
+        .describe("Submission ID, from get_dropbox_submissions or get_dropbox_user_submissions."),
+    fileId: z.coerce.number().int().positive()
+        .describe("File ID within that submission."),
+    downloadPath: z.string().min(1)
+        .describe("Absolute path to the local directory where the file should be saved."),
+    customFilename: z.string().max(255).optional()
+        .describe("Custom filename for the downloaded file (include extension). If omitted, uses the original submission filename."),
+});

package/package.json

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