Check Authentication Status

Instructions

Implementation Reference

• src/index.ts:120-164 (handler)

  The handler function for the check_auth tool. Checks if a valid token exists via TokenManager. If none, attempts auto-reauthentication via AuthRunner. Returns success/failure status with expiry details.

  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/index.ts:112-119 (schema)

  The tool registration metadata/schema: title and description for the check_auth tool. No input schema since it's a zero-argument tool.

  {
    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.",
  },

• src/index.ts:110-165 (registration)

  Registration of the check_auth tool on the MCP server using server.registerTool(). Registers the tool name, description metadata, and the async handler function.

  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/auth/token-manager.ts:34-51 (helper)

  TokenManager.getToken() helper used by check_auth to retrieve cached or stored tokens. Returns null if no valid token exists (expired or within refresh buffer).

  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;
  }

• src/auth/auth-runner.ts:26-77 (helper)

  AuthRunner helper that launches the brightspace-auth CLI as a child process for automatic reauthentication when the token is missing or expired.

  export class AuthRunner {
    private running = false;
    private readonly scriptPath: string;
    private readonly projectRoot: string;
  
    constructor() {
      // Resolve paths relative to this file's compiled location (build/auth/auth-runner.js)
      const thisDir = path.dirname(fileURLToPath(import.meta.url));
      this.scriptPath = path.resolve(thisDir, "..", "auth-cli.js");
      this.projectRoot = path.resolve(thisDir, "..", "..");
    }
  
    /**
     * Spawn the auth CLI and wait for it to complete.
     * Returns true if authentication succeeded, false otherwise.
     * Prevents concurrent auth attempts via a simple mutex.
     */
    async run(): Promise<boolean> {
      if (this.running) {
        log("DEBUG", "Auth already running, skipping duplicate attempt");
        return false;
      }
  
      this.running = true;
      try {
        log("INFO", "Auto-launching brightspace-auth...");
  
        return await new Promise<boolean>((resolve) => {
          execFile(
            process.execPath, // use the same Node binary
            [this.scriptPath],
            {
              timeout: AUTH_TIMEOUT_MS,
              cwd: this.projectRoot,
              env: { ...process.env },
            },
            (error, _stdout, _stderr) => {
              if (error) {
                log("ERROR", "Auto-auth process failed", error.message);
                resolve(false);
              } else {
                log("INFO", "Auto-auth completed successfully");
                resolve(true);
              }
            },
          );
        });
      } finally {
        this.running = false;
      }
    }
  }