@proars/ghost-mcp-server 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [2.2.0] - 2026-11-02
+
+### Added
+
+- `update_page_seo` shortcut, matching `update_post_seo` for pages (`PUT /pages/{id}/`). The server now has 60 tools. README documents it in the tool table and the calling conventions.
+- README: npm version badge and a demo GIF (`docs/demo.gif`).
+- README: JSON `args` example for the update command, and guidance on the API URL for Ghost(Pro) and custom domains.
+
+## [2.1.1] - 2026-11-01
+
+### Changed
+
+- README: Claude Code install uses `--scope user`, with steps to check and remove the server, a note on updating, and a warning about running `npx` inside a clone of this repository.
+
+## [2.1.0] - 2026-11-01
+
+First release on npm as `@proars/ghost-mcp-server`.
+
+### Added
+
+- `delete_member` tool (`DELETE /members/{id}/`). The server now has 59 tools.
+- `ghost-mcp-server` command (`bin` with a shebang), so the package runs with `npx -y @proars/ghost-mcp-server`.
+- GitHub Actions workflow that runs typecheck, build and tests on Node 20 and 22.
+- README warning that destructive tools are available, and an install section for `npx`.
+
+### Changed
+
+- `npm start` runs the compiled `dist/index.js` instead of `tsx`.
+- Published files are limited to `dist`, `README.md`, `LICENSE` and `.env.example`.
+- `prepublishOnly` builds the project and runs the tests before every publish.
+- Minimum `@modelcontextprotocol/sdk` raised from `^1.0.0` to `^1.32.0`.
+- README rewritten with a quick start, FAQ and access notes.

package/README.md

