# mfydev/ghost-mcp architecture

> Architecture diagram of the GitHub repository mfydev/ghost-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mfydev/ghost-mcp
- Repository: https://github.com/mfydev/ghost-mcp

## Overview

##### Project Type and Purpose
- This is an open-source backend service (a Node.js/TypeScript “MCP server”) that exposes Ghost CMS’s Admin API through a Model Context Protocol (MCP) interface to LLM clients (e.g., Claude).
- Its core purpose is to act as a secure, type-safe adapter between MCP-capable LLM clients and the Ghost CMS Admin API, providing CRUD operations on posts, members, tiers, etc.

##### File Structure Analysis
- Top-level directories:
- src/ – application source code
· config.ts – loads environment variables (API URL, key, version)
· ghostApi.ts – wraps the official @tryghost/admin-api client
· prompts.ts – text templates for human-readable outputs
· resources.ts – maps MCP resource definitions to tool implementations
· server.ts – entry point that initializes the MCP server and registers tools
· tools/ – one file per Ghost resource (posts.ts, members.ts, etc.) implementing browse/read/create/edit/delete
- assets/ – demo GIF
- types/ – TypeScript declaration for the Ghost Admin API client
- Configuration & scripts:
- package.json/lock – npm config
- tsconfig.json – TypeScript compiler settings
- .gitignore, LICENSE, README.md

##### Key Insights from README
- Describes migration from Python to TS, usage as an npm package, and environment variable configuration.
- Lists all “tools” (resources) exposed via MCP: posts, members, newsletters, offers, invites, roles, tags, tiers, users, webhooks.
- Emphasizes error handling (GhostError), logging integration, and the use of the official admin API client.

##### Main Components
a. External LLM Client (e.g., Claude Desktop)
b. MCP Server
- Entry Layer: server.ts (MCP protocol listener)
- Configuration Layer: config.ts (env variables)
- Adapter Layer: ghostApi.ts wrapping @tryghost/admin-api
- Tools Layer: individual modules in src/tools/* implementing resource operations
- Utility Layer: models.ts, prompts.ts, resources.ts, error handling
c. Ghost CMS Admin API (External Service)

##### Relationships & Data Flows
- LLM Client → MCP Server: JSON-RPC or MCP calls invoking a “tool” by name
- MCP Server → Config module: load API endpoint + credentials
- MCP Server → Adapter (ghostApi.ts) → Ghost Admin API: actual HTTP requests to Ghost endpoint
- Ghost Admin API → Adapter → MCP Server → LLM Client: returns data, formatted via prompts/models

##### Architectural Patterns & Design Principles
- Layered architecture (entry → config → adapter → tools → external API)
- Adapter/Facade pattern: ghostApi.ts abstracts the official client
- Single Responsibility: each tool file handles only one resource
- Dependency Injection via MCP context (for logging, error handling)

##### Technologies & Frameworks
- Node.js, TypeScript
- @tryghost/admin-api (official Ghost Admin client)
- MCP protocol framework (implicit in server.ts)
- npm packaging for distribution

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef external fill:#D3D3F3,stroke:#666,stroke-width:1px;
    classDef entry fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef config fill:#FFF2CC,stroke:#333,stroke-width:1px;
    classDef adapter fill:#B4C7E7,stroke:#333,stroke-width:1px;
    classDef util fill:#D9D9D9,stroke:#333,stroke-width:1px;
    classDef tools fill:#C6E0B4,stroke:#333,stroke-width:1px;
    classDef db fill:#B2A1C7,stroke:#333,stroke-width:1px;

    LLM["LLM Client"]:::external

    subgraph "MCP Server"
        subgraph "Entry Layer"
            SRV["server.ts"]:::entry
        end
        subgraph "Configuration Layer"
            CFG["config.ts"]:::config
        end
        subgraph "Adapter Layer"
            APIWRAP["ghostApi.ts"]:::adapter
            CLIENT["@tryghost/admin-api"]:::external
        end
        subgraph "Utility Layer"
            MODELS["models.ts"]:::util
            PROMPTS["prompts.ts"]:::util
            RES["resources.ts"]:::util
        end
        subgraph "Tools Layer"
            PO["posts.ts"]:::tools
            ME["members.ts"]:::tools
            NL["newsletters.ts"]:::tools
            OF["offers.ts"]:::tools
            IN["invites.ts"]:::tools
            RO["roles.ts"]:::tools
            TA["tags.ts"]:::tools
            TI["tiers.ts"]:::tools
            US["users.ts"]:::tools
            WH["webhooks.ts"]:::tools
        end
    end

    Ghost["Ghost CMS Admin API"]:::db

    LLM -->|"MCP calls"| SRV
    SRV -->|"load env"| CFG
    SRV -->|"register resources"| RES
    RES --> PO
    RES --> ME
    RES --> NL
    RES --> OF
    RES --> IN
    RES --> RO
    RES --> TA
    RES --> TI
    RES --> US
    RES --> WH

    PO -->|"uses"| APIWRAP
    ME -->|"uses"| APIWRAP
    NL -->|"uses"| APIWRAP
    OF -->|"uses"| APIWRAP
    IN -->|"uses"| APIWRAP
    RO -->|"uses"| APIWRAP
    TA -->|"uses"| APIWRAP
    TI -->|"uses"| APIWRAP
    US -->|"uses"| APIWRAP
    WH -->|"uses"| APIWRAP

    PO -->|"imports"| MODELS
    ME -->|"imports"| MODELS
    NL -->|"imports"| MODELS
    OF -->|"imports"| MODELS
    IN -->|"imports"| MODELS
    RO -->|"imports"| MODELS
    TA -->|"imports"| MODELS
    TI -->|"imports"| MODELS
    US -->|"imports"| MODELS
    WH -->|"imports"| MODELS

    APIWRAP --> CLIENT
    CLIENT -->|"HTTPS"| Ghost
    Ghost -->|"response"| APIWRAP
    APIWRAP -->|"data"| SRV
    SRV -->|"response"| LLM

    click SRV "https://github.com/mfydev/ghost-mcp/blob/main/src/server.ts"
    click CFG "https://github.com/mfydev/ghost-mcp/blob/main/src/config.ts"
    click APIWRAP "https://github.com/mfydev/ghost-mcp/blob/main/src/ghostApi.ts"
    click PO "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/posts.ts"
    click ME "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/members.ts"
    click NL "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/newsletters.ts"
    click OF "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/offers.ts"
    click IN "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/invites.ts"
    click RO "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/roles.ts"
    click TA "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/tags.ts"
    click TI "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/tiers.ts"
    click US "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/users.ts"
    click WH "https://github.com/mfydev/ghost-mcp/blob/main/src/tools/webhooks.ts"
    click MODELS "https://github.com/mfydev/ghost-mcp/blob/main/src/models.ts"
    click PROMPTS "https://github.com/mfydev/ghost-mcp/blob/main/src/prompts.ts"
    click RES "https://github.com/mfydev/ghost-mcp/blob/main/src/resources.ts"
```
