Skip to main content
Glama
README.md
# unw-mcp

Read-only, token-efficient MCP server for the **University of Northwestern – St. Paul**
student portal (`my.unw.edu`). It signs in through the portal's SAML/Entra flow using a
persistent Chromium profile, then projects portal and Banner data into compact JSON for an
assistant.

> **Status: phase 3 / first release** — session, dashboard, academics, finances, dining,
> academic calendar and page search. Read-only.

## ⚠️ Unofficial — use at your own risk

This is an **unofficial personal project**. It is **not affiliated with, endorsed by, or
supported by** University of Northwestern – St. Paul, Pathify, Ellucian, Microsoft, or Bon
Appétit. Use **your own account**, comply with every applicable term and policy (automation
may violate them), and verify anything that matters against the official portal. There is no
warranty and no liability for account lockout, data loss, policy/FERPA problems, or decisions
made from the data. No credentials or PII are included in this repository — your local
credentials and profile are yours to protect.

Read [`DISCLAIMER.md`](DISCLAIMER.md) before running anything. Licensed under the
[MIT License](LICENSE).

## Surface

| Tool | Ops | Backing endpoints | Cache | Returns |
|---|---|---|---|---|
| `unw_session` | `status`, `reauth` | `GET /api/v1/users/me/` probe; dashboard navigation for SAML | — | authenticated flag, auth method, cookie lifetimes (no values) |
| `unw_dashboard` | `overview` | profile + notices + tasks + today's events | 2–10 min | identity, degree progress, advisors, 3 notices, 5 pending tasks, today's events |
| | `day` | today's classes + next-24h events + tasks + notices + next meal | 2–10 min (reuses caches) | plan-my-day: 8 classes, 8 de-duplicated events (`duplicate_count`), 5 tasks, 2 notices, one meal with 6×8 options |
| | `announcements` | `GET /api/v1/notices/?notice_type=Emergency&notice_type=Alert&status=NO_STATUS&status=APPROVED&scheduled=false&expired=false&dismissed=false&limit=N&offset=0` | 2 min | title, type, preview, dates, ack flag |
| | `tasks` | `GET flow.my.unw.edu/pathify-api/v1/users/me/tasks/` | 2 min | title, preview, due, required/complete, link |
| | `events` | `GET /api/v2/events/?current=true&limit=N&field=id&field=title&field=start_date&field=end_date&field=all_day&field=location&field=calendar` | 5 min | title, start/end, local time, all-day, location, calendar |
| | `quick_links` | `GET /api/v1/dashboard/quick-link-cards/?active=true` | 10 min | card title + label/url pairs |
| `unw_academics` | `profile` | `GET /api/v1/users/me/` + `GET flow…/pathify-api/v1/users/me/?field=…` | 10 min | name, e-mail, role, GPA, degree progress, advisors, hold |
| | `today` | `GET registration-ss…/registrationHistory/reset?term=<current>` | 10 min | today's classes with local times and rooms |
| | `schedule` | same, requested/current term | 10 min | course, CRN, title, credits, instructors, meetings (days/times/room/dates) |
| | `grades` | same history endpoint for recent completed terms | 30 min | graded courses per term, credits |
| | `gpa` | `GET student-ss…/studentProfile/viewGPAHoursList?studentId=…` | 30 min | overall GPA/hours plus per-level rows |
| | `holds` | `GET student-ss…/studentHolds/showHolds?studentId=…` | 5 min | description, type, dates, releasable, amount owed |
| | `registration` | `GET student-ss…/studentProfile/viewRegistrationNotices?studentId=…` | 5 min | standing, allowsRegistration, status, time-ticket state |
| | `degree_audit` | `GET /api/v1/widgets/?shown=true` claims → `GET flow…/upstream/v1/degree-audit/degreeworks?claims=…` | none (claims 300 s) | degree/major/minor names, percent, credits, GPA, requirements; `requirements_available` is false when upstream has no requirement array |
| `unw_finances` | `balances` | `GET flow…/upstream/v1/balances` | 5 min | Student Account and Dining Funds amounts |
| | `financial_aid` | `GET student-ss…/applicantActiveAidYears/…` → `getAwardInfo`, `getCostOfAttendance` | 60 min | aid year, award rows, per-period totals, cost rows and total |
| | `chapel` | `GET flow…/upstream/chapel_summary` | 15 min | credits earned/required, remaining, percent, period |
| `unw_dining` | `locations` | `GET flow.my.unw.edu/upstream/v2/bonappetit` (public, ~1.8 MB) | 60 min | cafe name, address, plain-text hours/message |
| | `today` | same projected dataset | 60 min | requested date's cafes → dayparts → stations → item labels; `detail:"brief"` (default, 6×8) or `"full"`; `meal` filter |
| | `week` | same | 60 min | 7 rolling dates, daypart item/station counts and samples; `meal` filter |
| `unw_calendar` | `academic` | public Google ICS discovered from `unwsp.edu/academics/academic-calendar/` | 6 h | upcoming semester/break/deadline dates |
| | `breaks` | same | 6 h | recess/holiday/no-classes rows |
| | `deadlines` | same | 6 h | add/drop, withdraw, registration and other deadlines |
| | `events` | `GET /api/v2/events/?current=true&limit=N&field=…` | 5 min | campus events filtered to the local-date window |
| `unw_pages` | `search` | `GET /api/v1/pages/?search=<q>&limit=N` | 10 min | ranked slug/title/category/excerpt; exact title/slug first; `count` + `truncated`; `excerpt_chars` (default 120, max 400) |
| | `get` | `GET /api/v1/pages/slug/<slug>/` | 24 h | plain-text body (4,000-char cap), body_chars, body_truncated |

