emdash 0.39.1 → 0.40.1

package/src/mcp/server.ts

@@ -21,9 +21,11 @@ import {
 	CONTENT_TYPE_RE,
 	contentBylineInputSchema,
 	contentSeoInput,
+	createBlockTypeBody,
 	createCollectionBody,
 	createTaxonomyDefBody,
 	updateCollectionBody,
+	updateBlockTypeBody,
 	updateFieldBody,
 	updateTaxonomyDefBody,
 } from "#api/schemas.js";
@@ -36,7 +38,27 @@ import { convertDataForRead, convertDataForWrite } from "../client/portable-text
 import type { FieldSchema } from "../client/portable-text.js";
 import { decodeCursor, InvalidCursorError } from "../database/repositories/types.js";
 import type { RouteCallerInput } from "../plugins/routes.js";
+import {
+	TRANSFER_SCOPES,
+	type TransferApprovalAction,
+	type TransferScope,
+} from "../transfer/auth.js";
+import { readSiteWriteFence, recordSiteWrite } from "../transfer/fence.js";
+import { toSha256Digest } from "../transfer/format/digest.js";
+import { siteImportDecisionsInputSchema } from "../transfer/format/plan.js";
 import { decodeBase64, encodeBase64 } from "../utils/base64.js";
+import {
+	analyzeImport,
+	exportStatus,
+	hasOperationGrant,
+	importReceipt,
+	importStatus,
+	resumeImport,
+	startExport,
+	startImport,
+	transferCapabilities,
+	type TransferContext,
+} from "./transfer.js";
 
 const COLLECTION_SLUG_PATTERN = /^[a-z][a-z0-9_]*$/;
 /** http(s) scheme matcher used by `settings_update` URL validation. */
@@ -58,6 +80,43 @@ const REV_PARAM_DESCRIPTION =
 const REV_MISSING_ERROR =
 	"_rev is required: call content_get for this item and pass back the _rev it returns.";
 
+const SHA256_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const TRANSFER_OPERATION_ID_PATTERN = /^[0-9A-Za-z_-]{1,64}$/;
+
+const transferOperationIdSchema = z
+	.string()
+	.regex(TRANSFER_OPERATION_ID_PATTERN, "Invalid operation id")
+	.describe("Transfer operation id");
+
+const transferApprovalIdSchema = z
+	.string()
+	.min(1)
+	.max(64)
+	.describe("Approval id from an earlier TRANSFER_APPROVAL_REQUIRED error, once approved");
+
+/**
+ * The site transfer tools. Like the transfer REST API they are exempt from
+ * the site write fence, so an import started over MCP can be driven to
+ * completion over MCP.
+ */
+const TRANSFER_TOOL_NAMES: ReadonlySet<string> = new Set([
+	"site_transfer_capabilities",
+	"site_export_start",
+	"site_export_status",
+	"site_import_analyze",
+	"site_import_start",
+	"site_import_status",
+	"site_import_resume",
+	"site_import_receipt",
+]);
+
+const APPROVAL_FLOW_DESCRIPTION =
+	"If the token lacks the scope, the first call fails with TRANSFER_APPROVAL_REQUIRED and " +
+	"details.approvalId; an admin must approve that request in the EmDash admin " +
+	"(Settings → Transfer). Then repeat the call with the same arguments plus approvalId. " +
+	"Approvals are single-use, bound to this user, this token, and these exact arguments, " +
+	"and expire 15 minutes after they are requested or approved.";
+
 const TAXONOMY_CURSOR_VERSION = 2;
 const MAX_TAXONOMY_CURSOR_LENGTH = 2048;
 const contentDateTimeInputSchema = z.iso
