@abinnovision/payloadcms-mcpx 1.0.0-beta.10

package/dist/api-keys/fields.mjs

@@ -0,0 +1,137 @@
+import { CAPABILITIES_FIELD } from "../capabilities.mjs";
+//#region src/api-keys/fields.ts
+const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
+const decryptKey = ({ req, value }) => {
+	if (typeof value !== "string") return value;
+	try {
+		return req.payload.decrypt(value);
+	} catch {
+		return;
+	}
+};
+const checkbox = (name, description) => ({
+	name,
+	type: "checkbox",
+	defaultValue: false,
+	admin: { description }
+});
+const SETUP_GUIDE_FIELD = "setupGuide";
+/**
+* Fields every key carries. Key generation and the HMAC index live in the
+* collection-level `beforeChange` hook (see `collection.ts`), because sibling
+* field hooks run in parallel and cannot depend on each other's values.
+*/ const createKeyFields = () => [
+	{
+		name: "label",
+		type: "text",
+		required: true,
+		admin: { description: "What this key is used for." }
+	},
+	{
+		name: "enabled",
+		type: "checkbox",
+		defaultValue: true,
+		admin: { description: "Disabled keys are refused without revoking them." }
+	},
+	{
+		name: "apiKey",
+		type: "text",
+		access: {
+			create: () => false,
+			update: () => false
+		},
+		admin: {
+			readOnly: true,
+			description: "Generated when the key is created. Send it as `Authorization: Bearer <key>`."
+		},
+		hooks: {
+			beforeChange: [encryptKey],
+			afterRead: [decryptKey]
+		}
+	},
+	{
+		name: "apiKeyIndex",
+		type: "text",
+		hidden: true,
+		index: true
+	}
+];
+/**
+* Wraps the key fields and the setup guide in unnamed tabs, so the wide
+* snippets get the full form width without pushing the key itself out of view.
+* Unnamed on purpose: named tabs would nest the data and move `capabilities`
+* off the document root, which capability resolution reads.
+*
+* The guide tab is conditioned on the update operation. On create there is no
+* key to hand out, and a tab leading to an empty panel is worse than no tab.
+*/ const withSetupGuideTab = (keyFields, options) => {
+	if (!options.setupGuide) return keyFields;
+	return [{
+		type: "tabs",
+		tabs: [{
+			label: "Key",
+			fields: keyFields
+		}, {
+			label: "Connect a client",
+			admin: { condition: (_data, _siblingData, { operation }) => operation === "update" },
+			fields: [{
+				name: SETUP_GUIDE_FIELD,
+				type: "ui",
+				admin: {
+					disableListColumn: true,
+					components: { Field: {
+						path: "@abinnovision/payloadcms-mcpx/client",
+						exportName: "McpxSetupGuide",
+						clientProps: { endpointPath: options.endpointPath }
+					} }
+				}
+			}]
+		}]
+	}];
+};
+/**
+* One checkbox per exposed operation, grouped per collection, per global and
+* per custom tool. Only operations the plugin config exposes get a checkbox, so
+* a key can never enable more than the config allows. Everything defaults to
+* off, which is why a key issued before a capability existed stays closed to it.
+*/ const createCapabilityFields = (options) => {
+	const collectionGroups = options.collections.map((collection) => ({
+		name: collection.fieldName,
+		type: "group",
+		label: collection.slug,
+		fields: [...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [], ...collection.write ? [checkbox("write", "Create, patch and validate drafts.")] : []]
+	}));
+	const globalGroups = options.globals.map((global) => ({
+		name: global.fieldName,
+		type: "group",
+		label: global.slug,
+		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
+	}));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
+	const groups = [
+		...collectionGroups.length > 0 ? [{
+			name: "collections",
+			type: "group",
+			fields: collectionGroups
+		}] : [],
+		...globalGroups.length > 0 ? [{
+			name: "globals",
+			type: "group",
+			fields: globalGroups
+		}] : [],
+		...toolCheckboxes.length > 0 ? [{
+			name: "tools",
+			type: "group",
+			fields: toolCheckboxes
+		}] : []
+	];
+	if (groups.length === 0) return [];
+	return [{
+		name: CAPABILITIES_FIELD,
+		type: "group",
+		admin: { description: "What this key may do. Unchecked means refused, whatever the plugin config allows." },
+		fields: groups
+	}];
+};
+//#endregion
+export { SETUP_GUIDE_FIELD, createCapabilityFields, createKeyFields, withSetupGuideTab };

