@damusix/ghost-mcp 0.3.0 → 0.4.0

package/README.md

@@ -62,9 +62,58 @@ claude mcp add ghost \
 
 ## Tools
 
+### `compose_post`
+
+Create or update a post from structured Koenig content blocks. Prefer this over
+pushing raw HTML or hand-writing Lexical — it produces clean, natively-editable
+posts. Prose blocks (`paragraph`, `heading`, `list`, `quote`) accept inline
+markdown (`**bold**`, `_italic_`, `` `code` ``, `[links](url)`); rich features
+are cards (`callout`, `image`, `button`, `bookmark`, `codeblock`, `toggle`,
+`gallery`, and more). Omit `id` to create; set `id` + `updated_at` to update.
+
+```json
+{
+    "title": "We shipped the editor",
+    "status": "draft",
+    "blocks": [
+        { "type": "heading", "level": 2, "text": "What's new" },
+        { "type": "paragraph", "text": "Try the **new** [editor](https://ghost.org)." },
+        { "type": "list", "style": "bullet", "items": ["Clean blocks", "Native editing"] },
+        { "type": "callout", "emoji": "🚀", "color": "green", "text": "Live now" },
+        { "type": "button", "text": "Get started", "url": "https://ghost.org" }
+    ]
+}
+```
+
+Each block becomes a native Lexical node, so the post stays granularly editable
+in Ghost — not a single opaque HTML block. See
+[docs/koenig-cards.md](docs/koenig-cards.md) for every block type and field.
+
+For long posts, write the blocks to a JSON file (a bare `[...]` array or
+`{ "blocks": [...] }`) and pass its **absolute** path as `blockFile` instead of
+`blocks` — useful when iterating, so you edit the file rather than re-sending the
+whole array each time. Validate the file first with `compose_lexical`.
+
+```json
+{ "title": "Long post", "status": "draft", "blockFile": "/abs/path/tmp/post.json" }
+```
+
+### `compose_lexical`
+
+Compile the same `blocks` into a Lexical JSON string without creating a post —
+useful for preview or feeding into `use_ghost_api` yourself.
+
+### `koenig_help`
+
+List all block types, or get the fields and a JSON example for one block.
+
+```json
+{ "block": "callout" }
+```
+
 ### `use_ghost_api`
 
-Execute Ghost API actions. Supports full CRUD on posts, pages, tags, members, newsletters, offers, tiers, users, webhooks, images, themes, and site settings.
+Execute Ghost API actions. Supports full CRUD on posts, pages, tags, members, newsletters, offers, tiers, users, webhooks, images, themes, and site settings. For post bodies, prefer `compose_post` over passing raw `lexical`/`html` here.
 
 ```json
 {
@@ -109,6 +158,17 @@ 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.
 
+## Development
+
+Spin up a throwaway Ghost 6 + MySQL 8 stack to exercise the server against a
+live API, and inspect Ghost's real schema with noorm. See
+[docs/experimentation.md](docs/experimentation.md).
+
+```bash
+docker compose up -d
+bin/ghost-keys.sh --write   # writes .env pointed at the local Ghost
+```
+
 ## License
 
 MIT

package/bin/ghost-keys.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Derive Ghost API keys for the MCP straight from the dockerized DB via noorm.
+#
+# Reads the admin + content keys for a Ghost integration and prints them as
+# env lines (or writes them to .env with --write). The Admin API key is the
+# Ghost `{key_id}:{secret}` form; the Content API key is the bare secret.
+#
+#   bin/ghost-keys.sh                 # print keys for the "MCP Lab" integration
+#   bin/ghost-keys.sh "Zapier"        # a different integration by name
+#   bin/ghost-keys.sh --write         # write/refresh .env for the MCP
+#
+# Requires: the docker stack up (docker compose up -d) and noorm installed.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+WRITE=0
+INTEGRATION="MCP Lab"
+for arg in "$@"; do
+    case "$arg" in
+        --write) WRITE=1 ;;
+        *) INTEGRATION="$arg" ;;
+    esac
+done
+
+# shellcheck disable=SC1091
+set -a; source .noorm/dev.env; set +a
+
+row() {
+    noorm --json sql "SELECT ak.secret AS secret, ak.id AS key_id FROM api_keys ak JOIN integrations i ON i.id = ak.integration_id WHERE i.name = '${INTEGRATION}' AND ak.type = '$1'" 2>/dev/null | grep '^{' | head -1
+}
+
+ADMIN_ROW=$(row admin)
+CONTENT_ROW=$(row content)
+
+if [[ -z "$ADMIN_ROW" ]]; then
+    echo "No admin key found for integration '${INTEGRATION}'." >&2
+    echo "Is the stack up, and does that integration exist? (Ghost Admin > Settings > Integrations)" >&2
+    exit 1
+fi
+
+ADMIN_KEY="$(jq -r '.key_id' <<<"$ADMIN_ROW"):$(jq -r '.secret' <<<"$ADMIN_ROW")"
+CONTENT_KEY="$(jq -r '.secret' <<<"$CONTENT_ROW")"
+
+if [[ "$WRITE" == "1" ]]; then
+    cat > .env <<EOF
+# Local MCP -> dockerized Ghost (docker-compose.yml). Gitignored; throwaway creds.
+# Regenerate with: bin/ghost-keys.sh --write
+GHOST_URL=http://localhost:2368
+GHOST_API_VERSION=v6.0
+GHOST_ADMIN_API_KEY=${ADMIN_KEY}
+GHOST_CONTENT_API_KEY=${CONTENT_KEY}
+EOF
+    echo "Wrote .env for integration '${INTEGRATION}'."
+else
+    echo "GHOST_ADMIN_API_KEY=${ADMIN_KEY}"
+    echo "GHOST_CONTENT_API_KEY=${CONTENT_KEY}"
+fi