@@ -97,8 +156,9 @@ const settingsSeoSchema = z.object({
 		.optional()
 		.describe("Separator between page title and site title (e.g. ' | ')"),
 	defaultOgImage: settingsMediaReferenceSchema
+		.nullable()
 		.optional()
-		.describe("Default Open Graph image when content has none"),
+		.describe("Default Open Graph image when content has none; null removes it"),
 	robotsTxt: z
 		.string()
 		.max(5000)
@@ -465,6 +525,8 @@ interface EmDashExtra {
 	userRole: RoleLevel;
 	/** Token scopes — undefined for session auth (all access allowed). */
 	tokenScopes?: string[];
+	/** Id of the API or OAuth token the caller authenticated with. */
+	tokenId?: string;
 	/** The route cache of the MCP request, used to invalidate the same tags the REST routes do. */
 	cache?: APIContext["cache"];
 }
@@ -514,8 +576,9 @@ async function getCollectionFields(
 ): Promise<FieldSchema[] | null> {
 	try {
 		const { SchemaRegistry } = await import("../schema/index.js");
+		const { expandCollectionBlockFields } = await import("../schema/block-values.js");
 		const col = await new SchemaRegistry(ec.db).getCollectionWithFields(collection);
-		return col ? col.fields : null;
+		return col ? (await expandCollectionBlockFields(ec.db, col)).fields : null;
 	} catch {
 		return null;
 	}
@@ -603,6 +666,61 @@ function requireRole(
 	}
 }
 
+type TransferScopeRequirement = TransferScope | "transfer:*";
+
+/**
+ * Whether the caller's token holds `scope` (`transfer:*`: any transfer
+ * scope). A caller without token scopes holds none.
+ */
+function transferScopeHeld(
+	extra: { authInfo?: { extra?: Record<string, unknown> } },
+	scope: TransferScopeRequirement,
+): boolean {
+	const { tokenScopes } = getExtra(extra);
+	if (!tokenScopes) return false;
+	if (scope === "transfer:*") return TRANSFER_SCOPES.some((held) => hasScope(tokenScopes, held));
+	return hasScope(tokenScopes, scope);
+}
+
+function insufficientTransferScope(scope: TransferScopeRequirement): EmDashAuthError {
+	const required = scope === "transfer:*" ? TRANSFER_SCOPES.join(" or ") : scope;
+	return new EmDashAuthError(`Insufficient scope: requires ${required}`, "INSUFFICIENT_SCOPE");
+}
+
+function requireTransferScope(
+	extra: { authInfo?: { extra?: Record<string, unknown> } },
+	scope: TransferScopeRequirement,
+): void {
+	if (!transferScopeHeld(extra, scope)) throw insufficientTransferScope(scope);
+}
+
+/**
+ * Require `scope`, or a grant this user consumed with this token to start
+ * `operationId`.
+ */
+async function requireTransferAccess(
+	extra: { authInfo?: { extra?: Record<string, unknown> } },
+	scope: TransferScopeRequirement,
+	action: TransferApprovalAction,
+	operationId: string,
+): Promise<void> {
+	if (transferScopeHeld(extra, scope)) return;
+	const { emdash, userId, tokenId } = getExtra(extra);
+	if (await hasOperationGrant(emdash.db, { userId, tokenId }, action, operationId)) return;
+	throw insufficientTransferScope(scope);
+}
+
+function transferContext(extra: {
+	authInfo?: { extra?: Record<string, unknown> };
+}): TransferContext {
+	const { emdash } = getExtra(extra);
+	return { db: emdash.db, storage: emdash.storage, maxUploadSize: emdash.config.maxUploadSize };
+}
+
+function transferDigest(value: string) {
+	return toSha256Digest(value.slice("sha256:".length));
+}
+
 /**
  * Whether the current user may read non-published content (drafts, scheduled,
  * trashed, revisions, compare). SUBSCRIBER may hold content:read for
@@ -715,20 +833,38 @@ export function createMcpServer(
 	// surface as structured `_meta.code`-bearing tool error envelopes
 	// instead of the SDK's text-only fallback in createToolError().
 	//
+	// The wrapper also applies the site write fence. Every MCP request is a
+	// POST, so the fence middleware leaves the endpoint to this per-tool
+	// check: every tool is fenced unless it is annotated `readOnlyHint: true`
+	// or is a transfer tool. A tool annotated read-only must never write.
+	//
 	// Type-erased on purpose — the SDK's overloads are too narrow for a
 	// generic wrapper, but the runtime contract (callback returns the tool
 	// result envelope) holds for every registered tool.
 	const originalRegisterTool = server.registerTool.bind(server);
 	(server as { registerTool: typeof server.registerTool }).registerTool = ((
 		name: string,
-		config: unknown,
+		config: { annotations?: { readOnlyHint?: boolean } },
 		callback: (...callbackArgs: unknown[]) => Promise<SuccessEnvelope | ErrorEnvelope>,
 	) => {
+		const fenced = config.annotations?.readOnlyHint !== true && !TRANSFER_TOOL_NAMES.has(name);
 		const wrapped = async (
 			...callbackArgs: unknown[]
 		): Promise<SuccessEnvelope | ErrorEnvelope> => {
 			try {
-				return await callback(...callbackArgs);
+				if (!fenced) return await callback(...callbackArgs);
+				// The SDK passes the request extra as the last callback argument.
+				const extra = callbackArgs.at(-1) as { authInfo?: { extra?: Record<string, unknown> } };
+				const { db } = getEmDash(extra);
+				const fence = await readSiteWriteFence(db);
+				if (fence.error) return respondError(fence.error.code, fence.error.message);
+				const result = await callback(...callbackArgs);
+				// Recorded after the write so an export whose fence was captured
+				// while this tool ran still sees it.
+				if (fence.exportRunning && !("isError" in result && result.isError)) {
+					await recordSiteWrite(db);
+				}
+				return result;
 			} catch (error) {
 				return respondHandlerError(error, "INTERNAL_ERROR");
 			}
@@ -984,6 +1120,14 @@ export function createMcpServer(
 					.describe(
 						"ID of the content item this is a translation of. Links items in the same translation group.",
 					),
+				migrateBlocks: z
+					.boolean()
+					.optional()
+					.describe("Allow retained blocks to migrate to their type's active version"),
+				replaceBlocks: z
+					.boolean()
+					.optional()
+					.describe("Treat an entirely keyless blocks array as an explicit replacement"),
 				bylines: z
 					.array(contentBylineInputSchema)
 					.optional()
@@ -1036,6 +1180,8 @@ export function createMcpServer(
 					translationOf: args.translationOf,
 					bylines: args.bylines,
 					taxonomies: args.taxonomies,
+					migrateBlocks: args.migrateBlocks,
+					replaceBlocks: args.replaceBlocks,
 					actor,
 				});
 				if (!result.success) return unwrap(result);
@@ -1064,6 +1210,8 @@ export function createMcpServer(
 					translationOf: args.translationOf,
 					bylines: args.bylines,
 					taxonomies: args.taxonomies,
+					migrateBlocks: args.migrateBlocks,
+					replaceBlocks: args.replaceBlocks,
 					actor,
 				}),
 				[args.collection],
@@ -1136,6 +1284,14 @@ export function createMcpServer(
 					.describe(
 						"Override the publication timestamp (ISO 8601). Requires content:publish_any permission. Pass null to clear. Useful for content migrations.",
 					),
+				migrateBlocks: z
+					.boolean()
+					.optional()
+					.describe("Allow existing blocks to migrate to their type's active version"),
+				replaceBlocks: z
+					.boolean()
+					.optional()
+					.describe("Treat an entirely keyless blocks array as an explicit replacement"),
 				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
 			}),
 		},
@@ -1194,6 +1350,8 @@ export function createMcpServer(
 						bylines: args.bylines,
 						taxonomies: args.taxonomies,
 						publishedAt: args.publishedAt,
+						migrateBlocks: args.migrateBlocks,
+						replaceBlocks: args.replaceBlocks,
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
@@ -1233,6 +1391,8 @@ export function createMcpServer(
 						bylines: args.bylines,
 						taxonomies: args.taxonomies,
 						publishedAt: args.publishedAt,
+						migrateBlocks: args.migrateBlocks,
+						replaceBlocks: args.replaceBlocks,
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
@@ -1260,6 +1420,8 @@ export function createMcpServer(
 				bylines: args.bylines,
 				taxonomies: args.taxonomies,
 				publishedAt: args.publishedAt,
+				migrateBlocks: args.migrateBlocks,
+				replaceBlocks: args.replaceBlocks,
 				_rev: args._rev,
 			});
 			if (result.liveContentChanged === false) return unwrap(result);
@@ -1665,10 +1827,21 @@ export function createMcpServer(
 		async (args, extra) => {
 			requireScope(extra, "content:write");
 			requireRole(extra, Role.CONTRIBUTOR);
-			const ec = getEmDash(extra);
-			return unwrapAndInvalidate(extra, await ec.handleContentDuplicate(args.collection, args.id), [
-				args.collection,
-			]);
+			const { emdash, userId } = getExtra(extra);
+			const existing = await emdash.handleContentGet(args.collection, args.id);
+			if (!existing.success) return unwrap(existing);
+			requireOwnership(
+				extra,
+				extractContentAuthorId(existing.data),
+				"content:edit_own",
+				"content:edit_any",
+			);
+			const resolvedId = extractContentId(existing.data) ?? args.id;
+			return unwrapAndInvalidate(
+				extra,
+				await emdash.handleContentDuplicate(args.collection, resolvedId, userId),
+				[args.collection],
+			);
 		},
 	);
 
@@ -1925,7 +2098,8 @@ export function createMcpServer(
 				"Get detailed info about a collection including all field definitions. " +
 				"Fields describe the data model: name, type (string, text, number, " +
 				"boolean, datetime, portableText, image, reference, json, select, " +
-				"multiSelect, slug), constraints, and validation rules. Use this to " +
+				"multiSelect, slug, blocks), constraints, and validation rules. Blocks fields " +
+				"include every allowed and retired block type version. Use this to " +
 				"understand what data content_create and content_update expect.",
 			inputSchema: z.object({
 				slug: z
@@ -1941,19 +2115,114 @@ export function createMcpServer(
 			requireRole(extra, Role.EDITOR);
 			const ec = getEmDash(extra);
 			try {
-				const { SchemaRegistry } = await import("../schema/index.js");
+				const { SchemaRegistry, expandCollectionBlockFields } = await import("../schema/index.js");
 				const registry = new SchemaRegistry(ec.db);
 				const collection = await registry.getCollectionWithFields(args.slug);
 				if (!collection) {
 					return respondError("NOT_FOUND", `Collection '${args.slug}' not found`);
 				}
-				return jsonResult(collection);
+				return jsonResult(await expandCollectionBlockFields(ec.db, collection));
 			} catch (error) {
 				return respondHandlerError(error, "SCHEMA_GET_ERROR");
 			}
 		},
 	);
 
+	server.registerTool(
+		"schema_list_block_types",
+		{
+			title: "List Block Types",
+			description: "List every database-owned block type and all retained versions.",
+			inputSchema: z.object({}),
+			annotations: { readOnlyHint: true },
+		},
+		async (_args, extra) => {
+			requireScope(extra, "schema:read");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			const { handleBlockTypeList } = await import("../api/handlers/block-types.js");
+			return unwrap(await handleBlockTypeList(ec.db));
+		},
+	);
+
+	server.registerTool(
+		"schema_get_block_type",
+		{
+			title: "Get Block Type",
+			description: "Get one block type, including active, inactive, and historical versions.",
+			inputSchema: z.object({ slug: z.string().describe("Block type slug") }),
+			annotations: { readOnlyHint: true },
+		},
+		async (args, extra) => {
+			requireScope(extra, "schema:read");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			const { handleBlockTypeGet } = await import("../api/handlers/block-types.js");
+			return unwrap(await handleBlockTypeGet(ec.db, args.slug));
+		},
+	);
+
+	server.registerTool(
+		"schema_create_block_type",
+		{
+			title: "Create Block Type",
+			description: "Create a block type with active version 1.",
+			inputSchema: z.object(createBlockTypeBody.shape),
+		},
+		async (args, extra) => {
+			requireScope(extra, "schema:write");
+			requireRole(extra, Role.ADMIN);
+			const ec = getEmDash(extra);
+			const { handleBlockTypeCreate } = await import("../api/handlers/block-types.js");
+			return unwrap(await handleBlockTypeCreate(ec.db, args));
+		},
+	);
+
+	server.registerTool(
+		"schema_update_block_type",
+		{
+			title: "Update Block Type",
+			description:
+				"Update presentation or compatible fields in place. Set breaking to create an inactive retained version.",
+			inputSchema: z.object({ slug: z.string(), ...updateBlockTypeBody.shape }),
+		},
+		async (args, extra) => {
+			requireScope(extra, "schema:write");
+			requireRole(extra, Role.ADMIN);
+			const ec = getEmDash(extra);
+			const { slug, ...input } = args;
+			const { handleBlockTypeUpdate } = await import("../api/handlers/block-types.js");
+			return unwrap(await handleBlockTypeUpdate(ec.db, slug, input));
+		},
+	);
+
+	server.registerTool(
+		"schema_activate_block_type_version",
+		{
+			title: "Activate Block Type Version",
+			description: "Make a retained version the active version used by newly created blocks.",
+			inputSchema: z.object({
+				slug: z.string(),
+				version: z.number().int().positive(),
+				expectedFingerprint: z.string().min(1),
+			}),
+		},
+		async (args, extra) => {
+			requireScope(extra, "schema:write");
+			requireRole(extra, Role.ADMIN);
+			const ec = getEmDash(extra);
+			const { handleBlockTypeVersionActivate } = await import("../api/handlers/block-types.js");
+			return unwrap(
+				await handleBlockTypeVersionActivate(
+					ec.db,
+					args.slug,
+					args.version,
+					args.expectedFingerprint,
+				),
+			);
+		},
+	);
+
 	server.registerTool(
 		"schema_create_collection",
 		{
@@ -2084,7 +2353,7 @@ export function createMcpServer(
 				"database table. Field types: string (short text), text (long text), " +
 				"number (decimal), integer, boolean, datetime, select (single choice), " +
 				"multiSelect (multiple), portableText (rich text), image, file, " +
-				"reference (link to another collection), json, slug (URL-safe id). " +
+				"reference (link to another collection), json, slug (URL-safe id), or blocks. " +
 				"For select/multiSelect, provide choices in validation.options array.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug to add the field to"),
@@ -2109,6 +2378,7 @@ export function createMcpServer(
 						"reference",
 						"json",
 						"slug",
+						"blocks",
 					])
 					.describe("Data type for this field"),
 				required: z.boolean().optional().describe("Whether the field is required (default false)"),
@@ -2125,6 +2395,12 @@ export function createMcpServer(
 							.array(z.string())
 							.optional()
 							.describe("Allowed values for select/multiSelect"),
+						allowedTypes: z
+							.array(z.string())
+							.optional()
+							.describe("Ordered block type slugs allowed by a blocks field"),
+						minItems: z.number().int().min(0).optional(),
+						maxItems: z.number().int().min(1).optional(),
 					})
 					.optional()
 					.describe("Validation constraints"),
@@ -2271,27 +2547,15 @@ export function createMcpServer(
 	server.registerTool(
 		"media_create",
 		{
-			title: "Register Uploaded Media",
+			title: "Confirm Signed Media Upload",
 			description:
-				"Register a media file that has already been uploaded to storage. The " +
-				"caller is responsible for placing the file at `storageKey` (typically " +
-				"using a signed upload URL obtained from the admin UI or a separate API). " +
-				"This tool persists the metadata record so the file is discoverable via " +
-				"media_list / media_get and can be referenced by content. To upload the " +
-				"file itself, use media_upload (base64 data or a public URL) instead.",
+				"Confirm a file after uploading it with a signed URL obtained from " +
+				"POST /_emdash/api/media/upload-url. `storageKey` must be the key returned " +
+				"for the same user. Confirmation checks that the stored file exists and " +
+				"matches the size fixed when the URL was issued, then makes it available " +
+				"through media_list / media_get. To upload through MCP, use media_upload instead.",
 			inputSchema: z.object({
-				filename: z.string().describe("Original filename (e.g. 'logo.png')"),
-				mimeType: z.string().describe("MIME type (e.g. 'image/png')"),
-				storageKey: z.string().describe("Storage path/key the file was uploaded to"),
-				size: z.number().int().nonnegative().optional().describe("File size in bytes"),
-				width: z.number().int().positive().optional().describe("Image width in pixels"),
-				height: z.number().int().positive().optional().describe("Image height in pixels"),
-				contentHash: z.string().optional().describe("Hash of the file contents (for dedupe)"),
-				blurhash: z.string().optional().describe("Blurhash for image placeholders"),
-				dominantColor: z
-					.string()
-					.optional()
-					.describe("Hex color string for the image's dominant color"),
+				storageKey: z.string().describe("Storage key returned by the signed upload URL request"),
 			}),
 		},
 		async (args, extra) => {
@@ -2299,16 +2563,8 @@ export function createMcpServer(
 			requireRole(extra, Role.AUTHOR);
 			const { emdash, userId } = getExtra(extra);
 			return unwrap(
-				await emdash.handleMediaCreate({
-					filename: args.filename,
-					mimeType: args.mimeType,
+				await emdash.handleMediaRegisterUpload({
 					storageKey: args.storageKey,
-					size: args.size,
-					width: args.width,
-					height: args.height,
-					contentHash: args.contentHash,
-					blurhash: args.blurhash,
-					dominantColor: args.dominantColor,
 					authorId: userId,
 				}),
 			);
@@ -2320,34 +2576,20 @@ export function createMcpServer(
 		{
 			title: "Upload Media",
 			description:
-				"Upload a media file from base64-encoded data or an external URL and " +
+				"Upload a media file from base64-encoded data and " +
 				"register it in the media library. Returns the media item with id, " +
 				"storageKey, and url — ready to reference from content fields (e.g. " +
 				"featured_image) via content_create / content_update. Uploads are " +
 				"deduplicated by content hash: re-uploading identical bytes returns " +
-				"the existing item with deduplicated: true. URL fetches must resolve " +
-				"to a public http(s) host (SSRF-guarded). Subject to the global " +
+				"the existing item with deduplicated: true. Subject to the global " +
 				"upload MIME allowlist and the configured maximum upload size.",
 			inputSchema: z.object({
 				filename: z.string().min(1).describe("Filename including extension (e.g. 'cover.png')"),
-				base64: z
-					.string()
-					.optional()
-					.describe("Base64-encoded file contents. Provide exactly one of base64 / url."),
-				url: z
-					.url()
-					.optional()
-					.describe(
-						"Public http(s) URL to fetch the file from. Provide exactly one of base64 / url.",
-					),
+				base64: z.string().describe("Base64-encoded file contents."),
 				contentType: z
 					.string()
 					.regex(CONTENT_TYPE_RE, "Invalid content type")
-					.optional()
-					.describe(
-						"MIME type (e.g. 'image/png'). Required with base64; with url it " +
-							"defaults to the response's Content-Type header.",
-					),
+					.describe("MIME type (e.g. 'image/png')."),
 				alt: z.string().optional().describe("Alt text for accessibility"),
 			}),
 			annotations: { destructiveHint: false },
@@ -2364,7 +2606,6 @@ export function createMcpServer(
 					await emdash.handleMediaUpload({
 						filename: args.filename,
 						base64: args.base64,
-						url: args.url,
 						contentType: args.contentType,
 						alt: args.alt,
 						authorId: userId,
@@ -2620,12 +2861,13 @@ export function createMcpServer(
 		{
 			title: "Create Taxonomy Definition",
 			description:
-				"Create a new taxonomy definition. Definitions are per-locale; pass " +
-				"`locale` when the same taxonomy name exists in multiple translations. " +
-				"`collections` names which content types the taxonomy applies to. " +
-				"If `translationOf` is set, the new definition joins the source's " +
-				"translation group and inherits `hierarchical` and `collections` from " +
-				"the source when those fields are omitted.",
+				"Create a taxonomy definition in one locale. `label` and `labelSingular` " +
+				"belong to that locale; `hierarchical` and `collections` belong to the " +
+				"taxonomy and are the same in every locale. `collections` names which " +
+				"content types the taxonomy applies to. A definition for a name that " +
+				"already exists in another locale joins that taxonomy and takes its " +
+				"`hierarchical` and `collections`; passing different values is an error " +
+				"(change them with taxonomy_update).",
 			inputSchema: z.object({
 				name: createTaxonomyDefBody.shape.name.describe(
 					"Taxonomy name (lowercase letters, numbers, underscores)",
@@ -2635,10 +2877,10 @@ export function createMcpServer(
 					"Singular form of the display name",
 				),
 				hierarchical: createTaxonomyDefBody.shape.hierarchical.describe(
-					"Whether the taxonomy supports parent/child terms (defaults to false, or inherited from translationOf)",
+					"Whether the taxonomy supports parent/child terms, in every locale (defaults to false; must match when the taxonomy exists in another locale)",
 				),
 				collections: createTaxonomyDefBody.shape.collections.describe(
-					"Collection slugs this taxonomy applies to (defaults to [], or inherited from translationOf)",
+					"Collection slugs this taxonomy applies to, in every locale (defaults to []; must match when the taxonomy exists in another locale)",
 				),
 				locale: z.string().optional().describe("Locale for this definition (e.g. 'fr-fr')"),
 				translationOf: z
@@ -2678,9 +2920,10 @@ export function createMcpServer(
 			title: "Update Taxonomy Definition",
 			description:
 				"Update an existing taxonomy definition. The taxonomy `name` cannot be " +
-				"changed. Pass `locale` to update a specific translation; otherwise the " +
-				"lowest matching locale is updated. Any field may be omitted to leave it " +
-				"unchanged.",
+				"changed. Pass `locale` to update a specific translation's `label` and " +
+				"`labelSingular`; otherwise the lowest matching locale is updated. " +
+				"`hierarchical` and `collections` change for every locale. Any field " +
+				"may be omitted to leave it unchanged.",
 			inputSchema: z.object({
 				name: z.string().describe("Taxonomy name to update"),
 				label: updateTaxonomyDefBody.shape.label.describe("New display name"),
@@ -2688,10 +2931,10 @@ export function createMcpServer(
 					"New singular display name; pass null to clear",
 				),
 				hierarchical: updateTaxonomyDefBody.shape.hierarchical.describe(
-					"Whether the taxonomy supports parent/child terms",
+					"Whether the taxonomy supports parent/child terms, in every locale",
 				),
 				collections: updateTaxonomyDefBody.shape.collections.describe(
-					"Collection slugs this taxonomy applies to",
+					"Collection slugs this taxonomy applies to, in every locale",
 				),
 				locale: z.string().optional().describe("Locale of the definition to update"),
 			}),
@@ -2863,7 +3106,9 @@ export function createMcpServer(
 				translationOf: z
 					.string()
 					.optional()
-					.describe("Term id to join as a translation (same translation_group)"),
+					.describe(
+						"Term id to join as a translation (same translation_group). The new term takes that term's parent and position; a different parentId moves the term in every locale",
+					),
 			}),
 		},
 		async (args, extra) => {
@@ -3367,16 +3612,18 @@ export function createMcpServer(
 				"the full settings object after the update. To set a media reference " +
 				"(logo, favicon, seo.defaultOgImage), pass an object with `mediaId` " +
 				"(and optional `alt`) — the media item must already exist (use " +
-				"media_create first).",
+				"media_create first), or pass null to remove it.",
 			inputSchema: z.object({
 				title: z.string().optional().describe("Site title"),
 				tagline: z.string().optional().describe("Site tagline / short description"),
 				logo: settingsMediaReferenceSchema
+					.nullable()
 					.optional()
-					.describe("Logo media reference ({ mediaId, alt? })"),
+					.describe("Logo media reference ({ mediaId, alt? }); null removes it"),
 				favicon: settingsMediaReferenceSchema
+					.nullable()
 					.optional()
-					.describe("Favicon media reference ({ mediaId, alt? })"),
+					.describe("Favicon media reference ({ mediaId, alt? }); null removes it"),
 				url: z
 					.union([
 						z.url().refine((u) => HTTP_SCHEME_PATTERN.test(u), "URL must use http or https"),
@@ -3412,5 +3659,215 @@ export function createMcpServer(
 		},
 	);
 
+	// =====================================================================
+	// Site transfer tools
+	// =====================================================================
+
+	server.registerTool(
+		"site_transfer_capabilities",
+		{
+			title: "Get Site Transfer Capabilities",
+			description:
+				"Site package format versions, features, and limits this site supports, and whether " +
+				"it can receive an import (its portable content is empty) with the reasons it cannot. " +
+				"Requires any transfer scope (transfer:export, transfer:analyze, or transfer:execute).",
+			inputSchema: z.object({}),
+			annotations: { readOnlyHint: true },
+		},
+		async (_args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			requireTransferScope(extra, "transfer:*");
+			return unwrap(await transferCapabilities(transferContext(extra)));
+		},
+	);
+
+	server.registerTool(
+		"site_export_start",
+		{
+			title: "Start Site Export",
+			description:
+				"Start exporting the whole site as a portable site package (schema, content, media, " +
+				"settings; never users, credentials, or secrets). Returns the operation id and " +
+				"status only; drive it with site_export_status. The package itself is downloaded " +
+				"outside MCP, from the admin or the CLI. Requires the transfer:export scope. " +
+				APPROVAL_FLOW_DESCRIPTION,
+			inputSchema: z.object({
+				comments: z.boolean().optional().describe("Include comments and reactions (default true)"),
+				approvalId: transferApprovalIdSchema.optional(),
+			}),
+		},
+		async (args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			const scoped = transferScopeHeld(extra, "transfer:export");
+			const { userId, tokenId } = getExtra(extra);
+			return unwrap(
+				await startExport(transferContext(extra), { userId, tokenId }, { ...args, scoped }),
+			);
+		},
+	);
+
+	server.registerTool(
+		"site_export_status",
+		{
+			title: "Get Site Export Status",
+			description:
+				"Report an export's state, stage, and progress, and once it is complete its package " +
+				"digest and record and media totals. By default each call also runs one bounded " +
+				"export step, so call it repeatedly until nextRequestInMs is null; pass advance: " +
+				"false to only read. Requires the transfer:export scope, or the approval that " +
+				"started this export (same token).",
+			inputSchema: z.object({
+				operationId: transferOperationIdSchema,
+				advance: z
+					.boolean()
+					.optional()
+					.describe("Run one bounded export step before reporting (default true)"),
+			}),
+		},
+		async (args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			await requireTransferAccess(extra, "transfer:export", "export", args.operationId);
+			return unwrap(
+				await exportStatus(transferContext(extra), {
+					operationId: args.operationId,
+					advance: args.advance ?? true,
+				}),
+			);
+		},
+	);
+
+	server.registerTool(
+		"site_import_analyze",
+		{
+			title: "Analyze Site Import",
+			description:
+				"Validate an uploaded site package against this site and produce an import plan. " +
+				"The package must already be uploaded over HTTP, from the admin or the CLI; MCP " +
+				"never carries package bytes. Each call runs one bounded analysis step: repeat until " +
+				"nextRequestInMs is null, then read plan (counts, principals with suggested user " +
+				"mappings, warnings, blockers, packageDigest, planDigest). Pass decisions to map " +
+				"principals or keep this site's title and tagline; that produces a new planDigest. " +
+				"Principal emails are never returned. Writes no site content. Requires the " +
+				"transfer:analyze scope.",
+			inputSchema: z.object({
+				operationId: transferOperationIdSchema,
+				decisions: siteImportDecisionsInputSchema
+					.optional()
+					.describe(
+						"principalMappings (principal id to target user id, or null to drop the " +
+							"reference) and siteTitle / siteTagline ('package' or 'target'). Omitted " +
+							"values keep the plan defaults.",
+					),
+			}),
+		},
+		async (args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			requireTransferScope(extra, "transfer:analyze");
+			return unwrap(await analyzeImport(transferContext(extra), args));
+		},
+	);
+
+	server.registerTool(
+		"site_import_start",
+		{
+			title: "Start Site Import",
+			description:
+				"Start importing an analyzed package into this site. packageDigest and planDigest " +
+				"must be the values from the latest site_import_analyze plan, which must have no " +
+				"blockers. Returns the operation id and status; drive it with site_import_resume. " +
+				"The site refuses ordinary content writes until the import completes or an admin " +
+				"abandons it. Requires the transfer:execute scope. " +
+				APPROVAL_FLOW_DESCRIPTION,
+			inputSchema: z.object({
+				operationId: transferOperationIdSchema,
+				packageDigest: z
+					.string()
+					.regex(SHA256_DIGEST_PATTERN, "Expected sha256:<64 hex>")
+					.describe("Package digest from the plan"),
+				planDigest: z
+					.string()
+					.regex(SHA256_DIGEST_PATTERN, "Expected sha256:<64 hex>")
+					.describe("Plan digest from the latest analysis"),
+				approvalId: transferApprovalIdSchema.optional(),
+			}),
+			annotations: { destructiveHint: true },
+		},
+		async (args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			const scoped = transferScopeHeld(extra, "transfer:execute");
+			const { userId, tokenId } = getExtra(extra);
+			return unwrap(
+				await startImport(
+					transferContext(extra),
+					{ userId, tokenId },
+					{
+						operationId: args.operationId,
+						packageDigest: transferDigest(args.packageDigest),
+						planDigest: transferDigest(args.planDigest),
+						approvalId: args.approvalId,
+						scoped,
+					},
+				),
+			);
+		},
+	);
+
+	server.registerTool(
+		"site_import_status",
+		{
+			title: "Get Site Import Status",
+			description:
+				"Report an import's state, stage, progress, digests, and uploaded file counts. Does " +
+				"not advance the import. Requires any transfer scope, or the approval that started " +
+				"this import (same token).",
+			inputSchema: z.object({ operationId: transferOperationIdSchema }),
+			annotations: { readOnlyHint: true },
+		},
+		async (args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			await requireTransferAccess(extra, "transfer:*", "import", args.operationId);
+			return unwrap(await importStatus(transferContext(extra), args.operationId));
+		},
+	);
+
+	server.registerTool(
+		"site_import_resume",
+		{
+			title: "Resume Site Import",
+			description:
+				"Run one bounded step of a started import and report its status. Call repeatedly " +
+				"until nextRequestInMs is null; safe to repeat after a disconnect. Requires the " +
+				"transfer:execute scope, or the approval that started this import (same token).",
+			inputSchema: z.object({ operationId: transferOperationIdSchema }),
+		},
+		async (args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			await requireTransferAccess(extra, "transfer:execute", "import", args.operationId);
+			const { userId, tokenId } = getExtra(extra);
+			return unwrap(
+				await resumeImport(transferContext(extra), { userId, tokenId }, args.operationId),
+			);
+		},
+	);
+
+	server.registerTool(
+		"site_import_receipt",
+		{
+			title: "Get Site Import Receipt",
+			description:
+				"Return the verified receipt of a completed import: package and plan digests, " +
+				"origin and target site ids, logical digest, record counts, warnings, and the " +
+				"receipt's own digest. Requires any transfer scope, or the approval that started " +
+				"this import (same token).",
+			inputSchema: z.object({ operationId: transferOperationIdSchema }),
+			annotations: { readOnlyHint: true },
+		},
+		async (args, extra) => {
+			requireRole(extra, Role.ADMIN);
+			await requireTransferAccess(extra, "transfer:*", "import", args.operationId);
+			return unwrap(await importReceipt(transferContext(extra), args.operationId));
+		},
+	);
+
 	return server;
 }