@damusix/ghost-mcp 0.3.0 → 0.4.1

package/dist/index.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -6,6 +7,8 @@ import { attempt } from "@logosdx/utils";
 import { FetchEngine, config, get } from "@logosdx/fetch";
 import mimeDb from "mime-db";
 import jwt from "jsonwebtoken";
+import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
 //#region src/ghost-client.ts
 const GHOST_URL = process.env.GHOST_URL || "";
 const GHOST_ADMIN_API_KEY = process.env.GHOST_ADMIN_API_KEY || "";
@@ -141,7 +144,11 @@ const postWriteFields = {
 		"draft",
 		"scheduled"
 	]).optional().describe("Post status"),
-	tags: z.array(z.union([z.object({ id: z.string() }), z.object({ name: z.string() })])).optional().describe("Tags to assign (by id or name)"),
+	tags: z.array(z.union([
+		z.string(),
+		z.object({ id: z.string() }),
+		z.object({ name: z.string() })
+	])).optional().describe("Tags to assign — a tag name string, or an object { id } or { name }"),
 	authors: z.array(z.object({ id: z.string() })).optional().describe("Authors to assign (by id)"),
 	featured: z.boolean().optional().describe("Whether the post is featured"),
 	visibility: z.string().optional().describe("Post visibility (public, members, paid, tiers)"),
@@ -293,7 +300,11 @@ const pageWriteFields = {
 		"draft",
 		"scheduled"
 	]).optional().describe("Page status"),
-	tags: z.array(z.union([z.object({ id: z.string() }), z.object({ name: z.string() })])).optional().describe("Tags to assign (by id or name)"),
+	tags: z.array(z.union([
+		z.string(),
+		z.object({ id: z.string() }),
+		z.object({ name: z.string() })
+	])).optional().describe("Tags to assign — a tag name string, or an object { id } or { name }"),
 	authors: z.array(z.object({ id: z.string() })).optional().describe("Authors to assign (by id)"),
 	featured: z.boolean().optional().describe("Whether the page is featured"),
 	visibility: z.string().optional().describe("Page visibility"),
@@ -678,7 +689,7 @@ const adminNewsletterActions = [
 ];
 //#endregion
 //#region src/actions/admin/offers.ts
