@classytic/arc 2.15.4 → 2.16.0

package/dist/{resourceToTools-tFYUNmM0.mjs → mcpPlugin-7vGV51ED.mjs}

@@ -1,13 +1,16 @@
 import { p as isArcError } from "./errors-j4aJm1Wg.mjs";
-import { t as BaseController } from "./BaseController-dx3m2J8V.mjs";
-import { L as normalizePermissionResult } from "./permissions-ohQyv50e.mjs";
-import { t as executePipeline } from "./pipe-Zr0KXjQe.mjs";
-import { u as resolvePipelineSteps } from "./routerShared-DrOa-26E.mjs";
-import { n as executeAggregation, r as validateAggregations } from "./buildHandler-CcFOpJLh.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-CyUkQu6O.mjs";
-import { i as shouldRejectAdditionalProperties, r as schemaIRToZodShape, t as normalizeSchemaIR } from "./schemaIR-lYhC2gE5.mjs";
-import { t as pluralize } from "./pluralize-DQgqgifU.mjs";
+import { t as BaseController } from "./BaseController-DlCCTIxJ.mjs";
+import { L as normalizePermissionResult } from "./permissions-CTxMrreC.mjs";
+import { t as executePipeline } from "./pipe-DiCyvyPN.mjs";
+import { u as resolvePipelineSteps } from "./routerShared-CZV5aabX.mjs";
+import { r as validateAggregations } from "./validate-By96rH0r.mjs";
+import { n as executeAggregation } from "./buildHandler-BZX6zzDM.mjs";
+import { t as pluralize } from "./pluralize-B9M8xvy-.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-Bjmvn7Eb.mjs";
+import { i as shouldRejectAdditionalProperties, r as schemaIRToZodShape, t as normalizeSchemaIR } from "./schemaIR-Ctc89DSn.mjs";
+import { createHash, randomUUID } from "node:crypto";
 import { isHttpError, toErrorContract } from "@classytic/repo-core/errors";
+import fp from "fastify-plugin";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**
@@ -71,147 +74,6 @@ function registerPrompt(server, prompt) {
 	srv.registerPrompt(prompt.name, config, (args) => prompt.handler(args));
 }
 //#endregion