package/dist/api-keys/key.mjs

@@ -0,0 +1,10 @@
+import crypto from "node:crypto";
+//#region src/api-keys/key.ts
+/**
+* A fresh API key: 32 random bytes, base64url so it is safe in headers.
+*/ const generateApiKey = () => crypto.randomBytes(32).toString("base64url");
+/**
+* Lookup index of a key, the same HMAC Payload core uses for `apiKeyIndex`.
+*/ const hashApiKey = (secret, key) => crypto.createHmac("sha256", secret).update(key).digest("hex");
+//#endregion
+export { generateApiKey, hashApiKey };

package/dist/api-keys/setup-guide.mjs

@@ -0,0 +1,54 @@
+//#region src/api-keys/setup-guide.ts
+const KEY_PLACEHOLDER = "<your-key>";
+/**
+* Server name for the client config. MCP clients key their config by this, so
+* it has to survive labels with spaces or punctuation.
+*/ const toServerName = (label) => {
+	const slug = (label ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug === "" ? "payload" : slug;
+};
+/**
+* The connection instructions for one key, split into independently copyable
+* blocks. Kept a pure builder so the admin component holds only rendering and
+* the snippets stay unit-testable.
+*/ const buildSetupGuide = (input) => {
+	const key = typeof input.apiKey === "string" ? input.apiKey : KEY_PLACEHOLDER;
+	const name = toServerName(input.label);
+	const url = input.endpointUrl;
+	return [
+		{
+			id: "endpoint",
+			title: "Endpoint",
+			description: "Streamable HTTP. Point any MCP client at this URL.",
+			snippet: url
+		},
+		{
+			id: "header",
+			title: "Authorization header",
+			description: "The only accepted credential; cookies and JWTs are ignored.",
+			snippet: `Authorization: Bearer ${key}`
+		},
+		{
+			id: "claude-code",
+			title: "Claude Code",
+			snippet: [`claude mcp add --transport http ${name} ${url} \\`, `  --header "Authorization: Bearer ${key}"`].join("\n")
+		},
+		{
+			id: "claude-desktop",
+			title: "Claude Desktop",
+			description: "Has no direct header support, so it goes through mcp-remote.",
+			snippet: JSON.stringify({ mcpServers: { [name]: {
+				command: "npx",
+				args: [
+					"-y",
+					"mcp-remote",
+					url,
+					"--header",
+					`Authorization: Bearer ${key}`
+				]
+			} } }, null, 2)
+		}
+	];
+};
+//#endregion
+export { KEY_PLACEHOLDER, buildSetupGuide, toServerName };

package/dist/auth/resolve.mjs

@@ -0,0 +1,62 @@
+import { hashApiKey } from "../api-keys/key.mjs";
+//#region src/auth/resolve.ts
+const BEARER = /^Bearer\s+(\S+)\s*$/i;
+const relationId = (value) => {
+	if (typeof value === "string" || typeof value === "number") return value;
+	if (typeof value === "object" && value !== null && "id" in value) return value.id;
+};
+/**
+* The bearer token of an `Authorization` header, or `null`.
+*/ const parseBearer = (headers) => {
+	const header = headers.get("authorization");
+	if (!header) return null;
+	return BEARER.exec(header.trim())?.[1] ?? null;
+};
+/**
+* Resolves the bearer key of a request to the user it acts as.
+*
+* The key is looked up by its HMAC index, the same way Payload resolves its own
+* API keys. A missing, unknown, disabled or orphaned key yields `null`; nothing
+* here throws, so the handler alone decides how a refusal looks.
+*/ const resolveApiKeyAuth = async (req, options) => {
+	const key = parseBearer(req.headers);
+	if (key === null) return null;
+	const { payload } = req;
+	const { docs } = await payload.find({
+		collection: options.apiKeysSlug,
+		where: { apiKeyIndex: { equals: hashApiKey(payload.secret, key) } },
+		limit: 1,
+		pagination: false,
+		depth: 0,
+		overrideAccess: true,
+		select: {
+			enabled: true,
+			user: true,
+			capabilities: true
+		}
+	});
+	const keyDoc = docs[0];
+	const userId = relationId(keyDoc?.user);
+	if (!keyDoc || keyDoc.enabled !== true || userId === void 0) return null;
+	const userCollection = payload.collections[options.userCollection];
+	const user = await payload.findByID({
+		collection: options.userCollection,
+		id: userId,
+		depth: userCollection?.config.auth.depth ?? 0,
+		overrideAccess: true,
+		disableErrors: true
+	});
+	const lockUntil = typeof user?.["lockUntil"] === "string" ? Date.parse(user["lockUntil"]) : NaN;
+	if (!user || user["_verified"] === false || lockUntil > Date.now()) return null;
+	return {
+		user: {
+			...user,
+			collection: options.userCollection,
+			_strategy: "mcpx-api-key"
+		},
+		apiKeyId: keyDoc.id,
+		capabilities: keyDoc.capabilities
+	};
+};
+//#endregion
+export { parseBearer, resolveApiKeyAuth };

package/dist/capabilities.mjs

@@ -0,0 +1,43 @@
+//#region src/capabilities.ts
+/** Name of the capability group on the key document. */ const CAPABILITIES_FIELD = "capabilities";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const flag = (group, name) => isRecord(group) && group[name] === true;
+/**
+* Capabilities in force for a key: the plugin config decides what can exist,
+* the key's checkboxes decide what does. A missing checkbox is `false`, so keys
+* issued before a capability existed stay closed.
+*/ const resolveCapabilities = (options, keyCapabilities) => {
+	const collectionsGroup = isRecord(keyCapabilities) ? keyCapabilities["collections"] : void 0;
+	const globalsGroup = isRecord(keyCapabilities) ? keyCapabilities["globals"] : void 0;
+	const toolsGroup = isRecord(keyCapabilities) ? keyCapabilities["tools"] : void 0;
+	const collections = {};
+	for (const collection of options.collections) {
+		const group = isRecord(collectionsGroup) ? collectionsGroup[collection.fieldName] : void 0;
+		collections[collection.slug] = {
+			read: collection.read && flag(group, "read"),
+			write: collection.write && flag(group, "write")
+		};
+	}
+	const globals = {};
+	for (const global of options.globals) {
+		const group = isRecord(globalsGroup) ? globalsGroup[global.fieldName] : void 0;
+		globals[global.slug] = {
+			read: global.read && flag(group, "read"),
+			write: global.write && flag(group, "write")
+		};
+	}
+	const tools = {};
+	for (const tool of options.tools) tools[tool.name] = flag(toolsGroup, tool.name);
+	return {
+		collections,
+		globals,
+		tools
+	};
+};
+const pick = (entries, operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
+const readableSlugs = (capabilities) => pick(capabilities.collections, "read");
+const writableSlugs = (capabilities) => pick(capabilities.collections, "write");
+const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read");
+const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
+//#endregion
+export { CAPABILITIES_FIELD, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };

package/dist/client/index.d.mts

@@ -0,0 +1,2 @@
+import { McpxSetupGuide } from "./setup-guide.mjs";
+export { McpxSetupGuide };

package/dist/client/index.mjs

@@ -0,0 +1,2 @@
+import { McpxSetupGuide } from "./setup-guide.mjs";
+export { McpxSetupGuide };

package/dist/client/setup-guide.d.mts

@@ -0,0 +1,14 @@
+import React from "react";
+//#region src/client/setup-guide.d.ts
+interface McpxSetupGuideProps {
+  /** Endpoint path below the API route, from the plugin options. */
+  endpointPath: string;
+}
+/**
+ * Per-key connection instructions on the API key edit view. Renders nothing
+ * until the document is saved, because before that there is no key to hand to
+ * a client.
+ */
+declare const McpxSetupGuide: React.FC<McpxSetupGuideProps>;
+//#endregion
+export { McpxSetupGuide };

package/dist/client/setup-guide.mjs

@@ -0,0 +1,87 @@
+"use client";
+import { buildSetupGuide } from "../api-keys/setup-guide.mjs";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { CopyToClipboard, useConfig, useDocumentInfo, useFormFields } from "@payloadcms/ui";
+import { useEffect, useState } from "react";
+//#region src/client/setup-guide.tsx
+const asString = (value) => typeof value === "string" ? value : void 0;
+/**
+* Reads `serverURL` when the config sets one and falls back to the browser's
+* origin. The fallback has to wait for mount: this component is server-rendered
+* first, where `window` does not exist.
+*/ const useOrigin = (serverUrl) => {
+	const [origin, setOrigin] = useState(serverUrl);
+	useEffect(() => {
+		if (serverUrl === "") setOrigin(window.location.origin);
+	}, [serverUrl]);
+	return origin;
+};
+/**
+* Payload's own theme variables, so the panel follows the admin's light and
+* dark themes without shipping a stylesheet consumers would have to transpile.
+*/ const styles = {
+	lead: { marginBottom: "calc(var(--base) * 0.75)" },
+	section: { marginBottom: "calc(var(--base) * 0.75)" },
+	sectionHeader: {
+		display: "flex",
+		alignItems: "center",
+		gap: "calc(var(--base) * 0.25)"
+	},
+	description: {
+		margin: "calc(var(--base) * 0.15) 0",
+		color: "var(--theme-elevation-500)"
+	},
+	snippet: {
+		margin: 0,
+		padding: "calc(var(--base) * 0.4)",
+		background: "var(--theme-elevation-50)",
+		border: "1px solid var(--theme-elevation-150)",
+		borderRadius: "3px",
+		fontFamily: "var(--font-mono)",
+		overflowX: "auto",
+		whiteSpace: "pre-wrap",
+		wordBreak: "break-all"
+	}
+};
+/**
+* Per-key connection instructions on the API key edit view. Renders nothing
+* until the document is saved, because before that there is no key to hand to
+* a client.
+*/ const McpxSetupGuide = ({ endpointPath }) => {
+	const { id } = useDocumentInfo();
+	const { config } = useConfig();
+	const apiKey = useFormFields(([fields]) => fields["apiKey"]?.value);
+	const label = useFormFields(([fields]) => fields["label"]?.value);
+	const origin = useOrigin(config.serverURL);
+	if (id === void 0) return null;
+	const sections = buildSetupGuide({
+		endpointUrl: `${origin.replace(/\/+$/, "")}${config.routes.api}${endpointPath}`,
+		apiKey: asString(apiKey),
+		label: asString(label)
+	});
+	return /*#__PURE__*/ jsxs("div", {
+		className: "field-type",
+		children: [/*#__PURE__*/ jsx("p", {
+			style: styles.lead,
+			children: "Every snippet below contains this key in full. Treat it like a password."
+		}), sections.map((section) => /*#__PURE__*/ jsxs("section", {
+			style: styles.section,
+			children: [
+				/*#__PURE__*/ jsxs("div", {
+					style: styles.sectionHeader,
+					children: [/*#__PURE__*/ jsx("strong", { children: section.title }), /*#__PURE__*/ jsx(CopyToClipboard, { value: section.snippet })]
+				}),
+				section.description ? /*#__PURE__*/ jsx("p", {
+					style: styles.description,
+					children: section.description
+				}) : null,
+				/*#__PURE__*/ jsx("pre", {
+					style: styles.snippet,
+					children: section.snippet
+				})
+			]
+		}, section.id))]
+	});
+};
+//#endregion
+export { McpxSetupGuide };

package/dist/endpoint/handler.mjs

@@ -0,0 +1,86 @@
+import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
+import { resolveApiKeyAuth } from "../auth/resolve.mjs";
+import { jsonRpcError } from "./result.mjs";
+import { createMcpServer } from "./server.mjs";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+//#region src/endpoint/handler.ts
+const buildScope = (req, options, capabilities) => {
+	const { localization } = req.payload.config;
+	return {
+		req,
+		options,
+		capabilities,
+		readable: readableSlugs(capabilities),
+		writable: writableSlugs(capabilities),
+		readableGlobals: readableGlobalSlugs(capabilities),
+		writableGlobals: writableGlobalSlugs(capabilities),
+		locales: localization ? localization.localeCodes : null,
+		defaultLocale: localization ? localization.defaultLocale : null
+	};
+};
+/**
+* Answers GET and DELETE on the endpoint path. The server is stateless and
+* never streams, so only POST carries meaning.
+*/ const methodNotAllowed = () => jsonRpcError({
+	status: 405,
+	code: -32e3,
+	message: "Method not allowed. MCP requests must use POST.",
+	headers: { allow: "POST" }
+});
+/**
+* The MCP endpoint. Authenticates the bearer key, sets `req.user` and the
+* request marker, then serves the JSON-RPC body with a fresh server and
+* transport. Any user Payload resolved from cookies or a JWT is ignored: only
+* an API key authenticates here.
+*/ const createMcpxHandler = (options) => async (req) => {
+	const resolveDefault = () => resolveApiKeyAuth(req, options);
+	const auth = options.auth?.resolve ? await options.auth.resolve({
+		req,
+		resolveDefault
+	}) : await resolveDefault();
+	if (!auth) return jsonRpcError({
+		status: 401,
+		code: -32001,
+		message: "Unauthorized: a valid API key is required.",
+		headers: { "www-authenticate": "Bearer" }
+	});
+	const capabilities = resolveCapabilities(options, auth.capabilities);
+	req.user = auth.user;
+	req.context = {
+		...req.context,
+		mcpx: {
+			apiKeyId: auth.apiKeyId,
+			capabilities
+		}
+	};
+	let parsedBody;
+	try {
+		parsedBody = await req.json?.();
+	} catch {
+		return jsonRpcError({
+			status: 400,
+			code: -32700,
+			message: "Parse error: Invalid JSON"
+		});
+	}
+	if (parsedBody === void 0 || req.url === void 0) return jsonRpcError({
+		status: 400,
+		code: -32600,
+		message: "Invalid request: a JSON body is required."
+	});
+	const server = createMcpServer(buildScope(req, options, capabilities));
+	const transport = new WebStandardStreamableHTTPServerTransport({ enableJsonResponse: true });
+	await server.connect(transport);
+	const headers = new Headers(req.headers);
+	headers.set("accept", "application/json, text/event-stream");
+	try {
+		return await transport.handleRequest(new Request(req.url, {
+			method: "POST",
+			headers
+		}), { parsedBody });
+	} finally {
+		await server.close();
+	}
+};
+//#endregion
+export { createMcpxHandler, methodNotAllowed };

package/dist/endpoint/result.mjs

@@ -0,0 +1,65 @@
+import { pointerFromPayloadPath } from "../schema/walk.mjs";
+import { APIError, ValidationError } from "payload";
+//#region src/endpoint/result.ts
+/**
+* A JSON-RPC error response for failures that happen before the MCP server
+* is involved (auth, method, body parsing).
+*/ const jsonRpcError = (args) => {
+	const headers = new Headers(args.headers);
+	headers.set("content-type", "application/json");
+	return new Response(JSON.stringify({
+		jsonrpc: "2.0",
+		id: null,
+		error: {
+			code: args.code,
+			message: args.message
+		}
+	}), {
+		status: args.status,
+		headers
+	});
+};
+/**
+* A successful tool result carrying `value` as JSON text.
+*/ const jsonResult = (value) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(value)
+}] });
+/**
+* A failed tool result. `extras` travel alongside the message so the client
+* can act on them (problems, validation errors, the current `updatedAt`).
+*/ const errorResult = (message, extras = {}) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extras
+		})
+	}],
+	isError: true
+});
+/**
+* Maps an exception thrown by a tool to a result the client can read.
+*
+* Payload's public errors keep their message and status; a `ValidationError`
+* also surfaces its per-field detail, with each field's path restated as a
+* JSON Pointer so it reads like every other path this plugin reports. Anything
+* else is logged and reported as an internal error so no stack or driver
+* message leaks to the client.
+*/ const toToolError = (error, logger) => {
+	if (error instanceof ValidationError) return errorResult(error.message, {
+		status: error.status,
+		validationErrors: error.data.errors.map((entry) => ({
+			...entry,
+			path: pointerFromPayloadPath(entry.path)
+		}))
+	});
+	if (error instanceof APIError && error.isPublic) return errorResult(error.message, { status: error.status });
+	logger.error({
+		err: error,
+		msg: "[payloadcms-mcpx] Tool call failed."
+	});
+	return errorResult("Internal error");
+};
+//#endregion
+export { errorResult, jsonResult, jsonRpcError, toToolError };

