brightspace-mcp-server 5.1.21 → 5.1.22

package/build/auth/token-manager.js

@@ -262,6 +262,9 @@ export class TokenManager {
                 capturedAt: now,
                 expiresAt: now + FAR_FUTURE_MS,
                 source: "env",
+                // The token answers API calls; web pages such as course files only
+                // accept the session cookie, so keep it when both were pasted.
+                ...(this.envSessionCookie ? { cookieHeader: this.envSessionCookie } : {}),
             };
         }
         return {

package/build/doctor.js

@@ -28,7 +28,8 @@ import { describeShortcuts } from "./utils/two-factor-shortcuts.js";
 import { discoverVersions } from "./api/version-discovery.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, prepareCommand, signInCommand, } from "./utils/commands.js";
+import { SETUP_COMMAND, AUTH_COMMAND, GLOBAL_INSTALL_COMMAND, CLEAR_NPX_CACHE_COMMAND, prepareCommand, signInCommand, envCredentialRejectedMessage, } from "./utils/commands.js";
+import { ApiError } from "./api/errors.js";
 import { chromiumReady, chromiumStatus, dependencyRepairHint, BROWSER_REPAIR_COMMAND } from "./utils/browser-install.js";
 import { nodeVersionSupported, readOnlyTokenManager, readSavedSessionToken, sessionDirFor } from "./utils/saved-session.js";
 // Tests import this from doctor.ts.
@@ -236,6 +237,11 @@ async function checkSession(deps, baseUrl, sessionDir, envAccessToken, envSessio
         : `Not signed in yet — run this in a terminal: ${signInCommand(baseUrl)}`;
     try {
         const token = await deps.getSessionToken(baseUrl, sessionDir, envAccessToken, envSessionCookie);
+        // A pasted credential is used as given, so nothing was issued here: the
+        // course check below is what shows whether Brightspace accepts it.
+        const pasted = envAccessToken ? "D2L_ACCESS_TOKEN" : envSessionCookie ? "D2L_SESSION_COOKIE" : undefined;
+        if (token && pasted)
+            return { ok: true, result: pass("session", `Using the credential in ${pasted}; the course check below shows whether Brightspace accepts it`) };
         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) };
@@ -262,6 +268,14 @@ async function checkCourses(deps, baseUrl, sessionDir, envAccessToken, envSessio
         return pass("courses", `Found ${label} course${count === 1 ? "" : "s"} on Brightspace`);
     }
     catch (error) {
+        const rejected = error instanceof ApiError && error.status === 401
+            ? envCredentialRejectedMessage(envAccessToken, envSessionCookie)
+            : undefined;
+        if (rejected)
+            return problem("courses", `Brightspace refused the course list. ${rejected}`);
+        if (error instanceof ApiError && error.status === 401) {
+            return problem("courses", `Brightspace refused the saved sign-in when loading your courses — sign in again: ${AUTH_COMMAND}`);
+        }
         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.`);
     }

package/build/server.js

@@ -8,7 +8,8 @@ import { TokenManager, AuthRunner } from "./auth/index.js";
 import { D2LApiClient } from "./api/index.js";
 import { trackToolActivity } from "./utils/dev-activity.js";
 import { log } from "./utils/logger.js";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
+import { envCredentialRejectedMessage, ENV_COOKIE_REJECTED } from "./utils/commands.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, COURSE_FILE_NEEDS_COOKIE, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, registerSignOut, registerGetDropboxFolders, registerGetDropboxSubmissions, registerGetDropboxUserSubmissions, registerGetDropboxFeedback, registerGetRubricsForObject, registerDownloadDropboxSubmissionFile, acceptOmittedArguments, relayMfaChallenges, currentMfaAnnouncer, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 /**
  * Build the shared runtime. Nothing here reaches Brightspace: API versions
@@ -48,11 +49,7 @@ export function createRuntime(config, version) {
         baseUrl: config.baseUrl,
         tokenManager,
         onAuthExpired: authRunner ? () => authRunner.run(currentMfaAnnouncer()) : undefined,
-        authExpiredMessage: config.envAccessToken
-            ? "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set."
-            : config.envSessionCookie
-                ? "The pasted D2L_SESSION_COOKIE has expired. Copy a fresh d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser and update the environment variable; this server does not fall back to a browser login while D2L_SESSION_COOKIE is set."
-                : undefined,
+        authExpiredMessage: envCredentialRejectedMessage(config.envAccessToken, config.envSessionCookie),
     });
     return { config, version, tokenManager, apiClient, authRunner };
 }
@@ -87,7 +84,7 @@ export function createMcpServer(runtime) {
     registerGetAssignmentFiles(server, apiClient, config.baseUrl);
     registerGetAnnouncementFiles(server, apiClient);
     registerGetCourseContent(server, apiClient);
-    registerDownloadFile(server, apiClient);
+    registerDownloadFile(server, apiClient, config.envSessionCookie ? ENV_COOKIE_REJECTED : config.envAccessToken ? COURSE_FILE_NEEDS_COOKIE : undefined);
     registerGetClasslistEmails(server, apiClient);
     registerGetRoster(server, apiClient);
     registerGetMyGroups(server, apiClient);

package/build/tools/download-file.js

@@ -261,10 +261,21 @@ function extensionNote(requestedFilename, saved) {
             `not the format the requested name implied. Open it with an application that reads ${savedExt} files.`,
     };
 }
+/**
+ * Course files need a Brightspace web session, which D2L_ACCESS_TOKEN alone
+ * does not carry, and signing in again would not give it one.
+ */
+export const COURSE_FILE_NEEDS_COOKIE = "Course files are served only to a signed-in Brightspace web session, and D2L_ACCESS_TOKEN alone carries none. Set D2L_SESSION_COOKIE as well (a d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser) and restart the server.";
 /**
  * Register download_file tool
  */
-export function registerDownloadFile(server, apiClient) {
+export function registerDownloadFile(server, apiClient, 
+/**
+ * The fix to show when the session cookie a course file needs is missing
+ * or refused, set when the server runs on a pasted credential: there is no
+ * browser sign-in behind it, so signing in again would not help.
+ */
+cookieRejectedMessage) {
     server.registerTool("download_file", {
         title: "Download File",
         description: "Download a file from course content, files linked by path inside a module description (coursePath, from get_course_content's quickLink URLs with type=coursefile), instructor assignment attachments (source: assignmentAttachment with folderId + fileId), assignment submissions, or an announcement's attachments. Use this when the user wants a file from Brightspace course content, dropbox submissions, or an announcement (newsId + fileId, from get_announcements). Two response modes: (1) INLINE (default — omit downloadPath): the file comes back directly in the tool response — extracted text for PDFs and Office documents, an image block for jpeg/png/gif/webp, or a short description for anything else — so it can be read immediately without touching any filesystem. This is the right choice in clients like Claude Desktop, whose analysis/sandbox tools cannot see a file the MCP server writes to its own host filesystem. (2) DISK (set downloadPath to an absolute path on the HOST filesystem the MCP server runs on): the file is saved there. The directory must already exist; it is not created for you. Ask the user where to save it before using disk mode — never guess a directory. After identifying the file, suggest a clean readable filename (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and pass it as customFilename, or omit it to keep the original. If a content-topic download fails because the file isn't released yet, the response explains why when Brightspace's module/topic metadata supports it (not yet open, ended, locked, or hidden).",
@@ -309,7 +320,7 @@ export function registerDownloadFile(server, apiClient) {
                 const filePath = parseCoursePath(coursePath, courseId, apiClient.origin);
                 if (typeof filePath !== "string")
                     return errorResponse(filePath.error, "invalidInput");
-                return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename);
+                return await downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename, cookieRejectedMessage);
             }
             else if (topicId !== undefined) {
                 // Content file download
@@ -343,10 +354,12 @@ export function registerDownloadFile(server, apiClient) {
  * topics, so they have no topicId. Brightspace serves them to the signed-in
  * web session, not to the API token, so this goes through the session cookie.
  */
-async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename) {
+async function downloadCourseFile(apiClient, courseId, filePath, downloadPath, customFilename, cookieRejectedMessage) {
     log("INFO", `Downloading course file: courseId=${courseId}, path=${filePath}`);
     const response = await apiClient.getPageRaw(`${QUICKLINK_PATH}?ou=${courseId}&type=coursefile&fileId=${encodeURIComponent(filePath)}`);
     if (!response) {
+        if (cookieRejectedMessage)
+            return errorResponse(cookieRejectedMessage, "auth");
         return errorResponse(`Course files are served only to a signed-in Brightspace web session, and there is no valid one: the session cookie is missing or has expired. Sign in again with \`${AUTH_COMMAND}\` and retry. A server that runs on D2L_ACCESS_TOKEN alone has no cookie: set D2L_SESSION_COOKIE as well, or sign in through the browser.`, "auth");
     }
     // A missing file or a refused one can come back as an ordinary Brightspace

