brightspace-mcp-server 5.2.0 → 5.2.2

package/README.md

@@ -35,12 +35,11 @@ Works with Claude Desktop, Claude Code, Cursor, ChatGPT Desktop, Windsurf, and a
 **Rather have the AI install it?** Paste this into Claude Code, Cursor, Windsurf, Copilot, or Codex:
 
 ```
-Install brightspace-mcp-server for me by following
-https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
-(use --purdue at Purdue, --suny at SUNY, --tudelft at TU Delft, --cuny at CUNY, --leiden at Leiden, --mcgill at McGill, --mun at Memorial University, --ngeeann at Ngee Ann Polytechnic, or --javeriana at Javeriana Cali).
+Install the Brightspace MCP server for me. Follow the steps at
+https://raw.githubusercontent.com/RohanMuppa/brightspace-mcp-server/main/LLMs.md
 ```
 
-The AI does everything it can by itself, then gives you one terminal command. That command asks for your password and waits for you to approve the sign-in on your phone. That's the only part that needs you. Afterwards the AI checks that it can see your courses.
+The AI asks which school you attend and your username, does everything it can by itself, then gives you one terminal command. That command asks for your password and waits for you to approve the sign-in on your phone. That's the only part that needs you. Afterwards the AI checks that it can see your courses.
 
 Using a different AI app? Add the command `npx -y brightspace-mcp-server@latest` to its MCP settings (on Windows: `cmd /c npx -y brightspace-mcp-server@latest`). Codex and Claude Code commands, and general steps, are in [docs/troubleshooting.md](docs/troubleshooting.md).
 
