@junis/ghost-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fanyang Meng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# Ghost MCP Server
+
+## ‼️ Important Notice: Python to TypeScript Migration
+I've completely rewritten the Ghost MCP Server from Python to TypeScript in this v0.1.0 release. This major change brings several benefits:
+
+- Simplified installation: Now available as an NPM package (@fanyangmeng/ghost-mcp)
+- Improved reliability: Uses the official @tryghost/admin-api client instead of custom implementation
+- Better maintainability: TypeScript provides type safety and better code organization
+- Streamlined configuration: Simple environment variable setup
+
+### Breaking Changes
+
+- Python dependencies are no longer required
+- Configuration method has changed (now using Node.js environment variables)
+- Docker deployment has been simplified
+- Different installation process (now using NPM)
+
+Please see the below updated documentation for details on migrating from the Python version. If you encounter any issues, feel free to open an issue on GitHub.
+
+---
+
+A Model Context Protocol (MCP) server for interacting with Ghost CMS through LLM interfaces like Claude. This server provides secure and comprehensive access to your Ghost blog, leveraging JWT authentication and a rich set of MCP tools for managing posts, users, members, tiers, offers, and newsletters.
+
+![demo](./assets/ghost-mcp-demo.gif)
+
+## Features
+
+- Secure Ghost Admin API requests with `@tryghost/admin-api`
+- Comprehensive entity access including posts, users, members, tiers, offers, and newsletters
+- Advanced search functionality with both fuzzy and exact matching options
+- Detailed, human-readable output for Ghost entities
+- Robust error handling using custom `GhostError` exceptions
+- Integrated logging support via MCP context for enhanced troubleshooting
+
+## Usage
+
+To use this with MCP clients, for instance, Claude Desktop, add the following to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+      "ghost-mcp": {
+        "command": "npx",
+        "args": ["-y", "@fanyangmeng/ghost-mcp"],
+        "env": {
+            "GHOST_API_URL": "https://yourblog.com",
+            "GHOST_ADMIN_API_KEY": "your_admin_api_key",
+            "GHOST_API_VERSION": "v5.0"
+        }
+      }
+    }
+}
+```
+
+## Available Resources
+
+The following Ghost CMS resources are available through this MCP server:
+
+- **Posts**: Articles and content published on your Ghost site.
+- **Members**: Registered users and subscribers of your site.
+- **Newsletters**: Email newsletters managed and sent via Ghost.
+- **Offers**: Promotional offers and discounts for members.
+- **Invites**: Invitations for new users or staff to join your Ghost site.
+- **Roles**: User roles and permissions within the Ghost admin.
+- **Tags**: Organizational tags for posts and content.
+- **Tiers**: Subscription tiers and plans for members.
+- **Users**: Admin users and staff accounts.
+- **Webhooks**: Automated event notifications to external services.
+
+## Available Tools
+
+This MCP server exposes a comprehensive set of tools for managing your Ghost CMS via the Model Context Protocol. Each resource provides a set of operations, typically including browsing, reading, creating, editing, and deleting entities. Below is a summary of the available tools:
+
+### Posts
+- **Browse Posts**: List posts with optional filters, pagination, and ordering.
+- **Read Post**: Retrieve a post by ID or slug.
+- **Add Post**: Create a new post with title, content, and status.
+- **Edit Post**: Update an existing post by ID.
+- **Delete Post**: Remove a post by ID.
+
+### Members
+- **Browse Members**: List members with filters and pagination.
+- **Read Member**: Retrieve a member by ID or email.
+- **Add Member**: Create a new member.
+- **Edit Member**: Update member details.
+- **Delete Member**: Remove a member.
+
+### Newsletters
+- **Browse Newsletters**: List newsletters.
+- **Read Newsletter**: Retrieve a newsletter by ID.
+- **Add Newsletter**: Create a new newsletter.
+- **Edit Newsletter**: Update newsletter details.
+- **Delete Newsletter**: Remove a newsletter.
+
+### Offers
+- **Browse Offers**: List offers.
+- **Read Offer**: Retrieve an offer by ID.
+- **Add Offer**: Create a new offer.
+- **Edit Offer**: Update offer details.
+- **Delete Offer**: Remove an offer.
+
+### Invites
+- **Browse Invites**: List invites.
+- **Add Invite**: Create a new invite.
+- **Delete Invite**: Remove an invite.
+
+### Roles
+- **Browse Roles**: List roles.
+- **Read Role**: Retrieve a role by ID.
+
+### Tags
+- **Browse Tags**: List tags.
+- **Read Tag**: Retrieve a tag by ID or slug.
+- **Add Tag**: Create a new tag.
+- **Edit Tag**: Update tag details.
+- **Delete Tag**: Remove a tag.
+
+### Tiers
+- **Browse Tiers**: List tiers.
+- **Read Tier**: Retrieve a tier by ID.
+- **Add Tier**: Create a new tier.
+- **Edit Tier**: Update tier details.
+- **Delete Tier**: Remove a tier.
+
+### Users
+- **Browse Users**: List users.
+- **Read User**: Retrieve a user by ID or slug.
+- **Edit User**: Update user details.
+- **Delete User**: Remove a user.
+
+### Webhooks
+- **Browse Webhooks**: List webhooks.
+- **Add Webhook**: Create a new webhook.
+- **Delete Webhook**: Remove a webhook.
+
+> Each tool is accessible via the MCP protocol and can be invoked from compatible clients. For detailed parameter schemas and usage, see the source code in `src/tools/`.
+
+
+## Error Handling
+
+Ghost MCP Server employs a custom `GhostError` exception to handle API communication errors and processing issues. This ensures clear and descriptive error messages to assist with troubleshooting.
+
+## Contributing
+
+1. Fork repository
+2. Create feature branch
+3. Commit changes
+4. Create pull request
+
+## License
+
+MIT

package/build/config.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GHOST_API_VERSION = exports.GHOST_ADMIN_API_KEY = exports.GHOST_API_URL = void 0;
+// Read configuration values directly from process.env
+exports.GHOST_API_URL = process.env.GHOST_API_URL;
+exports.GHOST_ADMIN_API_KEY = process.env.GHOST_ADMIN_API_KEY;
+exports.GHOST_API_VERSION = process.env.GHOST_API_VERSION || 'v5.0'; // Default to v5.0
+// Basic validation to ensure required environment variables are set
+if (!exports.GHOST_API_URL) {
+    console.error("Error: GHOST_API_URL environment variable is not set.");
+    process.exit(1);
+}
+if (!exports.GHOST_ADMIN_API_KEY) {
+    console.error("Error: GHOST_ADMIN_API_KEY environment variable is not set.");
+    process.exit(1);
+}

package/build/ghostApi.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ghostApiClient = void 0;
+const admin_api_1 = __importDefault(require("@tryghost/admin-api"));
+const config_1 = require("./config");
+// Initialize and export the Ghost Admin API client instance.
+// Configuration is loaded from src/config.ts.
+exports.ghostApiClient = new admin_api_1.default({
+    url: config_1.GHOST_API_URL,
+    key: config_1.GHOST_ADMIN_API_KEY,
+    version: config_1.GHOST_API_VERSION
+});
+// You can add helper functions here to wrap API calls and handle errors
+// For example:
+/*
+export async function getPostById(postId: string): Promise<any> {
+    try {
+        const post = await ghostApiClient.posts.read({ id: postId });
+        return post;
+    } catch (error) {
+        console.error(`Error fetching post ${postId}:`, error);
+        throw new Error(`Failed to fetch post ${postId}`);
+    }
+}
+*/ 

package/build/models.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/prompts.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPrompts = registerPrompts;
+// src/prompts.ts
+const zod_1 = require("zod");
+const ghostApi_1 = require("./ghostApi");
+// Example prompt: summarize-post
+function registerPrompts(server) {
+    server.prompt("summarize-post", { postId: zod_1.z.string() }, async ({ postId }) => {
+        // Fetch the post by ID
+        const post = await ghostApi_1.ghostApiClient.posts.read({ id: postId });
+        const title = post.title || "";
+        const excerpt = post.excerpt || "";
+        const html = post.html || "";
+        // Compose a summary message
+        const summary = `Title: ${title}\nExcerpt: ${excerpt}\n\nContent Preview:\n${html.slice(0, 300)}...`;
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Summarize the following Ghost post:\n\n${summary}`,
+                    },
+                },
+            ],
+        };
+    });
+}

