@softr/sdk 0.0.46-alpha.2 → 0.0.46-alpha.3

package/dist/action.d.ts

@@ -198,9 +198,12 @@ type WorkflowDefinition<TId extends string> = {
  * await workflow.trigger(notifyTeam, { subject: "Hello" });
  */
 declare function defineWorkflow<const TId extends string>(definition: WorkflowDefinition<TId>): WorkflowAction<TId>;
+type IntegrationMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
 type IntegrationResource = {
   type: "INTEGRATION";
   integrationId: string;
+  method: IntegrationMethod;
+  url: string;
 };
 type IntegrationAction<TId extends string = string> = Action<IntegrationResource> & {
   id: TId;
@@ -208,22 +211,28 @@ type IntegrationAction<TId extends string = string> = Action<IntegrationResource
 type IntegrationDefinition<TId extends string> = {
   id: TId;
   integrationId: string;
+  method: IntegrationMethod;
+  url: string;
   permissions: ActionPermissions;
 };
 /**
- * Declares an integration: which workspace integration to call through, and who may call it.
+ * Declares an integration action: which workspace integration to call, the one HTTP method and the
+ * endpoint URL it allows, and who may call it. The proxy denies a call whose method does not match,
+ * so declare one action per operation. Use a `{placeholder}` token for a dynamic path segment,
  *
  * Pass the returned object to `integration.createFetcher()` to get a bound fetcher.
  *
  * @example
- * const googleCalendar = defineIntegration({
- *   id: "googleCalendar",
+ * const listCalendarEvents = defineIntegration({
+ *   id: "listCalendarEvents",
  *   integrationId: "25d60213-ef4f-4fa0-b094-a46931b2d120",
+ *   method: "GET",
+ *   url: "https://www.googleapis.com/calendar/v3/calendars/primary/events",
  *   permissions: { userGroup: "LOGGED_IN_USERS" },
  * })
  *
- * const calendar = integration.createFetcher(googleCalendar)
- * const res = await calendar('https://www.googleapis.com/calendar/v3/calendars/primary/events')
+ * const listEvents = integration.createFetcher(listCalendarEvents)
+ * const res = await listEvents({ query: { timeMin: now, singleEvents: "true" } })
  */
 declare function defineIntegration<const TId extends string>(definition: IntegrationDefinition<TId>): IntegrationAction<TId>;
 //#endregion

package/dist/action.js

@@ -38,12 +38,14 @@ function defineWorkflow(definition) {
 	};
 }
 function defineIntegration(definition) {
-	const { id, integrationId, permissions } = definition;
+	const { id, integrationId, method, url, permissions } = definition;
 	return {
 		id,
 		resource: {
 			type: "INTEGRATION",
-			integrationId
+			integrationId,
+			method,
+			url
 		},
 		permissions
 	};

package/dist/auth/session.js

@@ -3,7 +3,6 @@ import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
 import { userSchema } from "./user.js";
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { getRequestProtocol } from "@tanstack/react-start/server";
 import { z } from "zod";
 
@@ -36,20 +35,8 @@ function sessionCookie(base) {
 		secure
 	};
 }
-/**
-* Runs `fn` with `token` standing in for the request's session cookie, so that
-* every datasource call inside it acts as that visitor.
-*
-* For requests that carry who they are somewhere other than the cookie: an MCP
-* call authenticates with a bearer token and has no cookie at all.
-*/
-function withSessionToken(token, fn) {
-	return standInToken.run(token, fn);
-}
 /** The platform token this request carries, or `null`. */
 function readSessionToken() {
-	const standIn = standInToken.getStore();
-	if (standIn !== void 0) return standIn;
 	const { name } = sessionCookie(SESSION_TOKEN);
 	return openEnvelope(readRequestCookies()[name], SESSION_TOKEN);
 }
@@ -118,7 +105,6 @@ function clearSession() {
 		PENDING_AUTH
 	]);
 }
-const standInToken = new AsyncLocalStorage();
 const sessionDataSchema = z.object({
 	user: userSchema.nullable(),
 	permissions: permissionsSchema,
@@ -210,4 +196,4 @@ function openEnvelope(raw, purpose) {
 }
 
 //#endregion
-export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken, withSessionToken };
+export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken };

package/dist/core/integration.d.ts

@@ -2,12 +2,13 @@ import { IntegrationAction } from "../action.js";
 
 //#region src/core/integration.d.ts
 interface IntegrationFetchInit {
-  method?: string;
+  params?: Record<string, string>;
+  query?: Record<string, string>;
   headers?: Record<string, string>;
   body?: string;
   signal?: AbortSignal;
 }
-declare function integrationCreateFetcher(action: IntegrationAction): (url: string, init?: IntegrationFetchInit) => Promise<Response>;
+declare function integrationCreateFetcher(action: IntegrationAction): (init?: IntegrationFetchInit) => Promise<Response>;
 declare const integration: {
   createFetcher: typeof integrationCreateFetcher;
 };

package/dist/core/integration.js

@@ -3,15 +3,14 @@ import { readSessionToken } from "../auth/session.js";
 import { dsUrl } from "../datasource/record.js";
 
 //#region src/core/integration.ts
