emdash-auto-meta 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus Bellamy-Shaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# emdash-auto-meta
+
+An [Emdash CMS](https://emdashcms.com) plugin that lets AI agents (Claude, ChatGPT, etc.) assign taxonomy terms and set SEO metadata when creating content via the [Emdash MCP server](https://docs.emdashcms.com/mcp).
+
+## The Problem
+
+The Emdash MCP server is great for creating and updating content, but has two gaps that make it hard to use from an AI agent on mobile or in agentic workflows:
+
+1. **No `content_set_terms` tool.** There is no way for an agent to assign taxonomy terms (categories, tags, etc.) through the MCP server.
+2. **SEO metadata serialization bug.** The `seo` parameter in `content_update` does not persist correctly. ([Discussion #1070](https://github.com/emdash-cms/emdash/discussions/1070))
+
+This plugin works around both gaps by letting the agent embed a small metadata block directly in the post content. The plugin intercepts every save via `content:afterSave`, processes the block, and strips it before the content reaches readers.
+
+## How It Works
+
+1. When creating a post, the agent appends a metadata block to the Portable Text content field:
+
+   ```
+   <!-- ebt-meta:{"categories":["history"],"tags":["dallas"],"seo_title":"My Title"} -->
+   ```
+
+2. On `content:afterSave`, this plugin scans all Portable Text fields for the block.
+3. It resolves taxonomy slugs to database IDs, assigns terms, and sets SEO — all in a single pass.
+4. It strips the block from the content and saves the cleaned version.
+
+The save pipeline sees only the final, clean content. The metadata block is never visible to site visitors.
+
+## Installation
+
+```bash
+npm install emdash-auto-meta
+```
+
+If you're referencing the plugin locally via a `file:` path during development, also run `npm install` inside the plugin directory so Vite can resolve its peer dependency:
+
+```bash
+cd path/to/emdash-auto-meta && npm install
+```
+
+**Requirements:**
+
+- Emdash `^0.12.0`
+- Cloudflare Workers (paid plan) — this plugin uses `getDb()` from `emdash/runtime` and must run as a trusted plugin in your Workers environment
+- Must be registered in `plugins: []` (not `sandboxed: []`)
+
+## Setup
+
+```typescript
+// astro.config.mjs
+import { emdashAutoMeta } from "emdash-auto-meta";
+
+export default defineConfig({
+  integrations: [
+    emdash({
+      plugins: [
+        emdashAutoMeta({
+          taxonomyMap: {
+            categories: "category",  // your Emdash taxonomy name
+            tags: "tag",
+            regions: "regions",
+            eras: "eras",
+          },
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+## Metadata Block Format
+
+Append this block to the end of any Portable Text content field when creating a post. The agent writes it; the plugin strips it.
+
+```
+<!-- ebt-meta:{
+  "categories": ["history-landmarks"],
+  "tags": ["dallas-texas", "new-tag"],
+  "regions": ["prairies-lakes"],
+  "eras": ["the-oil-boom"],
+  "seo_title": "Your SEO Title",
+  "seo_description": "Your meta description."
+} -->
+```
+
+The block must be a single Portable Text block node containing the raw HTML comment. All fields are optional — include only what you need.
+
+### TypeScript Interface
+
+```typescript
+interface AutoMeta {
+  /** Slugs of existing category terms to assign */
+  categories?: string[];
+  /** Slugs of tag terms to assign (auto-created if autoCreateTags is true) */
+  tags?: string[];
+  /** Slugs of existing region terms to assign */
+  regions?: string[];
+  /** Slugs of existing era terms to assign */
+  eras?: string[];
+  /** SEO title tag */
+  seo_title?: string;
+  /** SEO meta description */
+  seo_description?: string;
+}
+```
+
+## Configuration
+
+```typescript
+emdashAutoMeta({
+  metaPrefix?: string;
+  autoCreateTags?: boolean;
+  logLevel?: "silent" | "info" | "debug";
+  taxonomyMap?: {
+    categories?: string;
+    tags?: string;
+    regions?: string;
+    eras?: string;
+  };
+})
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `metaPrefix` | `string` | `"<!-- ebt-meta:"` | The prefix string that identifies the metadata block. Change this if your agents use a different convention. |
+| `autoCreateTags` | `boolean` | `true` | When `true`, tag slugs that don't exist in the database are created automatically. Set to `false` to require all tags to be pre-created. |
+| `logLevel` | `"silent" \| "info" \| "debug"` | `"info"` | Controls log output. `"debug"` logs every step including successful updates. `"silent"` suppresses everything except errors. |
+| `taxonomyMap.categories` | `string` | `"category"` | The Emdash taxonomy name that maps to the `categories` key in the metadata block. |
+| `taxonomyMap.tags` | `string` | `"tag"` | The Emdash taxonomy name that maps to the `tags` key. |
+| `taxonomyMap.regions` | `string` | `"regions"` | The Emdash taxonomy name that maps to the `regions` key. |
+| `taxonomyMap.eras` | `string` | `"eras"` | The Emdash taxonomy name that maps to the `eras` key. |
+
+### Taxonomy Notes
+
+- **`categories`, `regions`, `eras`** — slugs must match terms that already exist in your Emdash database. Unknown slugs are logged as warnings and skipped.
+- **`tags`** — when `autoCreateTags: true` (the default), unknown slugs are created as new terms with a label derived from the slug (`"dallas-texas"` → `"Dallas Texas"`). Set `autoCreateTags: false` to treat tags the same as other taxonomies.
+- Taxonomy names in `taxonomyMap` must match the `name` field in your Emdash seed exactly, not the display label.
+
+### Prompt for Your Agent
+
+Add something like this to your agent's system prompt or instructions:
+
+```
+When creating a post in Emdash, append a metadata block as the final
+paragraph of the content field using this exact format:
+
+<!-- ebt-meta:{"categories":["slug"],"tags":["slug"],"seo_title":"Title","seo_description":"Description."} -->
+
+Only include the fields you have values for. Taxonomy slugs must be
+lowercase and hyphenated (e.g. "history-landmarks", not "History Landmarks").
+```
+
+## Limitations
+
+- **Trusted plugin only.** This plugin uses `getDb()` from `emdash/runtime` to assign taxonomy terms, which requires direct database access. It cannot run in `sandboxed: []` mode.
+- **Cloudflare Workers (paid plan) required.** The trusted plugin mode that provides `getDb()` is only available on Cloudflare Workers with a paid plan.
+- **Media upload not supported in v1.0.** Attaching images via URL is planned for v1.1, pending a reliable solution for server-side image fetching in the Cloudflare Workers environment. For now, upload images manually through the Emdash admin after creating a post.
+- **Metadata block must be in a Portable Text field.** The plugin scans only `_type: "block"` nodes inside array fields. It will not find the block in plain text or other field types.
+- **One metadata block per save.** Only the first block found is processed. If the agent writes multiple blocks, only the first is consumed; the rest remain in the content.
+
+## Contributing
+
+This plugin was built as a workaround for two gaps in the Emdash MCP server. If you're interested in seeing native MCP support for taxonomy assignment and SEO metadata, join the discussion:
+
+[github.com/emdash-cms/emdash/discussions/1070](https://github.com/emdash-cms/emdash/discussions/1070)
+
+Bug reports and pull requests welcome. Please open an issue before submitting a PR for anything beyond a small bug fix.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+	"name": "emdash-auto-meta",
+	"version": "1.0.0",
+	"description": "Emdash CMS plugin that enables AI agents to assign taxonomy terms and set SEO metadata via the content:afterSave hook",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"keywords": [
+		"emdash",
+		"emdash-plugin",
+		"cms",
+		"ai-agents",
+		"mcp",
+		"claude",
+		"taxonomy",
+		"seo",
+		"cloudflare-workers"
+	],
+	"author": "Marcus Bellamy-Shaw",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/marcusbellamyshaw-cell/emdash-auto-meta.git"
+	},
+	"bugs": {
+		"url": "https://github.com/marcusbellamyshaw-cell/emdash-auto-meta/issues"
+	},
+	"homepage": "https://github.com/marcusbellamyshaw-cell/emdash-auto-meta#readme",
+	"peerDependencies": {
+		"emdash": "^0.12.0"
+	},
+	"devDependencies": {
+		"emdash": "latest"
+	}
+}

package/src/index.ts

@@ -0,0 +1,300 @@
+import { definePlugin, ulid } from "emdash";
+import type { PluginContext, PluginDescriptor, ResolvedPlugin } from "emdash";
+import { getDb } from "emdash/runtime";
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+export interface EmdashAutoMetaConfig {
+	/** Prefix string that identifies the metadata block. Default: "<!-- ebt-meta:" */
+	metaPrefix?: string;
+	/** Auto-create tag terms that don't exist in the database. Default: true */
+	autoCreateTags?: boolean;
+	/** Logging verbosity. Default: "info" */
+	logLevel?: "silent" | "info" | "debug";
+	/**
+	 * Maps the fixed metadata block keys to the actual taxonomy names in your
+	 * Emdash schema. Use this when your site's taxonomies are named differently
+	 * from the defaults.
+	 */
+	taxonomyMap?: {
+		/** Taxonomy name for the "categories" key. Default: "category" */
+		categories?: string;
+		/** Taxonomy name for the "tags" key. Default: "tag" */
+		tags?: string;
+		/** Taxonomy name for the "regions" key. Default: "regions" */
+		regions?: string;
+		/** Taxonomy name for the "eras" key. Default: "eras" */
+		eras?: string;
+	};
+}
+
+interface ResolvedConfig {
+	metaPrefix: string;
+	metaPattern: RegExp;
+	autoCreateTags: boolean;
+	logLevel: "silent" | "info" | "debug";
+	taxonomyMap: {
+		categories: string;
+		tags: string;
+		regions: string;
+		eras: string;
+	};
+}
+
+function resolveConfig(config: EmdashAutoMetaConfig): ResolvedConfig {
+	const metaPrefix = config.metaPrefix ?? "<!-- ebt-meta:";
+	const escapedPrefix = metaPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return {
+		metaPrefix,
+		metaPattern: new RegExp(`${escapedPrefix}(.+?) -->`),
+		autoCreateTags: config.autoCreateTags ?? true,
+		logLevel: config.logLevel ?? "info",
+		taxonomyMap: {
+			categories: config.taxonomyMap?.categories ?? "category",
+			tags: config.taxonomyMap?.tags ?? "tag",
+			regions: config.taxonomyMap?.regions ?? "regions",
+			eras: config.taxonomyMap?.eras ?? "eras",
+		},
+	};
+}
+
+// ─── Metadata Schema ─────────────────────────────────────────────────────────
+
+export interface AutoMeta {
+	categories?: string[];
+	tags?: string[];
+	regions?: string[];
+	eras?: string[];
+	seo_title?: string;
+	seo_description?: string;
+}
+
+// ─── Internal Types ───────────────────────────────────────────────────────────
+
+type Db = Awaited<ReturnType<typeof getDb>>;
+
+interface Logger {
+	debug(msg: string): void;
+	info(msg: string): void;
+	warn(msg: string): void;
+	error(msg: string): void;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeLogger(ctx: PluginContext, level: "silent" | "info" | "debug"): Logger {
+	const tag = "[emdash-auto-meta]";
+	return {
+		debug: (msg) => { if (level === "debug") ctx.log.debug(`${tag} ${msg}`); },
+		info:  (msg) => { if (level !== "silent") ctx.log.info(`${tag} ${msg}`); },
+		warn:  (msg) => { if (level !== "silent") ctx.log.warn(`${tag} ${msg}`); },
+		error: (msg) => { if (level !== "silent") ctx.log.error(`${tag} ${msg}`); },
+	};
+}
+
+function extractMeta(
+	data: Record<string, unknown>,
+	pattern: RegExp,
+): { meta: AutoMeta; cleanedData: Record<string, unknown> } | null {
+	for (const [fieldKey, fieldValue] of Object.entries(data)) {
+		if (!Array.isArray(fieldValue)) continue;
+		for (let i = 0; i < fieldValue.length; i++) {
+			const block = fieldValue[i] as unknown;
+			if (!block || typeof block !== "object") continue;
+			const blockObj = block as Record<string, unknown>;
+			if (blockObj._type !== "block") continue;
+			const children = blockObj.children;
+			if (!Array.isArray(children)) continue;
+			for (const child of children) {
+				if (!child || typeof child !== "object") continue;
+				const childObj = child as Record<string, unknown>;
+				if (typeof childObj.text !== "string") continue;
+				const match = childObj.text.match(pattern);
+				if (!match?.[1]) continue;
+				let meta: AutoMeta;
+				try {
+					meta = JSON.parse(match[1]) as AutoMeta;
+				} catch {
+					return null;
+				}
+				const cleanedArray = (fieldValue as unknown[]).filter((_, idx) => idx !== i);
+				return { meta, cleanedData: { ...data, [fieldKey]: cleanedArray } };
+			}
+		}
+	}
+	return null;
+}
+
+async function resolveTermSlugs(
+	db: Db,
+	taxonomyName: string,
+	slugs: string[],
+	autoCreate: boolean,
+	log: Logger,
+): Promise<string[]> {
+	if (slugs.length === 0) return [];
+	const rows = await db
+		.selectFrom("taxonomies")
+		.select(["slug", "translation_group"])
+		.where("name", "=", taxonomyName)
+		.where("slug", "in", slugs)
+		.execute();
+	const existingBySlug = new Map(rows.map((r) => [r.slug, r.translation_group]));
+	const groups: string[] = [];
+	for (const slug of slugs) {
+		const group = existingBySlug.get(slug);
+		if (group) {
+			groups.push(group);
+		} else if (autoCreate) {
+			const id = ulid();
+			const label = slug
+				.split("-")
+				.map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+				.join(" ");
+			await db
+				.insertInto("taxonomies")
+				.values({ id, name: taxonomyName, slug, label, parent_id: null, data: null, locale: "en", translation_group: id } as never)
+				.execute();
+			groups.push(id);
+			log.info(`Created "${taxonomyName}" term: ${slug}`);
+		} else {
+			log.warn(`Term not found: ${taxonomyName}/${slug}`);
+		}
+	}
+	return groups;
+}
+
+async function setContentTerms(
+	db: Db,
+	collection: string,
+	entryId: string,
+	taxonomyName: string,
+	termGroups: string[],
+): Promise<void> {
+	const newSet = new Set(termGroups);
+	const current = await db
+		.selectFrom("content_taxonomies")
+		.innerJoin("taxonomies", "taxonomies.translation_group", "content_taxonomies.taxonomy_id")
+		.select("content_taxonomies.taxonomy_id")
+		.distinct()
+		.where("content_taxonomies.collection", "=", collection)
+		.where("content_taxonomies.entry_id", "=", entryId)
+		.where("taxonomies.name", "=", taxonomyName)
+		.execute();
+	const currentSet = new Set(current.map((r) => r.taxonomy_id));
+	const toRemove = [...currentSet].filter((g) => !newSet.has(g));
+	if (toRemove.length > 0) {
+		await db
+			.deleteFrom("content_taxonomies")
+			.where("collection", "=", collection)
+			.where("entry_id", "=", entryId)
+			.where("taxonomy_id", "in", toRemove)
+			.execute();
+	}
+	const toAdd = [...newSet].filter((g) => !currentSet.has(g));
+	if (toAdd.length > 0) {
+		await db
+			.insertInto("content_taxonomies")
+			.values(toAdd.map((taxonomy_id) => ({ collection, entry_id: entryId, taxonomy_id })))
+			.onConflict((oc) => oc.doNothing())
+			.execute();
+	}
+}
+
+// ─── Descriptor Factory ───────────────────────────────────────────────────────
+
+export function emdashAutoMeta(config: EmdashAutoMetaConfig = {}): PluginDescriptor<EmdashAutoMetaConfig> {
+	return {
+		id: "emdash-auto-meta",
+		version: "1.0.0",
+		entrypoint: "emdash-auto-meta",
+		options: config,
+		capabilities: ["content:write"],
+	};
+}
+
+// ─── Runtime Factory ──────────────────────────────────────────────────────────
+
+export function createPlugin(options: EmdashAutoMetaConfig = {}): ResolvedPlugin {
+	const cfg = resolveConfig(options);
+
+	return definePlugin({
+		id: "emdash-auto-meta",
+		version: "1.0.0",
+		capabilities: ["content:write"],
+
+		hooks: {
+			"content:afterSave": {
+				errorPolicy: "continue",
+				handler: async (event: never, ctx: PluginContext) => {
+					const log = makeLogger(ctx, cfg.logLevel);
+					const ev = event as { content: Record<string, unknown>; collection: string };
+					const content = ev.content;
+					const contentId = typeof content.id === "string" ? content.id : null;
+					const contentData = content.data as Record<string, unknown> | null | undefined;
+					if (!contentId || !contentData) return;
+
+					const extracted = extractMeta(contentData, cfg.metaPattern);
+					if (!extracted) return;
+
+					const { meta, cleanedData } = extracted;
+					log.info(`Processing ${ev.collection}/${contentId}`);
+
+					// Build update payload: cleaned body + optional SEO
+					const updatePayload: Record<string, unknown> = { ...cleanedData };
+					if (meta.seo_title || meta.seo_description) {
+						updatePayload["seo"] = {
+							title: meta.seo_title ?? "",
+							description: meta.seo_description ?? "",
+						};
+					}
+
+					// Strip the meta block (and set SEO) in a single content update
+					if (ctx.content && "update" in ctx.content) {
+						try {
+							await (ctx.content as {
+								update: (col: string, id: string, data: Record<string, unknown>) => Promise<unknown>;
+							}).update(ev.collection, contentId, updatePayload);
+							log.debug(`Content updated: ${ev.collection}/${contentId}`);
+						} catch (err) {
+							log.error(`Content update failed: ${err}`);
+						}
+					}
+
+					// Taxonomy assignment — each taxonomy fails independently
+					const assignments = [
+						{ taxName: cfg.taxonomyMap.categories, slugs: meta.categories ?? [], autoCreate: false },
+						{ taxName: cfg.taxonomyMap.tags,       slugs: meta.tags ?? [],       autoCreate: cfg.autoCreateTags },
+						{ taxName: cfg.taxonomyMap.regions,    slugs: meta.regions ?? [],    autoCreate: false },
+						{ taxName: cfg.taxonomyMap.eras,       slugs: meta.eras ?? [],       autoCreate: false },
+					];
+
+					if (assignments.every((a) => a.slugs.length === 0)) return;
+
+					let db: Db;
+					try {
+						db = await getDb();
+					} catch (err) {
+						log.error(`Could not get DB: ${err}`);
+						return;
+					}
+
+					for (const { taxName, slugs, autoCreate } of assignments) {
+						if (slugs.length === 0) continue;
+						try {
+							const groups = await resolveTermSlugs(db, taxName, slugs, autoCreate, log);
+							if (groups.length > 0) {
+								await setContentTerms(db, ev.collection, contentId, taxName, groups);
+								log.info(`Assigned "${taxName}": ${slugs.join(", ")}`);
+							}
+						} catch (err) {
+							log.error(`Taxonomy "${taxName}" failed: ${err}`);
+						}
+					}
+				},
+			},
+		},
+	});
+}
+
+export default createPlugin;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "preserve",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"noUncheckedIndexedAccess": true,
+		"verbatimModuleSyntax": true,
+		"skipLibCheck": true,
+		"rootDir": "src"
+	},
+	"include": ["src"]
+}