@abinnovision/payloadcms-mcpx 2.0.0-beta.18 → 2.0.0-beta.20

package/dist/grants/confirmation.mjs

@@ -1,17 +1,8 @@
-import { isPlainObject } from "../guards.mjs";
-import { hashApiKey } from "../api-keys/key.mjs";
-import { GRANT_ID, NO_REQ, expOf, issueRow, rowsWith } from "./grant.mjs";
-import { ValidationError } from "payload";
+import { NO_REQ, ROW_ID, claimRow, expOf, issueRow, rowHandle, rowPrefixes, rowsWith } from "./grant.mjs";
 //#region src/grants/confirmation.ts
 const CONFIRMATION_TTL_MS = 9e5;
 const HANDLE = /^[\da-f]{64}$/;
-const entryPrefix = (apiKeyId) => `mcpx-confirmation:${String(apiKeyId)}:`;
-const usedPrefix = (apiKeyId) => `mcpx-confirmation-used:${String(apiKeyId)}:`;
-const asConfirmation = (row, now) => row && isPlainObject(row.data) && expOf(row.data) > now ? row.data : void 0;
-/**
-* The handle the admin panel uses for the entry of `id`: its HMAC, which is
-* also what the row key holds.
-*/ const confirmationHandle = (payload, id) => hashApiKey(payload.secret, id);
+const asConfirmation = (row, now) => row && expOf(row.data) > now ? row.data : void 0;
 /**
 * Stores a pending call and returns its id. A key may hold at most
 * {@link CONFIRMATIONS_PER_KEY} calls.
@@ -21,8 +12,7 @@ const asConfirmation = (row, now) => row && isPlainObject(row.data) && expOf(row
 		state: "pending"
 	};
 	return await issueRow(payload, slug, {
-		prefix: entryPrefix(call.apiKeyId),
-		usedPrefix: usedPrefix(call.apiKeyId),
+		...rowPrefixes("confirmation", call.apiKeyId),
 		cap: 50,
 		capMessage: `This key already has ${String(50)} calls waiting for approval. Run or abandon them first; each expires 15 minutes after it was requested.`,
 		ttlMs: CONFIRMATION_TTL_MS,
@@ -33,40 +23,19 @@ const asConfirmation = (row, now) => row && isPlainObject(row.data) && expOf(row
 * The unexpired call of `apiKeyId` with `id`, without claiming it. A call of
 * another key is `undefined`, as is a malformed id, before any database read.
 */ const readConfirmation = async (payload, slug, apiKeyId, id) => {
-	if (!GRANT_ID.test(id)) return;
-	const key = `${entryPrefix(apiKeyId)}${confirmationHandle(payload, id)}`;
+	if (!ROW_ID.test(id)) return;
+	const key = `${rowPrefixes("confirmation", apiKeyId).prefix}${rowHandle(payload, id)}`;
 	const rows = await rowsWith(payload, slug, [key]);
 	return asConfirmation(rows.find((row) => row.key === key), Date.now());
 };
 /**
-* Marks the call used and removes it. The marker is a unique-key insert, so
-* of two concurrent claims exactly one returns `true`.
-*/ const claimConfirmation = async (payload, slug, apiKeyId, id, exp) => {
-	const handle = confirmationHandle(payload, id);
-	try {
-		await payload.db.create({
-			collection: slug,
-			data: {
-				key: `${usedPrefix(apiKeyId)}${handle}`,
-				data: { exp }
-			},
-			req: NO_REQ
-		});
-	} catch (error) {
-		if (error instanceof ValidationError) return false;
-		throw error;
-	}
-	await payload.db.deleteOne({
-		collection: slug,
-		where: { key: { equals: `${entryPrefix(apiKeyId)}${handle}` } },
-		req: NO_REQ
-	});
-	return true;
-};
+* Marks the call used and removes it. Of two concurrent claims exactly one
+* returns `true`.
+*/ const claimConfirmation = async (payload, slug, apiKeyId, id, exp) => await claimRow(payload, slug, rowPrefixes("confirmation", apiKeyId), rowHandle(payload, id), exp);
 /**
 * Every unexpired call of `apiKeyId` with its handle, oldest first.
 */ const listConfirmations = async (payload, slug, apiKeyId) => {
-	const prefix = entryPrefix(apiKeyId);
+	const { prefix } = rowPrefixes("confirmation", apiKeyId);
 	const now = Date.now();
 	return (await rowsWith(payload, slug, [prefix])).flatMap((row) => {
 		const confirmation = asConfirmation(row, now);
@@ -81,7 +50,7 @@ const asConfirmation = (row, now) => row && isPlainObject(row.data) && expOf(row
 * returns the handles it changed. A call that was decided, run or expired is
 * left alone and not returned.
 */ const decideConfirmations = async (payload, slug, apiKeyId, handles, state) => {
-	const prefix = entryPrefix(apiKeyId);
+	const { prefix } = rowPrefixes("confirmation", apiKeyId);
 	const keys = new Set(handles.filter((handle) => HANDLE.test(handle)).map((handle) => `${prefix}${handle}`));
 	if (keys.size === 0) return [];
 	const now = Date.now();
@@ -103,4 +72,4 @@ const asConfirmation = (row, now) => row && isPlainObject(row.data) && expOf(row
 	return decided;
 };
 //#endregion
-export { claimConfirmation, confirmationHandle, decideConfirmations, issueConfirmation, listConfirmations, readConfirmation };
+export { claimConfirmation, decideConfirmations, issueConfirmation, listConfirmations, readConfirmation };

package/dist/grants/grant.mjs

@@ -1,14 +1,21 @@
 import { isPlainObject } from "../guards.mjs";
-import { hashApiKey } from "../api-keys/key.mjs";
+import { generateApiKey, hashApiKey } from "../api-keys/key.mjs";
 import { APIError, ValidationError } from "payload";
-import crypto from "node:crypto";
 //#region src/grants/grant.ts
 const GRANT_TTL_MS = 3e5;
 const GRANTS_PER_KEY = 10;
-const GRANT_ID = /^[\w-]{43}$/;
+const ROW_ID = /^[\w-]{43}$/;
 const NO_REQ = {};
-const grantPrefix = (apiKeyId) => `mcpx-grant:${String(apiKeyId)}:`;
-const usedPrefix = (apiKeyId) => `mcpx-grant-used:${String(apiKeyId)}:`;
+/**
+* The key prefixes of a kind of row: waiting rows and the markers of used
+* ones.
+*/ const rowPrefixes = (kind, apiKeyId) => ({
+	prefix: `mcpx-${kind}:${String(apiKeyId)}:`,
+	usedPrefix: `mcpx-${kind}-used:${String(apiKeyId)}:`
+});
+/**
+* What a row is addressed by: the HMAC of its id, which the row key ends in.
+*/ const rowHandle = (payload, id) => hashApiKey(payload.secret, id);
 const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ? data["exp"] : 0;
 /**
 * The KV collection slug, when Payload's database KV adapter backs it with a
@@ -49,12 +56,12 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 		req: NO_REQ
 	});
 	if (rows.filter((row) => row.key.startsWith(args.prefix) && expOf(row.data) > now).length >= args.cap) throw new APIError(args.capMessage, 429);
-	const id = crypto.randomBytes(32).toString("base64url");
+	const id = generateApiKey();
 	const exp = now + args.ttlMs;
 	await payload.db.create({
 		collection: slug,
 		data: {
-			key: `${args.prefix}${hashApiKey(payload.secret, id)}`,
+			key: `${args.prefix}${rowHandle(payload, id)}`,
 			data: {
 				...args.data,
 				exp
@@ -68,52 +75,63 @@ const expOf = (data) => isPlainObject(data) && typeof data["exp"] === "number" ?
 	};
 };
 /**
-* Stores a grant and returns its id. A key may hold at most
-* {@link GRANTS_PER_KEY} grants.
-*/ const issueGrant = async (payload, slug, grant) => {
-	const { id, exp } = await issueRow(payload, slug, {
-		prefix: grantPrefix(grant.apiKeyId),
-		usedPrefix: usedPrefix(grant.apiKeyId),
-		cap: GRANTS_PER_KEY,
-		capMessage: `This key already has ${String(GRANTS_PER_KEY)} uploads or downloads waiting. Use or abandon them first; each expires 5 minutes after it was issued.`,
-		ttlMs: GRANT_TTL_MS,
-		data: grant
-	});
-	return {
-		grantId: id,
-		exp
-	};
-};
-/**
-* Loads the grant for `grantId` and marks it used, or returns `undefined` for
-* a malformed, unknown, expired or used one. The marker is a unique-key
-* insert, so of two concurrent claims exactly one succeeds. A malformed id
-* is refused before any database read.
-*/ const claimGrant = async (payload, slug, grantId) => {
-	if (!GRANT_ID.test(grantId)) return;
-	const hash = hashApiKey(payload.secret, grantId);
-	const row = (await findRows(payload, slug, [hash])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${hash}`));
-	const grant = row?.data;
-	if (!row || !isPlainObject(grant) || row.key !== `${grantPrefix(grant.apiKeyId)}${hash}` || expOf(grant) <= Date.now()) return;
+* Marks the row under `handle` used and removes it. The marker is a
+* unique-key insert, so of two concurrent claims exactly one returns `true`.
+*/ const claimRow = async (payload, slug, prefixes, handle, exp) => {
 	try {
 		await payload.db.create({
 			collection: slug,
 			data: {
-				key: `${usedPrefix(grant.apiKeyId)}${hash}`,
-				data: { exp: grant.exp }
+				key: `${prefixes.usedPrefix}${handle}`,
+				data: { exp }
 			},
 			req: NO_REQ
 		});
 	} catch (error) {
-		if (error instanceof ValidationError) return;
+		if (error instanceof ValidationError) return false;
 		throw error;
 	}
 	await payload.db.deleteOne({
 		collection: slug,
-		where: { key: { equals: row.key } },
+		where: { key: { equals: `${prefixes.prefix}${handle}` } },
 		req: NO_REQ
 	});
-	return grant;
+	return true;
+};
+/**
+* The KV slug and key id of the request, which a call that stores a grant or
+* a confirmation needs. Throws where the endpoint would not offer one.
+*/ const grantContext = (req) => {
+	const slug = grantKvSlug(req.payload.config);
+	const apiKeyId = req.context.mcpx?.apiKeyId;
+	if (slug === void 0 || apiKeyId === void 0) throw new Error("A grant or confirmation needs a database KV and a key.");
+	return {
+		slug,
+		apiKeyId
+	};
+};
+/**
+* Stores a grant and returns its id. A key may hold at most
+* {@link GRANTS_PER_KEY} grants.
+*/ const issueGrant = async (payload, slug, grant) => await issueRow(payload, slug, {
+	...rowPrefixes("grant", grant.apiKeyId),
+	cap: GRANTS_PER_KEY,
+	capMessage: `This key already has ${String(GRANTS_PER_KEY)} uploads or downloads waiting. Use or abandon them first; each expires 5 minutes after it was issued.`,
+	ttlMs: GRANT_TTL_MS,
+	data: grant
+});
+/**
+* Loads the grant for `grantId` and marks it used, or returns `undefined` for
+* a malformed, unknown, expired or used one. A malformed id is refused before
+* any database read.
+*/ const claimGrant = async (payload, slug, grantId) => {
+	if (!ROW_ID.test(grantId)) return;
+	const handle = rowHandle(payload, grantId);
+	const row = (await findRows(payload, slug, [handle])).find((candidate) => candidate.key.startsWith("mcpx-grant:") && candidate.key.endsWith(`:${handle}`));
+	const grant = row?.data;
+	if (!row || !isPlainObject(grant) || expOf(grant) <= Date.now()) return;
+	const prefixes = rowPrefixes("grant", grant.apiKeyId);
+	return row.key === `${prefixes.prefix}${handle}` && await claimRow(payload, slug, prefixes, handle, grant.exp) ? grant : void 0;
 };
 //#endregion
-export { GRANT_ID, NO_REQ, claimGrant, expOf, grantKvSlug, issueGrant, issueRow, rowsWith };
+export { NO_REQ, ROW_ID, claimGrant, claimRow, expOf, grantContext, grantKvSlug, issueGrant, issueRow, rowHandle, rowPrefixes, rowsWith };

package/dist/guards.mjs

@@ -1,7 +1,14 @@
 //#region src/guards.ts
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /**
+* A property of a plain object, `undefined` for any other value.
+*/ const propOf = (value, key) => isPlainObject(value) ? value[key] : void 0;
+/**
 * An own property only, so a client-chosen key never reads the prototype.
 */ const ownValue = (record, key) => record !== void 0 && Object.hasOwn(record, key) ? record[key] : void 0;
+/**
+* The entries whose value is not `undefined`, for spreading optional arguments
+* into a call.
+*/ const definedProps = (props) => Object.fromEntries(Object.entries(props).filter(([, value]) => value !== void 0));
 //#endregion
-export { isPlainObject, ownValue };
+export { definedProps, isPlainObject, ownValue, propOf };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { DocumentId } from "./entity.mjs";
-import { McpxAnyTool, McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope, McpxWriteMode } from "./types.mjs";
+import { McpxAnyTool, McpxAuthResult, McpxCollectionOptions, McpxEntityCapabilities, McpxExposedEntity, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxScopeSlugs, McpxTool, McpxToolExtra, McpxToolScope } from "./types.mjs";
 import { defineMcpxTool } from "./define-tool.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, type McpxWriteMode, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };
+export { type McpxAnyTool, type McpxAuthResult, type McpxCollectionOptions, type DocumentId as McpxDocumentId, type McpxEntityCapabilities, type McpxExposedEntity, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxScopeSlugs, type McpxTool, type McpxToolExtra, type McpxToolScope, defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { defineMcpxTool } from "./define-tool.mjs";
+import { isMcpxRequest } from "./request.mjs";
 import { errorResult, jsonResult } from "./result.mjs";
 import { mcpxReadRequest } from "./tools/read-request.mjs";
-import { isMcpxRequest } from "./request.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 export { defineMcpxTool, errorResult, isMcpxRequest, jsonResult, mcpxPlugin, mcpxReadRequest };

package/dist/options.mjs

@@ -1,6 +1,5 @@
 import { isPlainObject } from "./guards.mjs";
 import "./version.mjs";
-import { BUILTIN_TOOL_NAMES } from "./builtin-tool-names.mjs";
 import { InvalidConfiguration } from "payload";
 import { hasDraftsEnabled, hasLocalizeStatusEnabled } from "payload/shared";
 //#region src/options.ts
@@ -15,10 +14,10 @@ const fail = (message) => {
 /**
 * The same transform the stock MCP plugin uses to derive field names.
 */ const toCamelCase = (value) => value.replace(/[-_\s]+(.)?/g, (_, char) => char ? char.toUpperCase() : "").replace(/^(.)/, (_, char) => char.toLowerCase());
-const assertExposable = (collection, apiKeysSlug) => {
-	const { slug } = collection;
-	if (slug === apiKeysSlug || slug.startsWith("payload-")) fail(`Collection "${slug}" cannot be exposed.`);
-	if (collection.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
+const assertExposable = (kind, config, apiKeysSlug) => {
+	const { slug } = config;
+	if (slug.startsWith("payload-") || kind === "Collection" && slug === apiKeysSlug) fail(`${kind} "${slug}" cannot be exposed.`);
+	if ("auth" in config && config.auth) fail(`Auth collection "${slug}" cannot be exposed. Its documents carry credentials.`);
 };
 const OPTION_NAMES = [
 	"read",
@@ -40,8 +39,8 @@ const readFlag = (kind, slug, name, value) => {
 	const moved = name === "write" && typeof value === "string" ? REMOVED_WRITE_MODES[value] : void 0;
 	return fail(`${kind} "${slug}" has ${name}: ${JSON.stringify(value)}. ${moved ?? "Use true or false."}`);
 };
-const assertWritable = (kind, config, write) => {
-	if (write === "live" && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
+const assertWritable = (kind, config, publish) => {
+	if (publish && hasLocalizeStatusEnabled(config)) fail(`${kind} "${config.slug}" has versions.drafts.localizeStatus enabled, which live writes do not support yet. Set publish: false or write: false.`);
 };
 const normalizeDelete = (kind, config, value) => {
 	if (value !== "unattended") return {
@@ -75,68 +74,47 @@ const normalizeCapabilities = (kind, config, raw) => {
 	if (!read && deleting.delete) fail(`${kind} "${slug}" has read: false but delete on. Deleting needs read.`);
 	return {
 		read,
-		write: write ? publish === false ? "draft" : "live" : false,
+		write,
+		publish: write && publish !== false && hasDrafts,
+		liveWrite: write && !hasDrafts,
 		hasDrafts,
 		hasVersions: read && Boolean(config.versions),
 		...deleting
 	};
 };
-const assertGlobalExposable = (global) => {
-	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
-};
-const normalizeCollections = (config, options, apiKeysSlug) => {
-	const collections = config.collections ?? [];
+const bySlug = (configs) => new Map(configs.map((config) => [config.slug, config]));
+const normalizeEntities = (kind, configs, entries, apiKeysSlug) => {
 	const fieldNames = /* @__PURE__ */ new Set();
-	return Object.entries(options.collections).flatMap(([slug, raw]) => {
+	return Object.entries(entries).flatMap(([slug, raw]) => {
 		if (raw === void 0) return [];
-		const collection = collections.find((candidate) => candidate.slug === slug);
-		if (!collection) return fail(`Exposed collection "${slug}" does not exist.`);
-		assertExposable(collection, apiKeysSlug);
+		const config = configs.get(slug);
+		if (!config) return fail(`Exposed ${kind.toLowerCase()} "${slug}" does not exist.`);
+		assertExposable(kind, config, apiKeysSlug);
 		const normalized = {
 			slug,
-			...normalizeCapabilities("Collection", collection, raw),
-			isUpload: Boolean(collection.upload),
+			...normalizeCapabilities(kind, config, raw),
+			isUpload: "upload" in config && Boolean(config.upload),
 			fieldName: toCamelCase(slug)
 		};
-		if (normalized.write !== false) {
-			if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
-			assertWritable("Collection", collection, normalized.write);
+		if (normalized.write) {
+			if ("timestamps" in config && config.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
+			assertWritable(kind, config, normalized.publish);
 		}
-		if (fieldNames.has(normalized.fieldName)) fail(`Collection "${slug}" maps to capability field "${normalized.fieldName}", which another exposed collection already uses.`);
-		fieldNames.add(normalized.fieldName);
-		return [normalized];
-	});
-};
-const normalizeGlobals = (config, options) => {
-	const globals = config.globals ?? [];
-	const fieldNames = /* @__PURE__ */ new Set();
-	return Object.entries(options.globals ?? {}).flatMap(([slug, raw]) => {
-		if (raw === void 0) return [];
-		const global = globals.find((candidate) => candidate.slug === slug);
-		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
-		assertGlobalExposable(global);
-		const normalized = {
-			slug,
-			...normalizeCapabilities("Global", global, raw),
-			isUpload: false,
-			fieldName: toCamelCase(slug)
-		};
-		if (normalized.write !== false) assertWritable("Global", global, normalized.write);
-		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
+		if (fieldNames.has(normalized.fieldName)) fail(`${kind} "${slug}" maps to capability field "${normalized.fieldName}", which another exposed ${kind.toLowerCase()} already uses.`);
 		fieldNames.add(normalized.fieldName);
 		return [normalized];
 	});
 };
-const assertUserCollection = (config, slug) => {
-	const collection = (config.collections ?? []).find((candidate) => candidate.slug === slug);
+const assertUserCollection = (collections, slug) => {
+	const collection = collections.get(slug);
 	if (!collection) fail(`User collection "${slug}" does not exist.`);
-	else if (!collection.auth) fail(`User collection "${slug}" is not an auth collection.`);
+	else if (!("auth" in collection && collection.auth)) fail(`User collection "${slug}" is not an auth collection.`);
 };
-const assertTools = (tools) => {
+const assertTools = (tools, reserved) => {
 	const names = /* @__PURE__ */ new Set();
 	for (const tool of tools) {
 		if (!TOOL_NAME_PATTERN.test(tool.name)) fail(`Tool name "${tool.name}" must match ${String(TOOL_NAME_PATTERN)}.`);
-		if (BUILTIN_TOOL_NAMES.includes(tool.name)) fail(`Tool name "${tool.name}" is reserved for a builtin tool.`);
+		if (reserved.includes(tool.name)) fail(`Tool name "${tool.name}" is reserved for a builtin tool.`);
 		if (names.has(tool.name)) fail(`Tool name "${tool.name}" is used twice.`);
 		names.add(tool.name);
 	}
@@ -153,19 +131,21 @@ const normalizeLimits = (limits) => {
 };
 /**
 * Every problem is an `InvalidConfiguration`, so it fails at startup.
-*/ const normalizeOptions = (config, options) => {
+* `reservedToolNames` are the builtin tool names custom tools must not reuse.
+*/ const normalizeOptions = (config, options, reservedToolNames) => {
 	const apiKeysSlug = options.apiKeys?.slug ?? DEFAULT_API_KEYS_SLUG;
 	const userCollection = options.userCollection ?? config.admin?.user ?? "users";
-	if ((config.collections ?? []).some((c) => c.slug === apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
-	assertUserCollection(config, userCollection);
+	const collectionConfigs = bySlug(config.collections ?? []);
+	if (collectionConfigs.has(apiKeysSlug)) fail(`API key collection slug "${apiKeysSlug}" is already taken.`);
+	assertUserCollection(collectionConfigs, userCollection);
 	const tools = options.tools ?? [];
-	assertTools(tools);
-	const collections = normalizeCollections(config, options, apiKeysSlug);
+	assertTools(tools, reservedToolNames);
+	const collections = normalizeEntities("Collection", collectionConfigs, options.collections, apiKeysSlug);
 	const confirmations = collections.some((entity) => entity.delete);
 	if (confirmations && options.auth?.resolve) fail("delete needs approval on the API key document, which a custom auth.resolve does not support. Remove delete: true or auth.resolve.");
 	return {
 		collections,
-		globals: normalizeGlobals(config, options),
+		globals: normalizeEntities("Global", bySlug(config.globals ?? []), options.globals ?? {}, apiKeysSlug),
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,

package/dist/plugin.mjs

@@ -1,4 +1,5 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
+import { BUILTIN_TOOLS } from "./tools/builtin.mjs";
 import { confirmationEndpoints } from "./endpoint/confirmations.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
 import { createDownloadHandler, createUploadHandler } from "./endpoint/upload.mjs";
@@ -14,7 +15,7 @@ import { definePlugin } from "payload";
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
 	plugin: ({ config, plugins: _plugins, ...options }) => {
-		const normalized = normalizeOptions(config, options);
+		const normalized = normalizeOptions(config, options, BUILTIN_TOOLS.map((tool) => tool.name));
 		const apiKeys = createApiKeysCollection(normalized);
 		const apiKeysCollection = options.apiKeys?.overrideCollection?.(apiKeys) ?? apiKeys;
 		return {

package/dist/request.mjs

@@ -3,5 +3,9 @@
 * Whether `req` came through the MCP endpoint, which stamps `req.context.mcpx`.
 * The stamp follows `req` into every local API call, including custom tools.
 */ const isMcpxRequest = (req) => req.context.mcpx !== void 0;
+/**
+* The origin links to this server use: `serverURL` when set, else that of the
+* MCP request.
+*/ const publicOrigin = (req) => req.payload.config.serverURL || new URL(req.url ?? "").origin;
 //#endregion
-export { isMcpxRequest };
+export { isMcpxRequest, publicOrigin };

package/dist/result.mjs

@@ -1,4 +1,14 @@
 //#region src/result.ts
+/**
+* The JSON of a result's first text block. Other text comes back as `{ text }`.
+*/ const parseResult = (result) => {
+	const [first] = result.content;
+	try {
+		return first?.type === "text" ? JSON.parse(first.text) : {};
+	} catch {
+		return { text: first?.type === "text" ? first.text : void 0 };
+	}
+};
 const jsonResult = (value) => ({ content: [{
 	type: "text",
 	text: JSON.stringify(value)
@@ -17,4 +27,4 @@ const jsonResult = (value) => ({ content: [{
 	isError: true
 });
 //#endregion
-export { errorResult, jsonResult };
+export { errorResult, jsonResult, parseResult };

package/dist/schema/admin-hidden.mjs

@@ -1,5 +1,5 @@
 import { isPlainObject } from "../guards.mjs";
-import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, isAdminHidden, schemaOf } from "./walk.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, adminFlag, blockForRow, blockOf, blockSlugsOf, schemaOf } from "./walk.mjs";
 //#region src/schema/admin-hidden.ts
 const UPLOAD_BASE_FIELDS = /* @__PURE__ */ new Set([
 	"filename",
@@ -22,7 +22,7 @@ const stripFields = (config, fields, doc, exempt = NONE) => {
 	const result = { ...doc };
 	for (const field of fields) {
 		if (!("name" in field) || exempt.has(field.name) || isPayloadKey(field.name) || !Object.hasOwn(result, field.name)) continue;
-		if (isAdminHidden(field)) Reflect.deleteProperty(result, field.name);
+		if (adminFlag(field, "hidden")) Reflect.deleteProperty(result, field.name);
 		else result[field.name] = stripValue(config, field, result[field.name]);
 	}
 	return result;
@@ -45,7 +45,7 @@ const stripValue = (config, field, value) => {
 		case "tab": return isPlainObject(value) ? stripFields(config, field.flattenedFields, value) : value;
 		case "array": return mapEach(value, (row) => isPlainObject(row) ? stripFields(config, field.flattenedFields, row) : row);
 		case "blocks": return mapEach(value, (row) => {
-			const block = isPlainObject(row) && typeof row["blockType"] === "string" ? blockOf(config, field, row["blockType"]) : void 0;
+			const block = blockForRow(config, field, row);
 			return block && isPlainObject(row) ? stripFields(config, block.flattenedFields, row) : row;
 		});
 		case "relationship":
@@ -76,7 +76,7 @@ const stripValue = (config, field, value) => {
 		const matches = fields.filter((field) => "name" in field && field.name === segment);
 		if (matches.length === 0) return locales.includes(segment) ? walk(fields, rest) : false;
 		return matches.some((field) => {
-			if (isAdminHidden(field)) return true;
+			if (adminFlag(field, "hidden")) return true;
 			if (field.type === "group" || field.type === "tab" || field.type === "array") return walk(field.flattenedFields, rest);
 			return field.type === "blocks" && blockSlugsOf(field).some((slug) => {
 				const block = blockOf(config, field, slug);

package/dist/schema/describe.mjs

@@ -1,25 +1,22 @@
+import { SchemaError } from "./errors.mjs";
 import { lexicalSubSchema, subSchemaNodeTypes } from "./lexical.mjs";
 import { joinPath, splitPath } from "./path.mjs";
 import { translateAny } from "../i18n.mjs";
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, findRichTextField, schemaOf } from "./walk.mjs";
-import { SchemaError } from "./errors.mjs";
+import { blockSlugsOf, describeFields, findFieldAt, longestMatch, requireBlock, schemaOf } from "./walk.mjs";
 //#region src/schema/describe.ts
-const matchSchemaSegments = (descriptors, remaining) => descriptors.map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
 const stepThroughBlocks = ({ config, fields, match, remaining }) => {
-	const field = findBlocksField(fields, match);
+	const field = findFieldAt(fields, match, "blocks");
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const slug = remaining.at(match.length);
 	if (slug === void 0) throw new SchemaError(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
-	const block = blockOf(config, field, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
 	return {
 		blockType: slug,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, field, slug, joinPath(match)).flattenedFields,
 		rest: remaining.slice(match.length + 1)
 	};
 };
 const stepThroughLexical = ({ config, fields, match, remaining }) => {
-	const field = findRichTextField(fields, match);
+	const field = findFieldAt(fields, match, "richText");
 	if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 	const available = subSchemaNodeTypes(field).join(", ") || "none";
 	const nodeType = remaining.at(match.length);
@@ -32,13 +29,10 @@ const stepThroughLexical = ({ config, fields, match, remaining }) => {
 		rest: remaining.slice(match.length + 1)
 	};
 	const slug = remaining.at(match.length + 1);
-	const slugs = blockSlugsOf(sub.blocksField).join(", ");
-	if (slug === void 0) throw new SchemaError(`"${reached}" selects a block; append one of: ${slugs}`);
-	const block = blockOf(config, sub.blocksField, slug);
-	if (!block) throw new SchemaError(`"${slug}" is not allowed at "${reached}". Allowed: ${slugs}`);
+	if (slug === void 0) throw new SchemaError(`"${reached}" selects a block; append one of: ${blockSlugsOf(sub.blocksField).join(", ")}`);
 	return {
 		blockType: slug,
-		fields: block.flattenedFields,
+		fields: requireBlock(config, sub.blocksField, slug, reached).flattenedFields,
 		rest: remaining.slice(match.length + 2)
 	};
 };
@@ -48,15 +42,15 @@ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 	let remaining = splitPath(schemaPath);
 	while (remaining.length > 0) {
 		const descendable = describeFields(fields).filter((descriptor) => descriptor.type === "blocks" || descriptor.type === "richText");
-		const match = matchSchemaSegments(descendable, remaining);
-		if (!match) throw new SchemaError(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
+		const found = longestMatch(descendable, remaining, (part, segment) => part === segment);
+		if (!found) throw new SchemaError(`"${joinPath(remaining)}" does not address a blocks or rich text field. Available here: ${descendable.map((descriptor) => descriptor.path).join(", ") || "none"}`);
 		const at = {
 			config,
 			fields,
-			match,
+			match: found.parts,
 			remaining
 		};
-		const step = findBlocksField(fields, match) === void 0 ? stepThroughLexical(at) : stepThroughBlocks(at);
+		const step = found.descriptor.type === "blocks" ? stepThroughBlocks(at) : stepThroughLexical(at);
 		blockType = step.blockType;
 		fields = step.fields;
 		remaining = step.rest;
@@ -69,7 +63,7 @@ const fieldsAtSchemaPath = (config, target, schemaPath) => {
 const branchesOf = (fields, descriptor, schemaPath) => {
 	const base = `${schemaPath}${descriptor.path}`;
 	if (descriptor.type === "richText") {
-		const field = findRichTextField(fields, splitPath(descriptor.path));
+		const field = findFieldAt(fields, splitPath(descriptor.path), "richText");
 		if (!field) return [];
 		return subSchemaNodeTypes(field).flatMap((nodeType) => {
 			const sub = lexicalSubSchema(field, nodeType);

package/dist/schema/index.mjs

@@ -1,11 +1,10 @@
-import { REQUIRED_NODE_PROPERTIES, ROOT_PROPERTIES, allowedNodeTypes, constrainsFields, lexicalSubSchema, nodeOptions, nodeProblems, nodePropertiesFor, propertyProblem, rootProblems, subSchemaNodeTypes } from "./lexical.mjs";
-import { JSON_POINTER_PATTERN, isIndexSegment, joinPath, pointerFromPayloadPath, prototypeSegmentProblem, splitPath } from "./path.mjs";
-import { RESERVED_FIELD_NAMES, ROW_KEYS, blockOf, blockSlugsOf, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, schemaOf } from "./walk.mjs";
-import { addressesAdminHidden, stripAdminHidden } from "./admin-hidden.mjs";
 import { SchemaError } from "./errors.mjs";
+import { editorRoot, nodePropertiesFor } from "./lexical.mjs";
+import { JSON_POINTER_PATTERN, isIndexSegment, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, splitPath } from "./path.mjs";
+import { RESERVED_FIELD_NAMES, ROW_KEYS, blockForRow, classifyKey, descriptorsUnder, findFieldAt } from "./walk.mjs";
+import { addressesAdminHidden, stripAdminHidden } from "./admin-hidden.mjs";
 import { nodeDescriber, reachableSchemaPaths } from "./describe.mjs";
-import { resolveLexicalPointer } from "./lexical-pointer.mjs";
 import { lexicalOutline } from "./outline.mjs";
 import { resolveDataPointer } from "./pointer.mjs";
 import { EMPTY_ROOT, validateWriteValue } from "./shape.mjs";
-export { EMPTY_ROOT, JSON_POINTER_PATTERN, REQUIRED_NODE_PROPERTIES, RESERVED_FIELD_NAMES, ROOT_PROPERTIES, ROW_KEYS, SchemaError, addressesAdminHidden, allowedNodeTypes, blockOf, blockSlugsOf, constrainsFields, describeAddressableFields, describeFields, descriptorsUnder, findBlocksField, findRichTextField, isAdminHidden, isIndexSegment, joinPath, lexicalOutline, lexicalSubSchema, nodeDescriber, nodeOptions, nodeProblems, nodePropertiesFor, pointerFromPayloadPath, propertyProblem, prototypeSegmentProblem, reachableSchemaPaths, resolveDataPointer, resolveLexicalPointer, rootProblems, schemaOf, splitPath, stripAdminHidden, subSchemaNodeTypes, validateWriteValue };
+export { EMPTY_ROOT, JSON_POINTER_PATTERN, RESERVED_FIELD_NAMES, ROW_KEYS, SchemaError, addressesAdminHidden, blockForRow, classifyKey, descriptorsUnder, editorRoot, findFieldAt, isIndexSegment, lexicalOutline, nodeDescriber, nodePropertiesFor, parentPointer, pointerFromPayloadPath, prototypeSegmentProblem, reachableSchemaPaths, resolveDataPointer, splitPath, stripAdminHidden, validateWriteValue };