brightspace-d2l-mcp 1.4.2 → 1.4.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.4.4
+
+- Make a stale course id actionable: the error now says to call `get_my_courses` to list valid course IDs, and a course tool that finds no enrollments at all points at running `npx brightspace-d2l-mcp setup` again
+
+## 1.4.3
+
+- Add README section on switching from brightspace-mcp-server
+- Add docs/troubleshooting.md for connection, browser and sign in failures, linked from the README and llms.txt
+
 ## 1.4.2
 
 - Bump dependencies and assert version sync in release tests

package/README.md

@@ -64,6 +64,52 @@ People usually weigh a few Brightspace MCP servers before picking one. Here are
 
 "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.
 
+## Switching from brightspace-mcp-server
+
+If you are running [brightspace-mcp-server](https://www.npmjs.com/package/brightspace-mcp-server) by RohanMuppa and want to try this one, you only change the package name. Everything else stays where it is.
+
+In your MCP config, find the `brightspace` entry inside `mcpServers` and swap the command:
+
+```json
+{
+  "mcpServers": {
+    "brightspace": {
+      "command": "npx",
+      "args": ["-y", "brightspace-d2l-mcp@latest"]
+    }
+  }
+}
+```
+
+On Windows, wrap the launch in `cmd /c` the same way you do now:
+
+```json
+{
+  "mcpServers": {
+    "brightspace": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "brightspace-d2l-mcp@latest"]
+    }
+  }
+}
+```
+
+Then restart the app. If you would rather not edit files, run `npx brightspace-d2l-mcp setup`: it asks for your school, opens a browser window so you sign in, and writes this entry for you. You can also print the exact JSON for any app with `npx brightspace-d2l-mcp config`.
+
+### What carries over and what doesn't
+
+| | Status |
+|---|---|
+| The `brightspace` server name in `mcpServers` | Same here, so a config entry and any saved prompt that points at the `brightspace` server still lines up |
+| Tool names | They differ. See which tools this one has in the [Tools](#tools) table above and ask your AI for those names instead |
+| Your Brightspace account and courses | Nothing to move. This server signs in as you and sees the courses you are enrolled in, same as before |
+| A `D2L_INCLUDE_COURSES` or `D2L_EXCLUDE_COURSES` setting | Both names are read here too, so a course filter in your env block keeps working. `D2L_ACTIVE_ONLY` behaves the same way and is read here as well |
+| Whatever the first server saved on your computer | It is left alone. This server stores its own settings and session in `~/.brightspace-d2l-mcp/`, so nothing there changes unless you remove it yourself |
+
+Want to go back? Put the old command back in the same spot. Both servers can even be configured side by side under two different server names, but one AI app talking to two Brightspace servers at once tends to be more confusing than it is worth.
+
+A few things the first server does are not done here: it can sign you in without a browser window by saving your password in your computer's credential store, and it ships presets for several named schools. This server always opens a normal browser window where you sign in yourself, which is what makes any single sign-on work, and all it keeps afterward is your browser session.
+
 ## What you can ask
 
 | | Try asking |
@@ -205,6 +251,8 @@ App ids: `claude-desktop`, `claude-code`, `cursor`, `vscode`, `windsurf`, `codex
 
 ## Troubleshooting
 
+Something not working? **[docs/troubleshooting.md](docs/troubleshooting.md)** walks through an app that shows no Brightspace tools, a setup window that never opens, and a single sign on that keeps failing, with the exact message each one prints. It starts with `npx brightspace-d2l-mcp doctor`.
+
 <details>
 <summary><b>"No supported browser was found"</b></summary>
 
@@ -284,6 +332,12 @@ Yes. Local agents and SDKs launch it with `npx -y brightspace-d2l-mcp@latest`, a
 No. Brightspace API keys normally require an administrator. This uses your own student sign-in instead, so it sees exactly what you see in Brightspace, and nobody at your school has to set anything up.
 </details>
 
+<details>
+<summary><b>How do I switch from brightspace-mcp-server to this one?</b></summary>
+
+Change the package name in your MCP config: replace `brightspace-mcp-server` with `brightspace-d2l-mcp` in the same `brightspace` entry, then restart the app. Or run `npx brightspace-d2l-mcp setup` and let it write the entry for you. [Switching from brightspace-mcp-server](#switching-from-brightspace-mcp-server) covers what carries over and what does not.
+</details>
+
 <details>
 <summary><b>Does it work with Duo, Microsoft Authenticator or text-message codes?</b></summary>
 
@@ -334,6 +388,20 @@ node build/index.js setup     # connects your AI apps to this local build
 Tools live in [`src/tools/`](src/tools), sign-in in [`src/auth/`](src/auth), and setup in [`src/cli/`](src/cli).
 Issues and pull requests are welcome.
 
+## More free student MCP servers
+
+All free, open source and read only where they touch your accounts. Browse the full list at [brightspacemcp.com/more-mcps](https://brightspacemcp.com/more-mcps/).
+
+| Server | What it does |
+| --- | --- |
+| [Canvas MCP](https://github.com/AnonymousOnyx22/canvas-lms-student-mcp) | Canvas LMS for AI, read only. Due dates, missing work, grades and announcements. |
+| [Moodle MCP](https://github.com/AnonymousOnyx22/moodle-student-mcp) | Moodle for AI, read only. Due dates, overdue work, grades and announcements. |
+| [Google Classroom MCP](https://github.com/AnonymousOnyx22/google-classroom-student-mcp) | Google Classroom for AI, read only. Todos, due dates, missing work and grades. |
+| [GPA Calculator MCP](https://github.com/AnonymousOnyx22/gpa-calculator-mcp) | GPA, grade conversion and the grade you need on the final, for AI. Works offline, no account. |
+| [Citations MCP](https://github.com/AnonymousOnyx22/student-citations-mcp) | APA, MLA and Chicago citations from a DOI, an ISBN or typed details. No account. |
+| [Study Planner MCP](https://github.com/AnonymousOnyx22/study-planner-mcp) | Exam study schedules, spaced repetition dates, pomodoro plans and assignment milestones. Works offline. |
+| [Paper Finder MCP](https://github.com/AnonymousOnyx22/paper-finder-student-mcp) | Search scholarly papers, find open access copies and related work through OpenAlex. No key needed. |
+
 ## License
 
 [MIT](LICENSE) © AnonymousOnyx22

package/build/api/errors.js

@@ -12,13 +12,28 @@ function withSessionHint(status, message) {
     const detail = message.trim();
     return detail ? `${detail} ${SESSION_EXPIRED_HINT}` : SESSION_EXPIRED_HINT;
 }
+// A stale course id must never reach the person as a bare 404. Every 404
+// message names the tool that lists the valid ids, so the next step is obvious
+// wherever the text shows up: a tool result mid-chat, a log line, or the CLI.
+export const COURSE_NOT_FOUND_HINT = `Call \`get_my_courses\` to list valid course IDs, then retry.`;
+// An empty enrollment list gives the caller nothing to work with, so the
+// message points at the command that checks the sign in again.
+export const NO_COURSES_HINT = `No courses came back from Brightspace. Run \`${SETUP_COMMAND}\` again to check your sign in, then retry.`;
+// Appends the get_my_courses hint to a 404. A caller that already named the
+// tool keeps its own wording, so the hint is never repeated in one message.
+function withCourseHint(status, message) {
+    if (status !== 404 || message.includes("get_my_courses"))
+        return message;
+    const detail = message.trim();
+    return detail ? `${detail} ${COURSE_NOT_FOUND_HINT}` : COURSE_NOT_FOUND_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}: ${withSessionHint(status, message)}`, cause);
+        super(`[PBMCP-2001] API error (${status}) at ${endpoint}: ${withSessionHint(status, withCourseHint(status, message))}`, cause);
         this.status = status;
         this.endpoint = endpoint;
         this.responseBody = responseBody;
@@ -58,4 +73,23 @@ export class TokenRefreshError extends NetworkError {
         this.name = "TokenRefreshError";
     }
 }
+// The caller named a course id that is not in their enrollments. Thrown from
+// the enrollment check, before any course scoped request goes out, so the
+// person sees this instead of a bare 404 from Brightspace.
+export class CourseNotFoundError extends Error {
+    courseId;
+    constructor(courseId) {
+        super(`Course ${courseId} is not one of your Brightspace courses. ${COURSE_NOT_FOUND_HINT}`);
+        this.courseId = courseId;
+        this.name = "CourseNotFoundError";
+    }
+}
+// The enrollment list came back empty, so there is nothing for any course tool
+// to read. Setting up again checks the saved sign in and the school address.
+export class NoCoursesError extends Error {
+    constructor() {
+        super(NO_COURSES_HINT);
+        this.name = "NoCoursesError";
+    }
+}
 //# sourceMappingURL=errors.js.map

package/build/api/index.js

@@ -7,6 +7,6 @@ export { discoverVersions } from "./version-discovery.js";
 export { TTLCache } from "./cache.js";
 export { TokenBucket } from "./rate-limiter.js";
 // Errors
-export { ApiError, RateLimitError, NetworkError } from "./errors.js";
+export { ApiError, RateLimitError, NetworkError, CourseNotFoundError, NoCoursesError, COURSE_NOT_FOUND_HINT, NO_COURSES_HINT, } from "./errors.js";
 export { DEFAULT_CACHE_TTLS } from "./types.js";
 //# sourceMappingURL=index.js.map

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. Example: \"Did my professors post anything new?\"",
+        description: "Fetch recent announcements (news items) from your courses in D2L Brightspace. Can filter to a specific course or get announcements across all courses. Use this when the user asks about announcements, news, news items, updates from instructors, recent posts, or what professors said in Brightspace or D2L. Example: \"Did my professors post anything new?\"",
         inputSchema: GetAnnouncementsSchema,
         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. Example: \"What assignments do I have in Calculus this week?\"",
+        description: "Fetch assignments and quizzes for a specific course or all enrolled courses in D2L Brightspace. Shows dropbox (assignment) submissions and quizzes with due dates, status, and rubric info. Use this when the user asks about assignments, homework, dropboxes, dropbox folders, what to submit, quizzes, or assignment details and rubrics in Brightspace or D2L. Example: \"What assignments do I have in Calculus this week?\"",
         inputSchema: GetAssignmentsSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

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

@@ -2,6 +2,7 @@ import { DEFAULT_CACHE_TTLS } from "../api/index.js";
 import { fetchAllItems } from "../api/paginate.js";
 import { GetMyCoursesSchema, } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
+import { NoCoursesError } from "../api/errors.js";
 import { log } from "../utils/logger.js";
 import { applyCourseFilter } from "../utils/course-filter.js";
 export function registerGetMyCourses(server, apiClient, config) {
@@ -32,6 +33,10 @@ export function registerGetMyCourses(server, apiClient, config) {
                 canAccess: item.Access.CanAccess,
                 lastAccessed: item.Access.LastAccessed,
             })), { ...config.courseFilter, activeOnly });
+            // An empty list leaves the caller stuck, so say which command checks
+            // the sign in again instead of returning nothing to act on.
+            if (courses.length === 0)
+                throw new NoCoursesError();
             log("INFO", `get_my_courses: Retrieved ${courses.length} courses`);
             return toolResponse(courses);
         }

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. Example: \"What's my current grade in Calculus?\"",
+        description: "Fetch your grade breakdown for a specific course or all enrolled courses in D2L Brightspace. Shows grade items (grade columns) with points, percentages, and comments. Use this when the user asks about grades, grade items, grade item, scores, marks, GPA, academic performance, or how they're doing in a class in Brightspace or D2L. Example: \"What's my current grade in Calculus?\"",
         inputSchema: GetMyGradesSchema,
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, async (args) => {

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

@@ -1,4 +1,6 @@
 import { DEFAULT_CACHE_TTLS } from "../api/index.js";
+import { CourseNotFoundError, NoCoursesError } from "../api/errors.js";
+import { fetchAllItems } from "../api/paginate.js";
 import { GetUpcomingDueDatesSchema } from "./schemas.js";
 import { toolResponse, sanitizeError } from "./tool-helpers.js";
 import { log } from "../utils/logger.js";
@@ -10,9 +12,10 @@ function unwrapList(raw) {
 }
 export async function resolveCourses(apiClient, config, courseId) {
     let items = [];
+    let enrollmentsLoaded = false;
     try {
-        const response = await apiClient.get(apiClient.lp("/enrollments/myenrollments/?orgUnitTypeId=3&isActive=true"), { ttl: DEFAULT_CACHE_TTLS.enrollments });
-        items = response.Items ?? [];
+        items = await fetchAllItems(apiClient, apiClient.lp("/enrollments/myenrollments/?orgUnitTypeId=3&isActive=true"), { ttl: DEFAULT_CACHE_TTLS.enrollments });
+        enrollmentsLoaded = true;
     }
     catch (error) {
         if (!courseId)
@@ -21,6 +24,10 @@ export async function resolveCourses(apiClient, config, courseId) {
     }
     if (courseId) {
         const match = items.find((item) => item.OrgUnit.Id === courseId);
+        // Only claim the id is unknown when the list really loaded. After a failed
+        // lookup the course scoped request is still the better test.
+        if (enrollmentsLoaded && !match)
+            throw new CourseNotFoundError(courseId);
         return [{ id: courseId, name: match?.OrgUnit.Name ?? null }];
     }
     const filtered = applyCourseFilter(items.map((item) => ({
@@ -30,6 +37,8 @@ export async function resolveCourses(apiClient, config, courseId) {
         isActive: item.Access.IsActive,
         canAccess: item.Access.CanAccess,
     })), config.courseFilter);
+    if (enrollmentsLoaded && filtered.length === 0)
+        throw new NoCoursesError();
     return filtered.map((course) => ({ id: course.id, name: course.name }));
 }
 async function fetchCourseDueItems(apiClient, baseUrl, course) {

package/build/tools/tool-helpers.js

@@ -1,6 +1,6 @@
 import { ZodError } from "zod";
 import { ApiError, RateLimitError, NetworkError } from "../api/index.js";
-import { TokenRefreshError } from "../api/errors.js";
+import { TokenRefreshError, CourseNotFoundError, NoCoursesError, COURSE_NOT_FOUND_HINT, } from "../api/errors.js";
 import { AuthRequiredError } from "../auth/authenticator.js";
 import { log } from "../utils/logger.js";
 import { SETUP_COMMAND } from "../utils/paths.js";
@@ -36,9 +36,13 @@ export function sanitizeError(error) {
         const detail = error.detail && isSafeDetail(error.detail) ? ` (detected type: ${error.detail})` : "";
         return errorResponse(`Could not save the file.${detail} ${DOWNLOAD_FAILURE_GUIDANCE[error.kind]}`);
     }
+    // Messages are written by this package, never copied from a remote response.
+    if (error instanceof CourseNotFoundError || error instanceof NoCoursesError) {
+        return errorResponse(error.message);
+    }
     if (error instanceof ApiError) {
         if (error.status === 404) {
-            return errorResponse("Resource not found. The course or item may not exist, or you may not have access.");
+            return errorResponse(`Resource not found. The course or item may not exist, or you may not have access. ${COURSE_NOT_FOUND_HINT}`);
         }
         if (error.status === 401) {
             return errorResponse(`Your Brightspace session expired and signing in again did not finish. Run \`${SETUP_COMMAND}\` in a terminal, then try again.`);

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. Current version: 1.4.2.
+> 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.4.
 
 ## Install
 
@@ -49,6 +49,30 @@ The server also offers MCP prompts: what_should_i_do_now, plan_my_week, weekly_d
 
 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.
 
+## Which tool to use (decision table, routing table)
+
+Short routing: due today -> get_todo, target grade -> get_grade_outlook, catch up -> get_whats_new.
+
+| If the user asks about | Use this tool |
+|---|---|
+| What is due today, or what should I do now | get_todo |
+| What they need on the remaining work to hit a target grade | get_grade_outlook |
+| Catching up on what is new across every course | get_whats_new |
+| Upcoming deadlines with real submission status | get_upcoming_due_dates |
+| Exams, tests, labs or classes | get_calendar_events |
+| Current grades and instructor comments | get_my_grades |
+| Assignments and quizzes with rubrics | get_assignments |
+| Files attached to an assignment | get_assignment_files |
+| Course modules, slides, files and links | get_course_content |
+| Syllabus and course overview | get_syllabus |
+| Recent announcements | get_announcements |
+| Discussion forums and posts | get_discussions |
+| Instructors and TAs with contact info | get_roster |
+| Email addresses for a course | get_classlist_emails |
+| Saving a course file or submission | download_file |
+| Exporting unfinished deadlines to a calendar | export_due_dates_calendar |
+| Enrolled courses | get_my_courses |
+
 ## Other commands
 
 - npx brightspace-d2l-mcp login signs in again
@@ -71,5 +95,6 @@ The password is never seen or stored because the user types it into the school's
 ## Links
 
 - Repository https://github.com/AnonymousOnyx22/brightspace-d2l-mcp
+- Troubleshooting https://github.com/AnonymousOnyx22/brightspace-d2l-mcp/blob/main/docs/troubleshooting.md
 - npm https://www.npmjs.com/package/brightspace-d2l-mcp
 - Agent setup guides https://github.com/AnonymousOnyx22/brightspace-d2l-mcp/blob/main/docs/agents.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brightspace-d2l-mcp",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "mcpName": "io.github.AnonymousOnyx22/brightspace-d2l-mcp",
   "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",