brightspace-mcp-server 3.8.1 → 3.8.3

package/README.md

@@ -6,7 +6,7 @@ Talk to your Brightspace courses with AI. Ask about grades, due dates, quizzes,
 
 This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that connects your AI to D2L Brightspace so it can pull your grades, assignments, syllabus, and course content on demand.
 
-Connects to D2L Brightspace. Automatic login supports Purdue's Microsoft Entra flow, SUNY campus selection, Western University, and TU Delft NetID via SURFconext. Other schools need a compatible automated sign-in flow; unsupported login pages return an actionable error.
+Connects to D2L Brightspace. Automatic login supports Purdue's Microsoft Entra flow, SUNY campus selection, Western University, TU Delft NetID via SURFconext, and CUNY Login. Other schools need a compatible automated sign-in flow; unsupported login pages return an actionable error.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/RohanMuppa/brightspace-mcp-server/main/docs/how-it-works.svg" alt="Architecture diagram" width="100%">
@@ -28,7 +28,7 @@ Paste this into Claude Code, Cursor, Windsurf, Copilot, Codex, or any AI coding
 ```
 Install brightspace-mcp-server for me by following
 https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
-(use --purdue at Purdue, --suny at SUNY, or --tudelft at TU Delft).
+(use --purdue at Purdue, --suny at SUNY, --tudelft at TU Delft, or --cuny at CUNY).
 ```
 
 **Option 2: Run it yourself**
@@ -58,6 +58,16 @@ npx -y brightspace-mcp-server@latest setup --tudelft
 
 Use your NetID rather than your student email address. The TU Delft flow is headless NetID username and password sign-in only, including automatic re-authentication when the saved session expires; it does not support MFA or any other interactive step. If your account requires one, [open an issue](https://github.com/RohanMuppa/brightspace-mcp-server/issues) — that tenant isn't supported yet.
 
+CUNY students can add `--cuny`. Sign in with your full CUNY Login address
+(`firstname.lastname01@login.cuny.edu`); authentication asks in the terminal
+for the 6-digit code from your authenticator app. CUNY asks for that code on
+every full sign-in, so when your Brightspace session ends, run
+`npx -y brightspace-mcp-server@latest auth` in a terminal again:
+
+```bash
+npx -y brightspace-mcp-server@latest setup --cuny
+```
+
 The wizard saves your password in the native credential store and asks how you'll complete MFA: wait for approval or number matching, enter a terminal code from Google Authenticator or another app, or use a visible browser for other interactive methods. It can also configure Claude Desktop, Cursor, Codex Desktop and CLI, and Claude Code when installed — restart your AI client when it finishes.
 
 Any other D2L school: run `setup` without a flag and paste your Brightspace URL (for example `https://yourschool.brightspace.com`).
@@ -99,7 +109,7 @@ There's no login step — asking a question signs you in.
 
 **Normal days:** tokens renew over HTTPS, and a background browser silently replays your saved Microsoft session (silent SSO) if it lapses.
 
-**When MFA is asked:** the number to approve shows up right in the tool's response, and sign-in finishes in the background — approve it, call the tool again, and use the newest number if one goes stale. TOTP apps (Google Authenticator, etc.) get prompted via the terminal; visible-browser mode opens a window instead, though automatic recovery during a tool call still runs headless unless you set `D2L_HEADLESS=false`. On Duo, sign-in auto-answers "Is this your device?" with **yes**, since a headless run has nobody to click it — this also makes Duo remember the device, so skip it on shared machines. Set `D2L_DUO_PASSCODE` to swap the push for a typed passcode. On Microsoft's MFA page the server ticks "Don't ask again" when your school offers it, so later sign-ins can skip the second factor; how long that lasts is the school's setting, not the server's (`D2L_REMEMBER_MFA=false` turns this off, and `get_server_info` shows whether it was offered).
+**When MFA is asked:** the number to approve shows up right in the tool's response, and sign-in finishes in the background — approve it, call the tool again, and use the newest number if one goes stale. TOTP apps (Google Authenticator, etc.) get prompted via the terminal; visible-browser mode opens a window instead, though automatic recovery during a tool call still runs headless unless you set `D2L_HEADLESS=false`. On Duo, sign-in auto-answers "Is this your device?" with **yes**, since a headless run has nobody to click it — this also makes Duo remember the device, so skip it on shared machines. Set `D2L_DUO_PASSCODE` to swap the push for a typed passcode. On Microsoft's MFA page, setting `D2L_REMEMBER_MFA=true` makes the server tick "Don't ask again" when your school offers it, so later sign-ins can skip the second factor; how long that lasts is the school's setting, not the server's. It is off by default — leave it off on a shared machine — and `get_server_info` shows whether the box was ticked, offered, or left alone.
 
 **If it gets stuck:** a missed MFA approval pauses automatic sign-in for 5 minutes. This retries immediately, takes over a stuck sign-in, or asks for a code:
 
@@ -123,7 +133,7 @@ Run it from your home folder — macOS blocks `npx` from Documents, Desktop, or
 | Roster | "Who are the TAs for ECE 264?" · "Get me my instructor's email" |
 | Discussions | "What are people saying in the final project thread?" · "Summarize the latest discussion posts" |
 | 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?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, whether a credential is stored, and what Microsoft remembered (`microsoftSession`: stay-signed-in and its expiry, plus whether "Don't ask again" was ticked, already on, or not offered), without contacting Brightspace or revealing secrets |
+| Troubleshooting | "Which version of the Brightspace server am I running?" · "Where is my Brightspace config file?" — `get_server_info` reports the version, Node runtime, platform, config and session paths, school URL, whether a credential is stored, and 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), 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 |
 | Planning | "Build me a study schedule based on my upcoming due dates" · "Which class needs the most attention right now?" — pulls from assignments, quizzes, graded discussion topics (any topic with a due date), and course calendar events such as exams and labs |
 

