@oksigenia/ghost-mcp 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.env.example ADDED
@@ -0,0 +1,8 @@
1
+ # Connection to your Ghost site (the MCP client usually injects these as env vars;
2
+ # a local .env is only for development/testing).
3
+ GHOST_URL=https://your-site.com
4
+ GHOST_ADMIN_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx:yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
5
+ GHOST_API_VERSION=v5.0
6
+
7
+ # Default author (slug or email) for created posts, optional.
8
+ DEFAULT_AUTHOR_SLUG=
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Oksigenia SL
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,87 @@
1
+ # @oksigenia/ghost-mcp
2
+
3
+ A [Model Context Protocol](https://modelcontextprotocol.io) server for **Ghost**, aware of the **Xpresiva** theme. Operate your Ghost content by talking to an AI — locally, with no telemetry, straight against your own Ghost.
4
+
5
+ https://github.com/user-attachments/assets/8f252db7-9198-48e2-b2f4-42fd408a349d
6
+
7
+ It reuses the [`ghost-md-publisher`](https://github.com/OksigeniaSL/ghost-md-publisher) toolkit, so the MCP and the CLI share the same building blocks: the Admin API client, Markdown → native Ghost cards (callouts, bookmarks, video embeds, image captions), image processing (resize + EXIF clean) and the safe upsert.
8
+
9
+ ## Requirements
10
+
11
+ - Node.js 20.9+
12
+ - A Ghost site with an Admin API key (Settings → Integrations → Add custom integration).
13
+
14
+ ## Install & build
15
+
16
+ ```bash
17
+ npm install
18
+ npm run build
19
+ ```
20
+
21
+ ## Configure your MCP client
22
+
23
+ Point your MCP client at the built server and pass your Ghost credentials as env. Example (Claude Desktop `claude_desktop_config.json`):
24
+
25
+ ```json
26
+ {
27
+ "mcpServers": {
28
+ "ghost": {
29
+ "command": "node",
30
+ "args": ["/absolute/path/to/oksigenia-ghost-mcp/dist/index.js"],
31
+ "env": {
32
+ "GHOST_URL": "https://your-site.com",
33
+ "GHOST_ADMIN_API_KEY": "id:secret",
34
+ "GHOST_API_VERSION": "v5.0"
35
+ }
36
+ }
37
+ }
38
+ }
39
+ ```
40
+
41
+ ## Tools
42
+
43
+ Content ops:
44
+
45
+ | Tool | Kind | What it does |
46
+ |---|---|---|
47
+ | `verify_connection` | read | Check the connection and return basic site info. |
48
+ | `list_posts` | read | List posts (filter by status/tag). |
49
+ | `get_post` | read | Fetch a post by id or slug, with its HTML, tags and authors. |
50
+ | `list_tags` | read | List all tags with post counts. |
51
+ | `create_post` | write | Create a post from Markdown (draft by default). Processes local images. Stops if the slug already exists. |
52
+ | `update_post` | write | Update the post with a given slug (preserves its status). |
53
+ | `upload_image` | write | Process and upload a local image, returns the hosted URL. |
54
+
55
+ Xpresiva-aware:
56
+
57
+ | Tool | Kind | What it does |
58
+ |---|---|---|
59
+ | `xpresiva_check_post` | read | Suggestions for a post: valid `custom_template`, feature-image coherence, alt text, excerpt length, reading time. |
60
+ | `audit_site` | read | Scan recent posts and flag issues (no feature image, non-Xpresiva template, missing alt, stale drafts). |
61
+ | `set_custom_template` | write | Set or clear a post's Xpresiva `custom_template`. |
62
+
63
+ Multilingual:
64
+
65
+ | Tool | Kind | What it does |
66
+ |---|---|---|
67
+ | `publish_translation_set` | write | Create/update several language versions of one article, linked as an Xpresiva translation group (language tag `#es`/`#fr`/… + a shared pairing tag). Does not translate — you provide each version. |
68
+
69
+ The Markdown accepts the same extras as the CLI: `::video <url>`, `::bookmark <url>` (fetches OpenGraph metadata), and Obsidian-style callouts `> [!warning] ...` → native Ghost cards.
70
+
71
+ > Note: Ghost's Admin API does not expose the theme's `custom_theme_settings` to integration tokens (it returns 403), so "Xpresiva-aware" means the theme's baked-in conventions (template names, the 7 locales, the pairing-tag scheme), not reading the live theme config. Per-card member/paid visibility of callouts lives in the Ghost editor model, not the HTML, so it isn't set through this server.
72
+
73
+ ### Guardrails
74
+
75
+ - New posts are created as **drafts** by default.
76
+ - `create_post` **never overwrites** an existing slug — it stops and points you to `update_post`.
77
+ - No hard-delete tool.
78
+ - Everything runs locally against your own Ghost. No telemetry.
79
+
80
+ ## Roadmap
81
+
82
+ - Scheduling helpers and richer audits.
83
+ - Inline local-image handling improvements.
84
+
85
+ ## License
86
+
87
+ MIT © Oksigenia
package/dist/index.js ADDED
@@ -0,0 +1,448 @@
1
+ #!/usr/bin/env node
2
+
3
+ // src/index.ts
4
+ import dotenv from "dotenv";
5
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
6
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
7
+ import { z } from "zod";
8
+
9
+ // src/ghost.ts
10
+ import { getClient, verifyClient } from "@oksigenia/ghost-md-publisher/lib/ghost-client";
11
+ import { upsertPost } from "@oksigenia/ghost-md-publisher/lib/posts";
12
+ import { render } from "@oksigenia/ghost-md-publisher/lib/markdown";
13
+ import { resolveBookmarks } from "@oksigenia/ghost-md-publisher/lib/bookmarks";
14
+ import { findLocalImages, uploadAll, rewriteContent } from "@oksigenia/ghost-md-publisher/lib/images";
15
+ import { processImage } from "@oksigenia/ghost-md-publisher/lib/image-processing";
16
+ var _client = null;
17
+ function client() {
18
+ if (!_client) _client = getClient();
19
+ return _client;
20
+ }
21
+ var XPRESIVA_TEMPLATES = ["custom-wide-feature-image", "custom-full-feature-image"];
22
+ var XPRESIVA_LOCALES = ["en", "es", "fr", "de", "pt", "it", "nl"];
23
+ var RESERVED_INTERNAL = /* @__PURE__ */ new Set([
24
+ ...XPRESIVA_LOCALES.map((l) => `hash-${l}`),
25
+ "hash-historical"
26
+ ]);
27
+ function readingTime(html) {
28
+ const words = (html || "").replace(/<[^>]+>/g, " ").trim().split(/\s+/).filter(Boolean).length;
29
+ return Math.max(1, Math.round(words / 200));
30
+ }
31
+ async function verify() {
32
+ const c = client();
33
+ await verifyClient(c);
34
+ let site = void 0;
35
+ try {
36
+ site = await c.site.read();
37
+ } catch {
38
+ }
39
+ return { ok: true, site };
40
+ }
41
+ async function listPosts(args) {
42
+ const filters = [];
43
+ if (args.status && args.status !== "all") filters.push(`status:${args.status}`);
44
+ if (args.tag) filters.push(`tag:${args.tag}`);
45
+ const res = await client().posts.browse({
46
+ filter: filters.join("+") || void 0,
47
+ limit: args.limit ?? 15,
48
+ order: "updated_at DESC",
49
+ fields: "id,title,slug,status,updated_at,published_at,url,visibility"
50
+ });
51
+ return res.map((p) => ({
52
+ id: p.id,
53
+ title: p.title,
54
+ slug: p.slug,
55
+ status: p.status,
56
+ updated_at: p.updated_at,
57
+ url: p.url
58
+ }));
59
+ }
60
+ async function getPost(args) {
61
+ if (!args.id && !args.slug) throw new Error("Provide either id or slug.");
62
+ const key = args.id ? { id: args.id } : { slug: args.slug };
63
+ const p = await client().posts.read({ ...key, formats: "html" }, { include: "tags,authors" });
64
+ return {
65
+ id: p.id,
66
+ title: p.title,
67
+ slug: p.slug,
68
+ status: p.status,
69
+ url: p.url,
70
+ updated_at: p.updated_at,
71
+ published_at: p.published_at,
72
+ custom_template: p.custom_template,
73
+ feature_image: p.feature_image,
74
+ excerpt: p.custom_excerpt,
75
+ tags: (p.tags || []).map((t) => t.name),
76
+ authors: (p.authors || []).map((a) => a.slug),
77
+ html: p.html
78
+ };
79
+ }
80
+ async function uploadImage(args) {
81
+ const c = client();
82
+ const processed = await processImage(args.path, {
83
+ enabled: true,
84
+ maxWidth: args.max_width ?? 1920,
85
+ format: args.format ?? "auto",
86
+ quality: args.quality ?? 82,
87
+ exif: { Software: "ghost-mcp" }
88
+ });
89
+ const toUpload = typeof processed === "string" ? processed : processed.path;
90
+ const res = await c.images.upload({ file: toUpload, purpose: "image" });
91
+ return { url: res.url };
92
+ }
93
+ async function listTags() {
94
+ const res = await client().tags.browse({ limit: "all", fields: "id,name,slug,visibility,count" });
95
+ return res.map((t) => ({ name: t.name, slug: t.slug, visibility: t.visibility, count: t.count?.posts }));
96
+ }
97
+ async function writePost(args) {
98
+ const c = client();
99
+ const data = {
100
+ title: args.title,
101
+ slug: args.slug,
102
+ status: args.status ?? "draft",
103
+ tags: args.tags ?? [],
104
+ excerpt: args.excerpt,
105
+ feature_image: args.feature_image,
106
+ feature_image_alt: args.feature_image_alt,
107
+ template: args.custom_template,
108
+ author: args.author,
109
+ published_at: args.published_at
110
+ };
111
+ let body = args.markdown;
112
+ const baseDir = args.base_dir || process.cwd();
113
+ const images = findLocalImages(body, data, baseDir);
114
+ if (images.length) {
115
+ const processingConfig = {
116
+ enabled: true,
117
+ maxWidth: 1920,
118
+ format: "auto",
119
+ quality: 82,
120
+ exif: {
121
+ Copyright: process.env.IMAGE_COPYRIGHT || "",
122
+ Artist: process.env.IMAGE_ARTIST || args.author || "",
123
+ Software: "ghost-mcp",
124
+ ImageDescription: args.title || ""
125
+ }
126
+ };
127
+ const urlMap = await uploadAll(c, images, { dryRun: false, processingConfig, perImageMeta: {} });
128
+ body = rewriteContent(body, urlMap);
129
+ if (data.feature_image && urlMap.has(data.feature_image)) data.feature_image = urlMap.get(data.feature_image);
130
+ }
131
+ body = await resolveBookmarks(body);
132
+ const html = render(body, {});
133
+ const result = await upsertPost(c, data, html, { force: args.force ?? false });
134
+ if ("blocked" in result && result.blocked) {
135
+ return { created: false, blocked: true, existing: result.existing };
136
+ }
137
+ if ("post" in result) {
138
+ const p = result.post;
139
+ return { created: true, post: { id: p.id, url: p.url, status: p.status, slug: p.slug } };
140
+ }
141
+ throw new Error("Unexpected upsert result.");
142
+ }
143
+ function checkFields(p) {
144
+ const findings = [];
145
+ const tpl = p.custom_template || "";
146
+ if (tpl && !XPRESIVA_TEMPLATES.includes(tpl)) {
147
+ findings.push(`custom_template "${tpl}" is not an Xpresiva template (expected one of ${XPRESIVA_TEMPLATES.join(", ")}, or empty for the default).`);
148
+ }
149
+ if (XPRESIVA_TEMPLATES.includes(tpl) && !p.feature_image) {
150
+ findings.push(`template "${tpl}" is built around a feature image, but the post has none.`);
151
+ }
152
+ if (p.feature_image && !p.feature_image_alt) {
153
+ findings.push("feature image has no alt text (hurts SEO and accessibility).");
154
+ }
155
+ if (p.excerpt && p.excerpt.length > 300) {
156
+ findings.push(`excerpt is ${p.excerpt.length} chars; Ghost rejects custom_excerpt over 300.`);
157
+ }
158
+ return findings;
159
+ }
160
+ async function checkPost(args) {
161
+ const p = await getPost(args);
162
+ return {
163
+ slug: p.slug,
164
+ title: p.title,
165
+ reading_time_min: readingTime(p.html),
166
+ findings: checkFields({ custom_template: p.custom_template, feature_image: p.feature_image, feature_image_alt: p.feature_image_alt, excerpt: p.excerpt, html: p.html })
167
+ };
168
+ }
169
+ async function auditSite(args) {
170
+ const cap = Math.min(args.limit ?? 100, 100);
171
+ const res = await client().posts.browse({
172
+ limit: cap,
173
+ order: "updated_at DESC",
174
+ fields: "id,title,slug,status,updated_at,feature_image,feature_image_alt,custom_template,custom_excerpt"
175
+ });
176
+ const staleDays = args.stale_days ?? 90;
177
+ const staleBefore = Date.now() - staleDays * 864e5;
178
+ const flagged = [];
179
+ for (const p of res) {
180
+ const issues = checkFields({
181
+ custom_template: p.custom_template,
182
+ feature_image: p.feature_image,
183
+ feature_image_alt: p.feature_image_alt,
184
+ excerpt: p.custom_excerpt
185
+ });
186
+ if (!p.feature_image) issues.push("no feature image.");
187
+ if (p.status === "draft" && p.updated_at && Date.parse(p.updated_at) < staleBefore) {
188
+ issues.push(`stale draft (not touched in ${staleDays}+ days).`);
189
+ }
190
+ if (issues.length) flagged.push({ slug: p.slug, title: p.title, status: p.status, issues });
191
+ }
192
+ return { scanned: res.length, flagged, truncated: res.length >= cap };
193
+ }
194
+ async function setCustomTemplate(args) {
195
+ const tpl = args.template === "default" ? "" : args.template;
196
+ if (tpl && !XPRESIVA_TEMPLATES.includes(tpl)) {
197
+ throw new Error(`"${tpl}" is not an Xpresiva template. Use one of ${XPRESIVA_TEMPLATES.join(", ")}, or "default" to clear it.`);
198
+ }
199
+ if (!args.id && !args.slug) throw new Error("Provide either id or slug.");
200
+ const key = args.id ? { id: args.id } : { slug: args.slug };
201
+ const existing = await client().posts.read({ ...key, fields: "id,slug,updated_at" });
202
+ const updated = await client().posts.edit({ id: existing.id, updated_at: existing.updated_at, custom_template: tpl || null });
203
+ return { slug: updated.slug, custom_template: updated.custom_template || "(default)" };
204
+ }
205
+ async function publishTranslationSet(args) {
206
+ const bare = args.pair.replace(/^#/, "");
207
+ if (RESERVED_INTERNAL.has(`hash-${bare}`)) {
208
+ throw new Error(`"${args.pair}" is a reserved tag (a language or #historical); pick a pairing tag like "tr-1".`);
209
+ }
210
+ const pairTag = `#${bare}`;
211
+ const results = [];
212
+ for (const v of args.versions) {
213
+ if (!XPRESIVA_LOCALES.includes(v.locale)) {
214
+ results.push({ locale: v.locale, error: `unknown locale (Xpresiva supports ${XPRESIVA_LOCALES.join(", ")}).` });
215
+ continue;
216
+ }
217
+ const tags = [...v.tags ?? [], `#${v.locale}`, pairTag];
218
+ try {
219
+ const r = await writePost({
220
+ title: v.title,
221
+ markdown: v.markdown,
222
+ slug: v.slug,
223
+ tags,
224
+ status: v.status ?? "draft",
225
+ excerpt: v.excerpt,
226
+ feature_image: v.feature_image,
227
+ feature_image_alt: v.feature_image_alt,
228
+ base_dir: v.base_dir,
229
+ force: args.force ?? false
230
+ });
231
+ if ("blocked" in r && r.blocked) {
232
+ results.push({ locale: v.locale, blocked: true, existing_slug: r.existing.slug, note: "slug exists; pass force to overwrite." });
233
+ } else {
234
+ results.push({ locale: v.locale, ...r.post });
235
+ }
236
+ } catch (err) {
237
+ results.push({ locale: v.locale, error: err?.message || String(err) });
238
+ }
239
+ }
240
+ return { pair: pairTag, results };
241
+ }
242
+
243
+ // src/index.ts
244
+ dotenv.config({ quiet: true });
245
+ console.log = (...args) => console.error(...args);
246
+ var server = new McpServer({ name: "oksigenia-ghost-mcp", version: "0.1.0" });
247
+ var ok = (v) => ({
248
+ content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) }]
249
+ });
250
+ var fail = (msg) => ({ content: [{ type: "text", text: msg }], isError: true });
251
+ function guard(fn) {
252
+ return async (args) => {
253
+ try {
254
+ return await fn(args);
255
+ } catch (err) {
256
+ return fail(`Error: ${err?.message || String(err)}`);
257
+ }
258
+ };
259
+ }
260
+ var READ = { readOnlyHint: true, openWorldHint: true };
261
+ var WRITE = { readOnlyHint: false, openWorldHint: true };
262
+ server.registerTool(
263
+ "verify_connection",
264
+ {
265
+ title: "Verify the connection to Ghost",
266
+ description: "Check that the Admin API URL and key work, and return basic site info.",
267
+ inputSchema: {},
268
+ annotations: { ...READ, title: "Verify Ghost connection" }
269
+ },
270
+ guard(async () => {
271
+ const r = await verify();
272
+ const site = r.site ? { title: r.site.title, url: r.site.url, version: r.site.version } : void 0;
273
+ return ok({ connected: true, site });
274
+ })
275
+ );
276
+ server.registerTool(
277
+ "list_posts",
278
+ {
279
+ title: "List posts",
280
+ description: "List posts, most recently updated first. Filter by status and/or tag.",
281
+ inputSchema: {
282
+ status: z.enum(["draft", "published", "scheduled", "all"]).optional().describe("Filter by status (default: all)."),
283
+ tag: z.string().optional().describe("Filter by tag slug."),
284
+ limit: z.number().int().min(1).max(50).optional().describe("Max posts to return (default 15).")
285
+ },
286
+ annotations: { ...READ, title: "List Ghost posts" }
287
+ },
288
+ guard(async (args) => ok(await listPosts(args)))
289
+ );
290
+ server.registerTool(
291
+ "get_post",
292
+ {
293
+ title: "Get a post",
294
+ description: "Fetch a single post by id or slug, including its HTML, tags and authors.",
295
+ inputSchema: {
296
+ id: z.string().optional().describe("Post id."),
297
+ slug: z.string().optional().describe("Post slug (use this or id).")
298
+ },
299
+ annotations: { ...READ, title: "Get a Ghost post" }
300
+ },
301
+ guard(async (args) => ok(await getPost(args)))
302
+ );
303
+ server.registerTool(
304
+ "list_tags",
305
+ {
306
+ title: "List tags",
307
+ description: "List all tags in the site (public and internal), with post counts.",
308
+ inputSchema: {},
309
+ annotations: { ...READ, title: "List Ghost tags" }
310
+ },
311
+ guard(async () => ok(await listTags()))
312
+ );
313
+ var writeShape = {
314
+ title: z.string().describe("Post title."),
315
+ markdown: z.string().describe("Post body in Markdown. Supports ::video, ::bookmark and Obsidian-style > [!type] callouts."),
316
+ slug: z.string().optional().describe("Slug. If omitted on create, Ghost derives it from the title."),
317
+ tags: z.array(z.string()).optional().describe("Tag names."),
318
+ status: z.enum(["draft", "published", "scheduled"]).optional().describe("Default: draft."),
319
+ excerpt: z.string().optional().describe("Custom excerpt (max 300 chars)."),
320
+ feature_image: z.string().optional().describe("Feature image: a URL, or a local path to upload."),
321
+ feature_image_alt: z.string().optional().describe("Feature image alt text (max 191 chars)."),
322
+ custom_template: z.string().optional().describe("Ghost custom template, e.g. custom-wide-feature-image."),
323
+ author: z.string().optional().describe("Author slug or email."),
324
+ published_at: z.string().optional().describe("ISO date, only used when status is scheduled."),
325
+ base_dir: z.string().optional().describe("Directory to resolve local image paths against (default: cwd).")
326
+ };
327
+ server.registerTool(
328
+ "create_post",
329
+ {
330
+ title: "Create a post (draft by default)",
331
+ description: "Create a post from Markdown. Local images in the body/feature image are processed and uploaded. Creates a draft unless status says otherwise. If a post with the same slug already exists it will NOT overwrite it \u2014 use update_post for that.",
332
+ inputSchema: writeShape,
333
+ annotations: { ...WRITE, destructiveHint: false, idempotentHint: false, title: "Create a Ghost post" }
334
+ },
335
+ guard(async (args) => {
336
+ const r = await writePost({ ...args, force: false });
337
+ if ("blocked" in r && r.blocked) {
338
+ const e = r.existing;
339
+ return ok(
340
+ `A post with slug "${e.slug}" already exists (title: "${e.title}", status: ${e.status}). Not overwriting. Call update_post with the same slug to change it on purpose.`
341
+ );
342
+ }
343
+ return ok({ created: true, ...r.post });
344
+ })
345
+ );
346
+ server.registerTool(
347
+ "update_post",
348
+ {
349
+ title: "Update an existing post",
350
+ description: "Update the post that has this slug, overwriting its content. The existing status is preserved (a published post stays published). Use create_post for brand-new posts.",
351
+ inputSchema: { ...writeShape, slug: z.string().describe("Slug of the existing post to update.") },
352
+ annotations: { ...WRITE, destructiveHint: true, idempotentHint: true, title: "Update a Ghost post" }
353
+ },
354
+ guard(async (args) => {
355
+ const r = await writePost({ ...args, force: true });
356
+ return ok({ updated: true, ...r.post });
357
+ })
358
+ );
359
+ server.registerTool(
360
+ "upload_image",
361
+ {
362
+ title: "Upload an image to Ghost",
363
+ description: "Process a local image (resize, format, EXIF clean) and upload it to Ghost. Returns the hosted URL.",
364
+ inputSchema: {
365
+ path: z.string().describe("Local path to the image file."),
366
+ max_width: z.number().int().optional().describe("Max width in px (default 1920)."),
367
+ format: z.enum(["auto", "webp", "jpeg", "png", "preserve"]).optional().describe("Output format (default auto)."),
368
+ quality: z.number().int().min(1).max(100).optional().describe("Quality 1-100 (default 82).")
369
+ },
370
+ annotations: { ...WRITE, destructiveHint: false, idempotentHint: false, title: "Upload an image" }
371
+ },
372
+ guard(async (args) => ok(await uploadImage(args)))
373
+ );
374
+ server.registerTool(
375
+ "xpresiva_check_post",
376
+ {
377
+ title: "Check a post against Xpresiva conventions",
378
+ description: "Read a post and report suggestions for the Xpresiva theme: valid custom_template, feature-image coherence, missing alt text, excerpt length, reading time. Suggests only, never writes.",
379
+ inputSchema: {
380
+ id: z.string().optional().describe("Post id."),
381
+ slug: z.string().optional().describe("Post slug (use this or id).")
382
+ },
383
+ annotations: { ...READ, title: "Xpresiva post check" }
384
+ },
385
+ guard(async (args) => ok(await checkPost(args)))
386
+ );
387
+ server.registerTool(
388
+ "audit_site",
389
+ {
390
+ title: "Audit posts for Xpresiva issues",
391
+ description: "Scan recent posts and flag ones with issues: no feature image, non-Xpresiva custom_template, missing alt text, over-long excerpts, and stale drafts. Read-only.",
392
+ inputSchema: {
393
+ limit: z.number().int().min(1).max(100).optional().describe("How many recent posts to scan (default/max 100)."),
394
+ stale_days: z.number().int().optional().describe("Flag drafts untouched for this many days (default 90).")
395
+ },
396
+ annotations: { ...READ, title: "Audit the site" }
397
+ },
398
+ guard(async (args) => ok(await auditSite(args)))
399
+ );
400
+ server.registerTool(
401
+ "set_custom_template",
402
+ {
403
+ title: "Set a post custom template",
404
+ description: "Set (or clear) a post's Xpresiva custom_template. Valid values: " + XPRESIVA_TEMPLATES.join(", ") + ', or "default" to clear it.',
405
+ inputSchema: {
406
+ id: z.string().optional().describe("Post id."),
407
+ slug: z.string().optional().describe("Post slug (use this or id)."),
408
+ template: z.string().describe(`One of ${XPRESIVA_TEMPLATES.join(", ")}, or "default".`)
409
+ },
410
+ annotations: { ...WRITE, destructiveHint: false, idempotentHint: true, title: "Set custom template" }
411
+ },
412
+ guard(async (args) => ok(await setCustomTemplate(args)))
413
+ );
414
+ var translationVersion = z.object({
415
+ locale: z.enum(["en", "es", "fr", "de", "pt", "it", "nl"]).describe("Language of this version."),
416
+ title: z.string(),
417
+ markdown: z.string(),
418
+ slug: z.string().optional(),
419
+ tags: z.array(z.string()).optional().describe("Public tags for this version (language/pair tags are added automatically)."),
420
+ status: z.enum(["draft", "published", "scheduled"]).optional(),
421
+ excerpt: z.string().optional(),
422
+ feature_image: z.string().optional(),
423
+ feature_image_alt: z.string().optional(),
424
+ base_dir: z.string().optional()
425
+ });
426
+ server.registerTool(
427
+ "publish_translation_set",
428
+ {
429
+ title: "Publish a set of linked translations",
430
+ description: "Create/update several language versions of one article, linked as an Xpresiva translation group. Each version gets its language tag (#es, #fr, \u2026) and a shared pairing tag so the theme cross-links them. This tool does NOT translate \u2014 provide each version's title and Markdown yourself. Drafts by default.",
431
+ inputSchema: {
432
+ pair: z.string().describe('Pairing tag shared by all versions, e.g. "tr-1" (an internal tag).'),
433
+ versions: z.array(translationVersion).min(1).describe("One entry per language version."),
434
+ force: z.boolean().optional().describe("Overwrite existing posts with matching slugs (default false).")
435
+ },
436
+ annotations: { ...WRITE, destructiveHint: false, idempotentHint: false, title: "Publish translation set" }
437
+ },
438
+ guard(async (args) => ok(await publishTranslationSet(args)))
439
+ );
440
+ async function main() {
441
+ const transport = new StdioServerTransport();
442
+ await server.connect(transport);
443
+ console.error("oksigenia-ghost-mcp ready (stdio).");
444
+ }
445
+ main().catch((err) => {
446
+ console.error("Fatal:", err?.message || err);
447
+ process.exit(1);
448
+ });
package/package.json ADDED
@@ -0,0 +1,57 @@
1
+ {
2
+ "name": "@oksigenia/ghost-mcp",
3
+ "version": "0.1.0",
4
+ "publishConfig": {
5
+ "access": "public"
6
+ },
7
+ "description": "Model Context Protocol server for Ghost, aware of the Xpresiva theme. Operate your Ghost content by talking to an AI — locally, no telemetry. Wraps the ghost-md-publisher toolkit.",
8
+ "type": "module",
9
+ "main": "dist/index.js",
10
+ "bin": {
11
+ "oksigenia-ghost-mcp": "dist/index.js"
12
+ },
13
+ "files": [
14
+ "dist/",
15
+ ".env.example",
16
+ "README.md",
17
+ "LICENSE"
18
+ ],
19
+ "engines": {
20
+ "node": ">=20.9.0"
21
+ },
22
+ "scripts": {
23
+ "build": "tsup",
24
+ "prepublishOnly": "tsup",
25
+ "dev": "tsup --watch",
26
+ "start": "node dist/index.js",
27
+ "typecheck": "tsc --noEmit",
28
+ "test": "vitest run"
29
+ },
30
+ "keywords": [
31
+ "ghost",
32
+ "mcp",
33
+ "model-context-protocol",
34
+ "xpresiva",
35
+ "markdown",
36
+ "admin-api",
37
+ "ai"
38
+ ],
39
+ "author": "Oksigenia",
40
+ "license": "MIT",
41
+ "repository": {
42
+ "type": "git",
43
+ "url": "git+https://github.com/OksigeniaSL/oksigenia-ghost-mcp.git"
44
+ },
45
+ "dependencies": {
46
+ "@modelcontextprotocol/sdk": "^1.30.0",
47
+ "@oksigenia/ghost-md-publisher": "^0.3.3",
48
+ "dotenv": "^17.4.2",
49
+ "zod": "^3.23.8"
50
+ },
51
+ "devDependencies": {
52
+ "@types/node": "^22.20.1",
53
+ "tsup": "^8.3.5",
54
+ "typescript": "^5.7.2",
55
+ "vitest": "^4.1.11"
56
+ }
57
+ }