@@ -1,14 +1,17 @@
 # Ghost MCP Server: manage Ghost CMS from Claude, Cursor and other AI clients
 
 [![CI](https://github.com/proars/ghost-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/proars/ghost-mcp-server/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@proars/ghost-mcp-server)](https://www.npmjs.com/package/@proars/ghost-mcp-server)
 ![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)
-![Tools](https://img.shields.io/badge/tools-59-blue)
+![Tools](https://img.shields.io/badge/tools-60-blue)
 ![Routes](https://img.shields.io/badge/Admin%20API%20routes-253-orange)
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 
 Ghost MCP Server is an open-source [Model Context Protocol](https://modelcontextprotocol.io) server for Ghost CMS, written in TypeScript. It connects an MCP client such as Claude Desktop, Claude Code or Cursor to the Ghost Admin API over stdio. With it, an AI assistant can create and edit posts and pages, set SEO metadata, manage tags, members and newsletters, upload images and themes, and export content.
 
-It exposes **59 tools**: 55 dedicated API tools, two shortcuts for SEO and tags, a route search and a generic request tool. The built-in catalog covers **253 Admin API routes** taken from a pinned Ghost source snapshot. What works on your site depends on your credentials, your Ghost version and its feature flags. Routes and sources are listed in [GHOST_API.list](GHOST_API.list).
+It exposes **60 tools**: 55 dedicated API tools, three shortcuts for SEO and tags, a route search and a generic request tool. The built-in catalog covers **253 Admin API routes** taken from a pinned Ghost source snapshot. What works on your site depends on your credentials, your Ghost version and its feature flags. Routes and sources are listed in [GHOST_API.list](GHOST_API.list).
+
+![Demo: Claude Code creates a draft post in Ghost through the MCP server](https://raw.githubusercontent.com/proars/ghost-mcp-server/main/docs/demo.gif)
 
 ## Quick start
 
@@ -45,14 +48,28 @@ Config file locations: Claude Desktop on macOS uses `~/Library/Application Suppo
 **Claude Code:**
 
 ```bash
-claude mcp add ghost \
+claude mcp add ghost --scope user \
   -e GHOST_API_URL=https://your-blog.com \
   -e GHOST_ADMIN_API_KEY=64f1a2b3c4d5e6f7a8b9c0d1:3e5f7a9b1c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a2b4c6d8e0f2a3b5c7d9e1f \
   -- npx -y @proars/ghost-mcp-server
 ```
 
+`--scope user` makes the server available in every folder. Without it, the server is registered only for the folder where you ran the command. Claude Code starts and stops the server itself, so you don't need to keep a terminal open.
+
+Check the connection with `claude mcp get ghost`, which should report `Connected`, or type `/mcp` inside a `claude` session. To remove the server, run `claude mcp remove ghost -s user`.
+
 Any other stdio MCP client can run the same command, `npx -y @proars/ghost-mcp-server`, with the two environment variables.
 
+**Updating:** `npx` uses a cache, so `@latest` may not be checked against the registry on every start. To force a registry freshness check whenever the command runs, use `npx --prefer-online -y @proars/ghost-mcp-server@latest`. In a JSON client configuration, set `args` to:
+
+```json
+["--prefer-online", "-y", "@proars/ghost-mcp-server@latest"]
+```
+
+To stay on one version, pin it, for example `@proars/ghost-mcp-server@2.2.0`. See the [changelog](CHANGELOG.md) for what changed in each release.
+
+Don't run `npx` from inside a clone of this repository: npm finds the local `package.json` with the same name and fails with `ghost-mcp-server: command not found`. Run it from any other folder.
+
 ## Install from source
 
 Use this if you want to change the code or run an unpublished version.
@@ -96,17 +113,18 @@ The `.env` file in the project root is read regardless of the directory the clie
 | Images and themes | `upload_image`, `upload_theme`, `activate_theme` |
 | Webhooks | `create_webhook`, `update_webhook`, `delete_webhook` |
 | Site | `get_site`, `get_settings` |
-| Shortcuts | `update_post_seo`, `update_post_tags` |
+| Shortcuts | `update_post_seo`, `update_page_seo`, `update_post_tags` |
 | Discovery and generic calls | `ghost_list_endpoints`, `ghost_api_request` |
 
 Ghost has no delete endpoint for tiers, newsletters or offers, so those resources have no `delete_*` tool.
 
-> **Warning: this server exposes every supported function, including destructive ones.** `delete_post`, `delete_page`, `delete_tag`, `delete_member`, `delete_user`, `activate_theme`, `upload_theme` and `ghost_api_request` can permanently remove or overwrite content, subscribers and site settings. Deleted records usually cannot be restored. Create a separate integration key for the server, make a backup (Ghost Admin → Settings → Labs → Export) before bulk work, and turn on manual approval for all `update_*`, `delete_*` and generic calls in your client.
+> **Warning: this server exposes every supported function, including destructive ones.** `delete_post`, `delete_page`, `delete_tag`, `delete_member`, `delete_user`, `activate_theme`, `upload_theme` and `ghost_api_request` can permanently remove or overwrite content, subscribers and site settings. Deleted records usually cannot be restored. Create a separate integration key for the server, export a backup of your content from Ghost Admin before bulk work, and turn on manual approval for all `update_*`, `delete_*` and generic calls in your client.
 
 ### How do I call the tools?
 
-- **Create and update:** put the record fields in `data` and pass the record `id` as a separate argument. Post and page updates need `data.updated_at` from a fresh read. The SEO and tag shortcuts take `updated_at` directly.
+- **Create and update:** put the record fields in `data` and pass the record `id` as a separate argument. Post and page updates need `data.updated_at` from a fresh read. The SEO shortcuts (`update_post_seo`, `update_page_seo`) and the tag shortcut take `updated_at` directly.
 - **Lists:** use `limit`, `page`, `filter`, `order`, `include` and `fields`. Posts and pages come back with compact fields and tags by default. Single-record reads return the full record.
+- **SEO:** `update_post_seo` and `update_page_seo` set `meta_title`, `meta_description`, `og_title` and `og_description` in one call. Pass `id`, the current `updated_at` and at least one of those fields. Fields you leave out stay unchanged.
 - **Tags:** setting tags replaces the whole set. Tags that don't exist yet are created, and an empty array removes all tags.
 - **Publishing:** call `update_post` with `data.status="published"`, or with `"scheduled"` and a future `data.published_at`. To send the post by email, add `newsletter` (a slug) and, optionally, `email_segment`.
 - **Images:** `upload_image` takes `file_path`, an optional `purpose` (`image`, `profile_image` or `icon`) and `ref`.
@@ -172,7 +190,7 @@ The tests check catalog and tool consistency, request construction, file safety,
 ## FAQ
 
 **Does it work with self-hosted Ghost and Ghost(Pro)?**
-Yes, as long as you can reach the Admin API and have a key. Use the Admin domain of your site as `GHOST_API_URL`.
+Yes, as long as you can reach the Admin API and have a key. Set `GHOST_API_URL` to the API URL shown on your custom integration page in Ghost Admin. This matters most for Ghost(Pro) and for sites behind a custom domain, because the server never follows redirects: an address that redirects to another one will fail.
 
 **Which clients does it support?**
 Any MCP client that can start a stdio server, including Claude Desktop, Claude Code and Cursor.

package/dist/index.js

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { assertSafePath, assertSafeSegment, buildForm, ghostRequest, GhostError, } from "./client.js";
 import { accessNote, filterRoutes, hintFor, matchRoute, routeKey, ROUTES } from "./routes.js";
-const SERVER_VERSION = "2.1.0";
+const SERVER_VERSION = "2.2.0";
 const MAX_RESULT_CHARS = 100_000;
 /** Calls Ghost and, on 401, 403 and 404, adds what the route catalog knows about the failure. */
 async function request(method, path, query = {}, body, form, options) {
@@ -412,56 +412,61 @@ const STANDALONE_SPECS = [
     },
 ];
 const SEO_FIELDS = ["meta_title", "meta_description", "og_title", "og_description"];
-const seoTool = {
-    name: "update_post_seo",
-    description: "Shortcut to update SEO fields of a post (meta_title, meta_description, og_title, og_description). Requires id and the current updated_at. At least one SEO field must be provided. [PUT /admin/posts/{id}/]",
-    inputSchema: {
-        type: "object",
-        properties: {
-            id: { type: "string", description: "Post id." },
-            updated_at: {
-                type: "string",
-                description: "Current updated_at value of the post, as returned by get_posts.",
+function seoToolFor(kind) {
+    const path = `${kind}s`;
+    return {
+        name: `update_${kind}_seo`,
+        description: `Shortcut to update SEO fields of a ${kind} (meta_title, meta_description, og_title, og_description). Requires id and the current updated_at. At least one SEO field must be provided. [PUT /admin/${path}/{id}/]`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: `${kind === "post" ? "Post" : "Page"} id.` },
+                updated_at: {
+                    type: "string",
+                    description: `Current updated_at value of the ${kind}, as returned by get_${path}.`,
+                },
+                meta_title: { type: "string", description: "SEO meta title." },
+                meta_description: { type: "string", description: "SEO meta description." },
+                og_title: { type: "string", description: "Open Graph title." },
+                og_description: { type: "string", description: "Open Graph description." },
             },
-            meta_title: { type: "string", description: "SEO meta title." },
-            meta_description: { type: "string", description: "SEO meta description." },
-            og_title: { type: "string", description: "Open Graph title." },
-            og_description: { type: "string", description: "Open Graph description." },
+            required: ["id", "updated_at"],
         },
-        required: ["id", "updated_at"],
-    },
-    // Both overwrite existing values (SEO fields, or the whole tag list), so they are destructive.
-    annotations: { readOnlyHint: false, destructiveHint: true },
-    isMutation: () => true,
-    run: async (args) => {
-        const id = requireString(args, "id");
-        const updated_at = requireString(args, "updated_at");
-        const fields = {};
-        for (const key of SEO_FIELDS) {
-            const value = args[key];
-            if (value !== undefined) {
-                if (typeof value !== "string") {
-                    throw new Error(`Argument "${key}" must be a string.`);
+        // Both overwrite existing values (SEO fields, or the whole tag list), so they are destructive.
+        annotations: { readOnlyHint: false, destructiveHint: true },
+        isMutation: () => true,
+        run: async (args) => {
+            const id = requireString(args, "id");
+            const updated_at = requireString(args, "updated_at");
+            const fields = {};
+            for (const key of SEO_FIELDS) {
+                const value = args[key];
+                if (value !== undefined) {
+                    if (typeof value !== "string") {
+                        throw new Error(`Argument "${key}" must be a string.`);
+                    }
+                    fields[key] = value;
                 }
-                fields[key] = value;
             }
-        }
-        if (Object.keys(fields).length === 0) {
-            throw new Error(`Provide at least one of: ${SEO_FIELDS.join(", ")}.`);
-        }
-        assertSafeSegment("id", id);
-        const result = await request("PUT", `/posts/${encodeURIComponent(id)}/`, {}, { posts: [{ updated_at, ...fields }] });
-        const post = result.posts?.[0] ?? {};
-        return {
-            id: post.id,
-            updated_at: post.updated_at,
-            meta_title: post.meta_title,
-            meta_description: post.meta_description,
-            og_title: post.og_title,
-            og_description: post.og_description,
-        };
-    },
-};
+            if (Object.keys(fields).length === 0) {
+                throw new Error(`Provide at least one of: ${SEO_FIELDS.join(", ")}.`);
+            }
+            assertSafeSegment("id", id);
+            const result = await request("PUT", `/${path}/${encodeURIComponent(id)}/`, {}, { [path]: [{ updated_at, ...fields }] });
+            const record = result[path]?.[0] ?? {};
+            return {
+                id: record.id,
+                updated_at: record.updated_at,
+                meta_title: record.meta_title,
+                meta_description: record.meta_description,
+                og_title: record.og_title,
+                og_description: record.og_description,
+            };
+        },
+    };
+}
+const seoTool = seoToolFor("post");
+const pageSeoTool = seoToolFor("page");
 const tagsTool = {
     name: "update_post_tags",
     description: "Shortcut to replace the tags of a post (tag names; missing tags are created). Requires id and the current updated_at. An empty list removes all tags. [PUT /admin/posts/{id}/]",
@@ -669,6 +674,7 @@ const TOOLS = [
     ...RESOURCES.flatMap(specsForResource).map(toolFromSpec),
     ...STANDALONE_SPECS.map(toolFromSpec),
     seoTool,
+    pageSeoTool,
     tagsTool,
     endpointsTool,
     rawTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proars/ghost-mcp-server",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server for Ghost CMS: manage posts, pages, tags, SEO metadata, members, newsletters and themes through the Ghost Admin API from Claude, Cursor and other AI agents",
   "main": "dist/index.js",
   "bin": {
@@ -10,6 +10,7 @@
     "dist",
     "README.md",
     "LICENSE",
+    "CHANGELOG.md",
     ".env.example"
   ],
   "type": "module",