@terreno/mcp 57.1.0 → 57.3.0

package/src/docs/versioned/next/implementationPlans/mcp-service-tokens.md

@@ -0,0 +1,281 @@
+# Implementation Plan: MCP service tokens
+
+**Status:** Approved  
+**Branch:** TBD  
+**Owner:** unassigned  
+**Created:** 2026-09-03  
+**Depends on:** [model-router-mcp.md](model-router-mcp.md) (shipped — `POST /mcp` + `extractUserFromHeaders`)  
+**Sibling:** [app-mcp-server.md](app-mcp-server.md) (OAuth 2.1 for interactive MCP clients — complementary, not a blocker)
+
+## Goal
+
+Authenticated users mint **personal MCP service tokens** that act as that user on the
+consumer app's `POST /mcp` endpoint only. They copy an **MCP URL** plus a **Bearer
+`mcp_…` key** into external clients (Perplexity custom connectors, Claude Code, Cursor,
+Inspector) without pasting a session JWT. Admins list and revoke any user's tokens from
+the admin panel.
+
+When this is done, an operator can:
+
+1. Set `mcpServiceTokens: true` on `TerrenoApp`.
+2. Sign in to the example app, open **Settings → MCP**, create a named token, copy URL +
+   key once.
+3. Paste into Perplexity (**Custom connector → Remote → Streamable HTTP → API Key**).
+4. Call `tools/list` on `/mcp` with `Authorization: Bearer mcp_…` and see the same tools
+   that user would see over REST-backed MCP.
+5. Revoke from the settings screen or from **Admin → MCP service tokens**.
+
+## Non-Goals
+
+| Out | Why |
+| --- | --- |
+| Hosted `@terreno/mcp` (dev-time codegen server) | Different product surface |
+| `@terreno/infra-mcp` machine tokens | Separate IP; GCP/Sentry scope |
+| OAuth 2.1 / RFC 9728 for MCP | [app-mcp-server.md](app-mcp-server.md) Phase 6; tokens are the static-key path for Perplexity |
+| Per-token scopes (read-only, tool allowlists) | v1 is full user MCP permissions |
+| Token auth on REST, sync sockets, or admin HTTP | MCP-only credential (Q4) |
+| Secret in query string or connection URL | Header-only Bearer (Q3) |
+| Password re-prompt on mint | Session/JWT is enough for create/list/revoke |
+| Per-token rate limits | Existing `POST /mcp` **api** bucket applies |
+| Auto-enable when `/mcp` mounts | Explicit `mcpServiceTokens: true` (Q7) |
+| Profile-tab mint UI | Dedicated `/settings/mcp` route (Q13) |
+
+## Decisions
+
+| ID | Question | Decision |
+| --- | --- | --- |
+| Q1 | MCP surface | Consumer app `POST /mcp` on `@terreno/api` only |
+| Q2 | Identity | Token acts as **owning user**; same `modelRouter` / `registerMCPTool` permissions; no scopes in v1 |
+| Q3 | Transport | `Authorization: Bearer mcp_…`; plaintext shown **once** on create; never in URL |
+| Q4 | Power | **MCP endpoint only** — not REST, sync, or admin |
+| Q5 | Mint UX | Self-service API + example UI; new IP; hashed model in `@terreno/api` |
+| Q6 | Expiry | Optional `expiresAt` on create; default **no expiry**; expired → 401 on `/mcp` |
+| Q7 | Enablement | **`mcpServiceTokens: true`** on `TerrenoAppOptions` mounts routes + token auth |
+| Q8 | Token shape | Prefix **`mcp_`** + 32 random bytes (hex); SHA-256 hash stored; verify **before** JWT parse |
+| Q9 | Cap | Max **10** active (non-revoked, unexpired) tokens per user; 400 when over cap |
+| Q10 | UI placement | New settings route + admin changelist (not Profile tab) |
+| Q11 | Admin vs owner | Owners self-serve; **admins** list/revoke **all** users' tokens |
+| Q12 | Admin implementation | Generic **`AdminApp` model** registration (no custom widget) |
+| Q13 | User route | **`/settings/mcp`** in example-frontend |
+
+### Recorded assumptions (implementation detail)
+
+- Hash: `crypto.createHash("sha256")` (same as `AuthToken`).
+- Display prefix: first 8 characters after `mcp_` (e.g. `mcp_a1b2c3d4…`) for list UIs.
+- Revoke: set `revokedAt`; do not hard-delete rows (audit-friendly).
+- `lastUsedAt` updated on successful MCP auth (throttle optional; v1 update every auth).
+- Self-serve routes live at **`/mcp/service-tokens`** (session/JWT only).
+- Admin CRUD at **`/admin/mcp-service-tokens`** via `AdminApp` (list + revoke; create/update disabled).
+- `mcpUrl` in create response: `{publicApiUrl}/mcp` from new optional `mcpServiceTokens.publicMcpUrl` or `BETTER_AUTH_URL` / request host fallback.
+- Perplexity: GET `/mcp` is a Streamable-HTTP **405** (no GET SSE stream). POST `initialize` / `tools/list` are unauthenticated catalog in the stateless handler. Identity is enforced on **`tools/call`**. Send the same Bearer on GET and POST anyway.
+
+## Architecture
+
+```
+User (session)                External MCP client (Perplexity, etc.)
+     |                                    |
+     | POST /mcp/service-tokens          | POST|GET /mcp
+     | GET  /mcp/service-tokens            | Authorization: Bearer mcp_…
+     | DELETE /mcp/service-tokens/:id      |
+     v                                    v
+McpServiceToken model (hash only)   extractUserFromHeaders
+     |                                    |
+     |                                    +-- mcp_* ? verify hash -> User
+     |                                    +-- else Better Auth session
+     |                                    +-- else JWT
+     v                                    v
+AdminApp table (IsAdmin)            same User as REST MCP today
+list / revoke all users
+```
+
+### Connection string (operator copy-paste)
+
+Clients that accept JSON (Cursor, VS Code, Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer mcp_<secret-shown-once>"
+      }
+    }
+  }
+}
+```
+
+Perplexity custom connector form:
+
+| Field | Value |
+| --- | --- |
+| MCP Server URL | `https://api.example.com/mcp` |
+| Transport | Streamable HTTP |
+| Authentication | API Key |
+| API Key | full `mcp_…` string (Perplexity sends as Bearer) |
+
+## Models
+
+**`McpServiceToken`** (`api/src/models/mcpServiceToken.ts` + `api/src/types/mcpServiceToken.ts`)
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `userId` | ObjectId ref User | owner; required; indexed |
+| `name` | string | user label ("Perplexity laptop"); required; trim |
+| `tokenPrefix` | string | display only, e.g. `a1b2c3d4` |
+| `tokenHash` | string | SHA-256 of full `mcp_…`; unique |
+| `expiresAt` | Date? | optional; TTL index when set |
+| `revokedAt` | Date? | set on revoke |
+| `lastUsedAt` | Date? | updated on MCP auth |
+
+Plugins: `createdUpdatedPlugin`, `findOneOrNone`, `findExactlyOne`. **No** `isDeletedPlugin
+(revoke is explicit). Statics: `issueFor(user, {name, expiresAt?})` → `{token, doc}`;
+`verify(plaintext)` → `McpServiceTokenDocument | null` (not revoked, not expired);
+`revokeForUser(user, id)`; `countActiveForUser(userId)`.
+
+OpenAPI / admin metadata: **never** expose `tokenHash`. Create response is the only time
+`token` plaintext appears.
+
+## APIs
+
+### Self-serve (`/mcp/service-tokens`)
+
+Mounted only when `mcpServiceTokens: true`. All routes require session/JWT
+(`authenticateMiddleware`); **reject** `mcp_` Bearer on these routes (401 — tokens cannot
+mint tokens).
+
+| Method | Path | Body / params | Response |
+| --- | --- | --- | --- |
+| POST | `/mcp/service-tokens` | `{name, expiresAt?}` | `{data: {id, name, token, tokenPrefix, mcpUrl, expiresAt, created}}` |
+| GET | `/mcp/service-tokens` | `?page&limit` | `{data: [...], page, limit, total, more}` — no `token` field |
+| DELETE | `/mcp/service-tokens/:id` | — | `{data: {id, revokedAt}}` — owner only |
+
+Errors: 400 over cap (10); 404 not found / not owner; 401 unauthenticated.
+
+### MCP auth (`extractUserFromHeaders`)
+
+When `mcpServiceTokens` enabled and `Authorization` bearer starts with `mcp_`:
+
+1. Hash and lookup active token.
+2. Load `userId` → `User`; `rejectIfDisabled`.
+3. Set `lastUsedAt` (fire-and-forget).
+4. Return user (same type as JWT path).
+
+Order: **service token → Better Auth session → JWT** (Q8).
+
+### Admin (`AdminApp`)
+
+Register on consuming app (example-backend):
+
+```typescript
+{
+  model: McpServiceToken,
+  routePath: "/mcp-service-tokens",
+  displayName: "MCP service tokens",
+  group: "Platform",
+  listFields: ["name", "tokenPrefix", "userId", "lastUsedAt", "expiresAt", "revokedAt", "created"],
+  permissions: {create: [], update: [], delete: [Permissions.IsAdmin], list: [Permissions.IsAdmin], read: [Permissions.IsAdmin]},
+  // responseHandler strips tokenHash
+}
+```
+
+Admin **delete** sets `revokedAt` (override default hard delete in `preDelete` or use
+custom delete route).
+
+## UI
+
+### Example-frontend `/settings/mcp`
+
+- Linked from Profile (button "MCP connections" → `/settings/mcp`).
+- **Create:** name field, optional expiry date (`DateTimeField`), submit → modal with
+  **copy-once** `mcpUrl`, full `token`, and JSON snippet.
+- **List:** name, prefix, created, last used, expires, Revoke button.
+- Uses generated SDK hooks after `bun run sdk`.
+- Loading / error / empty states.
+
+### Admin
+
+Generic `AdminModelTable` via existing `[model]` routes — no new Expo screen.
+
+## TerrenoApp integration
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL, // optional; shown in create response
+  },
+});
+```
+
+Boolean `mcpServiceTokens: true` is shorthand for `{enabled: true}`.
+
+When enabled:
+
+1. Register self-serve routes (before or after `mountMCPServer` — order irrelevant).
+2. Pass `mcpServiceTokens: true` into `MCPAuthContext` so `extractUserFromHeaders` verifies tokens.
+
+`/mcp` mounting unchanged (still requires MCP tools). Token routes can mount even if no
+tools yet (harmless); example-backend already exposes MCP.
+
+## Phases
+
+| Phase | Delivers |
+| --- | --- |
+| 1 | Model, issue/verify/revoke, `extractUserFromHeaders` integration, unit tests |
+| 2 | Self-serve HTTP routes, `TerrenoApp` flag, OpenAPI |
+| 3 | Example-backend flag + `AdminApp` registration |
+| 4 | Example-frontend `/settings/mcp` + SDK + verification artifacts |
+| 5 | Docs (how-to connect Perplexity, reference, explanation cross-link) |
+
+## Feature Flags & Migrations
+
+- No feature flag beyond `mcpServiceTokens` opt-in.
+- New collection `mcpservicetokens` (mongoose default pluralization). No backfill.
+- Index: `{userId: 1, revokedAt: 1}`, unique `tokenHash`, TTL on `expiresAt` when present.
+
+## Activity Log & User Updates
+
+- Optional: `logger.info` on mint/revoke with `userId` + `tokenPrefix` (never log full token).
+- No email on mint in v1.
+
+## Not Included / Future Work
+
+- OAuth 2.1 ([app-mcp-server.md](app-mcp-server.md)) — use for Claude web connectors that cannot send static keys.
+- Scoped tokens (read-only MCP, named tool allowlist).
+- REST-wide personal access tokens.
+- Token rotation / regenerate keeping same id.
+- Audit log table for MCP calls per token.
+
+## Files to Create / Modify
+
+| Area | Files |
+| --- | --- |
+| Model | `api/src/models/mcpServiceToken.ts`, `api/src/types/mcpServiceToken.ts` |
+| Routes | `api/src/mcp/serviceTokens.ts`, `api/src/mcp/serviceTokens.test.ts` |
+| Auth | `api/src/mcp/auth.ts`, `api/src/mcp/auth.test.ts` |
+| App | `api/src/terrenoApp.ts`, `api/src/index.ts` |
+| Example backend | `example-backend/src/server.ts` (flag + admin model) |
+| Example frontend | `example-frontend/app/settings/mcp.tsx`, `example-frontend/app/settings/_layout.tsx`, link from `profile.tsx`, SDK regen |
+| Docs | `docs/how-to/connect-mcp-service-token.md`, `docs/how-to/expose-mcp-tools.md`, `docs/reference/api.md`, `docs/explanation/authentication.md` |
+
+## Task List
+
+See [`docs/tasks/mcp-service-tokens.md`](../tasks/mcp-service-tokens.md).
+
+## Acceptance Criteria
+
+| Criterion | Verification |
+| --- | --- |
+| Flag off: no `/mcp/service-tokens` routes; `mcp_` bearer on `/mcp` is ignored | `api` unit + integration test |
+| Flag on: create returns `mcp_` plaintext once; list never includes it | Route tests |
+| Active cap 10 per user | Route test returns 400 on 11th create |
+| Optional expiry: expired token 401 on `/mcp` | Auth test + HTTP initialize |
+| Revoked token 401 on `/mcp` | Auth test |
+| Valid token: `tools/list` as owner user | Supertest MCP handler or `invokeMCPTool`-style test |
+| Session JWT cannot call self-serve routes with `mcp_` only | Route test |
+| Admin lists all users' tokens; admin revoke blocks MCP | Admin integration test |
+| Perplexity-shaped GET `/mcp` is JSON-RPC 405; POST `tools/call` with same Bearer acts as owner | HTTP integration test + how-to |
+| Example `/settings/mcp` create-copy-revoke flow | Manual UI + artifact |
+| Docs: Perplexity form fields + JSON snippet | Doc review |

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci-research.md