Output rules enforced in code: 5–12 fields per row, HTML stripped, ISO **and**
`America/Chicago` local times, nulls omitted, lists capped, no raw Pathify/Banner
envelopes. The portal's event `count` is global, so events are filtered client-side to the
requested local-date window (`days`, default 7; `0` = today).

Arguments are shared per tool to keep schema tokens low:

```
unw_session   { op }
unw_dashboard { op, limit?, days?, include_completed? }  # op=day takes no extra args
unw_academics { op, term? }      # term: Banner code (202610) or name (Fall 2026)
unw_finances  { op, aid_year? }  # aid_year: code (2627) or label (2026-2027)
unw_dining    { op, date?, cafe?, meal?, detail? }  # detail defaults to brief
unw_calendar  { op, days?, limit?, query? }  # query filters academic/breaks/deadlines titles
unw_pages     { op, query?, slug?, limit?, excerpt_chars? }
```

## Install (no clone)

Requirements: Node >= 22 and Playwright Chromium (`npx playwright install chromium`); a Linux
desktop/Xvfb only if you set `headless: false`.

Point your MCP client at the GitHub repository directly — npm fetches the source, installs
devDependencies, runs `prepare` (`npm run build`) and links the `unw-mcp` binary. No clone, no
local build:

```json
{
  "mcpServers": {
    "unw": {
      "command": "npx",
      "args": ["-y", "github:HenryGetz/unw-mcp"],
      "env": { "UNW_MCP_TIMEZONE": "America/Chicago", "UNW_MCP_HEADLESS": "1" }
    }
  }
}
```

Other installs:

```bash
npx -y github:HenryGetz/unw-mcp          # run once (stdio; the client normally spawns it)
npm pack github:HenryGetz/unw-mcp        # builds dist/ inside the tarball
npm install -g ./unw-mcp-0.1.0.tgz       # global `unw-mcp` command
```

Use the tarball form for a global install: `npm install -g github:HenryGetz/unw-mcp` is
unreliable because npm ≥ 11 runs the git checkout's build with the global install's flags
inherited, so the build fails inside the checkout (`npm error git dep preparation failed`).
That is an npm limitation, not a problem with the tarball or `npx` path.