package/dist/endpoint/server.mjs

@@ -0,0 +1,52 @@
+import { toToolError } from "./result.mjs";
+import { BUILTIN_TOOLS } from "../tools/index.mjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+//#region src/endpoint/server.ts
+/**
+* Builds a builtin tool's input schema as a strict object, so an unknown
+* argument is rejected with its name instead of being silently stripped and
+* the tool answering as if it had not been passed.
+*/ const builtinInputSchema = (tool, scope) => z.strictObject(tool.inputSchema(scope));
+/**
+* Builds the MCP server for one request. Tools are registered against the
+* key's capabilities, so `tools/list` shows exactly what the key may call and
+* every `collection` enum is limited to what it may touch.
+*/ const createMcpServer = (scope) => {
+	const { req, options, capabilities } = scope;
+	const { logger } = req.payload;
+	const server = new McpServer({
+		name: options.serverInfo.name,
+		version: options.serverInfo.version
+	}, { instructions: "Start with listCapabilities, then describeSchema for the collection or global you work on. Writes always land as drafts; a human publishes." });
+	const guarded = (run) => async () => {
+		try {
+			return await run();
+		} catch (error) {
+			return toToolError(error, logger);
+		}
+	};
+	for (const tool of BUILTIN_TOOLS) {
+		if (!tool.isEnabled(scope)) continue;
+		server.registerTool(tool.name, {
+			description: tool.description,
+			inputSchema: builtinInputSchema(tool, scope),
+			annotations: tool.annotations
+		}, (args) => guarded(() => tool.handler(args, scope))());
+	}
+	for (const tool of options.tools) {
+		if (capabilities.tools[tool.name] !== true) continue;
+		server.registerTool(tool.name, {
+			description: tool.description,
+			inputSchema: tool.inputSchema ?? {},
+			...tool.annotations ? { annotations: tool.annotations } : {}
+		}, (args, extra) => guarded(() => tool.handler({
+			args,
+			req,
+			extra
+		}))());
+	}
+	return server;
+};
+//#endregion
+export { builtinInputSchema, createMcpServer };

