@softr/sdk 0.0.46 → 0.0.47

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/index.d.ts

@@ -6,7 +6,8 @@ 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, 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, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/index.js

@@ -3,8 +3,9 @@ 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, useCurrentUser, useFileUpload, useUserTimezone };
+export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/mcp.d.ts

@@ -0,0 +1,42 @@
+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>;
+  /**
+   * The app's sign-in page, as a path on this app. A signed-out visitor who
+   * opens the approval page is sent here with `?redirect=` pointing back at it.
+   * Defaults to `/login`.
+   */
+  loginPath?: string;
+};
+/**
+ * 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,580 @@
+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";
+/** 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 loginPath = options.loginPath ?? "/login";
+	assert(loginPath.startsWith("/") && new URL(loginPath, "https://app.invalid").origin === "https://app.invalid", `softrMcpMiddleware's loginPath must be a path on this app, got "${loginPath}"`);
+	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, loginPath);
+			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, loginPath) {
+	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, loginPath));
+	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) {
+	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)}">
+       <button type="submit" name="decision" value="allow" class="primary">Allow</button>
+       <button type="submit" name="decision" value="deny">Cancel</button>
+     </form>`);
+}
+function signInPage(url, loginPath) {
+	const back = encodeURIComponent(url.pathname + url.search);
+	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="${escapeHtml(loginPath)}?redirect=${back}">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/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,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "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
+  library_version: 0.0.47
 ---
 
 # 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 the middleware and resolve the session. Do not add a second registration.
+> **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**: `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,6 +47,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
 
@@ -78,13 +79,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/auth/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46
+  library_version: 0.0.47
 ---
 
 **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
+  library_version: 0.0.47
 ---
 
 **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
+  library_version: 0.0.47
 ---
 
 # 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
+  library_version: 0.0.47
 ---
 
 **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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46
+  library_version: 0.0.47
 ---
 
 **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.

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

@@ -0,0 +1,90 @@
+---
+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.47
+---
+
+**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`, and that is the only order it supports.
+
+## 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 the app's sign-in page with a `redirect` search param holding where to come back to. That page is `/login` unless you pass `loginPath`:
+
+```ts
+softrMcpMiddleware({ actions: [listCafes], loginPath: '/sign-in' })
+```
+
+**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. Ask the URL parser rather than checking prefixes: resolve the value against a placeholder origin and reject it unless the origin survives. Browsers read `\` as `/` and drop tabs and newlines, so a value that does not start with `//` can still leave the app. 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`.** Not a supported order. 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, or checked by prefix.** Anything that is not a path on this app is someone else's page, and `/\evil.test` is one of them. Let the URL parser decide, and 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

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
+  library_version: 0.0.47
 ---
 
 **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
+  library_version: 0.0.47
 ---
 
 **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
+  library_version: 0.0.47
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.46
+  library_version: 0.0.47
 ---
 
 **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
+  library_version: 0.0.47
 ---
 
 **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.