@terreno/mcp 57.20.0 → 57.21.0

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

@@ -1,165 +0,0 @@
-# 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. This flows through to the OpenAPI spec and makes generated SDK documentation more useful.
-
-``````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.2.0/how-to/deploy-backend-to-cloud-run.md

@@ -1,115 +0,0 @@
-# Deploy backend to Cloud Run
-
-Deploy a Terreno `@terreno/api` backend (for example `example-backend`) to Google Cloud Run with Secret Manager.
-
-Replace placeholders: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$REPOSITORY`.
-
-## Prerequisites
-
-- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
-- GCP project with billing enabled
-- MongoDB Atlas cluster (or other replica set) — [deployment baseline](../explanation/deployment-baseline.md)
-- Docker (local build) or Cloud Build
-
-Enable APIs:
-
-```bash
-gcloud services enable run.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com --project="$PROJECT_ID"
-```
-
-## 1. Create Artifact Registry
-
-```bash
-gcloud artifacts repositories create "$REPOSITORY" \
-  --repository-format=docker \
-  --location="$REGION" \
-  --project="$PROJECT_ID"
-```
-
-## 2. Build and push the image
-
-From the **repository root** (the Dockerfile expects the monorepo context):
-
-```bash
-docker build -f example-backend/Dockerfile -t "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" .
-docker push "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest"
-```
-
-## 3. Create secrets
-
-Create Secret Manager secrets (values added out of band):
-
-```bash
-for name in mongodb-uri token-secret token-issuer refresh-token-secret session-secret; do
-  gcloud secrets create "$SERVICE_NAME-$name" --project="$PROJECT_ID" --replication-policy=automatic
-done
-```
-
-Add secret values (example for MongoDB URI):
-
-```bash
-echo -n 'mongodb+srv://user:pass@cluster.example/terreno?retryWrites=true&w=majority' | \
-  gcloud secrets versions add "$SERVICE_NAME-mongodb-uri" --data-file=- --project="$PROJECT_ID"
-```
-
-Repeat for `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, and `SESSION_SECRET`.
-
-For Better Auth, also create `better-auth-secret` and set `AUTH_PROVIDER=better-auth` plus `BETTER_AUTH_URL` at deploy time. See [Configure Better Auth](configure-better-auth.md).
-
-## 4. Runtime service account
-
-```bash
-gcloud iam service-accounts create "$SERVICE_NAME-runtime" --project="$PROJECT_ID"
-
-gcloud projects add-iam-policy-binding "$PROJECT_ID" \
-  --member="serviceAccount:$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
-  --role="roles/secretmanager.secretAccessor"
-```
-
-Grant object access on your uploads bucket separately if using GCS file storage.
-
-## 5. Deploy to Cloud Run
-
-```bash
-gcloud run deploy "$SERVICE_NAME" \
-  --image="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" \
-  --region="$REGION" \
-  --project="$PROJECT_ID" \
-  --platform=managed \
-  --port=3000 \
-  --session-affinity \
-  --timeout=3600 \
-  --min-instances=1 \
-  --allow-unauthenticated \
-  --service-account="$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
-  --set-secrets="MONGO_URI=$SERVICE_NAME-mongodb-uri:latest,TOKEN_SECRET=$SERVICE_NAME-token-secret:latest,TOKEN_ISSUER=$SERVICE_NAME-token-issuer:latest,REFRESH_TOKEN_SECRET=$SERVICE_NAME-refresh-token-secret:latest,SESSION_SECRET=$SERVICE_NAME-session-secret:latest" \
-  --set-env-vars="NODE_ENV=production"
-```
-
-Adjust `min-instances` to `0` for dev sandboxes (websockets will churn on cold start).
-
-## 6. Verify
-
-```bash
-SERVICE_URL=$(gcloud run services describe "$SERVICE_NAME" --region="$REGION" --project="$PROJECT_ID" --format='value(status.url)')
-curl -s "$SERVICE_URL/health" | jq .
-```
-
-Expect `"healthy": true`.
-
-## Production constraints
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Websockets disconnect every few requests | No session affinity on Cloud Run | Add `--session-affinity` |
-| Socket connections drop after ~5 minutes | Default request timeout (300s) | Raise `--timeout` (for example `3600`) |
-| Live feature flags / realtime never update; log mentions replica set | MongoDB is standalone, not a replica set | Use Atlas or `replSet` — change streams required (`feature-flags/src/featureFlagsApp.ts`) |
-| First request after idle is slow; sockets reconnect constantly | Scaled to zero | Set `--min-instances=1` for user-facing services |
-| Browser API calls blocked by CORS | `corsOrigin` / Better Auth `trustedOrigins` missing web origin | Add your CDN URL to backend CORS and auth config |
-
-## Related
-
-- [Deployment baseline](../explanation/deployment-baseline.md)
-- [Environment variables](../reference/environment-variables.md)
-- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md)
-- [GCP architecture](../explanation/deployment-architecture-gcp.md)