@@ -38,7 +38,7 @@ Investigate what “migrate all CI/CD to CircleCI” means for Terreno: inventor
 
 ### Shared CI patterns
 
-1. `oven-sh/setup-bun@v2` (`bun-version: latest`, sometimes pinned `1.3.10` for EAS)
+1. `oven-sh/setup-bun@v2` (`bun-version: latest`, sometimes pinned `1.4.0` for EAS)
 2. `actions/cache` on `~/.bun/install/cache` keyed by OS + ref + lockfile
 3. `bun install --frozen-lockfile` then package `lint` / `compile` / `test(:coverage|:ci)`
 4. Mongo via `supercharge/mongodb-github-action` (image `mirror.gcr.io/library/mongo`) for api/ai/example-backend/e2e

package/src/docs/versioned/next/implementationPlans/migrate-cicd-to-circleci.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Migrate CI/CD to CircleCI
 
-**Status:** In progress — Phase 1–3 CI config landed (deploys deferred per request)  
+**Status:** In progress — CI, release, Netlify/GCP production path deploys, and PR previews landed; EAS PR/fingerprint temporarily disabled; GitHub-native maintenance remains  
 **Discussion:** _(none)_  
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1088
 **Linear:** _(none)_  
@@ -164,11 +164,22 @@ Port and dual-run:
 - Recreate preview aliases + optional GitHub Deployments via API.
 - `preview-cleanup` equivalent for Netlify/GCP previews as applicable.
 
