brightspace-d2l-mcp 1.4.3 → 1.4.4

package/CHANGELOG.md

@@ -1,8 +1,13 @@
 # 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
 

package/README.md

@@ -251,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>
 
@@ -386,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.3.
+> 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.3",
+  "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",