package/src/docs/versioned/57.2.0/how-to/deploy-to-gcp.md

@@ -1,36 +0,0 @@
-# Deploy to Google Cloud Platform
-
-Deploy a Terreno full-stack app to GCP: Cloud Run for the backend, GCS + Cloud CDN for the static web export.
-
-## Before you start
-
-Read the [deployment baseline](../explanation/deployment-baseline.md) — seven requirements (replica-set MongoDB, auth secrets, build-time `EXPO_PUBLIC_API_URL`, and more) apply to every provider.
-
-## Guides
-
-| Guide | What it covers |
-|-------|----------------|
-| [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) | Container image, Secret Manager, Cloud Run with session affinity |
-| [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) | Static web export, bucket + CDN setup, cache invalidation |
-| [Build for web](build-for-web.md) | Export command, `EXPO_PUBLIC_API_URL`, local verification |
-
-## Architecture
-
-[GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
-
-## Scripts
-
-- [`scripts/setup-gcs-hosting.sh`](https://github.com/TerrenoLabs/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
-
-## Environment variables
-
-[Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
-
-## Legacy Flourish deployment
-
-Flourish-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives in `infra/flourish/` and the existing `demo-deploy.yml` / `frontend-example-deploy.yml` workflows. New deployments should follow the generalized guides above with your own `$PROJECT_ID` and bucket names.
-
-## Related
-
-- [Environment variables](../reference/environment-variables.md)
-- [Deployment baseline](../explanation/deployment-baseline.md)

package/src/docs/versioned/57.2.0/how-to/expose-mcp-tools.md

@@ -1,194 +0,0 @@
-# Expose Model Context Protocol Tools
-
-Turn a `modelRouter` model into Model Context Protocol (MCP) tools that an LLM can call, reusing the permissions, query filters, population, and lifecycle hooks you already declared for REST.
-
-## Prerequisites
-
-- A working Terreno backend using `TerrenoApp`
-- At least one model registered with `modelRouter`
-
-## Steps
-
-### 1. Add an `mcp` config to a model router
-
-```typescript
-import {modelRouter, OwnerQueryFilter, Permissions} from "@terreno/api";
-
-export const todoRouter = modelRouter("/todos", Todo, {
-  mcp: {
-    excludeFields: ["internalNote"],
-    maxLimit: 25,
-    methods: ["list", "read", "create", "update", "delete"],
-  },
-  permissions: {
-    create: [Permissions.IsAuthenticated],
-    delete: [Permissions.IsOwner],
-    list: [Permissions.IsAuthenticated],
-    read: [Permissions.IsOwner],
-    update: [Permissions.IsOwner],
-  },
-  queryFields: ["completed", "title"],
-  queryFilter: OwnerQueryFilter,
-});
-```
-
-`methods` defaults to `["list", "read"]`, and `maxLimit` defaults to 50. A method whose `permissions` array is empty is never exposed as a tool, so REST and MCP cannot drift apart.
-
-### 2. Start the server
-
-`TerrenoApp` mounts `POST /mcp` automatically as soon as any model has an `mcp` config. Every other verb on `/mcp` returns a JSON-RPC 405. No extra registration is needed.
-
-Tools are named `{prefix}_{method}` — `todos_list`, `todos_read`, and so on.
-
-The endpoint speaks the `2026-07-28` MCP revision through the TypeScript SDK v2
-`createMcpHandler`. It is stateless: every request carries its protocol version,
-client identity, and capabilities, so requests can land on any backend instance.
-The SDK's stateless legacy fallback remains enabled, so 2025-era clients continue
-to work while clients migrate.
-
-### 3. Call the tools
-
-Point any MCP client at `POST /mcp` with the user's `Authorization: Bearer <token>` header. Both JWT and Better Auth sessions are accepted; the resolved user is what the permission checks run against, so an LLM can never see more than that user could see over REST.
-
-Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP.
-
-To run the same tools in-process (for example inside a chat route), use `getMCPTools`:
-
-```typescript
-import {getMCPTools} from "@terreno/ai";
-
-const tools = getMCPTools(req.user);
-```
-
-`useMCPTools()` from `@terreno/rtk` uses the official MCP v2 client with automatic
-version negotiation. It no longer constructs JSON-RPC or parses SSE responses by
-hand; the SDK supplies the `2026-07-28` `_meta` envelope and required
-`Mcp-Method` / `Mcp-Name` routing headers.
-
-## Naming tools
-
-The default prefix is the lowercase model name run through a simple pluralizer: `Todo` → `todos`, `Category` → `categories`, `Status` → `statuses`. Irregular nouns need an explicit prefix:
-
-```typescript
-mcp: {toolPrefix: "people"} // person_list -> people_list
-```
-
-## Filtering list results
-
-Only fields listed in `queryFields` can be filtered, exactly as in REST. A filter value may be an exact value or an operator object:
-
-```json
-{"completed": false, "title": {"$in": ["Buy milk", "Walk dog"]}}
-```
-
-Allowed operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$all`, `$size`, `$exists`, and `$regex` (with `$options`). Operators that can execute code or ignore indexes — `$where`, `$expr`, `$function`, `$accumulator`, `$jsonSchema`, `$text` — are rejected with an error rather than silently dropped, so the model can correct itself.
-
-Filters can be combined with top-level `$and` / `$or`, whose branches are validated against `queryFields` too:
-
-```json
-{"$or": [{"completed": true}, {"title": {"$regex": "^Urgent"}}]}
-```
-
-`queryFilter` still runs after the filter is built, so an `OwnerQueryFilter` keeps scoping results to the calling user no matter what the LLM sends.
-
-## Populating references
-
-Population comes from the model router's `populatePaths`, exactly as it does over REST. A tool may pass `populate` to request a **subset** of those declared paths — it can never introduce a new one, so the `fields` allowlist on each declared path always applies and a caller cannot pull back a whole referenced document:
-
-```typescript
-populatePaths: [{fields: ["name", "email"], path: "ownerId"}],
-```
-
-`{"populate": "ownerId"}` is accepted; anything undeclared is refused with an error listing the allowed paths. Models with no `populatePaths` don't get a `populate` parameter at all.
-
-## Hiding fields
-
-`excludeFields` removes fields from both the generated tool schemas and the responses:
-
-- A bare name (`"hash"`) is removed at **every depth**, including inside arrays and populated refs, so a redacted name cannot leak through a nested document.
-- A dot path (`"metadata.secretKey"`) removes exactly that location, following arrays of subdocuments element-wise.
-
-## Customizing responses
-
-`mcpResponseHandler` shapes MCP responses independently of the REST `responseHandler`, which is useful for returning compact summaries to an LLM:
-
-```typescript
-mcp: {
-  mcpResponseHandler: async (value, method) => {
-    if (Array.isArray(value)) {
-      return value.map((todo) => ({id: String(todo._id), title: todo.title}));
-    }
-    return {id: String(value._id), title: value.title};
-  },
-}
-```
-
-`excludeFields` is applied after your handler runs.
-
-## Lifecycle hooks
-
-`preCreate`, `postCreate`, `preUpdate`, `postUpdate`, `preDelete`, and `postDelete` all run for MCP calls. An MCP tool call is JSON-RPC rather than HTTP, so `createMCPRequest` builds a stub Express-shaped `request` (`MCPRequest`):
-
-- `user` — the authenticated MCP user
-- `body` — the hook-stage payload after write denylist + transform, not the raw tool args (on delete, `id` is in `body`, not `params`)
-- `headers` / `query` / `params` — always `{}` (MCP does not forward HTTP headers)
-- `isMCPRequest` — `true`
-
-REST `responseHandler` gets the same stub with an empty `body`.
-
-```typescript
-import type {MCPRequest} from "@terreno/api";
-
-preCreate: (body, req) => {
-  if ((req as unknown as MCPRequest).isMCPRequest) {
-    // e.g. tag records created by an assistant
-    return {...body, source: "assistant"};
-  }
-  return body;
-},
-```
-
-A hook that reads `req.headers` or `req.query` gets an empty object instead of a crash, but anything genuinely HTTP-specific (cookies, IP address) is unavailable — branch on `isMCPRequest` when that matters.
-
-## Logging and error reporting
-
-Every generated tool call emits a structured backend audit log with stable
-`mcpTool`, `mcpMethod`, and `mcpModel` labels plus the active Terreno request
-context (`requestId`, `userId`, and trace fields when present):
-
-- successful calls log at `info` with `durationMs`
-- expected refusals (permissions, not found, invalid filters) log at `warn`
-- caught database, transform, and lifecycle-hook failures log at `error`
-
-When `USE_SENTRY_LOGGING=true`, expected failures are mirrored as Sentry logs.
-Unexpected exceptions and caught internal causes are also captured with
-`Sentry.captureException`, preserving their original stack. The client still
-receives the stable MCP error text — internal exceptions and stack traces stay
-server-side. Tool arguments are not logged.
-
-## Custom tools
-
-CRUD tools cover one model at a time. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
-
-```typescript
-import {registerMCPTool} from "@terreno/api";
-import {z} from "zod";
-
-registerMCPTool({
-  name: "users_todo_statuses",
-  description: "List every user with each of their todos and completed status. Admin only.",
-  zodSchema: z.object({}).strict(),
-  handler: async (_args, user) => {
-    if (!user?.admin) {
-      return {
-        content: [{type: "text", text: JSON.stringify({error: "Permission denied: admin required"})}],
-        isError: true,
-      };
-    }
-    // load users + todos and return JSON text
-    return {content: [{type: "text", text: JSON.stringify({users: []})}]};
-  },
-});
-```
-
-The example backend registers this as `users_todo_statuses` from `example-backend/src/api/usersTodoStatus.ts`.

package/src/docs/versioned/57.2.0/how-to/install-agent-skills.md

@@ -1,46 +0,0 @@
-# Install agent skills
-
-Install Terreno's agent skills into another repo or agent with the skills CLI.
-
-```bash
-npx skills add TerrenoLabs/terreno
-npx skills add TerrenoLabs/terreno --skill terreno-1-grow
-```
-
-That copies the committed `skills/` tree: lifecycle stages (Grow, Pick, Roast, Brew,
-Taste), repository skills, and published package skills.
-
-## What you get
-
-| Group | Skills |
-| --- | --- |
-| Lifecycle | `terreno-1-grow` … `terreno-5-taste` |
-| Terreno apps | backend, UI, data, schema, SDK |
-| Docs | `update-docs`, `update-agent-docs`, architecture skills |
-| GitHub | commit, PR, review, verify, release, deploy |
-
-`skills.sh.json` at the repo root groups those names on [skills.sh](https://skills.sh).
-
-## Keep copies in sync (Terreno maintainers)
-
-Canonical sources:
-
-1. `.rulesync/skills/` — repository skills (`bun run rules` generates agent copies)
-2. `plugins/terreno-planning/skills/` — portable lifecycle stages
-3. `<package>/.ai/skills/` — published package skills; these overlay the repo copies
-
-Regenerate the installable tree:
-
-```bash
-bun run skills:sync
-bun run check:lifecycle-skills
-```
-
-Do not hand-edit `skills/`.
-
-## Write human docs with the skills
-
-Skills read architecture docs before changing code. After a user-visible or architectural
-change, update `docs/` in the same slice using `update-docs`. See
-[lifecycle plugin](../reference/lifecycle-plugin.md) and the
-[documentation contract](https://github.com/TerrenoLabs/terreno/blob/master/plugins/terreno-planning/references/documentation-contract.md).