-//#region src/integrations/mcp/fieldRulesToZod.ts
-/**
-* @classytic/arc — fieldRules → Zod Shape Converter
-*
-* Converts Arc's schemaOptions.fieldRules into flat Zod shapes
-* compatible with the MCP SDK's registerTool() inputSchema format.
-*
-* Returns `Record<string, z.ZodTypeAny>` (flat shape), NOT z.object().
-* The SDK wraps it internally.
-*
-* @example
-* ```typescript
-* import { fieldRulesToZod } from '@classytic/arc/mcp';
-*
-* const shape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
-*   mode: 'create',
-*   hiddenFields: resource.schemaOptions.hiddenFields,
-* });
-* // shape = { name: z.string(), price: z.number() }
-* ```
-*/
-const PAGINATION_SHAPE = {
-	page: z.number().int().min(1).optional().describe("Page number (1-based)"),
-	limit: z.number().int().min(1).max(100).optional().describe("Items per page (max 100)"),
-	sort: z.string().optional().describe("Sort field, prefix with - for descending"),
-	search: z.string().optional().describe("Full-text search query"),
-	select: z.string().optional().describe("Comma-separated field list to project (e.g. 'name,price'). Prefix with '-' to exclude (e.g. '-description')."),
-	populate: z.string().optional().describe("Comma-separated relation paths to hydrate (e.g. 'supplier,category'). Follows Mongoose populate syntax when the adapter is MongoKit.")
-};
-/**
-* Convert Arc fieldRules to a flat Zod shape.
-*
-* @returns Flat shape `Record<string, z.ZodTypeAny>` — pass directly to defineTool() or registerTool()
-*/
-function fieldRulesToZod(fieldRules, options = {}) {
-	const { mode = "create", hiddenFields = [], readonlyFields = [], extraHideFields = [] } = options;
-	if (mode === "list") return buildListShape(fieldRules, options);
-	if (!fieldRules) return {};
-	const allHidden = new Set([...hiddenFields, ...extraHideFields]);
-	const allReadonly = new Set(readonlyFields);
-	const shape = {};
-	for (const [name, rule] of Object.entries(fieldRules)) {
-		if (rule.systemManaged || rule.hidden || allHidden.has(name)) continue;
-		if (allReadonly.has(name)) continue;
-		if (mode === "update" && rule.immutable) continue;
-		const field = buildFieldSchema(rule);
-		if (mode === "update") shape[name] = field.optional();
-		else shape[name] = rule.required === true && !rule.optional ? field : field.optional();
-	}
-	return shape;
-}
-/** Build Zod type for a single field rule */
-function buildFieldSchema(rule) {
-	if (rule.enum?.length) {
-		const schema = z.enum(rule.enum);
-		return rule.description ? schema.describe(rule.description) : schema;
-	}
-	const base = typeToZod(rule.type);
-	if (base instanceof z.ZodString) {
-		let s = base;
-		if (rule.minLength != null) s = s.min(rule.minLength);
-		if (rule.maxLength != null) s = s.max(rule.maxLength);
-		if (rule.pattern) try {
-			s = s.regex(new RegExp(rule.pattern));
-		} catch {}
-		return rule.description ? s.describe(rule.description) : s;
-	}
-	if (base instanceof z.ZodNumber) {
-		let n = base;
-		if (rule.min != null) n = n.min(rule.min);
-		if (rule.max != null) n = n.max(rule.max);
-		return rule.description ? n.describe(rule.description) : n;
-	}
-	return rule.description ? base.describe(rule.description) : base;
-}
-/** Map Arc field type string to base Zod type */
-function typeToZod(type) {
-	switch (type) {
-		case "string": return z.string();
-		case "number": return z.number();
-		case "boolean": return z.boolean();
-		case "date": return z.string().describe("ISO 8601 date string");
-		case "array": return z.array(z.any());
-		case "object": return z.record(z.string(), z.any());
-		default: return z.string();
-	}
-}
-/** Operators that apply to numeric/date fields */
-const COMPARISON_OPS = new Set([
-	"gt",
-	"gte",
-	"lt",
-	"lte"
-]);
-/** Map operator to a human-readable description suffix */
-function opDescription(op, fieldName) {
-	switch (op) {
-		case "gt": return `${fieldName} greater than`;
-		case "gte": return `${fieldName} greater than or equal`;
-		case "lt": return `${fieldName} less than`;
-		case "lte": return `${fieldName} less than or equal`;
-		case "ne": return `${fieldName} not equal to`;
-		case "in": return `${fieldName} in comma-separated list`;
-		case "nin": return `${fieldName} not in comma-separated list`;
-		case "exists": return `${fieldName} exists (true/false)`;
-		default: return `${fieldName} ${op}`;
-	}
-}
-/** Build list/query shape with filterable fields, operators, and pagination */
-function buildListShape(fieldRules, options) {
-	const { filterableFields = [], hiddenFields = [], extraHideFields = [], allowedOperators } = options;
-	const allHidden = new Set([...hiddenFields, ...extraHideFields]);
-	const shape = { ...PAGINATION_SHAPE };
-	if (!fieldRules) return shape;
-	for (const name of filterableFields) {
-		if (allHidden.has(name)) continue;
-		const rule = fieldRules[name];
-		if (!rule) continue;
-		if (rule.hidden || rule.systemManaged) continue;
-		const filterField = buildFieldSchema(rule);
-		shape[name] = filterField.optional();
-		if (allowedOperators?.length) {
-			const isNumericOrDate = rule.type === "number" || rule.type === "date";
-			for (const op of allowedOperators) {
-				if (COMPARISON_OPS.has(op) && !isNumericOrDate) continue;
-				if (op === "eq") continue;
-				if (op === "exists") {
-					shape[`${name}_${op}`] = z.boolean().optional().describe(opDescription(op, name));
-					continue;
-				}
-				if (op === "in" || op === "nin") {
-					shape[`${name}_${op}`] = z.string().optional().describe(opDescription(op, name));
-					continue;
-				}
-				shape[`${name}_${op}`] = filterField.optional().describe(opDescription(op, name));
-			}
-		}
-	}
-	return shape;
-}
-//#endregion
 //#region src/integrations/mcp/buildRequestContext.ts
 /**
 * Build an IRequestContext from MCP tool input and session auth.
@@ -254,12 +116,15 @@ function buildRequestContext(input, auth, operation, policyFilters, scopeOverrid
 			query: expandOperatorKeys(input),
 			body: void 0
 		};
-		case "get": return {
-			...base,
-			params: { id: String(input.id ?? "") },
-			query: {},
-			body: void 0
-		};
+		case "get": {
+			const { id, ...rest } = input;
+			return {
+				...base,
+				params: { id: String(id ?? "") },
+				query: expandOperatorKeys(rest),
+				body: void 0
+			};
+		}
 		case "create": return {
 			...base,
 			params: {},
@@ -434,85 +299,529 @@ function toCallToolResult(result) {
 	}] };
 }
 /**
-* Wrap a raw success payload as an MCP `CallToolResult`. Use when the
-* tool produced a value directly (action handler return, aggregation
-* rows, etc.) instead of an `IControllerResponse` envelope.
+* Wrap a raw success payload as an MCP `CallToolResult`. Use when the
+* tool produced a value directly (action handler return, aggregation
+* rows, etc.) instead of an `IControllerResponse` envelope.
+*
+* Emits the value as JSON with no envelope — same no-envelope contract
+* the HTTP wire follows. The `isError: true` flag on `CallToolResult`
+* is the success/error discriminant for MCP, mirroring HTTP status.
+*/
+function toCallToolSuccess(value) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(value)
+	}] };
+}
+/**
+* Wrap an error as an MCP `CallToolResult` with the canonical
+* `ErrorContract` shape inside the text payload. Single source of truth
+* for MCP error serialization — every tool surface (CRUD, action, route,
+* aggregation) routes through here so the JSON shape an agent sees is
+* identical to what an HTTP client sees.
+*
+* Accepts:
+*  - An `ArcError` (or any `HttpError`-shaped throw) → routes through
+*    `toErrorContract()` for the canonical conversion.
+*  - A partial contract `{code, message, status, details?}` → used as-is.
+*  - Any other `Error` → falls back to `arc.internal_error` 500.
+*/
+function toCallToolError(input) {
+	let contract;
+	if (input instanceof Error) if (isArcError(input) || isHttpError(input)) contract = toErrorContract(input);
+	else contract = {
+		code: "arc.internal_error",
+		message: input.message || "Internal Server Error",
+		status: 500
+	};
+	else contract = {
+		code: input.code,
+		message: input.message,
+		...input.status !== void 0 ? { status: input.status } : {},
+		...input.details ? { details: input.details } : {}
+	};
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(contract)
+		}],
+		isError: true
+	};
+}
+/**
+* Build the canonical permission-denied `CallToolResult` for an MCP
+* tool. Discriminates 401 (no session — "Authentication required") from
+* 403 (session present, denied — "Permission denied"). Mirrors the
+* status split the HTTP `errorHandler` plugin uses.
+*/
+function permissionDeniedResult(args) {
+	const authenticated = args.session != null;
+	return toCallToolError({
+		code: authenticated ? "arc.forbidden" : "arc.unauthorized",
+		message: args.reason ?? (authenticated ? `Permission denied for '${args.operation}' on '${args.resource}'` : "Authentication required"),
+		status: authenticated ? 403 : 401
+	});
+}
+/**
+* Auto-create a BaseController from the resource's adapter for MCP use.
+* Called when the resource has an adapter but no controller
+* (e.g. `disableDefaultRoutes: true` skips controller creation in
+* `defineResource`).
+*/
+function createMcpController(resource) {
+	const repository = resource.adapter?.repository;
+	if (!repository) return void 0;
+	return new BaseController(repository, {
+		resourceName: resource.name,
+		schemaOptions: resource.schemaOptions,
+		tenantField: resource.tenantField,
+		idField: resource.idField,
+		matchesFilter: resource.adapter?.matchesFilter
+	});
+}
+//#endregion
+//#region src/integrations/mcp/invokeController.ts
+/**
+* Invoke a controller method through the MCP synthetic-context path.
+*
+* Runs the same chain CRUD MCP tools run:
+*   1. {@link evaluatePermission} — fails with the canonical
+*      `arc.unauthorized` / `arc.forbidden` `CallToolResult` shape on denial.
+*   2. {@link buildRequestContext} — projects MCP input + session into
+*      `IRequestContext`. Permission `filters` / `scope` thread through
+*      identically to CRUD/action routes.
+*   3. `controller[methodName](ctx)` — dispatch. Errors are routed through
+*      `toCallToolError` so `ArcError` / `HttpError` throws land as the same
+*      `ErrorContract` shape an HTTP client would see.
+*
+* @example Run a controller op from a custom MCP tool.
+* ```ts
+* defineTool('promote_post', {
+*   description: 'Promote a draft to published',
+*   inputSchema: { id: z.string() },
+*   handler: (input, ctx) =>
+*     invokeController(postController, 'update', { ...input, status: 'published' }, {
+*       session: ctx.session,
+*       resourceName: 'post',
+*       permissions: requireRoles(['editor']),
+*     }),
+* });
+* ```
+*
+* Workflow / scheduled-job callers pass a synthetic `session` they
+* constructed from the job's owning identity — the shape is the same
+* `McpAuthResult` the HTTP MCP plugin produces, so the same permission
+* checks compose.
+*/
+async function invokeController(controller, op, input, options) {
+	const { session, resourceName, actionName = op, permissions, methodName = op } = options;
+	const ctrl = controller;
+	try {
+		const method = ctrl[methodName];
+		if (typeof method !== "function") return toCallToolError({
+			code: "arc.not_implemented",
+			message: `Method '${methodName}' not available on '${resourceName}' controller`,
+			status: 501
+		});
+		const permResult = await evaluatePermission(permissions, session, resourceName, actionName, input);
+		if (permResult && !permResult.granted) return permissionDeniedResult({
+			resource: resourceName,
+			operation: actionName,
+			reason: permResult.reason,
+			session
+		});
+		return toCallToolResult(await method(buildRequestContext(input, session, op, permResult?.filters, permResult?.scope)));
+	} catch (err) {
+		return toCallToolError(err instanceof Error ? err : new Error(String(err)));
+	}
+}
+/**
+* Wrap an async function as a {@link ToolDefinition} handler — handles the
+* try/catch → canonical-error translation in one place so MCP tools that
+* compose multiple internal calls don't reimplement the boilerplate.
+*
+* The wrapped function may return:
+*  - A `CallToolResult` — passed through unchanged (use this to short-circuit
+*    with `permissionDeniedResult` or a custom error shape).
+*  - An `IControllerResponse` envelope (`{ data, meta?, status?, headers? }`)
+*    — serialised via `toCallToolResult` so pagination meta etc. survive.
+*  - Any other value — serialised as JSON via `toCallToolSuccess` semantics.
+*
+* Errors raised inside the function are caught and routed through
+* `toCallToolError`, so `ArcError` / `HttpError` throws collapse to the
+* canonical `ErrorContract` shape MCP agents see for every other surface.
+*
+* @example Compose two controller calls in one tool.
+* ```ts
+* defineTool('archive_and_log', {
+*   description: '...',
+*   handler: mcpHandlerAdapter(async (input, ctx) => {
+*     await invokeController(postController, 'update', { ...input, archived: true }, opts);
+*     return invokeController(auditController, 'create', { event: 'archive', ...input }, opts);
+*   }),
+* });
+* ```
+*/
+function mcpHandlerAdapter(fn) {
+	return async (input, ctx) => {
+		try {
+			const out = await fn(input, ctx);
+			if (isCallToolResult(out)) return out;
+			if (isControllerResponse(out)) return toCallToolResult(out);
+			return { content: [{
+				type: "text",
+				text: JSON.stringify(out ?? null)
+			}] };
+		} catch (err) {
+			return toCallToolError(err instanceof Error ? err : new Error(String(err)));
+		}
+	};
+}
+function isCallToolResult(value) {
+	return typeof value === "object" && value !== null && Array.isArray(value.content);
+}
+function isControllerResponse(value) {
+	return typeof value === "object" && value !== null && "data" in value && !("content" in value);
+}
+//#endregion
+//#region src/integrations/mcp/crud-tools.ts
+const ALL_CRUD_OPS = [
+	"list",
+	"get",
+	"create",
+	"update",
+	"delete"
+];
+const CRUD_ANNOTATIONS = {
+	list: { readOnlyHint: true },
+	get: { readOnlyHint: true },
+	create: { destructiveHint: false },
+	update: {
+		destructiveHint: true,
+		idempotentHint: true
+	},
+	delete: {
+		destructiveHint: true,
+		idempotentHint: true
+	}
+};
+/**
+* Build a handler that dispatches to the controller method for `op` via
+* the shared {@link invokeController} pipeline. Permission check + context
+* build + envelope/error conversion all live in one place — this factory
+* only resolves the op-specific permission and threads it through.
+*/
+function createCrudHandler(op, controller, resourceName, permissions) {
+	const permission = permissions?.[op];
+	return (input, ctx) => invokeController(controller, op, input, {
+		session: ctx.session,
+		resourceName,
+		permissions: permission
+	});
+}
+/**
+* Default description for a CRUD tool. Enriches list descriptions with the
+* configured filter/sort metadata so MCP clients can see what's queryable
+* without reading the resource source.
+*
+* Exposed publicly so authors using the function-form `descriptions`
+* override can call this from their own override to keep the auto-derived
+* blurb intact and only append extra context.
+*/
+function defaultCrudDescription(op, displayName, softDelete, queryMeta) {
+	const singular = displayName.toLowerCase();
+	switch (op) {
+		case "list": {
+			const parts = [`List ${pluralize(singular)} with optional filters and pagination.`];
+			if (queryMeta?.filterableFields?.length) parts.push(`Filterable fields: ${queryMeta.filterableFields.join(", ")}.`);
+			if (queryMeta?.allowedOperators?.length) parts.push(`Filter operators: ${queryMeta.allowedOperators.join(", ")} (use field[op]=value syntax).`);
+			if (queryMeta?.sortableFields?.length) parts.push(`Sortable fields: ${queryMeta.sortableFields.join(", ")}.`);
+			return parts.join(" ");
+		}
+		case "get": return `Get a single ${singular} by ID`;
+		case "create": return `Create a new ${singular}`;
+		case "update": return `Update an existing ${singular} by ID`;
+		case "delete": return softDelete ? `Delete a ${singular} by ID (soft delete — marks as deleted, not permanently removed)` : `Delete a ${singular} by ID`;
+	}
+}
+/**
+* Resolve a {@link CrudDescriptionOverride} (string or function) into a
+* concrete description. Centralises the function-form contract so every
+* call site that consumes an override applies it the same way.
+*
+* Falls back to {@link defaultCrudDescription} when no override is set.
+*/
+function resolveCrudDescription(override, meta) {
+	if (override === void 0) return meta.defaultDescription;
+	if (typeof override === "string") return override;
+	return override(meta);
+}
+//#endregion
+//#region src/integrations/mcp/fieldRulesToZod.ts
+/**
+* @classytic/arc — fieldRules → Zod Shape Converter
+*
+* Converts Arc's schemaOptions.fieldRules into flat Zod shapes
+* compatible with the MCP SDK's registerTool() inputSchema format.
+*
+* Returns `Record<string, z.ZodTypeAny>` (flat shape), NOT z.object().
+* The SDK wraps it internally.
+*
+* @example
+* ```typescript
+* import { fieldRulesToZod } from '@classytic/arc/mcp';
+*
+* const shape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
+*   mode: 'create',
+*   hiddenFields: resource.schemaOptions.hiddenFields,
+* });
+* // shape = { name: z.string(), price: z.number() }
+* ```
+*/
+const PAGINATION_SHAPE = {
+	page: z.number().int().min(1).optional().describe("Page number (1-based)"),
+	limit: z.number().int().min(1).max(100).optional().describe("Items per page (max 100)"),
+	sort: z.string().optional().describe("Sort field, prefix with - for descending"),
+	search: z.string().optional().describe("Full-text search query"),
+	select: z.string().optional().describe("Comma-separated field list to project (e.g. 'name,price'). Prefix with '-' to exclude (e.g. '-description')."),
+	populate: z.string().optional().describe("Comma-separated relation paths to hydrate (e.g. 'supplier,category'). Follows Mongoose populate syntax when the adapter is MongoKit.")
+};
+/**
+* Convert Arc fieldRules to a flat Zod shape.
+*
+* @returns Flat shape `Record<string, z.ZodTypeAny>` — pass directly to defineTool() or registerTool()
+*/
+function fieldRulesToZod(fieldRules, options = {}) {
+	const { mode = "create", hiddenFields = [], readonlyFields = [], extraHideFields = [] } = options;
+	if (mode === "list") return buildListShape(fieldRules, options);
+	if (!fieldRules) return {};
+	const allHidden = new Set([...hiddenFields, ...extraHideFields]);
+	const allReadonly = new Set(readonlyFields);
+	const shape = {};
+	for (const [name, rule] of Object.entries(fieldRules)) {
+		if (rule.systemManaged || rule.hidden || allHidden.has(name)) continue;
+		if (allReadonly.has(name)) continue;
+		if (mode === "update" && rule.immutable) continue;
+		const field = buildFieldSchema(rule);
+		if (mode === "update") shape[name] = field.optional();
+		else shape[name] = rule.required === true && !rule.optional ? field : field.optional();
+	}
+	return shape;
+}
+/** Build Zod type for a single field rule */
+function buildFieldSchema(rule) {
+	if (rule.enum?.length) {
+		const schema = z.enum(rule.enum);
+		return rule.description ? schema.describe(rule.description) : schema;
+	}
+	const base = typeToZod(rule.type);
+	if (base instanceof z.ZodString) {
+		let s = base;
+		if (rule.minLength != null) s = s.min(rule.minLength);
+		if (rule.maxLength != null) s = s.max(rule.maxLength);
+		if (rule.pattern) try {
+			s = s.regex(new RegExp(rule.pattern));
+		} catch {}
+		return rule.description ? s.describe(rule.description) : s;
+	}
+	if (base instanceof z.ZodNumber) {
+		let n = base;
+		if (rule.min != null) n = n.min(rule.min);
+		if (rule.max != null) n = n.max(rule.max);
+		return rule.description ? n.describe(rule.description) : n;
+	}
+	return rule.description ? base.describe(rule.description) : base;
+}
+/** Map Arc field type string to base Zod type */
+function typeToZod(type) {
+	switch (type) {
+		case "string": return z.string();
+		case "number": return z.number();
+		case "boolean": return z.boolean();
+		case "date": return z.string().describe("ISO 8601 date string");
+		case "array": return z.array(z.any());
+		case "object": return z.record(z.string(), z.any());
+		default: return z.string();
+	}
+}
+/** Operators that apply to numeric/date fields */
+const COMPARISON_OPS = new Set([
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+]);
+/** Map operator to a human-readable description suffix */
+function opDescription(op, fieldName) {
+	switch (op) {
+		case "gt": return `${fieldName} greater than`;
+		case "gte": return `${fieldName} greater than or equal`;
+		case "lt": return `${fieldName} less than`;
+		case "lte": return `${fieldName} less than or equal`;
+		case "ne": return `${fieldName} not equal to`;
+		case "in": return `${fieldName} in comma-separated list`;
+		case "nin": return `${fieldName} not in comma-separated list`;
+		case "exists": return `${fieldName} exists (true/false)`;
+		default: return `${fieldName} ${op}`;
+	}
+}
+/** Build list/query shape with filterable fields, operators, and pagination */
+function buildListShape(fieldRules, options) {
+	const { filterableFields = [], hiddenFields = [], extraHideFields = [], allowedOperators } = options;
+	const allHidden = new Set([...hiddenFields, ...extraHideFields]);
+	const shape = { ...PAGINATION_SHAPE };
+	if (!fieldRules) return shape;
+	for (const name of filterableFields) {
+		if (allHidden.has(name)) continue;
+		const rule = fieldRules[name];
+		if (!rule) continue;
+		if (rule.hidden || rule.systemManaged) continue;
+		const filterField = buildFieldSchema(rule);
+		shape[name] = filterField.optional();
+		if (allowedOperators?.length) {
+			const isNumericOrDate = rule.type === "number" || rule.type === "date";
+			for (const op of allowedOperators) {
+				if (COMPARISON_OPS.has(op) && !isNumericOrDate) continue;
+				if (op === "eq") continue;
+				if (op === "exists") {
+					shape[`${name}_${op}`] = z.boolean().optional().describe(opDescription(op, name));
+					continue;
+				}
+				if (op === "in" || op === "nin") {
+					shape[`${name}_${op}`] = z.string().optional().describe(opDescription(op, name));
+					continue;
+				}
+				shape[`${name}_${op}`] = filterField.optional().describe(opDescription(op, name));
+			}
+		}
+	}
+	return shape;
+}
+//#endregion
+//#region src/integrations/mcp/authBridge.ts
+/**
+* @classytic/arc — MCP Auth Bridge
 *
-* Emits the value as JSON with no envelope — same no-envelope contract
-* the HTTP wire follows. The `isError: true` flag on `CallToolResult`
-* is the success/error discriminant for MCP, mirroring HTTP status.
+* Resolves MCP session identity from request headers.
+* Supports three modes — the user chooses:
+*
+* 1. `false` — no auth, anonymous access
+* 2. `BetterAuthHandler` — OAuth 2.1 via Better Auth
+* 3. `McpAuthResolver` — custom function (API key, JWT, gateway headers, etc.)
 */