+Implemented: production and PR preview jobs exist on CircleCI. GitHub Actions
+is the live Netlify/GCP writer until `terreno-netlify` / `terreno-gcp` are
+populated; CircleCI deploy scripts skip (exit 0) when those variables are
+missing. After a successful CircleCI deploy, set GHA deploy workflows back to
+`on: []` in the same change. Preview cleanup on PR close is GHA
+`preview-cleanup.yml` plus the manual CircleCI parameter.
+
 ### Phase 5 — EAS + fingerprint (v1)
 
 - Port `eas-pr`, `eas-dev-build`, `fingerprint-gate` scripts under `.circleci/` or keep scripts in `.github/workflows/scripts/` and invoke from CircleCI until relocated to `scripts/ci/`.
 - PR comment + `fingerprint-acknowledged` label via GitHub API.
 
+Manual EAS dispatch is implemented. EAS PR updates and fingerprint
+acknowledgement are retained with `on: []` until CircleCI comment/label parity
+is implemented.
+
 ### Phase 6 — GCP CD + OIDC (v1)
 
 - Terraform: CircleCI OIDC provider + dual-trust.
@@ -176,18 +187,25 @@ Port and dual-run:
 - Port `preview-cleanup` onto OIDC (eliminate `GCP_SA_KEY`).
 - Dual-run CD carefully (concurrency: one deployer).
 
