From 5429dc313be8b3faf0f6c0e6f75ad78668d5e806 Mon Sep 17 00:00:00 2001
From: Aikhan Jumashukurov <117706338+aikhanj@users.noreply.github.com>
Date: Thu, 19 Nov 2026 22:55:20 -0500
Subject: [PATCH] Add authenticated Princeton course MCP connector
---
app/COURSE_CONNECTOR.md | 124 +++++++++++
app/README.md | 4 +
app/package-lock.json | 24 +--
app/package.json | 5 +
app/src/client/pages/AppsPage.tsx | 4 +
app/src/server/auth.ts | 12 +-
app/src/server/course-consent.ts | 43 ++++
app/src/server/course-mcp.ts | 174 ++++++++++++++++
app/src/server/course-oauth.ts | 133 ++++++++++++
app/src/server/index.ts | 6 +-
app/tests/auth.test.ts | 24 ++-
app/tests/course-mcp.test.ts | 113 ++++++++++
app/tests/course-oauth.test.ts | 196 ++++++++++++++++++
app/tests/fixtures/course-connector-worker.ts | 11 +
app/wrangler.jsonc | 6 +-
15 files changed, 862 insertions(+), 17 deletions(-)
create mode 100644 app/COURSE_CONNECTOR.md
create mode 100644 app/src/server/course-consent.ts
create mode 100644 app/src/server/course-mcp.ts
create mode 100644 app/src/server/course-oauth.ts
create mode 100644 app/tests/course-mcp.test.ts
create mode 100644 app/tests/course-oauth.test.ts
create mode 100644 app/tests/fixtures/course-connector-worker.ts
diff --git a/app/COURSE_CONNECTOR.md b/app/COURSE_CONNECTOR.md
new file mode 100644
index 0000000..0f8eeaf
--- /dev/null
+++ b/app/COURSE_CONNECTOR.md
@@ -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.
diff --git a/app/README.md b/app/README.md
index 596b7e8..ae5b2a0 100644
--- a/app/README.md
+++ b/app/README.md
@@ -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)
diff --git a/app/package-lock.json b/app/package-lock.json
index 1e854ca..da99788 100644
--- a/app/package-lock.json
+++ b/app/package-lock.json
@@ -11,6 +11,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",
@@ -25,6 +28,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",
@@ -1032,6 +1037,12 @@
"node": ">=16"
}
},
+ "node_modules/@cloudflare/workers-oauth-provider": {
+ "version": "1.2.4",
+ "resolved": "https://registry.npmjs.org/@cloudflare/workers-oauth-provider/-/workers-oauth-provider-1.2.4.tgz",
+ "integrity": "sha512-ayo6Z8DBHdAxwDpplFU8BrEoxoSn6wNo+E7ypTENRHUOc8R89A8/+nZ+a8pMZjjXzF0JXfpYXhw/7qqG+DC18Q==",
+ "license": "MIT"
+ },
"node_modules/@cloudflare/workers-types": {
"version": "5.20260822.1",
"resolved": "https://registry.npmjs.org/@cloudflare/workers-types/-/workers-types-5.20260822.1.tgz",
@@ -2176,7 +2187,6 @@
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/client/-/client-2.0.0.tgz",
"integrity": "sha512-8f1OghQ2rjzIOfqgUCP+8GiUWqRs89njoWLNqAe8kWmDePv3s1fZXseej+QXemssEuuOvLLmLO/kqM3IQHtISw==",
"license": "MIT",
- "peer": true,
"dependencies": {
"@modelcontextprotocol/core": "2.0.0",
"cross-spawn": "^7.0.5",
@@ -2195,7 +2205,6 @@
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/core/-/core-2.0.0.tgz",
"integrity": "sha512-pJCEwGG7Lfr/+PQp9ZTwKXNeO5wzbfKL7H3MYpCorM4oFBoQrdjnBgEoqG+RjhsvS1FKrDbKux+M1HhlnGWqcA==",
"license": "MIT",
- "peer": true,
"dependencies": {
"zod": "^4.2.0"
},
@@ -2249,7 +2258,6 @@
"resolved": "https://registry.npmjs.org/@modelcontextprotocol/server/-/server-2.0.0.tgz",
"integrity": "sha512-YhHWdHfpFMQfd0prsEnxKeS3Qz3ytIGmsS0sth4KDjnacIT7hxk6hXHkJ9KysxlkvTM+WZAtQbbcUhdoP4Hvtw==",
"license": "MIT",
- "peer": true,
"dependencies": {
"@modelcontextprotocol/core": "2.0.0",
"zod": "^4.2.0"
@@ -4276,7 +4284,6 @@
"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
"integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
"license": "MIT",
- "peer": true,
"dependencies": {
"path-key": "^3.1.0",
"shebang-command": "^2.0.0",
@@ -4633,7 +4640,6 @@
"resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz",
"integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==",
"license": "MIT",
- "peer": true,
"dependencies": {
"eventsource-parser": "^3.0.1"
},
@@ -5244,8 +5250,7 @@
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
"integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
- "license": "ISC",
- "peer": true
+ "license": "ISC"
},
"node_modules/isomorphic-git": {
"version": "1.41.8",
@@ -5277,7 +5282,6 @@
"resolved": "https://registry.npmjs.org/jose/-/jose-6.2.10.tgz",
"integrity": "sha512-iiW7J9qRFlGxvCOIBDBDxFePQSn7ZMAnrYGhrrOo6siO/MIqwfyilLR27pkfDgUk+raLuzADS8A3S/KLBisc0g==",
"license": "MIT",
- "peer": true,
"funding": {
"url": "https://github.com/sponsors/panva"
}
@@ -6615,7 +6619,6 @@
"resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
"integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
"license": "MIT",
- "peer": true,
"engines": {
"node": ">=8"
}
@@ -7320,7 +7323,6 @@
"resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
"integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
"license": "MIT",
- "peer": true,
"dependencies": {
"shebang-regex": "^3.0.0"
},
@@ -7333,7 +7335,6 @@
"resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
"integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
"license": "MIT",
- "peer": true,
"engines": {
"node": ">=8"
}
@@ -8136,7 +8137,6 @@
"resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
"integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
"license": "ISC",
- "peer": true,
"dependencies": {
"isexe": "^2.0.0"
},
diff --git a/app/package.json b/app/package.json
index 6c592d2..4d2cad3 100644
--- a/app/package.json
+++ b/app/package.json
@@ -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",
@@ -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",
diff --git a/app/src/client/pages/AppsPage.tsx b/app/src/client/pages/AppsPage.tsx
index 4f6fef5..0e3c5b0 100644
--- a/app/src/client/pages/AppsPage.tsx
+++ b/app/src/client/pages/AppsPage.tsx
@@ -167,6 +167,10 @@ export function AppsPage({
separate yes, even the ones TigerJunction could technically
answer for.
${body}`, { headers, status });
+}
+
+export function consentPage(details: ConsentDescription, handle: string, netid: string, subjectProof: string, headers: Headers): Response {
+ const name = escapeHtml(details.clientName);
+ return connectorPage("Connect your course assistant", `
+
${name} wants to use Princeton course tools as ${escapeHtml(netid)}.
+
Authorization returns to ${escapeHtml(details.redirectHost)}.
+${details.clientDomain ? `Client domain verified as ${escapeHtml(details.clientDomain)}.` : "The application name is supplied by the client. Check the destination before connecting."}${details.redirectIsLoopback ? " This destination is a local app. Another local process could be listening there." : ""}
+`, headers);
+}
+
+export function connectionsPage(origin: string, netid: string, grants: GrantSummary[], cursor?: string): Response {
+ return connectorPage("Your course connector", `
+
Use your existing Claude account to research courses, compare reviews, check degree requirements, and plan your semester.
+
In Claude, open Settings, then Connectors, then add a custom connector.
Use this server URL. ${escapeHtml(origin)}/mcp
Sign in with Princeton and choose the permissions to grant.
+
Try asking, “Help me choose next semester's courses for my degree and interests. Compare workload and section times, then show me alternatives before saving.”
+Connector availability depends on your assistant's plan and workspace settings. Your assistant handles model usage under its own limits. PI provides the course tools.
+