@@ -81,7 +80,7 @@ School-specific quirks are in [docs/sign-in.md](docs/sign-in.md#per-school-notes
 | Calendar | "When is my midterm?" · "Is lab cancelled on Thursday?" |
 | Instructors and TAs | "Which students haven't submitted Lab 4 yet?" (students see "Instructor or TA access required" for these) |
 
-If Brightspace hides part of the data, such as a submission, quiz attempts, or part of the quiz list, the answer says "unknown" or "incomplete" rather than "missing" or "complete". Full tool reference: [LLMs.md](LLMs.md).
+If Brightspace hides part of the data, such as a submission, quiz attempts, or part of the quiz list, the answer says "unknown" or "incomplete" rather than "missing" or "complete". Full tool reference: [docs/reference/tools.md](docs/reference/tools.md).
 
 ## Download a whole course
 
@@ -106,7 +105,19 @@ Every file in the course's Content area is saved into folders named after its mo
 - Each run is capped at 300 files and 5 GB. The assistant's version also stops cleanly after 8 minutes. Ask it again to continue. Ctrl-C stops the CLI cleanly (exit 130) with no partial file left behind.
 - Exit codes: 0 when everything was done, 1 if a file failed or wasn't attempted (including a sign-in that expired partway; saved files are kept), 2 for a usage error. Links and embedded videos aren't files, so the result counts them separately rather than as missing downloads.
 
-**Some folders are refused.** Downloads can't go to your home folder itself, a drive root, a hidden (dot) folder such as `~/.ssh`, `~/Library` (except cloud-drive and iCloud folders), system folders such as `/etc` or `/System`, or on Windows `Windows`, `Program Files`, `ProgramData` and `AppData`. Anything else is fine, including `/tmp`, external drives and `~/Documents`. Choose a folder like `~/Documents/Brightspace`; the refusal names the rule. The same rule applies to `download_file`, `get_syllabus` and every other tool that saves to disk. The person running the server can allow a folder anyway with `D2L_DOWNLOAD_ROOTS` (see [Settings](#settings-you-might-want)). Full rules: [LLMs.md](LLMs.md).
+**Some folders are refused.** Downloads can't go to your home folder itself, a drive root, a hidden (dot) folder such as `~/.ssh`, `~/Library` (except cloud-drive and iCloud folders), system folders such as `/etc` or `/System`, or on Windows `Windows`, `Program Files`, `ProgramData` and `AppData`. Anything else is fine, including `/tmp`, external drives and `~/Documents`. Choose a folder like `~/Documents/Brightspace`; the refusal names the rule. The same rule applies to `download_file`, `get_syllabus` and every other tool that saves to disk. The person running the server can allow a folder anyway with `D2L_DOWNLOAD_ROOTS` (see [Settings](#settings-you-might-want)). Full rules: [docs/internals/downloads.md](docs/internals/downloads.md).
+
+## Tools
+
+Every tool the server registers. Each tool's arguments and response fields are in [docs/reference/tools.md](docs/reference/tools.md).
+
+- **Courses and grades:** `get_my_courses`, `get_my_grades`, `get_upcoming_due_dates`, `get_calendar_events`
+- **Assignments and rubrics:** `get_assignments`, `get_assignment_rubric`, `get_assignment_files`, `get_rubrics_for_object`
+- **Announcements and discussions:** `get_announcements`, `get_announcement_files`, `get_discussions`
+- **Course content:** `get_course_content`, `search_course`, `get_syllabus`, `get_video_transcript`, `download_file`, `download_course_files`
+- **People and groups:** `get_roster`, `get_classlist_emails`, `get_my_groups`, `get_available_groups`
+- **Dropbox (instructors and TAs):** `get_dropbox_folders`, `get_dropbox_submissions`, `get_dropbox_user_submissions`, `get_dropbox_feedback`, `download_dropbox_submission_file`
+- **Account and sign-in:** `sign_in`, `sign_out`, `get_server_info`
 
 ## Prompts
 
@@ -137,9 +148,11 @@ How often your school asks for two-factor is up to the school, not this tool.
 
 Duo, authenticator codes, visible-browser mode, and running without a browser at all (Docker, WSL, hardware keys) are covered in [docs/sign-in.md](docs/sign-in.md).
 
+**What a sign-in message means,** including Microsoft's "having trouble verifying your account" hold and what to do about each one, is in [docs/troubleshooting.md](docs/troubleshooting.md#what-each-sign-in-message-means). Numbers that expire, and signing in on more than one computer, are in [docs/sign-in.md](docs/sign-in.md#when-a-number-expires).
+
 ## Settings you might want
 
-All optional. Set them in your AI app's MCP `env` config or in your shell. The full list is in [LLMs.md](LLMs.md#environment-variables).
+All optional. Set them in your AI app's MCP `env` config or in your shell. The full list is in [docs/reference/settings.md](docs/reference/settings.md).
 
 | Setting | What it does |
 |---------|--------------|
@@ -177,7 +190,9 @@ Your password is stored in your computer's password store, never in a plaintext
 
 ## For developers
 
-Tool reference, response fields, environment variables and the codebase map: [LLMs.md](LLMs.md). What's safe to build against: [STABILITY.md](STABILITY.md).
+- **Changing the code:** start with [AGENTS.md](AGENTS.md). It says which doc to read before touching each area.
+- **Exact behaviour:** [tools](docs/reference/tools.md), [commands](docs/reference/cli.md) and [settings](docs/reference/settings.md).
+- **What's safe to build against:** [STABILITY.md](STABILITY.md). **What changed:** [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

package/build/index.js

@@ -142,7 +142,7 @@ else {
             const { resolveHttpPort, resolveHttpToken, startHttpServer } = await import("./http-server.js");
             const running = await startHttpServer({ runtime, token: resolveHttpToken(), port: resolveHttpPort() });
             stopServing = running.close;
-            log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (29 tools, 4 prompts registered)`);
+            log("INFO", `Brightspace MCP Server by Rohan Muppa — shared HTTP server listening on ${running.url} (tools and prompts registered)`);
             log("INFO", "Leave this running; every MCP client on this computer connects to that URL. Press Ctrl+C to stop.");
         }
         catch (error) {

package/build/server.js

@@ -104,7 +104,7 @@ export function createMcpServer(runtime) {
     registerGetDropboxFeedback(server, apiClient);
     registerGetRubricsForObject(server, apiClient);
     registerDownloadDropboxSubmissionFile(server, apiClient);
-    log("DEBUG", "MCP tools registered (29 tools)");
+    log("DEBUG", "MCP tools registered");
     // 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

package/build/tools/get-course-content.js

@@ -170,7 +170,9 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
             if (typeFilter !== 'all' && !matchesTypeFilter(item, typeFilter)) {
                 continue;
             }
-            const topicProgress = progressMap.get(item.Id);
+            // A null map means progress couldn't be read: completion is unknown,
+            // not false, so a failed read can't pass for "nothing completed".
+            const topicProgress = progressMap?.get(item.Id);
             const topic = {
                 type: 'topic',
                 topicType,
@@ -181,7 +183,7 @@ export async function buildContentTree(apiClient, courseId, modules, progressMap
                 ...availabilityFields(availability),
                 ...(item.DueDate ? { dueDate: item.DueDate } : {}),
                 lastModified: item.LastModifiedDate ?? null,
-                isCompleted: topicProgress?.IsRead ?? false,
+                isCompleted: progressMap === null ? null : topicProgress?.IsRead ?? false,
                 ...(topicProgress?.DateCompleted ? { completedDate: topicProgress.DateCompleted } : {}),
             };
             // Add type-specific content
@@ -307,22 +309,25 @@ export function registerGetCourseContent(server, apiClient) {
                 const searchTerm = moduleTitle.toLowerCase();
                 rootModules = rootModules.filter(m => m.Title.toLowerCase().includes(searchTerm));
             }
-            // Fetch user progress for the course (graceful degradation)
-            let progressArray = [];
+            // Fetch user progress for the course (graceful degradation). 403/404
+            // means this course has no progress data for the user. Any other
+            // failure leaves completion unknown, so the map stays null and every
+            // topic reports isCompleted: null rather than false.
+            let progressMap = new Map();
             try {
-                progressArray = await apiClient.get(apiClient.le(courseId, '/content/userprogress/'), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+                const progressArray = await apiClient.get(apiClient.le(courseId, '/content/userprogress/'), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+                for (const p of Array.isArray(progressArray) ? progressArray : []) {
+                    progressMap.set(p.ContentObjectId, p);
+                }
             }
             catch (error) {
-                // 404/403 means no progress data available - not an error
+                if (isAuthUnavailable(error))
+                    throw error;
                 if (error?.status !== 404 && error?.status !== 403) {
                     log('DEBUG', `Failed to fetch progress for course ${courseId}`, error);
+                    progressMap = null;
                 }
             }
-            // Build progress map for O(1) lookups
-            const progressMap = new Map();
-            for (const p of progressArray) {
-                progressMap.set(p.ContentObjectId, p);
-            }
             // Recursively build content tree
             let contentTree = await buildContentTree(apiClient, courseId, rootModules, progressMap, typeFilter, maxDepth);
             // Apply modifiedSince filter, if requested, after the tree is built:
@@ -346,6 +351,12 @@ export function registerGetCourseContent(server, apiClient) {
                 topicCount,
                 moduleCount,
                 ...(modifiedSince ? { modifiedSince, returned: topicCount, filteredOut } : {}),
+                ...(progressMap === null
+                    ? {
+                        progressUnavailable: "Couldn't read this user's completion progress, so every topic has isCompleted null. " +
+                            "Do not report topics as not completed; try again later.",
+                    }
+                    : {}),
                 ...(unreadable > 0
                     ? {
                         notice: `The contents of ${unreadable} module(s) couldn't be read; they have children null and a ` +

package/package.json

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