Ghost CMS Interface Server

⚠️ Critical Update: Migration to TypeScript

Version 0.1.0 marks a complete architectural shift from the previous Python implementation to a pure TypeScript codebase. This rewrite significantly enhances stability and developer experience:

• Distribution: Now accessible via NPM as @fanyangmeng/ghost-mcp.
• API Reliability: Leverages the sanctioned @tryghost/admin-api client for all backend communication, replacing prior custom logic.
• Code Quality: TypeScript enforces static typing, improving long-term upkeep and reducing runtime surprises.
• Setup Simplicity: Configuration is streamlined via standard Node.js environment variables.

Mandatory Configuration Adjustments

• The Python runtime environment is entirely deprecated.
• Configuration parameters must now be injected as Node environment variables.
• The deployment procedure, particularly Docker setups, has been simplified.
• Installation now follows the standard NPM workflow.

Please consult the following documentation for transitioning workflows from the legacy Python structure. All transition challenges should be reported immediately via a new GitHub Issue.

---

This specialized Model Context Protocol (MCP) execution environment enables interaction with a Ghost Content Management System (CMS) using advanced language models (e.g., Claude). It furnishes secure, granular control over core platform elements: published material, subscriber rosters, monetization structures (tiers/offers), and user administration. Authentication relies on established JWT mechanisms.

Core Capabilities

• Secure backend interactions secured by the official @tryghost/admin-api.
• Full CRUD functionality across principal data entities: Articles (Posts), Subscribers (Members), Price Points (Tiers), Promotions (Offers), and Email Campaigns (Newsletters).
• Sophisticated data retrieval supporting both approximate (fuzzy) and precise (exact) search criteria.
• Generates output formatted for immediate, clear human comprehension.
• Integrates custom exception handling (GhostError) for predictable error resolution.
• Internal logging hooks accessible through the MCP runtime for diagnostics.

Initializing the Service

To integrate this gateway with an MCP client, such as Claude Desktop, configure your claude_desktop_config.json as follows:

{ "mcpServers": { "ghost-cms-gateway": { "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" } } } }

Supported CMS Entities

The following Ghost CMS domains are exposed via this gateway:

• Posts: The primary articles and site content.
• Members: Registered users and subscription holders.
• Newsletters: Scheduled and sent email publications.
• Offers: Discount codes and subscription incentives.
• Invites: System invitations for staff or new users.
• Roles: Definition of administrative permissions.
• Tags: Categorization metadata applied to content.
• Tiers: Defined monetization levels and access plans.
• Users: Administrative and staff accounts.
• Webhooks: Configurations for external service event notifications.

Available Toolset Summary

This server exposes a comprehensive set of tools conforming to the MCP standard for managing your Ghost instance. Each entity category provides the standard verbs: listing (Browse), retrieving details (Read), creation (Add), modification (Edit), and removal (Delete).

Posts Management

• Browse Posts: Retrieve paginated lists with filtering.
• Read Post: Fetch content based on unique identifier or URL slug.
• Add Post: Publish new content, setting initial status.
• Edit Post: Modify existing article attributes.
• Delete Post: Archive or permanently remove content.

Members Management

• Browse Members: List subscribers, subject to various filters.
• Read Member: Look up a subscriber via ID or email address.
• Add Member: Register a new site member.
• Edit Member: Update subscriber profile details.
• Delete Member: Remove member record.

Newsletters Management

• Browse Newsletters: Obtain a roster of email campaigns.
• Read Newsletter: Fetch specific campaign details.
• Add Newsletter: Draft a new newsletter asset.
• Edit Newsletter: Modify an existing newsletter template or content.
• Delete Newsletter: Discard a newsletter record.

Offers Management

• Browse Offers: List all defined promotional mechanisms.
• Read Offer: Retrieve specifics of a single offer.
• Add Offer: Introduce a new discount or promotion.
• Edit Offer: Adjust the parameters of an active offer.
• Delete Offer: Deactivate or remove an offer.

Invites Management

• Browse Invites: View outstanding invitations.
• Add Invite: Generate a new invitation link/record.
• Delete Invite: Revoke an unaccepted invitation.

Roles Management

• Browse Roles: List available system roles.
• Read Role: Inspect the permissions structure of a specific role.

Tags Management

• Browse Tags: List all used content tags.
• Read Tag: Fetch tag details by ID or name slug.
• Add Tag: Define a new organizational tag.
• Edit Tag: Modify tag properties.
• Delete Tag: Remove a tag from the system.

Tiers Management

• Browse Tiers: List all subscription pricing tiers.
• Read Tier: Retrieve detailed tier information.
• Add Tier: Establish a new paid or free subscription level.
• Edit Tier: Update tier benefits or pricing.
• Delete Tier: Decommission a membership tier.

Users Management

• Browse Users: List administrative and staff accounts.
• Read User: Retrieve details for a staff member.
• Edit User: Modify user attributes or permissions.
• Delete User: Deactivate or remove a staff account.

Webhooks Management

• Browse Webhooks: List configured external notification endpoints.
• Add Webhook: Register a new outbound event listener.
• Delete Webhook: Remove an existing webhook configuration.

Every function described is exposed via the MCP interface and callable by compatible clients. Comprehensive parameter specifications are documented within the source directory src/tools/.

Exception Management Strategy

The Ghost Interface Server utilizes a proprietary GhostError mechanism to encapsulate and present API faults or internal processing failures, ensuring that error feedback is both descriptive and actionable for debugging purposes.

Development Contribution Guidelines

1. Fork the primary repository.
2. Establish a dedicated feature branch.
3. Commit your modifications.
4. Submit a Pull Request for review.

Licensing

This project is released under the MIT License.