-function toCallToolSuccess(value) {
-	return { content: [{
-		type: "text",
-		text: JSON.stringify(value)
-	}] };
+/** Distinguish BetterAuthHandler from McpAuthResolver */
+function isBetterAuth(auth) {
+	return typeof auth === "object" && auth !== null && "api" in auth && "handler" in auth;
 }
 /**
-* Wrap an error as an MCP `CallToolResult` with the canonical
-* `ErrorContract` shape inside the text payload. Single source of truth
-* for MCP error serialization — every tool surface (CRUD, action, route,
-* aggregation) routes through here so the JSON shape an agent sees is
-* identical to what an HTTP client sees.
+* Resolve MCP session identity from request headers.
 *
-* Accepts:
-*  - An `ArcError` (or any `HttpError`-shaped throw) → routes through
-*    `toErrorContract()` for the canonical conversion.
-*  - A partial contract `{code, message, status, details?}` → used as-is.
-*  - Any other `Error` → falls back to `arc.internal_error` 500.
+* @param headers - HTTP request headers
+* @param auth - false | BetterAuthHandler | McpAuthResolver
+* @param authCache - Optional short-lived cache to avoid redundant auth lookups
 */
-function toCallToolError(input) {
-	let contract;
-	if (input instanceof Error) if (isArcError(input) || isHttpError(input)) contract = toErrorContract(input);
-	else contract = {
-		code: "arc.internal_error",
-		message: input.message || "Internal Server Error",
-		status: 500
-	};
-	else contract = {
-		code: input.code,
-		message: input.message,
-		...input.status !== void 0 ? { status: input.status } : {},
-		...input.details ? { details: input.details } : {}
-	};
-	return {
-		content: [{
-			type: "text",
-			text: JSON.stringify(contract)
-		}],
-		isError: true
-	};
+async function resolveMcpAuth(headers, auth, authCache) {
+	if (auth === false) return null;
+	const cacheKey = authCache ? extractAuthCacheKey(headers) : null;
+	if (cacheKey && authCache) {
+		const cached = authCache.get(cacheKey);
+		if (cached !== void 0) return cached;
+	}
+	let result = null;
+	if (typeof auth === "function") try {
+		result = await auth(headers);
+	} catch {
+		result = null;
+	}
+	else if (isBetterAuth(auth)) try {
+		const session = await auth.api.getMcpSession({ headers });
+		if (!session?.userId) result = null;
+		else result = {
+			userId: session.userId,
+			organizationId: session.activeOrganizationId,
+			...session.clientId ? { clientId: session.clientId } : {},
+			...session.scopes ? { scopes: session.scopes.split(" ") } : {}
+		};
+	} catch {
+		result = null;
+	}
+	if (cacheKey && authCache) authCache.set(cacheKey, result);
+	return result;
 }
+const DEFAULT_AUTH_CACHE_TTL_MS = 5e3;
+const DEFAULT_AUTH_CACHE_MAX = 500;
+/** Short-lived auth cache to avoid redundant auth resolver calls in stateless mode */
+var McpAuthCache = class {
+	cache = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxEntries;
+	constructor(opts) {
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_AUTH_CACHE_TTL_MS;
+		this.maxEntries = opts?.maxEntries ?? DEFAULT_AUTH_CACHE_MAX;
+	}
+	get(key) {
+		const entry = this.cache.get(key);
+		if (!entry) return void 0;
+		if (Date.now() > entry.expires) {
+			this.cache.delete(key);
+			return;
+		}
+		return entry.result;
+	}
+	set(key, result) {
+		if (this.cache.size >= this.maxEntries) {
+			const now = Date.now();
+			for (const [k, v] of this.cache) if (now > v.expires) this.cache.delete(k);
+			if (this.cache.size >= this.maxEntries) {
+				const firstKey = this.cache.keys().next().value;
+				if (firstKey) this.cache.delete(firstKey);
+			}
+		}
+		this.cache.set(key, {
+			result,
+			expires: Date.now() + this.ttlMs
+		});
+	}
+};
 /**
-* Build the canonical permission-denied `CallToolResult` for an MCP
-* tool. Discriminates 401 (no session — "Authentication required") from
-* 403 (session present, denied — "Permission denied"). Mirrors the
-* status split the HTTP `errorHandler` plugin uses.
+* Extract a cache key from auth-related headers.
+* Uses SHA-256 hash of header values to prevent cache key collisions
+* and avoid storing raw credentials in memory.
 */
-function permissionDeniedResult(args) {
-	const authenticated = args.session != null;
-	return toCallToolError({
-		code: authenticated ? "arc.forbidden" : "arc.unauthorized",
-		message: args.reason ?? (authenticated ? `Permission denied for '${args.operation}' on '${args.resource}'` : "Authentication required"),
-		status: authenticated ? 403 : 401
-	});
+function extractAuthCacheKey(headers) {
+	if (headers.authorization) return `authz:${hashForCache(headers.authorization)}`;
+	if (headers["x-api-key"]) return `apikey:${hashForCache(headers["x-api-key"])}`;
+	return null;
+}
+function hashForCache(value) {
+	return createHash("sha256").update(value).digest("hex").slice(0, 32);
 }
 /**
-* Auto-create a BaseController from the resource's adapter for MCP use.
-* Called when the resource has an adapter but no controller
-* (e.g. `disableDefaultRoutes: true` skips controller creation in
-* `defineResource`).
+* Register OAuth 2.1 discovery endpoints for MCP clients.
+* Only relevant when using Better Auth — custom auth doesn't need these.
 */
-function createMcpController(resource) {
-	const repository = resource.adapter?.repository;
-	if (!repository) return void 0;
-	return new BaseController(repository, {
-		resourceName: resource.name,
-		schemaOptions: resource.schemaOptions,
-		tenantField: resource.tenantField,
-		idField: resource.idField,
-		matchesFilter: resource.adapter?.matchesFilter
+async function registerOAuthDiscovery(fastify, auth) {
+	fastify.get("/.well-known/oauth-authorization-server", async (req, reply) => {
+		await forwardResponse(reply, await auth.handler(toWebRequest(req)));
+	});
+	fastify.get("/.well-known/oauth-protected-resource", async (req, reply) => {
+		await forwardResponse(reply, await auth.handler(toWebRequest(req)));
+	});
+}
+function toWebRequest(req) {
+	const protocol = req.protocol ?? "http";
+	const host = req.hostname ?? "localhost";
+	return new Request(`${protocol}://${host}${req.url}`, {
+		method: req.method,
+		headers: req.headers
+	});
+}
+async function forwardResponse(reply, response) {
+	reply.status(response.status);
+	response.headers.forEach((value, key) => {
+		if (key.toLowerCase() !== "transfer-encoding") reply.header(key, value);
 	});
+	reply.send(await response.text());
 }
 //#endregion
 //#region src/integrations/mcp/action-tools.ts
@@ -538,9 +847,9 @@ function convertActionSchemaToZod(raw) {
 * in the 2.10.8 review: REST and MCP action tools share identical
 * context-building machinery.
 */
-function createActionToolHandler(actionName, handler, permissions, resourceName, _resourcePermissions, rawSchema) {
+function createActionToolHandler(actionName, handler, permissions, resourceName, _resourcePermissions, rawSchema, idLess = false) {
 	const ir = rawSchema ? normalizeSchemaIR(rawSchema) : void 0;
-	const allowedKeys = (ir ? shouldRejectAdditionalProperties(ir) : false) && ir ? new Set(["id", ...Object.keys(ir.properties)]) : void 0;
+	const allowedKeys = (ir ? shouldRejectAdditionalProperties(ir) : false) && ir ? new Set([...idLess ? [] : ["id"], ...Object.keys(ir.properties)]) : void 0;
 	return async (input, ctx) => {
 		const session = ctx.session;
 		if (allowedKeys) {
@@ -567,7 +876,7 @@ function createActionToolHandler(actionName, handler, permissions, resourceName,
 			...input,
 			action: actionName
 		}, session, "action", permResult?.filters, permResult?.scope);
-		const id = typeof input.id === "string" ? input.id : "";
+		const id = idLess ? "" : typeof input.id === "string" ? input.id : "";
 		const { id: _discardId, ...data } = input;
 		try {
 			return toCallToolSuccess(await handler(id, data, reqCtx));
@@ -675,88 +984,6 @@ function createAggregationToolHandler(args) {
 	};
 }
 //#endregion
-//#region src/integrations/mcp/crud-tools.ts
-const ALL_CRUD_OPS = [
-	"list",
-	"get",
-	"create",
-	"update",
-	"delete"
-];
-const CRUD_ANNOTATIONS = {
-	list: { readOnlyHint: true },
-	get: { readOnlyHint: true },
-	create: { destructiveHint: false },
-	update: {
-		destructiveHint: true,
-		idempotentHint: true
-	},
-	delete: {
-		destructiveHint: true,
-		idempotentHint: true
-	}
-};
-/**
-* Build a handler that dispatches to the controller method for `op`,
-* passing through arc's MCP → IRequestContext adapter. Permission check
-* runs first and short-circuits with a structured tool error on denial.
-*/
-function createCrudHandler(op, controller, resourceName, permissions) {
-	const ctrl = controller;
-	return async (input, ctx) => {
-		try {
-			const method = ctrl[op];
-			if (typeof method !== "function") return {
-				content: [{
-					type: "text",
-					text: `Operation "${op}" not available on ${resourceName}`
-				}],
-				isError: true
-			};
-			const permResult = await evaluatePermission(permissions?.[op], ctx.session, resourceName, op, input);
-			if (permResult && !permResult.granted) return {
-				content: [{
-					type: "text",
-					text: `Permission denied: ${op} on ${resourceName}${permResult.reason ? ` — ${permResult.reason}` : ""}`
-				}],
-				isError: true
-			};
-			return toCallToolResult(await method(buildRequestContext(input, ctx.session, op, permResult?.filters, permResult?.scope)));
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			ctx.log("error", `${resourceName}.${op}: ${msg}`).catch(() => {});
-			return {
-				content: [{
-					type: "text",
-					text: `Error: ${msg}`
-				}],
-				isError: true
-			};
-		}
-	};
-}
-/**
-* Default description for a CRUD tool. Enriches list descriptions with the
-* configured filter/sort metadata so MCP clients can see what's queryable
-* without reading the resource source.
-*/
-function defaultCrudDescription(op, displayName, softDelete, queryMeta) {
-	const name = displayName.toLowerCase();
-	switch (op) {
-		case "list": {
-			const parts = [`List ${pluralize(name)} with optional filters and pagination.`];
-			if (queryMeta?.filterableFields?.length) parts.push(`Filterable fields: ${queryMeta.filterableFields.join(", ")}.`);
-			if (queryMeta?.allowedOperators?.length) parts.push(`Filter operators: ${queryMeta.allowedOperators.join(", ")} (use field[op]=value syntax).`);
-			if (queryMeta?.sortableFields?.length) parts.push(`Sortable fields: ${queryMeta.sortableFields.join(", ")}.`);
-			return parts.join(" ");
-		}
-		case "get": return `Get a single ${name} by ID`;
-		case "create": return `Create a new ${name}`;
-		case "update": return `Update an existing ${name} by ID`;
-		case "delete": return softDelete ? `Delete a ${name} by ID (soft delete — marks as deleted, not permanently removed)` : `Delete a ${name} by ID`;
-	}
-}
-//#endregion
 //#region src/integrations/mcp/jsonSchemaToZod.ts
 /**
 * @classytic/arc — JSON Schema → Zod shape converter
@@ -1046,6 +1273,32 @@ function mapJsonSchemaTypeToArcType(jsonType) {
 * 3. String handler — looks up a method on the controller by name.
 */
 /**
+* Pick the IRequestContext shape MCP should produce when invoking a
+* custom route's handler. Mirrors the HTTP semantics of the route:
+*
+* | HTTP                           | MCP kind  | params  | body  | query |
+* |--------------------------------|-----------|---------|-------|-------|
+* | `GET /thing` (no :id)          | `list`    | -       | -     | input |
+* | `GET /thing/:id`               | `get`     | { id }  | -     | input |
+* | `POST /thing` (no :id)         | `create`  | -       | input | -     |
+* | `PUT|PATCH /thing/:id`         | `update`  | { id }  | rest  | -     |
+* | `DELETE /thing/:id`            | `delete`  | { id }  | -     | -     |
+* | `POST /thing/:id` (any other)  | `update`  | { id }  | rest  | -     |
+*
+* Pre-2.15.5 every custom route used `update`/`create` regardless of method.
+* That broke GET-route bridging the moment a handler read `ctx.query` — MCP
+* stuffed the input into `ctx.body` instead and the handler returned empty.
+* The `kind` mapping below is the single source of truth that keeps HTTP
+* and MCP invocations producing the same `IRequestContext` shape.
+*/
+function operationKindForRoute(method, hasId) {
+	const upper = method.toUpperCase();
+	if (upper === "GET") return hasId ? "get" : "list";
+	if (upper === "DELETE") return "delete";
+	if (hasId) return "update";
+	return "create";
+}
+/**
 * Build an MCP tool handler for a custom route.
 *
 * Enforces the same contract as the REST route:
@@ -1075,7 +1328,7 @@ function createCustomRouteHandler(route, controller, hasId, options) {
 			session
 		});
 		try {
-			const reqCtx = buildRequestContext(input, session, hasId ? "update" : "create", permResult?.filters, permResult?.scope);
+			const reqCtx = buildRequestContext(input, session, operationKindForRoute(route.method, hasId), permResult?.filters, permResult?.scope);
 			if (typeof route.handler === "function") {
 				const fn = route.handler;
 				if (pipelineSteps.length > 0) return toCallToolResult(await executePipeline(pipelineSteps, {
@@ -1195,9 +1448,18 @@ function resourceToTools(resource, config = {}) {
 		if (config.operations) ops = ops.filter((op) => config.operations?.includes(op));
 		for (const op of ops) {
 			const name = config.names?.[op] ?? (op === "list" ? `${prefix ? `${prefix}_` : ""}list_${pluralize(resource.name)}` : `${prefix ? `${prefix}_` : ""}${op}_${resource.name}`);
+			const defaultDescription = defaultCrudDescription(op, resource.displayName, hasSoftDelete, {
+				filterableFields,
+				allowedOperators,
+				sortableFields
+			});
 			tools.push({
 				name,
-				description: config.descriptions?.[op] ?? defaultCrudDescription(op, resource.displayName, hasSoftDelete, {
+				description: resolveCrudDescription(config.descriptions?.[op], {
+					operation: op,
+					displayName: resource.displayName,
+					softDelete: hasSoftDelete,
+					defaultDescription,
 					filterableFields,
 					allowedOperators,
 					sortableFields
@@ -1219,13 +1481,16 @@ function resourceToTools(resource, config = {}) {
 		if (route.mcp === false) continue;
 		const mcpHandler = route.mcpHandler;
 		if (!!route.raw && !mcpHandler) continue;
-		if (!mcpHandler && ![
-			"POST",
-			"PUT",
-			"PATCH",
-			"DELETE"
-		].includes(route.method)) continue;
 		if (!mcpHandler && typeof route.handler === "string" && !controller) continue;
+		const routeWithRef = route;
+		let resolvedRouteHandler = route.handler;
+		if (typeof routeWithRef.controllerMethod === "function" && !resolvedRouteHandler) {
+			if (!controller) continue;
+			const referenced = routeWithRef.controllerMethod(controller);
+			if (typeof referenced !== "function") continue;
+			resolvedRouteHandler = referenced.bind(controller);
+		}
+		if (!resolvedRouteHandler) continue;
 		const opName = route.operation ?? slugifyRoute(route.method, route.path);
 		const hasId = route.path.includes(":id");
 		const mcpConfig = typeof route.mcp === "object" && route.mcp !== null ? route.mcp : void 0;
@@ -1248,7 +1513,12 @@ function resourceToTools(resource, config = {}) {
 			description: toolDescription,
 			annotations: toolAnnotations,
 			inputSchema: inputShape,
-			handler: mcpHandler ? createMcpHandlerPassthrough(mcpHandler) : createCustomRouteHandler(route, controller, hasId, {
+			handler: mcpHandler ? createMcpHandlerPassthrough(mcpHandler) : createCustomRouteHandler({
+				handler: resolvedRouteHandler,
+				operation: route.operation,
+				method: route.method,
+				path: route.path
+			}, controller, hasId, {
 				resourceName: resource.name,
 				operationName: opName,
 				permissions: route.permissions,
@@ -1262,7 +1532,8 @@ function resourceToTools(resource, config = {}) {
 		const mcpCfg = typeof def !== "function" && typeof def.mcp === "object" ? def.mcp : void 0;
 		const description = mcpCfg?.description ?? (typeof def !== "function" ? def.description : void 0) ?? `${actionName} action on ${resource.displayName}`;
 		const annotations = mcpCfg?.annotations ? { ...mcpCfg.annotations } : { destructiveHint: true };
-		const inputShape = { id: z.string().describe("Resource ID") };
+		const idLess = typeof def !== "function" && def.id === false;
+		const inputShape = idLess ? {} : { id: z.string().describe("Resource ID") };
 		const rawSchema = typeof def !== "function" ? def.schema : void 0;
 		if (rawSchema && typeof rawSchema === "object") {
 			const converted = convertActionSchemaToZod(rawSchema);
@@ -1281,7 +1552,7 @@ function resourceToTools(resource, config = {}) {
 			description: String(description),
 			annotations,
 			inputSchema: inputShape,
-			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema)
+			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema, idLess)
 		});
 	}
 	if (resource.aggregations && Object.keys(resource.aggregations).length > 0) {
@@ -1310,4 +1581,436 @@ function resourceToTools(resource, config = {}) {
 	return tools;
 }
 //#endregion
-export { fieldRulesToZod as n, createMcpServer as r, resourceToTools as t };
+//#region src/integrations/mcp/schemaResources.ts
+/**
+* Register MCP Resources for schema discovery.
+*/
+function registerSchemaResources(server, resources, overrides) {
+	const srv = server;
+	srv.resource("schemas", "arc://schemas", {
+		title: "Arc Resource Schemas",
+		description: "All available resources",
+		mimeType: "application/json"
+	}, async () => ({ contents: [{
+		uri: "arc://schemas",
+		mimeType: "application/json",
+		text: JSON.stringify(resources.map((r) => ({
+			name: r.name,
+			displayName: r.displayName,
+			fieldCount: r.schemaOptions?.fieldRules ? Object.keys(r.schemaOptions.fieldRules).length : 0,
+			operations: getOps(r, overrides?.[r.name]?.operations),
+			presets: r._appliedPresets ?? []
+		})), null, 2)
+	}] }));
+	for (const r of resources) {
+		const uri = `arc://schemas/${r.name}`;
+		const schemaOpts = r.schemaOptions;
+		srv.resource(`schema-${r.name}`, uri, {
+			title: `${r.displayName} Schema`,
+			description: `Schema for ${r.displayName}`,
+			mimeType: "application/json"
+		}, async () => ({ contents: [{
+			uri,
+			mimeType: "application/json",
+			text: JSON.stringify({
+				name: r.name,
+				displayName: r.displayName,
+				operations: getOps(r, overrides?.[r.name]?.operations),
+				fields: r.schemaOptions?.fieldRules ?? {},
+				filterableFields: schemaOpts?.filterableFields ?? [],
+				presets: r._appliedPresets ?? []
+			}, null, 2)
+		}] }));
+	}
+}
+function getOps(r, override) {
+	let ops = [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete"
+	].filter((op) => !r.disabledRoutes?.includes(op));
+	if (override) ops = ops.filter((op) => override.includes(op));
+	return ops;
+}
+//#endregion
+//#region src/integrations/mcp/sessionCache.ts
+const DEFAULT_TTL_MS = 1800 * 1e3;
+const DEFAULT_MAX_SESSIONS = 1e3;
+var McpSessionCache = class {
+	sessions = /* @__PURE__ */ new Map();
+	ttlMs;
+	maxSessions;
+	cleanupTimer = null;
+	constructor(opts = {}) {
+		this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+		this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+		if (this.ttlMs > 0) {
+			this.cleanupTimer = setInterval(() => this.cleanup(), Math.max(this.ttlMs / 2, 5e3));
+			if (this.cleanupTimer.unref) this.cleanupTimer.unref();
+		}
+	}
+	/** Get an existing session by ID */
+	get(sessionId) {
+		const entry = this.sessions.get(sessionId);
+		if (!entry) return void 0;
+		if (Date.now() - entry.lastAccessed > this.ttlMs) {
+			this.remove(sessionId);
+			return;
+		}
+		return entry;
+	}
+	/** Store a new session */
+	set(sessionId, entry) {
+		if (this.sessions.size >= this.maxSessions && !this.sessions.has(sessionId)) this.evictOldest();
+		entry.lastAccessed = Date.now();
+		this.sessions.set(sessionId, entry);
+	}
+	/** Refresh the TTL on a session */
+	touch(sessionId) {
+		const entry = this.sessions.get(sessionId);
+		if (entry) entry.lastAccessed = Date.now();
+	}
+	/** Remove and close a session */
+	remove(sessionId) {
+		const entry = this.sessions.get(sessionId);
+		if (entry) {
+			this.closeTransport(entry);
+			this.sessions.delete(sessionId);
+		}
+	}
+	/** Remove all expired sessions */
+	cleanup() {
+		const now = Date.now();
+		for (const [id, entry] of this.sessions) if (now - entry.lastAccessed > this.ttlMs) {
+			this.closeTransport(entry);
+			this.sessions.delete(id);
+		}
+	}
+	/** Close all sessions and stop cleanup timer */
+	close() {
+		if (this.cleanupTimer) {
+			clearInterval(this.cleanupTimer);
+			this.cleanupTimer = null;
+		}
+		for (const [id, entry] of this.sessions) {
+			this.closeTransport(entry);
+			this.sessions.delete(id);
+		}
+	}
+	/** Current session count */
+	get size() {
+		return this.sessions.size;
+	}
+	/** Evict the oldest (least recently accessed) session */
+	evictOldest() {
+		let oldestId = null;
+		let oldestTime = Infinity;
+		for (const [id, entry] of this.sessions) if (entry.lastAccessed < oldestTime) {
+			oldestTime = entry.lastAccessed;
+			oldestId = id;
+		}
+		if (oldestId) this.remove(oldestId);
+	}
+	/** Safely close a transport */
+	closeTransport(entry) {
+		try {
+			const transport = entry.transport;
+			if (transport && typeof transport.close === "function") transport.close();
+		} catch {}
+	}
+};
+//#endregion
+//#region src/integrations/mcp/mcpPlugin.ts
+/**
+* @classytic/arc — MCP Plugin (Level 1)
+*
+* Fastify plugin that auto-generates MCP tools from Arc resources.
+*
+* Two transport modes:
+* - **Stateless** (default) — fresh server per request, no session tracking.
+*   Best for production, horizontal scaling, serverless, edge.
+* - **Stateful** — sessions cached with TTL, reused across requests.
+*   Use when you need server-initiated notifications or long-lived connections.
+*
+* Auth is NOT enforced — the plugin respects whatever auth mode you choose:
+* - `auth: false` — no auth, anonymous access (dev/testing/stdio)
+* - `auth: betterAuthInstance` — OAuth 2.1 via Better Auth's mcp() plugin
+* - `auth: async (headers) => {...}` — custom function (API key, JWT, gateway, etc.)
+*
+* @example
+* ```typescript
+* // Stateless (default) — production, scalable
+* await app.register(mcpPlugin, { resources, auth: false });
+*
+* // Stateful — when you need session persistence
+* await app.register(mcpPlugin, { resources, stateful: true, sessionTtlMs: 600000 });
+*
+* // Multiple MCP endpoints scoped to different resource groups
+* await app.register(mcpPlugin, { resources: catalogResources, prefix: '/mcp/catalog' });
+* await app.register(mcpPlugin, { resources: orderResources, prefix: '/mcp/orders' });
+* ```
+*/
+const mcpPluginImpl = async (fastify, options) => {
+	let StreamableHTTPServerTransport;
+	try {
+		StreamableHTTPServerTransport = (await import("@modelcontextprotocol/sdk/server/streamableHttp.js")).StreamableHTTPServerTransport;
+	} catch {
+		throw new Error("@modelcontextprotocol/sdk is required for MCP support. Install it: npm install @modelcontextprotocol/sdk");
+	}
+	try {
+		await import("zod");
+	} catch {
+		throw new Error("zod is required for MCP tool schemas. Install it: npm install zod");
+	}
+	const enabledResources = filterResourcesForMcp(options.resources, {
+		expose: options.expose,
+		include: options.include,
+		exclude: options.exclude
+	});
+	const overrides = options.overrides ?? {};
+	const allTools = enabledResources.flatMap((r) => {
+		const resOverrides = overrides[r.name] ?? {};
+		return resourceToTools(r, {
+			...resOverrides,
+			toolNamePrefix: resOverrides.toolNamePrefix ?? options.toolNamePrefix
+		});
+	});
+	if (options.extraTools) allTools.push(...options.extraTools);
+	fastify.log.info(`mcpPlugin: ${allTools.length} tools from ${enabledResources.length} resources`);
+	const overrideOpsMap = {};
+	for (const [name, cfg] of Object.entries(overrides)) overrideOpsMap[name] = { operations: cfg.operations };
+	const stateful = options.stateful === true;
+	const cache = stateful ? new McpSessionCache({
+		ttlMs: options.sessionTtlMs,
+		maxSessions: options.maxSessions
+	}) : null;
+	async function createServerInstance(authRef) {
+		const server = await createMcpServer({
+			name: options.serverName ?? "arc-mcp",
+			version: options.serverVersion ?? "1.0.0",
+			instructions: options.instructions,
+			tools: allTools,
+			prompts: options.extraPrompts
+		}, authRef);
+		registerSchemaResources(server, enabledResources, overrideOpsMap);
+		return server;
+	}
+	if (options.auth && isBetterAuth(options.auth)) await registerOAuthDiscovery(fastify, options.auth);
+	const prefix = options.prefix ?? "/mcp";
+	fastify.get(`${prefix}/health`, async (_request, reply) => {
+		reply.send({
+			status: "ok",
+			mode: stateful ? "stateful" : "stateless",
+			tools: allTools.length,
+			resources: enabledResources.length,
+			toolNames: allTools.map((t) => t.name),
+			sessions: cache?.size ?? null
+		});
+	});
+	if (stateful) {
+		if (!cache) throw new Error("[Arc/MCP] Stateful session cache missing in stateful registration");
+		registerStatefulRoutes(fastify, prefix, options, cache, createServerInstance, StreamableHTTPServerTransport);
+	} else {
+		const authCache = options.auth && options.authCacheTtlMs !== 0 ? new McpAuthCache({ ttlMs: options.authCacheTtlMs }) : void 0;
+		registerStatelessRoutes(fastify, prefix, options, createServerInstance, StreamableHTTPServerTransport, authCache);
+	}
+	if (cache) fastify.addHook("onClose", async () => cache.close());
+	const registration = {
+		sessions: cache,
+		toolNames: allTools.map((t) => t.name),
+		resourceNames: enabledResources.map((r) => r.name),
+		stateful
+	};
+	if (!fastify.hasDecorator("mcp")) {
+		const registrations = /* @__PURE__ */ new Map();
+		registrations.set(prefix, registration);
+		const first = () => registrations.values().next().value;
+		const decorator = {
+			registrations,
+			get(p) {
+				return registrations.get(p);
+			},
+			get sessions() {
+				return first()?.sessions ?? null;
+			},
+			get toolNames() {
+				return first()?.toolNames ?? [];
+			},
+			get resourceNames() {
+				return first()?.resourceNames ?? [];
+			},
+			get stateful() {
+				return first()?.stateful ?? false;
+			}
+		};
+		fastify.decorate("mcp", decorator);
+	} else {
+		const existing = fastify.mcp;
+		if (existing) {
+			if (existing.registrations.has(prefix)) throw new Error(`mcpPlugin: prefix "${prefix}" is already registered`);
+			existing.registrations.set(prefix, registration);
+		}
+	}
+};
+function registerStatelessRoutes(fastify, prefix, options, createServer, Transport, authCache) {
+	fastify.post(prefix, async (request, reply) => {
+		const authResult = await resolveMcpAuth(request.headers, options.auth ?? false, authCache);
+		if (!authResult && options.auth) {
+			fastify.log.warn({
+				msg: "mcpPlugin: auth failed",
+				status: 401
+			});
+			return reply.code(401).send({
+				jsonrpc: "2.0",
+				error: {
+					code: -32e3,
+					message: "Unauthorized"
+				}
+			});
+		}
+		const authRef = { current: authResult };
+		const transport = new Transport({ sessionIdGenerator: void 0 });
+		await (await createServer(authRef)).connect(transport);
+		await transport.handleRequest(request.raw, reply.raw, request.body);
+	});
+	fastify.get(prefix, async (_request, reply) => {
+		reply.code(405).send({
+			jsonrpc: "2.0",
+			error: {
+				code: -32e3,
+				message: "SSE not available in stateless mode. Use stateful: true for server-initiated messages."
+			}
+		});
+	});
+	fastify.delete(prefix, async (_request, reply) => {
+		reply.code(200).send();
+	});
+}
+function registerStatefulRoutes(fastify, prefix, options, cache, createServer, Transport) {
+	/** Check if the requesting principal owns the session */
+	function isSessionOwner(entry, authResult) {
+		if (!options.auth || !entry.auth || !authResult) return true;
+		const prev = entry.auth;
+		return prev.userId === authResult.userId && prev.organizationId === authResult.organizationId && prev.clientId === authResult.clientId;
+	}
+	fastify.post(prefix, async (request, reply) => {
+		const authResult = await resolveMcpAuth(request.headers, options.auth ?? false);
+		if (!authResult && options.auth) {
+			fastify.log.warn({
+				msg: "mcpPlugin: auth failed",
+				status: 401
+			});
+			return reply.code(401).send({
+				jsonrpc: "2.0",
+				error: {
+					code: -32e3,
+					message: "Unauthorized"
+				}
+			});
+		}
+		const sessionId = request.headers["mcp-session-id"];
+		if (sessionId) {
+			const entry = cache.get(sessionId);
+			if (entry) {
+				if (!isSessionOwner(entry, authResult)) return reply.code(403).send({
+					jsonrpc: "2.0",
+					error: {
+						code: -32e3,
+						message: "Session ownership mismatch"
+					}
+				});
+				cache.touch(sessionId);
+				entry.auth = authResult;
+				entry.authRef.current = authResult;
+				await entry.transport.handleRequest(request.raw, reply.raw, request.body);
+				return;
+			}
+		}
+		const authRef = { current: authResult };
+		const transport = new Transport({
+			sessionIdGenerator: () => randomUUID(),
+			onsessioninitialized: (newSessionId) => {
+				cache.set(newSessionId, {
+					transport,
+					lastAccessed: Date.now(),
+					organizationId: authResult?.organizationId ?? "",
+					auth: authResult,
+					authRef
+				});
+			}
+		});
+		await (await createServer(authRef)).connect(transport);
+		await transport.handleRequest(request.raw, reply.raw, request.body);
+	});
+	fastify.get(prefix, async (request, reply) => {
+		const sessionId = request.headers["mcp-session-id"];
+		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
+		const entry = cache.get(sessionId);
+		if (!entry) return reply.code(403).send({ error: "Unauthorized" });
+		if (options.auth) {
+			const authResult = await resolveMcpAuth(request.headers, options.auth);
+			if (!isSessionOwner(entry, authResult)) return reply.code(403).send({ error: "Unauthorized" });
+			entry.auth = authResult;
+			entry.authRef.current = authResult;
+		}
+		cache.touch(sessionId);
+		await entry.transport.handleRequest(request.raw, reply.raw);
+	});
+	fastify.delete(prefix, async (request, reply) => {
+		const sessionId = request.headers["mcp-session-id"];
+		if (!sessionId) return reply.code(400).send({ error: "Missing Mcp-Session-Id header" });
+		const entry = cache.get(sessionId);
+		if (!entry) return reply.code(204).send();
+		if (options.auth) {
+			const authResult = await resolveMcpAuth(request.headers, options.auth);
+			if (!isSessionOwner(entry, authResult)) return reply.code(403).send({ error: "Unauthorized" });
+			entry.auth = authResult;
+			entry.authRef.current = authResult;
+		}
+		cache.remove(sessionId);
+		reply.code(204).send();
+	});
+}
+/**
+* Resolve `expose` / `include` / `exclude` into the filtered resource list
+* `mcpPlugin` should surface. Three mutually exclusive intents:
+*
+*  - `expose`: default-deny allowlist (preferred — new resources auto-deny).
+*  - `include`: legacy alias for `expose`, kept for back-compat.
+*  - `exclude`: default-allow opt-out (drift-prone — new resources auto-leak).
+*
+* Conflicting combinations throw with an actionable message so a host that
+* accidentally mixed paradigms fails at boot instead of silently leaking or
+* starving the LLM surface.
+*
+* **Local opt-out wins.** Any resource declared with
+* `defineResource({ mcp: false })` is dropped FIRST, before any of the
+* plugin-level allowlists/blocklists run. The opt-out is colocated with
+* the resource definition, so adding a new "never-expose" resource is
+* a single-file change instead of a host-wide blocklist update that
+* drifts as the codebase grows.
+*
+* Exported so `mcp/testing.ts` and external test harnesses can apply the
+* same precedence rules without duplicating them.
+*/
+function filterResourcesForMcp(resources, inputs) {
+	const { expose, include, exclude } = inputs;
+	if (expose && include) throw new Error("mcpPlugin: pass either `expose` (preferred) or `include` (legacy alias), not both.");
+	if (expose && exclude) throw new Error("mcpPlugin: `expose` is default-deny — `exclude` is redundant. Drop `exclude` or switch to `include`/`exclude` for default-allow semantics.");
+	const eligible = resources.filter((r) => r.mcp !== false);
+	const allow = expose ?? include;
+	if (allow) {
+		const allowSet = new Set(allow);
+		return eligible.filter((r) => allowSet.has(r.name));
+	}
+	const excludeSet = new Set(exclude ?? []);
+	return eligible.filter((r) => !excludeSet.has(r.name));
+}
+const mcpPlugin = fp(mcpPluginImpl, {
+	name: "arc-mcp",
+	fastify: "5.x"
+});
+//#endregion
+export { defaultCrudDescription as a, mcpHandlerAdapter as c, toCallToolResult as d, toCallToolSuccess as f, fieldRulesToZod as i, permissionDeniedResult as l, createMcpServer as m, mcpPlugin as n, resolveCrudDescription as o, buildRequestContext as p, resourceToTools as r, invokeController as s, filterResourcesForMcp as t, toCallToolError as u };