brightspace-mcp

# brightspace-mcp

[![CI](https://github.com/JhostinAleck/brightspace-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/JhostinAleck/brightspace-mcp/actions/workflows/ci.yml)
[![Docs](https://github.com/JhostinAleck/brightspace-mcp/actions/workflows/docs.yml/badge.svg)](https://jhostinaleck.github.io/brightspace-mcp/)
[![npm version](https://img.shields.io/npm/v/brightspace-mcp.svg)](https://www.npmjs.com/package/brightspace-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![Node.js](https://img.shields.io/node/v/brightspace-mcp.svg)](./package.json)

📖 **[Full documentation site →](https://jhostinaleck.github.io/brightspace-mcp/)**

MCP server for D2L Brightspace. Gives Claude (and any MCP-compatible client) access to your courses, grades, assignments, content, calendar, and more — with multi-strategy authentication, full MFA support, and production-grade resilience built in.

---

## Quick start

```bash
npx brightspace-mcp@latest setup   # interactive wizard (recommended for first time)
```

The interactive wizard handles everything: base URL, auth strategy, MFA, credential storage, and auto-registration with Claude Desktop / Cursor / Windsurf.

For CI pipelines or DevContainers with no TTY, use the non-interactive `init` command instead:

```bash
npx brightspace-mcp@latest init \
  --base-url https://yourschool.brightspace.com \
  --strategy api_token \
  --token-ref env:BRIGHTSPACE_API_TOKEN
```

---

## Documentation

Deep-dive guides live in [`docs/`](./docs/) — start with [`docs/README.md`](./docs/README.md).

| Topic | Doc |
|---|---|
| Setup walkthrough | [`docs/setup-guide.md`](./docs/setup-guide.md) |
| Auth strategies | [`docs/auth-strategies.md`](./docs/auth-strategies.md) |
| Known-good presets (Microsoft AAD, etc.) | [`docs/presets.md`](./docs/presets.md) |
| Write operations (submit, post, mark) | [`docs/writes.md`](./docs/writes.md) |
| MCP tools reference | [`docs/tools.md`](./docs/tools.md) |
| MCP Resources + Prompts | [`docs/tools.md#mcp-resources`](./docs/tools.md#mcp-resources) |
| Troubleshooting | [`docs/troubleshooting.md`](./docs/troubleshooting.md) |
| Architecture (DDD) | [`docs/architecture.md`](./docs/architecture.md) |
| Register with MCP clients | [`docs/clients.md`](./docs/clients.md) |

For AI assistants and contributors, [`AGENTS.md`](./AGENTS.md) is a one-page map of the repo.

---

## Table of contents

- [Installation](#installation)
- [Authentication strategies](#authentication-strategies)
- [MFA strategies](#mfa-strategies)
- [Configuration reference](#configuration-reference)
- [Output: timezone and language](#output-timezone-and-language)
- [Redis cache](#redis-cache)
- [Write operations](#write-operations)
- [Available tools](#available-tools)
- [MCP Resources](#mcp-resources)
- [MCP Prompts](#mcp-prompts)
- [TUI dashboard](#tui-dashboard)
- [Register with an MCP client](#register-with-an-mcp-client)
- [CLI reference](#cli-reference)
- [Docker](#docker)

---

## Installation

### npx (recommended — no install needed)

```bash
npx brightspace-mcp@latest setup   # first-time wizard
npx brightspace-mcp@latest serve   # run the server
```

### Global install

```bash
npm install -g brightspace-mcp
brightspace-mcp setup
brightspace-mcp serve
```

### From source

```bash
git clone https://github.com/JhostinAleck/brightspace-mcp.git
cd brightspace-mcp
npm install && npm run build
node build/cli/main.js serve
```

**Requirements**: Node.js ≥ 20.

### Staying up to date

- **npx (recommended)** — the MCP client config written by `setup` runs `npx --yes brightspace-mcp@latest serve`, so every client restart picks up the newest release. Nothing else to do.
- **Global install** — run `brightspace-mcp upgrade`.
- **Docker** — `docker pull` the latest image and recreate the container.

The server checks npm at most once a day (3 s timeout, cached in `~/.brightspace-mcp/update-check.json`). When a newer version exists — or when your installed version has been **deprecated** because of a security fix — the notice is appended to the first tool response of the session, so your assistant tells you about it. It also shows up under `update` in `get_diagnostics`. Set `BRIGHTSPACE_NO_UPDATE_CHECK=1` to opt out.

---

## Authentication strategies

Pick the strategy that matches your Brightspace setup. Run `npx brightspace-mcp@latest setup` and it will walk you through the right one.

### API Token (simplest)

Requires a Valence API token from your Brightspace admin panel.

```yaml
profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: api_token
      api_token:
        token_ref: env:BRIGHTSPACE_API_TOKEN
```

```bash
export BRIGHTSPACE_API_TOKEN="your-token"
npx brightspace-mcp@latest serve
```

### Headless (username + password)

Automates HTTP-level login — no browser window. Supports all MFA strategies including **Duo Push**.

```yaml
profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: headless
      headless:
        login_url: https://school.brightspace.com/d2l/login
        username_ref: env:BRIGHTSPACE_USERNAME
        password_ref: env:BRIGHTSPACE_PASSWORD
        mfa:
          strategy: duo_push     # or: totp, manual_prompt, none
          duo_push: {}           # uses defaults: poll every 1s, timeout 120s
```

### Browser (Playwright)

Launches a headless Chromium instance and automates the login UI. Best for SSO flows (Microsoft Azure AD, SAML) where the login page has complex JavaScript.

```bash
npm install playwright && npx playwright install chromium
```

```yaml
auth:
  strategy: browser
  browser:
    login_url: https://school.brightspace.com/d2l/login
    headless: true
    username_ref: env:BRIGHTSPACE_USERNAME
    password_ref: env:BRIGHTSPACE_PASSWORD
    selectors:
      username: "#i0116"
      password: "#i0118"
      submit: "#idSIButton9"
      password_submit: "#idSIButton9"
      mfa_input: "#idTxtBx_SAOTCC_OTC"
      mfa_submit: "#idSubmit_SAOTCC_Continue"
      post_login: "d2l-labs-navigation"
    mfa:
      strategy: totp
      totp:
        secret_ref: env:BRIGHTSPACE_TOTP_SECRET
```

The setup wizard includes a **Microsoft SSO preset** that fills all selectors automatically.

### Session Cookie

Paste the D2L session cookies from your browser's DevTools. Useful when other strategies are blocked.

```yaml
auth:
  strategy: session_cookie
  session_cookie:
    cookie_ref: env:BRIGHTSPACE_COOKIE
    session_ttl_seconds: 3600
```

```bash
# Cookie format: "d2lSessionVal=XXX; d2lSecureSessionVal=YYY"
export BRIGHTSPACE_COOKIE="d2lSessionVal=...; d2lSecureSessionVal=..."
```

---

## MFA strategies

| Strategy | When to use |
|---|---|
| `none` | No MFA on your account |
| `totp` | Authenticator app (Google Authenticator, Authy, etc.) |
| `duo_push` | Duo Security — server polls for mobile approval automatically |
| `manual_prompt` | Any TOTP/OTP — server pauses and asks you to paste the code |

### TOTP example

```yaml
mfa:
  strategy: totp
  totp:
    secret_ref: env:BRIGHTSPACE_TOTP_SECRET   # base32 secret from QR code setup
    digits: 6       # 6 or 8
    period: 30      # seconds
    algorithm: SHA1 # SHA1, SHA256, or SHA512
```

### Duo Push example

```yaml
mfa:
  strategy: duo_push
  duo_push:
    poll_interval_ms: 1000   # how often to check (default: 1000)
    timeout_ms: 120000       # give up after this many ms (default: 120000)
```

---

## Configuration reference

Full config file (`~/.brightspace-mcp/config.yaml`):

```yaml
default_profile: my_school

profiles:
  my_school:
    base_url: https://school.brightspace.com
    auth:
      strategy: api_token          # api_token | browser | headless | session_cookie | oauth
      api_token:
        token_ref: env:BRIGHTSPACE_API_TOKEN
    session:
      cache_backend: memory        # memory | file | redis
      preemptive_refresh_seconds: 300

output:
  tz: America/Bogota               # IANA timezone; default: auto-detected from system
  locale: es-419                   # en-US | es-419 | pt-BR | fr-CA; default: auto-detected
  format: markdown                 # markdown (default) | plain
  include_meta_footer: true

logging:
  level: info                      # debug | info | warn | error

writes:
  enabled: false
  dry_run: false

# Optional — required when session.cache_backend: redis
redis:
  url: redis://localhost:6379
  key_prefix: "brightspace:"
```

### Credential references

Secret values are never stored in plain text. Use `ref:` notation to point to the actual value:

| Prefix | Example | Description |
|---|---|---|
| `env:NAME` | `env:BRIGHTSPACE_API_TOKEN` | Read from environment variable |
| `keychain:service/account` | `keychain:brightspace-mcp/token` | OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) |
| `file:label` | `file:api_token` | Encrypted file (`~/.brightspace-mcp/credentials.enc`, AES-256-GCM) |

---

## Output: timezone and language

All tool responses are formatted in your configured timezone and language.

```yaml
output:
  tz: America/Bogota       # IANA name; default: auto-detected from system
  locale: es-419           # en-US | es-419 | pt-BR | fr-CA; default: auto-detected
  format: markdown         # markdown (default) | plain
  include_meta_footer: true
```

Run `brightspace-mcp setup` and choose your timezone and language. Or set it in `~/.brightspace-mcp/config.yaml`.

---

## Redis cache

When running multiple instances or want cache persistence across restarts, enable Redis:

**1. Add the `redis` section to config:**

```yaml
redis:
  url: redis://localhost:6379
  key_prefix: "brightspace:"

profiles:
  my_school:
    session:
      cache_backend: redis
```

**2. Install ioredis (optional dependency):**

```bash
npm install ioredis
```

**3. Start Redis and the server:**

```bash
docker run -d -p 6379:6379 redis:7-alpine
npx brightspace-mcp@latest serve
```

The domain cache (courses, grades, assignments