Or let [`add-mcp`](https://www.npmjs.com/package/add-mcp) write the client config for you
(`claude-code`, `claude-desktop`, `cursor`, `vscode`, `opencode`, `codex`, `zed`, `windsurf`):

```bash
npx -y add-mcp github:HenryGetz/unw-mcp -a cursor -n unw \
  --env UNW_MCP_TIMEZONE=America/Chicago -y
```

The **first run downloads the source, builds `dist/`, installs dependencies (~60–90 s with a
cold npm cache), then launches Chromium and completes the SAML/Entra handshake — expect ~90 s
cold** on an empty profile. Warm starts answer `unw_session op=status` in about a second.
Playwright's Chromium binary is not bundled: on a clean machine run
`npx playwright install chromium` once. `npx` caches the resolved commit, so after new commits
clear it (`npm cache clean --force`) to pick them up.

## Install from source (for development)

```bash
npm install          # runs `prepare` → builds dist/
npm run smoke        # tools/list over stdio, no browser
npm run live-proof   # session + all dashboard/academic/finance ops, read-only
```

Register the local checkout (see `mcp.example.json`):

```json
{
  "mcpServers": {
    "unw": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/unw-mcp",
      "env": { "UNW_MCP_TIMEZONE": "America/Chicago", "UNW_MCP_HEADLESS": "1" }
    }
  }
}
```

## Authentication

The portal is a Pathify/Angular app behind **SAML 2.0** with **Microsoft Entra ID**
(tenant `<tenant-id>`). There is no API key and no portal bearer token.

- Persistent profile: `~/.config/unw-mcp/browser-profile` (mode `0700`).
- Credentials (only needed when Entra itself expires):
  `~/.config/unw-mcp/credentials.json` (mode `0600`), falling back to
  `~/.config/teams-mcp/credentials.json`. Shape: `{ "username", "password", "totpSecret" }`
  (`totp_secret` is accepted too). Secrets are never copied into this repository.
- Warm profile: `status` and portal calls reuse the `sessionid` cookie (30 days, fixed).
- On `401`/`403`, a redirect to sign-in, or HTML where JSON was expected, the session
  reloads `/dashboard` once. Entra's `ESTSAUTHPERSISTENT` cookie usually makes this a silent
  SAML round trip (~7–11 s). If that fails, the server clears only `.my.unw.edu` cookies and
  retries once, then falls back to e-mail + password + TOTP. A rejected password is never
  retried (lockout protection).
- All browser work is serialized through one mutex; a cross-process profile lock prevents
  two MCP instances from sharing the Chromium profile.
- Portal and Flow requests use `browserContext.request`. Banner origins
  (`registration-ss.oci.unw.edu`, `student-ss.oci.unw.edu`) use `page.evaluate(fetch)`,
  because each Banner app owns a separate SAML session.

**Banner per-app sessions.** Before a Banner read, the server probes the portal session,
navigates that app's `registerPostSignIn` / `studentProfile` entry, and if the app returns a
login redirect or HTML it clears only that app's cookies and redoes the SAML handshake once.
A guest `JSESSIONID` cannot suppress the handshake because the retry clears it. A second
failure becomes `auth_required`. All Banner requests are GET-only.

**Degree audit.** The widget catalog carries a 300-second `claims` JWT. It is re-fetched
before every audit call, passed URL-encoded to Flow, retried once with fresh claims, and
never logged or cached.

## Startup and latency

The server does **not** launch Chromium at startup; the first authenticated tool call does.
On an isolated/cold profile the first call can take **~90 s** while the portal session and
Banner app sessions bootstrap. A warm persistent profile answers `unw_session status` in
about a second and dashboard/academic calls in 0.2–7 s. Call `unw_session op=status` first if
you want to pay the warm-up explicitly; subsequent questions in the same process reuse the
profile, portal session and in-memory caches.

## Configuration

Precedence: environment > `~/.config/unw-mcp/config.yaml` > defaults. See
`config.example.yaml` and `.env.example`.

| Setting | Default | Notes |
|---|---|---|
| `timezone` | `America/Chicago` | all rendering, event windows, today's classes |
| `headless` | `true` | `false` needs a display/xvfb |
| `cache.dashboard_ttl_minutes` | 5 | overview |
| `cache.announcements_ttl_minutes` / `tasks` | 2 | personalized lists |
| `cache.events_ttl_minutes` | 5 | portal events |
| `cache.quick_links_ttl_minutes` | 10 | dashboard links |
| `cache.profile_ttl_minutes` | 10 | portal + Flow profile |
| `cache.schedule_ttl_minutes` | 10 | terms and registration history |
| `cache.grades_ttl_minutes` | 30 | graded-term aggregation |
| `cache.gpa_ttl_minutes` | 30 | Banner GPA/hours |
| `cache.holds_ttl_minutes` / `registration_ttl_minutes` | 5 | Banner student data |
| `cache.terms_ttl_minutes` | 60 | Banner term list |
| `cache.balances_ttl_minutes` | 5 | Flow balances |
| `cache.chapel_ttl_minutes` | 15 | chapel summary |
| `cache.financial_aid_ttl_minutes` | 60 | award + cost bundle |
| `cache.dining_ttl_minutes` | 60 | projected 7-day dining dataset |
| `cache.academic_calendar_ttl_minutes` | 360 | discovered ICS feeds |
| `cache.page_search_ttl_minutes` / `pages_ttl_minutes` | 10 / 1440 | search rows / page bodies |
| `max_results.*` | 5–20 rows, 300 preview chars, 25 full-dining items/station, 12 full stations, 4,000 page chars | per-call caps; dining brief is fixed at 6 stations × 8 items |
| `limits.event_fetch_limit` / `event_window_days` | 60 / 7 | client-side event filter |

Environment overrides: `UNW_MCP_CONFIG_DIR`, `UNW_MCP_PROFILE_DIR`, `UNW_MCP_TIMEZONE`,
`UNW_MCP_HEADLESS`, `UNW_MCP_REQUEST_TIMEOUT_MS`, `UNW_MCP_NAVIGATION_TIMEOUT_MS`,
`UNW_MCP_REAUTH_TIMEOUT_MS`, and per-cache `UNW_MCP_*_TTL_MINUTES` (see `.env.example`).

## Token efficiency

- Every list request passes an upstream `limit`; projections drop internal flags and
  redundant fields.
- In-process TTL cache with single-flight loading. Concurrent tool calls do not duplicate
  requests.
- Observed live sizes: dashboard overview 4.3 KB, dashboard day 5.0 KB, announcements
  0.37 KB, tasks 1.2 KB, events (10 rows) 2.5 KB, quick links 1.1 KB, academic profile
  0.24 KB, today 0.6 KB, schedule 1.7 KB, grades 1.1 KB, GPA 0.3 KB, holds 0.2 KB,
  registration 0.25 KB, degree audit 1.1 KB, balances 0.12 KB, chapel 0.18 KB, financial
  aid 5.7 KB, dining locations 1.2 KB, dining today brief 3.4 KB / full 7.0 KB / one meal
  1.1 KB, dining week 5.8 KB, academic calendar 1.1 KB, breaks 1.2 KB, deadlines 1.1 KB,
  page search (10) 2.6 KB, page body 0.55 KB, calendar breaks filtered by query 0.45 KB.
- Financial aid and a full dining day are the largest payloads (22 awards + 22 cost rows;
  ~300 item labels). Both are explicitly capped and never include internal upstream fields.
- The dining endpoint is ~1.8 MB; only the projected dataset is cached, and only the
  requested date/cafe leaves the server. The raw payload is never returned.

## Verification

Measured in this repository on 2026-11-17:

| Command | Result |
|---|---|
| `npm run typecheck` | clean (strict TypeScript, `noUncheckedIndexedAccess`) |
| `npm test` | **137 tests / 14 files** pass |
| `npm run build` | clean `dist/` |
| `npm run smoke` | 7 tools; all op enums listed; missing/unknown op rejected |
| `npm run live-proof` | all seven tools returned live data: session, dashboard, day (3 classes/8 de-duplicated events/3 tasks/1 notice/next meal, 5.0 KB), profile, today, schedule, grades, GPA, holds (1), registration, degree audit (5 degrees; 1/5 has requirement detail), balances (2), chapel (8/20), financial aid (22 awards/22 cost rows), dining brief 3.4 KB vs full 7.0 KB vs one meal 1.1 KB, 7-day week, academic/breaks/deadlines rows, Thanksgiving-filtered breaks (445 B), campus events (10 rows), page search (56 hits, top 10, 2.6 KB), page get |

Unit coverage: config precedence/validation, redaction, sign-in classification, response
classification (401 vs SAML HTML vs 5xx vs 302), session status, Banner page fetch plus
one-shot re-handshake, TTL/single-flight cache, dashboard projections, Banner term/schedule/
today/grades/GPA/holds/registration projections, degree-audit projection and claims
refresh, balance/chapel/aid projections and loaders, dining dataset/day/week/locations
projection, brief/full detail, meal filtering and caps, day assembly and next-meal selection,
ICS discovery/parsing/cohort merging and date filtering, page HTML→text search/ranking/get,
tool schemas and error mapping.

Live proof prints counts, field names and timings only; no names, e-mail addresses, IDs or
balances are written to the repository. Live proof is read-only.

## Known limitations / not exposed

- **Time ticket text**: `viewRegistrationNotices` returns an empty `timeTickets` array for
  this account. The time ticket lives only in the `prepareRegistration` HTML after a
  term-selection POST; this server does not issue that POST, so `time_ticket_source` is
  `not_exposed` and standing/allowsRegistration are still returned.
- **Housing assignment/roommates**: no endpoint exists in the portal.
- **Meal-plan swipe counts**: only the Dining Funds balance exists.
- **Degree requirements**: Flow returns requirement rows only on the degree record;
  majors/minors report completion percentages with `requirements_available: false` and
  `requirements_total: 0`. On the live account **4 of 5 programs** have no requirement
  detail; only the degree record does. This is an upstream limitation, not an inference of
  "complete".
- **Banner pre-registration holds**: the JSON `showHolds` endpoint is authoritative;
  registration-notice holds text is not parsed from HTML.
- **Dining**: the public payload covers 7 rolling days only; some cafes (e.g. Heritage) may
  publish no menu for a date. `today` reports `no_menu` per cafe rather than inventing items.
  Default `detail:"brief"` caps each station at 8 items and each daypart at 6 stations;
  `detail:"full"` uses the configured 12/25 caps. Use `meal` and `cafe` to scope further.
- **Academic calendar**: discovery depends on the public page embedding Google Calendars.
  If the layout changes, the tool returns `unavailable` instead of guessed dates. Cohort
  prefixes (`TRAD:`, `DE:`, `AGS:`) are merged into one row with `audiences`.
- **Pages**: search covers portal content pages only, not users/directory; results are
  ranked with exact title/slug matches first and carry `count`/`truncated`. Bodies are capped
  at 4,000 chars; `body_truncated`/`body_chars` say what was cut.

## Repository / CI

This repository is **public** ([MIT](LICENSE)). It contains no account data, credentials,
browser profiles or raw portal captures; `.gitignore` excludes `node_modules/`, `dist/`, `.env*`,
`config.yaml`, `credentials.json`, `browser-profile/`, `.recon/`, `artifacts/` and `*.tgz`.
Everything the server reads from `my.unw.edu` is **read-only** — the portal and Banner code
paths issue GETs only (registration is never posted).

`ci.yml` runs on pushes and pull requests with a read-only `GITHUB_TOKEN`, no secrets and no
network access to the portal:

1. `npm ci` — lockfile install; `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` because unit tests never
   launch Chromium
2. `npm run typecheck` — `tsc --noEmit` (strict)
3. `npm test` — `vitest run`, mocked HTTP, no browser or credentials
4. `npm run build` — clean `dist/`

Live checks are operator-only and never run in CI: `npm run smoke` (tools/list over stdio) and
`npm run live-proof` (requires a warm authenticated profile on the operator's machine).

## Layout

```
src/
  index.ts              stdio MCP entrypoint
  config.ts             YAML + env configuration
  cache.ts              in-memory TTL + single-flight cache
  format.ts, time.ts    projection and America/Chicago rendering helpers
  auth/
    browser.ts          persistent Chromium, SAML driver, portal-ready probe
    session.ts          mutex, portal re-auth, Banner per-app sessions
    credentials.ts      0600 credential discovery with teams-mcp fallback
    response.ts         auth vs availability classification
    redact.ts           log/URL/token redaction
    signin.ts           pure Entra page classifier
    lock.ts             cross-process profile lock
    totp.ts             RFC 6238
  banner/client.ts      per-app client; GET-only page fetches
  portal/
    client.ts           origin-locked portal/Flow reader
    values.ts           tolerant upstream accessors
    dashboard.ts        dashboard projections + loaders
    academics.ts        term/schedule/grades/GPA/holds/registration/audit
    finances.ts         balances, chapel, financial aid
    dining.ts           public menu dataset + day/week projections
    calendar.ts         ICS discovery/parsing + campus events
    pages.ts            page search and slug lookup
  tools/                registry, envelopes, four op-dispatched tools
scripts/recon/          reconnaissance behind docs/portal-recon.md
scripts/dev/            smoke and live proof
test/                   unit tests (no browser, mock HTTP)
docs/                   portal recon, design notes, usage examples
```

See `SECURITY.md` for the threat model and secret handling. See `docs/design.md` for the
projection/caching design and `docs/usage.md` for example conversations and payloads.

TDQS

A3.7/5.0

Scored across 7 tools

Disambiguation3/5

The core domains (session, academics, finances, dining, calendar, pages) are distinct, but unw_dashboard's 'day' view deliberately re-aggregates data that also lives in unw_academics (today's classes), unw_calendar (campus events), and unw_dining (next meal), so an agent asking about 'today' has several plausible entry points. Descriptions do explain the aggregator role, but the boundaries between dashboard and the domain tools remain blurry in practice.

Naming Consistency4/5

All seven tools use a uniform 'unw_' prefix followed by a single domain noun, which is predictable and readable. Minor deviation: plurality is inconsistent (academics/finances/pages are plural while session/dashboard/dining/calendar are singular), and the pattern is resource-oriented rather than verb_noun, so actions are only discoverable via descriptions.

Tool Count5/5

Seven tools is well within the sweet spot and each maps to a genuine portal area (auth, dashboard, academics, finances, dining, calendar, pages). No tool feels redundant as a standalone resource, and the surface is compact enough for an agent to hold in context.

Completeness4/5

The read-only lifecycle is well covered: authentication handling, academic records, balances, dining menus, calendar/deadlines, and content pages. Gaps exist for a student portal — no course/catalog search to support registration, no messages/inbox, and no task creation or completion despite dashboard surfacing pending tasks — but these are workable omissions for a read-only surface.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues