brightspace-mcp-server 3.8.4 → 3.8.9

package/README.md

@@ -103,6 +103,8 @@ Claude Desktop uses a separate configuration, which the setup wizard can update
 
 </details>
 
+**Running from a source checkout or fork?** When a newer release is published, the server tells a source checkout to `git pull` and `npm run build` rather than to install the npm package. For a fork you maintain, set `D2L_NO_UPDATE_CHECK=1` in the server's environment to turn off upstream update notices.
+
 ## Session Expired?
 
 There's no login step — asking a question signs you in.

package/build/tools/get-assignments.js

@@ -6,7 +6,7 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllItems } from "../api/paginate.js";
 import { GetAssignmentsSchema } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable, authPendingNotice } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
@@ -66,6 +66,8 @@ async function recoverContentQuizzes(apiClient, courseId, toc, listedIds) {
             });
         }
         catch (error) {
+            if (isAuthUnavailable(error))
+                throw error;
             log("DEBUG", `Failed to fetch content-linked quiz ${quizId}: using content metadata`, error);
         }
         let detail = topic;
@@ -73,6 +75,8 @@ async function recoverContentQuizzes(apiClient, courseId, toc, listedIds) {
             detail = await apiClient.get(apiClient.le(courseId, `/content/topics/${topic.TopicId}`), { ttl: DEFAULT_CACHE_TTLS.courseContent });
         }
         catch (error) {
+            if (isAuthUnavailable(error))
+                throw error;
             log("DEBUG", `Failed to fetch content topic ${topic.TopicId}: using table-of-contents metadata`, error);
         }
         return {
@@ -109,6 +113,12 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
             ttl: DEFAULT_CACHE_TTLS.courseContent,
         }),
     ]);
