@classytic/arc 2.16.1 → 2.17.0

package/dist/integrations/jobs.mjs

@@ -16,6 +16,30 @@ import fp from "fastify-plugin";
 function defineJob(definition) {
 	return definition;
 }
+var Semaphore = class {
+	available;
+	waiters = [];
+	constructor(permits) {
+		this.available = permits;
+	}
+	get isFull() {
+		return this.available === 0;
+	}
+	acquire() {
+		if (this.available > 0) {
+			this.available--;
+			return Promise.resolve();
+		}
+		return new Promise((resolve) => {
+			this.waiters.push(resolve);
+		});
+	}
+	release() {
+		const next = this.waiters.shift();
+		if (next) next();
+		else this.available++;
+	}
+};
 const jobsPluginImpl = async (fastify, options) => {
 	const { connection, jobs, prefix = "/jobs", bridgeEvents = true, defaults = {} } = options;
 	let Queue;
@@ -33,6 +57,7 @@ const jobsPluginImpl = async (fastify, options) => {
 	const queues = /* @__PURE__ */ new Map();
 	const dlqQueues = /* @__PURE__ */ new Map();
 	const workers = /* @__PURE__ */ new Map();
+	const throttledJobs = /* @__PURE__ */ new Map();
 	for (const job of jobs) {
 		if (!job.repeat) continue;
 		const { pattern, every, tz } = job.repeat;
@@ -66,24 +91,39 @@ const jobsPluginImpl = async (fastify, options) => {
 			dlqQueues.set(dlqName, dlqQueue);
 		}
 		const jobTimeout = job.timeout ?? defaults.timeout;
+		const semaphore = job.maxConcurrent != null ? new Semaphore(job.maxConcurrent) : null;
+		const throttledSet = /* @__PURE__ */ new Set();
+		throttledJobs.set(queueName, throttledSet);
 		const worker = new Worker(queueName, async (bullJob) => {
 			const meta = {
 				jobId: bullJob.id ?? "",
 				attemptsMade: bullJob.attemptsMade ?? 0,
 				timestamp: Date.now()
 			};
-			let result;
-			if (jobTimeout) {
-				let timer;
-				const timeoutPromise = new Promise((_, reject) => {
-					timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Job '${queueName}' timed out after ${jobTimeout}ms`)), jobTimeout);
-				});
+			if (semaphore) {
+				if (semaphore.isFull) throttledSet.add(bullJob.id ?? "");
 				try {
-					result = await Promise.race([job.handler(bullJob.data, meta), timeoutPromise]);
+					await semaphore.acquire();
 				} finally {
-					clearTimeout(timer);
+					throttledSet.delete(bullJob.id ?? "");
 				}
-			} else result = await job.handler(bullJob.data, meta);
+			}
+			let result;
+			try {
+				if (jobTimeout) {
+					let timer;
+					const timeoutPromise = new Promise((_, reject) => {
+						timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`Job '${queueName}' timed out after ${jobTimeout}ms`)), jobTimeout);
+					});
+					try {
+						result = await Promise.race([job.handler(bullJob.data, meta), timeoutPromise]);
+					} finally {
+						clearTimeout(timer);
+					}
+				} else result = await job.handler(bullJob.data, meta);
+			} finally {
+				semaphore?.release();
+			}
 			if (bridgeEvents && fastify.events?.publish) try {
 				await fastify.events.publish(`job.${queueName}.completed`, {
 					jobId: bullJob.id,
@@ -197,6 +237,27 @@ const jobsPluginImpl = async (fastify, options) => {
 			}
 			return stats;
 		},
+		async getStatus(jobId) {
+			for (const [name, queue] of queues) {
+				const job = await queue.getJob(jobId);
+				if (!job) continue;
+				const state = typeof job.getState === "function" ? await job.getState() : "unknown";
+				const throttled = throttledJobs.get(name)?.has(jobId) || void 0;
+				return {
+					id: jobId,
+					name,
+					state,
+					progress: job.progress ?? 0,
+					throttled: throttled === true ? true : void 0,
+					timestamp: job.timestamp ?? void 0,
+					processedOn: job.processedOn ?? void 0,
+					finishedOn: job.finishedOn ?? void 0,
+					failedReason: job.failedReason ?? void 0,
+					returnValue: job.returnvalue ?? void 0
+				};
+			}
+			return null;
+		},
 		async close() {
 			await Promise.all(Array.from(workers.values()).map((w) => w.pause().catch(() => {})));
 			const closePromises = [];
@@ -213,6 +274,18 @@ const jobsPluginImpl = async (fastify, options) => {
 			data: await dispatcher.getStats()
 		};
 	});
+	fastify.get(`${prefix}/:id/status`, async (req, reply) => {
+		const { id } = req.params;
+		const status = await dispatcher.getStatus(id);
+		if (!status) return reply.status(404).send({
+			success: false,
+			error: "Job not found"
+		});
+		return {
+			success: true,
+			data: status
+		};
+	});
 	fastify.addHook("onClose", async () => {
 		await dispatcher.close();
 	});

package/dist/integrations/mcp/index.d.mts

@@ -1,7 +1,7 @@
-import { V as ResourceDefinition, bt as IRequestContext, yt as IControllerResponse } from "../../index-DBDgy6Hw.mjs";
+import { V as ResourceDefinition, bt as IRequestContext, yt as IControllerResponse } from "../../index-C1JSBan-.mjs";
 import { i as RequestScope } from "../../types-CfapW2t8.mjs";
 import { c as PermissionCheck } from "../../fields-DqZLp5d6.mjs";
-import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-BD0BCdf6.mjs";
+import { a as CrudDescriptionOverride, c as McpAuthResult, d as PromptDefinition, f as PromptResult, g as ToolDefinition, h as ToolContext, i as CrudDescriptionMeta, l as McpPluginOptions, m as ToolAnnotations, n as CallToolResult, o as CrudOperation, p as SessionEntry, r as CreateMcpServerConfig, s as McpAuthResolver, t as BetterAuthHandler, u as McpResourceConfig } from "../../types-CoMjNmkF.mjs";
 import { ErrorContract } from "@classytic/repo-core/errors";
 import { FastifyPluginAsync } from "fastify";
 import { z } from "zod";
@@ -54,6 +54,47 @@ interface BuildMcpToolsFromBridgesOptions {
  */
 declare function buildMcpToolsFromBridges(bridges: readonly McpBridge[], options?: BuildMcpToolsFromBridgesOptions): ToolDefinition[];
 //#endregion
+//#region src/integrations/mcp/betterAuthApiKey.d.ts
+/** Minimal subset of Better Auth's API-key record the helper needs. */
+interface BetterAuthKeyRecord {
+  id?: string;
+  userId?: string;
+  referenceId?: string;
+  metadata?: unknown;
+  permissions?: unknown;
+  scopes?: unknown;
+  expiresAt?: string | Date | null;
+  disabled?: boolean;
+  name?: string | null;
+}
+interface CreateMcpAuthFromBetterAuthApiKeyOptions {
+  /**
+   * How to resolve the organization id from a verified key.
+   *
+   * - `true` (default) — read `key.metadata.organizationId`.
+   * - `false` — never set `organizationId` (single-tenant deployments).
+   * - `(metadata, key) => string | undefined` — custom extractor, e.g.
+   *   `(m) => m?.tenantId` for hosts that named the column differently.
+   */
+  orgFromMetadata?: boolean | ((metadata: unknown, key: BetterAuthKeyRecord) => string | undefined);
+  /**
+   * Field name on `metadata` that holds the org id. Default
+   * `"organizationId"`. Ignored when `orgFromMetadata` is a function.
+   */
+  metadataOrgField?: string;
+  /**
+   * Permission scope name inside `key.permissions` that should be flattened
+   * onto `McpAuthResult.scopes`. Default `"mcp"` — matches Better Auth's
+   * docs example. Set to `false` to keep scopes empty.
+   */
+  permissionScope?: string | false;
+}
+/**
+ * Build an {@link McpAuthResolver} that authenticates MCP requests against
+ * Better Auth's API-key plugin. See module docstring for the rationale.
+ */
+declare function createMcpAuthFromBetterAuthApiKey(auth: BetterAuthHandler, options?: CreateMcpAuthFromBetterAuthApiKeyOptions): McpAuthResolver;
+//#endregion
 //#region src/integrations/mcp/createMcpServer.d.ts
 /**
  * Mutable auth ref — updated per-request by mcpPlugin.
@@ -69,6 +110,27 @@ interface AuthRef {
  * @returns McpServer instance (not yet connected to a transport)
  */
 declare function createMcpServer(config: CreateMcpServerConfig, authRef?: AuthRef): Promise<McpServerInstance>;
+/**
+ * Detect and resolve duplicate MCP tool names across the assembled tool list.
+ *
+ * Two outcomes:
+ *
+ *  1. **Auto-namespace** — when one tool's `source` carries a `preset:<name>`
+ *     prefix and the other doesn't, the preset tool is renamed to
+ *     `<presetName>_<originalName>` (e.g. softDelete's `restore_post`
+ *     becomes `softdelete_restore_post` when the user defines
+ *     `actions.restore`). The user's tool wins the canonical name because
+ *     it's the more-specific intent.
+ *
+ *  2. **Typed throw** — every other collision (two user actions, two
+ *     custom routes, two presets) raises `ArcError('arc.mcp.tool_name_collision')`
+ *     naming both sources so the host's stack trace points at the
+ *     resource definitions, not the MCP SDK internals.
+ *
+ * Exported for the testing harness so collision behaviour can be exercised
+ * without a full server boot.
+ */
+declare function resolveToolCollisions(tools: readonly ToolDefinition[]): ToolDefinition[];
 /** Minimal interface for McpServer — avoids hard SDK type dependency */
 interface McpServerInstance {
   connect: (transport: unknown) => Promise<void>;
@@ -516,4 +578,4 @@ declare function permissionDeniedResult(args: {
   session: McpAuthResult | null;
 }): CallToolResult;
 //#endregion
-export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpServerConfig, type CrudDescriptionMeta, type CrudDescriptionOverride, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type InvokeControllerOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpOperation, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };
+export { type AuthRef, type BetterAuthHandler, type BuildMcpToolsFromBridgesOptions, type CallToolResult, type CreateMcpAuthFromBetterAuthApiKeyOptions, type CreateMcpServerConfig, type CrudDescriptionMeta, type CrudDescriptionOverride, type CrudOperation, type DefinePromptConfig, type DefineToolConfig, type FieldRuleEntry, type FieldRulesToZodOptions, type InvokeControllerOptions, type McpAuthResolver, type McpAuthResult, type McpBridge, type McpGuard, type McpOperation, type McpPluginOptions, type McpResourceConfig, type McpServerInstance, type PromptDefinition, type PromptResult, type ResourceToToolsConfig, type ToolAnnotations, type ToolContext, type ToolDefinition, bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };

package/dist/integrations/mcp/index.mjs

@@ -1,4 +1,4 @@
-import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-Dbgz9_Rj.mjs";
+import { a as defaultCrudDescription, c as mcpHandlerAdapter, d as toCallToolResult, f as toCallToolSuccess, h as resolveToolCollisions, i as fieldRulesToZod, l as permissionDeniedResult, m as createMcpServer, n as mcpPlugin, o as resolveCrudDescription, p as buildRequestContext, r as resourceToTools, s as invokeController, t as filterResourcesForMcp, u as toCallToolError } from "../../mcpPlugin-hZE00H74.mjs";
 //#region src/integrations/mcp/defineTool.ts
 /**
 * Define a type-safe MCP tool.
@@ -167,6 +167,97 @@ function buildMcpToolsFromBridges(bridges, options = {}) {
 	}).map(bridgeToMcp);
 }
 //#endregion
+//#region src/integrations/mcp/betterAuthApiKey.ts
+/**
+* Build an {@link McpAuthResolver} that authenticates MCP requests against
+* Better Auth's API-key plugin. See module docstring for the rationale.
+*/
+function createMcpAuthFromBetterAuthApiKey(auth, options = {}) {
+	const verifyApiKey = auth.api?.verifyApiKey;
+	if (typeof verifyApiKey !== "function") throw new Error("createMcpAuthFromBetterAuthApiKey: the provided Better Auth instance does not expose `api.verifyApiKey`. Register the `apiKey()` plugin on your auth instance (see https://www.better-auth.com/docs/plugins/api-key) and pass the same `auth` object you pass to your REST routes.");
+	const orgFromMetadata = options.orgFromMetadata ?? true;
+	const metadataOrgField = options.metadataOrgField ?? "organizationId";
+	const permissionScope = options.permissionScope === void 0 ? "mcp" : options.permissionScope;
+	return async (headers) => {
+		const apiKey = extractApiKey(headers);
+		if (!apiKey) return null;
+		let result;
+		try {
+			result = await verifyApiKey({
+				body: { key: apiKey },
+				headers
+			});
+		} catch {
+			return null;
+		}
+		if (!result?.valid || !result.key) return null;
+		const key = result.key;
+		if (key.disabled === true) return null;
+		if (key.expiresAt) {
+			const exp = key.expiresAt instanceof Date ? key.expiresAt : new Date(key.expiresAt);
+			if (Number.isFinite(exp.getTime()) && exp.getTime() < Date.now()) return null;
+		}
+		const userId = key.userId ?? key.referenceId;
+		const organizationId = resolveOrg(key, orgFromMetadata, metadataOrgField);
+		const scopes = resolveScopes(key, permissionScope);
+		const clientId = !userId && key.id ? key.id : void 0;
+		if (!userId && !clientId) return null;
+		return {
+			...userId ? { userId } : {},
+			...organizationId ? { organizationId } : {},
+			...clientId ? { clientId } : {},
+			...scopes && scopes.length ? { scopes } : {}
+		};
+	};
+}
+function extractApiKey(headers) {
+	const authz = headers.authorization ?? headers.Authorization;
+	if (typeof authz === "string" && authz.length > 0) {
+		const token = /^Bearer\s+(.+)$/i.exec(authz)?.[1];
+		if (token) return token.trim();
+	}
+	const direct = headers["x-api-key"] ?? headers["X-Api-Key"];
+	if (typeof direct === "string" && direct.length > 0) return direct.trim();
+	return null;
+}
+function resolveOrg(key, setting, field) {
+	if (setting === false) return void 0;
+	const metadata = parseMetadata(key.metadata);
+	if (typeof setting === "function") {
+		const value = setting(metadata, key);
+		return typeof value === "string" && value.length > 0 ? value : void 0;
+	}
+	if (metadata && typeof metadata === "object") {
+		const raw = metadata[field];
+		if (typeof raw === "string" && raw.length > 0) return raw;
+	}
+}
+function resolveScopes(key, scopeKey) {
+	if (scopeKey === false) return void 0;
+	const permissions = parseMetadata(key.permissions);
+	if (permissions && typeof permissions === "object") {
+		const bucket = permissions[scopeKey];
+		if (Array.isArray(bucket) && bucket.every((s) => typeof s === "string")) return bucket;
+	}
+	if (Array.isArray(key.scopes) && key.scopes.every((s) => typeof s === "string")) return key.scopes;
+}
+/**
+* Better Auth stores `metadata` and `permissions` as JSON-stringified
+* columns in SQL kits. Accept both shapes — already-parsed objects pass
+* through, strings round-trip through `JSON.parse`. Failures yield
+* `undefined` rather than throwing because malformed metadata should
+* degrade gracefully (key still authenticates; org scope is absent).
+*/
+function parseMetadata(value) {
+	if (value === null || value === void 0) return void 0;
+	if (typeof value === "string") try {
+		return JSON.parse(value);
+	} catch {
+		return;
+	}
+	return value;
+}
+//#endregion
 //#region src/integrations/mcp/definePrompt.ts
 /**
 * Define a type-safe MCP prompt.
@@ -184,4 +275,4 @@ function definePrompt(name, config) {
 	};
 }
 //#endregion
-export { bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };
+export { bridgeToMcp, buildMcpToolsFromBridges, buildRequestContext, createMcpAuthFromBetterAuthApiKey, createMcpServer, customGuard, defaultCrudDescription, definePrompt, defineTool, denied, fieldRulesToZod, filterResourcesForMcp, getOrgId, getUserId, guard, hasOrg, invokeController, isAuthenticated, isOrg, mcpHandlerAdapter, mcpPlugin, permissionDeniedResult, requireAuth, requireOrg, requireOrgId, requireRole, resolveCrudDescription, resolveToolCollisions, resourceToTools, toCallToolError, toCallToolResult, toCallToolSuccess };

package/dist/integrations/mcp/testing.d.mts

@@ -1,4 +1,4 @@
-import { c as McpAuthResult, l as McpPluginOptions } from "../../types-BD0BCdf6.mjs";
+import { c as McpAuthResult, l as McpPluginOptions } from "../../types-CoMjNmkF.mjs";
 
 //#region src/integrations/mcp/testing.d.ts
 interface TestMcpClientOptions {

package/dist/integrations/mcp/testing.mjs

@@ -1,4 +1,4 @@
-import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-Dbgz9_Rj.mjs";
+import { m as createMcpServer, r as resourceToTools, t as filterResourcesForMcp } from "../../mcpPlugin-hZE00H74.mjs";
 //#region src/integrations/mcp/testing.ts
 /**
 * @classytic/arc/mcp/testing — MCP Test Utilities

package/dist/integrations/websocket.mjs

@@ -1,3 +1,4 @@
+import sjson from "secure-json-parse";
 import fp from "fastify-plugin";
 //#region src/integrations/websocket/adapter.ts
 /**
@@ -140,7 +141,7 @@ async function handleConnection(ctx, socket, request) {
 		}
 		let msg;
 		try {
-			msg = JSON.parse(typeof raw === "string" ? raw : raw.toString());
+			msg = sjson.parse(typeof raw === "string" ? raw : raw.toString());
 		} catch {
 			socket.send(JSON.stringify({
 				type: "error",

package/dist/{mcpPlugin-Dbgz9_Rj.mjs → mcpPlugin-hZE00H74.mjs}

@@ -1,8 +1,8 @@
-import { p as isArcError } from "./errors-j4aJm1Wg.mjs";
-import { t as BaseController } from "./BaseController-Vk8I7C0x.mjs";
-import { L as normalizePermissionResult } from "./permissions-CTxMrreC.mjs";
+import { p as isArcError, t as ArcError } from "./errors-j4aJm1Wg.mjs";
+import { t as BaseController } from "./BaseController-Dmeh4Y_y.mjs";
+import { L as normalizePermissionResult } from "./permissions-B1Qy55fg.mjs";
 import { t as executePipeline } from "./pipe-DiCyvyPN.mjs";
-import { u as resolvePipelineSteps } from "./routerShared-ClV4cCaa.mjs";
+import { f as resolvePipelineSteps } from "./routerShared-nCyJGOKX.mjs";
 import { r as validateAggregations } from "./validate-DFIP2VrM.mjs";
 import { n as executeAggregation } from "./buildHandler-C_SkBNF3.mjs";
 import { t as pluralize } from "./pluralize-B9M8xvy-.mjs";
@@ -14,6 +14,31 @@ import fp from "fastify-plugin";
 import { z } from "zod";
 //#region src/integrations/mcp/createMcpServer.ts
 /**
+* @classytic/arc — createMcpServer()
+*
+* Level 2 — Declarative MCP server factory.
+* Uses `server.registerTool()` / `server.registerPrompt()` (official SDK API)
+* with flat inputSchema shapes — no z.object() wrapping, no Zod version hacks.
+*
+* @example
+* ```typescript
+* import { createMcpServer, defineTool } from '@classytic/arc/mcp';
+* import { z } from 'zod';
+*
+* const server = await createMcpServer({
+*   name: 'my-api',
+*   version: '1.0.0',
+*   tools: [
+*     defineTool('greet', {
+*       description: 'Say hello',
+*       input: { name: z.string() },
+*       handler: async ({ name }) => ({ content: [{ type: 'text', text: `Hello ${name}` }] }),
+*     }),
+*   ],
+* });
+* ```
+*/
+/**
 * Create a configured MCP server from declarative config.
 *
 * @param config - Server name, version, tools, prompts
@@ -25,11 +50,70 @@ async function createMcpServer(config, authRef) {
 		name: config.name,
 		version: config.version ?? "1.0.0"
 	}, config.instructions ? { instructions: config.instructions } : void 0);
-	if (config.tools) for (const tool of config.tools) registerTool(server, tool, authRef);
+	if (config.tools) {
+		const resolved = resolveToolCollisions(config.tools);
+		for (const tool of resolved) registerTool(server, tool, authRef);
+	}
 	if (config.prompts) for (const prompt of config.prompts) registerPrompt(server, prompt);
 	return server;
 }
 /**
+* Detect and resolve duplicate MCP tool names across the assembled tool list.
+*
+* Two outcomes:
+*
+*  1. **Auto-namespace** — when one tool's `source` carries a `preset:<name>`
+*     prefix and the other doesn't, the preset tool is renamed to
+*     `<presetName>_<originalName>` (e.g. softDelete's `restore_post`
+*     becomes `softdelete_restore_post` when the user defines
+*     `actions.restore`). The user's tool wins the canonical name because
+*     it's the more-specific intent.
+*
+*  2. **Typed throw** — every other collision (two user actions, two
+*     custom routes, two presets) raises `ArcError('arc.mcp.tool_name_collision')`
+*     naming both sources so the host's stack trace points at the
+*     resource definitions, not the MCP SDK internals.
+*
+* Exported for the testing harness so collision behaviour can be exercised
+* without a full server boot.
+*/
+function resolveToolCollisions(tools) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const t of tools) {
+		const list = byName.get(t.name);
+		if (list) list.push(t);
+		else byName.set(t.name, [t]);
+	}
+	const out = [];
+	for (const [name, list] of byName) {
+		const [first, second, ...rest] = list;
+		if (!first) continue;
+		if (!second) {
+			out.push(first);
+			continue;
+		}
+		if (rest.length === 0) {
+			const firstIsPreset = first.source?.startsWith("preset:") ?? false;
+			if (firstIsPreset !== (second.source?.startsWith("preset:") ?? false)) {
+				const preset = firstIsPreset ? first : second;
+				const user = firstIsPreset ? second : first;
+				const namespaced = `${(preset.source?.split(":")[1] ?? "preset").toLowerCase()}_${name}`;
+				out.push({
+					...preset,
+					name: namespaced
+				});
+				out.push(user);
+				continue;
+			}
+		}
+		throw new ArcError(`MCP tool name '${name}' is registered by ${list.length} sources: ${list.map((t) => t.source ?? "(unknown)").join(", ")}. Rename one of the sources (e.g. via 'actions.${name}' → 'actions.${name}V2', or pass 'names: { [op]: "custom_name" }' in mcpPlugin overrides) so each tool has a unique name.`, {
+			code: "arc.mcp.tool_name_collision",
+			statusCode: 500
+		});
+	}
+	return out;
+}
+/**
 * Register a ToolDefinition using `server.registerTool()`.
 *
 * The inputSchema is passed as a flat Zod shape `{ field: z.string() }` —
@@ -223,6 +307,13 @@ function expandOperatorKeys(input) {
 	}
 	return out;
 }
+/**
+* Resolve an `McpAuthResult` (or `null` for unauthenticated calls) into a
+* canonical `RequestScope`. Exported so the MCP tool helpers can build the
+* same scope when constructing the permission-check context, ensuring
+* `requireOrgMembership()` / `requireOrgRole()` see the same auth shape on
+* MCP that they see on HTTP.
+*/
 function buildScope(auth) {
 	if (!auth) return { kind: "public" };
 	if (auth.clientId && auth.organizationId) return {
@@ -264,6 +355,7 @@ async function evaluatePermission(check, session, resource, action, input) {
 		_id: session.userId,
 		...session
 	} : null;
+	const scope = buildScope(session);
 	return normalizePermissionResult(await check({
 		user,
 		request: {
@@ -271,7 +363,9 @@ async function evaluatePermission(check, session, resource, action, input) {
 			headers: {},
 			params: {},
 			query: {},
-			body: input
+			body: input,
+			scope,
+			metadata: { _scope: scope }
 		},
 		resource,
 		action,
@@ -1473,7 +1567,8 @@ function resourceToTools(resource, config = {}) {
 					allowedOperators,
 					adapterBodies
 				}),
-				handler: createCrudHandler(op, controller, resource.name, resource.permissions)
+				handler: createCrudHandler(op, controller, resource.name, resource.permissions),
+				source: `crud:${resource.name}:${op}`
 			});
 		}
 	}
@@ -1508,11 +1603,13 @@ function resourceToTools(resource, config = {}) {
 			for (const [key, val] of Object.entries(schemaIRToZodShape(ir))) if (!(key in inputShape)) inputShape[key] = val;
 		}
 		const toolName = prefix ? `${prefix}_${opName}_${resource.name}` : `${opName}_${resource.name}`;
+		const routeSource = route._presetSource ? `preset:${route._presetSource}:${resource.name}:${opName}` : `route:${resource.name}:${route.method} ${route.path}`;
 		tools.push({
 			name: toolName,
 			description: toolDescription,
 			annotations: toolAnnotations,
 			inputSchema: inputShape,
+			source: routeSource,
 			handler: mcpHandler ? createMcpHandlerPassthrough(mcpHandler) : createCustomRouteHandler({
 				handler: resolvedRouteHandler,
 				operation: route.operation,
@@ -1552,6 +1649,7 @@ function resourceToTools(resource, config = {}) {
 			description: String(description),
 			annotations,
 			inputSchema: inputShape,
+			source: `action:${resource.name}:${actionName}`,
 			handler: createActionToolHandler(actionName, handler, actionPerms, resource.name, resource.permissions, rawSchema, idLess)
 		});
 	}
@@ -1799,6 +1897,11 @@ const mcpPluginImpl = async (fastify, options) => {
 	}
 	if (options.auth && isBetterAuth(options.auth)) await registerOAuthDiscovery(fastify, options.auth);
 	const prefix = options.prefix ?? "/mcp";
+	if (options.auth === false) {
+		const toolList = allTools.map((t) => t.name).slice(0, 5).join(", ");
+		const more = allTools.length > 5 ? ` (+${allTools.length - 5} more)` : "";
+		fastify.log.warn(`[arc/mcp] MCP server registered at "${prefix}" with auth DISABLED. Anyone who can reach this URL has full access to ${allTools.length} tools across ${enabledResources.length} resources: ${toolList}${more}. Pass \`auth: betterAuthInstance\` or \`auth: async (headers) => ...\` to gate access. Safe only for stdio transports, local development, or explicitly-public read-only APIs.`);
+	}
 	fastify.get(`${prefix}/health`, async (_request, reply) => {
 		reply.send({
 			status: "ok",
@@ -2013,4 +2116,4 @@ const mcpPlugin = fp(mcpPluginImpl, {
 	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 };
+export { defaultCrudDescription as a, mcpHandlerAdapter as c, toCallToolResult as d, toCallToolSuccess as f, resolveToolCollisions as h, 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 };

package/dist/middleware/index.d.mts

@@ -1,4 +1,4 @@
-import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-DBDgy6Hw.mjs";
+import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-C1JSBan-.mjs";
 import { RouteHandlerMethod } from "fastify";
 
 //#region src/middleware/middleware.d.ts

package/dist/middleware/index.mjs

@@ -1,5 +1,5 @@
 import { t as CRUD_OPERATIONS } from "../constants-TrJVIJl0.mjs";
-import { t as multipartBody } from "../multipartBody-BOvVSVCD.mjs";
+import { t as multipartBody } from "../multipartBody-VjVWmZl8.mjs";
 //#region src/middleware/middleware.ts
 /**
 * Named Middleware — Priority-based, conditional middleware execution.

package/dist/{multipartBody-BOvVSVCD.mjs → multipartBody-VjVWmZl8.mjs}

@@ -1,3 +1,4 @@
+import sjson from "secure-json-parse";
 //#region src/middleware/multipartBody.ts
 const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
 const DEFAULT_MAX_FILES = 5;
@@ -118,7 +119,7 @@ function tryParseValue(value) {
 		if (Number.isFinite(num)) return num;
 	}
 	if (value.startsWith("{") && value.endsWith("}") || value.startsWith("[") && value.endsWith("]")) try {
-		return JSON.parse(value);
+		return sjson.parse(value);
 	} catch {}
 	return value;
 }

package/dist/{openapi-BRnd3pT7.mjs → openapi-DKDs9NfD.mjs}

@@ -1,8 +1,8 @@
-import { t as getUserRoles } from "./types-D57iXYb8.mjs";
+import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
 import { n as convertRouteSchema } from "./schemaConverter-De34B1ZG.mjs";
 import { t as pluralize } from "./pluralize-B9M8xvy-.mjs";
 import { t as resolveActionPermission } from "./actionPermissions-Bjmvn7Eb.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-eiOFtnC3.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-BHUMb1-y.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi/canonical-schemas.ts
 /**

package/dist/permissions/index.mjs

@@ -1,3 +1,3 @@
-import { A as roles, C as allowPublic, D as requireAuth, E as not, F as applyPermissionResult, L as normalizePermissionResult, M as requireAgentScope, N as requireDPoP, O as requireOwnership, P as requireMandate, S as allOf, T as denyAll, _ as requireOrgMembership, a as presets_exports, b as requireServiceScope, c as readOnly, d as applyFieldWritePermissions, f as fields, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, l as createRoleHierarchy, m as createDynamicPermissionMatrix, n as authenticated, o as publicRead, p as resolveEffectiveRoles, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as applyFieldReadPermissions, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "../permissions-CTxMrreC.mjs";
-import { n as normalizeRoles, t as getUserRoles } from "../types-D57iXYb8.mjs";
+import { A as requireMandate, C as requireAuth, D as when, E as roles, F as applyPermissionResult, L as normalizePermissionResult, M as applyFieldWritePermissions, N as fields, O as requireAgentScope, P as resolveEffectiveRoles, S as not, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, j as applyFieldReadPermissions, k as requireDPoP, l as createRoleHierarchy, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "../permissions-B1Qy55fg.mjs";
+import { n as normalizeRoles, t as getUserRoles } from "../types-DV9WDfeg.mjs";
 export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };