brightspace-d2l-mcp 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.4.1
+
+- Make expired-session errors actionable in src/api/errors.ts
+- Sync llms.txt and glama.json to the 17 tools and 9 prompts
+- Put a vs-competitors table on the README first screen
+- Add an example prompt to every tool description in src/index.ts
+- Rewrite the npm description to lead with 'Brightspace MCP server'
+- Update the MCP SDK to 1.32.1, playwright-core to 1.64.1, zod to 4.6.7 and unpdf to 1.9.1
+- Keep file-type on 21 and vitest on 4, because those releases need Node 22 and this server still runs on Node 20
+- Add release tests that keep package.json, server.json and the registry entry on one version, and that keep the build and test gate before publishing
+
+## 1.4.0
+
+- Update check. Running a command like `npx brightspace-d2l-mcp setup` on an older version now says which version is out and asks "Update now? (Y/n)". Yes switches to the new version and carries on with the same command. It never asks when an AI app runs the server, in CI, with `--yes`, or when `BRIGHTSPACE_NO_UPDATE_CHECK` is set.
+- Running `npx brightspace-d2l-mcp` with no command in a terminal now shows help instead of silently starting the server. AI apps are unaffected.
+
 ## 1.3.0
 
 - Setup closes its window when it finishes on Windows, after a 10 second countdown. Press Enter to close it straight away, type k to keep it open, or pass `--keep-open`. Every command now exits as soon as it is done, so the terminal is never left hanging.

package/README.md

@@ -12,11 +12,15 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9fb4ff?style=flat-square&labelColor=1b2033" alt="MIT license"></a>
 </p>
 
+<p align="center">
+  <a href="https://www.producthunt.com/products/brightspace-d2l-mcp-server?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-brightspace-d2l-mcp-server"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1279179&theme=neutral" alt="Brightspace D2L MCP Server on Product Hunt" width="250" height="54"></a>
+</p>
+
 <h3 align="center">Connect D2L Brightspace to Claude, ChatGPT, Cursor and Copilot.<br>It knows what you already handed in, so it only shows what is actually left.</h3>
 
 <p align="center">One command. Sign in the way you always do. No passwords stored.</p>
 
-<p align="center">By Nick, a networking student at Fleming College</p>
+<p align="center"><a href="https://brightspace-mcp.netlify.app"><b>brightspace-mcp.netlify.app</b></a></p>
 
 <br>
 
@@ -35,11 +39,30 @@ Then ask your AI:
 
 > **"What should I work on right now?"**
 
+<p align="center">
+  <img src="assets/demo.gif" alt="Asking an AI what to work on and getting a Brightspace to-do list that skips submitted work (sample data)" width="760">
+</p>
+
 <p align="center">
   <img src="assets/setup.svg" alt="The setup command finding the school, signing in, and connecting AI apps" width="760">
 </p>
 
 New to this? The **[step-by-step setup guide](docs/setup.md)** walks through everything with pictures of each step.
