# nyu-brightspace-mcp

MCP server for NYU Brightspace (`brightspace.nyu.edu`). Read-only: deadlines, assignments, grades, announcements, course content.

A rewrite of `brightspace-mcp-server` (Purdue-oriented, Microsoft Entra SSO) for NYU's Shibboleth + Duo login and NYU course conventions.

## Setup

```sh
bun install
bun run build
node dist/index.js setup    # optional: NetID + password (macOS Keychain) for auto-fill
node dist/index.js login    # Chrome window: NetID + Duo, tick "trust this browser"
node dist/index.js status
```

Register with Claude Code:

```sh
claude mcp add -s user brightspace -- node /absolute/path/to/nyu-brightspace-mcp/dist/index.js
```

Login runs a real browser through `playwright-core`, trying in order: installed Google Chrome, Microsoft Edge, then Playwright's Chromium if already downloaded. Nothing is downloaded at install time, so `ignore-scripts=true` in `.npmrc` does not matter. With none of them installed, login fails with a hint to install Chrome or run `npx playwright install chromium`.

## Auth model

- `login` saves the full browser storage state (Brightspace, Shibboleth and Duo cookies) to `~/.nyu-brightspace-mcp/session.json` (mode 0600).
- API calls use the Brightspace session cookies directly.
- When the Brightspace session expires, the server silently re-runs the SSO flow in headless Chrome. It succeeds without Duo while the Shibboleth session or Duo "trusted browser" cookie is alive. It never waits on a Duo push in the background; if interaction is needed, the tool error tells the model to call `login`, which opens a visible window.
- With `setup`, the NetID password lives in the macOS Keychain (service `nyu-brightspace-mcp`) and is auto-filled on the Shibboleth page. Env vars `NYU_NETID` / `NYU_PASSWORD` also work.

## Tools

| Tool | What it does |
| --- | --- |
| `get_upcoming` | Deadlines across current courses from one calendar call, with submission/completion status, plus deadline sentences found in recent announcements (for Gradescope-only courses) |
| `list_courses` | Current-semester courses by default; parses `FA26_CSCI-UA_310_1_040` style codes |
| `get_assignments` / `get_assignment` | Dropbox folders, submission status, scores, feedback, instructions, attachments |
| `get_quizzes` | Quiz windows, time limits, attempts |
| `get_grades` | Released grade items with weights and the final grade |
| `get_announcements` | Newest first, as markdown |
| `get_content` / `search_content` | Module outline with topicIds, file types, external tools (Gradescope, Ed), links |
| `read_content` | Text from PDF (per page), DOCX, PPTX, HTML, ZIP (inlines code/tex), plain text |
| `download_file` | Saves a topic file or assignment attachment to `~/Downloads/brightspace/<course>/` |
| `get_discussions`, `get_classlist` | Brightspace forums; course staff |
| `auth_status`, `login` | Session check; interactive NetID + Duo |
| `api_get` | Raw GET on any Valence path (`/le/...`, `/lp/...`) |

Every `course` argument takes an org unit id or text: `cs310`, `CSCI-UA 480`, `algorithms`, `OS`, or a word from the course's module titles (`crypto`).

## Config

| Env var | Default |
| --- | --- |
| `NYU_BRIGHTSPACE_URL` | `https://brightspace.nyu.edu` |
| `NYU_BRIGHTSPACE_TZ` | `America/New_York` |
| `NYU_BRIGHTSPACE_HOME` | `~/.nyu-brightspace-mcp` |
| `NYU_BRIGHTSPACE_DOWNLOADS` | `~/Downloads/brightspace` |
| `NYU_BRIGHTSPACE_CHROME_CHANNEL` | unset: try `chrome`, `msedge`, `chromium`; set to pin one |

## License

MIT