Skip to main content
Glama
README.md
# UBC MCP

UBC course discovery and registration planning as a standalone MCP server that
works with any standard MCP client. No hosting platform, account service or
hardcoded server address is required. Independent project; not affiliated with
UBC or Workday.

## Current alpha

The public profile provides seven read-only tools over the official UBC Academic
Calendar and UBCGrades. Vancouver and Okanagan catalog reads and a historical
grade-distribution request have passed live checks.

The personal profile adds four tools over a user's isolated Workday snapshots.
The snapshot connector, encryption, credential separation and revocation have
automated integration coverage. The browser extension can automatically synchronize registrations in a short-lived background Workday tab after the user grants access. It also synchronizes recognized course-search pages while they are open; it does not fetch the full catalog. An installed-browser
registration export passed a real local connector/MCP acceptance run. Hosted self-service connection and registration synchronization have also been exercised with a real browser session. Course-search export acceptance remains outstanding.

Workday UI fields were inspected in an authenticated browser on 2026-10-26.
This is evidence of field availability, not evidence of a public Workday API or
an unattended production integration. See [validation](docs/VALIDATION.md).

## Run locally

Requires Node.js 24 or newer.

```sh
npm ci
npm run build
npm start
```

The default transport is stdio. stdout is reserved for MCP protocol messages.
`node dist/cli.js --list-tools` lists the public tools. Public mode reads no
personal environment credentials and cannot expose personal tools.

Configure an MCP client with `node` as the command and the absolute path to
`dist/cli.js` as its argument. No public-source API key is required. For
example, in a client that uses the common `mcpServers` JSON format:

```json
{"mcpServers":{"ubc":{"command":"node","args":["/absolute/path/to/dist/cli.js"]}}}
```

