emdash 0.8.0 → 0.10.0

package/src/mcp/server.ts

@@ -14,6 +14,8 @@ import { canActOnOwn, hasPermission, Role } from "@emdash-cms/auth";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
+import { contentBylineInputSchema, contentSeoInput } from "#api/schemas.js";
+
 import type { EmDashHandlers } from "../astro/types.js";
 import { hasScope } from "../auth/api-tokens.js";
 
@@ -623,7 +625,10 @@ export function createMcpServer(): McpServer {
 				"Update an existing content item. Only include fields you want to change " +
 				"in the 'data' object — unspecified fields are left unchanged. Pass the " +
 				"_rev token from content_get to enable optimistic concurrency checking " +
-				"(the update fails if the item was modified since you read it).",
+				"(the update fails if the item was modified since you read it). " +
+				"`seo` and `bylines` are persisted alongside the field updates in a " +
+				"single transaction. `publishedAt` requires the content:publish_any " +
+				"permission and is useful for migrations or correcting historical dates.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
@@ -638,6 +643,28 @@ export function createMcpServer(): McpServer {
 					.describe(
 						"New status. Setting to 'published' requires publish permission. Setting to 'draft' unpublishes the item and also requires publish permission.",
 					),
+				// Reuse the REST schema rather than redefining inline. The REST schema's
+				// `canonical` field is gated through `httpUrl` (validates the URL parses
+				// AND has an http(s) scheme) which rejects javascript:/data: URIs that
+				// would otherwise become stored XSS in the rendered <link rel="canonical">.
+				// Inlining a looser shape here would let MCP callers bypass that.
+				seo: contentSeoInput
+					.optional()
+					.describe(
+						"Per-content SEO metadata. Only valid for collections with SEO enabled (see schema_get_collection.hasSeo). Fields not included are left unchanged; pass null to clear.",
+					),
+				bylines: z
+					.array(contentBylineInputSchema)
+					.optional()
+					.describe(
+						"Replace the byline list for this item. The first entry becomes the primary byline. Pass an empty array to clear all bylines.",
+					),
+				publishedAt: z.iso
+					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+					.nullish()
+					.describe(
+						"Override the publication timestamp (ISO 8601). Requires content:publish_any permission. Pass null to clear. Useful for content migrations.",
+					),
 				_rev: z
 					.string()
 					.optional()
@@ -647,35 +674,48 @@ export function createMcpServer(): McpServer {
 		async (args, extra) => {
 			requireScope(extra, "content:write");
 			requireRole(extra, Role.AUTHOR);
-			const { emdash, userId } = getExtra(extra);
+			const { emdash, userId, userRole } = getExtra(extra);
 
 			// Fetch item to check ownership
 			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 ownerId = extractContentAuthorId(existing.data);
+			requireOwnership(extra, ownerId, "content:edit_own", "content:edit_any");
+
+			// Writing publishedAt directly (incl. clearing to null) overwrites
+			// historical record — gate behind publish_any, mirroring the REST PUT
+			// route. Status-driven publishes are gated separately below.
+			if (args.publishedAt !== undefined) {
+				const user = { id: userId, role: userRole };
+				if (!hasPermission(user, "content:publish_any" as Permission)) {
+					throw new EmDashAuthError(
+						"Setting publishedAt requires content:publish_any permission",
+						"INSUFFICIENT_PERMISSIONS",
+					);
+				}
+			}
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
 
 			// Status transitions route through dedicated handlers for proper revision management
 			if (args.status === "published") {
-				requireOwnership(
-					extra,
-					extractContentAuthorId(existing.data),
-					"content:publish_own",
-					"content:publish_any",
-				);
-				if (args.data || args.slug) {
+				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				if (
+					args.data ||
+					args.slug ||
+					args.seo !== undefined ||
+					args.bylines !== undefined ||
+					args.publishedAt !== undefined
+				) {
 					const updateResult = await emdash.handleContentUpdate(args.collection, resolvedId, {
 						data: args.data,
 						slug: args.slug,
 						authorId: userId,
+						seo: args.seo,
+						bylines: args.bylines,
+						publishedAt: args.publishedAt,
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
@@ -684,17 +724,21 @@ export function createMcpServer(): McpServer {
 			}
 
 			if (args.status === "draft") {
-				requireOwnership(
-					extra,
-					extractContentAuthorId(existing.data),
-					"content:publish_own",
-					"content:publish_any",
-				);
-				if (args.data || args.slug) {
+				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				if (
+					args.data ||
+					args.slug ||
+					args.seo !== undefined ||
+					args.bylines !== undefined ||
+					args.publishedAt !== undefined
+				) {
 					const updateResult = await emdash.handleContentUpdate(args.collection, resolvedId, {
 						data: args.data,
 						slug: args.slug,
 						authorId: userId,
+						seo: args.seo,
+						bylines: args.bylines,
+						publishedAt: args.publishedAt,
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
@@ -707,6 +751,9 @@ export function createMcpServer(): McpServer {
 					data: args.data,
 					slug: args.slug,
 					authorId: userId,
+					seo: args.seo,
+					bylines: args.bylines,
+					publishedAt: args.publishedAt,
 					_rev: args._rev,
 				}),
 			);
@@ -809,31 +856,53 @@ export function createMcpServer(): McpServer {
 			description:
 				"Publish a content item, making it live on the site. Creates a published " +
 				"revision from the current draft. Further edits create a new draft without " +
-				"affecting the live version until re-published.",
+				"affecting the live version until re-published. Pass `publishedAt` to " +
+				"backdate (e.g. when migrating content from another CMS) — this requires " +
+				"the content:publish_any permission. Without `publishedAt`, the existing " +
+				"`published_at` is preserved on re-publish (idempotent) and falls back to " +
+				"the current time on first publish.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
+				publishedAt: z.iso
+					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+					.optional()
+					.describe(
+						"Override publication timestamp (ISO 8601). Requires content:publish_any permission. Useful when importing content with original publish dates.",
+					),
 			}),
 		},
 		async (args, extra) => {
 			requireScope(extra, "content:write");
 			requireRole(extra, Role.AUTHOR);
-			const ec = getEmDash(extra);
+			const { emdash, userId, userRole } = getExtra(extra);
 
 			// Fetch item to check ownership
-			const existing = await ec.handleContentGet(args.collection, args.id);
+			const existing = await emdash.handleContentGet(args.collection, args.id);
 			if (!existing.success) {
 				return unwrap(existing);
 			}
-			requireOwnership(
-				extra,
-				extractContentAuthorId(existing.data),
-				"content:publish_own",
-				"content:publish_any",
-			);
+			const ownerId = extractContentAuthorId(existing.data);
+			requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+
+			// Backdating overwrites historical record — gate behind publish_any
+			// regardless of ownership (mirrors the REST PUT route's publishedAt gate).
+			if (args.publishedAt !== undefined) {
+				const user = { id: userId, role: userRole };
+				if (!hasPermission(user, "content:publish_any" as Permission)) {
+					throw new EmDashAuthError(
+						"Setting publishedAt requires content:publish_any permission",
+						"INSUFFICIENT_PERMISSIONS",
+					);
+				}
+			}
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
-			return unwrap(await ec.handleContentPublish(args.collection, resolvedId));
+			return unwrap(
+				await emdash.handleContentPublish(args.collection, resolvedId, {
+					publishedAt: args.publishedAt,
+				}),
+			);
 		},
 	);
 
@@ -1195,7 +1264,7 @@ export function createMcpServer(): McpServer {
 					// ['drafts', 'revisions'] when undefined; pass through verbatim.
 					supports: args.supports,
 				});
-				ec.invalidateManifest();
+				ec.invalidateUrlPatternCache();
 				return jsonResult(collection);
 			} catch (error) {
 				return respondHandlerError(error, "SCHEMA_CREATE_ERROR");
@@ -1227,7 +1296,7 @@ export function createMcpServer(): McpServer {
 				const { SchemaRegistry } = await import("../schema/index.js");
 				const registry = new SchemaRegistry(ec.db);
 				await registry.deleteCollection(args.slug, { force: args.force });
-				ec.invalidateManifest();
+				ec.invalidateUrlPatternCache();
 				return jsonResult({ deleted: args.slug });
 			} catch (error) {
 				return respondHandlerError(error, "SCHEMA_DELETE_ERROR");
@@ -1331,7 +1400,6 @@ export function createMcpServer(): McpServer {
 					searchable: args.searchable,
 					translatable: args.translatable,
 				});
-				ec.invalidateManifest();
 				return jsonResult(field);
 			} catch (error) {
 				return respondHandlerError(error, "FIELD_CREATE_ERROR");
@@ -1360,7 +1428,6 @@ export function createMcpServer(): McpServer {
 				const { SchemaRegistry } = await import("../schema/index.js");
 				const registry = new SchemaRegistry(ec.db);
 				await registry.deleteField(args.collection, args.fieldSlug);
-				ec.invalidateManifest();
 				return jsonResult({ deleted: args.fieldSlug, collection: args.collection });
 			} catch (error) {
 				return respondHandlerError(error, "FIELD_DELETE_ERROR");
@@ -1600,16 +1667,19 @@ export function createMcpServer(): McpServer {
 			description:
 				"List all taxonomy definitions (e.g. categories, tags). Taxonomies are " +
 				"classification systems applied to content. Each has a name, label, and " +
-				"can be hierarchical (categories) or flat (tags).",
-			inputSchema: z.object({}),
+				"can be hierarchical (categories) or flat (tags). Optionally filter by " +
+				"locale.",
+			inputSchema: z.object({
+				locale: z.string().optional().describe("Filter by locale (omit for all)"),
+			}),
 			annotations: { readOnlyHint: true },
 		},
-		async (_args, extra) => {
+		async (args, extra) => {
 			requireScope(extra, "content:read");
 			const ec = getEmDash(extra);
 			try {
 				const { handleTaxonomyList } = await import("../api/handlers/taxonomies.js");
-				return unwrap(await handleTaxonomyList(ec.db));
+				return unwrap(await handleTaxonomyList(ec.db, { locale: args.locale }));
 			} catch (error) {
 				return respondHandlerError(error, "TAXONOMY_LIST_ERROR");
 			}
@@ -1628,6 +1698,7 @@ export function createMcpServer(): McpServer {
 				taxonomy: z.string().describe("Taxonomy name (e.g. 'categories', 'tags')"),
 				limit: z.number().int().min(1).max(100).optional().describe("Max items (default 50)"),
 				cursor: z.string().min(1).max(2048).optional().describe("Pagination cursor"),
+				locale: z.string().optional().describe("Filter by locale (omit for all)"),
 			}),
 			annotations: { readOnlyHint: true },
 		},
@@ -1635,9 +1706,8 @@ export function createMcpServer(): McpServer {
 			requireScope(extra, "content:read");
 			const ec = getEmDash(extra);
 			try {
-				// Verify taxonomy exists via handler layer
 				const { handleTaxonomyList } = await import("../api/handlers/taxonomies.js");
-				const listResult = await handleTaxonomyList(ec.db);
+				const listResult = await handleTaxonomyList(ec.db, { locale: args.locale });
 				if (!listResult.success) return unwrap(listResult);
 
 				const taxonomies = (listResult.data as { taxonomies: Array<{ name: string; id?: string }> })
@@ -1645,13 +1715,12 @@ export function createMcpServer(): McpServer {
 				const taxonomy = taxonomies.find((t: { name: string }) => t.name === args.taxonomy);
 				if (!taxonomy) return respondError("NOT_FOUND", `Taxonomy '${args.taxonomy}' not found`);
 
-				// Paginated term query via repository (avoids N+1 of handleTermList)
 				const { TaxonomyRepository } = await import("../database/repositories/taxonomy.js");
 				const { decodeCursor, encodeCursor, InvalidCursorError } =
 					await import("../database/repositories/types.js");
 				const repo = new TaxonomyRepository(ec.db);
 				const limit = Math.min(args.limit ?? 50, 100);
-				const terms = await repo.findByName(args.taxonomy);
+				const terms = await repo.findByName(args.taxonomy, { locale: args.locale });
 
 				// Manual keyset pagination over the sorted-by-label results.
 				// Using a base64-encoded `(label, id)` cursor matches the
@@ -1693,6 +1762,8 @@ export function createMcpServer(): McpServer {
 						label: t.label,
 						parentId: t.parentId,
 						description: typeof t.data?.description === "string" ? t.data.description : undefined,
+						locale: t.locale,
+						translationGroup: t.translationGroup,
 					})),
 					nextCursor,
 				});
@@ -1718,6 +1789,11 @@ export function createMcpServer(): McpServer {
 				label: z.string().describe("Display name"),
 				parentId: z.string().optional().describe("Parent term ID for hierarchical taxonomies"),
 				description: z.string().optional().describe("Description of the term"),
+				locale: z.string().optional().describe("Locale for the new term (e.g. 'es')"),
+				translationOf: z
+					.string()
+					.optional()
+					.describe("Term id to join as a translation (same translation_group)"),
 			}),
 		},
 		async (args, extra) => {
@@ -1732,6 +1808,8 @@ export function createMcpServer(): McpServer {
 						label: args.label,
 						parentId: args.parentId,
 						description: args.description,
+						locale: args.locale,
+						translationOf: args.translationOf,
 					}),
 				);
 			} catch (error) {
@@ -1808,6 +1886,29 @@ export function createMcpServer(): McpServer {
 		},
 	);
 
+	server.registerTool(
+		"taxonomy_term_translations",
+		{
+			title: "List Term Translations",
+			description:
+				"Return every locale variant of a taxonomy term, identified via its shared translation_group.",
+			inputSchema: z.object({
+				id: z.string().describe("Term id (or translation_group)"),
+			}),
+			annotations: { readOnlyHint: true },
+		},
+		async (args, extra) => {
+			requireScope(extra, "content:read");
+			const ec = getEmDash(extra);
+			try {
+				const { handleTermTranslations } = await import("../api/handlers/taxonomies.js");
+				return unwrap(await handleTermTranslations(ec.db, args.id));
+			} catch (error) {
+				return respondHandlerError(error, "TERM_TRANSLATIONS_ERROR");
+			}
+		},
+	);
+
 	// =====================================================================
 	// Menu tools
 	// =====================================================================
@@ -1817,18 +1918,20 @@ export function createMcpServer(): McpServer {
 		{
 			title: "List Menus",
 			description:
-				"List all navigation menus defined in the CMS. Menus are named " +
-				"navigation structures (e.g. 'main', 'footer') containing ordered " +
-				"items with labels, URLs, and optional nesting.",
-			inputSchema: z.object({}),
+				"List navigation menus. Menus are per-locale: filter by `locale` to " +
+				"get just one locale's worth, or omit to list every row (one per " +
+				"locale per menu name).",
+			inputSchema: z.object({
+				locale: z.string().optional().describe("Filter by locale (omit for all)"),
+			}),
 			annotations: { readOnlyHint: true },
 		},
-		async (_args, extra) => {
+		async (args, extra) => {
 			requireScope(extra, "content:read");
 			const ec = getEmDash(extra);
 			try {
 				const { handleMenuList } = await import("../api/handlers/menus.js");
-				return unwrap(await handleMenuList(ec.db));
+				return unwrap(await handleMenuList(ec.db, { locale: args.locale }));
 			} catch (error) {
 				return respondHandlerError(error, "MENU_LIST_ERROR");
 			}
@@ -1840,11 +1943,11 @@ export function createMcpServer(): McpServer {
 		{
 			title: "Get Menu with Items",
 			description:
-				"Get a menu by name including all its items in order. Items have a " +
-				"label, URL, type (custom/content/collection), and optional parent " +
-				"for nesting.",
+				"Get a menu by name, including its items. When multiple locales exist, " +
+				"pass `locale` to pick the right one.",
 			inputSchema: z.object({
 				name: z.string().describe("Menu name (e.g. 'main', 'footer')"),
+				locale: z.string().optional().describe("Locale to resolve the menu for"),
 			}),
 			annotations: { readOnlyHint: true },
 		},
@@ -1853,13 +1956,36 @@ export function createMcpServer(): McpServer {
 			const ec = getEmDash(extra);
 			try {
 				const { handleMenuGet } = await import("../api/handlers/menus.js");
-				return unwrap(await handleMenuGet(ec.db, args.name));
+				return unwrap(await handleMenuGet(ec.db, args.name, { locale: args.locale }));
 			} catch (error) {
 				return respondHandlerError(error, "MENU_GET_ERROR");
 			}
 		},
 	);
 
+	server.registerTool(
+		"menu_translations",
+		{
+			title: "List Menu Translations",
+			description:
+				"Return every locale variant of a menu, identified via the shared translation_group.",
+			inputSchema: z.object({
+				id: z.string().describe("Menu id (or translation_group)"),
+			}),
+			annotations: { readOnlyHint: true },
+		},
+		async (args, extra) => {
+			requireScope(extra, "content:read");
+			const ec = getEmDash(extra);
+			try {
+				const { handleMenuTranslations } = await import("../api/handlers/menus.js");
+				return unwrap(await handleMenuTranslations(ec.db, args.id));
+			} catch (error) {
+				return respondHandlerError(error, "MENU_TRANSLATIONS_ERROR");
+			}
+		},
+	);
+
 	server.registerTool(
 		"menu_create",
 		{