-async function integrationFetch(action, url, { method = "GET", headers = {}, body, signal } = {}) {
+async function integrationFetch(action, { params, query, headers = {}, body, signal } = {}) {
 	if (signal?.aborted) throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
-	const upperMethod = method.toUpperCase();
 	const payload = {
-		method: upperMethod,
-		url,
+		method: action.resource.method,
+		url: buildUrl(action.resource.url, params, query),
 		headers
 	};
-	if (upperMethod !== "GET" && upperMethod !== "HEAD" && body !== void 0) payload.body = body;
+	if (body !== void 0) payload.body = body;
 	return fetch(`${dsUrl(action.id)}/proxy`, {
 		method: "POST",
 		headers: {
@@ -22,8 +21,16 @@ async function integrationFetch(action, url, { method = "GET", headers = {}, bod
 		signal
 	});
 }
+function buildUrl(template, params, query) {
+	let url = params === void 0 ? template : template.replace(/\{(\w+)\}/g, (_, key) => {
+		const value = params[key];
+		return value !== void 0 ? encodeURIComponent(value) : `{${key}}`;
+	});
+	if (query !== void 0 && Object.keys(query).length > 0) url += `?${new URLSearchParams(query).toString()}`;
+	return url;
+}
 function integrationCreateFetcher(action) {
-	return (url, init) => integrationFetch(action, url, init);
+	return (init) => integrationFetch(action, init);
 }
 const integration = { createFetcher: integrationCreateFetcher };
 

package/dist/datasource/record.js

@@ -249,7 +249,7 @@ function resolveTarget(subject, operation) {
 }
 function aliasFields(fields, aliases) {
 	const result = {};
-	for (const [alias, fieldId] of Object.entries(aliases)) result[alias] = fields[fieldId];
+	for (const [alias, fieldId] of Object.entries(aliases)) result[alias] = fields[fieldId] ?? null;
 	return result;
 }
 function dealiasData(data, select) {

package/dist/index.d.ts

@@ -6,8 +6,7 @@ import { SoftrContext } from "./auth/context.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
-import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
+export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/index.js

@@ -3,9 +3,8 @@ import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
-import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };
+export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.46-alpha.2";
+var version = "0.0.46-alpha.1";
 
 //#endregion
 export { version };

package/dist/server.js

@@ -1,6 +1,6 @@
 import { upload } from "./core/file-upload.js";
-import { ds } from "./datasource/datasource.js";
 import { auth } from "./auth/server.js";
+import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.46-alpha.2",
+  "version": "0.0.46-alpha.3",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 # Softr SDK core
@@ -20,7 +20,7 @@ metadata:
 
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 > **CRITICAL**: Every route file must declare its audience with `defineVisibility` and guard itself with that rule in `beforeLoad`. There is no default and nothing is inherited from a sibling.
-> **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the session. Do not add a second registration of it. `softrMcpMiddleware` is the one thing an app adds to `src/start.ts` itself — load the `softr-sdk/mcp` sub-skill before doing so.
+> **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register the middleware and resolve the session. Do not add a second registration.
 > **CRITICAL**: `workflow.trigger` lives on `@softr/sdk/server` and only runs inside a `createServerFn` handler. Use `defineWorkflow` from `@softr/sdk` to declare the action, then pass it to `workflow.trigger`. Load the `softr-sdk/workflows` sub-skill for the full pattern.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `record-queries` plus `routes-and-visibility`.
@@ -47,7 +47,6 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Trigger a Softr workflow | [workflows/SKILL.md](./workflows/SKILL.md) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
-| Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -79,16 +78,13 @@ Wiring a login, signup, or sign-out?
 Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
   load softr-sdk/integrations
 
-Opening the app to an AI assistant over MCP?
-  load softr-sdk/mcp
-
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.
 ```
 
 ## The wiring
 
-Already present in the app. Read it to understand where the visitor comes from. Do not recreate it. `softrMcpMiddleware` is the exception: it is not wired by default and is added here when the app opens itself to AI assistants.
+Already present in the app. Read it to understand where the visitor comes from. Do not recreate it.
 
 ```ts
 // src/start.ts: resolves the visitor once per request

package/skills/softr-sdk/auth/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/current-user/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/integrations/SKILL.md

@@ -2,14 +2,15 @@
 name: integrations
 description: >-
   Call a third-party service connected to the app as an integration:
-  defineIntegration from @softr/sdk declares the action with its integrationId
-  and permissions; integration.createFetcher from @softr/sdk/server binds it and
-  returns a fetcher function you call with url, optional method, headers, and
-  body. Check res.ok before res.json().
+  defineIntegration from @softr/sdk declares the action with its integrationId,
+  the one HTTP method and endpoint url it allows, and permissions;
+  integration.createFetcher from @softr/sdk/server binds it and returns a fetcher
+  function you call with optional params, query, headers, and body. Check res.ok
+  before res.json().
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -35,55 +36,87 @@ When the user attaches integrations to the chat, they appear in the `## Attached
 - integration `<integrationId>`, type `GMAIL`
 ```
 
-Pass the `integration` value as `integrationId` in `defineIntegration`. The `database` value is the table coordinate; integrations do not use it, so do not pass it anywhere. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL path, including any query parameters, directly in the `url` string.
+Pass the `integration` value as `integrationId` in `defineIntegration`. The `database` value is the table coordinate; integrations do not use it, so do not pass it anywhere. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL path in the `url` field. Pass query parameters via `query` on the fetcher call, not in the declared `url`.
 
 Either shape configures `defineIntegration`. An entry with no `database` coordinate carries the `integrationId`, which is all the call needs.
 
 ## Declare the integration action
 
 ```ts
-const googleCalendar = defineIntegration({
-  id: 'googleCalendar',
+const listCalendarEvents = defineIntegration({
+  id: 'listCalendarEvents',
   integrationId: '25d60213-ef4f-4fa0-b094-a46931b2d120',
+  method: 'GET',
+  url: 'https://www.googleapis.com/calendar/v3/calendars/primary/events',
   permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 ```
 
 Write the object inline in `defineIntegration`. Passing it through a variable widens the types.
 
+The action allows exactly one HTTP `method` and one endpoint `url`. The proxy denies a call whose method does not match. So **declare one action per operation** — reading a record and deleting it are two actions, each with its own `id` and its own audience.
+
+Declare the **full endpoint path**, not just the host — one action names one endpoint. For a dynamic path segment, write a `{placeholder}` token with any name — for example `url: 'https://api.stripe.com/v1/customers/{id}'` or `url: 'https://api.stripe.com/v1/invoices/{invoiceId}/void'`. Keep query parameters out of the declared `url`; add them to the call.
+
 ## Core pattern
 
-`integration.createFetcher(action)` binds the action and returns a fetcher function. Call that function with a `url` and optional `method`, `headers`, `body`, and `signal`.
+`integration.createFetcher(action)` binds the action and returns a fetcher function. The `method` and `url` come from the action — you do not repeat them on the call. Pass an optional init object with:
+
+- `params` — fills `{placeholder}` tokens in the declared url, one key per token.
+- `query` — appended as a query string (`?key=value`).
+- `headers` — extra request headers.
+- `body` — request body string.
+- `signal` — abort signal.
 
 ```ts
 const getCalendarEvents = createServerFn().handler(async () => {
-  const calendar = integration.createFetcher(googleCalendar)
+  const calendar = integration.createFetcher(listCalendarEvents)
   const now = new Date().toISOString()
-  const res = await calendar(
-    `https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=${now}&singleEvents=true&orderBy=startTime&maxResults=10`,
-  )
+  const res = await calendar({
+    query: { timeMin: now, singleEvents: 'true', orderBy: 'startTime', maxResults: '10' },
+  })
   if (!res.ok) throw new Error(`Integration request failed: ${res.status} ${await res.text()}`)
   return res.json()
 })
 ```
 
-Include query parameters directly in the `url` string — there is no separate `queryParams` option.
+For a dynamic path segment, pass `params` matching each `{placeholder}` token:
+
+```ts
+const getStripeCustomer = defineIntegration({
+  id: 'getStripeCustomer',
+  integrationId: 'wsint-stripe',
+  method: 'GET',
+  url: 'https://api.stripe.com/v1/customers/{id}',
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const fetchCustomer = createServerFn({ method: 'GET' })
+  .validator((data: { customerId: string }) => data)
+  .handler(async ({ data }) => {
+    const stripe = integration.createFetcher(getStripeCustomer)
+    const res = await stripe({ params: { id: data.customerId } })
+    if (!res.ok) throw new Error(`Stripe error: ${res.status} ${await res.text()}`)
+    return res.json()
+  })
+```
 
 ## POST request
 
 ```ts
-const slackDs = defineIntegration({
-  id: 'slack',
+const postSlackMessage = defineIntegration({
+  id: 'postSlackMessage',
   integrationId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  method: 'POST',
+  url: 'https://slack.com/api/chat.postMessage',
   permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 
 const sendSlackMessage = createServerFn({ method: 'POST' })
   .validator((data: { channel: string; text: string }) => data)
   .handler(async ({ data }) => {
-    const slack = integration.createFetcher(slackDs)
-    const res = await slack('https://slack.com/api/chat.postMessage', {
-      method: 'POST',
+    const slack = integration.createFetcher(postSlackMessage)
+    const res = await slack({
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ channel: data.channel, text: data.text }),
     })
@@ -163,3 +196,5 @@ If the API the user needs is not in the table above, call it directly from a ser
 **Setting Authorization headers.** Softr injects credentials automatically. A manually set `Authorization` header overrides the injected one and the request is rejected by the third-party API.
 
 **Not checking `res.ok`.** The fetcher returns the proxied response as-is. A 4xx or 5xx from the third-party API is not thrown — call `res.ok` or `res.status` before calling `res.json()`.
+
+**Reusing one action for a different endpoint.** An action authorizes one `method` and one endpoint `url`. A different endpoint belongs to a different action — declare one for it, with its own audience.

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -5,14 +5,15 @@ description: >-
   with ALL_USERS, LOGGED_IN_USERS or NON_LOGGED_IN_USERS, userGroupIds, and the
   ways to apply a rule: guardRoute and assertRouteAccess in a route,
   isAuthorized and checkAccess anywhere. Covers per-reason overrides, the
-  redirect and throw strategies, rendering an access error with isAccessError,
-  isUnauthenticatedError, isForbiddenError and isAlreadyAuthenticatedError,
-  guarding a layout, and the lint rule that requires a declaration alongside the
-  rules that reject a duplicate, computed or root-level one.
+  redirect and throw strategies, rendering an access error with
+  isAccessError, isUnauthenticatedError, isForbiddenError and
+  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that requires a
+  declaration alongside the rules that reject a duplicate, computed or
+  root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/workflows/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46-alpha.2
+  library_version: 0.0.46
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.

package/dist/mcp.d.ts

@@ -1,36 +0,0 @@
-import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start2 from "@tanstack/react-start";
-
-//#region src/mcp.d.ts
-
-type SoftrMcpOptions = {
-  /**
-   * The actions to expose as tools, from `defineQuery` and `defineMutation`.
-   *
-   * Listing them is deliberate: an action left out is invisible over MCP, even
-   * though the app's own pages may use it. The action's own `permissions` still
-   * decide who may run the ones that are listed.
-   */
-  actions?: Array<DatasourceAction>;
-};
-/**
- * Serves the MCP endpoint and its OAuth flow from the app's own origin.
- *
- * Register it in the app's `src/start.ts`, ahead of `softrAuthMiddleware`: it
- * answers its own paths and resolves the caller from the bearer token, so it
- * must not sit behind the session lookup that middleware does on every
- * request. Everything else passes straight through.
- *
- * @example
- * import { publishedPosts, addCafe } from './actions'
- *
- * export const startInstance = createStart(() => ({
- *   requestMiddleware: [
- *     softrMcpMiddleware({ actions: [publishedPosts, addCafe] }),
- *     softrAuthMiddleware(),
- *   ],
- * }))
- */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start2.RequestMiddlewareAfterServer<{}, undefined, undefined>;
-//#endregion
-export { softrMcpMiddleware };

package/dist/mcp.js

@@ -1,581 +0,0 @@
-import { fetch } from "./fetch.js";
-import { assert } from "./assertions.js";
-import { sessionConfig } from "./auth/config.js";
-import { readSessionToken, withSessionToken } from "./auth/session.js";
-import { makePlatform, platformApiUrl } from "./auth/platform.js";
-import { isDatasourceAction } from "./action.js";
-import { ds } from "./datasource/datasource.js";
-import { createMiddleware } from "@tanstack/react-start";
-import { z } from "zod";
-
-//#region src/mcp.ts
-const MCP_PATH = "/_softr/mcp";
-const AUTHORIZE_PATH = "/_softr/oauth/authorize";
-const TOKEN_PATH = "/_softr/oauth/token";
-const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
-const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
-/** Where a visitor signs in. The blank template routes `_auth/login` here. */
-const LOGIN_PATH = "/login";
-/** What the platform grants. Advertised here so a client asks for the same. */
-const SCOPES = ["mcp:read", "mcp:write"];
-/** What a client that named no scope gets. Matches the platform's own default. */
-const DEFAULT_SCOPE = "mcp:read";
-const SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26"];
-/**
-* Serves the MCP endpoint and its OAuth flow from the app's own origin.
-*
-* Register it in the app's `src/start.ts`, ahead of `softrAuthMiddleware`: it
-* answers its own paths and resolves the caller from the bearer token, so it
-* must not sit behind the session lookup that middleware does on every
-* request. Everything else passes straight through.
-*
-* @example
-* import { publishedPosts, addCafe } from './actions'
-*
-* export const startInstance = createStart(() => ({
-*   requestMiddleware: [
-*     softrMcpMiddleware({ actions: [publishedPosts, addCafe] }),
-*     softrAuthMiddleware(),
-*   ],
-* }))
-*/
-function softrMcpMiddleware(options = {}) {
-	const actions = /* @__PURE__ */ new Map();
-	for (const action of options.actions ?? []) {
-		assert(isDatasourceAction(action), "softrMcpMiddleware takes actions built by defineQuery or defineMutation");
-		const value = action;
-		assert(!actions.has(value.id), `two actions share the id "${value.id}"`);
-		actions.set(value.id, value);
-	}
-	return createMiddleware({ type: "request" }).server(async ({ next, request }) => {
-		const url = new URL(request.url);
-		const origin = url.origin;
-		switch (url.pathname) {
-			case PROTECTED_RESOURCE_PATH: return json({
-				resource: `${origin}${MCP_PATH}`,
-				authorization_servers: [origin],
-				bearer_methods_supported: ["header"],
-				scopes_supported: SCOPES
-			});
-			case AUTHORIZATION_SERVER_PATH: return json({
-				issuer: origin,
-				authorization_endpoint: `${origin}${AUTHORIZE_PATH}`,
-				token_endpoint: `${origin}${TOKEN_PATH}`,
-				response_types_supported: ["code"],
-				grant_types_supported: ["authorization_code", "refresh_token"],
-				code_challenge_methods_supported: ["S256"],
-				token_endpoint_auth_methods_supported: ["none", "client_secret_basic"],
-				client_id_metadata_document_supported: true,
-				scopes_supported: SCOPES
-			});
-			case AUTHORIZE_PATH: return await authorize(request);
-			case TOKEN_PATH: return await issueToken(request);
-			case MCP_PATH: return await rpc(request, origin, actions);
-			default: return await next();
-		}
-	});
-}
-const authorizeQuerySchema = z.object({
-	client_id: z.string().min(1),
-	redirect_uri: z.string().url(),
-	response_type: z.literal("code"),
-	code_challenge: z.string().min(1),
-	code_challenge_method: z.literal("S256"),
-	state: z.string().optional(),
-	scope: z.string().optional(),
-	resource: z.string().optional()
-});
-/**
-* The Allow page, and the approval itself.
-*
-* We know who the visitor is from the app's session cookie — readable only
-* because this runs on the app's origin. The client and the code are the
-* platform's, so we ask it for both.
-*/
-async function authorize(request) {
-	const url = new URL(request.url);
-	const query = authorizeQuerySchema.safeParse(Object.fromEntries(url.searchParams));
-	if (!query.success) return html(400, page("This request is not valid", "The app that sent you here left something out. Close this window and try connecting again."));
-	if (request.method !== "GET" && request.method !== "POST") return methodNotAllowed("GET, POST");
-	const sessionToken = readSessionToken();
-	const user = sessionToken === null ? null : await resolveUser(sessionToken);
-	if (user === null || sessionToken === null) return html(200, signInPage(url));
-	const client = await platformConsent(query.data);
-	if (!client.ok) return html(400, page("We can't connect this right now", escapeHtml(client.message)));
-	if (request.method === "GET") return html(200, consentPage(user, url, client.name));
-	const form = await request.formData();
-	const decision = await platformApprove(sessionToken, query.data, form.get("decision") === "allow");
-	if (!decision.ok) return html(502, page("We could not finish this", decision.message));
-	return redirect(decision.redirectUri);
-}
-/**
-* Passes the token request straight through. The code and refresh token are the
-* platform's, so only it can redeem them. The client's credentials ride along
-* in the Authorization header untouched.
-*/
-async function issueToken(request) {
-	if (request.method !== "POST") return methodNotAllowed("POST");
-	const authorization = request.headers.get("authorization");
-	const response = await platformFetch("/v1/oauth/token", {
-		method: "POST",
-		headers: {
-			"content-type": "application/x-www-form-urlencoded",
-			...authorization === null ? {} : { authorization }
-		},
-		body: await request.text()
-	});
-	return new Response(await response.text(), {
-		status: response.status,
-		headers: {
-			"content-type": "application/json",
-			"access-control-allow-origin": "*",
-			"cache-control": "no-store"
-		}
-	});
-}
-/**
-* Tells the platform which app this is about. It normally works that out from
-* the domain, and none of the calls below arrive on the app's domain.
-*/
-const APPLICATION_ID_HEADER = "Softr-Application-ID";
-/**
-* An unreachable platform comes back as a 503, not a thrown error, so callers
-* can handle it with the `response.ok` check they already do. If it threw, the
-* MCP endpoint would answer 500 where the client needs a refusal it can act on.
-*/
-async function platformFetch(path, init) {
-	const { applicationId } = sessionConfig();
-	try {
-		return await fetch(`${await platformApiUrl()}${path}`, {
-			method: init.method,
-			headers: {
-				accept: "application/json",
-				[APPLICATION_ID_HEADER]: applicationId,
-				...init.headers
-			},
-			body: init.body
-		});
-	} catch {
-		return json({ message: "Softr could not be reached. Try again in a moment." }, 503);
-	}
-}
-/** The name to show on the Allow page, or why there's nothing to approve. */
-async function platformConsent(query) {
-	const response = await platformFetch(`/v1/oauth/authorize?${new URLSearchParams({
-		client_id: query.client_id,
-		redirect_uri: query.redirect_uri,
-		response_type: query.response_type,
-		code_challenge: query.code_challenge,
-		code_challenge_method: query.code_challenge_method,
-		state: query.state ?? "",
-		scope: query.scope ?? DEFAULT_SCOPE
-	})}`, { method: "GET" });
-	const body = await response.json().catch(() => null);
-	if (!response.ok) {
-		const refusal = z.object({ message: z.string() }).safeParse(body);
-		return {
-			ok: false,
-			message: refusal.success ? refusal.data.message : "The assistant asking for access is not set up for this app."
-		};
-	}
-	const parsed = z.object({ client_name: z.string().nullish() }).safeParse(body);
-	return {
-		ok: true,
-		name: parsed.success && parsed.data.client_name ? parsed.data.client_name : "An AI assistant"
-	};
-}
-/**
-* Records the answer and returns where to send the browser next — with a code
-* if they allowed it, an error if they didn't. The session token goes in the
-* header. The platform reads a cookie from its own consent page, but this
-* isn't that page.
-*/
-async function platformApprove(sessionToken, query, approved) {
-	const response = await platformFetch("/v1/oauth/authorize", {
-		method: "POST",
-		headers: {
-			"content-type": "application/json",
-			authorization: `Bearer ${sessionToken}`
-		},
-		body: JSON.stringify({
-			client_id: query.client_id,
-			redirect_uri: query.redirect_uri,
-			state: query.state ?? "",
-			code_challenge: query.code_challenge,
-			code_challenge_method: query.code_challenge_method,
-			scope: query.scope ?? DEFAULT_SCOPE,
-			approved
-		})
-	});
-	const parsed = z.object({ redirect_uri: z.string().url() }).safeParse(await response.json().catch(() => null));
-	if (!response.ok || !parsed.success) return {
-		ok: false,
-		message: "The app could not record your answer. Close this window and try connecting again."
-	};
-	return {
-		ok: true,
-		redirectUri: parsed.data.redirect_uri
-	};
-}
-async function platformSession(accessToken) {
-	const response = await platformFetch("/v1/mcp/session", {
-		method: "POST",
-		headers: { authorization: `Bearer ${accessToken}` }
-	});
-	if (!response.ok) return {
-		ok: false,
-		refused: response.status === 401 || response.status === 403
-	};
-	const parsed = z.object({ jwt: z.string() }).safeParse(await response.json().catch(() => null));
-	return parsed.success ? {
-		ok: true,
-		sessionToken: parsed.data.jwt
-	} : {
-		ok: false,
-		refused: false
-	};
-}
-const WHOAMI = {
-	name: "whoami",
-	title: "Who am I",
-	description: "Returns the Softr user this connection is authenticated as: their name, email and user group ids. Use it to confirm which account the app sees.",
-	inputSchema: {
-		type: "object",
-		properties: {},
-		additionalProperties: false
-	}
-};
-/** How many records a read returns when the caller does not say. */
-const DEFAULT_LIMIT = 20;
-const MAX_LIMIT = 100;
-/**
-* One tool per action the app chose to expose.
-*
-* The app passes its actions in rather than the SDK discovering them, so that
-* being reachable over MCP is something an app opts into per action. An app
-* that only ever reads one datasource exposes one read, even though its
-* credentials would allow more.
-*/
-function describeTool(action) {
-	const { operation, fields } = action.resource;
-	const names = Object.keys(fields ?? {});
-	const fieldProps = Object.fromEntries(names.map((name) => [name, { description: `The "${name}" field.` }]));
-	switch (operation) {
-		case "read": return {
-			name: action.id,
-			description: `Read records from "${action.id}". Returns the fields ${names.join(", ")}. Only records the signed-in user may see come back.`,
-			inputSchema: {
-				type: "object",
-				properties: {
-					limit: {
-						type: "integer",
-						minimum: 1,
-						maximum: MAX_LIMIT,
-						description: `How many records to return. Defaults to ${DEFAULT_LIMIT}.`
-					},
-					offset: {
-						type: "integer",
-						minimum: 0,
-						description: "Where the page starts. Use nextOffset from a previous call."
-					}
-				},
-				additionalProperties: false
-			}
-		};
-		case "create": return {
-			name: action.id,
-			description: `Create a record with "${action.id}". Writable fields: ${names.join(", ")}.`,
-			inputSchema: {
-				type: "object",
-				properties: fieldProps,
-				additionalProperties: false
-			}
-		};
-		case "update": return {
-			name: action.id,
-			description: `Update a record with "${action.id}". Writable fields: ${names.join(", ")}.`,
-			inputSchema: {
-				type: "object",
-				properties: {
-					id: {
-						type: "string",
-						description: "The id of the record to update."
-					},
-					...fieldProps
-				},
-				required: ["id"],
-				additionalProperties: false
-			}
-		};
-		case "delete": return {
-			name: action.id,
-			description: `Delete a record with "${action.id}".`,
-			inputSchema: {
-				type: "object",
-				properties: { id: {
-					type: "string",
-					description: "The id of the record to delete."
-				} },
-				required: ["id"],
-				additionalProperties: false
-			}
-		};
-	}
-}
-/**
-* Runs one action as the visitor the access token belongs to.
-*
-* Every call goes through `ds`, so the platform authorizes it against that
-* visitor's user groups exactly as it would a click in the app. Nothing here
-* decides what is allowed.
-*/
-async function runTool(action, args) {
-	const typed = action;
-	switch (action.resource.operation) {
-		case "read": {
-			const limit = clampLimit(args.limit);
-			const offset = clampOffset(args.offset);
-			const result$1 = await ds.list(typed).limit(limit).offset(offset);
-			return {
-				records: result$1.records,
-				nextOffset: result$1.nextOffset
-			};
-		}
-		case "create": return await ds.create(typed, { data: writableFields(action, args) });
-		case "update": {
-			const { id,...data } = args;
-			assert(typeof id === "string" && id !== "", "update needs a record id");
-			return await ds.update(typed, {
-				id,
-				data: writableFields(action, data)
-			});
-		}
-		case "delete": {
-			const { id } = args;
-			assert(typeof id === "string" && id !== "", "delete needs a record id");
-			await ds.delete(typed, { id });
-			return { deleted: id };
-		}
-	}
-}
-/**
-* Only the fields the action declared.
-*
-* `additionalProperties: false` in the tool schema is a hint to the model, not
-* a check — a client can send whatever it likes. An unlisted key reaches the
-* datasource as a raw field id, because `dealiasData` passes an unknown alias
-* straight through. So the action's field list gets enforced here, or it isn't
-* a boundary at all.
-*/
-function writableFields(action, args) {
-	const allowed = action.resource.fields ?? {};
-	return Object.fromEntries(Object.entries(args).filter(([name]) => name in allowed));
-}
-function clampLimit(raw) {
-	if (typeof raw !== "number" || !Number.isInteger(raw)) return DEFAULT_LIMIT;
-	return Math.min(Math.max(raw, 1), MAX_LIMIT);
-}
-function clampOffset(raw) {
-	if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) return null;
-	return raw;
-}
-async function rpc(request, origin, actions) {
-	if (request.method !== "POST") return methodNotAllowed("POST");
-	const token = bearerToken(request);
-	if (token === null) return unauthorized(origin);
-	const session = await platformSession(token);
-	if (!session.ok) return session.refused ? unauthorized(origin) : unavailable();
-	const { sessionToken } = session;
-	const body = await readJson(request);
-	const message = z.object({
-		id: z.union([z.string(), z.number()]).optional(),
-		method: z.string(),
-		params: z.record(z.string(), z.unknown()).optional()
-	}).safeParse(body);
-	if (!message.success) return json({
-		jsonrpc: "2.0",
-		id: null,
-		error: {
-			code: -32700,
-			message: "Parse error"
-		}
-	});
-	const { id, method, params } = message.data;
-	if (id === void 0) return new Response(null, { status: 202 });
-	switch (method) {
-		case "initialize": {
-			const requested = params?.protocolVersion;
-			return result(id, {
-				protocolVersion: typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : SUPPORTED_PROTOCOL_VERSIONS[0],
-				capabilities: { tools: { listChanged: false } },
-				serverInfo: {
-					name: "softr-app",
-					version: "0.1.0"
-				}
-			});
-		}
-		case "tools/list": return result(id, { tools: [WHOAMI, ...[...actions.values()].map(describeTool)] });
-		case "tools/call": {
-			const name = params?.name;
-			const args = typeof params?.arguments === "object" && params.arguments !== null ? params.arguments : {};
-			if (name === WHOAMI.name) {
-				const user = await resolveUser(sessionToken);
-				if (user === null) return unauthorized(origin);
-				return result(id, toolResult(user));
-			}
-			const action = typeof name === "string" ? actions.get(name) : void 0;
-			if (action === void 0) return failure(id, -32602, `Unknown tool: ${String(name)}`);
-			try {
-				return result(id, toolResult(await withSessionToken(sessionToken, () => runTool(action, args))));
-			} catch (error) {
-				return result(id, {
-					isError: true,
-					content: [{
-						type: "text",
-						text: error instanceof Error ? error.message : String(error)
-					}]
-				});
-			}
-		}
-		default: return failure(id, -32601, `Method not found: ${method}`);
-	}
-}
-function toolResult(output) {
-	return {
-		content: [{
-			type: "text",
-			text: JSON.stringify(output, null, 2)
-		}],
-		structuredContent: output
-	};
-}
-function result(id, payload) {
-	return json({
-		jsonrpc: "2.0",
-		id,
-		result: payload
-	});
-}
-function failure(id, code, message) {
-	return json({
-		jsonrpc: "2.0",
-		id,
-		error: {
-			code,
-			message
-		}
-	});
-}
-function unauthorized(origin) {
-	return new Response(JSON.stringify({ error: "invalid_token" }), {
-		status: 401,
-		headers: {
-			"content-type": "application/json",
-			"www-authenticate": `Bearer resource_metadata="${origin}${PROTECTED_RESOURCE_PATH}", scope="${SCOPES.join(" ")}"`
-		}
-	});
-}
-/** The platform is down, not the token. 503 so the client retries rather than
-* throwing its token away. */
-function unavailable() {
-	return json({ error: "temporarily_unavailable" }, 503);
-}
-function bearerToken(request) {
-	const header = request.headers.get("authorization");
-	if (header === null) return null;
-	const [scheme, value] = header.split(" ");
-	return scheme?.toLowerCase() === "bearer" && value ? value : null;
-}
-/**
-* The visitor a session token belongs to, or `null` when the platform refuses
-* it — expired, revoked, or issued for another application.
-*/
-async function resolveUser(sessionToken) {
-	const { applicationId } = sessionConfig();
-	const result$1 = await makePlatform(applicationId).session(sessionToken);
-	return result$1.ok ? result$1.data.user : null;
-}
-async function readJson(request) {
-	try {
-		return await request.json();
-	} catch {
-		return null;
-	}
-}
-function json(payload, status = 200) {
-	return new Response(JSON.stringify(payload), {
-		status,
-		headers: {
-			"content-type": "application/json",
-			"access-control-allow-origin": "*",
-			"cache-control": "no-store"
-		}
-	});
-}
-function methodNotAllowed(allowed) {
-	return new Response(null, {
-		status: 405,
-		headers: { allow: allowed }
-	});
-}
-function redirect(location) {
-	return new Response(null, {
-		status: 302,
-		headers: { location }
-	});
-}
-function html(status, body) {
-	return new Response(body, {
-		status,
-		headers: {
-			"content-type": "text/html; charset=utf-8",
-			"cache-control": "no-store"
-		}
-	});
-}
-function consentPage(user, url, clientName) {
-	const fields = Array.from(url.searchParams.entries()).map(([key, value]) => `<input type="hidden" name="${escapeHtml(key)}" value="${escapeHtml(value)}">`).join("");
-	return page("Connect to this app?", `<strong>${escapeHtml(clientName)}</strong> is asking to use this app as <strong>${escapeHtml(user.fullName || user.email)}</strong>. It will see only what you can see.`, `<form method="post" action="${escapeHtml(url.pathname + url.search)}">
-       ${fields}
-       <button type="submit" name="decision" value="allow" class="primary">Allow</button>
-       <button type="submit" name="decision" value="deny">Cancel</button>
-     </form>`);
-}
-function signInPage(url) {
-	return page("Sign in first", "You need to be signed in to this app before you can connect an assistant to it.", `<a class="primary" href="${LOGIN_PATH}?redirect=${encodeURIComponent(url.pathname + url.search)}">Sign in</a>`);
-}
-function page(title, body, actions = "") {
-	return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(title)}</title>
-<style>
-  :root { color-scheme: light dark; }
-  body {
-    margin: 0; min-height: 100vh; display: grid; place-items: center;
-    font: 15px/1.55 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
-    background: Canvas; color: CanvasText; padding: 24px;
-  }
-  main { max-width: 26rem; }
-  h1 { font-size: 1.35rem; margin: 0 0 .6rem; }
-  p { margin: 0 0 1.5rem; opacity: .8; }
-  form { display: flex; gap: .6rem; flex-wrap: wrap; }
-  button, a.primary {
-    font: inherit; padding: .55rem 1.1rem; border-radius: .4rem; cursor: pointer;
-    border: 1px solid currentColor; background: transparent; color: inherit;
-    text-decoration: none; display: inline-block;
-  }
-  .primary { background: CanvasText; color: Canvas; border-color: CanvasText; }
-</style>
-</head>
-<body><main><h1>${escapeHtml(title)}</h1><p>${body}</p>${actions}</main></body>
-</html>`;
-}
-function escapeHtml(value) {
-	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
-}
-
-//#endregion
-export { softrMcpMiddleware };

package/skills/softr-sdk/mcp/SKILL.md

@@ -1,86 +0,0 @@
----
-name: mcp
-description: >-
-  Open the app to AI assistants over MCP: softrMcpMiddleware({ actions }) from
-  @softr/sdk, registered in src/start.ts ahead of softrAuthMiddleware, turns the
-  actions you list into tools an assistant can call as the signed-in visitor.
-  The list is explicit — an action left out is invisible over MCP. The app's own
-  login must honour a `redirect` search param, or the approval step dead-ends.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.46-alpha.2
----
-
-**Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.
-
-# MCP
-
-An app can answer an AI assistant on its own origin. The assistant signs in as an ordinary app user, and the actions you list become the tools it may call. Not wired by default — a new app serves no MCP endpoint until you add the middleware.
-
-## The URL
-
-The app's own public origin, plus `/_softr/mcp`:
-
-```
-https://myapp.mysoftr.app/_softr/mcp
-```
-
-Custom domain, default subdomain, a staging host — whatever origin the app is published on, the path is the same. That whole string is the MCP URL. The origin on its own is the app's home page, and an assistant pointed at it gets HTML back.
-
-## Setup
-
-```ts
-// src/start.ts
-import { createCsrfMiddleware, createStart } from '@tanstack/react-start'
-import { softrAuthMiddleware, softrMcpMiddleware } from '@softr/sdk'
-import { listCafes, addCafe } from './actions'
-
-export const startInstance = createStart(() => ({
-  requestMiddleware: [
-    createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === 'serverFn' }),
-    softrMcpMiddleware({ actions: [listCafes, addCafe] }),
-    softrAuthMiddleware(),
-  ],
-}))
-```
-
-Order is part of the contract. `softrMcpMiddleware` goes **before** `softrAuthMiddleware`: an assistant arrives with a token, not a browser session, so it must not hit the session lookup first.
-
-## Choosing the actions
-
-The list is the whole tool surface. Write it out:
-
-- An action you leave out is invisible to the assistant, even where the app's pages use it freely.
-- An action you list still obeys its own `permissions`. Listing it does not widen who may run it — the assistant runs as whoever signed in, with that user's groups.
-- Two actions with the same `id` throw at startup. So does anything that is not a `defineQuery` or `defineMutation` value.
-
-Reads first. Add a write only when the user asked for one, and name it back to them.
-
-## The login round trip
-
-Connecting starts with an approval page the app serves. Most people hit it signed out, and that page cannot sign anyone in. It sends them to `/login` with a `redirect` search param holding where to come back to.
-
-**The app's login has to honour that param.** Carry it through every exit that ends a sign-in, the second-factor step included, and send the visitor there instead of the home page. Drop it anywhere along the way and the approval dies quietly: they land on the home page, the assistant never gets its answer, nothing reports an error.
-
-Validate it before following it. A path on this app and nothing else — not a full URL, not one starting `//`. The whole flow starts with a link someone was sent, so this is the one redirect an attacker can reliably aim.
-
-The blank template does this in `src/routes/_auth/login.tsx`, `src/routes/verify.tsx` and `src/lib/after-auth.ts`. Read those before writing your own.
-
-## Failure modes
-
-**Registering with no actions.** `softrMcpMiddleware()` is valid and serves an endpoint with nothing on it. The assistant connects, lists tools, finds only `whoami`. Pass the actions.
-
-**Registering after `softrAuthMiddleware`.** The assistant's token is never read. Put the MCP middleware first.
-
-**Handing over the app's URL as the MCP URL.** The origin is where the app's pages are. Without `/_softr/mcp` on the end the assistant has nothing to talk to, and the owner is left comparing a URL that looks right against a connection that never works.
-
-**A login that drops `redirect`.** Sign-in works, approval doesn't. The most common break, and silent — test the connect flow signed out, not only signed in.
-
-**Following `redirect` unchecked.** Anything that is not a path on this app is someone else's page. Reject it, fall back to `/`.
-
-## References
-
-- [record-queries/SKILL.md](../record-queries/SKILL.md): declaring the read actions you expose
-- [record-mutations/SKILL.md](../record-mutations/SKILL.md): declaring the write actions you expose
-- [auth/SKILL.md](../auth/SKILL.md): the sign-in and second-factor flows the round trip passes through