@damusix/ghost-mcp 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damusix/ghost-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server for Ghost CMS — manage content, members, newsletters, and more via LLMs",
   "keywords": [
     "ai",
@@ -20,7 +20,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skills"
   ],
   "type": "module",
   "main": "./dist/index.mjs",

package/skills/ghost-writing/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: ghost-writing
+description: 'Use when writing, editing, or publishing Ghost blog posts with the ghost-mcp server. Covers compose_post vs use_ghost_api, the full Koenig block catalog, and blog-writing best practices.'
+---
+
+# Ghost Writing
+
+## Quick Start
+
+    compose_post {
+        "title": "We shipped the editor",
+        "status": "draft",
+        "blocks": [
+            { "type": "heading", "level": 2, "text": "What changed" },
+            { "type": "paragraph", "text": "Prose with **bold** and [links](https://ghost.org)." },
+            { "type": "callout", "emoji": "🚀", "color": "green", "text": "Live now" }
+        ]
+    }
+
+## Critical Rules
+
+1. **Never push raw HTML** — compose posts from Koenig blocks via `compose_post`. The `html` block is a last resort when no native block fits.
+2. **Draft first** — create with `status: "draft"`, report the post URL, publish only when asked.
+3. **Long posts use `blockFile`** — write blocks JSON to an absolute path, validate with `compose_lexical`, pass the path to `compose_post`.
+4. **Updates replace the whole body** — `compose_post` with `id` needs the current `updated_at` (via `posts.read`) and full blocks; keep the blockFile as source of truth when iterating.
+5. **Don't guess block fields** — run `koenig_help` (list) or `koenig_help { "block": "callout" }` (fields + example) before composing.
+
+## Workflow
+
+1. Outline: one goal per post, working title, section list — see [writing](references/writing.md)
+2. Pick blocks per section: prose vs cards — see [blocks](references/blocks.md)
+3. Compose: `compose_post` with inline `blocks`, or `blockFile` for long posts
+4. Review: re-read for rhythm, set excerpt/tags/feature image
+5. Publish or schedule via `use_ghost_api` — see [workflows](references/workflows.md)
+
+## References
+
+- [Blocks](references/blocks.md) — every block type, its purpose, and how to choose between similar ones
+- [Writing](references/writing.md) — structure, rhythm, metadata, and voice practices for good posts
+- [Workflows](references/workflows.md) — tool map and end-to-end recipes: create, edit, publish, newsletter, members-only

package/skills/ghost-writing/references/blocks.md

