Brightspace MCP Server

Instructions

Implementation Reference

• src/index.ts:96-151 (handler)

  Complete implementation of the check_auth tool handler. This async function checks authentication status by: 1) Getting current token from TokenManager, 2) Attempting auto-reauthentication via AuthRunner if no valid token exists, 3) Returning appropriate status messages with token expiry time and source, 4) Optionally appending update notices. The tool is registered with server.registerTool() at line 96.
  server.registerTool( "check_auth", { title: "Check Authentication Status", description: "Check if you are authenticated with Brightspace. " + "Run the brightspace-auth CLI first to authenticate. " + "Use this when the user asks if they're logged in, if authentication is working, " + "or when other tools return auth errors.", }, async () => { log("DEBUG", "check_auth tool called"); let token = await tokenManager.getToken(); if (!token) { log("INFO", "check_auth: No valid token, attempting auto-reauthentication..."); const success = await authRunner.run(); if (success) { token = await tokenManager.getToken(); } if (!token) { log("INFO", "check_auth: Auto-reauthentication failed or produced no valid token"); const content: Array<{ type: "text"; text: string }> = [ { type: "text", text: "Not authenticated. Auto-reauthentication was attempted but failed. " + "Please run `brightspace-auth` manually in your terminal to log in. " + "Make sure your credentials in .env are correct and your internet connection is stable.", }, ]; const notice = getUpdateNotice(); if (notice) content.push({ type: "text", text: notice }); return { content }; } log("INFO", "check_auth: Auto-reauthentication succeeded"); } const expiresIn = Math.round((token.expiresAt - Date.now()) / 1000 / 60); log("INFO", `check_auth: Token valid, expires in ~${expiresIn} minutes`); const content: Array<{ type: "text"; text: string }> = [ { type: "text", text: `Authenticated with Brightspace. Token expires in ~${expiresIn} minutes. Source: ${token.source}.`, }, ]; const notice = getUpdateNotice(); if (notice) content.push({ type: "text", text: notice }); return { content }; } );
• src/types/index.ts:8-13 (schema)

  TokenData schema definition used by check_auth handler. Defines the structure of authentication tokens including accessToken, capture timestamp, expiry timestamp, and source (browser or cache). This schema is used to validate and manage tokens returned by TokenManager.
  export interface TokenData { accessToken: string; capturedAt: number; // Unix timestamp ms expiresAt: number; // Unix timestamp ms source: "browser" | "cache"; }
• src/utils/update-checker.ts:36-40 (helper)

  getUpdateNotice() helper function used by check_auth to append update notifications to responses. This function retrieves and clears a one-time notice about available Git updates, which gets added to the first check_auth response.
  export function getUpdateNotice(): string | null { const result = notice; notice = null; return result; }
• src/auth/token-manager.ts:34-51 (helper)

  TokenManager.getToken() helper method used by check_auth to retrieve current authentication tokens. Implements in-memory caching with disk persistence fallback and validity checking (including refresh buffer to prevent using near-expiry tokens).
  async getToken(): Promise<TokenData | null> { // Check memory cache first if (this.cachedToken && this.isValid(this.cachedToken)) { log("DEBUG", "Returning cached token"); return this.cachedToken; } // Try loading from disk const storedToken = await this.sessionStore.load(); if (storedToken && this.isValid(storedToken)) { log("DEBUG", "Loaded valid token from session store"); this.cachedToken = storedToken; return storedToken; } log("DEBUG", "No valid token available"); return null; }