-const browseParams$7 = z.object({}).describe("No parameters required");
+const browseParams$7 = z.object({ filter: z.string().optional().describe("NQL filter expression (e.g. \"status:active\" or \"status:archived\")") });
 const readParams$8 = z.object({ id: z.string().describe("Offer ID") });
 const addSchema$2 = z.object({
 	name: z.string().describe("Internal name for the offer (required)"),
@@ -710,7 +721,8 @@ const adminOfferActions = [
 		method: "GET",
 		path: "/offers/",
 		inputSchema: browseParams$7,
-		description: "Browse all offers"
+		description: "Browse all offers (Ghost returns the full list; filter by status)",
+		example: { filter: "status:active" }
 	},
 	{
 		name: "offers.read",
@@ -1293,7 +1305,32 @@ function initRegistry() {
 }
 initRegistry();
 //#endregion
+//#region src/koenig/util.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/tools/use-ghost-api.ts
+/**
+* Surface the Ghost API error body instead of just the HTTP status text.
+* `@logosdx/fetch` puts the parsed response on `err.data`; Ghost returns
+* `{ errors: [{ message, context, type, property, ... }] }`. Without this the
+* caller only sees "Unprocessable Entity" and cannot tell what actually failed.
+*/
+function formatApiError(err) {
+	if (isRecord(err)) {
+		const status = typeof err.status === "number" ? err.status : void 0;
+		if (isRecord(err.data) && Array.isArray(err.data.errors) && err.data.errors.length > 0) return JSON.stringify({
+			status,
+			errors: err.data.errors
+		});
+		if (typeof err.message === "string") return JSON.stringify({
+			status,
+			error: err.message
+		});
+	}
+	return JSON.stringify({ error: String(err) });
+}
 const extToMime = {};
 for (const [mime, meta] of Object.entries(mimeDb)) for (const ext of meta.extensions ?? []) extToMime[`.${ext}`] = mime;
 const useGhostApiSchema = z.object({
@@ -1356,30 +1393,30 @@ async function handleUseGhostApi(input, mode) {
 	if (actionDef.method === "GET") {
 		const queryParams = extractQueryParams(validPayload, usedPathParams);
 		const [response, err] = await attempt(async () => engine.get(path, { params: queryParams }));
-		if (err) return JSON.stringify({ error: err.message });
-		return JSON.stringify(response);
+		if (err) return formatApiError(err);
+		return JSON.stringify(response.data);
 	}
 	if (actionDef.method === "DELETE") {
 		const [response, err] = await attempt(async () => engine.delete(path));
-		if (err) return JSON.stringify({ error: err.message });
+		if (err) return formatApiError(err);
 		const resourcePrefix = `/${actionDef.name.split(".")[0]}`;
 		await engine.invalidatePath(resourcePrefix);
-		return JSON.stringify(response ?? { success: true });
+		return JSON.stringify(response?.data ?? { success: true });
 	}
 	const resourceKey = actionDef.name.split(".")[0];
 	const body = extractBodyPayload(validPayload, usedPathParams);
 	const wrappedBody = { [resourceKey]: [body] };
 	if (actionDef.method === "POST") {
 		const [response, err] = await attempt(async () => engine.post(path, wrappedBody));
-		if (err) return JSON.stringify({ error: err.message });
-		return JSON.stringify(response);
+		if (err) return formatApiError(err);
+		return JSON.stringify(response.data);
 	}
 	if (actionDef.method === "PUT") {
 		const [response, err] = await attempt(async () => engine.put(path, wrappedBody));
-		if (err) return JSON.stringify({ error: err.message });
+		if (err) return formatApiError(err);
 		const resourcePrefix = `/${actionDef.name.split(".")[0]}`;
 		await engine.invalidatePath(resourcePrefix);
-		return JSON.stringify(response);
+		return JSON.stringify(response.data);
 	}
 	return JSON.stringify({ error: `Unsupported method: ${actionDef.method}` });
 }
@@ -1405,8 +1442,8 @@ async function handleFileUpload(actionName, payload, path) {
 	const [response, err] = await attempt(async () => adminApi.post(path, formData, { onBeforeReq: (opts) => {
 		delete opts.headers["Content-Type"];
 	} }));
-	if (err) return JSON.stringify({ error: err.message });
-	return JSON.stringify(response);
+	if (err) return formatApiError(err);
+	return JSON.stringify(response.data);
 }
 //#endregion
 //#region src/tools/ghost-api-help.ts
@@ -1448,20 +1485,11 @@ const ghostDocsSchema = z.object({
 	search: z.string().optional().describe("Case-insensitive substring search across the documentation"),
 	regex: z.string().optional().describe("Regex pattern string to match (e.g. \"/pattern/i\")")
 });
-async function fetchDocs() {
-	const [response, err] = await attempt(async () => docsApi.get("/llms.txt"));
-	if (err) throw new Error(`Failed to fetch Ghost docs: ${err.message}`);
-	return response.data;
-}
 async function handleGhostDocs(input) {
 	const { all, search, regex } = input;
 	if (!all && !search && !regex) return "Provide one of: `all: true` to get full docs, `search` for text search, or `regex` for pattern matching.";
-	let content;
-	try {
-		content = await fetchDocs();
-	} catch (error) {
-		return `Error: ${error.message}`;
-	}
+	const response = await docsApi.get("/llms.txt");
+	const content = String(response.data);
 	if (all) return content;
 	const lines = content.split("\n");
 	const matchedLines = [];
@@ -1494,11 +1522,998 @@ async function handleGhostDocs(input) {
 	return matchedLines.join("\n");
 }
 //#endregion
+//#region src/koenig/inline.ts
+const FORMAT = {
+	bold: 1,
+	italic: 2,
+	strikethrough: 4,
+	underline: 8,
+	code: 16
+};
+function textNode(text, format = 0) {
+	return {
+		type: "extended-text",
+		version: 1,
+		text,
+		format,
+		mode: "normal",
+		style: "",
+		detail: 0
+	};
+}
+function linkNode(url, label) {
+	return {
+		type: "link",
+		version: 1,
+		direction: "ltr",
+		format: "",
+		indent: 0,
+		rel: null,
+		target: null,
+		title: null,
+		url,
+		children: [textNode(label)]
+	};
+}
+const TOKEN = /\[([^\]]+)\]\(([^)\s]+)\)|`([^`]+)`|\*\*([^*]+)\*\*|\*([^*]+)\*|(?<![\w])_([^_]+)_(?![\w])/g;
+function parseInline(input) {
+	const nodes = [];
+	let last = 0;
+	let m;
+	TOKEN.lastIndex = 0;
+	while ((m = TOKEN.exec(input)) !== null) {
+		if (m.index > last) nodes.push(textNode(input.slice(last, m.index)));
+		if (m[1] !== void 0) nodes.push(linkNode(m[2], m[1]));
+		else if (m[3] !== void 0) nodes.push(textNode(m[3], FORMAT.code));
+		else if (m[4] !== void 0) nodes.push(textNode(m[4], FORMAT.bold));
+		else if (m[5] !== void 0) nodes.push(textNode(m[5], FORMAT.italic));
+		else if (m[6] !== void 0) nodes.push(textNode(m[6], FORMAT.italic));
+		last = m.index + m[0].length;
+	}
+	if (last < input.length) nodes.push(textNode(input.slice(last)));
+	if (nodes.length === 0) nodes.push(textNode(input));
+	return nodes;
+}
+//#endregion
+//#region src/koenig/node-specs.ts
+const NODE_SPECS = {
+	audio: {
+		nodeType: "audio",
+		hasVisibility: false,
+		fields: {
+			duration: 0,
+			mimeType: "",
+			src: "",
+			title: "",
+			thumbnailSrc: ""
+		}
+	},
+	bookmark: {
+		nodeType: "bookmark",
+		hasVisibility: false,
+		fields: {
+			title: "",
+			description: "",
+			url: "",
+			caption: "",
+			author: "",
+			publisher: ""
+		}
+	},
+	button: {
+		nodeType: "button",
+		hasVisibility: false,
+		fields: {
+			buttonText: "",
+			alignment: "center",
+			buttonUrl: ""
+		}
+	},
+	"call-to-action": {
+		nodeType: "call-to-action",
+		hasVisibility: true,
+		fields: {
+			layout: "minimal",
+			alignment: "left",
+			textValue: "",
+			showButton: true,
+			showDividers: true,
+			buttonText: "Learn more",
+			buttonUrl: "",
+			buttonColor: "#000000",
+			buttonTextColor: "#ffffff",
+			hasSponsorLabel: true,
+			sponsorLabel: "<p><span style=\"white-space: pre-wrap;\">SPONSORED</span></p>",
+			backgroundColor: "grey",
+			linkColor: "text",
+			imageUrl: "",
+			imageWidth: null,
+			imageHeight: null
+		}
+	},
+	callout: {
+		nodeType: "callout",
+		hasVisibility: false,
+		fields: {
+			calloutText: "",
+			calloutEmoji: "💡",
+			backgroundColor: "blue"
+		}
+	},
+	codeblock: {
+		nodeType: "codeblock",
+		hasVisibility: false,
+		fields: {
+			code: "",
+			language: "",
+			caption: ""
+		}
+	},
+	email: {
+		nodeType: "email",
+		hasVisibility: false,
+		fields: { html: "" }
+	},
+	"email-cta": {
+		nodeType: "email-cta",
+		hasVisibility: false,
+		fields: {
+			alignment: "left",
+			buttonText: "",
+			buttonUrl: "",
+			html: "",
+			segment: "status:free",
+			showButton: false,
+			showDividers: true
+		}
+	},
+	embed: {
+		nodeType: "embed",
+		hasVisibility: false,
+		fields: {
+			url: "",
+			embedType: "",
+			html: "",
+			caption: ""
+		}
+	},
+	file: {
+		nodeType: "file",
+		hasVisibility: false,
+		fields: {
+			src: "",
+			fileTitle: "",
+			fileCaption: "",
+			fileName: "",
+			fileSize: 0
+		}
+	},
+	gallery: {
+		nodeType: "gallery",
+		hasVisibility: false,
+		fields: {
+			images: "[]",
+			caption: ""
+		}
+	},
+	header: {
+		nodeType: "header",
+		hasVisibility: false,
+		fields: {
+			size: "small",
+			style: "dark",
+			buttonEnabled: false,
+			buttonUrl: "",
+			buttonText: "",
+			header: "",
+			subheader: "",
+			backgroundImageSrc: "",
+			version: 1,
+			accentColor: "#FF1A75",
+			alignment: "center",
+			backgroundColor: "#000000",
+			backgroundImageWidth: null,
+			backgroundImageHeight: null,
+			backgroundSize: "cover",
+			textColor: "#FFFFFF",
+			buttonColor: "#ffffff",
+			buttonTextColor: "#000000",
+			layout: "full",
+			swapped: false
+		}
+	},
+	html: {
+		nodeType: "html",
+		hasVisibility: true,
+		fields: { html: "" }
+	},
+	image: {
+		nodeType: "image",
+		hasVisibility: false,
+		fields: {
+			src: "",
+			caption: "",
+			title: "",
+			alt: "",
+			cardWidth: "regular",
+			width: null,
+			height: null,
+			href: ""
+		}
+	},
+	markdown: {
+		nodeType: "markdown",
+		hasVisibility: false,
+		fields: { markdown: "" }
+	},
+	product: {
+		nodeType: "product",
+		hasVisibility: false,
+		fields: {
+			productImageSrc: "",
+			productImageWidth: null,
+			productImageHeight: null,
+			productTitle: "",
+			productDescription: "",
+			productRatingEnabled: false,
+			productStarRating: 5,
+			productButtonEnabled: false,
+			productButton: "",
+			productUrl: ""
+		}
+	},
+	signup: {
+		nodeType: "signup",
+		hasVisibility: false,
+		fields: {
+			alignment: "left",
+			backgroundColor: "#F0F0F0",
+			backgroundImageSrc: "",
+			backgroundSize: "cover",
+			textColor: "",
+			buttonColor: "accent",
+			buttonTextColor: "#FFFFFF",
+			buttonText: "Subscribe",
+			disclaimer: "",
+			header: "",
+			layout: "wide",
+			subheader: "",
+			successMessage: "Email sent! Check your inbox to complete your signup.",
+			swapped: false
+		}
+	},
+	toggle: {
+		nodeType: "toggle",
+		hasVisibility: false,
+		fields: {
+			heading: "",
+			content: ""
+		}
+	},
+	transistor: {
+		nodeType: "transistor",
+		hasVisibility: true,
+		fields: {
+			accentColor: "",
+			backgroundColor: ""
+		}
+	},
+	video: {
+		nodeType: "video",
+		hasVisibility: false,
+		fields: {
+			src: "",
+			caption: "",
+			fileName: "",
+			mimeType: "",
+			width: null,
+			height: null,
+			duration: 0,
+			thumbnailSrc: "",
+			customThumbnailSrc: "",
+			thumbnailWidth: null,
+			thumbnailHeight: null,
+			cardWidth: "regular",
+			loop: false
+		}
+	}
+};
+//#endregion
+//#region src/koenig/cards.ts
+function passthrough(def, fields) {
+	const spec = NODE_SPECS[def.nodeType];
+	const validFields = spec ? new Set(Object.keys(spec.fields)) : null;
+	const node = {};
+	for (const [key, value] of Object.entries(fields)) {
+		const target = def.aliases[key] ?? key;
+		if (validFields && !validFields.has(target)) {
+			const allowed = [...Object.keys(def.aliases), ...validFields ?? []].join(", ");
+			throw new Error(`unknown field "${key}" for card "${def.nodeType}". allowed: ${allowed}`);
+		}
+		node[target] = value;
+	}
+	return node;
+}
+/** keyed by the friendly block `type` the LLM writes */
+const CARDS = {
+	image: {
+		nodeType: "image",
+		version: 1,
+		group: "media",
+		description: "An image with optional caption, alt text, and link.",
+		required: ["src"],
+		aliases: {},
+		example: {
+			src: "https://example.com/photo.jpg",
+			alt: "A photo",
+			caption: "My caption"
+		}
+	},
+	gallery: {
+		nodeType: "gallery",
+		version: 1,
+		group: "media",
+		description: "A grid of images. Provide `images` as an array of { src, alt?, width?, height? }.",
+		required: ["images"],
+		aliases: {},
+		example: {
+			images: [{ src: "https://example.com/1.jpg" }, { src: "https://example.com/2.jpg" }],
+			caption: "Trip photos"
+		},
+		build(fields) {
+			const node = { images: (Array.isArray(fields.images) ? fields.images : []).map((img, i) => {
+				const o = isRecord(img) ? img : {};
+				return {
+					fileName: o.fileName ?? `image-${i}.jpg`,
+					row: o.row ?? 0,
+					src: o.src ?? "",
+					width: o.width ?? 0,
+					height: o.height ?? 0,
+					title: o.title ?? "",
+					alt: o.alt ?? ""
+				};
+			}) };
+			if (typeof fields.caption === "string") node.caption = fields.caption;
+			return node;
+		}
+	},
+	video: {
+		nodeType: "video",
+		version: 1,
+		group: "media",
+		description: "A video file. Needs `src`; `thumbnailSrc` sets the poster.",
+		required: ["src"],
+		aliases: { thumbnail: "thumbnailSrc" },
+		example: {
+			src: "https://example.com/clip.mp4",
+			caption: "A clip",
+			thumbnail: "https://example.com/poster.jpg"
+		}
+	},
+	audio: {
+		nodeType: "audio",
+		version: 1,
+		group: "media",
+		description: "An audio file with a title.",
+		required: ["src"],
+		aliases: { thumbnail: "thumbnailSrc" },
+		example: {
+			src: "https://example.com/track.mp3",
+			title: "Episode 1",
+			duration: 320
+		}
+	},
+	file: {
+		nodeType: "file",
+		version: 1,
+		group: "media",
+		description: "A downloadable file card.",
+		required: ["src"],
+		aliases: {
+			title: "fileTitle",
+			name: "fileName",
+			caption: "fileCaption",
+			size: "fileSize"
+		},
+		example: {
+			src: "https://example.com/guide.pdf",
+			title: "Whitepaper",
+			caption: "Download our guide"
+		}
+	},
+	bookmark: {
+		nodeType: "bookmark",
+		version: 1,
+		group: "embed",
+		description: "A rich link preview. Provide `url`; optionally title/description/author/publisher/icon/thumbnail.",
+		required: ["url"],
+		aliases: {},
+		example: {
+			url: "https://ghost.org",
+			title: "Ghost",
+			description: "Publishing platform"
+		},
+		build(fields) {
+			const metaKeys = [
+				"title",
+				"description",
+				"author",
+				"publisher",
+				"icon",
+				"thumbnail"
+			];
+			const metadata = { url: fields.url };
+			for (const k of metaKeys) metadata[k] = fields[k] ?? (k === "author" ? null : "");
+			return {
+				url: fields.url,
+				caption: fields.caption ?? "",
+				metadata
+			};
+		}
+	},
+	embed: {
+		nodeType: "embed",
+		version: 1,
+		group: "embed",
+		description: "An external embed (YouTube, Twitter, etc.). Provide `url` and the embed `html`.",
+		required: ["url"],
+		aliases: {},
+		example: {
+			url: "https://youtube.com/watch?v=abc",
+			embedType: "video",
+			html: "<iframe src=\"...\"></iframe>"
+		}
+	},
+	html: {
+		nodeType: "html",
+		version: 1,
+		group: "embed",
+		description: "Raw HTML passthrough. Use only when no native card fits.",
+		required: ["html"],
+		aliases: {},
+		example: { html: "<div class=\"custom\">Raw HTML</div>" }
+	},
+	markdown: {
+		nodeType: "markdown",
+		version: 1,
+		group: "embed",
+		description: "A markdown block (rendered as one unit). Prefer paragraph/heading/list blocks for editable prose.",
+		required: ["markdown"],
+		aliases: { text: "markdown" },
+		example: { markdown: "## Heading\n\nSome **markdown**." }
+	},
+	codeblock: {
+		nodeType: "codeblock",
+		version: 1,
+		group: "embed",
+		description: "A syntax-highlighted code block.",
+		required: ["code"],
+		aliases: { lang: "language" },
+		example: {
+			code: "const x = 1;",
+			language: "javascript",
+			caption: "snippet"
+		}
+	},
+	callout: {
+		nodeType: "callout",
+		version: 1,
+		group: "layout",
+		description: "A highlighted callout box with an emoji and background color.",
+		required: ["text"],
+		aliases: {
+			text: "calloutText",
+			emoji: "calloutEmoji",
+			color: "backgroundColor"
+		},
+		example: {
+			text: "Heads up!",
+			emoji: "💡",
+			color: "blue"
+		}
+	},
+	toggle: {
+		nodeType: "toggle",
+		version: 1,
+		group: "layout",
+		description: "A collapsible accordion. `content` is HTML. (No-op in email.)",
+		required: ["heading"],
+		aliases: {},
+		example: {
+			heading: "Click to expand",
+			content: "<p>Hidden content.</p>"
+		}
+	},
+	button: {
+		nodeType: "button",
+		version: 1,
+		group: "layout",
+		description: "A call-to-action button.",
+		required: ["text", "url"],
+		aliases: {
+			text: "buttonText",
+			url: "buttonUrl"
+		},
+		example: {
+			text: "Subscribe",
+			url: "https://example.com",
+			alignment: "center"
+		}
+	},
+	header: {
+		nodeType: "header",
+		version: 2,
+		group: "layout",
+		description: "A large hero header with optional background image and button.",
+		required: [],
+		aliases: { title: "header" },
+		example: {
+			header: "Big Header",
+			subheader: "A subheader",
+			buttonEnabled: true,
+			buttonText: "Start",
+			buttonUrl: "https://example.com"
+		}
+	},
+	cta: {
+		nodeType: "call-to-action",
+		version: 1,
+		group: "layout",
+		description: "A call-to-action card with text, optional image and button. `text` accepts HTML or plain text.",
+		required: [],
+		aliases: { buttonColor: "buttonColor" },
+		example: {
+			text: "Subscribe for more.",
+			buttonText: "Join",
+			buttonUrl: "https://example.com",
+			showButton: true
+		},
+		build(fields) {
+			const node = {};
+			for (const k of [
+				"layout",
+				"alignment",
+				"showButton",
+				"showDividers",
+				"buttonText",
+				"buttonUrl",
+				"buttonColor",
+				"buttonTextColor",
+				"hasSponsorLabel",
+				"sponsorLabel",
+				"backgroundColor",
+				"linkColor",
+				"imageUrl",
+				"imageWidth",
+				"imageHeight",
+				"visibility"
+			]) if (k in fields) node[k] = fields[k];
+			if (typeof fields.text === "string") node.textValue = /^\s*</.test(fields.text) ? fields.text : `<p>${fields.text}</p>`;
+			return node;
+		}
+	},
+	signup: {
+		nodeType: "signup",
+		version: 1,
+		group: "membership",
+		description: "A member signup form. (No-op in email.)",
+		required: [],
+		aliases: {},
+		example: {
+			header: "Subscribe",
+			subheader: "Join the newsletter",
+			disclaimer: "No spam."
+		}
+	},
+	product: {
+		nodeType: "product",
+		version: 1,
+		group: "layout",
+		description: "A product card with image, rating, and button.",
+		required: ["productTitle"],
+		aliases: {
+			title: "productTitle",
+			description: "productDescription",
+			image: "productImageSrc",
+			button: "productButton",
+			url: "productUrl",
+			rating: "productStarRating"
+		},
+		example: {
+			title: "The Product",
+			description: "A great product.",
+			rating: 5,
+			button: "Buy",
+			url: "https://example.com",
+			productButtonEnabled: true,
+			productRatingEnabled: true
+		}
+	},
+	divider: {
+		nodeType: "horizontalrule",
+		version: 1,
+		group: "divider",
+		description: "A horizontal rule / divider.",
+		required: [],
+		aliases: {},
+		example: {},
+		build() {
+			return {};
+		}
+	},
+	paywall: {
+		nodeType: "paywall",
+		version: 1,
+		group: "membership",
+		description: "Splits free vs members-only content. Everything after it is members-only.",
+		required: [],
+		aliases: {},
+		example: {},
+		build() {
+			return {};
+		}
+	},
+	email: {
+		nodeType: "email",
+		version: 1,
+		group: "email-only",
+		description: "Content shown ONLY in the email newsletter (empty on web). `html` supports {first_name, \"fallback\"}.",
+		required: ["html"],
+		aliases: {},
+		example: { html: "<p>Hello {first_name, \"there\"}!</p>" }
+	},
+	"email-cta": {
+		nodeType: "email-cta",
+		version: 1,
+		group: "email-only",
+		description: "A newsletter-only call to action targeting a member segment.",
+		required: [],
+		aliases: {},
+		example: {
+			html: "<p>Read more.</p>",
+			buttonText: "Read",
+			buttonUrl: "https://example.com",
+			segment: "status:free"
+		}
+	}
+};
+function buildCardNode(blockType, fields) {
+	const def = CARDS[blockType];
+	if (!def) throw new Error(`unknown card type "${blockType}"`);
+	for (const r of def.required) if (fields[r] === void 0 || fields[r] === null || fields[r] === "") throw new Error(`card "${blockType}" requires field "${r}"`);
+	const data = def.build ? def.build(fields) : passthrough(def, fields);
+	return {
+		type: def.nodeType,
+		version: def.version,
+		...data
+	};
+}
+function isCardType(blockType) {
+	return blockType in CARDS;
+}
+//#endregion
+//#region src/koenig/blocks.ts
+const ELEMENT = {
+	direction: "ltr",
+	format: "",
+	indent: 0
+};
+function element(type, extra, children) {
+	return {
+		type,
+		version: 1,
+		...ELEMENT,
+		...extra,
+		children
+	};
+}
+function asString(value, field, blockType) {
+	if (typeof value !== "string") throw new Error(`block "${blockType}" field "${field}" must be a string`);
+	return value;
+}
+function buildProse(block) {
+	switch (block.type) {
+		case "paragraph": return element("paragraph", {}, parseInline(asString(block.text, "text", "paragraph")));
+		case "heading": return element("extended-heading", { tag: `h${typeof block.level === "number" ? Math.min(6, Math.max(1, block.level)) : 2}` }, parseInline(asString(block.text, "text", "heading")));
+		case "quote": return element("extended-quote", {}, parseInline(asString(block.text, "text", "quote")));
+		case "aside": return element("aside", {}, parseInline(asString(block.text, "text", "aside")));
+		case "list": {
+			const items = Array.isArray(block.items) ? block.items : [];
+			if (items.length === 0) throw new Error("block \"list\" requires a non-empty \"items\" array");
+			const ordered = block.style === "number" || block.style === "ordered";
+			const children = items.map((item, i) => element("listitem", { value: i + 1 }, parseInline(String(item))));
+			return element("list", {
+				listType: ordered ? "number" : "bullet",
+				tag: ordered ? "ol" : "ul",
+				start: 1
+			}, children);
+		}
+		default: return null;
+	}
+}
+function isBlock(value) {
+	return isRecord(value) && typeof value.type === "string";
+}
+function buildBlock(block) {
+	if (!isBlock(block)) throw new Error("each block must be an object with a string \"type\"");
+	const prose = buildProse(block);
+	if (prose) return prose;
+	if (isCardType(block.type)) {
+		const { type, ...fields } = block;
+		return buildCardNode(type, fields);
+	}
+	throw new Error(`unknown block type "${block.type}". valid types: ${[...PROSE_TYPES, ...Object.keys(CARDS)].join(", ")}`);
+}
+const PROSE_TYPES = [
+	"paragraph",
+	"heading",
+	"list",
+	"quote",
+	"aside"
+];
+//#endregion
+//#region src/koenig/compose.ts
+var ComposeError = class extends Error {
+	constructor(issues) {
+		const detail = issues.map((i) => `[#${i.index} ${i.type}] ${i.message}`).join("; ");
+		super(`composition failed (${issues.length} issue${issues.length === 1 ? "" : "s"}): ${detail}`);
+		this.issues = issues;
+		this.name = "ComposeError";
+	}
+};
+function composeRoot(blocks) {
+	if (!Array.isArray(blocks) || blocks.length === 0) throw new ComposeError([{
+		index: -1,
+		type: "(none)",
+		message: "blocks must be a non-empty array"
+	}]);
+	const children = [];
+	const issues = [];
+	blocks.forEach((block, index) => {
+		try {
+			children.push(buildBlock(block));
+		} catch (error) {
+			issues.push({
+				index,
+				type: isRecord(block) && typeof block.type === "string" ? block.type : "(invalid)",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		}
+	});
+	if (issues.length > 0) throw new ComposeError(issues);
+	return { root: {
+		type: "root",
+		version: 1,
+		direction: "ltr",
+		format: "",
+		indent: 0,
+		children
+	} };
+}
+function compose(blocks) {
+	return JSON.stringify(composeRoot(blocks));
+}
+//#endregion
+//#region src/koenig/help.ts
+const PROSE = [
+	{
+		type: "paragraph",
+		description: "A text paragraph. `text` supports inline **bold**, _italic_, `code`, [links](url).",
+		example: {
+			type: "paragraph",
+			text: "Some **bold** and a [link](https://x.com)."
+		}
+	},
+	{
+		type: "heading",
+		description: "A heading. `level` 1–6 (default 2). `text` supports inline markdown.",
+		example: {
+			type: "heading",
+			level: 2,
+			text: "Section title"
+		}
+	},
+	{
+		type: "list",
+		description: "A bullet or numbered list. `style`: \"bullet\" (default) or \"number\". `items` is a string array (inline markdown supported).",
+		example: {
+			type: "list",
+			style: "bullet",
+			items: ["First", "Second"]
+		}
+	},
+	{
+		type: "quote",
+		description: "A blockquote. `text` supports inline markdown.",
+		example: {
+			type: "quote",
+			text: "A memorable quote."
+		}
+	},
+	{
+		type: "aside",
+		description: "A pull-quote / aside.",
+		example: {
+			type: "aside",
+			text: "An aside."
+		}
+	}
+];
+function blockHelp(blockType) {
+	if (blockType) {
+		const prose = PROSE.find((p) => p.type === blockType);
+		if (prose) return [
+			`# block: ${prose.type}`,
+			"",
+			prose.description,
+			"",
+			"```json",
+			JSON.stringify(prose.example, null, 2),
+			"```"
+		].join("\n");
+		const card = CARDS[blockType];
+		if (!card) return `Unknown block type "${blockType}". Run koenig_help with no argument to list all block types.`;
+		const example = {
+			type: blockType,
+			...card.example
+		};
+		const lines = [
+			`# block: ${blockType}`,
+			"",
+			`${card.description}`,
+			"",
+			`- Lexical node: \`${card.nodeType}\` (version ${card.version})`,
+			card.required.length ? `- Required fields: ${card.required.map((r) => `\`${r}\``).join(", ")}` : "- Required fields: none"
+		];
+		if (Object.keys(card.aliases).length) lines.push(`- Aliases: ${Object.entries(card.aliases).map(([f, t]) => `\`${f}\`→\`${t}\``).join(", ")}`);
+		lines.push("", "```json", JSON.stringify(example, null, 2), "```");
+		return lines.join("\n");
+	}
+	const lines = [
+		"# Koenig block types",
+		"",
+		"Compose posts from these blocks instead of raw HTML — they produce clean, natively-editable Ghost content.",
+		"",
+		"## Prose (native, inline markdown in `text`)"
+	];
+	for (const p of PROSE) lines.push(`- **${p.type}** — ${p.description}`);
+	const byGroup = {};
+	for (const [type, def] of Object.entries(CARDS)) (byGroup[def.group] ??= []).push(`- **${type}** — ${def.description}`);
+	for (const [group, entries] of Object.entries(byGroup)) {
+		lines.push("", `## ${group}`);
+		lines.push(...entries);
+	}
+	lines.push("", "Use `koenig_help` with a `block` name for fields + a JSON example. Then call `compose_post` (creates the post) or `compose_lexical` (returns the lexical string).");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/tools/blocks-source.ts
+function extractBlocks(parsed) {
+	if (Array.isArray(parsed)) return parsed;
+	if (isRecord(parsed) && Array.isArray(parsed.blocks)) return parsed.blocks;
+	return null;
+}
+function resolveBlocks(src) {
+	const hasFile = typeof src.blockFile === "string" && src.blockFile.trim() !== "";
+	if (Array.isArray(src.blocks)) {
+		if (hasFile) throw new Error("provide either \"blocks\" or \"blockFile\", not both");
+		return src.blocks;
+	}
+	if (!hasFile) throw new Error("provide \"blocks\" (inline array) or \"blockFile\" (absolute path to a JSON file of blocks)");
+	const file = src.blockFile;
+	if (typeof file !== "string") throw new Error("blockFile must be a string path");
+	if (!isAbsolute(file)) throw new Error(`blockFile must be an absolute path (got "${file}"). Write the JSON to an absolute path, e.g. under your tmp/ directory.`);
+	let raw;
+	try {
+		raw = readFileSync(file, "utf8");
+	} catch {
+		throw new Error(`could not read blockFile: ${file}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error(`blockFile is not valid JSON: ${file}`);
+	}
+	const blocks = extractBlocks(parsed);
+	if (!blocks) throw new Error(`blockFile must contain a JSON array of blocks, or { "blocks": [...] }: ${file}`);
+	return blocks;
+}
+//#endregion
+//#region src/tools/compose-post.ts
+const blockSchema = z.object({ type: z.string().describe("Block type: paragraph, heading, list, quote, aside, image, gallery, video, audio, file, bookmark, embed, html, markdown, codeblock, callout, toggle, button, header, cta, signup, product, divider, paywall, email, email-cta. Run koenig_help for fields.") }).passthrough();
+const composeFields = {
+	blocks: z.array(blockSchema).optional().describe("Ordered content blocks (inline). Prefer native blocks (paragraph/heading/list/quote) and cards over raw html. Prose `text` supports inline **bold**, _italic_, `code`, [links](url). Use koenig_help to discover block fields. For long posts, write the blocks to a JSON file and pass `blockFile` instead."),
+	blockFile: z.string().optional().describe("Absolute path to a local JSON file containing the blocks — either a bare array `[...]` or `{ \"blocks\": [...] }`. Use this for long posts: compose/edit the file (validating with compose_lexical), then pass the path instead of re-sending the whole array. Provide exactly one of `blocks` or `blockFile`. Writing to an absolute path under tmp/ is recommended."),
+	title: z.string().optional().describe("Post title (required when creating a new post)"),
+	id: z.string().optional().describe("Post ID to update. Omit to create a new post."),
+	updated_at: z.string().optional().describe("Required when updating (id set): the post's current updated_at, for collision detection. Get it via posts.read."),
+	status: z.enum([
+		"published",
+		"draft",
+		"scheduled"
+	]).optional().describe("Post status (default draft)"),
+	tags: z.array(z.union([z.object({ id: z.string() }), z.object({ name: z.string() })])).optional().describe("Tags to assign (by id or name)"),
+	feature_image: z.string().optional().describe("Feature image URL"),
+	excerpt: z.string().optional().describe("Custom excerpt (maps to custom_excerpt)"),
+	slug: z.string().optional().describe("Custom URL slug"),
+	visibility: z.string().optional().describe("public, members, paid, or tiers")
+};
+const composePostSchema = z.object(composeFields);
+async function handleComposePost(input, mode) {
+	let lexical;
+	try {
+		lexical = compose(resolveBlocks({
+			blocks: input.blocks,
+			blockFile: input.blockFile
+		}));
+	} catch (error) {
+		if (error instanceof ComposeError) return JSON.stringify({
+			error: "composition failed",
+			issues: error.issues
+		});
+		return JSON.stringify({
+			error: "invalid blocks input",
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+	const { blocks: _blocks, blockFile: _blockFile, id, excerpt, ...rest } = input;
+	const payload = {
+		...rest,
+		lexical
+	};
+	if (excerpt !== void 0) payload.custom_excerpt = excerpt;
+	if (id) return handleUseGhostApi({
+		api: "admin",
+		action: "posts.edit",
+		payload: {
+			id,
+			...payload
+		}
+	}, mode);
+	return handleUseGhostApi({
+		api: "admin",
+		action: "posts.add",
+		payload
+	}, mode);
+}
+//#endregion
+//#region src/tools/compose-lexical.ts
+const composeLexicalSchema = z.object({
+	blocks: z.array(z.object({ type: z.string() }).passthrough()).optional().describe("Ordered content blocks (same shape as compose_post), inline."),
+	blockFile: z.string().optional().describe("Absolute path to a JSON file of blocks. Use to validate a file you are building before calling compose_post. Provide exactly one of `blocks` or `blockFile`.")
+});
+function handleComposeLexical(input) {
+	try {
+		const lexical = compose(resolveBlocks({
+			blocks: input.blocks,
+			blockFile: input.blockFile
+		}));
+		return JSON.stringify({ lexical });
+	} catch (error) {
+		if (error instanceof ComposeError) return JSON.stringify({
+			error: "composition failed",
+			issues: error.issues
+		});
+		return JSON.stringify({
+			error: "invalid blocks input",
+			message: error instanceof Error ? error.message : String(error)
+		});
+	}
+}
+//#endregion
+//#region src/tools/koenig-help.ts
+const koenigHelpSchema = z.object({ block: z.string().optional().describe("A block type (e.g. \"callout\", \"image\") for its fields + a JSON example. Omit to list all block types.") });
+function handleKoenigHelp(input) {
+	return blockHelp(input.block);
+}
+const VERSION = createRequire(import.meta.url)("../package.json").version;
+//#endregion
 //#region src/index.ts
 const GHOST_API_MODE = process.env.GHOST_API_MODE || "admin";
 const server = new McpServer({
 	name: "ghost-mcp",
-	version: "0.1.0"
+	version: VERSION
 });
 server.tool("use_ghost_api", "Execute a Ghost API action (browse, read, add, edit, delete posts, pages, tags, members, newsletters, and more)", useGhostApiSchema.shape, async ({ api, action, payload }) => {
 	return { content: [{
@@ -1529,6 +2544,36 @@ server.tool("ghost_docs", "Search Ghost CMS documentation — fetch full docs, s
 		})
 	}] };
 });
+server.tool("compose_post", "Create or update a Ghost post from structured Koenig content blocks (paragraphs, headings, lists, callouts, images, buttons, etc.). PREFER THIS over use_ghost_api with raw html/lexical — it produces clean, natively-editable posts. Pass blocks inline for short posts, or write them to a JSON file and pass `blockFile` (absolute path) for long posts. Omit `id` to create, set `id`+`updated_at` to update. Call koenig_help to discover block types and fields.", composePostSchema.shape, async (input) => {
+	return { content: [{
+		type: "text",
+		text: await handleComposePost(input, GHOST_API_MODE)
+	}] };
+});
+server.tool("compose_lexical", "Compile Koenig content blocks into a Lexical JSON string without creating a post (for preview/inspection). Same block shape as compose_post.", composeLexicalSchema.shape, async (input) => {
+	return { content: [{
+		type: "text",
+		text: handleComposeLexical(input)
+	}] };
+});
+server.tool("koenig_help", "List Koenig content block types, or get the fields and a JSON example for one block. Use before compose_post to build clean, editable posts instead of raw HTML.", koenigHelpSchema.shape, async ({ block }) => {
+	return { content: [{
+		type: "text",
+		text: handleKoenigHelp({ block })
+	}] };
+});
+server.registerPrompt("compose_ghost_post", { description: "Guidance for composing clean, editable Ghost posts from Koenig blocks instead of raw HTML." }, () => ({ messages: [{
+	role: "assistant",
+	content: {
+		type: "text",
+		text: [
+			"When writing Ghost post content, do NOT push raw HTML into the API. Compose the post from structured Koenig blocks via the `compose_post` tool — this yields clean, natively-editable posts.",
+			"Workflow: (1) call `koenig_help` to see block types; (2) build a `blocks` array — prose as paragraph/heading/list/quote blocks (their `text` supports inline **bold**, _italic_, `code`, [links](url)), and rich features as cards (callout, image, button, bookmark, embed, codeblock, toggle, gallery, etc.); (3) call `compose_post`. Use the `html` block ONLY when no native block fits.",
+			"For a short post, pass `blocks` inline. For a long post, write the blocks JSON to an absolute path (e.g. under tmp/), optionally validate it with `compose_lexical` (`blockFile`), then call `compose_post` with `blockFile` — this avoids re-sending the whole array on each edit.",
+			blockHelp()
+		].join("\n\n")
+	}
+}] }));
 async function main() {
 	const transport = new StdioServerTransport();
 	await server.connect(transport);