@@ -0,0 +1,68 @@
+# Koenig block catalog
+
+Every block `compose_post` / `compose_lexical` accepts, grouped as `koenig_help` reports them. This page tells you **when to reach for each block**; run `koenig_help { "block": "<type>" }` for exact fields and a JSON example — never guess field names.
+
+## Prose blocks
+
+Native Lexical nodes. Their `text` (or `items`) accepts inline markdown: `**bold**`, `_italic_`, `` `code` ``, `[links](url)`.
+
+| Block       | Purpose                                              | Reach for it when                                                                |
+| ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `paragraph` | A text paragraph                                     | The default. Most of every post should be paragraphs.                            |
+| `heading`   | Section heading, `level` 1–6 (default 2)             | Starting a new section. Use level 2 for top sections — the post title is the h1. |
+| `list`      | Bullet or numbered list (`style`: `bullet`/`number`) | 3+ parallel items; steps in order → `number`.                                    |
+| `quote`     | Blockquote                                           | Quoting a person or source. Attribution goes in a following paragraph.           |
+| `aside`     | Pull-quote / aside                                   | Restating your own key line for emphasis, or a tangential remark.                |
+
+## Media cards
+
+| Block     | Purpose                                            | Reach for it when                                                      |
+| --------- | -------------------------------------------------- | ---------------------------------------------------------------------- |
+| `image`   | Single image with caption, alt text, optional link | One illustrative image. Always set `alt`.                              |
+| `gallery` | Grid of images (`images` array)                    | 3+ related photos that belong together; beats stacking `image` blocks. |
+| `video`   | Video file (`src`, `thumbnailSrc` poster)          | Self-hosted video files. For YouTube/Vimeo use `embed` instead.        |
+| `audio`   | Audio file with title                              | Podcast episodes, audio clips.                                         |
+| `file`    | Downloadable file card                             | PDFs, zips — anything the reader should download.                      |
+
+## Embed cards
+
+| Block       | Purpose                                                            | Reach for it when                                                                       |
+| ----------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `bookmark`  | Rich link preview (title, description, thumbnail)                  | Featuring a link as a visual card — recommended reading, source articles.               |
+| `embed`     | External embed (YouTube, X/Twitter, etc.) via `url` + embed `html` | Third-party content with a player/widget.                                               |
+| `codeblock` | Syntax-highlighted code block                                      | Any multi-line code. Set `language`. Inline code stays in paragraph backticks.          |
+| `markdown`  | Markdown rendered as one opaque unit                               | Avoid for prose — it edits as one blob. Only for markdown-specific needs (e.g. tables). |
+| `html`      | Raw HTML passthrough                                               | Last resort when no native block fits. Not granularly editable in Ghost.                |
+
+## Layout cards
+
+| Block     | Purpose                                                     | Reach for it when                                                                  |
+| --------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `callout` | Highlighted box with emoji and background color             | Warnings, tips, key takeaways — content the reader must not skim past.             |
+| `toggle`  | Collapsible accordion (`content` is HTML; no-op in email)   | FAQs, optional detail. Don't hide essential content in it.                         |
+| `button`  | Call-to-action button                                       | The post's one primary action. More than ~2 buttons dilutes all of them.           |
+| `header`  | Large hero header with optional background image and button | Big visual section break in landing-page-style posts. Regular posts use `heading`. |
+| `cta`     | Call-to-action card with text, optional image and button    | A richer pitch than a bare `button` — sponsorships, product plugs.                 |
+| `product` | Product card with image, star rating, and button            | Product recommendations and reviews.                                               |
+
+## Membership cards
+
+| Block     | Purpose                             | Reach for it when                                                                                  |
+| --------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `signup`  | Member signup form (no-op in email) | Converting anonymous readers — typically near the end, once.                                       |
+| `paywall` | Free/paid split marker              | Everything after it is members-only. Place it after the hook so free readers get real value first. |
+
+## Structure & email cards
+
+| Block       | Purpose                                                                                  | Reach for it when                                                                     |
+| ----------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `divider`   | Horizontal rule                                                                          | Scene change within a section. Between sections, a `heading` already breaks the page. |
+| `email`     | Content shown ONLY in the email newsletter (`html`, supports `{first_name, "fallback"}`) | Personal newsletter greetings/postscripts. Invisible on web.                          |
+| `email-cta` | Newsletter-only CTA targeting a member segment                                           | Upgrade pitches to free subscribers in the email version.                             |
+
+## Choosing between similar blocks
+
+- **`quote` vs `aside` vs `callout`** — someone else's words → `quote`; your own line, amplified → `aside`; must-see info with visual weight → `callout`.
+- **`bookmark` vs `embed` vs `button`** — preview a link → `bookmark`; play third-party content inline → `embed`; ask the reader to act → `button`.
+- **`heading` vs `header`** — document structure → `heading`; full-width visual hero → `header`.
+- **prose blocks vs `markdown` vs `html`** — native blocks edit granularly in Ghost's editor; `markdown` and `html` become single opaque cards. Prefer native, always.

package/skills/ghost-writing/references/workflows.md

@@ -0,0 +1,68 @@
+# Tool map and workflows
+
+## Which tool when
+
+| Tool              | Use it for                                                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------------------ |
+| `koenig_help`     | Discover block types, or fields + JSON example for one block. Call before composing.                   |
+| `compose_post`    | Create or update a post from blocks. The default write path — never hand-write `lexical` or push HTML. |
+| `compose_lexical` | Compile blocks to Lexical JSON _without_ touching the site — validate a `blockFile`, or preview.       |
+| `use_ghost_api`   | Everything else: publish/schedule, tags, images, members, newsletters, settings.                       |
+| `ghost_api_help`  | List available actions, or the payload schema for one (`{ "action": "posts.edit" }`).                  |
+| `ghost_docs`      | Search Ghost's official docs (`{ "search": "..." }`) for platform questions the tools don't answer.    |
+
+The server runs in **admin** mode (full read/write) or **content** mode (read-only). In content mode every write is rejected — surface that to the user instead of retrying.
+
+## Create a post
+
+1. `koenig_help` — refresh the block list if unsure.
+2. Build the `blocks` array ([blocks.md](blocks.md)), following [writing.md](writing.md).
+3. `compose_post { "title": ..., "status": "draft", "blocks": [...], "excerpt": ..., "tags": [{ "name": ... }] }`.
+4. Report the returned post `url` and `id` so the user can review the draft.
+
+Stay in `draft` until the user asks to publish. `visibility` controls access: `public`, `members`, `paid`, or `tiers`.
+
+## Long posts: `blockFile`
+
+For posts beyond ~15 blocks, don't inline the array — write it to a file and iterate there:
+
+1. Write the blocks JSON (bare `[...]` or `{ "blocks": [...] }`) to an **absolute** path, e.g. under the project's `tmp/`.
+2. Validate: `compose_lexical { "blockFile": "/abs/path/tmp/post.json" }` — composition errors list the offending block index.
+3. Create: `compose_post { "title": ..., "status": "draft", "blockFile": "/abs/path/tmp/post.json" }`.
+4. To revise, edit the file and re-run — the file is the source of truth; you never re-send the array.
+
+## Edit an existing post
+
+`compose_post` with an `id` **replaces the entire body** — there is no partial patch:
+
+1. `use_ghost_api { "action": "posts.read", "payload": { "id": ..., "formats": "lexical" } }` — get current content and `updated_at`.
+2. Rebuild the full blocks array (from your blockFile if you authored the post; otherwise reconstruct from the fetched content).
+3. `compose_post { "id": ..., "updated_at": "<current value>", "blocks": [...] }` — a stale `updated_at` is rejected as a collision; re-read and retry.
+
+For metadata-only changes (title, tags, status, feature image) skip composition and call `posts.edit` directly with `id` + `updated_at`.
+
+## Publish or schedule
+
+- Publish now: `posts.edit` with `{ "status": "published" }`.
+- Schedule: `posts.edit` with `{ "status": "scheduled", "published_at": "<future ISO 8601>" }`.
+- Both need `id` + current `updated_at`. Confirm with the user before either — publishing can trigger the newsletter send.
+
+## Images
+
+Ghost only renders images it can reach by URL:
+
+1. Local file → `images.upload` (multipart upload) → returns the hosted URL.
+2. Use that URL in `image` / `gallery` blocks or as `feature_image`.
+3. External URLs work directly but break if the host removes them — prefer uploading.
+
+## Newsletter posts
+
+- Email-specific content: `email` and `email-cta` blocks ([blocks.md](blocks.md) — email-only group).
+- Audience and sending are controlled at publish time by newsletter settings, not by blocks; check `newsletters.browse` for what exists and `ghost_docs { "search": "newsletter" }` for sending mechanics.
+- Members-only content: `paywall` block for in-post splits, `visibility` for whole-post gating.
+
+## When something fails
+
+- Composition errors from `compose_post`/`compose_lexical` return `issues` with block indexes — fix the named block, don't fall back to `html`.
+- API errors come back verbatim from Ghost; `ghost_api_help { "action": ... }` shows the expected payload shape.
+- Unknown platform behavior (routing, themes, member tiers): `ghost_docs` before guessing.

