@terreno/mcp 57.1.0 → 57.3.0

package/dist/docs/versioned/next/implementationPlans/ai-observability.md

@@ -0,0 +1,348 @@
+# Implementation Plan: AI observability (Langfuse-light, pluggable)
+
+**Status:** Draft  
+**Created:** 2026-08-24  
+**Owner:** unassigned  
+**Branch:** `cursor/ai-observability-ip-64ca`  
+**Task list:** [docs/tasks/ai-observability.md](../tasks/ai-observability.md)  
+**Linear:** none  
+**Roadmap issue:** none yet (handoff after Approved)
+
+**Depends on:** current `@terreno/ai` (`AIService`, `AIRequest`, `LangfuseApp`, `AIAdminApp`). The requested `ai-agents-and-failover` IP is **not in this repo**; this plan follows shipped AI code, not that missing doc.
+
+**Related:** [terreno-langfuse-integration.md](./terreno-langfuse-integration.md) (`LangfuseApp` stays). [FH-48](https://linear.app/flourish-health/issue/FH-48/ai-improvements) (prompts in-app vs Langfuse).
+
+## Goal
+
+Ship **Langfuse-like** prompt versioning, nested traces (user / session / cost), multidimensional evaluators (LLM-as-judge + structured I/O), datasets, experiments, and a **local human review queue** — **inside Terreno**, as **plugins on `@terreno/ai`**, with an operator UI in **`admin-frontend` only**.
+
+Apps can:
+
+- Run **fully local** (Mongo) with zero Langfuse keys.
+- Keep **`LangfuseApp` as a second plugin** (not deleted, not merged).
+- Fan out **traces and scores** to local + Langfuse + **OTLP/OpenInference** (Phoenix, Laminar, Arize AX, generic collectors).
+- Point **prompts, datasets, experiments** at local **or** Langfuse independently (with one mix rule).
+
+## Non-goals
+
+- Removing or rewriting `LangfuseApp`.
+- `admin-spa` screens (spa already embeds `admin-frontend` widgets).
+- First-class Braintrust, Helicone, LangSmith, Weave, Opik, Portkey adapters (document how they fit; do not code stubs).
+- Langfuse **annotation queues** as `reviewQueue.primary` (local Mongo queue only in this IP).
+- Dual-write of prompt versions, datasets, or review items.
+- Retention / redaction / retry **jobs** (full I/O stored; Q9=C, Q13=A).
+- Replacing `AIRequest` (cheap call log remains).
+- Pixel-clone of Langfuse Cloud chrome.
+
+## Decisions
+
+| ID | Question | Choice |
+| --- | --- | --- |
+| Q1 | System of record | Mongo **local plugin** + **pluggable** backends (Langfuse and others), not wrap-only |
+| Q2 | Package | Grow `@terreno/ai` |
+| Q3 | Existing Langfuse | **Two plugins**: keep `LangfuseApp`; add local observability plugin |
+| Q4 | Operator UI | **`admin-frontend` only** |
+| Q5 | IP shape | **One IP**, full destination, **phased tasks** |
+| Q6 / Q11 | Dual receive | **Traces + scores + OTel** fan-out. Not prompts/datasets/queue |
+| Q7 | SDK | Capability interfaces + `capabilities` (comms-style) |
+| Q8 | v1 adapters | `local` (full) + `langfuse` (mapped) + **`otel` TraceSink** |
+| Q9 | PHI / I/O | Persist **full I/O**; **no** retention job in this IP |
+| Q10 | Langfuse UI | Terreno screens + **Open in Langfuse** for playground / Langfuse experiments |
+| Q12 / Q16 / Q21 | Primaries | Four flags: `prompts`, `datasets`, `experiments`, `reviewQueue` |
+| Q22 | Mix rule | `experiments.primary` **must equal** `datasets.primary` (fail config) |
+| Q23 | Defaults | All four primaries **`local`** when both plugins exist; Langfuse/OTel are extra **sinks** |
+| Q24 | Local off | **Allowed** (Langfuse-only app; no Mongo observability collections) |
+| Q25 | Review queue | **Local-only**; `reviewQueue.primary: "langfuse"` is a **config error** |
+| Q13 | Secondary down | Local (or primary write) **succeeds**; Langfuse/OTel errors **logged, never thrown** |
+| Q14 / Q17 | Experiments | Runner follows **`experiments.primary`**: local → always **`BackgroundTask`**; Langfuse → Langfuse experiment API |
+| Q15 | Mongo | **New collections**; keep `AIRequest` |
+| Q18 | Live evals | Interceptor with **`sampleRate` default `0`** |
+| Q19 | Cost | `inputTokens` / `outputTokens` / `model`; **USD from config price map** (missing model → tokens only) |
+| Q20 | Instrumentation | If observability is registered, **`AIService` emits traces** on every `generate*` (**opt-out per call**) |
+
+### Competitor coverage (why the SDK is split)
+
+| Backend | TraceSink | PromptRegistry | Dataset / experiment | ScoreSink | ReviewQueue |
+| --- | --- | --- | --- | --- | --- |
+| Local Mongo | yes | yes | yes | yes | yes (v1) |
+| Langfuse | yes | yes | yes | yes | no in v1 |
+| OTLP / OpenInference | yes | no | no | no | no |
+| Phoenix / Laminar / Datadog | via OTel | no | no | no | no |
+| Helicone / Portkey | later (gateway) | no | no | no | no |
+| Braintrust / LangSmith | later | later | later | later | later |
+
+Traces use **OpenTelemetry + OpenInference** span kinds (`LLM`, `AGENT`, `CHAIN`, `TOOL`, `EVALUATOR`, `PROMPT`). That is the honest “works with competitors” layer. Prompt/dataset/queue APIs stay vendor CRUD behind Terreno interfaces.
+
+## Architecture
+
+```
+AIService.generate*
+        │
+        ├─ AIRequest.logRequest          (unchanged cheap log)
+        └─ if observability registered and !opts.skipTrace
+              Observability.traceSinks[]  →  local | langfuse | otel   (fan-out, best-effort)
+
+PromptRegistry.get({name, label})     → primary prompts plugin only
+DatasetStore / ExperimentRunner       → their primaries (must match each other)
+ReviewQueue                           → local plugin only
+ScoreSinks[]                          → fan-out with traces
+```
+
+**Two planes**
+
+| Plane | Plugins | Write | Read (admin) |
+| --- | --- | --- | --- |
+| Telemetry | all registered `TraceSink` / `ScoreSink` | fan-out | **local** if local plugin on; else Langfuse |
+| Control | primary per capability | **one** writer | that primary |
+
+Mirrors `@terreno/comms`: interfaces in `ai/src/observability/types.ts`; adapters do not put extra vendor SDKs on core beyond what `LangfuseApp` already uses. OTLP exporter is an optional adapter file.
+
+### Public types (normative)
+
+```typescript
+type ObservabilityCapability =
+  | "traces"
+  | "prompts"
+  | "scores"
+  | "datasets"
+  | "experiments"
+  | "reviewQueue";
+
+type ControlPrimary = "local" | "langfuse";
+
+interface ObservabilityControlConfig {
+  datasets: ControlPrimary;
+  experiments: ControlPrimary;
+  prompts: ControlPrimary;
+  reviewQueue: "local"; // langfuse rejected at register()
+}
+
+interface ObservabilityPlugin {
+  readonly capabilities: ReadonlySet<ObservabilityCapability>;
+  readonly id: string;
+  datasetStore?: DatasetStore;
+  experimentRunner?: ExperimentRunner;
+  promptRegistry?: PromptRegistry;
+  reviewQueue?: ReviewQueue;
+  scoreSink?: ScoreSink;
+  traceSink?: TraceSink;
+}
+
+interface TraceRecord {
+  id: string;
+  name: string;
+  startedAt: string;
+  endedAt?: string;
+  userId?: string;
+  sessionId?: string;
+  status: "ok" | "error";
+  input?: unknown;
+  output?: unknown;
+  metadata?: Record<string, unknown>;
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    model?: string;
+    costUsd?: number;
+  };
+  prompt?: {name: string; version: number; label?: string};
+  spans: SpanRecord[];
+}
+
+interface ScoreRecord {
+  name: string;
+  dataType: "numeric" | "categorical" | "boolean";
+  value: number | string | boolean;
+  comment?: string;
+  source: "human" | "llm-judge" | "code";
+  evaluatorId?: string;
+  traceId: string;
+  spanId?: string;
+}
+```
+
+`ObservabilityApp` (new `TerrenoPlugin`):
+
+- Validates config (Q22, Q25, plugin present for each primary).
+- Holds the sink lists and primaries.
+- Contributes admin screens when local and/or Langfuse control APIs are on.
+- Does **not** replace `LangfuseApp.register()` — example-backend may `.register(new LangfuseApp(...)).register(new ObservabilityApp({plugins: [local, langfuseAdapter, otel]}))`. The Langfuse **adapter** wraps the existing client from `LangfuseApp` / `getLangfuseClient()`; it must not start a second OTel SDK if `LangfuseApp` already did.
+
+### `AIService` hook
+
+After each generate path (same place as `logRequest`):
+
+1. Skip if no `ObservabilityApp` or `options.skipTrace === true`.
+2. Build a root span (`CHAIN` or `LLM`) plus children for tool rounds when present.
+3. Attach `userId`, `sessionId` from generate options (GPT routes copy from `req.user` / body).
+4. Attach prompt name/version when `options.promptRef` is set.
+5. Compute `costUsd` from `options.priceMap ?? observability.priceMap` keyed by `model`.
+6. `Promise.allSettled` on each `TraceSink.export`; log rejections; **never throw**.
+7. If `sampleRate > 0` and `Math.random() < sampleRate`, enqueue live evaluators (same BackgroundTask path as experiments, one trace).
+
+Parent/child workflows: `AIRequest` already has `parentRequestId` / `subRequestIds`. Traces use `traceId` + `parentSpanId`. Multi-agent `logMultiAgentRequest` should also emit a parent `AGENT`/`CHAIN` span wrapping children when observability is on.
+
+## Models (local plugin)
+
+All new models: `createdUpdatedPlugin`, `isDeletedPlugin`, `findOneOrNone`, `findExactlyOne`, **description on every field**. Types in `ai/src/types/` (five-type pattern). Connection: default mongoose connection (same as `AIRequest`). If local plugin is not registered, **do not** register these models.
+
+| Model | Role |
+| --- | --- |
+| `ObsPrompt` | Named prompt (`name` unique). Tags. |
+| `ObsPromptVersion` | Immutable version: `type` text\|chat, body, `variables[]`, `inputSchema`/`outputSchema` (JSON Schema objects), `config` (temperature preset name, model hint). |
+| `ObsPromptLabel` | Movable labels: `production`, `latest`, optional `staging`. Unique `(promptId, label)`. |
+| `ObsTrace` | Root trace: user, session, status, usage, prompt ref, timestamps. |
+| `ObsSpan` | Nested spans: `traceId`, `parentSpanId`, OpenInference `kind`, input/output, model, tokens, cost. |
+| `ObsScore` | Scores on trace/span. |
+| `ObsEvaluator` | Named grader: dimensions[], type human\|llm-judge\|json-assert, judge `promptName` + schema. |
+| `ObsDataset` / `ObsDatasetItem` | Items: input vars, optional expected output, `sourceTraceId`. |
+| `ObsExperiment` / `ObsExperimentItem` | Run metadata + per-item outputs/scores. Status queued\|running\|completed\|failed. `backgroundTaskId`. |
+| `ObsReviewItem` | Queue: pending\|in_progress\|done\|skipped, evaluatorId, traceId, assigneeId, scores payload. |
+
+**Do not** put a unique index on fields that can duplicate (scores per trace are many). Index `{created: -1, userId: 1}`, `{sessionId: 1, created: -1}`, `{promptName: 1, promptVersion: 1}`, `{status: 1, created: 1}` on review items.
+
+No backfill: new collections. `AIRequest` unchanged.
+
+## APIs
+
+Admin-only unless noted (`Permissions.IsAdmin`). OpenAPI via `createOpenApiBuilder`. Base path `/ai/observability` (stable, not `/admin/langfuse`).
+
+| Method | Path | Behavior |
+| --- | --- | --- |
+| GET | `/ai/observability/status` | Plugin ids, capabilities, primaries, sink health (last error) |
+| GET/POST | `/ai/observability/prompts` | List/create via **prompt primary** |
+| GET/POST | `/ai/observability/prompts/:name/versions` | Immutable versions; POST creates `vN+1` |
+| POST | `/ai/observability/prompts/:name/labels` | Move `production` / `staging` |
+| POST | `/ai/observability/prompts/:name/playground` | Compile + one `AIService` call (not a new version) |
+| GET | `/ai/observability/traces` | Filters: time, user, session, prompt, status, minCost, hasScore |
+| GET | `/ai/observability/traces/:id` | Tree + scores |
+| GET | `/ai/observability/sessions/:sessionId` | Timeline |
+| GET | `/ai/observability/users/:userId` | Totals 7d/30d/all + recent traces |
+| GET | `/ai/observability/costs` | Aggregates by model, prompt, user |
+| CRUD | `/ai/observability/evaluators` | Dimension definitions |
+| POST | `/ai/observability/traces/:id/scores` | Human or code score → **all ScoreSinks** |
+| CRUD | `/ai/observability/datasets` + items | Dataset **primary** |
+| POST | `/ai/observability/experiments` | Creates run; local → `BackgroundTask`; Langfuse → vendor API |
+| GET | `/ai/observability/experiments/:id` | Status + aggregates |
+| GET/POST | `/ai/observability/review` | Local queue only |
+
+GPT routes: pass `userId` / `sessionId` / optional `promptRef` into `AIService`.
+
+Langfuse-primary prompt/dataset/experiment routes **proxy** existing Langfuse admin routes where they already exist (`langfuseRoutesPrompts.ts` etc.) so we do not duplicate HTTP. ObservabilityApp may mount a thin facade that delegates.
+
+## UI (`admin-frontend`)
+
+New screens in `AI_ADMIN_WIDGETS` / `customScreens` (same pattern as `AIRequestsScreenWidget`):
+
+| Screen | Name | Notes |
+| --- | --- | --- |
+| Prompts | `ai-prompts` | List + editor (new version, labels, JSON Schema I/O, playground) |
+| Traces | `ai-traces` | List + detail waterfall |
+| Sessions | `ai-sessions` | Optional v1: filter traces by session from detail |
+| Costs | `ai-costs` | KPI + breakdown tables |
+| Evaluators | `ai-evaluators` | Dimension builder |
+| Datasets | `ai-datasets` | |
+| Experiments | `ai-experiments` | Wizard; poll BackgroundTask; promote version |
+| Review | `ai-review` | Split view; **hide** if local plugin off |
+| Status chip | chrome | Active primaries; **Open in Langfuse** when Langfuse plugin id present |
+
+Reuse `@terreno/ui` (`Page`, `Box`, `DataTable`, `Tabs`, `Modal`, `TextField`). Keep **AI Requests** explorer as-is (`AIRequest`).
+
+Disabled tabs: if prompt primary is Langfuse, editor still works via API facade; if local off, Prompts/Datasets/Experiments/Review either hide or show Langfuse-backed lists + deep links (Q10). Review hidden when local off (Q25).
+
+## Example app
+
+`example-backend`:
+
+- Register `ObservabilityApp` with **local plugin always**.
+- If `LANGFUSE_*` already used for `LangfuseApp`, also pass Langfuse TraceSink/ScoreSink (and prompt adapter only if env `AI_OBS_PROMPTS_PRIMARY=langfuse`).
+- Optional `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` → `OtelTraceSink`.
+- Seed one prompt `example-summarize` v1 production, one evaluator `faithfulness` (numeric 0–1) + `safety` (boolean), empty dataset.
+
+`example-frontend`: no product UI required (admin-only). Regen SDK if example-frontend calls new routes (likely admin-only; skip consumer SDK if unused).
+
+## Feature flags & env
+
+No OpenFeature flag required: **registration is the flag**.
+
+Env (example-backend):
+
+| Variable | Role |
+| --- | --- |
+| `AI_OBS_PROMPTS_PRIMARY` | `local` \| `langfuse` (default `local`) |
+| `AI_OBS_DATASETS_PRIMARY` | default `local` |
+| `AI_OBS_EXPERIMENTS_PRIMARY` | must equal datasets |
+| `AI_OBS_SAMPLE_RATE` | `0`–`1`, default `0` |
+| `AI_OBS_PRICE_MAP_JSON` | `{ "gemini-2.5-flash": { "inputPerMTok": 0.1, "outputPerMTok": 0.4 } }` |
+| existing Langfuse keys | unchanged |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | optional OTLP |
+
+Validate dataset/experiment primary equality and reject `reviewQueue` langfuse at boot with a clear `APIError` / logger.error + throw (fail fast like missing SendGrid key).
+
+## Activity log
+
+Do **not** add `UserUpdate` spam for every trace. Admin audit: prompt **production** label moves and experiment **promote** (reuse `onAdminAudit` if AdminApp is present; otherwise `logger.info` with prompt name + version).
+
+## Testing
+
+- Bun tests, `expect`, `@terreno/test` Mongo preload. **Never mock `@terreno/api` or models.**
+- Fake TraceSink / ScoreSink in unit tests (in-memory).
+- `AIService` tests: emit called; `skipTrace`; sink throw does not fail generate; `AIRequest` still written.
+- Config tests: illegal experiment/dataset mix; langfuse reviewQueue; local-off + prompt primary local fails.
+- Local experiment: POST creates `BackgroundTask`, items scored, aggregates.
+- Langfuse adapter tests: mock `getLangfuseClient` (existing pattern in `langfuseClient.test.ts`).
+- Admin widget tests: render list empty/loading (existing admin-frontend patterns).
+- `verify-ui-changes` on admin-frontend screens before Brew.
+
+## Documentation (same slices as code)
+
+| Page | Kind |
+| --- | --- |
+| `docs/explanation/ai-observability.md` | Why two planes, plugins, vs `LangfuseApp` / `AIRequest` |
+| `docs/how-to/observe-llm-calls.md` | Register plugins, primaries, price map, sampleRate, Open in Langfuse |
+| `docs/reference/ai.md` | Models, routes, `AIService` trace options, env |
+| `terreno-langfuse-integration.md` | Pointer: native path is this IP; LangfuseApp remains the vendor plugin |
+| `ai-prompt-governance` skill | Prompt bodies for judges still named constants **or** `PromptRegistry` production label — not inline strings in `AIService` |
+
+## Phases
+
+1. **Contracts + ObservabilityApp + AIService emit + in-memory sinks** (tracer).
+2. **Local Mongo plugin** (prompts, traces, scores, costs, users/sessions).
+3. **Evaluators + live sampleRate + review queue**.
+4. **Datasets + local experiments via BackgroundTask**.
+5. **Langfuse adapter** (trace/score/prompt/dataset/experiment) + OTel TraceSink + admin UI + example-backend + docs.
+
+## Acceptance criteria
+
+- [ ] `AIService.generateText` with ObservabilityApp registered writes a nested-capable trace to **every** TraceSink; a throwing sink does **not** fail the generate; `AIRequest` still exists.
+- [ ] Creating prompt v2 does not mutate v1; moving `production` is an explicit label API; `get({name, label: "production"})` returns v2.
+- [ ] Trace list filters by `userId`, `sessionId`, prompt name/version; detail shows cost USD when price map has the model.
+- [ ] Evaluator with two dimensions (numeric + boolean) can score a trace via LLM-judge (`AIService` + named judge prompt) and via human review queue.
+- [ ] Dataset of N prior traces; experiment of production vs draft always uses `BackgroundTask` when local; promote sets production label.
+- [ ] Langfuse plugin on: same generate dual-writes traces/scores; prompts stay on configured primary; boot fails if `experiments.primary !== datasets.primary` or `reviewQueue` is langfuse.
+- [ ] OTel sink: one test asserts an OTLP payload / exporter mock received an OpenInference `LLM` span.
+- [ ] Admin: prompts, traces, costs, review, experiments usable as admin; Review hidden without local plugin.
+- [ ] Docs pages above match shipped behavior; `bun run --filter=@terreno/ai compile test lint` green.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| Langfuse experiment API vs Terreno dataset | Config equality; no sync job |
+| Double OTel SDK vs LangfuseApp | Adapter shares existing tracing init |
+| PHI in Mongo | Document; retention is a follow-on IP |
+| Live evals cost | `sampleRate` default 0 |
+| Missing failover IP | Follow current `AIService` / parent-child `AIRequest` |
+| Admin SPA drift | Widgets in admin-frontend automatically appear in spa shell |
+
+## Files to create / modify (expected)
+
+- `ai/src/observability/**` (types, app, local models/stores, otel sink, langfuse adapter)
+- `ai/src/service/aiService.ts` — emit traces
+- `ai/src/routes/gpt.ts` — pass user/session
+- `ai/src/aiAdminApp.ts` / new `observabilityAdmin.ts` — screens
+- `ai/src/index.ts` — exports
+- `admin-frontend/src/widgets/*` — new screens + registry
+- `example-backend/src/server.ts` — register ObservabilityApp
+- docs listed above
+- tests colocated

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

@@ -0,0 +1,316 @@
+# Implementation Plan: App MCP server
+
+**Status:** Draft  
+**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 keep bearer-only; OAuth metadata mounts only when Better Auth is enabled. |
+| 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):** do not mount OAuth metadata. Bearer JWT behavior is unchanged. Docs state that ChatGPT-class connectors need Better Auth.
+
+**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.
+- 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: existing bearer behavior unchanged; no OAuth well-known required
+- [ ] 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