brightspace-mcp-server 3.9.16 → 3.9.18

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
 
@@ -109,6 +110,7 @@ How often you're asked is up to your school, not this tool. Everything else abou
 
 ## Something not working?
 
+- Run `npx -y brightspace-mcp-server@latest doctor` first — it checks your Node version, saved setup, credential store, Brightspace connectivity, saved sign-in, and installed version, and tells you exactly what to fix.
 - **It works in the terminal but not in the app:** the app starts it separately and may not see your password store yet — see [docs/troubleshooting.md](docs/troubleshooting.md).
 - **Which version do I have?** Ask your AI "which version of the Brightspace server am I running?"
 - **Still stuck?** [Open an issue](https://github.com/RohanMuppa/brightspace-mcp-server/issues) and paste what the terminal printed.

package/build/doctor.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+/**
+ * Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ *
+ * `doctor` — a beginner-facing diagnostic. It runs a fixed, ordered list of
+ * checks (Node version, saved setup, credential store, school reachability,
+ * saved sign-in, one real API call, installed version) and prints one line
+ * per check: a checkmark plus a short description, or a cross plus exactly
+ * one plain-English next step.
+ *
+ * Every check after "setup found" depends on the ones before it, so a
+ * missing config or a broken sign-in is reported once, with everything
+ * downstream marked "skipped" instead of printing a cascade of confusing
+ * errors for the same root cause.
+ *
+ * Like `setup` and `auth`, this never prints a secret: no password, token,
+ * or cookie value appears in any line.
+ */
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as os from "node:os";
+import { configStoreExists, loadConfigStore, } from "./utils/config-store.js";
+import { accountSessionDirectory, expandTilde, readEnvSecret, parseSessionCookieEnv } from "./utils/config.js";
+import { getStoredPassword } from "./auth/credential-store.js";
+import { discoverVersions } from "./api/version-discovery.js";
+import { TokenManager } from "./auth/token-manager.js";
+import { SessionStore } from "./auth/session-store.js";
+import { D2LApiClient } from "./api/client.js";
+import { fetchLatestVersion, isNewerVersion, safeVersionLabel, installKindOf, } from "./utils/update-checker.js";
+import { SETUP_COMMAND, AUTH_COMMAND, GLOBAL_INSTALL_COMMAND, CLEAR_NPX_CACHE_COMMAND, } from "./utils/commands.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function readInstalledVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(path.resolve(__dirname, "..", "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * doctor only ever reads a saved session — it must never write session.json,
+ * trash it, or take the write lock a v1-record migration uses (that lock can
+ * also throw AuthenticationInProgressError while a real sign-in holds it).
+ * SessionStore.peek() is the read-only sibling of load() that does none of
+ * that, so every write-shaped method here is a no-op and load() delegates to
+ * peek() instead of the real load(). Exported for tests, which pass a fake
+ * in place of a real SessionStore to prove the no-op wiring.
+ */
+export function readOnlySessionStore(store) {
+    return {
+        load: () => store.peek(),
+        save: async () => { },
+        clear: async () => { },
+        saveIfCurrent: async () => true,
+        clearIfCurrent: async () => true,
+    };
+}
+/** A TokenManager that can mint from a saved cookie but can never write, clear, or migrate session.json. */
+function readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie) {
+    return new TokenManager({
+        baseUrl,
+        envAccessToken,
+        envSessionCookie,
+        sessionStore: readOnlySessionStore(new SessionStore(sessionDir)),
+    });
+}
+function defaultDoctorDeps() {
+    return {
+        nodeVersion: process.version,
+        platform: process.platform,
+        env: process.env,
+        configStoreExists,
+        loadConfigStore,
+        getStoredPassword,
+        discoverVersions,
+        getSessionToken: (baseUrl, sessionDir, envAccessToken, envSessionCookie) => readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie).getToken(),
+        countCourses: async (baseUrl, sessionDir, envAccessToken, envSessionCookie) => {
+            const apiClient = new D2LApiClient({
+                baseUrl,
+                tokenManager: readOnlyTokenManager(baseUrl, sessionDir, envAccessToken, envSessionCookie),
+            });
+            const coursesPath = apiClient.lp("/enrollments/myenrollments/?orgUnitTypeId=3");
+            const response = await apiClient.get(coursesPath);
+            return { count: response?.Items?.length ?? 0, hasMore: Boolean(response?.PagingInfo?.HasMoreItems) };
+        },
+        fetchLatestVersion,
+        installKind: installKindOf(),
+        installedVersion: readInstalledVersion(),
+    };
+}
+function pass(id, message) {
+    return { id, ok: true, line: `✓ ${message}` };
+}
+function problem(id, message) {
+    return { id, ok: false, line: `✗ ${message}` };
+}
+// ── Individual checks ────────────────────────────────────────────────
+function checkNode(deps) {
+    const major = Number(deps.nodeVersion.replace(/^v/, "").split(".")[0]);
+    if (Number.isFinite(major) && major >= 20) {
+        return pass("node", `Node.js ${deps.nodeVersion} (20 or newer)`);
+    }
+    return problem("node", `Node.js ${deps.nodeVersion} is too old — install Node 20 or newer from https://nodejs.org/, then try again.`);
+}
+/**
+ * Checks the resolved configuration — config.json AND the same env overrides
+ * loadConfig() honours (D2L_BASE_URL, D2L_USERNAME, D2L_ACCESS_TOKEN,
+ * D2L_SESSION_COOKIE) — since a Docker/headless setup legitimately has no
+ * config.json at all and is configured entirely through the environment.
+ * "Neither config.json nor the environment says anything" is the single most
+ * common first-run state for everyone else.
+ */
+function checkConfig(deps) {
+    let store = null;
+    try {
+        if (deps.configStoreExists())
+            store = deps.loadConfigStore();
+    }
+    catch {
+        store = null;
+    }
+    let envAccessToken;
+    let envSessionCookie;
+    try {
+        envAccessToken = readEnvSecret(deps.env.D2L_ACCESS_TOKEN, "D2L_ACCESS_TOKEN");
+        const rawCookie = readEnvSecret(deps.env.D2L_SESSION_COOKIE, "D2L_SESSION_COOKIE");
+        envSessionCookie = rawCookie ? parseSessionCookieEnv(rawCookie) : undefined;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            result: problem("config", error instanceof Error ? error.message : "D2L_ACCESS_TOKEN or D2L_SESSION_COOKIE is malformed."),
+        };
+    }
+    const rawBaseUrl = deps.env.D2L_BASE_URL || store?.baseUrl;
+    const username = deps.env.D2L_USERNAME || store?.username;
+    const hasEnvCredential = Boolean(envAccessToken || envSessionCookie);
+    // A username is required only for the normal stored-password flow: an env
+    // credential signs in on its own and never needs one.
+    if (!rawBaseUrl || (!username && !hasEnvCredential)) {
+        return { ok: false, result: problem("config", `No setup found — run: ${SETUP_COMMAND}`) };
+    }
+    let baseUrl;
+    try {
+        baseUrl = new URL(rawBaseUrl).origin;
+    }
+    catch {
+        return { ok: false, result: problem("config", `The configured Brightspace URL is invalid — run: ${SETUP_COMMAND}`) };
+    }
+    const sessionRoot = deps.env.D2L_SESSION_DIR
+        ? expandTilde(deps.env.D2L_SESSION_DIR)
+        : store?.sessionDir
+            ? expandTilde(store.sessionDir)
+            : path.join(os.homedir(), ".d2l-session");
+    const sessionDir = accountSessionDirectory(sessionRoot, baseUrl, username);
+    const label = username ? `signed in as ${username} at ${baseUrl}` : `configured for ${baseUrl} via environment variables`;
+    return {
+        ok: true,
+        result: pass("config", `Setup found — ${label}`),
+        baseUrl,
+        username,
+        sessionDir,
+        envAccessToken,
+        envSessionCookie,
+    };
+}
+async function checkCredential(deps, baseUrl, username, envAccessToken, envSessionCookie) {
+    // Never print the value — only which variable is supplying it.
+    if (envAccessToken)
+        return pass("credential", "Signed in via the D2L_ACCESS_TOKEN environment variable (no password needed)");
+    if (envSessionCookie)
+        return pass("credential", "Signed in via the D2L_SESSION_COOKIE environment variable (no password needed)");
+    if (!username)
+        return problem("credential", `No username configured — run: ${SETUP_COMMAND}`);
+    try {
+        const password = await deps.getStoredPassword(baseUrl, username);
+        if (password)
+            return pass("credential", "Password saved in your operating system's credential store");
+        return problem("credential", `No saved password found for this account — run: ${SETUP_COMMAND}`);
+    }
+    catch (error) {
+        // On Linux the store itself (secret-tool / an unlocked Secret Service)
+        // is usually the problem, and the thrown error already explains that in
+        // plain English. Elsewhere, re-running setup is the one fix that covers
+        // every native-store failure a student could hit.
+        if (deps.platform === "linux") {
+            return problem("credential", error instanceof Error ? error.message : "The Linux credential store is locked or unavailable. Unlock your keyring and try again.");
+        }
+        return problem("credential", `Run setup again: ${SETUP_COMMAND}`);
+    }
+}
+async function checkNetwork(deps, baseUrl) {
+    try {
+        await deps.discoverVersions(baseUrl);
+        return pass("network", `${baseUrl} is reachable`);
+    }
+    catch {
+        return problem("network", `Could not reach ${baseUrl} — check your internet connection and the school address, then run doctor again.`);
+    }
+}
+async function checkSession(deps, baseUrl, sessionDir, envAccessToken, envSessionCookie) {
+    const failMessage = `No working saved sign-in — open your AI app and ask a question to sign in, or run: ${AUTH_COMMAND}`;
+    try {
+        const token = await deps.getSessionToken(baseUrl, sessionDir, envAccessToken, envSessionCookie);
+        if (token)
+            return { ok: true, result: pass("session", "Saved sign-in works — a token was issued without opening a browser") };
+        return { ok: false, result: problem("session", failMessage) };
+    }
+    catch {
+        return { ok: false, result: problem("session", failMessage) };
+    }
+}
+/**
+ * Trims an upstream error message down to something safe to show a beginner:
+ * a 403/404 body can be a whole HTML page, and either way the raw text can
+ * carry the endpoint URL. Collapses newlines, drops URLs, and caps length.
+ */
+function sanitizeErrorDetail(message) {
+    const noUrls = message.replace(/https?:\/\/\S+/gi, "");
+    const singleLine = noUrls.replace(/\s+/g, " ").trim();
+    const LIMIT = 120;
+    return singleLine.length > LIMIT ? `${singleLine.slice(0, LIMIT).trimEnd()}…` : singleLine;
+}
+async function checkCourses(deps, baseUrl, sessionDir, envAccessToken, envSessionCookie) {
+    try {
+        const { count, hasMore } = await deps.countCourses(baseUrl, sessionDir, envAccessToken, envSessionCookie);
+        const label = hasMore ? `at least ${count}` : `${count}`;
+        return pass("courses", `Found ${label} course${count === 1 ? "" : "s"} on Brightspace`);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? sanitizeErrorDetail(error.message) : "an unknown error";
+        return problem("courses", `Could not load your courses (${detail}) — run doctor again after checking your connection.`);
+    }
+}
+async function checkVersion(deps) {
+    let latest = null;
+    try {
+        latest = await deps.fetchLatestVersion();
+    }
+    catch {
+        latest = null;
+    }
+    const sourceNote = deps.installKind === "source-checkout" ? " (source checkout)" : "";
+    // Offline, or the registry hiccuped: never treat "couldn't check" as a
+    // failure — there is nothing actionable to tell a student here.
+    if (latest === null) {
+        return pass("version", `Running v${safeVersionLabel(deps.installedVersion)}${sourceNote} — could not check for a newer version (you may be offline)`);
+    }
+    if (!isNewerVersion(latest, deps.installedVersion)) {
+        return pass("version", `Running the latest version (v${safeVersionLabel(deps.installedVersion)})${sourceNote}`);
+    }
+    const from = safeVersionLabel(deps.installedVersion);
+    const to = safeVersionLabel(latest);
+    const nextStep = deps.installKind === "source-checkout"
+        ? "pull the latest changes and run npm run build"
+        : deps.installKind === "npm-install"
+            ? `run: ${GLOBAL_INSTALL_COMMAND}`
+            : `it updates automatically next time, or run: ${CLEAR_NPX_CACHE_COMMAND}`;
+    return problem("version", `A newer version is available (v${from} to v${to}) — ${nextStep}.`);
+}
+// ── Orchestration ────────────────────────────────────────────────────
+/** Human-readable name for each check, used to prefix its "Skipped" line. */
+const CHECK_NAMES = {
+    node: "Node.js version",
+    config: "Setup",
+    credential: "Credential store",
+    network: "Brightspace reachability",
+    session: "Saved sign-in",
+    courses: "Course list",
+    version: "Version",
+};
+const SKIPPED_SETUP = `finish setup first, then run doctor again: ${SETUP_COMMAND}`;
+const SKIPPED_SESSION = "fix the saved sign-in step above first, then run doctor again.";
+function skip(id, reason) {
+    return problem(id, `${CHECK_NAMES[id]}: Skipped — ${reason}`);
+}
+export async function runDoctorChecks(overrides = {}) {
+    const deps = { ...defaultDoctorDeps(), ...overrides };
+    const checks = [];
+    checks.push(checkNode(deps));
+    const config = checkConfig(deps);
+    checks.push(config.result);
+    if (!config.ok) {
+        checks.push(skip("credential", SKIPPED_SETUP));
+        checks.push(skip("network", SKIPPED_SETUP));
+        checks.push(skip("session", SKIPPED_SETUP));
+        checks.push(skip("courses", SKIPPED_SETUP));
+    }
+    else {
+        checks.push(await checkCredential(deps, config.baseUrl, config.username, config.envAccessToken, config.envSessionCookie));
+        checks.push(await checkNetwork(deps, config.baseUrl));
+        const session = await checkSession(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie);
+        checks.push(session.result);
+        if (session.ok) {
+            checks.push(await checkCourses(deps, config.baseUrl, config.sessionDir, config.envAccessToken, config.envSessionCookie));
+        }
+        else {
+            checks.push(skip("courses", SKIPPED_SESSION));
+        }
+    }
+    checks.push(await checkVersion(deps));
+    return { checks, allOk: checks.every((c) => c.ok) };
+}
+// ── CLI entry point ──────────────────────────────────────────────────
+async function main() {
+    const result = await runDoctorChecks();
+    console.log("");
+    console.log("Brightspace MCP Server — doctor");
+    console.log("");
+    for (const check of result.checks)
+        console.log(`  ${check.line}`);
+    console.log("");
+    console.log(result.allOk
+        ? "Everything looks good — open your AI app and ask a question."
+        : "Fix the ✗ items above, then run doctor again.");
+    console.log("");
+    process.exitCode = result.allOk ? 0 : 1;
+}
+// VITEST is set only by the test runner, which imports this module for the
+// functions above and must never run the real checks against this machine.
+if (!process.env.VITEST) {
+    main().catch((err) => {
+        console.error("doctor failed:", err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    });
+}

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);
@@ -37,6 +37,9 @@ if (subcommand === 'setup') {
 else if (subcommand === 'auth') {
     await import('./auth-cli.js');
 }
+else if (subcommand === 'doctor') {
+    await import('./doctor.js');
+}
 else {
     // ── MCP Server (default) ────────────────────────────────────────────
     // CRITICAL: Enable stdout guard IMMEDIATELY to prevent corruption of stdio transport
@@ -135,7 +138,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 +158,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/setup.js

@@ -15,7 +15,7 @@ import { fileURLToPath } from "node:url";
 import { configStoreExists, getConfigStorePath, loadConfigStore, } from "./utils/config-store.js";
 import { saveSecureConfig } from "./utils/secure-config.js";
 import { writeFileAtomicSync } from "./utils/atomic-write.js";
-import { AUTH_COMMAND } from "./utils/commands.js";
+import { AUTH_COMMAND, DOCTOR_COMMAND } from "./utils/commands.js";
 import { cliMcpClients, configureCliMcpClient, isCliAvailable, } from "./utils/mcp-client-cli.js";
 // ANSI helpers
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -387,11 +387,12 @@ async function main() {
         console.log("");
     }
     else {
+        console.log(dim("  Your school's Brightspace address — the web address you open to see your courses."));
         while (!baseUrl) {
-            const raw = await ask(rl, "What is your Brightspace URL? (e.g., purdue.brightspace.com): ");
+            const raw = await ask(rl, "What is your Brightspace address? (e.g., purdue.brightspace.com): ");
             const normalized = normalizeUrl(raw);
             if (!raw || !isValidUrl(normalized)) {
-                console.log(yellow("  Please enter a valid URL (e.g., purdue.brightspace.com)"));
+                console.log(yellow("  Please enter a valid address, like purdue.brightspace.com"));
                 continue;
             }
             baseUrl = normalized;
@@ -416,10 +417,13 @@ async function main() {
     // ── Step 2: Username ─────────────────────────────────────────────
     const usernamePrompt = preset
         ? `What is your ${preset.usernameLabel}? `
-        : "What is your Brightspace username? ";
+        : "What username do you use to sign in to Brightspace? ";
     if (preset?.usernameHint) {
         console.log(dim(`  ${preset.usernameHint}`));
     }
+    else {
+        console.log(dim("  The same username you type on your school's Brightspace sign-in page."));
+    }
     let username = "";
     while (!username) {
         username = await ask(rl, usernamePrompt);
@@ -431,6 +435,7 @@ async function main() {
     // ── Step 3: Password (hidden) ────────────────────────────────────
     // Close the rl temporarily since askPassword manages its own
     rl.close();
+    console.log(dim("  The password you use to sign in. It won't be shown as you type — asterisks stand in for each character."));
     const passwordPrompt = preset
         ? `What is your ${preset.name} password? `
         : "What is your Brightspace password? ";
@@ -449,20 +454,21 @@ async function main() {
     });
     const configuredClients = [];
     // ── Step 4: MFA info ─────────────────────────────────────────────
+    console.log(dim("  Your school may ask you to approve the sign-in a second way — on your phone, with a code, or something else."));
     if (preset) {
-        console.log(dim(`  MFA: ${preset.mfaNote}`));
+        console.log(dim(`  ${preset.mfaNote}`));
     }
     else {
-        console.log(dim("  MFA: You will be prompted to approve the sign-in on your phone during auth."));
+        console.log(dim("  You'll be prompted to approve the sign-in on your phone during auth."));
     }
     console.log("");
     // Only two outcomes exist: a hidden browser or a visible one. Which kind of
     // MFA you have is detected at sign-in time, so offering "approve a prompt"
     // and "type a code" as separate choices would be a distinction the code does
     // not make, and picking between them would change nothing on disk.
-    console.log("  How do you complete MFA?");
-    console.log("    1. On your phone, or by typing a code here (recommended)");
-    console.log("    2. In a visible browser window");
+    console.log("  When your school asks you to approve the sign-in, how will you do it?");
+    console.log("    1. I approve on my phone, or I type a code from an authenticator app (recommended)");
+    console.log("    2. Something else — open a browser window I can use");
     let savedHeadless;
     try {
         savedHeadless = configStoreExists() ? loadConfigStore().headless : undefined;
@@ -495,23 +501,23 @@ async function main() {
     console.log(green("  Config saved to: " + getConfigStorePath()));
     console.log("");
     // ── Step 6: Authenticate now? ────────────────────────────────────
-    const authNow = await ask(rl2, "Would you like to authenticate now? (yes/no): ");
+    const authNow = await ask(rl2, "Sign in now, so everything is ready to go? (yes/no): ");
     if (/^y(es)?$/i.test(authNow)) {
         rl2.close();
         console.log("");
-        console.log(dim("  Starting authentication..."));
+        console.log(dim("  Signing you in..."));
         console.log("");
         const ok = await runAuth();
         rl2 = readline.createInterface({ input: process.stdin, output: process.stdout });
         if (ok) {
-            console.log(green("\n  Authentication successful!"));
+            console.log(green("\n  Signed in!"));
         }
         else {
-            console.log(yellow(`\n  Authentication failed. You can retry later with: ${AUTH_COMMAND}`));
+            console.log(yellow(`\n  Sign-in didn't finish. You can try again later by running: ${AUTH_COMMAND}`));
         }
     }
     else {
-        console.log(dim(`  You can authenticate later by running: ${AUTH_COMMAND}`));
+        console.log(dim(`  You can sign in later by running: ${AUTH_COMMAND}`));
     }
     console.log("");
     // ── Step 7: Claude Desktop auto-config ───────────────────────────
@@ -590,14 +596,16 @@ async function main() {
     console.log("  Next steps:");
     if (configuredClients.length > 0) {
         console.log(`  1. Restart ${configuredClients.join(", ")}`);
-        console.log("  2. Ask your AI client about your Brightspace courses");
+        console.log(`  2. Ask it: "What's due this week?"`);
         console.log("     Sign-in runs automatically if your saved session has expired.");
     }
     else {
         console.log("  1. Register the MCP server in your AI client using the command in README.md");
-        console.log("  2. Restart your AI client and ask about your Brightspace courses");
+        console.log(`  2. Restart your AI client, then ask it: "What's due this week?"`);
     }
     console.log("");
+    console.log(dim(`  If something doesn't work, run: ${DOCTOR_COMMAND}`));
+    console.log("");
 }
 // Both entry points — the `brightspace-setup` bin and `brightspace-mcp-server
 // setup`, which imports this module — start the wizard here. VITEST is set

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/build/utils/commands.js

@@ -19,6 +19,8 @@ export const PACKAGE_NAME = "brightspace-mcp-server";
 export const AUTH_COMMAND = `npx -y ${PACKAGE_NAME}@latest auth`;
 /** Re-run the setup wizard. Always runs the current published release. */
 export const SETUP_COMMAND = `npx -y ${PACKAGE_NAME}@latest setup`;
+/** Diagnose a broken setup. Always runs the current published release. */
+export const DOCTOR_COMMAND = `npx -y ${PACKAGE_NAME}@latest doctor`;
 /** Bring a global install up to date. The only fix for a stale `npm i -g` copy. */
 export const GLOBAL_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}@latest`;
 /** Drop cached npx copies so the next `@latest` genuinely refetches. */

package/build/utils/config.js

@@ -211,7 +211,8 @@ export function parseSessionCookieEnv(raw) {
     }
     throw new Error(SESSION_COOKIE_FORMAT_ERROR);
 }
-function expandTilde(filePath) {
+/** Exported for the `doctor` CLI, which resolves the same session directory without loading the full app config. */
+export function expandTilde(filePath) {
     if (filePath.startsWith("~")) {
         return path.join(os.homedir(), filePath.slice(1));
     }

package/package.json

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