@terreno/mcp 57.17.0 → 57.19.2

package/src/docs/versioned/57.17.0/how-to/connect-mcp-service-token.md

@@ -0,0 +1,112 @@
+# Connect an MCP client with a service token
+
+Mint a personal `mcp_…` Bearer key, then paste the MCP URL and key into Perplexity, Cursor, VS Code, or Claude Code.
+
+This is the **static-key** path for the consumer app's `POST /mcp`. It is not the hosted `@terreno/mcp` codegen server. For exposing tools, see [Expose MCP tools](expose-mcp-tools.md). Interactive OAuth for remote clients such as Claude.ai and ChatGPT is [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md); do not send these keys in a query string.
+
+## 1. Enable the flag
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL,
+  },
+});
+```
+
+`mcpServiceTokens: true` is the same as `{enabled: true}`. Off (omitted or `enabled: false`) does not mount `/mcp/service-tokens` and does not accept `mcp_` Bearer credentials on `/mcp`.
+
+Pass `publicMcpUrl` so create responses include a copy-paste MCP URL (`…/mcp` is appended when missing). The example backend uses `PUBLIC_API_URL` or `BETTER_AUTH_URL`.
+
+## 2. Mint a token (Settings)
+
+1. Sign in to the example app.
+2. Open **Profile** → **MCP connections** (`/settings/mcp`).
+3. Enter a name (for example `Perplexity laptop`). Optionally set an expiry.
+4. Tap **Create token**.
+5. Copy the MCP URL, the full `mcp_…` secret, or the JSON snippet from the modal. The secret is shown **once**. Close the modal only after you have stored it in the client.
+
+Cap is **10** active tokens per user. List rows show prefix (`mcp_` + eight hex characters), last used, and expiry — never the full secret.
+
+## 3. Mint a token (curl)
+
+Use a session or JWT. A service token cannot mint another token.
+
+```bash
+curl -X POST "$API/mcp/service-tokens" \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Perplexity"}'
+```
+
+Read `data.token` and `data.mcpUrl` from the JSON. List and revoke never return `token`. Do not log the secret.
+
+## 4. Perplexity custom connector
+
+| Field | Value |
+| --- | --- |
+| MCP Server URL | `https://api.example.com/mcp` (use `data.mcpUrl` from create) |
+| Transport | Streamable HTTP |
+| Authentication | API Key |
+| API Key | full `mcp_…` string (Perplexity sends as Bearer) |
+
+Perplexity probes with GET, then POSTs JSON-RPC. Send the same key on both.
+
+GET does **not** authenticate. This server has no GET SSE stream, so `/mcp` answers `405` with `{"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."}}` whether or not the key is valid. That 405 is the expected probe — not a failed login.
+
+POST `initialize` and `tools/list` are the unauthenticated catalog in the stateless handler. Identity is checked when a **tool runs** (`tools/call`). A missing or invalid `mcp_` key then returns `Permission denied: authentication required`.
+
+## 5. Cursor, VS Code, Claude Code (JSON)
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer mcp_<secret-shown-once>"
+      }
+    }
+  }
+}
+```
+
+Replace the URL with `data.mcpUrl` and the Bearer value with the one-time `data.token`.
+
+## 6. Prove the key with curl
+
+```bash
+# Expected probe: JSON-RPC 405 "Method not allowed."
+curl -X GET "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream"
+
+# Catalog is unauthenticated. Identity is not proven here.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
+
+# Identity check: tools/call as the owning user. Use a tool name from tools/list.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"todos_list","arguments":{}}}'
+```
+
+A bogus key such as `mcp_deadbeef` on `tools/call` is denied. A valid key sees the same owner-scoped result as that user's REST session.
+
+The token acts as the owning user on **MCP only**. It cannot mint or list tokens, and it is not valid on REST, sync, or admin routes.
+
+## 7. Revoke
+
+- **Owner:** Profile → MCP connections → **Revoke** on the row (`DELETE /mcp/service-tokens/:id`).
+- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete the row.
+
+Revoked and expired keys fail `tools/call` immediately. Disabled user accounts are refused the same way as over HTTP.
+
+A password reset, Better Auth password change, or "sign out everywhere" (`revoke-sessions` / `revoke-other-sessions`) bumps the user's `tokenEpoch` and ends every key minted before it. The keys show as revoked in the list; mint a new one for each client you still use.

package/src/docs/versioned/57.17.0/how-to/create-a-model.md

@@ -0,0 +1,165 @@
+# How to Create a Mongoose Model
+
+Learn how to create a Mongoose model with Terreno conventions for use with modelRouter.
+
+## Prerequisites
+
+- Basic understanding of MongoDB and Mongoose
+- @terreno/api installed
+- MongoDB connection configured
+
+## Step-by-step
+
+### 1. Define TypeScript interfaces
+
+Create type definitions for your model document, model statics, and methods:
+
+``````typescript
+// src/types/models/todoTypes.ts
+import type mongoose from "mongoose";
+import type {DefaultDoc, DefaultModel} from "@terreno/api";
+
+export interface TodoDocument extends DefaultDoc {
+  title: string;
+  completed: boolean;
+  ownerId: mongoose.Types.ObjectId;
+}
+
+export interface TodoModel extends DefaultModel<TodoDocument> {
+  // Add custom static methods here if needed
+}
+``````
+
+### 2. Create the schema with field descriptions
+
+**Important:** Every field **must** include a `description` property. Terreno's `describeModel()` reads descriptions into the canonical field graph; that graph feeds the OpenAPI spec, admin `/admin/config` field metadata, and MCP tool schemas.
+
+``````typescript
+// src/models/todo.ts
+import mongoose from "mongoose";
+import type {TodoDocument, TodoModel} from "../types";
+import {addDefaultPlugins} from "./modelPlugins";
+
+const todoSchema = new mongoose.Schema<TodoDocument, TodoModel>(
+  {
+    completed: {
+      default: false,
+      description: "Whether the todo item has been completed",
+      type: Boolean,
+    },
+    ownerId: {
+      description: "The user who owns this todo",
+      ref: "User",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    title: {
+      description: "The title of the todo item",
+      required: true,
+      trim: true,
+      type: String,
+    },
+  },
+  {
+    strict: "throw",
+    toJSON: {virtuals: true},
+    toObject: {virtuals: true},
+  }
+);
+``````
+
+### 3. Add plugins
+
+Apply default plugins to get standard fields (created, updated, deleted):
+
+``````typescript
+addDefaultPlugins(todoSchema);
+``````
+
+The default plugins typically include:
+- `createdUpdatedPlugin` — Adds `created` and `updated` timestamps
+- `isDeletedPlugin` — Adds soft delete support with `deleted` field
+- `findExactlyOne` and `findOneOrNone` — Safe query methods
+
+### 4. Export the model
+
+``````typescript
+export const Todo = mongoose.model<TodoDocument, TodoModel>("Todo", todoSchema);
+``````
+
+### 5. Create routes with modelRouter
+
+Use the model with `modelRouter` to generate CRUD endpoints:
+
+``````typescript
+// src/api/todos.ts
+import {Router} from "express";
+import {modelRouter, Permissions, OwnerQueryFilter} from "@terreno/api";
+import {Todo} from "../models/todo";
+
+export const addTodoRoutes = (router: Router) => {
+  router.use(
+    "/todos",
+    modelRouter(Todo, {
+      permissions: {
+        create: [Permissions.IsAuthenticated],
+        list: [Permissions.IsAuthenticated],
+        read: [Permissions.IsOwner],
+        update: [Permissions.IsOwner],
+        delete: [Permissions.IsOwner],
+      },
+      preCreate: (body, req) => ({
+        ...body,
+        ownerId: req.user?._id,
+      }),
+      queryFilter: OwnerQueryFilter,
+      queryFields: ["completed", "ownerId"],
+      sort: "-created",
+    })
+  );
+};
+``````
+
+## Field description guidelines
+
+When writing field descriptions:
+
+- **Be concise:** One clear sentence is usually enough
+- **Explain purpose, not type:** The type is already specified
+- **Use active voice:** "The user who owns..." not "The owner of..."
+- **Include constraints if relevant:** "Email address (must be unique)"
+
+### Good examples
+
+``````typescript
+{
+  email: {
+    description: "User's email address (must be unique)",
+    type: String,
+    required: true,
+    unique: true,
+  },
+  createdAt: {
+    description: "Timestamp when the record was created",
+    type: Date,
+    default: Date.now,
+  },
+  status: {
+    description: "Current status of the order",
+    type: String,
+    enum: ["pending", "processing", "completed"],
+  },
+}
+``````
+
+## Next steps
+
+- Learn about [modelRouter options](../reference/api.md)
+- Explore [permissions and access control](../reference/api.md#permissions)
+- See the [example-backend](../../example-backend/) for a complete working example
+
+## See also
+
+- [@terreno/api reference](../reference/api.md)
+- [Getting started tutorial](../tutorials/getting-started.md)
+- [example-backend source](../../example-backend/src/models/)

package/src/docs/versioned/57.17.0/how-to/create-a-terreno-app.md

@@ -0,0 +1,154 @@
+# Create a Terreno app
+
+Scaffold a deployable full-stack Terreno app (backend, Expo frontend, seed script, consumer `Dockerfile`, CI, MCP config) with one non-interactive command.
+
+The CLI writes files only — it does not run `bun install`, start MongoDB, or seed data.
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) (or Node/npm for `npm create`)
+- An empty target directory (see [Non-empty targets](#non-empty-targets))
+- MongoDB as a **replica set** before running the backend (see [Start MongoDB](#3-start-mongodb-replica-set))
+
+## 1. Scaffold the app
+
+From the parent directory where you want `<appName>/`:
+
+```bash
+bunx create-terreno-app my-app --display-name "My App"
+```
+
+npm alternative (note the `--` before flags):
+
+```bash
+npm create terreno-app my-app -- --display-name "My App"
+```
+
+Derive the display name from `appName` when you do not need a custom title:
+
+```bash
+bunx create-terreno-app my-app --yes
+```
+
+Optional flags:
+
+| Flag | Required | Default |
+| --- | --- | --- |
+| `appName` (positional) | yes | — kebab-case directory and package name (`^[a-z][a-z0-9-]*$`) |
+| `--display-name` | unless `--yes` | derived from `appName` when `--yes` |
+| `--description` | no | empty |
+| `--mcp-server-url` | no | `https://mcp.terreno.app` |
+| `--yes` | no | off |
+
+The CLI creates `<cwd>/<appName>/`. Package source: [`create-terreno-app/`](https://github.com/TerrenoLabs/terreno/tree/master/create-terreno-app) in the Terreno monorepo.
+
+## Non-empty targets
+
+The CLI refuses to write when the target already contains anything other than `.git` or `.gitignore`. It exits non-zero and leaves existing files unchanged.
+
+Initializing git first is fine:
+
+```bash
+mkdir my-app && cd my-app && git init
+cd .. && bunx create-terreno-app my-app --yes
+```
+
+## Generated layout
+
+| Path | Purpose |
+| --- | --- |
+| `backend/` | Express/Mongoose API (`@terreno/api`, Better Auth, admin, sync) |
+| `frontend/` | Expo universal app (`@terreno/ui`, `@terreno/syncdb`, `@terreno/rtk`) |
+| `Dockerfile` | Consumer backend image (`backend/` only — not the Terreno monorepo) |
+| `.dockerignore` | Excludes local env secrets, dependencies, and build output from the image context |
+| `backend/.env`, `frontend/.env` | Gitignored local-dev defaults (written on scaffold) |
+| `backend/.env.example`, `frontend/.env.example` | Committed templates for production and export |
+| `.github/workflows/` | Backend and frontend CI |
+| `.cursor/mcp.json`, `.cursorrules`, `CLAUDE.md` | Agent tooling |
+| `README.md` | App-specific next steps and deploy links |
+
+Generated `@terreno/*` dependencies pin to `^<create-terreno-app version>` at scaffold time.
+
+## 2. Install dependencies
+
+```bash
+cd my-app
+(cd backend && bun install)
+(cd frontend && bun install)
+```
+
+## 3. Start MongoDB (replica set)
+
+Sync and realtime require a replica set (even a single-node dev set). See the [deployment baseline](../explanation/deployment-baseline.md).
+
+From the generated app root, run this local single-node example after `mongod` is available:
+
+```bash
+mkdir -p .devdata/mongo
+mongod --replSet rs0 --port 27017 --bind_ip 127.0.0.1 --dbpath .devdata/mongo &
+# Initiate once (use node for the driver command if bun errors on bson):
+node -e 'import("mongodb").then(async ({MongoClient})=>{const c=new MongoClient("mongodb://127.0.0.1:27017/?directConnection=true");await c.connect();await c.db("admin").command({replSetInitiate:{_id:"rs0",members:[{_id:0,host:"127.0.0.1:27017"}]}}).catch(()=>{});await c.close();})'
+```
+
+The scaffold sets `MONGO_URI` in `backend/.env` to `mongodb://127.0.0.1:27017/<app_name>?replicaSet=rs0` (hyphens in `appName` become underscores in the database name). Copy from `backend/.env.example` when you need production values.
+
+## 4. Seed login users
+
+With MongoDB running as a replica set:
+
+```bash
+(cd backend && bun run seed)
+```
+
+Creates:
+
+| Email | Password | Notes |
+| --- | --- | --- |
+| `test@example.com` | `testpassword123` | Standard user |
+| `admin@example.com` | `testpassword123` | Admin user |
+
+Seed behavior and flags: [Seed a database](seed-a-database.md). Better Auth setup: [Configure Better Auth](configure-better-auth.md).
+
+## 5. Run the stack
+
+Terminal 1 — API (default port `4000`):
+
+```bash
+(cd backend && bun run dev)
+```
+
+Health check: `curl http://localhost:4000/health` → `"healthy":true`.
+
+Terminal 2 — web UI (port `8082`):
+
+```bash
+(cd frontend && bun run sdk)   # after backend is up; regenerates OpenAPI hooks
+(cd frontend && bun run web)
+```
+
+Open `http://localhost:8082` and sign in as `test@example.com` / `testpassword123`.
+
+`frontend/.env` defaults `EXPO_PUBLIC_API_URL` to `http://localhost:4000`. For production web builds, set it **before** export — see [Build for web](build-for-web.md).
+
+## Deploy
+
+Read the [deployment baseline](../explanation/deployment-baseline.md) first.
+
+**Backend:** the root `Dockerfile` builds only `backend/` on `oven/bun`, listens on `PORT` (default `8080` in the image), binds `0.0.0.0`, and exposes `GET /health`. It does not copy Terreno monorepo packages.
+
+```bash
+docker build -t my-app-backend .
+docker run --rm -p 8080:8080 \
+  -e MONGO_URI='mongodb+srv://...' \
+  -e BETTER_AUTH_SECRET='...' \
+  -e BETTER_AUTH_URL='https://api.example.com' \
+  my-app-backend
+```
+
+Cloud Run concepts and commands: [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md). That guide targets Terreno's monorepo example; for a generated app, keep the root `Dockerfile`, port `8080`, and Better Auth variables shown here. The generated backend throws if `BETTER_AUTH_SECRET` is unset. `GET /users` list and read require an admin.
+
+**Frontend:** [Build for web](build-for-web.md) — set `EXPO_PUBLIC_API_URL` at export time.
+
+## Monorepo examples (secondary)
+
+To explore Terreno itself without scaffolding a new app, clone the [Terreno monorepo](https://github.com/TerrenoLabs/terreno) and use `example-backend` / `example-frontend`. See [Getting started](../tutorials/getting-started.md#explore-the-terreno-monorepo-examples).

package/src/docs/versioned/57.17.0/how-to/debug-with-mcp.md

@@ -0,0 +1,160 @@
+# Debug a Terreno app with MCP
+
+Start the backend and frontend, reproduce the failure once, then inspect the merged runtime evidence
+instead of copying logs into the agent chat.
+
+## 1. Read the latest error
+
+Call the local MCP tool:
+
+```json
+{"name":"last_error","arguments":{"sources":["backend","browser","metro","app"]}}
+```
+
+It returns the newest error-level JSONL/CDP entry. Use `read_logs` when the failure needs surrounding
+events:
+
+```json
+{
+  "name": "read_logs",
+  "arguments": {
+    "entries": 100,
+    "level": "error",
+    "sources": ["backend", "browser", "metro", "app"]
+  }
+}
+```
+
+`backend` and `browser` read durable JSONL; `metro` and `app` read in-memory rings populated from
+Metro `/events` and CDP. Connection status in the response explains when either live source is
+unavailable.
+
+CLI equivalents:
+
+```bash
+terreno logs last-error --sources backend,browser,metro,app
+terreno logs --entries 100 --level error --sources backend,browser,metro,app
+```
+
+## 2. Inspect client state
+
+Check authentication and non-synced RTK Query cache state:
+
+```json
+{"name":"get_rtk_state","arguments":{"slice":"rtk","query":"todos"}}
+```
+
+The tool reads `globalThis.__TERRENO_STORE__` registered by the app, using CDP when the MCP process
+cannot access the app heap directly. `slice: "auth"` prefers the Better Auth slice and falls back to
+legacy JWT auth; pass `betterAuth` to request that exact slice. The CLI equivalent is:
+
+Sensitive fields whose names include `password`, `token`, `secret`, `authorization`, or `cookie` are
+returned as `[REDACTED]`; use this summary to inspect cache state, never to retrieve credentials.
+
+```bash
+terreno state --slice rtk --query todos
+```
+
+## 3. Inspect and change SyncDB state
+
+Create the app client with `debug: true`, then inspect the same state that powers
+the SyncDB debugger:
+
+```json
+{"name":"get_syncdb_state","arguments":{"collection":"todos"}}
+```
+
+The result includes entities (including tombstones, seq/stream, and pending ids),
+decoded outbox rows, conflicts, cursors, known streams, repair markers, aggregate
+status, and debugger events. Sensitive fields are returned as `[REDACTED]`.
+
+Capture state before and after reproduction, then compare it:
+
+```json
+{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
+{"name":"syncdb_snapshot","arguments":{"action":"capture"}}
+{"name":"syncdb_snapshot","arguments":{"action":"compare","snapshotId":"syncdb-...-1","otherSnapshotId":"syncdb-...-2"}}
+```
+
+Snapshots live in the local MCP process. Each capture privately retains the
+TinyBase mergeable content so `mergeSnapshot` can CRDT-merge it back later
+without wiping newer local rows (later HLCs win, including deletes). `get` and
+`compare` never return that merge payload. To restore a specific captured row,
+use `setLocalEntity` from `syncdb_snapshot` `get`.
+
+State changes require an explicit local opt-in:
+
+```bash
+TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+```
+
+Then use `syncdb_action`. Normal writes should use `mutate`; `flush` drains the
+outbox, and `reconcile` catches up from server snapshots:
+
+```json
+{"name":"syncdb_action","arguments":{"action":"mutate","collection":"todos","operation":"update","id":"todo-1","data":{"completed":true}}}
+{"name":"syncdb_action","arguments":{"action":"flush"}}
+{"name":"syncdb_action","arguments":{"action":"reconcile"}}
+```
+
+Other actions are `forceResync`, `resolveConflict`, `retryFailed`, `goOffline`,
+`goOnline`, `clearDebug`, `setLocalEntity`, `deleteLocalEntity`, and
+`mergeSnapshot`. Direct local edits bypass server validation and outbox
+semantics. `mergeSnapshot` CRDT-merges the captured TinyBase content into the
+live store (later HLCs win) instead of replacing it. Capture a baseline first
+and use these only for fault injection or repair.
+
+## 4. Prove the web fix
+
+Use Bun 1.4's built-in WebView through the local `browser` tool:
+
+```json
+{"name":"browser","arguments":{"action":"open","url":"http://localhost:8082"}}
+{"name":"browser","arguments":{"action":"wait","timeout":1000}}
+{"name":"browser","arguments":{"action":"click","selector":"[data-testid=save]"}}
+{"name":"browser","arguments":{"action":"snapshot"}}
+{"name":"browser","arguments":{"action":"screenshot","output":"/opt/cursor/artifacts/save-result.png"}}
+{"name":"browser","arguments":{"action":"close"}}
+```
+
+The session persists between MCP calls. `snapshot` returns visible text and up to 200 interactive
+elements so the agent can choose selectors and verify state without image guessing. `screenshot`
+saves the viewport for the PR or walkthrough.
+WebView console output is not added to `browser.log`; call `read_logs` alongside this flow when the
+running app posts browser logs to the backend collector. The collector accepts local-loopback
+traffic before login; devices or remote browsers must send the app's normal authentication.
+
+The equivalent one-process CLI sequence is:
+
+```bash
+terreno web http://localhost:8082 \
+  --action '{"action":"click","selector":"[data-testid=save]"}' \
+  --snapshot \
+  --screenshot /opt/cursor/artifacts/save-result.png
+```
+
+## 5. Verify the native fix in the running app
+
+Navigation and arbitrary evaluation are disabled by default. Opt in only for local debugging:
+
+```bash
+TERRENO_MCP_EVAL=1 bunx terreno-mcp-local
+```
+
+Then call `navigate` with `{"path":"/profile"}` or run:
+
+```bash
+TERRENO_MCP_EVAL=1 terreno navigate /profile
+```
+
+Confirm the target screen renders, then call `last_error` again. A successful fix has no new
+error-level entry after the navigation timestamp.
+
+## Connection problems
+
+- Upgrade to Bun 1.4 or newer when `Bun.WebView requires Bun 1.4 or newer` appears.
+- Set `BUN_CHROME_PATH` if WebView cannot discover Chrome, Chromium, or Edge on Linux or Windows.
+- Set `TERRENO_PROJECT_ROOT` if logs or package versions come from the wrong directory.
+- Set `TERRENO_METRO_URL` if Metro is not on the frontend script's `--port`.
+- Close React Native DevTools when Hermes reports another debugger connection.
+- Use only `backend,browser` sources when Metro is intentionally stopped.