brightspace-mcp-server 3.9.6 → 3.9.7

package/README.md

@@ -175,6 +175,7 @@ If this is a Docker or other headless setup with no `~/.brightspace-mcp/config.j
 | Roster | "Who are the TAs for ECE 264?" · "Get me my instructor's email" |
 | Groups | "Who is in my project group?" · "List my lab group members for this course" |
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |
+| Search | "Search this course for the midterm review slides" · "Has anyone posted about office hours?" — searches content, announcements, and discussions by keyword in one call instead of reading the whole content tree |
 | Video transcripts | "What did the professor say about pinch-off in Tuesday's lecture recording?" · "Summarize last week's BoilerCast video" — works for Kaltura and YouTube embeds; other platforms report that they aren't supported yet |
 | Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" · "What timezone are my due dates being computed in?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, whether a credential is stored, the server's local timezone and UTC offset (`localTimezone`, `utcOffsetMinutes`), who the session is signed in as when known (`signedInAs: { uniqueName, displayName }`), what Microsoft remembered (`microsoftSession`: stay-signed-in and its expiry, plus whether "Don't ask again" was ticked, already on, not offered, or left off because `D2L_REMEMBER_MFA` isn't set), and `requests` (lightweight counters: responses by status class, network errors, cache hits/misses, coalesced in-flight joins, and token refreshes), without contacting Brightspace or revealing secrets |
 | Calendar | "When is my midterm?" · "What's on my calendar this week?" · "Is lab cancelled on Thursday?" — reads exams, labs, review sessions, and deadlines instructors put only on the course calendar |

package/build/index.js

@@ -16,7 +16,7 @@ import { startUpdateChecks } from "./utils/update-checker.js";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, } from "./tools/index.js";
+import { registerGetMyCourses, registerGetUpcomingDueDates, registerGetCalendarEvents, registerGetMyGrades, registerGetAnnouncements, registerGetAssignments, registerGetAssignmentRubric, registerGetAssignmentFiles, registerGetAnnouncementFiles, registerGetCourseContent, registerDownloadFile, registerGetClasslistEmails, registerGetRoster, registerGetMyGroups, registerGetSyllabus, registerGetDiscussions, registerGetVideoTranscript, registerGetServerInfo, registerSearchCourse, } from "./tools/index.js";
 import { registerWeeklyBriefingPrompt, registerGradeAuditPrompt, registerStudyPlannerPrompt, registerCourseSummaryPrompt, } from "./prompts/index.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -134,7 +134,8 @@ else {
             registerGetDiscussions(server, apiClient);
             registerGetVideoTranscript(server, apiClient);
             registerGetServerInfo(server, config, PKG_VERSION, apiClient);
-            log("DEBUG", "MCP tools registered (18 tools)");
+            registerSearchCourse(server, apiClient);
+            log("DEBUG", "MCP tools registered (19 tools)");
             // 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
@@ -147,7 +148,7 @@ else {
             // Connect stdio transport
             const transport = new StdioServerTransport();
             await server.connect(transport);
-            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (18 tools, 4 prompts registered)");
+            log("INFO", "Brightspace MCP Server by Rohan Muppa — running on stdio (19 tools, 4 prompts registered)");
             log("INFO", "Setup: see README.md for MCP client configuration (Claude Desktop, ChatGPT Desktop, Cursor, etc.)");
         }
         catch (error) {

package/build/tools/get-announcements.js

@@ -52,6 +52,15 @@ export function newestFirst(a, b) {
         return -1;
     return new Date(b.date).getTime() - new Date(a.date).getTime();
 }
+/**
+ * Fetch the raw news items for a course. Shared with search_course so both
+ * tools hit the same endpoint (and cache entry) instead of duplicating it.
+ */
+export async function fetchCourseNews(apiClient, courseId) {
+    return apiClient.get(apiClient.le(courseId, "/news/"), {
+        ttl: DEFAULT_CACHE_TTLS.announcements,
+    });
+}
 /**
  * Map a raw D2L news item to a clean announcement object.
  */
@@ -88,10 +97,7 @@ export function registerGetAnnouncements(server, apiClient, config) {
             const cutoff = modifiedSince ? new Date(modifiedSince) : null;
             // Single course case
             if (courseId) {
-                const path = apiClient.le(courseId, "/news/");
-                const newsItems = await apiClient.get(path, {
-                    ttl: DEFAULT_CACHE_TTLS.announcements,
-                });
+                const newsItems = await fetchCourseNews(apiClient, courseId);
                 // Drop drafts, then map to clean objects
                 const published = newsItems.filter(isPublishedNewsItem).map(mapNewsItem);
                 const matched = cutoff
@@ -129,10 +135,7 @@ export function registerGetAnnouncements(server, apiClient, config) {
             // Fetch announcements for each course (handle 403s gracefully)
             const announcementPromises = filteredEnrollments.map(async (item) => {
                 try {
-                    const path = apiClient.le(item.OrgUnit.Id, "/news/");
-                    const newsItems = await apiClient.get(path, {
-                        ttl: DEFAULT_CACHE_TTLS.announcements,
-                    });
+                    const newsItems = await fetchCourseNews(apiClient, item.OrgUnit.Id);
                     return newsItems
                         .filter(isPublishedNewsItem)
                         .map((newsItem) => ({

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

@@ -34,6 +34,28 @@ function matchesTypeFilter(item, filter) {
             return true;
     }
 }
+/**
+ * Fetch the root content modules for a course. Shared with search_course so
+ * both tools walk the exact same tree (and share its cache entry) instead of
+ * each hand-rolling the `/content/root/` call.
+ */
+export async function fetchRootContent(apiClient, courseId) {
+    return apiClient.get(apiClient.le(courseId, '/content/root/'), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+}
+/**
+ * Fetch a single module's structure, or null when the dedicated endpoint
+ * fails (locked module, transient error) so the caller can fall back to
+ * whatever structure the parent listing already embedded.
+ */
+export async function fetchModuleStructure(apiClient, courseId, moduleId) {
+    try {
+        return await apiClient.get(apiClient.le(courseId, `/content/modules/${moduleId}/structure/`), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+    }
+    catch (e) {
+        log('DEBUG', `Failed to fetch children for module ${moduleId}: falling back to the embedded structure`);
+        return null;
+    }
+}
 /**
  * How deep the tree builder will descend when the caller names no maxDepth.
  * A module structure that lists itself is a cycle, and without a ceiling the
@@ -61,7 +83,7 @@ function availabilityFields(availability) {
 /**
  * Recursively build the content tree with progress tracking.
  */
-async function buildContentTree(apiClient, courseId, modules, progressMap, typeFilter, maxDepth, currentDepth = 0, parentAvailability, now = new Date()) {
+export async function buildContentTree(apiClient, courseId, modules, progressMap, typeFilter, maxDepth, currentDepth = 0, parentAvailability, now = new Date()) {
     const tree = [];
     const depthLimit = Math.min(maxDepth ?? MAX_CONTENT_DEPTH, MAX_CONTENT_DEPTH);
     for (const item of modules) {
@@ -77,13 +99,7 @@ async function buildContentTree(apiClient, courseId, modules, progressMap, typeF
                 // what the parent already handed us. Falling through to an empty list
                 // made a locked or erroring module look like an empty one, and under a
                 // typeFilter it dropped the module from the tree with no trace.
-                let children = null;
-                try {
-                    children = await apiClient.get(apiClient.le(courseId, `/content/modules/${item.Id}/structure/`), { ttl: DEFAULT_CACHE_TTLS.courseContent });
-                }
-                catch (e) {
-                    log('DEBUG', `Failed to fetch children for module ${item.Id}: falling back to the embedded structure`);
-                }
+                let children = await fetchModuleStructure(apiClient, courseId, item.Id);
                 if (!Array.isArray(children)) {
                     children = Array.isArray(item.Structure) ? item.Structure : [];
                 }
@@ -218,7 +234,7 @@ export function registerGetCourseContent(server, apiClient) {
             // Parse and validate input
             const { courseId, typeFilter = 'all', moduleTitle, maxDepth, modifiedSince } = GetCourseContentSchema.parse(args);
             // Fetch root modules
-            let rootModules = await apiClient.get(apiClient.le(courseId, '/content/root/'), { ttl: DEFAULT_CACHE_TTLS.courseContent });
+            let rootModules = await fetchRootContent(apiClient, courseId);
             // Filter root modules by title if specified
             if (moduleTitle) {
                 const searchTerm = moduleTitle.toLowerCase();

package/build/tools/get-discussions.js

@@ -8,6 +8,26 @@ import { GetDiscussionsSchema } from "./schemas.js";
 import { toolResponse, sanitizeError, errorResponse } from "./tool-helpers.js";
 import { convertHtmlToMarkdown } from "../utils/html-converter.js";
 import { log } from "../utils/logger.js";
+/**
+ * Fetch a course's discussion forums. Shared with search_course so both
+ * tools hit the same endpoint (and cache entry) instead of duplicating it.
+ */
+export async function fetchForums(apiClient, courseId) {
+    const forumsPath = apiClient.le(courseId, "/discussions/forums/");
+    return apiClient.get(forumsPath, {
+        ttl: DEFAULT_CACHE_TTLS.courseContent,
+    });
+}
+/**
+ * Fetch the topics for a single forum. Shared with search_course, same
+ * reasoning as fetchForums above.
+ */
+export async function fetchForumTopics(apiClient, courseId, forumId) {
+    const topicsPath = apiClient.le(courseId, `/discussions/forums/${forumId}/topics/`);
+    return apiClient.get(topicsPath, {
+        ttl: DEFAULT_CACHE_TTLS.courseContent,
+    });
+}
 /**
  * Register get_discussions tool
  */
@@ -44,19 +64,13 @@ export function registerGetDiscussions(server, apiClient) {
  * Get all forums for a course with their topics (no posts).
  */
 async function getForumsOverview(apiClient, courseId) {
-    const forumsPath = apiClient.le(courseId, "/discussions/forums/");
-    const forums = await apiClient.get(forumsPath, {
-        ttl: DEFAULT_CACHE_TTLS.courseContent,
-    });
+    const forums = await fetchForums(apiClient, courseId);
     const result = [];
     for (const forum of forums) {
         // Fetch topics for each forum
         let topics = [];
         try {
-            const topicsPath = apiClient.le(courseId, `/discussions/forums/${forum.ForumId}/topics/`);
-            topics = await apiClient.get(topicsPath, {
-                ttl: DEFAULT_CACHE_TTLS.courseContent,
-            });
+            topics = await fetchForumTopics(apiClient, courseId, forum.ForumId);
         }
         catch (error) {
             if (error?.status === 403) {

package/build/tools/index.js

@@ -22,6 +22,7 @@ export { registerGetSyllabus } from "./get-syllabus.js";
 export { registerGetDiscussions } from "./get-discussions.js";
 export { registerGetVideoTranscript } from "./get-video-transcript.js";
 export { registerGetServerInfo } from "./get-server-info.js";
+export { registerSearchCourse } from "./search-course.js";
 // Re-export shared helpers and schemas for convenience
 export { toolResponse, errorResponse, sanitizeError } from "./tool-helpers.js";
 export * from "./schemas.js";

package/build/tools/schemas.js

@@ -137,6 +137,14 @@ export const GetRosterSchema = z.object({
     limit: z.coerce.number().int().positive().max(1000).default(100)
         .describe("Maximum users to return. Default 100. The response reports the true total and whether it was truncated."),
 });
+export const SearchCourseSchema = z.object({
+    courseId: z.coerce.number().int().positive()
+        .describe("Course ID to search within."),
+    query: z.string().min(2).max(200)
+        .describe("Keyword(s) to search for, e.g. 'midterm review slides' or 'office hours'."),
+    limit: z.coerce.number().int().positive().max(50).default(10)
+        .describe("Maximum number of results to return, highest scoring first."),
+});
 export const GetAssignmentRubricSchema = z.object({
     courseId: z.coerce.number().int().positive()
         .describe("Course ID the assignment belongs to."),

package/build/tools/search-course.js

@@ -0,0 +1,257 @@
+/**
+ * Purdue Brightspace MCP Server
+ * Copyright (c) 2026 Rohan Muppa. All rights reserved.
+ * Licensed under MIT — see LICENSE file for details.
+ */
+import { ApiError } from "../api/index.js";
+import { SearchCourseSchema } from "./schemas.js";
+import { toolResponse, sanitizeError } 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";
+import { fetchForums, fetchForumTopics } from "./get-discussions.js";
+/** A query term matched in the title outranks the same term only in the body. */
+const TITLE_WEIGHT = 10;
+const BODY_WEIGHT = 1;
+/**
+ * Large enough that an entry matching every query term always outranks one
+ * matching only some of them, regardless of how those partial matches are
+ * distributed between title and body.
+ */
+const ALL_TERMS_BONUS = 1000;
+/**
+ * Lowercase, split on anything that isn't a Unicode letter or digit (so
+ * accented and non-Latin query terms tokenize the same as their matches
+ * instead of being shredded at every diacritic), and drop both empty and
+ * single-character residue left over from the split.
+ */
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter((term) => term.length > 1);
+}
+/**
+ * Score one entry against the already-tokenized query. A term counts once,
+ * against whichever field it was found in first (title preferred), so a term
+ * present in both title and body is not double-counted into a false "both
+ * fields matched" signal.
+ */
+export function scoreEntry(entry, queryTerms) {
+    if (queryTerms.length === 0)
+        return 0;
+    const titleTokens = tokenize(entry.title);
+    const bodyTokens = tokenize(entry.body);
+    let score = 0;
+    let matchedTerms = 0;
+    for (const term of queryTerms) {
+        if (titleTokens.some((t) => t.includes(term))) {
+            score += TITLE_WEIGHT;
+            matchedTerms++;
+        }
+        else if (bodyTokens.some((t) => t.includes(term))) {
+            score += BODY_WEIGHT;
+            matchedTerms++;
+        }
+    }
+    if (matchedTerms === 0)
+        return 0;
+    if (matchedTerms === queryTerms.length)
+        score += ALL_TERMS_BONUS;
+    return score;
+}
+/** First case-insensitive occurrence of any query term in text, or -1. */
+function firstMatchIndex(text, queryTerms) {
+    const lower = text.toLowerCase();
+    let first = -1;
+    for (const term of queryTerms) {
+        const idx = lower.indexOf(term);
+        if (idx >= 0 && (first === -1 || idx < first))
+            first = idx;
+    }
+    return first;
+}
+/**
+ * A window of at most maxLen characters around matchIndex, with an ellipsis
+ * on whichever side(s) were cut — the ellipsis itself counts against maxLen
+ * so the result never exceeds it.
+ */
+export function buildSnippet(text, matchIndex, maxLen = 200) {
+    if (!text)
+        return "";
+    if (matchIndex < 0 || text.length <= maxLen) {
+        return text.length <= maxLen ? text : text.slice(0, maxLen - 1).trimEnd() + "…";
+    }
+    const half = Math.floor(maxLen / 2);
+    let start = Math.max(0, matchIndex - half);
+    let end = start + maxLen;
+    if (end > text.length) {
+        end = text.length;
+        start = Math.max(0, end - maxLen);
+    }
+    const hasPrefix = start > 0;
+    const hasSuffix = end < text.length;
+    const budget = maxLen - (hasPrefix ? 1 : 0) - (hasSuffix ? 1 : 0);
+    let slice = text.slice(start, end).trim();
+    if (slice.length > budget)
+        slice = slice.slice(0, budget);
+    return (hasPrefix ? "…" : "") + slice + (hasSuffix ? "…" : "");
+}
+/**
+ * Score, snippet, sort, and trim every entry to `limit`. Pure and
+ * network-free so ranking can be tested without mocking the API client.
+ */
+export function rankEntries(entries, query, limit) {
+    const queryTerms = tokenize(query);
+    const results = [];
+    for (const entry of entries) {
+        const score = scoreEntry(entry, queryTerms);
+        if (score <= 0)
+            continue;
+        const snippetSource = entry.body.trim() ? entry.body : entry.title;
+        const snippet = buildSnippet(snippetSource, firstMatchIndex(snippetSource, queryTerms));
+        results.push({
+            kind: entry.kind,
+            id: entry.id,
+            title: entry.title,
+            snippet,
+            ...(entry.moduleTitle ? { moduleTitle: entry.moduleTitle } : {}),
+            ...(entry.url ? { url: entry.url } : {}),
+            score,
+        });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+}
+/**
+ * Flatten the content tree built by get_course_content's own buildContentTree
+ * into search entries, carrying each topic's immediate parent module title
+ * along for context.
+ */
+export function flattenContentTree(tree, moduleTitle) {
+    const entries = [];
+    for (const item of tree) {
+        if (item.type === "module") {
+            entries.push({
+                kind: "module",
+                id: item.id,
+                title: item.title,
+                body: item.description ?? "",
+                ...(moduleTitle ? { moduleTitle } : {}),
+            });
+            entries.push(...flattenContentTree(item.children ?? [], item.title));
+        }
+        else if (item.type === "topic") {
+            const body = [item.description, item.content].filter(Boolean).join("\n\n");
+            entries.push({
+                kind: "topic",
+                id: item.id,
+                title: item.title,
+                body,
+                ...(moduleTitle ? { moduleTitle } : {}),
+                ...(item.url ? { url: item.url } : {}),
+            });
+        }
+    }
+    return entries;
+}
+/** A short, safe description of why a source's fetch failed — never the raw error. */
+function describeFailure(error) {
+    if (error instanceof ApiError) {
+        if (error.status === 403)
+            return "no access (403)";
+        if (error.status === 404)
+            return "not found (404)";
+        return `request failed (${error.status})`;
+    }
+    return "request failed";
+}
+/**
+ * Register search_course tool
+ */
+export function registerSearchCourse(server, apiClient) {
+    server.registerTool("search_course", {
+        title: "Search Course",
+        description: "Search a course's content (modules, topics, file names), announcements, and discussion forums/topics by keyword in a single call, instead of reading the whole content tree. Use this when the user wants to find something specific, e.g. 'find the midterm review slides' or 'did anyone post about office hours'. Results are ranked: a result matching every query term ranks above one matching only some, and within that, a match in the title ranks above one only in the body text. If one source (e.g. discussions) can't be read, it's skipped and named in `note` rather than failing the whole search. This fans out over the entire content tree, announcements, and every discussion forum, so it can be slower than calling a single tool like get_course_content directly.",
+        inputSchema: SearchCourseSchema,
+    }, async (args) => {
+        try {
+            log("DEBUG", "search_course tool called", { args });
+            const { courseId, query, limit } = SearchCourseSchema.parse(args);
+            const entries = [];
+            const notes = [];
+            // Content: modules and topics
+            try {
+                const rootModules = await fetchRootContent(apiClient, courseId);
+                const tree = await buildContentTree(apiClient, courseId, rootModules, new Map(), "all");
+                entries.push(...flattenContentTree(tree));
+            }
+            catch (error) {
+                log("DEBUG", `search_course: content fetch failed for course ${courseId}`, error);
+                notes.push(`content: ${describeFailure(error)}`);
+            }
+            // Announcements
+            try {
+                const newsItems = await fetchCourseNews(apiClient, courseId);
+                for (const raw of newsItems.filter(isPublishedNewsItem)) {
+                    const announcement = mapNewsItem(raw);
+                    entries.push({
+                        kind: "announcement",
+                        id: announcement.id,
+                        title: announcement.title,
+                        body: announcement.body,
+                    });
+                }
+            }
+            catch (error) {
+                log("DEBUG", `search_course: announcements fetch failed for course ${courseId}`, error);
+                notes.push(`announcements: ${describeFailure(error)}`);
+            }
+            // Discussions: forums and their topics
+            try {
+                const forums = await fetchForums(apiClient, courseId);
+                for (const forum of forums) {
+                    entries.push({
+                        kind: "discussion",
+                        id: forum.ForumId,
+                        title: forum.Name,
+                        body: forum.Description?.Text ?? "",
+                    });
+                    try {
+                        const topics = await fetchForumTopics(apiClient, courseId, forum.ForumId);
+                        for (const topic of topics) {
+                            entries.push({
+                                kind: "discussion",
+                                id: topic.TopicId,
+                                title: topic.Name,
+                                body: topic.Description?.Text ?? "",
+                                moduleTitle: forum.Name,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        // One forum's topics failing (e.g. no access) shouldn't drop
+                        // every other forum — same graceful-degradation rule
+                        // get_discussions already follows for this exact call.
+                        log("DEBUG", `search_course: topics fetch failed for forum ${forum.ForumId}`, error);
+                    }
+                }
+            }
+            catch (error) {
+                log("DEBUG", `search_course: discussions fetch failed for course ${courseId}`, error);
+                notes.push(`discussions: ${describeFailure(error)}`);
+            }
+            const results = rankEntries(entries, query, limit);
+            log("INFO", `search_course: ${results.length} matches for "${query}" in course ${courseId}`);
+            return toolResponse({
+                courseId,
+                query,
+                results,
+                ...(notes.length > 0 ? { note: `Could not search: ${notes.join("; ")}` } : {}),
+            });
+        }
+        catch (error) {
+            return sanitizeError(error);
+        }
+    });
+}

package/package.json

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