package/skills/ghost-writing/references/writing.md

@@ -0,0 +1,48 @@
+# Writing good posts
+
+Block mechanics live in [blocks.md](blocks.md); this page is the craft — what makes a post worth reading and how to shape it with the blocks you have.
+
+## One post, one goal
+
+Before composing anything, answer: _what should the reader know or do after this post?_ If you have two answers, you have two posts. The goal decides the title, the structure, and the single CTA at the end.
+
+## Structure
+
+- **Hook first.** The opening paragraph earns the rest of the read: state the problem, the payoff, or the surprising claim. No throat-clearing ("In today's fast-paced world...").
+- **Sections with `heading` level 2.** The post title is the h1 — body headings start at level 2, with level 3 for subsections. Never skip levels.
+- **A heading every 3–6 paragraphs.** Readers scan before they read; headings are the scan path. A heading should make sense out of context.
+- **End with a conclusion and one CTA.** Summarize the takeaway in a paragraph, then one `button`, `signup`, or `cta` — not all three.
+
+## Rhythm and scannability
+
+- Keep paragraphs to 2–4 sentences. A wall of `paragraph` blocks reads as work; break long chains with a `list`, `image`, `callout`, or `divider`.
+- Use `list` whenever items are parallel — three comma-separated clauses in a sentence usually want to be bullets.
+- Bold sparingly: **key terms** the scanner's eye should catch, not whole sentences.
+- Make link text descriptive: `[the Koenig card reference](url)`, never `[click here](url)`.
+- One `callout` per section at most. When everything is highlighted, nothing is.
+
+## Metadata
+
+Set these on every post — they control how the post looks in lists, search, and shares:
+
+- **`title`** — under ~60 characters so it doesn't truncate in search results. Specific beats clever.
+- **`excerpt`** — 1–2 sentences selling the post; shows in post lists and social cards. Don't let Ghost auto-truncate the first paragraph.
+- **`tags`** — the first tag is the primary tag and drives theme layout/routing. Reuse existing tags (check `tags.browse`) before inventing new ones.
+- **`feature_image`** — posts without one look broken in most themes' index pages. Upload via `images.upload` if needed.
+- **`slug`** — short and stable; leave it derived from the title unless the title is long.
+- **`meta_title` / `meta_description`** — only when the SEO framing should differ from the display title/excerpt (set via `use_ghost_api posts.edit`).
+
+## Voice
+
+- Plain, precise language. Name things what they are; cut adjectives that don't discriminate.
+- Active voice, present tense where possible. "Ghost renders the card" over "the card is rendered".
+- Concrete beats abstract: an example, a number, or a before/after every few paragraphs.
+- Cut the last 10%: filler intros, hedges ("arguably", "quite"), and restating what the heading already said.
+
+## Newsletter and member awareness
+
+If the post goes out as a newsletter or sits behind membership, shape it for both renderings:
+
+- `toggle` and `signup` do nothing in email; don't put essential content or the only CTA in them.
+- `email` / `email-cta` blocks are invisible on web — use them for the personal greeting or subscriber-only pitch, never for the body.
+- Place `paywall` after the hook and first real insight, so free readers get value and a reason to upgrade.