+    // Each route may fail on its own without costing the others, but a failed
+    // sign-in means none of them answered: report that, not an empty course.
+    for (const result of [dropboxResult, quizResult, gradebookResult, contentResult]) {
+        if (result.status === "rejected" && isAuthUnavailable(result.reason))
+            throw result.reason;
+    }
     // Process Dropbox folders
     if (dropboxResult.status === "fulfilled") {
         // D2L dropbox endpoint may return paged { Objects: [...] } or flat array
@@ -125,6 +135,8 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 submissions = Array.isArray(submissionsRaw) ? submissionsRaw : submissionsRaw.Objects ?? [];
             }
             catch (error) {
+                if (isAuthUnavailable(error))
+                    throw error;
                 // 404 means no submissions yet - that's fine
                 if (error?.status !== 404) {
                     log("DEBUG", `Failed to fetch submissions for folder ${folder.Id}`, error);
@@ -136,6 +148,8 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 feedback = await apiClient.get(apiClient.le(courseId, `/dropbox/folders/${folder.Id}/feedback/myFeedback/`), { ttl: DEFAULT_CACHE_TTLS.assignments });
             }
             catch (error) {
+                if (isAuthUnavailable(error))
+                    throw error;
                 // 404/403 means no feedback available (or no access) - that's fine
                 if (error?.status !== 404 && error?.status !== 403) {
                     log("DEBUG", `Failed to fetch feedback for folder ${folder.Id}`, error);
@@ -229,6 +243,8 @@ export async function fetchCourseAssignments(apiClient, courseId, baseUrl) {
                 attempts = Array.isArray(attemptsRaw) ? attemptsRaw : attemptsRaw.Objects ?? [];
             }
             catch (error) {
+                if (isAuthUnavailable(error))
+                    throw error;
                 if (error?.status === 404) {
                     // 404 means no attempts yet, which is a measurement of zero
                     attempts = [];
@@ -353,9 +369,31 @@ export function registerGetAssignments(server, apiClient, config) {
             const { courseId } = GetAssignmentsSchema.parse(args);
             // Single course case
             if (courseId) {
-                const assignments = await fetchCourseAssignments(apiClient, courseId, config.baseUrl);
-                log("INFO", `get_assignments: Retrieved ${assignments.length} assignments for course ${courseId}`);
-                return toolResponse({ courseId, assignments });
+                try {
+                    const assignments = await fetchCourseAssignments(apiClient, courseId, config.baseUrl);
+                    log("INFO", `get_assignments: Retrieved ${assignments.length} assignments for course ${courseId}`);
+                    return toolResponse({ courseId, assignments });
+                }
+                catch (error) {
+                    // A pending sign-in is not an empty course: the routes never
+                    // answered, so the result says so instead of reporting zero
+                    // assignments as if that were a real measurement. The envelope
+                    // stays a success — existing callers that only read `assignments`
+                    // keep working — with authPending/notice added for callers that
+                    // want to tell "no assignments" apart from "couldn't check".
+                    if (isAuthUnavailable(error)) {
+                        log("DEBUG", `get_assignments: sign-in pending for course ${courseId}`, error);
+                        return toolResponse({
+                            courseId,
+                            assignments: [],
+                            authPending: true,
+                            notice: "Sign-in to Brightspace is still in progress, so assignments for this course " +
+                                `could not be fetched yet. ${authPendingNotice(error)} Call get_assignments again ` +
+                                "once sign-in finishes.",
+                        });
+                    }
+                    throw error;
+                }
             }
             // All courses case
             // First, fetch enrolled courses. isActive=true is the configured
@@ -391,15 +429,57 @@ export function registerGetAssignments(server, apiClient, config) {
                         log("DEBUG", `get_assignments: 403 Forbidden for course ${item.OrgUnit.Id} (${item.OrgUnit.Name}) - skipping`);
                         return null;
                     }
+                    // A pending sign-in only means this course's routes never
+                    // answered — it says nothing about the other courses, whose
+                    // requests may already have gone out independently. Mark this one
+                    // rather than failing the whole call and losing every course that
+                    // *did* answer.
+                    if (isAuthUnavailable(error)) {
+                        log("DEBUG", `get_assignments: sign-in pending for course ${item.OrgUnit.Id} (${item.OrgUnit.Name})`);
+                        return {
+                            courseId: item.OrgUnit.Id,
+                            courseName: item.OrgUnit.Name,
+                            authPending: true,
+                            authError: error,
+                        };
+                    }
                     throw error; // Re-throw other errors
                 }
             });
             const results = await Promise.allSettled(assignmentPromises);
-            const courses = results
+            const settled = results
                 .filter((r) => r.status === "fulfilled" && r.value !== null)
                 .map((r) => r.value);
-            log("INFO", `get_assignments: Retrieved assignments for ${courses.length} courses (out of ${enrollmentItems.length} enrolled)`);
-            return toolResponse({ courses });
+            const pending = settled.filter((c) => c.authPending);
+            const courses = settled
+                .filter((c) => !c.authPending)
+                .map(({ courseId, courseName, assignments }) => ({ courseId, courseName, assignments }));
+            log("INFO", `get_assignments: Retrieved assignments for ${courses.length} courses ` +
+                `(out of ${enrollmentItems.length} enrolled${pending.length > 0 ? `, ${pending.length} pending sign-in` : ""})`);
+            // Pending courses keep `assignments: []` so callers that read
+            // `courses[i].assignments` still get an array; authPending marks it
+            // as unchecked rather than empty.
+            const response = {
+                courses: [
+                    ...courses,
+                    ...pending.map(({ courseId, courseName }) => ({
+                        courseId,
+                        courseName,
+                        assignments: [],
+                        authPending: true,
+                    })),
+                ],
+            };
+            if (pending.length > 0) {
+                response.authPending = true;
+                response.unavailableCourseIds = pending.map((c) => c.courseId);
+                response.notice =
+                    "Sign-in to Brightspace is still in progress, so assignments for " +
+                        `${pending.length} course(s) (${pending.map((c) => c.courseId).join(", ")}) could not be ` +
+                        `fetched yet. ${authPendingNotice(pending[0].authError)} Call get_assignments again once ` +
+                        "sign-in finishes.";
+            }
+            return toolResponse(response);
         }
         catch (error) {
             // Temporary: log full error details to stderr for debugging

package/build/tools/tool-helpers.js

@@ -108,6 +108,40 @@ const DOWNLOAD_FAILURE_GUIDANCE = {
     pathTraversal: "The name Brightspace gave this file pointed outside the download " +
         "directory and was refused. Pass customFilename to choose one yourself.",
 };
+/**
+ * True when an error means the session itself is unusable, not that one
+ * resource refused: a sign-in that failed or is still waiting on MFA, a 401
+ * left over after re-authentication, or a token that could not be renewed.
+ * Tools that tolerate per-route failures must not tolerate these, or a pending
+ * sign-in reads as a successful empty result.
+ */
+export function isAuthUnavailable(error) {
+    return error instanceof AuthProcessError ||
+        error instanceof TokenRefreshError ||
+        (error instanceof ApiError && error.status === 401);
+}
+/**
+ * Guidance for a tool that returned a *successful* envelope anyway, because
+ * the sign-in blocking one or more of its routes is still being worked on in
+ * the background (see isAuthUnavailable). Reuses the same per-kind wording
+ * sanitizeError gives an AuthProcessError — including the dynamic MFA number,
+ * when one is known — so a caller sees identical instructions whether the
+ * tool reported isError or not; only the framing differs. Only call this once
+ * isAuthUnavailable(error) is true; it has no fallback for other errors.
+ */
+export function authPendingNotice(error) {
+    if (error instanceof AuthProcessError) {
+        return authFailureMessage(error);
+    }
+    if (error instanceof TokenRefreshError) {
+        return "Brightspace could not renew your session right now. Your saved login was kept. " +
+            "Try again in a few minutes.";
+    }
+    // The remaining isAuthUnavailable case: a 401 ApiError left over after
+    // automatic re-authentication was attempted and failed.
+    return "Authentication expired. Auto-reauthentication was attempted but failed. " +
+        `Please run \`${AUTH_COMMAND}\` in your terminal, then try again.`;
+}
 /**
  * Sanitize errors for user-friendly messages
  *

package/build/utils/update-checker.js

@@ -18,6 +18,10 @@
  * caller happens to read it first. A one-shot notice is invisible in practice:
  * it gets swallowed by a single background tool call and never seen again.
  *
+ * A source checkout gets different advice: installing the npm package would
+ * update some other copy, and for a fork it would mean leaving its changes
+ * behind. Such a checkout is told to pull and rebuild, or to opt out.
+ *
  * Set D2L_NO_UPDATE_CHECK to any value to switch the check off entirely.
  */
 import { readFileSync } from "node:fs";
@@ -54,8 +58,17 @@ export function ownNpxCacheDir(root = projectRoot) {
     const match = new RegExp(`^(.*/_npx/[^/]+)/node_modules/${PACKAGE_NAME}`).exec(normalized);
     return match ? resolve(match[1]) : null;
 }
-function isNpxCache() {
-    return ownNpxCacheDir() !== null;
+/**
+ * Classify the package directory this process runs from. npm only ever puts
+ * the package under a `node_modules` directory, so anything else is a checkout
+ * someone built by hand, possibly a fork.
+ */
+export function installKindOf(root = projectRoot) {
+    if (ownNpxCacheDir(root) !== null)
+        return "npx-cache";
+    return root.split(sep).join("/").split("/").includes("node_modules")
+        ? "npm-install"
+        : "source-checkout";
 }
 /**
  * Remove npx cache entries holding a copy of this package, so the next
@@ -155,7 +168,7 @@ export async function fetchLatestVersion(fetchImpl = fetch) {
  * swallowed, because a version check must not affect the server.
  */
 export async function initUpdateChecker(deps = {}) {
-    const { fetchImpl = fetch, env = process.env, installedVersion = getInstalledVersion(), runningFromNpxCache = isNpxCache(), clearCaches = () => clearAllNpxCaches(), } = deps;
+    const { fetchImpl = fetch, env = process.env, installedVersion = getInstalledVersion(), installKind = installKindOf(), clearCaches = () => clearAllNpxCaches(), } = deps;
     if (env.D2L_NO_UPDATE_CHECK)
         return;
     try {
@@ -168,7 +181,7 @@ export async function initUpdateChecker(deps = {}) {
         const to = safeVersionLabel(latest);
         const headline = `Update available: v${from} to v${to}.`;
         let text;
-        if (runningFromNpxCache) {
+        if (installKind === "npx-cache") {
             const count = await clearCaches();
             const cleanup = count > 0
                 ? `Cleared ${count} stale npx cache director${count === 1 ? "y" : "ies"} for ${PACKAGE_NAME} ` +
@@ -176,6 +189,11 @@ export async function initUpdateChecker(deps = {}) {
                 : "";
             text = `${headline} ${cleanup}Restart your MCP client to pick up v${to}.`;
         }
+        else if (installKind === "source-checkout") {
+            text = `${headline} This server runs from a source checkout, so update that checkout ` +
+                `(git pull, then npm run build) and restart your MCP client. ` +
+                `If it is a fork you maintain, set D2L_NO_UPDATE_CHECK=1 to turn off upstream update notices.`;
+        }
         else {
             text = `${headline} Run: ${GLOBAL_INSTALL_COMMAND}` +
                 `, then ${CLEAR_NPX_CACHE_COMMAND} and restart your MCP client.`;

package/package.json

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