+Implemented as CircleCI jobs plus GHA dual-run until CircleCI OIDC/context
+values exist. Path filters start `gcp-cd-prod` / `gcp-cd-preview`. CircleCI
+skips apply when `terreno-gcp` is empty so terraform is not double-applied.
+
 ### Phase 7 — npm publish (v1)
 
 - Port `publish-on-tag` + `publish-feature-flags-manual`.
 - **Single-writer rule:** disable GHA tag trigger in the same change that enables CircleCI tag pipeline.
 - Keep Zoom notify + master version bump + docs cut + demo dispatch.
 
+Implemented as a semver-tag release job plus manual `syncdb`/`feature-flags`
+publishing. GHA publishing triggers are disabled. Docs version cutting remains
+a follow-up; package publish, stable master bumps, Zoom notify, and demo deploy
+are ported.
+
 ### Phase 8 — Mobile runners (post-v1 / still required for full cutover)
 
-- Maestro (`maestro-e2e`).
-- Appium Android on Linux VM.
-- Appium iOS on CircleCI macOS resource class (image pin parity with `macos-15` intent).
-- Then delete `demo-appium-ci.yml` / `maestro-e2e.yml`.
+- Maestro web/Chrome (`maestro-e2e`) is implemented on CircleCI Linux browsers + Mongo replica set. GHA `maestro-e2e.yml` is `on: []`.
+- Appium Android on Linux VM and Appium iOS on CircleCI macOS remain unported.
 
 ### Phase 9 — GitHub-native + agentic replacements (full cutover)
 
