luiz/ghost-mcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ghost-mcp/SPEC.md
Luiz Costa 777d4e1f56 finish clarification
2025-09-22 23:39:30 -03:00

696 lines
28 KiB
Markdown
Raw Blame History

# 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 Ghost REST API actions (both Content and Admin APIs)
- Provide a comprehensive MCP server that allows Claude to interact with Ghost blog content for both reading and writing
- Support all major Ghost Content API endpoints for reading published content
- Support all major Ghost Admin API endpoints for creating, updating, and deleting content
## Requirements
### Infrastructure
- Deploy a local Ghost instance using `docker compose` and figure out a way to create API keys
- Set up proper authentication using both Ghost Content API keys (read-only) and Admin API keys (read/write)
- Configure the MCP server to connect to the Ghost instance with appropriate permissions
### 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
## Ghost Admin API Endpoints
The Ghost Admin API provides full read/write access to all Ghost content. All endpoints require Admin API authentication.
### Posts (Admin)
- `GET /admin/posts/` - Browse posts (including drafts)
- `GET /admin/posts/{id}/` - Read a specific post
- `POST /admin/posts/` - Create a new post
- `PUT /admin/posts/{id}/` - Update an existing post
- `POST /admin/posts/{id}/copy/` - Copy a post
- `DELETE /admin/posts/{id}/` - Delete a post
### Pages (Admin)
- `GET /admin/pages/` - Browse pages (including drafts)
- `GET /admin/pages/{id}/` - Read a specific page
- `POST /admin/pages/` - Create a new page
- `PUT /admin/pages/{id}/` - Update an existing page
- `POST /admin/pages/{id}/copy/` - Copy a page
- `DELETE /admin/pages/{id}/` - Delete a page
### Tags (Admin)
- `GET /admin/tags/` - Browse all tags
- `GET /admin/tags/{id}/` - Read a specific tag
- `POST /admin/tags/` - Create a new tag
- `PUT /admin/tags/{id}/` - Update an existing tag
- `DELETE /admin/tags/{id}/` - Delete a tag
### Tiers (Admin)
- `GET /admin/tiers/` - Browse membership tiers
- `GET /admin/tiers/{id}/` - Read a specific tier
- `POST /admin/tiers/` - Create a new tier
- `PUT /admin/tiers/{id}/` - Update an existing tier
### Members (Admin)
- `GET /admin/members/` - Browse members
- `GET /admin/members/{id}/` - Read a specific member
- `POST /admin/members/` - Create a new member
- `PUT /admin/members/{id}/` - Update an existing member
### Users (Admin)
- `GET /admin/users/` - Browse users
- `GET /admin/users/{id}/` - Read a specific user
### Media (Admin)
- `POST /admin/images/upload/` - Upload images
- `POST /admin/media/upload/` - Upload media files
### Themes (Admin)
- `POST /admin/themes/upload/` - Upload theme
- `PUT /admin/themes/{name}/activate/` - Activate theme
### Webhooks (Admin)
- `GET /admin/webhooks/` - Browse webhooks
- `POST /admin/webhooks/` - Create webhook
- `PUT /admin/webhooks/{id}/` - Update webhook
- `DELETE /admin/webhooks/{id}/` - Delete webhook
### Newsletters (Admin)
- `GET /admin/newsletters/` - Browse newsletters
- `GET /admin/newsletters/{id}/` - Read newsletter
- `POST /admin/newsletters/` - Create newsletter
- `PUT /admin/newsletters/{id}/` - Update newsletter
### Offers (Admin)
- `GET /admin/offers/` - Browse offers
- `GET /admin/offers/{id}/` - Read offer
- `POST /admin/offers/` - Create offer
- `PUT /admin/offers/{id}/` - Update offer
## 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
## Admin API MCP Tools
The following MCP tools provide full read/write access to Ghost content via the Admin API:
### Posts Admin Tools
- **`ghost_admin_list_posts`** - Browse all posts (including drafts)
- Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
- Returns: Array of post objects with pagination metadata
- **`ghost_admin_get_post`** - Read a specific post by ID
- Parameters: `id` (required string), `include?` (string), `fields?` (string)
- Returns: Single post object
- **`ghost_admin_create_post`** - Create a new post
- Parameters: `title` (required string), `html?` (string), `mobiledoc?` (string), `lexical?` (string), `status?` (string), `slug?` (string), `excerpt?` (string), `meta_title?` (string), `meta_description?` (string), `tags?` (array), `authors?` (array), `featured?` (boolean), `published_at?` (string)
- Returns: Created post object
- **`ghost_admin_update_post`** - Update an existing post
- Parameters: `id` (required string), `title?` (string), `html?` (string), `mobiledoc?` (string), `lexical?` (string), `status?` (string), `slug?` (string), `excerpt?` (string), `meta_title?` (string), `meta_description?` (string), `tags?` (array), `authors?` (array), `featured?` (boolean), `published_at?` (string), `updated_at` (required string)
- Returns: Updated post object
- **`ghost_admin_copy_post`** - Copy an existing post
- Parameters: `id` (required string)
- Returns: Copied post object
- **`ghost_admin_delete_post`** - Delete a post
- Parameters: `id` (required string)
- Returns: Success confirmation
### Pages Admin Tools
- **`ghost_admin_list_pages`** - Browse all pages (including drafts)
- Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
- Returns: Array of page objects with pagination metadata
- **`ghost_admin_get_page`** - Read a specific page by ID
- Parameters: `id` (required string), `include?` (string), `fields?` (string)
- Returns: Single page object
- **`ghost_admin_create_page`** - Create a new page
- Parameters: `title` (required string), `html?` (string), `mobiledoc?` (string), `lexical?` (string), `status?` (string), `slug?` (string), `excerpt?` (string), `meta_title?` (string), `meta_description?` (string), `tags?` (array), `authors?` (array), `featured?` (boolean), `published_at?` (string)
- Returns: Created page object
- **`ghost_admin_update_page`** - Update an existing page
- Parameters: `id` (required string), `title?` (string), `html?` (string), `mobiledoc?` (string), `lexical?` (string), `status?` (string), `slug?` (string), `excerpt?` (string), `meta_title?` (string), `meta_description?` (string), `tags?` (array), `authors?` (array), `featured?` (boolean), `published_at?` (string), `updated_at` (required string)
- Returns: Updated page object
- **`ghost_admin_copy_page`** - Copy an existing page
- Parameters: `id` (required string)
- Returns: Copied page object
- **`ghost_admin_delete_page`** - Delete a page
- Parameters: `id` (required string)
- Returns: Success confirmation
### Tags Admin Tools
- **`ghost_admin_list_tags`** - Browse all tags
- Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
- Returns: Array of tag objects with pagination metadata
- **`ghost_admin_get_tag`** - Read a specific tag by ID
- Parameters: `id` (required string), `include?` (string), `fields?` (string)
- Returns: Single tag object
- **`ghost_admin_create_tag`** - Create a new tag
- Parameters: `name` (required string), `slug?` (string), `description?` (string), `feature_image?` (string), `meta_title?` (string), `meta_description?` (string), `visibility?` (string)
- Returns: Created tag object
- **`ghost_admin_update_tag`** - Update an existing tag
- Parameters: `id` (required string), `name?` (string), `slug?` (string), `description?` (string), `feature_image?` (string), `meta_title?` (string), `meta_description?` (string), `visibility?` (string), `updated_at` (required string)
- Returns: Updated tag object
- **`ghost_admin_delete_tag`** - Delete a tag
- Parameters: `id` (required string)
- Returns: Success confirmation
### Members Admin Tools
- **`ghost_admin_list_members`** - Browse all members
- Parameters: `limit?` (number), `page?` (number), `filter?` (string), `include?` (string), `fields?` (string)
- Returns: Array of member objects with pagination metadata
- **`ghost_admin_get_member`** - Read a specific member by ID
- Parameters: `id` (required string), `include?` (string), `fields?` (string)
- Returns: Single member object
- **`ghost_admin_create_member`** - Create a new member
- Parameters: `email` (required string), `name?` (string), `note?` (string), `subscribed?` (boolean), `comped?` (boolean), `labels?` (array), `newsletters?` (array)
- Returns: Created member object
- **`ghost_admin_update_member`** - Update an existing member
- Parameters: `id` (required string), `email?` (string), `name?` (string), `note?` (string), `subscribed?` (boolean), `comped?` (boolean), `labels?` (array), `newsletters?` (array), `updated_at` (required string)
- Returns: Updated member object
### Media Admin Tools
- **`ghost_admin_upload_image`** - Upload an image
- Parameters: `file` (required file/base64), `purpose?` (string), `ref?` (string)
- Returns: Uploaded image URL and metadata
- **`ghost_admin_upload_media`** - Upload media file
- Parameters: `file` (required file/base64), `purpose?` (string), `ref?` (string)
- Returns: Uploaded media URL and metadata
### Tiers Admin Tools
- **`ghost_admin_list_tiers`** - Browse membership tiers
- Parameters: `limit?` (number), `page?` (number), `include?` (string), `fields?` (string)
- Returns: Array of tier objects
- **`ghost_admin_get_tier`** - Read a specific tier by ID
- Parameters: `id` (required string), `include?` (string), `fields?` (string)
- Returns: Single tier object
- **`ghost_admin_create_tier`** - Create a new membership tier
- Parameters: `name` (required string), `description?` (string), `monthly_price?` (number), `yearly_price?` (number), `currency?` (string), `trial_days?` (number), `visibility?` (string), `welcome_page_url?` (string), `benefits?` (array)
- Returns: Created tier object
- **`ghost_admin_update_tier`** - Update an existing tier
- Parameters: `id` (required string), `name?` (string), `description?` (string), `monthly_price?` (number), `yearly_price?` (number), `currency?` (string), `trial_days?` (number), `visibility?` (string), `welcome_page_url?` (string), `benefits?` (array), `updated_at` (required string)
- Returns: Updated tier object
### Webhooks Admin Tools
- **`ghost_admin_list_webhooks`** - Browse webhooks
- Parameters: `limit?` (number), `page?` (number)
- Returns: Array of webhook objects
- **`ghost_admin_create_webhook`** - Create a new webhook
- Parameters: `event` (required string), `target_url` (required string), `name?` (string), `secret?` (string), `api_version?` (string), `integration_id?` (string)
- Returns: Created webhook object
- **`ghost_admin_update_webhook`** - Update an existing webhook
- Parameters: `id` (required string), `event?` (string), `target_url?` (string), `name?` (string), `secret?` (string), `api_version?` (string), `updated_at` (required string)
- Returns: Updated webhook object
- **`ghost_admin_delete_webhook`** - Delete a webhook
- Parameters: `id` (required string)
- Returns: Success confirmation
### Theme Admin Tools
- **`ghost_admin_upload_theme`** - Upload a new theme
- Parameters: `file` (required file/base64), `activate?` (boolean)
- Returns: Theme upload result
- **`ghost_admin_activate_theme`** - Activate an installed theme
- Parameters: `name` (required string)
- Returns: Activation result
### Advanced Features (Stub Implementation)
- **`ghost_admin_search_content`** - Search across all content (STUB)
- Parameters: `query` (required string), `content_types?` (array), `limit?` (number)
- Returns: Search results across posts, pages, etc.
- **`ghost_admin_bulk_operation`** - Perform bulk operations (STUB)
- Parameters: `operation` (required string), `resource_type` (required string), `filters?` (object), `data?` (object)
- Returns: Bulk operation results
- **`ghost_admin_site_analytics`** - Get site analytics data (STUB)
- Parameters: `metric` (required string), `date_range?` (object), `granularity?` (string)
- Returns: Analytics data
- **`ghost_admin_export_content`** - Export site content (STUB)
- Parameters: `format?` (string), `include?` (array)
- Returns: Export data or download URL
- **`ghost_admin_import_content`** - Import content to site (STUB)
- Parameters: `file` (required file/base64), `format?` (string), `options?` (object)
- Returns: Import results
### Common Parameters
All tools support comprehensive filtering and pagination:
- `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 (Phase 1: basic filters, Phase 2: advanced syntax)
- `include`: Comma-separated list of related resources to include (e.g., "tags,authors")
- `fields`: Comma-separated list of fields to return (e.g., "id,title,slug,published_at")
#### Filtering Examples (Phase 1 Support)
- `filter=featured:true` - Get featured posts
- `filter=status:published` - Get published content
- `filter=tag:news` - Get posts with "news" tag
- `filter=author:john-doe` - Get content by specific author
#### Advanced Filtering (Phase 2 - Future Implementation)
- Complex queries with operators (`+`, `>`, `<`, etc.)
- Multiple filter combinations
- Date range filtering
- Full-text search capabilities
**Note**: Advanced filter strings will be passed directly to Ghost API as stubs until Phase 2 implementation.
## 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 custom integration which provides:
- **Content API Key**: For read-only access to published content
- **Admin API Key**: For full read/write access to all Ghost content
5. Save both API keys for MCP server configuration
### Authentication Types
#### Content API Authentication
- **Purpose**: Read-only access to published content
- **Security**: Safe for browser/public environments
- **Authentication**: Content API key passed as query parameter
- **Scope**: Posts, pages, tags, authors, tiers, settings (published content only)
#### Admin API Authentication
- **Purpose**: Full read/write access to all Ghost content
- **Security**: Must remain secret, server-side only
- **Authentication**: Admin API key with JWT token generation
- **Scope**: All Ghost resources including drafts, members, webhooks, media uploads
## Configuration
The MCP server uses a priority-based configuration system:
### Configuration Precedence (Highest to Lowest)
1. **Environment Variables** - Direct system environment variables
2. **`./.env` File** - Local environment file in project root
3. **Default Values** - Built-in fallback defaults
### Environment Variables
- `GHOST_URL`: Ghost instance URL (default: http://localhost:2368)
- `GHOST_CONTENT_API_KEY`: Content API key (required for read operations)
- `GHOST_ADMIN_API_KEY`: Admin API key (required for write operations)
- `GHOST_VERSION`: API version (default: v5.0)
- `MCP_GHOST_MODE`: Operation mode - "readonly", "readwrite", or "auto" (default: "auto")
### .env File Example
Create a `./.env` file in the project root:
```env
GHOST_URL=http://localhost:2368
GHOST_CONTENT_API_KEY=your-content-api-key
GHOST_ADMIN_API_KEY=your-admin-api-key
GHOST_VERSION=v5.0
MCP_GHOST_MODE=readwrite
```
### Operation Modes
- **readonly**: Only Content API tools are available (requires Content API key)
- **readwrite**: All tools available (requires both Content and Admin API keys)
- **auto**: Automatically detects available keys and enables appropriate tools
### Configuration Loading Process
1. Load built-in default values
2. Read and merge `./.env` file (if exists)
3. Override with environment variables (if set)
4. Validate required configuration is present
5. Initialize appropriate API clients based on available keys
## Implementation Details
### Project Structure
```
ghost-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── ghost-client.ts # Ghost API client (both Content and Admin)
│ ├── auth/
│ │ ├── content-auth.ts # Content API authentication
│ │ └── admin-auth.ts # Admin API JWT authentication
│ ├── tools/
│ │ ├── content/ # Content API tools (read-only)
│ │ │ ├── posts.ts
│ │ │ ├── pages.ts
│ │ │ ├── tags.ts
│ │ │ ├── authors.ts
│ │ │ └── settings.ts
│ │ └── admin/ # Admin API tools (read/write)
│ │ ├── posts.ts
│ │ ├── pages.ts
│ │ ├── tags.ts
│ │ ├── members.ts
│ │ ├── media.ts
│ │ ├── tiers.ts
│ │ └── webhooks.ts
│ ├── 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
- **jsonwebtoken** for Admin API JWT authentication
- **zod** for runtime type validation
- **dotenv** for environment variable management
- **multer** or equivalent for file upload handling
- **winston** or **pino** for structured logging
- **uuid** for request ID generation
### Error Handling
- **Comprehensive Error Coverage**: Handle all error categories (network, auth, API, MCP, file upload)
- **Mandatory Logging**: Structured JSON logs with required fields for all operations
- **Parameter Validation**: Use Zod schemas with detailed validation error messages
- **Retry Logic**: Exponential backoff for transient errors, respect rate limits
- **Authentication Handling**: JWT refresh for Admin API, graceful Content API fallback
- **MCP Error Responses**: Proper error codes and user-friendly messages
- **Security**: Never log sensitive data (API keys, tokens, personal info)
- **Monitoring**: Request IDs for tracing, performance metrics logging
### 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. Filtering and Pagination ✅ RESOLVED
- **Decision**: Both filtering and pagination must be fully supported
- **Implementation Strategy**:
- Start with core filtering/pagination parameters for initial implementation
- Add stubs for complex Ghost filtering syntax that can be implemented later
- Ensure all tools support basic `limit`, `page`, `filter`, `include`, and `fields` parameters
- **Approach**:
- **Phase 1**: Basic filtering (simple field=value filters) and standard pagination
- **Phase 2 (Future)**: Advanced Ghost filtering syntax (complex queries, operators)
- **Stub Implementation**: Accept advanced filter strings but pass them directly to Ghost API
### 2. Error Handling Strategy ✅ RESOLVED
- **Decision**: Comprehensive error handling with mandatory detailed logging
- **Requirements**:
- Handle all possible error scenarios
- Output comprehensive logs for debugging and monitoring
- Implement appropriate retry logic for transient failures
- Graceful degradation when services are unavailable
#### Error Categories to Handle:
1. **Network Errors**
- Connection timeouts
- DNS resolution failures
- Network connectivity issues
- SSL/TLS certificate problems
2. **Authentication Errors**
- Invalid API keys (Content/Admin)
- JWT token generation failures
- Token expiration
- Permission denied errors
3. **Ghost API Errors**
- Rate limiting (429 status)
- Server errors (5xx status)
- Client errors (4xx status)
- Invalid request format
- Resource not found (404)
- Validation errors
4. **MCP Protocol Errors**
- Invalid tool parameters
- Schema validation failures
- Unsupported operations
5. **File Upload Errors**
- File size limits exceeded
- Unsupported file types
- Storage failures
#### Logging Requirements:
- **Log Level**: DEBUG, INFO, WARN, ERROR
- **Log Format**: Structured JSON with timestamps
- **Required Fields**:
- `timestamp`, `level`, `tool_name`, `operation`, `error_code`, `error_message`, `request_id`, `ghost_api_response`, `retry_count`, `user_context`
- **Sensitive Data**: Never log API keys or personal information
- **Log Destinations**: Console (development), File/Service (production)
#### Retry Logic:
- **Transient Errors**: 3 retries with exponential backoff
- **Rate Limits**: Respect retry-after headers
- **Authentication**: Single retry after token refresh
- **Network**: Progressive timeout increases
### 3. Configuration Management ✅ RESOLVED
- **Decision**: Environment variables have priority, then `./.env` file
- **Configuration Precedence** (highest to lowest):
1. **Environment Variables** - Direct system environment variables
2. **`./.env` File** - Local environment file in project root
3. **Default Values** - Fallback defaults for optional settings
#### Configuration Loading Process:
1. Load default configuration values
2. Read and parse `./.env` file (if exists)
3. Override with actual environment variables
4. Validate required configuration is present
#### Required vs Optional Variables:
- **Required**: `GHOST_URL`, `GHOST_CONTENT_API_KEY` or `GHOST_ADMIN_API_KEY` (at least one)
- **Optional**: `GHOST_VERSION`, `MCP_GHOST_MODE`, logging settings
### 4. Additional Features ✅ RESOLVED
- **Decision**: Everything available in the Ghost REST API must be covered
- **Implementation Strategy**: If too complex, implement stubs for future development
#### Complete Ghost API Coverage Required:
1. **Content Operations** (✅ Already Specified)
- Posts, Pages, Tags, Authors (CRUD operations)
- Draft management and publishing workflows
- Content copying and duplication
2. **Member Management** (✅ Already Specified)
- Member CRUD operations
- Subscription management
- Newsletter assignments
3. **Media Management** (✅ Already Specified)
- Image and file uploads
- Media metadata management
4. **Site Management** (✅ Already Specified)
- Settings configuration
- Tier/membership management
- Webhook management
5. **Advanced Features** (⚠️ Stub Implementation Required)
- **Theme Management**: Upload, activate, delete themes
- **Site Analytics**: Traffic, member statistics (if available via API)
- **Content Search**: Full-text search across content
- **Bulk Operations**: Batch create/update/delete operations
- **Content Scheduling**: Advanced publishing schedules
- **Email Campaigns**: Newsletter creation and sending (if available)
- **Comment Management**: If Ghost comments API is available
- **Integration Management**: Third-party integrations
- **Site Migration**: Import/export functionality
#### Stub Implementation Approach:
- **Phase 1**: Core CRUD operations (already specified)
- **Phase 2**: Advanced features with basic implementations
- **Phase 3**: Full feature implementations
**Note**: All Ghost REST API endpoints will be mapped to MCP tools, with complex features initially implemented as pass-through stubs to the Ghost API.
Reference in a new issue View git blame Copy permalink