@softr/sdk 0.0.43 → 0.0.45-alpha.0

package/dist/auth/session.js

@@ -3,6 +3,7 @@ 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";
 
@@ -35,8 +36,20 @@ 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);
 }
@@ -105,6 +118,7 @@ function clearSession() {
 		PENDING_AUTH
 	]);
 }
+const standInToken = new AsyncLocalStorage();
 const sessionDataSchema = z.object({
 	user: userSchema.nullable(),
 	permissions: permissionsSchema,
@@ -196,4 +210,4 @@ function openEnvelope(raw, purpose) {
 }
 
 //#endregion
-export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken };
+export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken, withSessionToken };

package/dist/boot-error.js

@@ -23,6 +23,17 @@ function bootErrorMiddleware() {
 		}
 	});
 }
+/**
+* Faults of the dev server rather than the app: a module graph swapped under a render already in
+* flight, so React's dispatcher or a split chunk belongs to a generation that is gone. The next
+* request reads the settled graph and succeeds, which is why these clear on their own — and why
+* showing one is worse than useless. The page invites the reader to copy it to the agent, and an
+* agent handed a phantom spends a repair round looking for it in code that is correct.
+*/
+const TRANSIENT = [/Cannot read properties of (?:null|undefined) \(reading 'use[A-Z]/, /Failed to fetch dynamically imported module/];
+function isTransientBootError(message) {
+	return TRANSIENT.some((pattern) => pattern.test(message));
+}
 function errorPage(error) {
 	if (process.env.NODE_ENV === "production") return page("Something went wrong", "This page couldn’t be shown. Try again in a moment, and if it keeps happening, reach out to the owner of this app.", { note: "If you are the owner, you can check what happened in Studio." });
 	const cause = error instanceof Error ? error.cause : void 0;
@@ -31,6 +42,7 @@ function errorPage(error) {
 	const stack = root instanceof Error ? root.stack : void 0;
 	return page("This app crashed", "The app stopped before it could start. The technical details below show where it failed and can be copied to the agent to help fix the issue.", {
 		note: "These details are only shown because the app is running in development mode.",
+		autoRetry: isTransientBootError(message),
 		detail: `<pre class="message">${escapeHtml(message)}</pre>`,
 		actions: stack ? `<button type="button" id="toggle" aria-expanded="true" aria-controls="panel">
              <svg class="chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>
@@ -71,7 +83,7 @@ function errorPage(error) {
            <\/script>` : ""
 	});
 }
-function page(title, description, { note = "", detail = "", actions = "", panel = "" } = {}) {
+function page(title, description, { note = "", detail = "", actions = "", panel = "", autoRetry = false } = {}) {
 	return `<!doctype html>
 <html lang="en">
   <head>
@@ -222,7 +234,7 @@ function page(title, description, { note = "", detail = "", actions = "", panel
     </style>
   </head>
   <body>
-    <main>
+    <main${autoRetry ? " hidden" : ""}>
       <div class="alert">
         <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
       </div>
@@ -241,9 +253,37 @@ function page(title, description, { note = "", detail = "", actions = "", panel
       </div>
       ${panel}
     </main>
+    ${autoRetry ? RETRY_SCRIPT : ""}
   </body>
 </html>`;
 }
+/**
+* One reload, then the page reveals itself. The reload is what the reader would have done by hand,
+* so a fault that clears is never seen; a fault that survives it shows the same page it always did.
+* Session storage is what remembers the attempt, and a preview frame may refuse it — then there is
+* no way to count, and the honest move is to show the error rather than risk reloading forever.
+*/
+const RETRY_SCRIPT = `<noscript><style>main[hidden] { display: flex !important }</style></noscript>
+<script>
+  (() => {
+    const KEY = 'softr:boot-retry'
+    const reveal = () => { document.querySelector('main').hidden = false }
+
+    let store = null
+    try { store = sessionStorage } catch { /* blocked in this frame */ }
+    if (!store) return reveal()
+
+    const now = Date.now()
+    if (now - Number(store.getItem(KEY) ?? 0) < 15000) {
+      store.removeItem(KEY)
+      return reveal()
+    }
+
+    store.setItem(KEY, String(now))
+    // A beat, so the reload lands after the dev server has finished rebuilding rather than during.
+    setTimeout(() => location.reload(), 500)
+  })()
+<\/script>`;
 function escapeHtml(value) {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { FileItem, useFileUpload } from "./core/use-file-upload.js";
 import { SoftrContext } from "./auth/context.js";
 import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
+import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { type ActionPermissions, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+export { type ActionPermissions, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };

package/dist/index.js

@@ -2,7 +2,8 @@ import { useFileUpload } from "./core/use-file-upload.js";
 import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
+import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 
-export { DefaultErrorOverlay, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+export { DefaultErrorOverlay, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };

package/dist/mcp.d.ts

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,581 @@
+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/dist/package.js

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

package/dist/server.js

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

package/package.json

@@ -1,16 +1,37 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.43",
+  "version": "0.0.45-alpha.0",
   "type": "module",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
-    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
-    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
-  },
-  "bin": { "softr-sdk": "./dist/cli.js" },
-  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
-  "publishConfig": { "access": "public" },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "bin": {
+    "softr-sdk": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -42,7 +63,9 @@
       "optional": true
     }
   },
-  "keywords": ["tanstack-intent"],
+  "keywords": [
+    "tanstack-intent"
+  ],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

package/skills/softr-sdk/SKILL.md

@@ -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`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
-> **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**: The session wiring is already in place. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the visitor. 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**: `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`.
@@ -46,6 +46,7 @@ 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
 
@@ -74,13 +75,16 @@ 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.
+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.
 
 ```ts
 // src/start.ts: resolves the visitor once per request

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

@@ -0,0 +1,74 @@
+---
+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.44
+---
+
+**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.
+
+## 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.
+
+**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