brightspace-mcp-server 1.6.3 → 3.0.0

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.
 
-Works with any school that uses D2L Brightspace, including Purdue, SUNY, USC, and hundreds more.
+Connects to D2L Brightspace. Automatic login supports Purdue's Microsoft Entra flow and SUNY campus selection. 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%">
@@ -19,7 +19,7 @@ Works with any school that uses D2L Brightspace, including Purdue, SUNY, USC, an
 
 ## Install
 
-**You need:** [Node.js 18+](https://nodejs.org/) (download the current LTS, 20 or newer)
+**You need:** [Node.js 20+](https://nodejs.org/) and an available native credential store: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Linux requires `secret-tool` and an unlocked desktop keyring. Install `libsecret-tools` on Debian/Ubuntu, or the package providing `secret-tool` on your distribution. A container or SSH session without Secret Service cannot persist authentication in v2.
 
 **Option 1: Let your AI do it**
 
@@ -34,23 +34,23 @@ https://github.com/RohanMuppa/brightspace-mcp-server/blob/main/LLMs.md
 **Option 2: Run it yourself**
 
 ```bash
-npx brightspace-mcp-server setup
+npx -y brightspace-mcp-server@latest setup
 ```
 
 Purdue students can add `--purdue` to skip entering the school URL:
 
 ```bash
-npx brightspace-mcp-server setup --purdue
+npx -y brightspace-mcp-server@latest setup --purdue
 ```
 
 SUNY campuses share one Brightspace site, so `--suny` also asks which campus
 you're at and skips SUNY's campus picker when you sign in:
 
 ```bash
-npx brightspace-mcp-server setup --suny
+npx -y brightspace-mcp-server@latest setup --suny
 ```
 
-The wizard walks you through login and MFA, auto configures Claude Desktop and Cursor, and prints the config to paste into ChatGPT Desktop if it is installed. Restart your AI client when it finishes.
+The wizard saves your password in the native credential store and asks how you complete MFA. Authentication can wait for approval or number matching, prompt in the terminal for a code from Google Authenticator or another app, or open a visible browser for other interactive methods. The wizard can configure Claude Desktop and Cursor. 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`).
 
@@ -65,19 +65,25 @@ npx -y brightspace-mcp-server@latest
 
 On **Windows**, npx must be wrapped: `cmd /c npx -y brightspace-mcp-server@latest`
 
-You still need to run `npx brightspace-mcp-server setup` first to save your credentials.
+You still need to run `npx -y brightspace-mcp-server@latest setup` first to save your credentials.
 
 </details>
 
 ## Session Expired?
 
-You should rarely see this. Access tokens are re-minted from your saved session cookie in the background, with no browser, in about 200 ms. A browser only opens when the Brightspace session itself has ended. How long that takes is set by your school, not by this tool, and it has not been measured over a long enough stretch to quote a number here. If the automatic re-login fails, run:
+There is nothing to log into first. Ask for your grades and the sign-in happens as part of that request, so the assistant never has to check whether you are authenticated before it can answer. Starting your AI client touches Brightspace not at all: a restart on its own will never set off an MFA prompt.
+
+Returning the next day normally requires no action. The server renews short-lived API tokens over HTTPS using the saved Brightspace session. If that session ends, a browser restores your saved Microsoft session and tries silent SSO. Approval and code-based modes stay headless; when an automatic run needs a code, run the auth command below to enter it securely in the terminal.
+
+Your school's policy controls when MFA is required. There is no local 24-hour cutoff, and the server no longer discards browser state after one hour. A network outage preserves the saved session and returns a temporary error.
+
+If you miss an MFA request, automatic browser authentication pauses for five minutes before trying again. Existing tokens and HTTP token renewal still work. Browser-based SSO also pauses because Microsoft can send another phone prompt during a redirect, even without a password submission. Run this command in a terminal to retry immediately, see a number match, or enter an authenticator code:
 
 ```bash
-npx brightspace-mcp-server auth
+npx -y brightspace-mcp-server@latest auth
 ```
 
-**MFA at Purdue** is Microsoft Authenticator number matching: a two digit number appears in the browser and is also printed in the terminal. Enter it on your phone. Other schools may use Duo or their own app.
+**MFA at Purdue** commonly uses Microsoft Authenticator number matching: enter the terminal-displayed number on your phone. Google Authenticator and other one-time-code apps work too, with no setting to change: run the auth command above in a terminal and it prompts for the code when your provider asks for one. Pick the visible-browser option during setup only if your identity provider needs interaction the server cannot drive. The MCP also sends authentication progress as logging notifications to clients that display them. Some desktop clients hide server logs, so use the terminal command above for interactive MFA.
 
 ## What You Can Ask About
 
@@ -96,8 +102,9 @@ npx brightspace-mcp-server auth
 
 ## Security
 
-- Your username and password stay on your machine in `~/.brightspace-mcp/config.json`, readable only by your user (mode 0600). They are typed into your school's real login page and nowhere else.
-- Session tokens and cookies live in `~/.d2l-session/`, encrypted with AES-256-GCM.
+- Your school URL and username live in `~/.brightspace-mcp/config.json`. Your password lives in the native credential store. macOS and Windows use `@napi-rs/keyring`; Linux uses `secret-tool` directly to require Secret Service without a temporary kernel-key fallback. Linux secrets travel through stdin, never command-line arguments.
+- Each account directory stores `session.json` for access tokens and `storage-state.encrypted.json` for cookies and browser storage. Both use AES-256-GCM with a random key held in the native credential store. The application never writes new plaintext password or browser-state snapshots. `D2L_SESSION_DIR` changes the local root of these account directories.
+- On Unix, session files are mode 0600 and their directory is mode 0700. Security also depends on your operating-system account: software running as you may be able to access the same credential store. Runtime memory and recoverable v1 files in Trash are outside the encrypted-file guarantee.
 - All traffic to Brightspace is HTTPS.
 - On startup the server asks the npm registry whether a newer version exists. When running through `npx`, it clears this package's own stale npx cache directories so the next start downloads the new version. It never installs anything itself. Set `D2L_NO_UPDATE_CHECK=1` to turn the check off.
 - Read only: this server never submits, posts, or changes anything in Brightspace.
@@ -124,38 +131,39 @@ Licensed under the MIT License.
 
 ## Updates
 
-Automatic. Every time your AI client starts a session, it runs `npx brightspace-mcp-server@latest` which pulls the newest version from npm. No action needed.
+Automatic, in both places it matters.
+
+**The MCP server** is registered as `npx -y brightspace-mcp-server@latest`, so your AI client pulls the newest version every time it starts a session.
 
-If you ever suspect you're on an old version (the auth banner prints the version), clear the npx cache and restart your client:
+**The auth CLI** updates itself too. If you installed globally with `npm install -g`, that copy stays at whatever version you installed it at — npm never revisits it. So when the CLI notices it is behind, it re-runs itself through `npx -y brightspace-mcp-server@latest auth` and you get the current code. You are not prompted and there is nothing to confirm.
+
+One caveat worth knowing: a re-exec runs the newest code, it does not overwrite the old copy on disk. `npm ls -g` will still report the version you installed. To actually replace it:
 
 ```bash
+npm install -g brightspace-mcp-server@latest
 npx clear-npx-cache
 ```
 
-## What's new in 1.6.1
-
-- Your saved login now survives a network change. The session file was encrypted with a key derived from the machine hostname, which on campus wifi is a DHCP name that changes with the lease. When it changed, the saved session became unreadable and you were sent back through a full MFA login. Upgrading costs one final login, then it stops.
-
-## What's new in 1.6.0
-
-- **Read the files attached to an assignment.** The spec PDF, the starter workbook, the rubric. Ask what an assignment requires and the answer comes from the actual document, not just its one-line description. Handles PDF, Word, Excel, and PowerPoint.
-- The roster no longer hides people: a class larger than the limit now reports the true total and says it was truncated, and the limit can be raised.
-- Fixed a case where a class list or course list could stop short of the last page.
+Then restart your AI client. The server and the CLI both check npm on startup, and the server re-checks every few hours, so you get told when either one falls behind — including when they disagree with each other.
 
-## What's new in 1.5.0
+Set `D2L_NO_UPDATE_CHECK=1` to switch all of this off.
 
-- Token refresh no longer opens a browser: the access token is re-minted from your session cookie in about 200 ms.
-- Silent re-login when your Microsoft session is still alive, and a fast fallback to the credential login when it is not.
-- The Microsoft Authenticator number match is printed in the terminal, so headless logins can be approved.
-- `get_upcoming_due_dates` reads due dates from assignments and quizzes directly. It no longer reports a quiz as due on the day it opens.
-- Every assignment, quiz, and due date carries a `url` that opens the item in Brightspace.
-- Gradebook columns with no matching assignment or quiz (a proctored midterm, for example) are surfaced as `gradeOnly` items.
-- Unpublished announcements are hidden, and announcements sort by the date they were scheduled to post.
-- A dead session is detected even when Brightspace answers with HTTP 200, so re-login triggers instead of a confusing network error.
-- SUNY preset (`--suny`) and a more robust Microsoft Entra login, contributed by the community.
+## What's new in 3.0.0
 
----
+- Signing in is part of the first tool call. The separate `check_auth` tool is gone, and so is the step where the assistant had to ask about your login before it could answer anything. **This removes a tool, so any saved prompt that names `check_auth` needs updating.**
+- Starting the server makes no network requests. API versions are discovered by the first request that needs them, and a tenant that is briefly unreachable no longer stops the server from starting.
+- Concurrent tool calls on a cold session share one sign-in instead of racing, so you get one MFA prompt rather than several.
+- Failed sign-ins now explain themselves in the tool's answer: a locked keychain, a paused MFA cooldown, or a network outage each say what to do.
+- A missed MFA prompt pauses automatic sign-in for five minutes instead of four hours.
+- Authenticator-code MFA (Google Authenticator and similar) works, with the code entered in the terminal.
+- Every command the server prints is pinned to `@latest`, so following its own advice can never run a stale copy.
 
-Proudly made for Boilermakers by [Rohan Muppa](https://github.com/rohanmuppa) 🚂
+## What's new in 2.0.0
 
+- Headless saved-credential login and terminal MFA, with silent session reuse across restarts.
+- Native secure credential storage and encrypted browser-state migration from v1.
+- Removed the one-hour browser-state cutoff and destructive profile recovery.
+- Process-level authentication coordination, failed-MFA cooldown, and transport errors that preserve your session.
+- Publishing waits for the test matrix on macOS, Windows, and Linux.
+  
 [Report a bug](https://github.com/rohanmuppa/brightspace-mcp-server/issues) · MIT · Copyright 2026 Rohan Muppa

package/build/api/client.d.ts

@@ -8,11 +8,11 @@ import type { D2LApiClientOptions, ApiVersions } from "./types.js";
  * D2L API client with authentication, caching, rate limiting, and version discovery.
  *
  * Key features:
- * - Auto-discovers LP/LE versions from /d2l/api/versions/
+ * - Auto-discovers LP/LE versions from /d2l/api/versions/ on the first request
  * - Supports both Bearer tokens and cookie-based auth (auto-detected via "cookie:" prefix)
  * - Client-side rate limiting using token bucket algorithm
  * - In-memory response caching with per-data-type TTLs
- * - 401 retry logic: retry once with fresh token, then clear and throw
+ * - 401 recovery: refresh the token before requesting browser authentication
  * - HTTPS-only enforcement
  * - Browser-like User-Agent for requests
  * - Raw response passthrough (no transformation)
@@ -27,17 +27,38 @@ export declare class D2LApiClient {
     private readonly onAuthExpired?;
     private readonly retryConfig;
     private versions;
+    /** Single in-flight discovery, so concurrent first requests share one fetch. */
+    private versionsInFlight;
     constructor(options: D2LApiClientOptions);
     /**
-     * Initialize the client by discovering API versions.
-     * Must be called before making API requests.
+     * Discover the API versions, joining a discovery already in flight.
+     *
+     * Called from get() and getRaw() rather than at startup, so the server
+     * answers tools/list without touching the network and a user who never
+     * calls a tool never pays for a request. Nothing needs to call this
+     * directly.
+     */
+    ensureVersions(): Promise<ApiVersions>;
+    /**
+     * Discover API versions eagerly. Idempotent, and no longer required:
+     * requests discover on demand. Kept for callers that want the network
+     * failure up front rather than on the first tool call.
      */
     initialize(): Promise<void>;
     /**
      * Get discovered API versions.
-     * @throws Error if initialize() hasn't been called yet
+     * @throws Error if no request has discovered them yet
      */
     get apiVersions(): ApiVersions;
+    /**
+     * Substitute the discovered versions into a path built by lp(), le(), or
+     * leGlobal(), discovering them first if no request has yet.
+     *
+     * A path that carries no placeholder is returned untouched and costs
+     * nothing: a bookmark page whose URL came back fully resolved from D2L
+     * does not trigger a discovery of its own.
+     */
+    private resolvePath;
     /**
      * Make a GET request to the D2L API.
      *
@@ -61,6 +82,8 @@ export declare class D2LApiClient {
      * @throws NetworkError on network/fetch failures
      */
     getRaw(path: string): Promise<Response>;
+    /** One HTTP refresh and at most one browser login per caller. */
+    private withAuthentication;
     /** One rate limiter token per attempt. */
     private throttled;
     /** Retry 429, 5xx, and network failures. A 401 is never retried here. */
@@ -71,11 +94,11 @@ export declare class D2LApiClient {
      */
     private tryAutoReauth;
     /**
-     * Internal method to make HTTP request with 401 retry logic.
+     * Make one HTTP request. Authentication recovery is shared with raw downloads.
      */
     private makeRequest;
     /**
-     * Internal method to make HTTP request for raw binary data with 401 retry logic.
+     * Make one HTTP request for raw binary data.
      */
     private makeRawRequest;
     /**
@@ -85,21 +108,25 @@ export declare class D2LApiClient {
     private buildAuthHeaders;
     /**
      * Build path for LP (Learning Platform) API endpoints.
+     *
+     * The version is left as a placeholder and substituted by get() or getRaw()
+     * once it has been discovered. See LP_VERSION above.
+     *
      * @param path - Path within LP API (e.g., "/users/whoami")
-     * @returns Full versioned path (e.g., "/d2l/api/lp/1.56/users/whoami")
+     * @returns Versioned path template (e.g., "/d2l/api/lp/{lp}/users/whoami")
      */
     lp(path: string): string;
     /**
      * Build path for LE (Learning Environment) API endpoints with orgUnitId.
      * @param orgUnitId - Organizational unit ID (course ID)
      * @param path - Path within LE API (e.g., "/content/root/")
-     * @returns Full versioned path (e.g., "/d2l/api/le/1.91/123456/content/root/")
+     * @returns Versioned path template (e.g., "/d2l/api/le/{le}/123456/content/root/")
      */
     le(orgUnitId: number, path: string): string;
     /**
      * Build path for global LE (Learning Environment) API endpoints without orgUnitId.
      * @param path - Path within LE API (e.g., "/enrollments/myenrollments/")
-     * @returns Full versioned path (e.g., "/d2l/api/le/1.91/enrollments/myenrollments/")
+     * @returns Versioned path template (e.g., "/d2l/api/le/{le}/enrollments/myenrollments/")
      */
     leGlobal(path: string): string;
     /**

package/build/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAwB,MAAM,YAAY,CAAC;AAezF;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAA4B;gBAEhC,OAAO,EAAE,mBAAmB;IAuCxC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAQjC;;;OAGG;IACH,IAAI,WAAW,IAAI,WAAW,CAO7B;IAED;;;;;;;;OAQG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BlE;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAsB7C,0CAA0C;YAC5B,SAAS;IAKvB,yEAAyE;IACzE,OAAO,CAAC,QAAQ;IAQhB;;;OAGG;YACW,aAAa;IAgB3B;;OAEG;YACW,WAAW;IAyHzB;;OAEG;YACW,cAAc;IAuH5B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;OAIG;IACH,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAKxB;;;;;OAKG;IACH,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAK3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK9B;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAwB,MAAM,YAAY,CAAC;AAsDzF;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAA4B;IAC5C,gFAAgF;IAChF,OAAO,CAAC,gBAAgB,CAAqC;gBAEjD,OAAO,EAAE,mBAAmB;IAuCxC;;;;;;;OAOG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAsB5C;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;OAGG;IACH,IAAI,WAAW,IAAI,WAAW,CAO7B;IAED;;;;;;;OAOG;YACW,WAAW;IAMzB;;;;;;;;OAQG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBlE;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAK7C,iEAAiE;YACnD,kBAAkB;IA+BhC,0CAA0C;YAC5B,SAAS;IAKvB,yEAAyE;IACzE,OAAO,CAAC,QAAQ;IAQhB;;;OAGG;YACW,aAAa;IAgB3B;;OAEG;YACW,WAAW;IAuFzB;;OAEG;YACW,cAAc;IA2F5B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;;OAQG;IACH,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAIxB;;;;;OAKG;IACH,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;IAI3C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9B;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}