package/build/tools/get-syllabus.js

@@ -5,7 +5,7 @@
  */
 import { ApiError, DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { GetSyllabusSchema } from "./schemas.js";
-import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, errorResponse, isAuthUnavailable } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { stripD2lSessionParams } from "../utils/session-params.js";
 import { secureDownload, readBodyCapped } from "../utils/download-helpers.js";
@@ -61,9 +61,13 @@ async function tryLookup(lookup, fetch) {
         return { ok: true, value: await fetch() };
     }
     catch (error) {
+        // A pending or refused sign-in is not a permission the student lacks:
+        // the lookup never ran, so the call fails with the sign-in's answer.
+        if (isAuthUnavailable(error))
+            throw error;
         log("DEBUG", `get_syllabus: could not read ${LOOKUP_LABELS[lookup]}`, error);
         if (error instanceof ApiError) {
-            const forbidden = error.status === 401 || error.status === 403;
+            const forbidden = error.status === 403;
             return {
                 ok: false,
                 unavailable: { lookup, reason: forbidden ? "permission-denied" : "request-failed", status: error.status },

package/build/tools/index.js

@@ -14,7 +14,7 @@ export { registerGetAssignmentRubric } from "./get-assignment-rubric.js";
 export { registerGetAssignmentFiles } from "./get-assignment-files.js";
 export { registerGetAnnouncementFiles } from "./get-announcement-files.js";
 export { registerGetCourseContent } from "./get-course-content.js";
-export { registerDownloadFile } from "./download-file.js";
+export { registerDownloadFile, COURSE_FILE_NEEDS_COOKIE } from "./download-file.js";
 export { registerGetClasslistEmails } from "./get-classlist-emails.js";
 export { registerGetRoster } from "./get-roster.js";
 export { registerGetMyGroups } from "./get-my-groups.js";

package/build/tools/search-course.js

@@ -5,7 +5,7 @@
  */
 import { ApiError } from "../api/index.js";
 import { SearchCourseSchema } from "./schemas.js";
-import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { toolResponse, sanitizeError, isAuthUnavailable } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
 import { fetchRootContent, buildContentTree } from "./get-course-content.js";
 import { fetchCourseNews, isPublishedNewsItem, mapNewsItem } from "./get-announcements.js";
@@ -188,6 +188,10 @@ export function registerSearchCourse(server, apiClient) {
                 entries.push(...flattenContentTree(tree));
             }
             catch (error) {
+                // A pending or refused sign-in is not a source that failed: the
+                // search never ran, and its answer carries what the user must do.
+                if (isAuthUnavailable(error))
+                    throw error;
                 log("DEBUG", `search_course: content fetch failed for course ${courseId}`, error);
                 notes.push(`content: ${describeFailure(error)}`);
             }
@@ -205,6 +209,10 @@ export function registerSearchCourse(server, apiClient) {
                 }
             }
             catch (error) {
+                // A pending or refused sign-in is not a source that failed: the
+                // search never ran, and its answer carries what the user must do.
+                if (isAuthUnavailable(error))
+                    throw error;
                 log("DEBUG", `search_course: announcements fetch failed for course ${courseId}`, error);
                 notes.push(`announcements: ${describeFailure(error)}`);
             }
@@ -234,12 +242,16 @@ export function registerSearchCourse(server, apiClient) {
                         // One forum's topics failing (e.g. no access) shouldn't drop
                         // every other forum, but it still has to be named in `note` so
                         // a search missing those topics never reads as complete.
+                        if (isAuthUnavailable(error))
+                            throw error;
                         log("DEBUG", `search_course: topics fetch failed for forum ${forum.ForumId}`, error);
                         notes.push(`discussions: topics in "${forum.Name}" ${describeFailure(error)}`);
                     }
                 }
             }
             catch (error) {
+                if (isAuthUnavailable(error))
+                    throw error;
                 log("DEBUG", `search_course: discussions fetch failed for course ${courseId}`, error);
                 notes.push(`discussions: ${describeFailure(error)}`);
             }