A stdio container image (`Dockerfile`, published by the `MCP server image`
workflow as `ghcr.io/kkazuhak/ubc-mcp` once a release is tagged) runs with
`docker run -i --rm`.
`node dist/cli.js --version` prints the package version, which is read from
`package.json` (a single source also used by the connector's `/healthz`).

## Tools

| Public | Purpose |
| --- | --- |
| `get_data_status` | Source capabilities, connection state, captured scopes and ages |
| `list_subjects` | Official Calendar subjects for one campus |
| `search_courses` | Search one subject's catalog entries |
| `get_course` | Full description and prerequisite/corequisite text |
| `list_grade_sessions` | Available historical sessions for API v2 or v3 |
| `get_course_grades` | Course and section grade distributions |
| `compare_courses` | Up to five catalog/grade comparisons |

| Personal | Purpose |
| --- | --- |
| `search_sections` | Search captured sections in one exact campus and period |
| `get_section_availability` | Source status, counts, seat pools and observation time |
| `get_my_schedule` | Captured personal registrations, if supplied |
| `check_schedule` | Meeting/date overlaps and available component constraints |

Campus defaults to `UBCV`; pass `UBCO` explicitly for Okanagan. Course arguments
use a subject such as `CPSC` and number such as `110`. Historical sessions use
`2026W`; availability queries require an exact `academicPeriod.id` returned by
`get_data_status`, for example `2026W-2`. Section searches and personal registrations
are stored as separate snapshot kinds; schedule checks can select either kind.
This prevents confusing Winter Term 2
in January 2027 with the 2027 Winter Session.

## Connect a personal snapshot (local / administrative tools)

For local verification, set `UBC_PROFILE=personal` and `UBC_SNAPSHOT_FILE` to an
absolute private JSON file path. Never point a shared Hub service at an
individual's file.

For multi-user use, start the connector with `npm run connector`. It needs no
platform: `GET /healthz` returns `{"ok":true,"version":...}` and the bearer-token
snapshot API works with the CLI alone. It binds
loopback by default. Provision a binding using the local administrative CLI:

```sh
node dist/connector/cli.js create-binding student-label
```

This displays a random binding ID, read token and upload token once. Treat the
output as secret. The read token belongs in that user's Hub Credential slot;
the upload token stays with their local companion. Neither authorizes the other
operation. There is no public administrative HTTP endpoint.

Set `UBC_PROFILE=personal`, operator-controlled `UBC_CONNECTOR_URL` and the
user's `UBC_CONNECTOR_TOKEN` (READ token) in the personal process. Bindings never
come from tool arguments. Missing/revoked credentials never use a shared token.

The connector stores token hashes and AES-256-GCM-encrypted snapshot bodies in
SQLite. Preserve the complete data directory and its encryption key together.
The operator who controls the host and key can decrypt data. Restrict host access
and keep the directory and backups private. Source snapshots exported to the
user's Downloads folder are ordinary plaintext files and need private handling.

```sh
node dist/connector/cli.js revoke BINDING_ID
```

Revocation disables both tokens and removes active snapshots. Revoked data may
remain in historical backups; manage backup retention separately.

## Firefox status

Extension 0.2.3 prepares Firefox support and fixes startup stuck at Checking.
For a Firefox submission build, run npm run build:firefox. See
[signing preparation](docs/firefox-publishing.md) and
[privacy](docs/extension-privacy.md) ([中文](docs/extension-privacy.zh.md)). The ZIP is unsigned; Mozilla signing is
still required for persistent installation. Firefox connection/upload requires
connector alpha.4, which has not yet been deployed from this workstation.

## Capture Workday course data

```sh
npm run build:extension
```

For a private local acceptance run using an exported registration file:

```sh
node scripts/private-check.mjs /absolute/path/to/private-registrations.json
```

This starts a temporary loopback connector, checks personal MCP queries and
revocation, prints aggregate results, then removes the temporary encrypted store.
It does not upload the input file to the public Internet or delete the input file.

Releases published after this workflow was added carry the packaged builds (`ubc-course-capture-chrome-<version>.zip`, an unsigned Firefox zip, the source archive and checksums); see [extension release](docs/chrome-release.md). The extension has no built-in server address. Load the `extension/` folder as an unpacked Chrome extension, or build and load `extension-firefox/` for Firefox. Automatic synchronization requires user-granted host access to UBC Workday and the server address you enter (see the optional MCPHub section). Without a server, use the offline export and `push` flow below. It does not read passwords or cookies.
Log into Workday yourself and complete Duo. Navigate to **Find Course Sections**,
select a specific Winter Term (not the umbrella Winter Session), and search.
Refresh the results before capturing. Open a section detail dialog to include
unreserved/reserved seats, eligibility rules and all date intervals.

Click the extension's **Export course snapshot** button. It captures only DOM
records currently loaded. Coverage is always marked partial. A collapsed
`+N more` meeting list is treated as incomplete; missing meeting data is never
classified as asynchronous. The capture timestamp records the DOM observation,
not an upstream database refresh guarantee. Only the section detail currently
open gains complete meeting/seat-pool fields.

With `UBC_CONNECTOR_URL` and your `UBC_UPLOAD_TOKEN` configured in the local
environment, synchronize the saved file:

```sh
node dist/connector/cli.js push /absolute/path/to/ubc-snapshot.json
```

This explicitly uploads the structured course snapshot to your connector. It
does not upload the browser session, password, cookies or student profile. A push
replaces that binding's existing snapshot for the same campus and period; capture
all desired loaded records together. Older snapshots cannot replace newer ones.
On **View My Courses**, the separate **Export my registrations** action captures
the loaded Registered and Waitlisted rows, grouped into academic periods. It
discards student names/IDs and does not collect grades or financial details.
Keep that export private. The same push command accepts its snapshot array.
Registration snapshots do not replace section-search availability snapshots.
Registration snapshots are refreshed through a temporary background Workday tab; course-search snapshots cover recognized open pages only.

## Interpretation

- Catalog records do not establish current offerings. Full prerequisite text is
  preserved; there is no invented prerequisite tree or official degree audit.
- UBCGrades is historical. `OVERALL` is separate from sections to prevent double
  counting. The selected API version and session are returned with every report.
- Unknown counts remain `null`. Capacity minus enrollment is not substituted for
  unreserved availability. Workday detail fields identify the two seat pools.
- `openOnly` requires an observed Open status, a known positive unreserved/available
  count and an observation no older than five minutes. It does not prove eligibility.
- Source status is preserved separately from normalized status. Unknown states
  remain unknown. Stale snapshots remain inspectable with their original age.
- Schedule checks preserve multiple date intervals, including reading-break gaps.
  Unknown meeting patterns and component rules require manual verification.
  Final exams, travel time and personal eligibility are not inferred.
- Tool text is fenced as untrusted source data. No registration/write tools exist.

## Deploy and validate

Keep the public profile lightweight; run the connector in an isolated container
if personal use is enabled. Do not mount its data directory or encryption key
into any aggregator or client container. Platform-specific deployment is in the
optional section below.

```sh
npm test
npm run test:protocol
npm run test:smoke   # standalone stdio server + connector, no platform, offline
npm run test:live
npm run build:extension
```

The live suite makes bounded public read requests; the default suite is offline.
No test loads personal Workday cookies or sends a registration request.

### Connector Docker deployment

See [the container deployment guide](deploy/selfhost/README.md) for automated multi-architecture images, controlled upgrades, persistent data migration and rollback. This deploys the connector independently of MCPHub.

## Remote MCP endpoint (OAuth)

The connector can serve the public and personal tools over Streamable HTTP at
`/mcp` as a standard OAuth-protected MCP resource (MCP authorization
specification, RFC 9728 protected resource metadata). It is **off by default**
and independent of any platform: it only validates bearer JWT access tokens
from one issuer and maps the token's `sub` to the connector account of the same
username (the same keying the platform adapters use). The stdio server and the
READ-token snapshot API are unchanged.

| Variable | Meaning |
| --- | --- |
| `UBC_MCP_HTTP` | `on` enables the endpoint; unset, empty or `off` disables it. Any other value is a startup error. |
| `UBC_PUBLIC_ORIGIN` | Required. Origin the connector is reached on: `https://...` (plain `http://` only for `localhost`, `127.0.0.1`, `[::1]`), no path. |
| `UBC_OAUTH_ISSUER` | Required. Issuer URL of the authorization server (https, or http on loopback). Must equal the tokens' `iss` exactly. |
| `UBC_MCP_RESOURCE` | Optional resource identifier. Default `${UBC_PUBLIC_ORIGIN}/mcp`. Set it when a reverse proxy changes the public URL. The endpoint itself is always served at `/mcp`. |
| `UBC_OAUTH_AUDIENCE` | Optional required `aud`. Default: the resource identifier. |
| `UBC_OAUTH_REQUIRE_AT_JWT` | Default `true`: the token header must carry `typ: at+jwt` (RFC 9068). Set `false` for issuers that sign access tokens with `typ: JWT` or no `typ`, for example some Keycloak and Okta configurations. `iss`, `aud`, `exp`, `sub` and `alg` stay strictly enforced. |
| `UBC_TRUST_PROXY` | Default off (X-Forwarded-For is ignored). A hop count such as `1` takes the client address from the entry that many places from the right of X-Forwarded-For, i.e. the first address not added by your own proxies. Set it behind a reverse proxy, otherwise every client shares the proxy's address in the rate limits. |

Endpoints:

- `POST|GET|DELETE /mcp`: Streamable HTTP (stateless; one fresh server per request). 
- `GET /.well-known/oauth-protected-resource` (also served at `/.well-known/oauth-protected-resource/mcp`):
  `{"resource": ..., "authorization_servers": [issuer], "bearer_methods_supported": ["header"], "scopes_supported": []}`.

Token validation (any standard authorization server issuing RFC 9068 JWT access tokens works):

- The issuer's metadata is read from `${issuer}/.well-known/oauth-authorization-server`, falling back to
  `/.well-known/openid-configuration`. Its `issuer` must match, and `jwks_uri` must be https (or loopback http).
  The key set is cached and refetched when a token names an unknown `kid` (at most every 30 seconds).
- Header `typ` must be `at+jwt`; `alg` must be `ES256` or `RS256` (`none`, `HS*` and everything else are rejected before any key is fetched).
- `iss` must equal `UBC_OAUTH_ISSUER`, `aud` (a string, or an array containing it) must equal the audience exactly,
  `exp` and a non-empty `sub` are required, and 60 seconds of clock skew are tolerated. `scope` is optional and not required.
- No token: `401` with `WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"`.
  A presented but invalid token: the same with `error="invalid_token"` added. If the issuer cannot be reached the answer is `503`
  (never an implicit allow). Tokens are never logged, stored or forwarded.
- Requests carrying an `Origin` header are refused and no CORS headers are ever sent; bodies are limited to 1 MB.
  Browser-based MCP clients, which always send `Origin`, are therefore refused by design (DNS-rebinding protection);
  use a server-side or native MCP client.
- Rate limits: requests with a valid token are limited only per issuer+subject (600 per minute) and are never blocked by their
  address. Requests that fail authentication are throttled per client address: invalid tokens at 120 per minute, missing or
  expired tokens (discovery probes, refresh) at a more generous 600 per minute.
- With `UBC_TRUST_PROXY` set, the connector must not be reachable directly: bind it to localhost or a private network that only
  your proxy can reach (`UBC_CONNECTOR_HOST`), because `X-Forwarded-For` can otherwise be forged to evade or abuse the address limits.
- Issuer comparison ignores a single trailing slash on both the configured issuer and the token's `iss`.
- If the key set cannot be fetched, is not JSON or is not a valid JWKS, the answer is `503` (issuer misconfigured or down), not `401`,
  and a one-line reason is logged. Rejected tokens log only a category (`iss`, `aud`, `exp`, `typ`, `alg`, `kid`, ...), at most once a minute each.

**Accounts are bound to the issuer.** A token only reaches the account created for the same issuer and `sub`; the same
username at a different authority reads nothing. Accounts created by the platform adapters before this existed have no
issuer ("legacy"). They are matched only if the configured `UBC_OAUTH_ISSUER` is the platform's own authority: the connector
reads the `issuer` from the platform's metadata (`UBC_PLATFORM_URL`) and compares. Otherwise they are never matched and one warning is
logged. `mcphub-oauth` records the platform's issuer on an account whenever it creates or reconnects it, which removes the need for that check.

An authenticated user whose `sub` has no connector account (or whose connection was revoked) still gets the public tools;
personal tools return the structured `CONNECTION_REVOKED` error, exactly as the READ-token path does. Personal tools read
only that account's snapshots; no READ token is involved on this path.

### Standalone, with any issuer

```sh
UBC_MCP_HTTP=on \
UBC_PUBLIC_ORIGIN=https://ubc.example.org \
UBC_OAUTH_ISSUER=https://auth.example.org \
UBC_PLATFORM_ADAPTER=none \
npm run connector
```

Create the account for each user with `link-account` (the issuer defaults to `UBC_OAUTH_ISSUER`); it prints the upload token
the browser extension or `push` uses, like `create-binding`. Running it again prints the same token.

```sh
UBC_DATA_DIR=/data UBC_OAUTH_ISSUER=https://auth.example.org node dist/connector/cli.js link-account --sub alice
# {"sub":"alice","issuer":"https://auth.example.org","id":"...","uploadToken":"..."}
```

Register `https://ubc.example.org/mcp` as the resource (audience) at your authorization server and make it put the
user's connector username in `sub`. Setting `UBC_PLATFORM_ADAPTER=none` matters here: `UBC_PUBLIC_ORIGIN` alone would
otherwise enable the deprecated `mcphub` adapter. Behind a reverse proxy, forward `/mcp` and `/.well-known/oauth-protected-resource`.

### With MCPHub

MCPHub is one possible issuer. Its admin adds an `externalResources` entry whose resource is
`<UBC_PUBLIC_ORIGIN>/mcp` and allows the client; set `UBC_OAUTH_ISSUER` to the MCPHub base URL and keep the audience at its default.
MCPHub then connects to the endpoint with its personal OAuth identity mode (the access token's `sub` is the MCPHub username,
which is the account name `mcphub-oauth` creates). That wiring is a separate step.

## Optional: MCPHub integration

Everything here is optional and disabled by default. The MCP server and the
connector core never depend on it. The integration is one adapter module per
mode (`src/connector/adapters/mcphub-oauth.ts`, and the deprecated cookie-based
`mcphub.ts`) selected by configuration. The variables below apply to the
cookie-based `mcphub` adapter; `mcphub-oauth` has its own set, listed in the next section:

| Variable | Meaning |
| --- | --- |
| `UBC_PLATFORM_ADAPTER` | `mcphub-oauth` (recommended, see [Connecting to MCPHub](#connecting-to-mcphub-oauth)) or `mcphub` (**deprecated**, forwards the user's Hub session cookie); `none` disables explicitly (wins over the legacy variables). Unset with none of the variables below set: off, and `/ubc/*` return 404. |
| `UBC_PUBLIC_ORIGIN` | Required with the adapter: HTTPS origin on which users reach the connector's `/ubc/` page. |
| `UBC_PLATFORM_URL` | Hub base URL for API calls. Defaults to `UBC_PUBLIC_ORIGIN`. `UBC_HUB_URL` is a deprecated alias. |
| `UBC_PLATFORM_SERVER_NAME` | Name of the Hub server entry that holds the user's credential. Default `ubc-personal`. |

Server names must match `^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$`.

### Connecting to MCPHub (OAuth)

`UBC_PLATFORM_ADAPTER=mcphub-oauth` connects a user's snapshots to MCPHub with
standard OAuth 2.1 (authorization code + PKCE S256) instead of forwarding the
user's MCPHub session cookie. The connector never reads, forwards or relies on
MCPHub cookies, requests only the scope `credentials:write:<server name>`, uses
the access token once and discards it. Default remains: no adapter.

**MCPHub admin steps**

1. Register the connector as an OAuth client in MCPHub as a **public client (no
   secret)**: PKCE S256 is what protects the flow. Redirect URI:
   `${UBC_PUBLIC_ORIGIN}/ubc/oauth/callback`
   (for example `https://hub.example.com/ubc/oauth/callback`). Do not register a
   confidential client until you run an MCPHub that contains the fix
   "fix: let confidential clients complete the authorization code flow"; older
   versions cannot complete `/oauth/authorize` for confidential clients.
2. There is no dashboard control for `credentialWriteClients`; set it with the
   administrator API. The server update replaces the whole server config, so read it,
   add the field, and send it back. The example uses an all-access system bearer key
   in `Authorization`; with a dashboard session token, send it as `x-auth-token`
   instead. The `jq` step adds the client to any ids already listed:

   ```sh
   HUB=https://hub.example.com; NAME=ubc-personal
   curl -s -H "Authorization: Bearer $ADMIN_TOKEN" "$HUB/api/servers/$NAME" \
     | jq '{config: (.data.config // .data | .credentialWriteClients = (((.credentialWriteClients // []) + ["ubc-connector"]) | unique))}' \
     | curl -s -X PUT -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \
         -d @- "$HUB/api/servers/$NAME"
   ```

   Check the response of the first call for the exact shape on your MCPHub version;
   the PUT body is `{"config": { ...full server config..., "credentialWriteClients": ["<client id>"] }}`.
   Before sending it back, make sure the first call returned real values rather than
   masked placeholders for any secret headers or environment variables; writing a
   masked value back would replace the real one. If they are masked, add the field
   in the server's entry in `mcp_settings.json` instead (JSON mode).
3. The `ubc-personal` server must be visible (shared or public) to the users who
   connect, and must define the `env.UBC_CONNECTOR_TOKEN` credential. The scoped
   token never acts as an administrator, so it cannot see a private server.
4. If `UBC_PLATFORM_URL` is an internal address (for example `http://mcphub:3000`),
   configure MCPHub's public base URL (`install.baseUrl` in the system config, or the
   `INSTALL_BASE_URL` environment variable). MCPHub builds the endpoints in its
   discovery document from it; without it the advertised `authorization_endpoint`
   would be the internal address, which browsers cannot reach. The connector logs
   a warning on first use when the advertised authorization host differs from
   `UBC_PLATFORM_URL` and is not https.

Limitations: MCPHub's custom bearer header name (`routing.bearerAuthHeaderName`) and
base paths are not supported by this adapter yet; it sends `Authorization: Bearer` and
uses `/api/credentials/<server>` and `/oauth/*` from the discovery document as served.

**Connector configuration** (validated at startup; a missing or invalid value stops the process with a clear message)

| Variable | Meaning |
| --- | --- |
| `UBC_PLATFORM_ADAPTER` | `mcphub-oauth` |
| `UBC_PUBLIC_ORIGIN` | Required. Origin users reach `/ubc/` on: `https://...` (plain `http://` only for `localhost`, `127.0.0.1`, `[::1]`). No path. |
| `UBC_PLATFORM_URL` | Required. MCPHub base URL. Used for `/.well-known/oauth-authorization-server`, `/api/credentials/<server>`, and (re-based onto this host) the token and userinfo endpoints. Use `https`; plain `http` only on a trusted private network (a warning is logged). |
| `UBC_OAUTH_CLIENT_ID` | Required. The OAuth client id registered in MCPHub. |
| `UBC_OAUTH_CLIENT_SECRET` | Optional; leave unset (public client with PKCE). Only for MCPHub versions that support confidential clients in the authorization code flow ("fix: let confidential clients complete the authorization code flow"). If set, sent as `client_secret_post`, or HTTP Basic when MCPHub advertises only `client_secret_basic`. |
| `UBC_PLATFORM_SERVER_NAME` | MCPHub server entry holding the credential. Default `ubc-personal`; same validation as the cookie adapter. |
| `UBC_SESSION_SECRET` | Required, at least 32 bytes (for example `openssl rand -base64 48`). Signs the connector's own cookies. Changing it signs everyone out of the connector page, nothing else. |

**Flow**

1. On `/ubc/` the user clicks **Connect with MCPHub**. `/ubc/oauth/start` creates
   a random `state` and PKCE verifier, stores them in a short-lived (10 minute)
   signed `HttpOnly` `SameSite=Lax` cookie (`Secure` unless the origin is
   loopback http) and redirects to MCPHub's authorization endpoint.
2. MCPHub redirects to `/ubc/oauth/callback`. The connector checks the signed
   cookie and `state` (single use), exchanges the code with the PKCE verifier,
   and calls `userinfo` to learn the MCPHub username (`sub`).
3. It finds or creates the connector account for that username (the same account
   model as the cookie adapter, so existing users keep their snapshots), then
   `PUT`s that account's READ token to `/api/credentials/<server>` with the access
   token as Bearer. The access token is then dropped.
4. The connector sets its own signed session cookie (account id, **7 days**, so coming back to the page within a week, for example from a Hub management link, needs no new authorization; **Forget this browser** or Disconnect ends it sooner) and
   shows the connection page. The extension's "Connect with MCPHub" completes
   through it.
5. **Disconnect** requires a fresh authorization: the page starts the flow with
   `intent=disconnect`; after MCPHub confirms the same user, the callback deletes
   the credential on MCPHub and revokes the connector binding and snapshots.
   Connector revocation always wins if the MCPHub delete fails. **Forget this
   browser** only clears the connector session cookie.

All state-changing calls from the page need the connector session plus a CSRF
token (synchronizer token, sent as `X-CSRF-Token`) and a same-origin request.
MCPHub error bodies are never shown or logged (on an `error=` redirect only the standard error code such as `invalid_scope`, `invalid_client` or `access_denied` is logged, so operators can tell misconfiguration from a user declining); users see a short message, and
tokens, codes, verifiers and credential values are never logged.

Proxy note: the connector only looks at its own `ubc_session` and `ubc_oauth`
cookies. If you want to be strict, forward only those to `/ubc/` in the reverse
proxy instead of the whole `Cookie` header.

### Upgrading

- **New variables:** `UBC_PLATFORM_ADAPTER` (`mcphub` or `none`), `UBC_PLATFORM_URL`
  (replaces `UBC_HUB_URL`, which still works) and `UBC_PLATFORM_SERVER_NAME`.
  `UBC_PUBLIC_ORIGIN` is unchanged.
- **Existing Hub deployments keep working.** If `UBC_PLATFORM_ADAPTER` is unset but
  `UBC_PUBLIC_ORIGIN` is set (as before), the connector enables the mcphub
  adapter automatically and logs a deprecation warning. Set
  `UBC_PLATFORM_ADAPTER=mcphub` explicitly; automatic enabling will be removed later.
  A stray `UBC_HUB_URL` without `UBC_PUBLIC_ORIGIN` is ignored with a warning, as before;
  with neither set the connector runs without an adapter.
- **Switching from `mcphub` (cookie) to `mcphub-oauth`:** register the OAuth client
  and add its id to `credentialWriteClients` on MCPHub first (see above), then
  change `UBC_PLATFORM_ADAPTER=mcphub-oauth` and add `UBC_PLATFORM_URL`,
  `UBC_PUBLIC_ORIGIN` (unchanged), `UBC_OAUTH_CLIENT_ID`, `UBC_SESSION_SECRET`
  (and optionally `UBC_OAUTH_CLIENT_SECRET`) and restart. The database is
  untouched: accounts are keyed by the MCPHub username in both modes, so existing
  users keep their binding, snapshots and extension credentials. Users click
  **Connect with MCPHub** once on `/ubc/` to authorize; the READ credential stored
  in MCPHub is rewritten with the same token. The cookie routes
  (`/ubc/api/connect`, `/ubc/api/disconnect`) do not exist in the new mode. Roll
  back by switching the variable back.
- **Deprecation:** the cookie-based `mcphub` adapter logs a warning at startup and
  will be removed in a future release. Automatic enabling from `UBC_PUBLIC_ORIGIN` alone is also deprecated.
- **Version:** the version now comes from `package.json` (`--version`, MCP server info,
  `/healthz`, User-Agent). `/healthz` returns `{"ok":true,"version":"..."}`.
- **Extension first run:** no server address is built in; the field starts empty and
  you enter your own HTTPS address. Connections made with 0.4.x keep their stored
  origin. Older connections (a token without an origin) are not migrated; connect again
  with MCPHub.
- **Images:** the stdio server image is published as `ghcr.io/kkazuhak/ubc-mcp` by
  the `MCP server image` workflow. Release tags must equal `v` + the `package.json`
  version or the workflows fail. As in the connector workflow, every `v*` tag (stable or
  pre-release) also moves the `beta` tag; only stable tags move `latest`.

### Self-service connection (alpha.2)

With the optional self-service routes deployed, enter your own MCPHub HTTPS origin in the extension, grant access, and approve the connection in Hub. The extension automatically opens a temporary background registration page and syncs it every 15 minutes while the browser and Workday session remain available. Recognized course-search pages are synced while open. A manual sync button and offline JSON export remain available.

The connection page calls existing Hub APIs as the signed-in user to save only
that user's READ credential. It does not change Hub source, server configuration
or permissions. Hub access rules still apply: each user must be allowed to access the configured Hub server (`ubc-personal` by default).

The extension requests local storage and optional access to the user-selected Hub origin and UBC Workday, in addition to activeTab/scripting/downloads. It stores the UPLOAD credential
in extension-local trusted-context storage, never browser sync storage. Forgetting the extension's local connection does not
revoke the server credential; use Disconnect on the connection page to revoke all
credentials and delete current snapshots. Historical backups have separate retention.

### Connect the extension through your MCPHub

Extension 0.4.0 and connector alpha.5 support **Connect with MCPHub** and automatic sync of supported open pages. New installations
start with an empty server field. Enter your own MCPHub HTTPS origin, allow access
to that origin, sign in there, and approve the extension connection. No token or
code needs to be copied. The connection persists in local extension
storage across normal browser restarts. Firefox still requires a signed install
for the extension itself to survive a restart.

Only `/ubc/` needs to be proxied to the connector on that Hub origin, alongside
`/v1/snapshots`; no Hub code, identity-provider setup or `/api/` route changes are
needed. The connector verifies the current Hub session and existing access to the configured
Hub server before issuing the upload-only credential. This is session reuse rather
than a new OAuth server (this is the deprecated `mcphub` adapter; prefer `mcphub-oauth`). An outdated connector is reported before authorization.

Credentials remain bound to their original origin when switching servers. The extension syncs registrations through a temporary background Workday tab every 15 minutes, plus recognized open course-search pages. A manual sync button and a pause control are available. It does not fetch the full catalog.

TDQS

A3.7/5.0

Scored across 7 tools

Disambiguation5/5

Each tool occupies a clearly distinct slot: browsing subject codes (list_subjects), keyword search (search_courses), single-record detail (get_course), grade history (get_course_grades), multi-course comparison (compare_courses), and metadata/health (list_grade_sessions, get_data_status). The descriptions explicitly draw boundaries between catalog records, historical grades, and data freshness, so an agent can select without guessing.

Naming Consistency5/5

All seven tools follow a uniform verb_noun snake_case convention (list_*, get_*, search_*, compare_*). The two get_course/get_course_grades names are predictably nested rather than confusing.

Tool Count5/5

Seven tools is a tight, well-scoped set for a course-catalog-plus-grades domain, with no redundant or filler entries. Each tool maps to one user intent (discover, inspect, compare, check freshness).

Completeness4/5

Discovery, detail, grade history, comparison, and data-health are all covered, and prerequisite text is preserved for planning. The main gap is any current-offering/section/seat lookup, which the descriptions disclaim but which agents will likely want for real course planning.

Maintenance

ActivityNo data
ResponsivenessOutdated data