# Ghost MCP

This is the spec for the Ghost Blog platform MCP server.

## Goal

- The main goal is to implement the MCP tools for all https://docs.ghost.org/content-api REST actions
- Provide a comprehensive MCP server that allows Claude to interact with Ghost blog content
- Support all major Ghost Content API endpoints for reading published content

## Requirements

### Infrastructure
- Deploy a local Ghost instance using `docker compose` and figure out a way to create an API key
- Set up proper authentication using Ghost Content API keys
- Configure the MCP server to connect to the Ghost instance

### Development
- Implement MCP server using Node.js/TypeScript
- Follow MCP protocol specifications
- Include comprehensive error handling and validation
- Support proper filtering, pagination, and query parameters

## Ghost Content API Endpoints

The Ghost Content API provides read-only access to published content. All endpoints support the following:
- Content API key authentication (query parameter)
- JSON response format with consistent structure
- Filtering, pagination, and field selection
- Full caching support

### Posts
- `GET /posts/` - List all published posts
- `GET /posts/{id}/` - Get a specific post by ID
- `GET /posts/slug/{slug}/` - Get a specific post by slug

### Pages
- `GET /pages/` - List all published pages
- `GET /pages/{id}/` - Get a specific page by ID
- `GET /pages/slug/{slug}/` - Get a specific page by slug

### Tags
- `GET /tags/` - List all tags
- `GET /tags/{id}/` - Get a specific tag by ID
- `GET /tags/slug/{slug}/` - Get a specific tag by slug

### Authors
- `GET /authors/` - List all authors
- `GET /authors/{id}/` - Get a specific author by ID
- `GET /authors/slug/{slug}/` - Get a specific author by slug

### Tiers
- `GET /tiers/` - List all membership tiers

### Settings
- `GET /settings/` - Get public settings

## API Response Format

All Ghost Content API responses follow this structure:
```json
{
    "resource_type": [{ ... }],
    "meta": {
        "pagination": {
            "page": 1,
            "limit": 15,
            "pages": 1,
            "total": 1,
            "next": null,
            "prev": null
        }
    }
}
```

## MCP Tools Specification

The following MCP tools should be implemented to provide comprehensive access to the Ghost Content API:

### Posts Tools
- **`ghost_list_posts`** - List all published posts
  - Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
  - Returns: Array of post objects with pagination metadata

- **`ghost_get_post_by_id`** - Get a specific post by ID
  - Parameters: `id` (required string), `include?` (string), `fields?` (string)
  - Returns: Single post object

- **`ghost_get_post_by_slug`** - Get a specific post by slug
  - Parameters: `slug` (required string), `include?` (string), `fields?` (string)
  - Returns: Single post object

### Pages Tools
- **`ghost_list_pages`** - List all published pages
  - Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
  - Returns: Array of page objects with pagination metadata

- **`ghost_get_page_by_id`** - Get a specific page by ID
  - Parameters: `id` (required string), `include?` (string), `fields?` (string)
  - Returns: Single page object

- **`ghost_get_page_by_slug`** - Get a specific page by slug
  - Parameters: `slug` (required string), `include?` (string), `fields?` (string)
  - Returns: Single page object

### Tags Tools
- **`ghost_list_tags`** - List all tags
  - Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
  - Returns: Array of tag objects with pagination metadata

- **`ghost_get_tag_by_id`** - Get a specific tag by ID
  - Parameters: `id` (required string), `include?` (string), `fields?` (string)
  - Returns: Single tag object

- **`ghost_get_tag_by_slug`** - Get a specific tag by slug
  - Parameters: `slug` (required string), `include?` (string), `fields?` (string)
  - Returns: Single tag object

### Authors Tools
- **`ghost_list_authors`** - List all authors
  - Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
  - Returns: Array of author objects with pagination metadata

- **`ghost_get_author_by_id`** - Get a specific author by ID
  - Parameters: `id` (required string), `include?` (string), `fields?` (string)
  - Returns: Single author object

- **`ghost_get_author_by_slug`** - Get a specific author by slug
  - Parameters: `slug` (required string), `include?` (string), `fields?` (string)
  - Returns: Single author object

### Other Tools
- **`ghost_list_tiers`** - List all membership tiers
  - Parameters: `limit?` (number), `page?` (number), `include?` (string), `fields?` (string)
  - Returns: Array of tier objects

- **`ghost_get_settings`** - Get public settings
  - Parameters: None
  - Returns: Settings object

### Common Parameters
- `limit`: Number of resources to return (default: 15, max: 50)
- `page`: Page number for pagination (default: 1)
- `filter`: Filter string using Ghost's filtering syntax
- `include`: Comma-separated list of related resources to include
- `fields`: Comma-separated list of fields to return

## Docker Compose Setup