+Using a specific app? See the guides for **[Claude](https://brightspace-mcp.netlify.app/claude/)** and **[ChatGPT](https://brightspace-mcp.netlify.app/chatgpt/)**, or **[how this compares](https://brightspace-mcp.netlify.app/compare/)** to other Brightspace MCP servers.
+
+## How it compares
+
+People usually weigh a few Brightspace MCP servers before picking one. Here are the three differences that come up most, with the [full comparison](https://brightspace-mcp.netlify.app/compare/) for the rest:
+
+| Server | Submission status | Sign-in (SSO) | Target grade |
+|---|---|---|---|
+| **Brightspace MCP** (this repo, `brightspace-d2l-mcp`) | Every due date says whether you already handed the work in, and the to-do list skips what is done | Real browser window where you sign in yourself, so any SSO works: Microsoft, Duo, Okta, Shibboleth. No password stored | `get_grade_outlook` gives your current percentage, your best and worst possible final grade, and what you need on the remaining work to hit any target |
+| [brightspace-mcp-server](https://www.npmjs.com/package/brightspace-mcp-server) by RohanMuppa | Shown in its assignments tool | Automated sign-in that saves your password in Keychain or Credential Manager, with presets for nine schools | No target-grade tool in its published list |
+| [brightspace-mcp](https://www.npmjs.com/package/brightspace-mcp) by JhostinAleck | Lists the files you submitted | Configured automation: HTTP login, headless browser with a Microsoft preset, Duo push, or pasted cookies | `grade_audit` answers "what you need to pass" |
+| [@n35da/brightspace-mcp](https://www.npmjs.com/package/@n35da/brightspace-mcp) | Shown on each dropbox folder | Real browser window where you sign in with your school's SSO | No target-grade tool in its published list |
+| [@exhabition/brightspace-mcp](https://www.npmjs.com/package/@exhabition/brightspace-mcp) (Rust) | Has assignment and submission readers | Visible Chromium window, Microsoft SSO only | No target-grade tool in its published list |
+
+"No target-grade tool in its published list" means we could not find one in each project's public README and tool list as of October 2026, not that it can never be added. Spot a mistake in the table? Open an issue and it will be fixed.
 
 ## What you can ask
 
@@ -117,7 +140,7 @@ If your school uses D2L Brightspace, yes. Setup opens a normal browser window so
 
 | School | Status |
 |---|---|
-| Fleming College | Tested by the author |
+| One college | Tested by the author |
 | Any other D2L school | Should work. Open an issue with yours and I will add it here |
 
 ## Works with your AI app or agent
@@ -156,6 +179,8 @@ https://github.com/AnonymousOnyx22/brightspace-d2l-mcp/blob/main/llms.txt
 | `npx brightspace-d2l-mcp serve --http` | Run over HTTP for ChatGPT and HTTP-based agents |
 | `npx brightspace-d2l-mcp config` | Print the MCP config JSON for any other app |
 
+When a newer version is out, commands ask whether to update first. Set `BRIGHTSPACE_NO_UPDATE_CHECK=1` to turn that off.
+
 <details>
 <summary><b>Setup options</b></summary>
 

package/build/api/client.js

@@ -5,7 +5,6 @@ import { discoverVersions } from "./version-discovery.js";
 import { ApiError, RateLimitError, NetworkError } from "./errors.js";
 import { withRetry, isRetryableFailure, retryAfterMsFrom } from "./retry.js";
 import { log } from "../utils/logger.js";
-import { LOGIN_COMMAND } from "../utils/paths.js";
 import { packageVersion } from "../utils/version.js";
 function isExpiredSessionRedirect(body, baseUrl) {
     const expiredTarget = (target) => {
@@ -184,7 +183,9 @@ export class D2LApiClient {
             }
             log("WARN", "Auto-reauthentication did not produce a valid token");
         }
-        throw new ApiError(401, path, `Session expired. Please re-authenticate via ${LOGIN_COMMAND}.`);
+        // The 401 wording and the fix both live in errors.ts, so every dead-session
+        // error carries the same sign-in command.
+        throw new ApiError(401, path, "Brightspace rejected the saved session.");
     }
     async makeRequest(path, token) {
         const url = `${this.baseUrl}${path}`;
@@ -226,7 +227,7 @@ export class D2LApiClient {
                 // marker still parses, so it can never be misread as a dead session.
                 if (isExpiredSessionRedirect(responseBody, this.baseUrl)) {
                     log("DEBUG", "Response carried the session-expired stub, treating it as a 401");
-                    throw new ApiError(401, path, `Session expired. Please re-authenticate via ${LOGIN_COMMAND}.`);
+                    throw new ApiError(401, path, "Brightspace answered with its session-expired login page.");
                 }
                 throw new ApiError(response.status, path, `Expected JSON from ${path} but the body did not parse`);
             }
@@ -283,7 +284,7 @@ export class D2LApiClient {
                 const body = await response.text();
                 if (isExpiredSessionRedirect(body, this.baseUrl)) {
                     log("DEBUG", "File download answered with the session-expired stub, treating it as a 401");
-                    throw new ApiError(401, path, `Session expired. Please re-authenticate via ${LOGIN_COMMAND}.`);
+                    throw new ApiError(401, path, "Brightspace answered with its session-expired login page.");
                 }
                 // A legitimate HTML page: hand back an equivalent response with the
                 // body we already consumed.

package/build/api/errors.js

@@ -1,11 +1,24 @@
 import { AuthError } from "../utils/errors.js";
+import { SETUP_COMMAND } from "../utils/paths.js";
+// A dead Brightspace session must never reach the person as a bare 401. Every
+// 401 message carries the command that signs them in again, so the text stays
+// fixable wherever it shows up: a tool result mid-chat, a log line, or the CLI.
+export const SESSION_EXPIRED_HINT = `Your Brightspace session expired. Run \`${SETUP_COMMAND}\` again to sign in, then retry.`;
+// Appends the sign-in command to a 401. A caller that already named the command
+// keeps its own wording, so the hint is never repeated in one message.
+function withSessionHint(status, message) {
+    if (status !== 401 || message.includes(SETUP_COMMAND))
+        return message;
+    const detail = message.trim();
+    return detail ? `${detail} ${SESSION_EXPIRED_HINT}` : SESSION_EXPIRED_HINT;
+}
 // Base class for all HTTP API errors
 export class ApiError extends AuthError {
     status;
     endpoint;
     responseBody;
     constructor(status, endpoint, message, responseBody, cause) {
-        super(`[PBMCP-2001] API error (${status}) at ${endpoint}: ${message}`, cause);
+        super(`[PBMCP-2001] API error (${status}) at ${endpoint}: ${withSessionHint(status, message)}`, cause);
         this.status = status;
         this.endpoint = endpoint;
         this.responseBody = responseBody;

package/build/cli/update-check.js

@@ -0,0 +1,76 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { PACKAGE_NAME } from "../utils/paths.js";
+import { packageVersion } from "../utils/version.js";
+import { isNewerVersion } from "./doctor.js";
+import * as ui from "./ui.js";
+const CHECK_TIMEOUT_MS = 1500;
+/** Set on the relaunched process so it never asks again. */
+const RELAUNCHED_ENV = "BRIGHTSPACE_UPDATED";
+/** Commands that never prompt: the MCP server itself, and output meant for scripts. */
+const SKIP_COMMANDS = new Set(["serve", "config", "--version", "-v"]);
+export function shouldCheckForUpdate(command, args, env = process.env, tty = process.stdin.isTTY === true && process.stdout.isTTY === true) {
+    if (!tty || SKIP_COMMANDS.has(command))
+        return false;
+    if (args.includes("--yes") || args.includes("-y"))
+        return false;
+    return !env.CI && !env.BRIGHTSPACE_NO_UPDATE_CHECK && !env[RELAUNCHED_ENV];
+}
+async function latestVersion() {
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, { signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) });
+        if (!response.ok)
+            return null;
+        const { version } = (await response.json());
+        return typeof version === "string" ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function quoteForCmd(arg) {
+    return /[\s"&|<>^]/.test(arg) ? `"${arg.replace(/"/g, '\\"')}"` : arg;
+}
+function relaunch(version, command, args) {
+    const windows = process.platform === "win32";
+    const argv = ["-y", `${PACKAGE_NAME}@${version}`, command, ...args];
+    return new Promise((resolve) => {
+        const child = spawn("npx", windows ? argv.map(quoteForCmd) : argv, {
+            stdio: "inherit",
+            shell: windows,
+            // Run outside the current folder, so a project that itself depends on this package can't shadow the new version.
+            cwd: homedir(),
+            env: { ...process.env, [RELAUNCHED_ENV]: "1" },
+        });
+        child.on("error", () => resolve(-1));
+        child.on("exit", (code) => resolve(code ?? 1));
+    });
+}
+/**
+ * Before an interactive command, offers to switch to a newer release.
+ * Returns the exit code of the updated run, or null to carry on with this version.
+ */
+export async function offerUpdate(command, args) {
+    if (!shouldCheckForUpdate(command, args))
+        return null;
+    const current = packageVersion();
+    const latest = await latestVersion();
+    if (!latest || !isNewerVersion(latest, current))
+        return null;
+    console.log(`\n  ${ui.yellow("↑")} ${ui.bold(`brightspace-d2l-mcp v${latest}`)} is out ${ui.dim(`(you have v${current})`)}`);
+    if (!(await ui.confirm("Update now?"))) {
+        ui.info(ui.dim(`Skipped. Run npx -y ${PACKAGE_NAME}@latest ${command} any time to update.`));
+        return null;
+    }
+    ui.info(ui.dim(`Downloading v${latest}...`));
+    const code = await relaunch(latest, command, args);
+    if (code === -1) {
+        ui.warn(`Couldn't start the update. Carrying on with v${current}.`);
+        return null;
+    }
+    if (!process.argv[1]?.includes("_npx")) {
+        ui.info(ui.dim(`To update your installed copy too, run: npm install -g ${PACKAGE_NAME}@latest`));
+    }
+    return code;
+}
+//# sourceMappingURL=update-check.js.map

package/build/index.js

@@ -1,9 +1,12 @@
 #!/usr/bin/env node
 const CLI_COMMANDS = new Set(["setup", "login", "status", "doctor", "logout", "uninstall", "serve", "config", "help", "--help", "-h", "--version", "-v"]);
-const command = process.argv[2];
+// AI apps launch the server with piped stdio. A person typing the bare command in a terminal gets help instead of a silent server.
+const command = process.argv[2] ?? (process.stdin.isTTY ? "help" : undefined);
 if (command && CLI_COMMANDS.has(command)) {
     const { runCli } = await import("./cli/main.js");
-    const code = await runCli(command, process.argv.slice(3));
+    const { offerUpdate } = await import("./cli/update-check.js");
+    const args = process.argv.slice(3);
+    const code = (await offerUpdate(command, args)) ?? (await runCli(command, args));
     // Exit as soon as a command finishes. A browser or timer left behind would otherwise keep the terminal busy.
     // `serve` only returns once its stdio server is running, so it keeps the process alive.
     if (command === "serve")

package/build/tools/download-file.js

@@ -8,7 +8,7 @@ import path from "node:path";
 export function registerDownloadFile(server, apiClient) {
     server.registerTool("download_file", {
         title: "Download File",
-        description: "Download a file from course content or assignment submissions to a local directory. Use this when the user wants to download, save, or get a file from Brightspace course content or dropbox submissions. IMPORTANT: You MUST ask the user where they want to save the file before calling this tool. Never guess or assume a download directory. After identifying the file to download, suggest a clean readable filename to the user (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and ask if they'd like to rename it. Pass their preferred name as customFilename, or omit it to keep the original.",
+        description: "Download a file from course content or assignment submissions to a local directory. Use this when the user wants to download, save, or get a file from Brightspace course content or dropbox submissions. Example: \"Save the week 4 problem set PDF to my homework folder.\" IMPORTANT: You MUST ask the user where they want to save the file before calling this tool. Never guess or assume a download directory. After identifying the file to download, suggest a clean readable filename to the user (e.g., 'Lecture 7 - Memory Management.pdf' instead of 'L07_CS251_2026SP_v2.pdf') and ask if they'd like to rename it. Pass their preferred name as customFilename, or omit it to keep the original.",
         inputSchema: DownloadFileSchema,
     }, async (args) => {
         try {

package/build/tools/export-due-dates-calendar.js

@@ -13,7 +13,8 @@ export function registerExportDueDatesCalendar(server, apiClient, config) {
         title: "Export Due Dates To Calendar",
         description: "Builds an iCalendar (.ics) file of upcoming assignments and quizzes that opens in Google Calendar, Apple Calendar " +
             "and Outlook. Each event has a link back to Brightspace and a one day reminder. By default only unfinished work is " +
-            "included. Pass downloadPath (an absolute folder) to save the file, otherwise the calendar text is returned.",
+            "included. Pass downloadPath (an absolute folder) to save the file, otherwise the calendar text is returned. " +
+            "Example: \"Put my upcoming due dates in Google Calendar.\"",
         inputSchema: ExportDueDatesCalendarSchema,
         annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-announcements.js

@@ -38,7 +38,7 @@ export function mapNewsItem(item) {
 export function registerGetAnnouncements(server, apiClient, config) {
     server.registerTool("get_announcements", {
         title: "Get Announcements",
-        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said.",
+        description: "Fetch recent announcements from your courses. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, updates from instructors, recent posts, or what professors said. Example: \"Did my professors post anything new?\"",
         inputSchema: GetAnnouncementsSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-assignment-files.js

@@ -90,7 +90,7 @@ async function readAttachment(apiClient, courseId, folderId, attachment, extract
 export function registerGetAssignmentFiles(server, apiClient, baseUrl) {
     server.registerTool("get_assignment_files", {
         title: "Get Assignment Files",
-        description: "Read the files an instructor attached to an assignment: the spec or instructions PDF, a starter workbook, a rubric document. Call it with just courseId to see which assignments have attachments, then with folderId and fileId to read one. Use this when the user asks what an assignment requires, what the instructions say, or to summarize a handout. Returns the text itself. Use download_file instead when the user wants the file saved to disk.",
+        description: "Read the files an instructor attached to an assignment: the spec or instructions PDF, a starter workbook, a rubric document. Call it with just courseId to see which assignments have attachments, then with folderId and fileId to read one. Use this when the user asks what an assignment requires, what the instructions say, or to summarize a handout. Returns the text itself. Use download_file instead when the user wants the file saved to disk. Example: \"What does the lab report assignment ask for?\"",
         inputSchema: GetAssignmentFilesSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-assignments.js

@@ -279,7 +279,7 @@ function gradebookHeadsUp(raw, fetched, courseId, baseUrl) {
 export function registerGetAssignments(server, apiClient, config) {
     server.registerTool("get_assignments", {
         title: "Get Assignments",
-        description: "Fetch assignments and quizzes for a specific course or all enrolled courses. Shows dropbox submissions and quizzes with due dates, status, and rubric info. Use this when the user asks about assignments, homework, what to submit, quizzes, or assignment details and rubrics.",
+        description: "Fetch assignments and quizzes for a specific course or all enrolled courses. Shows dropbox submissions and quizzes with due dates, status, and rubric info. Use this when the user asks about assignments, homework, what to submit, quizzes, or assignment details and rubrics. Example: \"What assignments do I have in Calculus this week?\"",
         inputSchema: GetAssignmentsSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-calendar-events.js

@@ -37,7 +37,8 @@ export function registerGetCalendarEvents(server, apiClient, config) {
         title: "Get Calendar Events",
         description: "Events from the Brightspace course calendar: exams, tests, labs, classes, office hours and other dated events " +
             "that instructors post, plus due-date events. Use this when the user asks when an exam or test is, what is on their " +
-            "schedule, or what is happening on a day. For what work is left to hand in, use get_todo instead.",
+            "schedule, or what is happening on a day. For what work is left to hand in, use get_todo instead. " +
+            "Example: \"When is my final exam?\"",
         inputSchema: GetCalendarEventsSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-classlist-emails.js

@@ -9,7 +9,8 @@ export function registerGetClasslistEmails(server, apiClient) {
         description: "Fetch all email addresses for everyone in a course: instructors, TAs, and students. " +
             "Use this when the user wants a list of emails for a class, needs to email the whole class, " +
             "or wants contact info for everyone enrolled. Returns emails only, with no names or roles. " +
-            "For names, roles or finding a specific instructor or TA, use get_roster instead.",
+            "For names, roles or finding a specific instructor or TA, use get_roster instead. " +
+            "Example: \"Give me everyone's email in my Biology course.\"",
         inputSchema: GetClasslistEmailsSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

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

@@ -124,7 +124,7 @@ function countModules(tree) {
 export function registerGetCourseContent(server, apiClient) {
     server.registerTool("get_course_content", {
         title: "Get Course Content",
-        description: "Fetch the content tree for a course showing modules, topics, files, and links. Use this when the user asks about course materials, lecture slides, uploaded files, content structure, or what's in a course module. Use moduleTitle to filter to a specific module (e.g. 'Labs', 'Staff', 'Homeworks') instead of fetching the entire tree. Use maxDepth to limit recursion depth for a table-of-contents view.",
+        description: "Fetch the content tree for a course showing modules, topics, files, and links. Use this when the user asks about course materials, lecture slides, uploaded files, content structure, or what's in a course module. Use moduleTitle to filter to a specific module (e.g. 'Labs', 'Staff', 'Homeworks') instead of fetching the entire tree. Use maxDepth to limit recursion depth for a table-of-contents view. Example: \"Where are the lecture slides for week 4?\"",
         inputSchema: GetCourseContentSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-discussions.js

@@ -6,7 +6,7 @@ import { log } from "../utils/logger.js";
 export function registerGetDiscussions(server, apiClient) {
     server.registerTool("get_discussions", {
         title: "Get Discussions",
-        description: "Fetch discussion board content for a course including forums, topics, and posts. Use this when the user asks about discussion boards, forum posts, class discussions, or wants to see what's been posted. Provide just courseId to list all forums and their topics. Add forumId to get topics and posts for a specific forum. Add both forumId and topicId to get all posts in a specific discussion topic.",
+        description: "Fetch discussion board content for a course including forums, topics, and posts. Use this when the user asks about discussion boards, forum posts, class discussions, or wants to see what's been posted. Provide just courseId to list all forums and their topics. Add forumId to get topics and posts for a specific forum. Add both forumId and topicId to get all posts in a specific discussion topic. Example: \"What have people posted in this week's discussion board?\"",
         inputSchema: GetDiscussionsSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-grade-outlook.js

@@ -7,8 +7,9 @@ export function registerGetGradeOutlook(server, apiClient) {
         title: "Grade Outlook And Target Calculator",
         description: "Works out where the user stands in one course and what they need on the remaining work to reach a target grade. " +
             "Returns the current percentage, the best and worst possible final grade, and the average they must score on " +
-            "everything left to hit targetPercent. Use for \"what do I need on the final to get 80?\", \"can I still pass?\" " +
-            "or \"am I on track?\". For the raw grade items, use get_my_grades instead.",
+            "everything left to hit targetPercent. Use for \"can I still pass?\" or \"am I on track?\". " +
+            "For the raw grade items, use get_my_grades instead. " +
+            "Example: \"What do I need on the final to get an 80?\"",
         inputSchema: GetGradeOutlookSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-my-courses.js

@@ -7,7 +7,7 @@ import { applyCourseFilter } from "../utils/course-filter.js";
 export function registerGetMyCourses(server, apiClient, config) {
     server.registerTool("get_my_courses", {
         title: "Get My Courses",
-        description: "Fetch your enrolled Brightspace courses with names, codes, and IDs. Use this when the user asks about their courses, enrolled classes, what they're taking this semester, or needs a course ID for other queries.",
+        description: "Fetch your enrolled Brightspace courses with names, codes, and IDs. Use this when the user asks about their courses, enrolled classes, what they're taking this semester, or needs a course ID for other queries. Example: \"What courses am I taking this term?\"",
         inputSchema: GetMyCoursesSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-my-grades.js

@@ -6,7 +6,7 @@ import { applyCourseFilter } from "../utils/course-filter.js";
 export function registerGetMyGrades(server, apiClient, config) {
     server.registerTool("get_my_grades", {
         title: "Get My Grades",
-        description: "Fetch your grade breakdown for a specific course or all enrolled courses. Shows grade items with points, percentages, and comments. Use this when the user asks about grades, scores, marks, GPA, academic performance, or how they're doing in a class.",
+        description: "Fetch your grade breakdown for a specific course or all enrolled courses. Shows grade items with points, percentages, and comments. Use this when the user asks about grades, scores, marks, GPA, academic performance, or how they're doing in a class. Example: \"What's my current grade in Calculus?\"",
         inputSchema: GetMyGradesSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-roster.js

@@ -22,7 +22,7 @@ async function fetchClasslistUsers(apiClient, courseId, options) {
 export function registerGetRoster(server, apiClient) {
     server.registerTool("get_roster", {
         title: "Get Course Roster",
-        description: "Fetch the roster for a course including instructors, TAs, and optionally students with their names, emails, and roles. Use this when the user asks about classmates, instructor contact info, TA emails, professor names, or who's in a class. By default returns only instructors and TAs for privacy. Use includeStudents to get full class list. For just a plain list of email addresses to copy or email everyone, use get_classlist_emails instead.",
+        description: "Fetch the roster for a course including instructors, TAs, and optionally students with their names, emails, and roles. Use this when the user asks about classmates, instructor contact info, TA emails, professor names, or who's in a class. By default returns only instructors and TAs for privacy. Use includeStudents to get full class list. For just a plain list of email addresses to copy or email everyone, use get_classlist_emails instead. Example: \"Who's the TA for my Chemistry class and what's their email?\"",
         inputSchema: GetRosterSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-syllabus.js

@@ -11,7 +11,7 @@ import fs from "node:fs/promises";
 export function registerGetSyllabus(server, apiClient) {
     server.registerTool("get_syllabus", {
         title: "Get Course Syllabus",
-        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF). IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
+        description: "Fetch the syllabus/overview text and optional attachment for a course. Returns the course overview description as markdown. If downloadPath is provided, also downloads the syllabus attachment (e.g. PDF). Example: \"What's the grading breakdown in my Physics course?\" IMPORTANT: You MUST ask the user where they want to save the file before calling this tool with a downloadPath.",
         inputSchema: GetSyllabusSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-todo.js

@@ -43,7 +43,8 @@ export function registerGetTodo(server, apiClient, config) {
         description: "Prioritized to-do list across all courses: unfinished work due soon, recently overdue work, " +
             "work not open yet, items to double-check (quizzes), and work already submitted. " +
             "Use this first when the user asks what to work on, what's left, or what they should do now. " +
-            "For a plain chronological list of deadlines or a custom date range, use get_upcoming_due_dates instead.",
+            "For a plain chronological list of deadlines or a custom date range, use get_upcoming_due_dates instead. " +
+            "Example: \"What should I work on right now?\"",
         inputSchema: GetTodoSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-upcoming-due-dates.js

@@ -122,7 +122,8 @@ export function registerGetUpcomingDueDates(server, apiClient, config) {
         description: "Upcoming due dates across all courses, with whether each assignment is already submitted " +
             "(submissionStatus: submitted, graded, draft, not_submitted, not_open_yet, closed, past_due, restricted, unknown). " +
             "Dates are UTC ISO strings; convert to the user's local time. Use for deadlines, what's due and date ranges, " +
-            "in date order. For advice on what to do first, use get_todo instead.",
+            "in date order. For advice on what to do first, use get_todo instead. " +
+            "Example: \"What's due next week?\"",
         inputSchema: GetUpcomingDueDatesSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/get-whats-new.js

@@ -44,7 +44,8 @@ export function registerGetWhatsNew(server, apiClient, config) {
         title: "What's New",
         description: "One catch-up summary across all courses: new announcements, unread assignment feedback (newly marked work), " +
             "unread discussion posts and quizzes not attempted yet. Use this when the user asks what's new, what they missed, " +
-            "whether anything was graded or posted, or for a daily or weekly catch-up.",
+            "whether anything was graded or posted, or for a daily or weekly catch-up. " +
+            "Example: \"What did I miss in my courses this week?\"",
         inputSchema: GetWhatsNewSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

package/build/tools/tool-helpers.js

@@ -3,7 +3,7 @@ import { ApiError, RateLimitError, NetworkError } from "../api/index.js";
 import { TokenRefreshError } from "../api/errors.js";
 import { AuthRequiredError } from "../auth/authenticator.js";
 import { log } from "../utils/logger.js";
-import { LOGIN_COMMAND } from "../utils/paths.js";
+import { SETUP_COMMAND } from "../utils/paths.js";
 import { DownloadError, isSafeDetail, } from "../utils/download-errors.js";
 export function toolResponse(data) {
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
@@ -41,7 +41,7 @@ export function sanitizeError(error) {
             return errorResponse("Resource not found. The course or item may not exist, or you may not have access.");
         }
         if (error.status === 401) {
-            return errorResponse(`Your Brightspace session expired and signing in again did not finish. Run \`${LOGIN_COMMAND}\` in a terminal, then try again.`);
+            return errorResponse(`Your Brightspace session expired and signing in again did not finish. Run \`${SETUP_COMMAND}\` in a terminal, then try again.`);
         }
         if (error.status === 403) {
             return errorResponse("Access denied. You may not have permission to access this resource.");

package/llms.txt

@@ -1,6 +1,6 @@
 # Brightspace D2L MCP Server
 
-> MCP server that gives AI assistants and agents read access to D2L Brightspace. It returns due dates with real submission status, grades, assignments, rubrics, course content, announcements, discussions and class lists. It works at any school that uses D2L Brightspace, including schools with Microsoft, Duo, Okta or Shibboleth sign-in. It is read only and never stores a password.
+> MCP server that gives AI assistants and agents read access to D2L Brightspace. It returns due dates with real submission status, grades, assignments, rubrics, course content, announcements, discussions and class lists. It works at any school that uses D2L Brightspace, including schools with Microsoft, Duo, Okta or Shibboleth sign-in. It is read only and never stores a password. Current version: 1.4.1.
 
 ## Install
 
@@ -47,7 +47,7 @@ For any other app run npx brightspace-d2l-mcp config to print the MCP config JSO
 
 The server also offers MCP prompts: what_should_i_do_now, plan_my_week, weekly_digest, grade_target, exam_prep, summarize_assignment, put_deadlines_in_my_calendar, catch_me_up and when_are_my_exams.
 
-Submission status values are submitted, graded, not_submitted, draft, not_open_yet, closed, past_due and unknown. Items that are submitted or graded are done and should never be suggested as a to-do. Quizzes can show unknown because Brightspace does not show students their quiz attempts, so ask the user.
+Submission status values are submitted, graded, not_submitted, draft, not_open_yet, closed, past_due, restricted and unknown. Items that are submitted or graded are done and should never be suggested as a to-do. Quizzes can show unknown because Brightspace does not show students their quiz attempts, so ask the user.
 
 ## Other commands
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "brightspace-d2l-mcp",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "mcpName": "io.github.AnonymousOnyx22/brightspace-d2l-mcp",
-  "description": "MCP server for D2L Brightspace: connect Brightspace to Claude, ChatGPT, Cursor, Copilot and any AI agent. One-command setup at any school with normal browser sign-in (SSO, Duo, MFA). Due dates with real submission status, exam and calendar events, what's new catch-up, grades and target-grade calculator, calendar export, assignments, content, announcements.",
+  "description": "Brightspace MCP server for D2L: connect Brightspace to Claude, ChatGPT, Cursor, Copilot and any AI agent. One-command setup at any school with normal browser sign-in (SSO, Duo, MFA). Due dates with real submission status, exam and calendar events, what's new catch-up, grades and target-grade calculator, calendar export, assignments, content, announcements.",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -28,26 +28,26 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "file-type": "^21.3.0",
-    "playwright-core": "^1.63.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "file-type": "^21.3.4",
+    "playwright-core": "^1.64.1",
     "sanitize-filename": "^1.6.3",
     "turndown": "^7.2.2",
-    "unpdf": "^1.4.0",
-    "zod": "^4.0.0"
+    "unpdf": "^1.9.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^22.20.5",
     "@types/turndown": "^5.0.6",
-    "typescript": "^5.9.0",
-    "vitest": "^4.0.0"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
   },
   "engines": {
     "node": ">=20.0.0"
   },
   "license": "MIT",
   "author": "AnonymousOnyx22",
-  "homepage": "https://github.com/AnonymousOnyx22/brightspace-d2l-mcp#readme",
+  "homepage": "https://brightspace-mcp.netlify.app",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AnonymousOnyx22/brightspace-d2l-mcp.git"