@damusix/ghost-mcp 0.4.0 → 0.5.0

package/README.md

@@ -158,6 +158,24 @@ Search Ghost documentation via `docs.ghost.org/llms.txt`.
 - **Admin mode** (default): Full access to all Ghost Admin API and Content API actions. Requires `GHOST_ADMIN_API_KEY`.
 - **Content mode**: Read-only access to Content API actions only. Requires `GHOST_CONTENT_API_KEY`. Admin actions are rejected with a clear error.
 
+## Bundled skill: `ghost-writing`
+
+The package ships an [Agent Skill](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
+at [`skills/ghost-writing/`](skills/ghost-writing/SKILL.md) that pairs with the
+MCP server: which tool to use when, the full Koenig block catalog with guidance
+on choosing between similar blocks, and best practices for structuring good
+posts (drafting workflow, long-post `blockFile` iteration, publishing,
+newsletters, members-only content).
+
+Install it:
+
+```bash
+npx skills add damusix/ghost-mcp
+```
+
+Claude picks it up automatically the next time a conversation involves writing
+Ghost posts.
+
 ## Development
 
 Spin up a throwaway Ghost 6 + MySQL 8 stack to exercise the server against a

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";
@@ -143,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)"),
@@ -295,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"),
@@ -680,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)"),
@@ -712,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",
@@ -1295,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({
@@ -1358,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}` });
 }
@@ -1407,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
@@ -1784,11 +1819,6 @@ const NODE_SPECS = {
 	}
 };
 //#endregion
-//#region src/koenig/util.ts
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
 //#region src/koenig/cards.ts
 function passthrough(def, fields) {
 	const spec = NODE_SPECS[def.nodeType];
@@ -2477,12 +2507,13 @@ const koenigHelpSchema = z.object({ block: z.string().optional().describe("A blo
 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: [{