package/build/utils/commands.js

@@ -28,6 +28,21 @@ export const DOCTOR_COMMAND = `npx -y ${PACKAGE_NAME}@latest doctor`;
 export const GLOBAL_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}@latest`;
 /** Drop cached npx copies so the next `@latest` genuinely refetches. */
 export const CLEAR_NPX_CACHE_COMMAND = "npx clear-npx-cache";
+/** What to do when Brightspace rejects a pasted D2L_ACCESS_TOKEN. */
+export const ENV_TOKEN_REJECTED = "D2L_ACCESS_TOKEN was rejected by Brightspace (expired or invalid). Issue a fresh token and update the environment variable; this server does not fall back to a browser login while D2L_ACCESS_TOKEN is set.";
+/** What to do when Brightspace rejects a pasted D2L_SESSION_COOKIE. */
+export const ENV_COOKIE_REJECTED = "The pasted D2L_SESSION_COOKIE has expired. Copy a fresh d2lSessionVal/d2lSecureSessionVal pair from a logged-in browser and update the environment variable; this server does not fall back to a browser login while D2L_SESSION_COOKIE is set.";
+/**
+ * The fix for a rejected credential pasted into the environment, or undefined
+ * when neither is set. D2L_ACCESS_TOKEN wins, as it does for signing in.
+ */
+export function envCredentialRejectedMessage(envAccessToken, envSessionCookie) {
+    if (envAccessToken)
+        return ENV_TOKEN_REJECTED;
+    if (envSessionCookie)
+        return ENV_COOKIE_REJECTED;
+    return undefined;
+}
 /**
  * The school's flag for a setup command, or `--url <origin>` for a school
  * with no preset. An unreadable URL gives no school at all, which `setup`

package/package.json

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