package/build/auth/browser-auth.js

@@ -26,7 +26,9 @@ const SILENT_SSO = {
     // get past this gate otherwise.
     emailFields: ["input[type=email]", "input[name=loginfmt]", "input[name=j_username]", "input#signinid"],
     credentialFields: ['input#username', 'input#userName', 'input[type="password"]'],
-    mfaChallenges: ["#idRichContext_DisplaySign", "#idDiv_SAOTCAS_Title", "#idDiv_SAOTCC_Title"],
+    // Entra's number match and code prompts, then CUNY Login's authenticator-code
+    // field (cuny-sso.ts CUNY_TOTP_SELECTOR).
+    mfaChallenges: ["#idRichContext_DisplaySign", "#idDiv_SAOTCAS_Title", "#idDiv_SAOTCC_Title", '[id="otpValue|input"]'],
     campusSaml: 'a[href*="/d2l/lp/auth/saml/initiate-login"]',
     kmsiCheckbox: "#KmsiCheckboxField",
     kmsiTitle: "Stay signed in?",

package/build/auth/cuny-sso.js

@@ -0,0 +1,216 @@
+/** CUNY login entry point. Licensed under MIT; see LICENSE. */
+import { BrowserAuthError } from "../utils/errors.js";
+import { log } from "../utils/logger.js";
+import { AUTH_COMMAND, SETUP_COMMAND } from "../utils/commands.js";
+import { MfaApprovalError, UnsupportedAuthenticationError } from "./sso-flow.js";
+/** All CUNY campuses share one Brightspace tenant behind CUNY Login (Oracle OAM). */
+const CUNY_BRIGHTSPACE_HOST = "brightspace.cuny.edu";
+const CUNY_LOGIN_HOST = "ssologin.cuny.edu";
+/**
+ * Oracle JET generates the authenticator-code field's id with a pipe in it,
+ * which is not valid in an `#id` selector, so match the attribute instead.
+ * browser-auth.ts lists the same selector so a run that resumes on this page
+ * is recognized as an MFA challenge.
+ */
+export const CUNY_TOTP_SELECTOR = '[id="otpValue|input"]';
+const SELECTORS = {
+    // The visible field takes the full @login.cuny.edu address. CUNY's own
+    // submit handler copies the short name into a hidden #CUNYLoginUsername,
+    // so that hidden field is left for the page to fill.
+    username: "#CUNYLoginUsernameDisplay",
+    password: "#CUNYLoginPassword",
+    submit: "#submit",
+    // Only rendered on the reload OAM serves after rejecting the password.
+    serverError: "#serverError",
+    totp: CUNY_TOTP_SELECTOR,
+};
+const POLL_MS = 500;
+/** CUNY parks on a processing page for about ten seconds before the code challenge. */
+const CHALLENGE_TIMEOUT_MS = 60_000;
+/** A person has to find their authenticator and read a code. */
+const MFA_TIMEOUT_MS = 5 * 60 * 1000;
+/** True for the shared CUNY Brightspace instance. */
+export function isCunyBrightspace(baseUrl) {
+    try {
+        return new URL(baseUrl).hostname.toLowerCase() === CUNY_BRIGHTSPACE_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+/** Compare hosts, not substrings: the SAML round trip carries other hosts in its query. */
+function isCunyLogin(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" && parsed.hostname.toLowerCase() === CUNY_LOGIN_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+/** A rejected code reloads the challenge with `?emsg=Entered+TOTP+is+incorrect.` */
+function hasErrorMessage(url) {
+    try {
+        return new URL(url).searchParams.has("emsg");
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Login flow for CUNY Brightspace.
+ *
+ * Brightspace federates by SAML to CUNY Login at ssologin.cuny.edu, an Oracle
+ * Access Manager page rather than Entra, Shibboleth, or Duo:
+ *
+ *   /d2l/login → /oamfed/idp/samlv20 (username + password)
+ *     → /oaa/authnui (a "Processing Request" page, roughly ten seconds)
+ *     → /oaa-totp-factor/rui/index.html (authenticator code) → /d2l/home
+ *
+ * Its username field is a plain text input, which none of the default flow's
+ * username selectors match, and its code challenge is an Oracle JET page the
+ * default MFA loop does not know. The code itself still comes from a person,
+ * through the same terminal prompt or visible browser every other code-based
+ * MFA uses.
+ */
+export class CunySSOFlow {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    hasCredentials() {
+        return Boolean(this.config.username && this.config.password);
+    }
+    async login(page) {
+        try {
+            log("INFO", "Starting CUNY Login sign-in flow");
+            await this.completeLogin(page);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof BrowserAuthError)
+                throw error;
+            throw new UnsupportedAuthenticationError("CUNY Login could not complete automatic sign-in. Check saved credentials and your authenticator settings.", error);
+        }
+    }
+    /**
+     * Poll the page and answer whichever CUNY Login step is on screen. A run
+     * can hand over mid-flow (awaitSilentSSO also stops on the code page), so
+     * no step is assumed to come first.
+     */
+    async completeLogin(page) {
+        // A visible browser may be answering a different CUNY MFA method by hand.
+        let deadline = Date.now() + (this.config.headless === false ? MFA_TIMEOUT_MS : CHALLENGE_TIMEOUT_MS);
+        let credentialsSubmitted = false;
+        let challenged = false;
+        /** The challenge URL a code was submitted from; a reload away from it with ?emsg= is a rejection. */
+        let codeSubmittedFrom = null;
+        let announced = false;
+        while (Date.now() < deadline) {
+            if (await this.isAuthenticated(page)) {
+                log("INFO", "Login successful - verified Brightspace home");
+                return;
+            }
+            // Never type the CUNY password into anything but CUNY Login itself.
+            if (isCunyLogin(page.url())) {
+                if (await this.isVisible(page, SELECTORS.serverError)) {
+                    throw new BrowserAuthError(`CUNY Login rejected the saved username or password. Run \`${SETUP_COMMAND} --cuny\` to update them.`, "credentials");
+                }
+                if (await this.isVisible(page, SELECTORS.totp)) {
+                    if (!challenged) {
+                        challenged = true;
+                        deadline = Date.now() + MFA_TIMEOUT_MS;
+                    }
+                    if (this.config.headless === false) {
+                        // The person at the window types the code and can retry a typo
+                        // there, so a rejection is theirs to answer, not a failure here.
+                        if (!announced) {
+                            announced = true;
+                            log("WARN", "Enter the code from your authenticator app in the CUNY Login window. Waiting up to 5 minutes.");
+                            this.config.onMfaChallenge?.(null);
+                        }
+                    }
+                    else {
+                        const url = page.url();
+                        if (codeSubmittedFrom !== null && url !== codeSubmittedFrom && hasErrorMessage(url)) {
+                            throw new MfaApprovalError(new Error("CUNY Login rejected the authenticator code."));
+                        }
+                        if (codeSubmittedFrom === null) {
+                            codeSubmittedFrom = url;
+                            await this.submitCode(page);
+                        }
+                    }
+                }
+                else if (!credentialsSubmitted && await this.isVisible(page, SELECTORS.username)) {
+                    // CUNY Login asks for a code on every full sign-in and does not
+                    // re-federate Brightspace from its own cookies, so a headless run with
+                    // no terminal (the MCP server's background re-authentication) can
+                    // never finish. Stop before the password is sent: otherwise every tool
+                    // call after the session ends posts it again, and a stale saved
+                    // password would keep counting toward a CUNY lockout.
+                    if (this.config.headless !== false && !this.config.requestMfaCode)
+                        throw this.codePromptUnavailable();
+                    credentialsSubmitted = true;
+                    await this.enterCredentials(page);
+                }
+            }
+            await page.waitForTimeout(POLL_MS);
+        }
+        if (challenged)
+            throw new MfaApprovalError();
+        throw new UnsupportedAuthenticationError("CUNY Login did not reach the authenticator-code challenge or Brightspace. If your default CUNY MFA method is not an authenticator app, set D2L_HEADLESS=false and finish sign-in in the browser.");
+    }
+    async enterCredentials(page) {
+        if (!this.config.username)
+            throw new BrowserAuthError("Username is required for SSO login", "credentials");
+        if (!this.config.password)
+            throw new BrowserAuthError("Password is required for SSO login", "credentials");
+        log("INFO", "Entering CUNY Login credentials");
+        await page.locator(SELECTORS.username).first().fill(this.config.username);
+        await page.locator(SELECTORS.password).first().fill(this.config.password);
+        // OAM answers the POST with a full navigation, which can detach the button.
+        await page.locator(SELECTORS.submit).first().click().catch(() => { });
+    }
+    codePromptUnavailable() {
+        return new UnsupportedAuthenticationError(`CUNY Login requires an authenticator code. Run \`${AUTH_COMMAND}\` in a terminal to enter it.`);
+    }
+    /** Feed CUNY's code challenge from the terminal prompt. */
+    async submitCode(page) {
+        if (!this.config.requestMfaCode)
+            throw this.codePromptUnavailable();
+        const code = (await this.config.requestMfaCode()).replace(/\s/g, "");
+        if (!/^\d{6,8}$/.test(code))
+            throw new UnsupportedAuthenticationError("The MFA code must contain 6-8 digits.");
+        await page.locator(SELECTORS.totp).first().fill(code);
+        // Oracle JET gives the Verify button no id; its label is the stable handle.
+        const verify = page.getByRole("button", { name: /^\s*verify\s*$/i }).first();
+        if (await verify.isVisible().catch(() => false))
+            await verify.click().catch(() => { });
+        else
+            await page.locator(SELECTORS.totp).first().press("Enter");
+        log("INFO", "Authenticator code submitted");
+    }
+    async isVisible(page, selector) {
+        return page.locator(selector).first().isVisible().catch(() => false);
+    }
+    /** The login shell also exposes D2L.LP, so verify origin and home as well. */
+    async isAuthenticated(page) {
+        try {
+            const expected = new URL(this.config.baseUrl ?? `https://${CUNY_BRIGHTSPACE_HOST}`);
+            const current = new URL(page.url());
+            if (current.origin !== expected.origin || !/^\/d2l\/home(?:\/|$)/.test(current.pathname))
+                return false;
+            const cookies = await page.context().cookies(expected.origin);
+            if (!cookies.some(cookie => cookie.name === "d2lSessionVal" && Boolean(cookie.value)))
+                return false;
+            return await page.evaluate(() => {
+                const d2l = window.D2L;
+                return Boolean(d2l?.LP);
+            });
+        }
+        catch {
+            // Redirects can replace the execution context mid-check. Keep polling.
+            return false;
+        }
+    }
+}

package/build/auth/index.js

@@ -7,6 +7,7 @@ export { BrowserAuth } from "./browser-auth.js";
 export { PurdueSSOFlow } from "./purdue-sso.js";
 export { SunySSOFlow, isSunyBrightspace } from "./suny-sso.js";
 export { TUDelftSSOFlow, isTUDelftBrightspace } from "./tudelft-sso.js";
+export { CunySSOFlow, isCunyBrightspace } from "./cuny-sso.js";
 export { createSSOFlow } from "./sso-flow.js";
 export { TokenManager } from "./token-manager.js";
 export { SessionStore } from "./session-store.js";

package/build/auth/microsoft-session.js

@@ -10,7 +10,7 @@ import { BROWSER_STATE_FILE } from "./browser-state-store.js";
 const SUMMARY_FILE = "microsoft-session.json";
 const ENTRA_HOST = "login.microsoftonline.com";
 const ENTRA_COOKIES = new Set(["ESTSAUTH", "ESTSAUTHPERSISTENT", "ESTSAUTHLIGHT"]);
-const OUTCOMES = ["ticked", "already", "absent", "unknown"];
+const OUTCOMES = ["ticked", "already", "absent", "unknown", "off"];
 /** Latest expiry of each Entra sign-in cookie in a jar. */
 function entraExpiries(state) {
     const expiries = new Map();

package/build/auth/purdue-sso.js

@@ -39,6 +39,7 @@ const REMEMBER_MFA_LOG = {
     already: "already checked",
     absent: "not offered by tenant",
     unknown: "could not be ticked",
+    off: "off (set D2L_REMEMBER_MFA=true to tick it)",
 };
 /** How often to look for the number while waiting on MFA. */
 const NUMBER_MATCH_POLL_MS = 2000;
@@ -469,11 +470,18 @@ export class PurdueSSOFlow {
     }
     /**
      * Tick Entra's "Don't ask again" box, once per login and never in a loop.
+     * Opt-in: without an explicit true the box is left alone and the outcome
+     * is recorded as "off", so get_server_info can say why nothing was ticked.
      * An already-checked box is left alone so this can never untick it.
      */
     async rememberMfaDevice(page) {
-        if (this.rememberMfa || this.config.rememberMfa === false)
+        if (this.rememberMfa)
             return;
+        if (this.config.rememberMfa !== true) {
+            this.rememberMfa = { outcome: "off", at: new Date().toISOString() };
+            log("INFO", `Entra remember-MFA checkbox: ${REMEMBER_MFA_LOG.off}`);
+            return;
+        }
         if (new URL(page.url()).hostname !== "login.microsoftonline.com")
             return;
         // A nicety, never a reason to fail sign-in: any surprise is "unknown".

package/build/auth/sso-flow.js

@@ -7,6 +7,7 @@ import { PurdueSSOFlow } from "./purdue-sso.js";
 import { SunySSOFlow, isSunyBrightspace } from "./suny-sso.js";
 import { WesternSSOFlow, isWesternBrightspace } from "./western-sso.js";
 import { TUDelftSSOFlow, isTUDelftBrightspace } from "./tudelft-sso.js";
+import { CunySSOFlow, isCunyBrightspace } from "./cuny-sso.js";
 import { BrowserAuthError } from "../utils/errors.js";
 import { AUTH_COMMAND } from "../utils/commands.js";
 export class UnsupportedAuthenticationError extends BrowserAuthError {
@@ -55,5 +56,8 @@ export function createSSOFlow(config, requestMfaCode, onMfaChallenge) {
     if (isWesternBrightspace(config.baseUrl)) {
         return new WesternSSOFlow(credentials);
     }
+    if (isCunyBrightspace(config.baseUrl)) {
+        return new CunySSOFlow(credentials);
+    }
     return new PurdueSSOFlow(credentials);
 }

package/build/setup.js

@@ -52,9 +52,16 @@ export const SCHOOL_PRESETS = {
         mfaNote: "Approve the sign-in request from your MFA app.",
         usernameHint: "Use your full sign-in address if your Western account requires it.",
     },
+    cuny: {
+        name: "CUNY",
+        baseUrl: "https://brightspace.cuny.edu",
+        usernameLabel: "CUNY Login username",
+        mfaNote: "Type the 6-digit code from your authenticator app when prompted.",
+        usernameHint: "Use your full CUNY Login address, e.g. firstname.lastname01@login.cuny.edu",
+    },
 };
 /**
- * Pick the school preset named by `--purdue`, `--suny`, `--western`, etc.
+ * Pick the school preset named by `--purdue`, `--suny`, `--western`, `--cuny`, etc.
  *
  * Own properties only: a bare index would make `--constructor` or
  * `--__proto__` resolve to something off `Object.prototype` and hand the

package/build/utils/config.js

@@ -29,8 +29,10 @@ export async function loadConfig() {
     const headless = envBoolean(process.env.D2L_HEADLESS, "D2L_HEADLESS")
         ?? store?.headless
         ?? true;
-    // Ask Microsoft to skip the second factor for its "Don't ask again" window.
-    const rememberMfa = envBoolean(process.env.D2L_REMEMBER_MFA, "D2L_REMEMBER_MFA") ?? true;
+    // Opt-in: ask Microsoft to skip the second factor for its "Don't ask again"
+    // window. Off unless D2L_REMEMBER_MFA=true, so a shared machine never
+    // remembers MFA without the user choosing it.
+    const rememberMfa = envBoolean(process.env.D2L_REMEMBER_MFA, "D2L_REMEMBER_MFA") ?? false;
     // Resolve tokenTtl: env > store > default (3600)
     const tokenTtl = positiveSeconds(process.env.D2L_TOKEN_TTL, "D2L_TOKEN_TTL")
         ?? positiveSeconds(store?.tokenTtl, "tokenTtl in config.json")

package/package.json

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