package/build/resources.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handlePostResource = exports.handleNewsletterResource = exports.handleOfferResource = exports.handleTierResource = exports.handleMemberResource = exports.handleUserResource = void 0;
+exports.handleBlogInfoResource = handleBlogInfoResource;
+// Handler for the user resource
+const handleUserResource = async (uri, variables) => {
+    try {
+        const userId = variables.user_id; // Access parameter from variables
+        if (!userId) {
+            // TODO: Return a structured MCP error for missing parameter
+            throw new Error("Missing user_id parameter");
+        }
+        // TODO: Use ghostApiClient to fetch user data by ID
+        // const user: User = await ghostApiClient.users.read({ id: userId });
+        // return {
+        //     contents: [{
+        //         uri: uri.href,
+        //         text: JSON.stringify(user, null, 2), // Or format as needed
+        //         mimeType: 'application/json'
+        //     }]
+        // };
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `User resource requested for ID: ${userId}`,
+                    mimeType: 'text/plain'
+                }]
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching user ${variables.user_id}:`, error);
+        // TODO: Return an error result in the MCP format
+        throw error;
+    }
+};
+exports.handleUserResource = handleUserResource;
+// Handler for the member resource
+const handleMemberResource = async (uri, variables) => {
+    try {
+        const memberId = variables.member_id; // Access parameter from variables
+        if (!memberId) {
+            // TODO: Return a structured MCP error for missing parameter
+            throw new Error("Missing member_id parameter");
+        }
+        // TODO: Use ghostApiClient to fetch member data by ID
+        // const member: Member = await ghostApiClient.members.read({ id: memberId });
+        // return {
+        //     contents: [{
+        //         uri: uri.href,
+        //         text: JSON.stringify(member, null, 2), // Or format as needed
+        //         mimeType: 'application/json'
+        //     }]
+        // };
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Member resource requested for ID: ${memberId}`,
+                    mimeType: 'text/plain'
+                }]
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching member ${variables.member_id}:`, error);
+        // TODO: Return an error result in the MCP format
+        throw error;
+    }
+};
+exports.handleMemberResource = handleMemberResource;
+// Handler for the tier resource
+const handleTierResource = async (uri, variables) => {
+    try {
+        const tierId = variables.tier_id; // Access parameter from variables
+        if (!tierId) {
+            // TODO: Return a structured MCP error for missing parameter
+            throw new Error("Missing tier_id parameter");
+        }
+        // TODO: Use ghostApiClient to fetch tier data by ID
+        // const tier: Tier = await ghostApiClient.tiers.read({ id: tierId });
+        // return {
+        //     contents: [{
+        //         uri: uri.href,
+        //         text: JSON.stringify(tier, null, 2), // Or format as needed
+        //         mimeType: 'application/json'
+        //     }]
+        // };
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Tier resource requested for ID: ${tierId}`,
+                    mimeType: 'text/plain'
+                }]
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching tier ${variables.tier_id}:`, error);
+        // TODO: Return an error result in the MCP format
+        throw error;
+    }
+};
+exports.handleTierResource = handleTierResource;
+// Handler for the offer resource
+const handleOfferResource = async (uri, variables) => {
+    try {
+        const offerId = variables.offer_id; // Access parameter from variables
+        if (!offerId) {
+            // TODO: Return a structured MCP error for missing parameter
+            throw new Error("Missing offer_id parameter");
+        }
+        // TODO: Use ghostApiClient to fetch offer data by ID
+        // const offer: Offer = await ghostApiClient.offers.read({ id: offerId });
+        // return {
+        //     contents: [{
+        //         uri: uri.href,
+        //         text: JSON.stringify(offer, null, 2), // Or format as needed
+        //         mimeType: 'application/json'
+        //     }]
+        // };
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Offer resource requested for ID: ${offerId}`,
+                    mimeType: 'text/plain'
+                }]
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching offer ${variables.offer_id}:`, error);
+        // TODO: Return an error result in the MCP format
+        throw error;
+    }
+};
+exports.handleOfferResource = handleOfferResource;
+// Handler for the newsletter resource
+const handleNewsletterResource = async (uri, variables) => {
+    try {
+        const newsletterId = variables.newsletter_id; // Access parameter from variables
+        if (!newsletterId) {
+            // TODO: Return a structured MCP error for missing parameter
+            throw new Error("Missing newsletter_id parameter");
+        }
+        // TODO: Use ghostApiClient to fetch newsletter data by ID
+        // const newsletter: Newsletter = await ghostApiClient.newsletters.read({ id: newsletterId });
+        // return {
+        //     contents: [{
+        //         uri: uri.href,
+        //         text: JSON.stringify(newsletter, null, 2), // Or format as needed
+        //         mimeType: 'application/json'
+        //     }]
+        // };
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Newsletter resource requested for ID: ${newsletterId}`,
+                    mimeType: 'text/plain'
+                }]
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching newsletter ${variables.newsletter_id}:`, error);
+        // TODO: Return an error result in the MCP format
+        throw error;
+    }
+};
+exports.handleNewsletterResource = handleNewsletterResource;
+// Handler for the post resource
+const handlePostResource = async (uri, variables) => {
+    try {
+        const postId = variables.post_id; // Access parameter from variables
+        if (!postId) {
+            // TODO: Return a structured MCP error for missing parameter
+            throw new Error("Missing post_id parameter");
+        }
+        // TODO: Use ghostApiClient to fetch post data by ID
+        // const post: Post = await ghostApiClient.posts.read({ id: postId });
+        // return {
+        //     contents: [{
+        //         uri: uri.href,
+        //         text: JSON.stringify(post, null, 2), // Or format as needed
+        //         mimeType: 'application/json'
+        //     }]
+        // };
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Post resource requested for ID: ${postId}`,
+                    mimeType: 'text/plain'
+                }]
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching post ${variables.post_id}:`, error);
+        // TODO: Return an error result in the MCP format
+        throw error;
+    }
+};
+exports.handlePostResource = handlePostResource;
+// Handler for the blog info resource
+async function handleBlogInfoResource(uri) {
+    try {
+        // TODO: Use ghostApiClient to fetch blog info
+        // const blogInfo = await ghostApiClient.site.read();
+        // return {
+        //     contents: [{
+        //         uri: uri.href,
+        //         text: JSON.stringify(blogInfo, null, 2), // Or format as needed
+        //         mimeType: 'application/json'
+        //     }]
+        // };
+        return {
+            contents: [{
+                    uri: uri.href,
+                    text: `Blog info resource requested`,
+                    mimeType: 'text/plain'
+                }]
+        };
+    }
+    catch (error) {
+        console.error(`Error fetching blog info:`, error);
+        // TODO: Return an error result in the MCP format
+        throw error;
+    }
+}

package/build/server.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const resources_1 = require("./resources"); // Import resource handlers
+// Create an MCP server instance
+const server = new mcp_js_1.McpServer({
+    name: "ghost-mcp-ts",
+    version: "1.0.0", // TODO: Get version from package.json
+    capabilities: {
+        resources: {}, // Capabilities will be enabled as handlers are registered
+        tools: {},
+        prompts: {},
+        logging: {} // Enable logging capability
+    }
+});
+// Register resource handlers
+server.resource("user", new mcp_js_1.ResourceTemplate("user://{user_id}", { list: undefined }), resources_1.handleUserResource);
+server.resource("member", new mcp_js_1.ResourceTemplate("member://{member_id}", { list: undefined }), resources_1.handleMemberResource);
+server.resource("tier", new mcp_js_1.ResourceTemplate("tier://{tier_id}", { list: undefined }), resources_1.handleTierResource);
+server.resource("offer", new mcp_js_1.ResourceTemplate("offer://{offer_id}", { list: undefined }), resources_1.handleOfferResource);
+server.resource("newsletter", new mcp_js_1.ResourceTemplate("newsletter://{newsletter_id}", { list: undefined }), resources_1.handleNewsletterResource);
+server.resource("post", new mcp_js_1.ResourceTemplate("post://{post_id}", { list: undefined }), resources_1.handlePostResource);
+server.resource("blog-info", "blog://info", resources_1.handleBlogInfoResource);
+// Register tools
+const posts_1 = require("./tools/posts");
+const members_1 = require("./tools/members");
+(0, posts_1.registerPostTools)(server);
+(0, members_1.registerMemberTools)(server);
+const users_1 = require("./tools/users");
+(0, users_1.registerUserTools)(server);
+const tags_1 = require("./tools/tags");
+(0, tags_1.registerTagTools)(server);
+const tiers_1 = require("./tools/tiers");
+(0, tiers_1.registerTierTools)(server);
+const offers_1 = require("./tools/offers");
+(0, offers_1.registerOfferTools)(server);
+const newsletters_1 = require("./tools/newsletters");
+(0, newsletters_1.registerNewsletterTools)(server);
+const invites_1 = require("./tools/invites");
+(0, invites_1.registerInviteTools)(server);
+const roles_1 = require("./tools/roles");
+(0, roles_1.registerRoleTools)(server);
+const webhooks_1 = require("./tools/webhooks");
+(0, webhooks_1.registerWebhookTools)(server);
+const prompts_1 = require("./prompts");
+(0, prompts_1.registerPrompts)(server);
+// Set up and connect to the standard I/O transport
+async function startServer() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("Ghost MCP TypeScript Server running on stdio"); // Log to stderr
+}
+// Start the server
+startServer().catch((error) => {
+    console.error("Fatal error starting server:", error);
+    process.exit(1);
+});

package/build/tools/invites.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerInviteTools = registerInviteTools;
+// src/tools/invites.ts
+const zod_1 = require("zod");
+const ghostApi_1 = require("../ghostApi");
+// Parameter schemas as ZodRawShape (object literals)
+const browseParams = {
+    filter: zod_1.z.string().optional(),
+    limit: zod_1.z.number().optional(),
+    page: zod_1.z.number().optional(),
+    order: zod_1.z.string().optional(),
+};
+const addParams = {
+    role_id: zod_1.z.string(),
+    email: zod_1.z.string(),
+};
+const deleteParams = {
+    id: zod_1.z.string(),
+};
+function registerInviteTools(server) {
+    // Browse invites
+    server.tool("invites_browse", browseParams, async (args, _extra) => {
+        const invites = await ghostApi_1.ghostApiClient.invites.browse(args);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(invites, null, 2),
+                },
+            ],
+        };
+    });
+    // Add invite
+    server.tool("invites_add", addParams, async (args, _extra) => {
+        const invite = await ghostApi_1.ghostApiClient.invites.add(args);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(invite, null, 2),
+                },
+            ],
+        };
+    });
+    // Delete invite
+    server.tool("invites_delete", deleteParams, async (args, _extra) => {
+        await ghostApi_1.ghostApiClient.invites.delete(args);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Invite with id ${args.id} deleted.`,
+                },
+            ],
+        };
+    });
+}