@@ -197,7 +215,8 @@ Port and dual-run:
 | `dependabot-auto-merge` | Keep Dependabot PRs on GitHub; auto-merge via CircleCI on Dependabot branches **or** Renovate on CircleCI |
 | `triage.yml` | CircleCI pipeline trigger on `issues` via GitHub Apps webhook → CircleCI API, or GitHub Action **stub** only if product accepts residual GHA (conflicts with CC1 — prefer webhook) |
 | `roadmap-generate` | Scheduled CircleCI job with `ROADMAP_PROJECT_TOKEN` |
-| `architectural-pr-review` | CircleCI job + `CURSOR_API_KEY` (lose `pull_request_target` free fork safety — use least privilege + fork policy) |
+| `architectural-pr-review` | Implemented: CircleCI job + `CURSOR_API_KEY` / `GITHUB_TOKEN`. Checks out `origin/master`, skips forks. GHA workflow is `on: []`. |
+| Cursor Approval / Security / Bugbot | **Cannot move.** Cursor GitHub App automations, not repo workflows. |
 | `agentics-maintenance` + `*.lock.yml` gh-aw | Re-home to CircleCI scheduled pipelines calling the same scripts **or** retire features; do not leave gh-aw as the only runner if CC1 holds |
 | `docs-audit` | Scheduled CircleCI job |
 

package/src/docs/versioned/next/implementationPlans/model-router-mcp.md

@@ -1,5 +1,7 @@
 # Implementation Plan: modelRouter MCP Tools
 
+**Status:** Complete (write path now uses unified mutation executors — see [unified-mutation-executors.md](unified-mutation-executors.md); list/read remain handlers)
+
 **Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1092
 *When an engineer is assigned to a project but before you begin coding, you should fill in the implementation plan and get feedback from the engineering team. Once you have finished or you make any changes, tag Josh with the @ symbol so he can review. Also tag anyone else that needs to be notified, has conflicting work, etc.*
 
@@ -177,7 +179,7 @@ No activity logging specific to this feature. MCP tool calls go through the same
 ## Not Included / Future Work
 
 - **Rate limiting** — structured for future hooks but not implemented
-- **MCP resources/prompts** — only tools generated from modelRouter plus `registerMCPTool`
+- **MCP resources/prompts** — only tools generated from modelRouter plus `registerMCPTool`. Follow-up: [`app-mcp-server.md`](app-mcp-server.md) (prompts, resources, named servers, Better Auth OAuth 2.1, Inspector/test DX, Streamable HTTP client, hosted generators).
 - **Array operation tools** — handled via update, no dedicated push/patch/delete array tools
 - **WebSocket transport** — HTTP/SSE only
 - **Admin dashboard** — use `getMCPTools()` programmatically or MCP client tool listing