Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions app/COURSE_CONNECTOR.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# Princeton course connector

PI can supply Princeton course tools to a student's existing assistant through
authenticated remote MCP at `/mcp`. The assistant runs the conversation and
model inference under its own account limits. This path does not use PI's
Anthropic key, import memories, or share PI chat history.

## Student setup

After deployment, open **My apps → Use Princeton course tools in Claude** in PI.
Add the URL shown there as a custom connector in Claude, then complete Princeton
sign-in and consent. On the normal production origin the URL is
`https://pi.tigerapps.org/mcp`. That address is a deployment target, not a claim
that this branch is already live.

The default permission reads courses, sections, reviews, requirements, and the
student's saved TigerJunction and TigerPath plans. A separate, unchecked option
allows saved-plan changes. Grants can be disconnected at `/connect`.
PI's existing app switches govern PI chat. Connector grants are managed
separately, and signing out of PI does not revoke them.

Example request

> Help me choose courses for next semester. I'm a COS student in the class of
> 2029 interested in systems and quant development. Ask which degree I'm pursuing
> and which prerequisites I've completed. Compare available courses, workload,
> reviews, requirements, and section times. Give me alternatives before saving
> anything.

An optional `plan_semester` MCP prompt accepts the student's goal and constraints.
Claude's current remote-connector instructions and account restrictions are
documented in its [custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
Compatibility with other MCP clients must be tested individually.

## What is exposed

The connector filters live tool definitions through an explicit allowlist.
Overlapping upstream tool catalogs cannot change a tool's designated source.

| Source | Read access | Optional changes |
| --- | --- | --- |
| TigerJunction | Catalog search, details, sections, terms, departments, comparisons, enrollment statistics, own schedules, upstream schedule screening | Create or rename a saved schedule, add or remove a course |
| PrincetonCourses | Course evaluations, review summaries, instructor information | None |
| TigerPath | Degree requirement trees, aggregate planning statistics, own four-year plan | Add or remove a course in a semester |

There are 24 allowlisted read tools and 5 optional write tools. Whole-schedule
deletion, seat alerts, TigerHub registration, Canvas, calendar access, and PI
workspaces are excluded. A saved plan is not a transcript or actual enrollment.

The upstream `verify_schedule` tool screens a proposed course set. It does not
prove that a complete combination of lecture, precept, and lab sections is
feasible, verify completed prerequisites, or certify degree completion. The
assistant instructions explicitly preserve those distinctions.

## Authentication and deployment

The existing CAS login establishes the NetID. The connector adds OAuth
authorization code flow with required PKCE S256, dynamic client registration,
audience-bound access tokens, refresh, and revocation through
[`@cloudflare/workers-oauth-provider`](https://github.com/cloudflare/workers-oauth-provider).
Consent uses the library's browser-bound transaction plus a signed binding to
the displayed CAS identity. An account switch cannot silently authorize the
old consent page as a different student.

Required deployment configuration

- `SESSION_SECRET` must be the existing PI signing secret.
- `APP_ORIGIN` must be the canonical HTTPS origin, also allowed by Princeton CAS.
- `OAUTH_KV` stores client registrations, grants, and tokens. The Wrangler config
declares a draft binding. Before the first production deployment, provision
or select the production namespace and record its ID in `wrangler.jsonc`.
Wrangler also supports provisioning at deployment when the deploy credential
has the required KV permissions. Reuse the namespace on later deploys.
- `ENGINE_MCP_BASE` selects the trusted TigerApps backend. `ENGINE_MCP_TOKEN` is
sent only to that backend. Production must enforce its service credential
before trusting `x-user-netid`, and must enforce ownership for schedule IDs.
This connector authenticates its own callers. It does not secure a separately
exposed engine that accepts arbitrary identity headers.

The Worker routes `/mcp`, `/connect/*`, and OAuth discovery before SPA assets.
Ordinary PI routes do not depend on connector KV lookups. MCP requests never
forward a caller's cookies, bearer token, or identity headers to the engine.
Upstream sessions are per operation and deleted after use. Redirects are rejected.

Access tokens last one hour. Refresh grants expire after 30 days. Revocation
uses Workers KV and is subject to its propagation delay. It cannot remove data
already received by a third-party assistant. CIMD is explicitly disabled for
this first version. OAuth dynamic registration is supported instead.

## Verification

Run the repository's normal checks from `app`

```sh
npm ci
cp .dev.vars.example .dev.vars
npx wrangler types
npm run typecheck
npm test
npm run build
```

Do not overwrite an existing configured `.dev.vars` file. The copy step above
is for a fresh checkout. Local development uses local KV and a separate session
secret, with `APP_ORIGIN` matching the local server.

`course-mcp.test.ts` uses actual MCP clients and transports. `course-oauth.test.ts`
runs the production connector handlers in workerd via Miniflare with local KV
and a mocked engine, covering sign-in return, consent, PKCE, scope enforcement,
refresh, identity isolation, revocation ownership, and upstream session cleanup.
It does not contact student accounts or modify real plans.

A read-only live smoke check on November 19, 2026 discovered all 24 read tools,
read the COS-BSE class-of-2029 requirement tree, and retrieved COS 217 evaluations
and Fall 2026 sections.
The live catalog listed terms only through Fall 2026. Spring 2027 COS 217 search
returned no courses and its sections lookup returned an explicit missing-course
error despite the tool descriptions mentioning Spring 2027. Missing coverage is
not proof that the course will not be offered. The connector's instructions
require the assistant to report that gap instead of substituting an older term.

Production CAS-to-Claude authorization, real personal-plan ownership enforcement,
and saved-plan changes still require an authorized staging check. No production
deployment or real plan mutation is part of these local checks.
4 changes: 4 additions & 0 deletions app/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ React app and the agent; there are no containers and no servers to warm up.

## Architecture

The [course connector](COURSE_CONNECTOR.md) lets students use Princeton course
tools from their existing Claude account, with Princeton sign-in and separate
read or saved-plan editing permissions.

```
browser (React + useAgentChat over WebSocket)
└─ Cloudflare Worker (static assets + routeAgentRequest)
Expand Down
24 changes: 12 additions & 12 deletions app/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 5 additions & 0 deletions app/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
"@ai-sdk/anthropic": "^4.0.0",
"@ai-sdk/react": "^4.0.45",
"@cloudflare/think": "^0.16.0",
"@cloudflare/workers-oauth-provider": "^1.2.4",
"@modelcontextprotocol/client": "2.0.0",
"@modelcontextprotocol/server": "2.0.0",
"agents": "^0.21.0",
"ai": "^7.0.0",
"react": "^19.0.0",
Expand All @@ -29,6 +32,8 @@
"@types/react": "^19.0.0",
"@types/react-dom": "^19.0.0",
"@vitejs/plugin-react": "^5.0.0",
"esbuild": "0.28.2",
"miniflare": "5.20260820.0-alpha",
"tsx": "^4.23.15",
"typescript": "^5.9.0",
"vite": "^7.0.0",
Expand Down
4 changes: 4 additions & 0 deletions app/src/client/pages/AppsPage.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,10 @@ export function AppsPage({
separate yes, even the ones TigerJunction could technically
answer for.
</p>
<p className="page-sub">
<a href="/connect">Use Princeton course tools in Claude</a>
. Manage its access separately from these app switches.
</p>
</div>

<div className="master-switch">
Expand Down
12 changes: 11 additions & 1 deletion app/src/server/auth.ts
Original file line number Diff line number Diff line change
Expand Up @@ -119,8 +119,17 @@ const pendingSchema = z.object({
state: z.string().min(1),
service: z.string().url(),
exp: z.number().finite(),
returnTo: z.string().optional(),
});

/** Only the connector's own pages can be resumed after CAS sign-in. */
function loginReturnTo(value: string | null | undefined): string {
if (!value || value.length > 8192 || !/^\/connect(?:\?|\/authorize\?|$)/.test(value)) return "/";
const parsed = new URL(value, "https://pi.invalid");
return parsed.origin === "https://pi.invalid" && ["/connect", "/connect/authorize"].includes(parsed.pathname)
? parsed.pathname + parsed.search : "/";
}

const casResponseSchema = z.object({
serviceResponse: z.object({
authenticationFailure: z.unknown().optional(),
Expand Down Expand Up @@ -169,6 +178,7 @@ export async function handleAuth(
authorize.searchParams.set("service", service.toString());
const pending = await signToken({
state, service: service.toString(), exp: Date.now() / 1000 + LOGIN_TTL_S,
returnTo: loginReturnTo(url.searchParams.get("returnTo")),
}, env.SESSION_SECRET);
return response(null, {
status: 302,
Expand Down Expand Up @@ -239,7 +249,7 @@ export async function handleAuth(
return response(null, {
status: 302,
headers: [
["location", "/"],
["location", loginReturnTo(pending.returnTo)],
["set-cookie", cookie(SESSION_COOKIE, token, SESSION_TTL_S)],
["set-cookie", cookie(CAS_COOKIE, "", 0)],
["set-cookie", cookie("pi_oauth", "", 0)],
Expand Down
Loading
Loading