@terreno/mcp 57.17.0 → 57.18.0

package/dist/docs/versioned/57.17.0/implementationPlans/apierror-standard-error-redesign.md

@@ -0,0 +1,333 @@
+# APIError redesign — standards-first extension of Error
+
+**Status:** Complete
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1080
+**Branch:** cursor/apierror-standard-error-redesign-e24a
+**Owner:** TBD
+**Created:** 2026-07-28
+
+## Goal
+
+Redesign `APIError` (`api/src/errors.ts`) so the **standard `Error` fields carry the standard
+meaning** — `name` is the error type, `message` is the stable human-readable summary, `stack` is
+the capture site, and `cause` is the wrapped original error — and the JSONAPI extension fields
+(`status`, `code`, `detail`, `source`, `meta`, `links`, `id`) only carry the *extra* API context.
+
+The motivating symptom: tools like Sentry derive the issue headline from `error.name` and the
+subtitle from `error.message`, and walk `error.cause` for linked exceptions. Because every
+`APIError` has `name === "APIError"` and a `message` polluted with an embedded stack trace,
+unrelated errors all show up as **"APIError"** and group together, while the actual wrapped error
+is invisible to Sentry.
+
+## Non-Goals
+
+- Changing the client-facing wire format beyond clarifying `disableExternalErrorTracking` (see
+  Decisions). Frontends (`ui/src/Utilities.tsx` `isAPIError`/`printAPIError`, RTK error
+  middleware, `example-frontend/store/errors.ts`) keep reading `data.title`, `data.detail`,
+  `data.status`, `data.meta.fields`, and `data.disableExternalErrorTracking` when present.
+- Replacing the JSONAPI error model. The extension fields stay; only their relationship to the
+  standard `Error` fields changes.
+- A general error-taxonomy overhaul for consuming apps (Flourish, etc.). They get better behavior
+  for free; adopting `code`/subclasses is opt-in.
+
+## Evaluation of the current design
+
+What `APIError` does today (`api/src/errors.ts`):
+
+| Standard field | Current use | Problem |
+|---|---|---|
+| `name` | Hardcoded `"APIError"` | Every Sentry issue headline is "APIError". A 403 admin check and a 500 integration failure are indistinguishable at a glance, and type-based grouping collapses. |
+| `message` | `` `${title}: ${detail}\n${wrappedError.stack}` `` | Embedding a per-occurrence stack makes `message` unstable (defeats message-based grouping) and unreadable as a Sentry subtitle. It duplicates data Sentry would render natively from a `cause` chain. |
+| `stack` | Default (capture site) | Fine — but for framework-wrapped errors (e.g. the `preCreate hook error:` re-wraps in `api.ts`), the top frames are framework code, so unrelated app errors share a stack and group together. |
+| `cause` | Not used; a non-standard `error: unknown` field instead | Sentry's default `linkedErrors` integration walks `error.cause` and shows the chain as linked exceptions. The `error` field is invisible to it. |
+
+Additional design issues:
+
+1. **Constructor side effects.** Every construction calls `logger.error`/`logger.warn`, even when
+   the error is caught and handled, converted, or expected. Reporting belongs at the handling
+   boundary (`apiErrorMiddleware`), not at construction.
+2. **Internal config on the wire.** `getAPIErrorBody` serializes
+   `disableExternalErrorTracking` into the HTTP response body when true (needed for client-side
+   Sentry suppression). It is omitted when false/undefined.
+3. **Brittle type guard.** `isAPIError` checks `error.name === "APIError"`, which forbids ever
+   making `name` meaningful (the fix for the Sentry headline) and only exists to survive duplicate
+   `@terreno/api` instances across packages.
+4. **No `toJSON`.** `getAPIErrorBody` manually iterates a key list; the class should own its wire
+   serialization.
+5. **`title` is documented as stable per problem type (JSONAPI) but the framework violates it** —
+   e.g. `title: errorMessage(error)` and `` title: `preCreate hook error: ${errorMessage(error)}` ``
+   in `api.ts` interpolate per-occurrence text into `title`.
+6. **Sentry capture has no grouping hints.** `apiErrorMiddleware` calls
+   `Sentry.captureException(err)` bare — no fingerprint, no tags, no context from the JSONAPI
+   fields.
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| What does `message` hold? | Exactly `title` — a stable, human-readable summary of the problem type. `detail`, `fields`, and the cause stack are **never** concatenated into `message`. `title` becomes a getter aliasing `message` so the extension field and the standard field cannot drift. |
+| What does `name` hold? | The error *type*, by precedence: subclass name (via `new.target.name`) → PascalCased `code` (`"update-admin-error"` → `UpdateAdminError`) → status-derived name (`BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `InternalServerError`, …) → `APIError`. |
+| How is the wrapped error attached? | Standard ES2022 `cause`: `super(title, {cause})`. The old `error` option is kept as a deprecated alias that feeds `cause`. Sentry then renders the chain as linked exceptions with the original stack. |
+| Where does logging happen? | In `apiErrorMiddleware`, not the constructor: `warn` for 4xx, `error` for 5xx (5xx are bugs/ops issues; 4xx are mostly client mistakes). Non-HTTP boundaries (websockets, scripts) already log via `logger.catch`/`captureException`. |
+| Is `disableExternalErrorTracking` still sent to clients? | Only when `true`. It lets the frontend suppress duplicate Sentry reporting (`example-frontend/store/errors.ts`). Omitted from the wire body when false/undefined. Still suppresses server-side Sentry capture in `apiErrorMiddleware` when set. |
+| How does `isAPIError` work? | Brand property `isTerrenoAPIError = true` set in the constructor (survives duplicate package instances), with a transition fallback for `name === "APIError"`. |
+| Does Sentry still capture 4xx APIErrors? | Unchanged for now: capture everything unless `disableExternalErrorTracking`. But capture gains a fingerprint and context (below) so 4xx noise at least groups correctly. A follow-up may default 4xx to log-only. |
+| Wire body shape? | `{status, title, detail?, code?, id?, links?, source?, meta?, disableExternalErrorTracking?}`. The last field is present only when `true`. `meta.fields` unchanged. |
+
+## Architecture
+
+### New class shape (`api/src/errors.ts`)
+
+```typescript
+export interface APIErrorOptions {
+  /** Stable, human-readable summary of the problem TYPE (JSONAPI title). Becomes Error.message. */
+  title: string;
+  /** HTTP status, 400–599. Defaults to 500; out-of-range values are coerced to 500 with a warn. */
+  status?: number;
+  /** Application-specific stable error code (kebab-case). Also drives Error.name when set. */
+  code?: string;
+  /** Human-readable, per-occurrence explanation. NOT folded into message. */
+  detail?: string;
+  /** Field-level messages for forms; folded into meta.fields on the wire (unchanged). */
+  fields?: {[id: string]: string};
+  /** The original error being wrapped. Standard ES2022 Error cause. */
+  cause?: unknown;
+  /** @deprecated Use `cause`. */
+  error?: unknown;
+  id?: string;
+  links?: {about?: string; type?: string};
+  source?: {pointer?: string; parameter?: string; header?: string};
+  meta?: {[id: string]: unknown};
+  /** When true, skip Sentry capture in apiErrorMiddleware. Never serialized to clients. */
+  disableExternalErrorTracking?: boolean;
+}
+
+export class APIError extends Error {
+  /** Brand for cross-package instanceof-free detection. */
+  readonly isTerrenoAPIError = true as const;
+
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly detail: string | undefined;
+  readonly id: string | undefined;
+  readonly links: {about?: string; type?: string} | undefined;
+  readonly source: {pointer?: string; parameter?: string; header?: string} | undefined;
+  readonly meta: {[id: string]: unknown};
+  readonly disableExternalErrorTracking: boolean | undefined;
+
+  constructor(options: APIErrorOptions) {
+    // message = title, nothing else. cause = the wrapped error, natively understood by Sentry.
+    super(options.title, {cause: options.cause ?? options.error});
+    this.status = normalizeStatus(options.status); // 500 default, 400–599 enforced
+    this.code = options.code;
+    // name precedence: subclass > code > status. `new.target` keeps subclass names automatically.
+    this.name =
+      new.target !== APIError
+        ? new.target.name
+        : (options.code ? pascalCase(options.code) : nameForStatus(this.status));
+    this.detail = options.detail;
+    this.id = options.id;
+    this.links = options.links;
+    this.source = options.source;
+    this.meta = {...options.meta, ...(options.fields ? {fields: options.fields} : {})};
+    this.disableExternalErrorTracking = options.disableExternalErrorTracking;
+    // No logging here. Reporting happens where the error is handled.
+  }
+
+  /** JSONAPI title === Error.message; a getter so the two can never drift. */
+  get title(): string {
+    return this.message;
+  }
+
+  /** Client-facing JSONAPI body. Excludes name/stack/cause; includes disableExternalErrorTracking when true. */
+  toJSON(): APIErrorBody {
+    ...
+  }
+}
+```
+
+`nameForStatus` maps common statuses (`400 BadRequestError`, `401 UnauthorizedError`,
+`403 ForbiddenError`, `404 NotFoundError`, `409 ConflictError`, `422 ValidationError`,
+`429 TooManyRequestsError`, `500 InternalServerError`, `502/503/504` gateway names) and falls back
+to `APIError` for anything unmapped.
+
+### What Sentry sees, before vs. after
+
+```text
+Before:  APIError
+         Only an admin can update that!: You must be an admin...\nError: inner\n  at ...
+
+After:   ForbiddenError            (or UpdateAdminError when code is set)
+         Only an admin can update that!
+         └─ caused by TypeError: Cannot read properties of undefined   (linked exception, own stack)
+```
+
+### Middleware changes (`apiErrorMiddleware`)
+
+```typescript
+if (isAPIError(err)) {
+  const logMessage = `${err.name}(${err.status}): ${err.message}${err.detail ? ` — ${err.detail}` : ""}`;
+  if (err.status >= 500) {
+    logger.error(logMessage);   // moved here from the constructor
+  } else {
+    logger.warn(logMessage);
+  }
+  if (!err.disableExternalErrorTracking) {
+    Sentry.withScope((scope) => {
+      // Group by logical error type, not by whichever framework frame constructed it.
+      scope.setFingerprint([err.name, err.code ?? err.message, String(err.status)]);
+      scope.setTag("http.status_code", String(err.status));
+      if (err.code) {
+        scope.setTag("api_error.code", err.code);
+      }
+      scope.setContext("apiError", err.toJSON()); // detail, source, meta.fields, etc.
+      Sentry.captureException(err);
+    });
+  }
+  res.status(err.status).json(err.toJSON());
+  return;
+}
+```
+
+The explicit fingerprint fixes the second half of the reported problem: today all framework-thrown
+`APIError`s share near-identical construction stacks inside `api.ts`, so Sentry's default
+stack-trace grouping lumps unrelated errors together. Fingerprinting on
+`name + (code ?? title) + status` groups by problem type instead, while the `cause` chain
+preserves each occurrence's real origin stack for debugging.
+
+### Optional convenience subclasses (phase 2)
+
+For the most common statuses, thin subclasses give static `name`s, less boilerplate, and free
+`instanceof` narrowing. They are sugar only — everything works with plain `APIError`:
+
+```typescript
+export class NotFoundError extends APIError {
+  constructor(options: Omit<APIErrorOptions, "status"> | string) {
+    super(typeof options === "string" ? {status: 404, title: options} : {...options, status: 404});
+  }
+}
+// BadRequestError, UnauthorizedError, ForbiddenError, ConflictError, ValidationError, InternalError
+```
+
+`mongooseErrorToAPIError` would return `ValidationError` instances (name "ValidationError",
+status 400) instead of generic `APIError({title: "Validation failed"})`.
+
+### Framework call-site cleanup (`api/src/api.ts`)
+
+The re-wrap sites currently interpolate the inner message into `title`. With `cause`, `title`
+becomes stable and per-occurrence text moves to `detail`:
+
+```typescript
+// Before
+throw new APIError({title: `preCreate hook error: ${errorMessage(error)}`, error, status: 400, ...});
+
+// After
+throw new APIError({
+  cause: error,
+  code: "pre-create-hook-error",       // -> name PreCreateHookError
+  detail: errorMessage(error),
+  disableExternalErrorTracking: getDisableExternalErrorTracking(error),
+  status: 400,
+  title: "preCreate hook failed",
+});
+```
+
+Same pattern for `preUpdate`/`preDelete`/`postCreate`/`postUpdate`, `Populate error`,
+`responseHandler error`, and `Query filter error` sites.
+
+## Models
+
+No model changes. `errorsPlugin` (the `apiErrors` subdocument schema) already stores only the
+JSONAPI extension fields and is unaffected.
+
+## APIs
+
+- **Wire format:** `disableExternalErrorTracking` is included in the body only when `true`.
+- **Public exports:** `APIError`, `APIErrorOptions` (new; `APIErrorConstructor` kept as a
+  deprecated alias), `isAPIError`, `errorMessage`, `errorStack`,
+  `getDisableExternalErrorTracking`, `mongooseErrorToAPIError`, middlewares — all keep their
+  names. `getAPIErrorBody` becomes a deprecated wrapper around `error.toJSON()`.
+- **`isAPIError`:** checks the `isTerrenoAPIError` brand (plus a transition-period fallback for
+  `name === "APIError"` to accept instances from older `@terreno/api` versions in mixed
+  node_modules).
+
+## Notifications
+
+None.
+
+## UI
+
+No UI changes required. `ui/src/Utilities.tsx` `isAPIError` (checks `data.title`) and
+`printAPIError` (reads `data.title`/`data.detail`) continue to work; `title` remains the stable
+summary and `detail` the occurrence-specific text.
+
+## Phases
+
+1. **Core class** — rewrite `APIError` (message=title, name derivation, `cause`, brand, `toJSON`,
+   no constructor logging); update `isAPIError`, deprecate `getAPIErrorBody`; move logging +
+   Sentry scope/fingerprint into    `apiErrorMiddleware`; update `errors.test.ts`, `api.hooks.test.ts` (assert
+   `res.body.disableExternalErrorTracking` when the flag is set),
+   `api.errors.test.ts`, `permissions.middleware.test.ts`, `docLoader.test.ts`.
+2. **Framework call sites** — stabilize `title` + move per-occurrence text to `detail`/`cause` in
+   `api.ts`, `openApiValidator.ts`, `permissions.ts`, `auth.ts`, `plugins.ts`, and add `code`
+   where a stable identity helps grouping. Introduce the convenience subclasses and use
+   `ValidationError` in `mongooseErrorToAPIError`.
+3. **Downstream packages** — `admin-backend`, `feature-flags`, `ai`, `example-backend`: swap
+   `error:` for `cause:` and adopt `code`/subclasses opportunistically. Regenerate website
+   reference docs (`update-docs` skill).
+
+## Feature Flags & Migrations
+
+None. No stored data changes. The behavior changes (Sentry titles/grouping, log level for 4xx,
+dropped response flag) ship with a minor version bump and a changelog entry; consuming apps need
+no code changes unless they asserted on the removed response field or the exact `name` string.
+
+## Activity Log & User Updates
+
+N/A.
+
+## Not Included / Future Work
+
+- Defaulting 4xx APIErrors to log-only (no Sentry capture) unless opted in.
+- An RFC 9457 (`application/problem+json`) response mode. The JSONAPI error object is close
+  (`title`/`detail`/`status` align); `links.about` ≈ `type`. Not worth a wire break now.
+- Client-side (RTK) typed error codes generated from the OpenAPI spec.
+
+## Files to Create / Modify
+
+As implemented:
+
+- `api/src/errors.ts` — core redesign (class, name/status maps, subclasses, `toJSON`, middleware).
+- `api/tsconfig.json` — add `es2022.error` to `lib` for the standard `ErrorOptions`/`cause` types.
+- `api/src/api.ts`, `api/src/transformers.ts`, `api/src/httpClient.ts`, `api/src/config.ts`,
+  `api/src/docLoader.ts` — stable titles, `cause`, `code` at every wrap site (phase 2).
+  `permissions.ts`, `auth.ts`, `plugins.ts`, and `openApiValidator.ts` needed no changes — they
+  already used stable titles without wrapped errors.
+- Tests: `api/src/errors.test.ts`, `api/src/api.errors.test.ts`, `api/src/api.hooks.test.ts`,
+  `api/src/api.test.ts`, `api/src/api.errorPaths.test.ts`, `api/src/notifiers/*.test.ts`,
+  `ai/src/langfuseRoutesMiddleware.test.ts` — updated expectations plus new coverage for name
+  derivation, `cause`, subclasses, `toJSON`, and the Sentry fingerprint.
+- Downstream packages had no `error:` usages, so phase 3 required no code changes.
+- Docs: `.rulesync/rules/api/00-api.md` error-handling section (mirrors regenerated with
+  `bun run rules`).
+
+## Task List
+
+Implemented directly on this branch (all three phases); no separate tasks file.
+
+## Acceptance Criteria
+
+- [x] `new APIError({status: 404, title: "Todo not found"})` has `name === "NotFoundError"`,
+      `message === "Todo not found"`, `title === "Todo not found"`, and a clean single-line message.
+- [x] `new APIError({title: "X", cause: inner})` exposes `error.cause === inner` and Sentry shows
+      the inner error as a linked exception with its own stack.
+- [x] Sentry issue headline shows the derived/subclass name (never a bare "APIError" for errors
+      with a mapped status or code), and two errors with different `name`/`code` never share an
+      issue (fingerprint on `name + code + status`, falling back to `name` when `code` is absent).
+- [x] Constructing an APIError produces no log output; handling one through `apiErrorMiddleware`
+      logs `warn` (4xx) or `error` (5xx) exactly once.
+- [x] Response bodies keep `{status, title, detail, code, meta.fields, ...}`; include
+      `disableExternalErrorTracking` only when `true`; never include `name`, `stack`, or `cause`.
+- [x] `isAPIError` returns true across duplicate `@terreno/api` copies and for subclasses.
+- [x] `bun run api:test` passes; `bun run lint` passes for all touched packages (the pre-existing
+      `@terreno/ui` `ConsentNavigator.tsx` floating-promise failures are unrelated).

package/dist/docs/versioned/57.17.0/implementationPlans/app-mcp-server.md

@@ -0,0 +1,320 @@
+# Implementation Plan: App MCP server
+
+**Status:** Draft  
+**Roadmap:** Area=`mcp`, Target=`Future`, Impact=`Feature`  
+**Created:** 2026-08-24  
+**Owner:** unassigned  
+**Depends on:** [model-router-mcp.md](model-router-mcp.md) (shipped), [mcp-boost-parity.md](mcp-boost-parity.md) (dev-time MCP — sibling, not a blocker)  
+**Roadmap issue:** TBD after Approve (`roadmap-item`)
+
+Follow-up to the Boost IP. That plan is the **development-time** MCP (`@terreno/mcp` + `terreno-mcp-local`): agents writing Terreno apps. This plan is the **running app** as an MCP server: ChatGPT, Claude, Cursor, Inspector, and in-app agents calling the consumer backend.
+
+## Goal
+
+A Terreno backend exposes a complete MCP product surface — tools, prompts, resources, named HTTP servers, OAuth 2.1 for remote clients, Inspector/test DX, a Streamable HTTP client, and hosted generators for those primitives — without giving up generated CRUD tools that stay aligned with `modelRouter` permissions.
+
+When this is done, an operator can:
+
+1. Keep `mcp: { methods: ["list", "read"] }` on `modelRouter` (already shipped).
+2. Register a custom tool / prompt / resource with the same auth user as REST.
+3. Optionally mount a second server at `/mcp/admin` (or similar) with a subset of primitives.
+4. Connect remote MCP clients via Better Auth OAuth 2.1 (discovery + PKCE + access token), while JWT/session bearer still works for Inspector and in-app hooks.
+5. Hit the endpoint with MCP Inspector and assert tool calls in Bun tests without speaking JSON-RPC by hand.
+6. Use `@terreno/ai` `MCPService` over Streamable HTTP (the transport `/mcp` already speaks).
+7. Ask the hosted `@terreno/mcp` to emit `defineMCPTool` / `defineMCPPrompt` / `defineMCPResource` snippets.
+
+## Non-goals
+
+| Out | Why |
+| --- | --- |
+| Hosted `@terreno/mcp` docs search, local CDP logs, simulator control | Boost IP |
+| MCP Apps (`ui://` HTML iframes) | Spec still moving; no Terreno UI host |
+| Class-hierarchy primitive APIs | TS factories + hosted snippet generators |
+| stdio transport for **app** MCP | Product path is HTTP; local stdio is the Boost companion |
+| Streaming/progress generators, resource subscriptions | Defer |
+| Changing generated CRUD tool names or default read-only methods | Compat |
+| Privileged infra tools (GCP, Sentry, …) | [infra-mcp.md](infra-mcp.md) — reuse the same Better Auth MCP OAuth plugins, different host |
+
+## Why this is a separate IP
+
+| Layer | Terreno today |
+| --- | --- |
+| Dev-time (“teach the agent the framework”) | `@terreno/mcp` + Boost IP |
+| Runtime (“the app *is* an MCP server”) | `modelRouter` `mcp` + `registerMCPTool` on `POST /mcp` |
+
+[model-router-mcp.md](model-router-mcp.md) deferred resources and prompts. Generated CRUD is already the differentiator (`mcp:` on `modelRouter` ⇒ permissioned tools). This IP fills the rest of the MCP server kit: prompts, resources, named mounts, remote-client OAuth, test/Inspector DX, client transport, and generators.
+
+## Current code (leaves)
+
+| Seam | Behavior |
+| --- | --- |
+| `api/src/mcp/server.ts` `mountMCPServer` | Stateless `createMcpHandler`, `POST /mcp`, tools capability only |
+| `api/src/mcp/toolGenerator.ts` | `{prefix}_{list,read,create,update,delete}` from registry |
+| `api/src/mcp/registry.ts` `registerMCPTool` | Custom tools: `name`, `description`, `zodSchema`, `handler` |
+| Auth | `extractUserFromHeaders` — opt-in `mcp_` [service tokens](mcp-service-tokens.md), then Better Auth session, then JWT. No OAuth 2.1 resource server yet; no RFC 9728 metadata. Operator how-to: [Connect an MCP client with a service token](../how-to/connect-mcp-service-token.md) |
+| `@terreno/ai` `MCPService` | **SSE** client only — mismatch with Streamable HTTP server |
+| `@terreno/rtk` `useMCPTools` | Official MCP client, Streamable HTTP to `/mcp` |
+| Tests | Registry/handler/integration tests; no Inspector helper, no prompt/resource tests |
+| `@terreno/mcp` | Codegen for models/routes/screens; no generators for app MCP primitives |
+
+## Decisions
+
+| ID | Question | Choice |
+| --- | --- | --- |
+| Q1 | Scope vs Boost | **App MCP on `@terreno/api`.** Hosted `@terreno/mcp` only gains generators *of* app primitives (Q12). |
+| Q2 | Primitive shape | **Factories:** `defineMCPTool` / `defineMCPPrompt` / `defineMCPResource` wrapping `registerMCP*`. |
+| Q3 | Default endpoint | **Keep `/mcp`.** Additive capabilities. No rename. |
+| Q4 | Multiple servers | **Yes, v1.** Named mounts with explicit include lists. Default `/mcp` remains the union of CRUD + globally registered primitives. Extra servers are opt-in and do not auto-include every model tool. |
+| Q5 | Auth | **Bearer (JWT + Better Auth session) plus OAuth 2.1 for MCP** via Better Auth (`@better-auth/mcp` + `@better-auth/oauth-provider`). Same User as REST after token exchange. JWT-only apps get the Terreno-native `mcpOAuth` authorization server instead (#1573); with `mcpOAuth` off they keep bearer-only and mount no OAuth metadata. |
+| Q6 | Tool metadata | **MCP spec hints:** `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, plus optional `outputSchema` + `structuredContent`. |
+| Q7 | Conditional register | **`shouldRegister(user)`** (and optional `shouldRegister: false`). Filter list methods and reject call/get/read if hidden. |
+| Q8 | Response helper | **`mcpResult.text` / `.json` / `.error`.** Images/audio out. |
+| Q9 | Client | **Upgrade `MCPService` to Streamable HTTP**; add list/get prompts and list/read resources. Named clients stay a `Record` keyed by name. |
+| Q10 | MCP Apps / streaming | **Out.** OAuth is in (Q5), not in this row. |
+| Q11 | Test DX | **`invokeMCPTool` / `invokeMCPPrompt` / `readMCPResource`** against an in-process Express app. Document MCP Inspector; do not vendor Inspector. |
+| Q12 | Codegen on hosted MCP | **In.** `terreno_generate_mcp_tool`, `terreno_generate_mcp_prompt`, `terreno_generate_mcp_resource` on `@terreno/mcp` emit factory snippets. Required, not optional. |
+
+## Architecture
+
+```
+MCP client (Inspector, Claude, ChatGPT, useMCPTools, MCPService)
+        │  Bearer JWT/session  OR  OAuth 2.1 access token (Better Auth)
+        ▼
+ POST /mcp              ← default union (CRUD + global registerMCP*)
+ POST /mcp/:serverName  ← optional named server (explicit primitives)
+ GET  /.well-known/oauth-protected-resource   ← RFC 9728 (Better Auth on)
+        │
+        ├─ tools     (generated CRUD + defineMCPTool)
+        ├─ prompts   (defineMCPPrompt)
+        └─ resources (defineMCPResource)
+              │
+              ▼
+     same User as REST → permissions / queryFilter / hooks
+```
+
+### Public API (target)
+
+```typescript
+import {
+  defineMCPPrompt,
+  defineMCPResource,
+  defineMCPTool,
+  mcpResult,
+  mountMCPServer,
+} from "@terreno/api";
+import {z} from "zod";
+
+defineMCPTool({
+  name: "weather_current",
+  description: "Current forecast for a city.",
+  annotations: {readOnlyHint: true, openWorldHint: true},
+  zodSchema: z.object({city: z.string()}),
+  outputSchema: z.object({tempC: z.number(), summary: z.string()}),
+  shouldRegister: (user) => Boolean(user),
+  handler: async ({city}, user) => {
+    return mcpResult.json({tempC: 22, summary: `Clear in ${city}`});
+  },
+});
+
+defineMCPPrompt({
+  name: "weather_briefing",
+  description: "Ask the model to summarize weather for a user.",
+  arguments: [{name: "city", required: true, description: "City name"}],
+  handler: async ({city}) => ({
+    messages: [{role: "user", content: {type: "text", text: `Brief the weather in ${city}.`}}],
+  }),
+});
+
+defineMCPResource({
+  uri: "weather://guidelines",
+  name: "weather_guidelines",
+  mimeType: "text/markdown",
+  handler: async () => mcpResult.text("# Use metric units."),
+});
+
+mountMCPServer(expressApp, {
+  path: "/mcp/weather",
+  name: "weather",
+  instructions: "Weather tools only.",
+  tools: ["weather_current"],
+  prompts: ["weather_briefing"],
+  resources: ["weather://guidelines"],
+});
+```
+
+`defineMCP*` is sugar over `registerMCP*` (same registry). Existing `registerMCPTool` calls keep working.
+
+`TerrenoApp` continues to auto-mount `/mcp` when the registry is non-empty. Named extra servers are registered via `app.mcpServer({path, ...})` or `mountMCPServer` in `configureApp`.
+
+CRUD tools get annotations: list/read `readOnlyHint: true`; create/update `idempotentHint: false`; delete `destructiveHint: true`.
+
+### Auth (Q5)
+
+Remote MCP clients (Claude connectors, ChatGPT, Cursor HTTP) expect **OAuth 2.1** with protected-resource metadata, not a hand-pasted JWT.
+
+**When Better Auth is enabled** (`BetterAuthApp` / `AUTH_PROVIDER=better-auth`):
+
+1. Add `@better-auth/mcp` and `@better-auth/oauth-provider` to `@terreno/api`, same plugins [infra-mcp.md](infra-mcp.md) plans to use.
+2. Register the MCP plugin on the Better Auth instance Terreno already builds (login page = existing Better Auth sign-in).
+3. Serve RFC 9728 `/.well-known/oauth-protected-resource` (and authorization-server discovery that the plugin provides, typically under the Better Auth base path).
+4. On unauthenticated `/mcp` requests, return **401** with `WWW-Authenticate` pointing at that metadata (MCP authorization spec).
+5. Extend `extractUserFromHeaders` to accept an OAuth access token on `Authorization: Bearer`, resolve it through Better Auth, then load the app `User` by `betterAuthId` — same mapping as session cookies today.
+6. Keep JWT verification as a fallback so Inspector, tests, and `useMCPTools` keep working with session/JWT bearer.
+
+**When Better Auth is off (JWT-only):** set `mcpOAuth: {enabled: true, …}` to mount the Terreno-native OAuth 2.1 authorization server ([Enable MCP OAuth](../how-to/enable-mcp-oauth.md)). It serves the RFC 9728 and RFC 8414 documents, authorize/consent, token, and revoke, and `/mcp` answers unauthenticated requests with the 401 challenge. Dynamic client registration is a second opt-in (`dynamicClientRegistration: true`), off by default because the endpoint is unauthenticated and lets anyone create a client; without it the app creates `McpOAuthClient` documents itself. Revoking a token family writes a tombstone that `McpOAuthToken.issue` honors, so in-flight exchanges cannot revive it. The app hosts the consent screen. Bearer JWT keeps working. With `mcpOAuth` off, no OAuth metadata mounts and bearer behavior is unchanged.
+
+**Not in this IP:** social login providers (already documented); infra-mcp’s RBAC/elicitation; replacing Passport JWT for REST.
+
+Align plugin versions with the infra-mcp catalog pins so the two servers do not fork OAuth behavior.
+
+### Client (`@terreno/ai`)
+
+`MCPService` transport becomes Streamable HTTP (SDK `StreamableHTTPClientTransport` or AI SDK equivalent). Keep SSE as `transport: "sse"` for old servers. Add `listPrompts` / `getPrompt` / `listResources` / `readResource`. Optional `auth: { oauth: ... }` can wait until the server OAuth path exists; bearer header injection stays the default for in-process agents.
+
+`getMCPTools` (in-process) includes custom tools unchanged; prompts/resources stay MCP-protocol-only unless a later IP asks for in-process prompt runners.
+
+### Testing
+
+```typescript
+const res = await invokeMCPTool(app, {
+  name: "weather_current",
+  arguments: {city: "Austin"},
+  user: adminUser,
+});
+expect(res.isError).toBe(false);
+```
+
+Helper authenticates as `user`, POSTs `tools/call` (or uses the SDK), returns parsed result. OAuth tests cover: 401 + `WWW-Authenticate` without a token; a Better Auth–issued access token maps to the same user as REST.
+
+### Hosted generators (Q12)
+
+On `@terreno/mcp` (hosted HTTP server, not `terreno-mcp-local`):
+
+| Tool | Emits |
+| --- | --- |
+| `terreno_generate_mcp_tool` | `defineMCPTool({...})` snippet |
+| `terreno_generate_mcp_prompt` | `defineMCPPrompt({...})` snippet |
+| `terreno_generate_mcp_resource` | `defineMCPResource({...})` snippet |
+
+Inputs: name, description, input fields (tool), arguments (prompt), URI/mime (resource). Output is TypeScript that typechecks against the public factories. Tool descriptions tell agents to prefer these over inventing `registerMCPTool` shapes.
+
+## Docs (same slice as code — Pick)
+
+| Diátaxis | Page |
+| --- | --- |
+| Explanation | `docs/explanation/app-mcp.md` — two MCP layers (Boost vs app), generated CRUD vs registered primitives, Better Auth OAuth vs JWT bearer |
+| How-to | Expand `docs/how-to/expose-mcp-tools.md`; add `docs/how-to/add-mcp-prompts-and-resources.md`; Inspector; `docs/how-to/secure-app-mcp.md` (OAuth + bearer) |
+| Reference | `docs/reference/api.md` MCP section: factories, annotations, named servers, OAuth well-known routes; `docs/reference/mcp-server.md` generator tools |
+| Example | `example-backend` registers one prompt + resource + annotated custom tool; README for Inspector and OAuth when Better Auth is on |
+
+`update-docs` on every phase that changes public API. Bundled `@terreno/mcp` resources that mention app MCP must match.
+
+## Phases
+
+### Phase 1 — Prompts, resources, richer tools on `/mcp`
+
+Tracer: example-backend custom tool already exists (`users_todo_statuses`). Add one prompt + one resource; Inspector `prompts/list` and `resources/list` succeed with a bearer token.
+
+- Registry for prompts/resources; `shouldRegister`; annotations; `outputSchema` / structured content when SDK supports it; `mcpResult`.
+- `mountMCPServer` advertises `prompts` and `resources` capabilities. **Mount `/mcp` when any primitive exists**, not only when `getAllMCPTools().length > 0`.
+- Tests: list/call/get/read; hidden primitive absent from list and rejected on call; CRUD tools still work.
+
+### Phase 2 — Named HTTP servers
+
+- `mountMCPServer(app, {path, name, instructions, tools?, prompts?, resources?})`.
+- Default `/mcp` union unchanged when extra servers exist.
+- Empty include list on a named server ⇒ that primitive kind empty (no surprise CRUD leak).
+- Tests: tool on `/mcp` not listed on `/mcp/weather` unless included.
+
+### Phase 3 — Factories + hosted generators
+
+- Export `defineMCPTool|Prompt|Resource`.
+- Example-backend uses `defineMCP*` for the tracer primitives.
+- Hosted MCP tools `terreno_generate_mcp_tool|prompt|resource` (required).
+
+### Phase 4 — Inspector + `invokeMCP*`
+
+- Test helpers in `api/src/mcp/testHelpers.ts` (or `api/src/tests/` if that is the existing helper home).
+- How-to: `bunx @modelcontextprotocol/inspector` against example-backend `/mcp`.
+- Assertions: `isError`, text contains, structured JSON.
+
+### Phase 5 — `MCPService` Streamable HTTP + prompts/resources
+
+- Default HTTP transport matches server.
+- Tests with a mock Streamable HTTP server or example-backend.
+- `useMCPTools` already HTTP — no change unless headers break.
+
+### Phase 6 — MCP OAuth 2.1 via Better Auth
+
+- Catalog deps: `@better-auth/mcp`, `@better-auth/oauth-provider` as required by that plugin.
+- Wire plugin in Better Auth setup used by `BetterAuthApp`.
+- RFC 9728 + 401 `WWW-Authenticate` on `/mcp`.
+- `extractUserFromHeaders` accepts OAuth access tokens.
+- JWT-only apps unchanged by this phase: they use the Terreno-native `mcpOAuth` server (#1573, [Enable MCP OAuth](../how-to/enable-mcp-oauth.md)). Reuse its well-known builders (`buildProtectedResourceMetadata`, `buildAuthorizationServerMetadata`) and `/mcp` challenge (`sendMcpOAuthChallenge`) from `api/src/mcp/oauthMetadata.ts`, which does not depend on the JWT authorization-server routes, so both stacks share one code path.
+- How-to `docs/how-to/secure-app-mcp.md`; reference well-known paths.
+- Tests with Better Auth test instance: no token → 401 challenge; valid access token → `tools/list` as that user.
+
+## Notifications
+
+None.
+
+## UI
+
+No new screens. Example-frontend chat already uses MCP tools; optional follow-up to surface prompt names is out of scope. OAuth consent uses Better Auth’s existing login page.
+
+## Feature flags & migrations
+
+None. Additive APIs. `registerMCPTool` signature may gain optional fields only. OAuth is additive when Better Auth is on.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| MCP SDK prompt/resource APIs differ by SDK version | Pin to the SDK `createMcpHandler` already uses; wrap in `api/src/mcp/` |
+| Tool list cardinality explodes with CRUD × models × extras | Named servers + `shouldRegister`; docs tell operators to split |
+| `MCPService` SSE clients in the wild | Keep `transport: "sse"`; default new HTTP |
+| Structured output clients ignore `outputSchema` | Always include a text content part |
+| Better Auth MCP plugin vs current session extraction | One `extractUserFromHeaders` pipeline: session → OAuth token → JWT |
+| Duplicate OAuth stacks vs infra-mcp | Same plugins and catalog versions; different Express app |
+| Dynamic client registration abuse | Follow plugin defaults; document production redirect allowlists |
+
+## Future work (not this IP)
+
+- MCP Apps / `ui://` HTML
+- Resource templates (`weather://forecast/{city}`) if SDK templates are stable
+- Progress notifications / streaming tool handlers
+- Rate limiting (already deferred on model-router-mcp)
+- MCPService performing the OAuth redirect dance itself (server + bearer is v1)
+
+## Files to create / modify (expected)
+
+| Area | Files |
+| --- | --- |
+| API | `api/src/mcp/registry.ts`, `server.ts`, `toolGenerator.ts`, `types.ts`, `auth.ts`, new `prompts.ts` / `resources.ts` / `result.ts` / `testHelpers.ts` + tests |
+| Better Auth | `api/src/betterAuthSetup.ts` (or equivalent), `package.json` catalog deps |
+| App | `api/src/terrenoApp.ts`, `api/src/index.ts` |
+| AI | `ai/src/service/mcpService.ts` + tests |
+| Hosted MCP | `mcp-server/src/tools.ts` + tests |
+| Example | `example-backend` MCP module + README |
+| Docs | explanation + how-tos + `docs/reference/api.md` + `docs/reference/mcp-server.md` |
+
+## Task list
+
+[`docs/tasks/app-mcp-server.md`](../tasks/app-mcp-server.md)
+
+## Acceptance criteria
+
+- [ ] `prompts/list` and `resources/list` work on `/mcp` when primitives are registered
+- [ ] `shouldRegister: false` hides the primitive from list and call
+- [ ] CRUD tools keep REST permission behavior
+- [ ] A named server at a second path exposes only its include list
+- [ ] `invokeMCPTool` can assert a successful custom tool in Bun tests
+- [ ] `MCPService` can list tools over Streamable HTTP against `mountMCPServer`
+- [ ] Better Auth on: unauthenticated `/mcp` returns 401 with resource metadata; a valid OAuth access token runs tools as that user
+- [ ] JWT-only with `mcpOAuth` off: existing bearer behavior unchanged; no OAuth well-known mounted
+- [ ] JWT-only with `mcpOAuth` on: RFC 9728/8414 documents mount, unauthenticated `/mcp` returns the 401 challenge, and bearer JWT still works
+- [ ] `mcpOAuth` on without `dynamicClientRegistration`: `/oauth/register` is 404, metadata has no `registration_endpoint`, and an app-created client completes the flow
+- [ ] A revoked token family stays revoked when a concurrent refresh or code exchange issues after the revoke
+- [ ] Hosted `terreno_generate_mcp_tool|prompt|resource` return TypeScript matching the factories
+- [ ] Docs: two MCP layers; prompts/resources; Inspector; OAuth vs bearer; generator tools
+- [ ] `registerMCPTool` without new fields still typechecks and runs