Create a `docker-compose.yml` file to run Ghost locally:

```yaml
version: '3.8'
services:
  ghost:
    image: ghost:5-alpine
    restart: always
    ports:
      - "2368:2368"
    environment:
      database__client: mysql
      database__connection__host: db
      database__connection__user: root
      database__connection__password: yourpassword
      database__connection__database: ghost
      url: http://localhost:2368
    volumes:
      - ghost_content:/var/lib/ghost/content
    depends_on:
      - db

  db:
    image: mysql:8.0
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: yourpassword
      MYSQL_DATABASE: ghost
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  ghost_content:
  mysql_data:
```

### API Key Creation Process

1. Start the Ghost instance: `docker compose up -d`
2. Visit `http://localhost:2368/ghost` to set up your admin account
3. Navigate to Settings → Integrations → Custom Integrations
4. Create a new integration to get your Content API key
5. Save the Content API key for MCP server configuration

## Configuration

The MCP server should support configuration via:

### Environment Variables
- `GHOST_URL`: Ghost instance URL (default: http://localhost:2368)
- `GHOST_CONTENT_API_KEY`: Content API key (required)
- `GHOST_VERSION`: API version (default: v5.0)

### Configuration File
Alternative JSON configuration file:
```json
{
  "ghost": {
    "url": "http://localhost:2368",
    "contentApiKey": "your-content-api-key",
    "version": "v5.0"
  }
}
```

## Implementation Details

### Project Structure
```
ghost-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── ghost-client.ts       # Ghost API client
│   ├── tools/
│   │   ├── posts.ts          # Post-related tools
│   │   ├── pages.ts          # Page-related tools
│   │   ├── tags.ts           # Tag-related tools
│   │   ├── authors.ts        # Author-related tools
│   │   └── settings.ts       # Settings and tiers tools
│   ├── types/
│   │   ├── ghost.ts          # Ghost API response types
│   │   └── mcp.ts            # MCP-specific types
│   └── utils/
│       ├── validation.ts     # Parameter validation
│       └── errors.ts         # Error handling utilities
├── package.json
├── tsconfig.json
├── docker-compose.yml
└── README.md
```

### Technology Stack
- **Node.js** (v18+) with **TypeScript**
- **@modelcontextprotocol/sdk** for MCP implementation
- **axios** or **fetch** for HTTP requests
- **zod** for runtime type validation
- **dotenv** for environment variable management

### Error Handling
- Validate all input parameters using Zod schemas
- Handle Ghost API errors gracefully with meaningful messages
- Implement retry logic for transient network errors
- Return proper MCP error responses with error codes

### Testing Strategy
- Unit tests for individual tools and utilities
- Integration tests with local Ghost instance
- Mock Ghost API responses for reliable testing
- Test parameter validation and error scenarios

### Performance Considerations
- Implement request caching where appropriate
- Use connection pooling for HTTP requests
- Support streaming responses for large datasets
- Add request rate limiting to respect Ghost API limits

## Questions for Clarification

Before proceeding with implementation, please clarify the following:

### 1. API Scope
- **Question**: Should this MCP server be read-only (Content API) or also include write operations (Admin API)?
- **Impact**: Admin API would require different authentication and additional tools for creating/updating content
- **Recommendation**: Start with read-only Content API for initial implementation

### 2. Authentication Strategy
- **Question**: Do you want to support both Content API keys and Admin API keys?
- **Impact**: Different authentication methods have different capabilities and security considerations
- **Recommendation**: Begin with Content API keys only

### 3. Filtering and Pagination
- **Question**: Should all Ghost API filtering/pagination options be exposed as tool parameters?
- **Impact**: More parameters provide flexibility but increase complexity
- **Options**:
  - Full parameter exposure (complete flexibility)
  - Simplified parameter set (easier to use)
  - Progressive enhancement (start simple, add more later)

### 4. Error Handling Strategy
- **Question**: Any specific error handling or retry logic requirements?
- **Impact**: Affects reliability and user experience
- **Considerations**: Network timeouts, rate limits, API downtime

### 5. Configuration Management
- **Question**: How should the Ghost instance URL and API keys be configured?
- **Options**:
  - Environment variables only
  - Configuration file only
  - Both (with precedence order)
  - Runtime configuration via MCP parameters

### 6. Additional Features
- **Question**: Are there any additional features beyond basic CRUD operations?
- **Examples**:
  - Content search across posts/pages
  - Bulk operations
  - Content analytics/statistics
  - Webhook support for real-time updates

### 7. Development Environment
- **Question**: Should the development setup include sample Ghost content for testing?
- **Impact**: Makes testing and development easier but increases setup complexity

Please provide guidance on these questions to ensure the implementation meets your specific needs and use cases.