package/dist/i18n.d.mts

@@ -0,0 +1 @@
+import { PayloadRequest } from "payload";

package/dist/i18n.mjs

@@ -0,0 +1,40 @@
+//#region src/i18n.ts
+/**
+* A locale-keyed record, once it is known to hold nothing but strings.
+*/ const stringRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string") ? value : void 0;
+/**
+* Picks the entry a language addresses, treating an empty value as absent so
+* the chain continues rather than yielding a useless string.
+*/ const pick = (record, language) => {
+	for (const code of Array.isArray(language) ? language : [language]) {
+		const entry = record[code];
+		if (entry !== void 0 && entry.trim() !== "") return entry;
+	}
+};
+/**
+* Resolves a static label or `admin.description` to the one string a client
+* can use: the request's language, then the fallback language configured for
+* the deployment, then whichever entry the record declares first.
+*
+* Anything that is not a string or a string-valued record is dropped. A
+* description written as a function or a React component is an admin-UI
+* construct that may reach client-only i18n, so it is never invoked here.
+*/ const translateStatic = (value, language) => {
+	if (typeof value === "string") return value.trim() === "" ? void 0 : value;
+	const record = stringRecord(value);
+	if (!record) return;
+	return pick(record, language.language) ?? pick(record, language.fallbackLanguage) ?? Object.values(record).find((entry) => entry.trim() !== "");
+};
+/**
+* Binds {@link translateStatic} to a request's language, so a walk that
+* resolves many descriptions carries no request of its own.
+*/ const translatorFor = (i18n) => (value) => translateStatic(value, i18n);
+/**
+* Translator for callers with no request in hand. Both language keys miss, so
+* the chain degrades to the record's first entry.
+*/ const translateAny = translatorFor({
+	fallbackLanguage: "",
+	language: ""
+});
+//#endregion
+export { translateAny, translateStatic, translatorFor };

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { mcpxPlugin } from "./plugin.mjs";
+import { isMcpxRequest } from "./write/draft-guard.mjs";
+import { PublishBlocker } from "./write/publish-blockers.mjs";
+export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { isMcpxRequest } from "./write/draft-guard.mjs";
+import { mcpxPlugin } from "./plugin.mjs";
+import { defineMcpxTool } from "./types.mjs";
+export { defineMcpxTool, isMcpxRequest, mcpxPlugin };