259 lines
No EOL
6.9 KiB
Markdown
259 lines
No EOL
6.9 KiB
Markdown
# Ghost MCP Server
|
|
|
|
A comprehensive Model Context Protocol (MCP) server for Ghost CMS, providing both read-only Content API and read/write Admin API access through FastMCP.
|
|
|
|
## 🎯 Features
|
|
|
|
- **Complete Ghost API Coverage**: Both Content API (read-only) and Admin API (read/write)
|
|
- **15+ MCP Tools**: Posts, pages, tags, authors, settings, and more
|
|
- **Modern Python Implementation**: FastMCP 2.12.3 with async/await
|
|
- **JWT Authentication**: Secure Admin API access with token caching
|
|
- **Robust Error Handling**: 5 error categories with comprehensive logging
|
|
- **Configuration Management**: Environment variables with precedence
|
|
- **Development Tools**: Complete Docker setup and automation scripts
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Docker and Docker Compose
|
|
- Python 3.10+ (with uv recommended)
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone <repository-url>
|
|
cd ghost-mcp
|
|
|
|
# Complete setup from scratch
|
|
make setup
|
|
|
|
# Or step by step:
|
|
make install-uv # Install uv package manager
|
|
make install # Install Python dependencies
|
|
make start-ghost # Start Ghost and database
|
|
make setup-tokens # Extract API keys and create .env
|
|
make test # Test the implementation
|
|
```
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
# Run the MCP server
|
|
make run
|
|
|
|
# Development mode with auto-reload
|
|
make dev
|
|
|
|
# Check system status
|
|
make status
|
|
|
|
# View container logs
|
|
make logs
|
|
```
|
|
|
|
## 📋 Available MCP Tools
|
|
|
|
### Content API Tools (Read-only)
|
|
|
|
- `get_posts` - Get published posts with filtering/pagination
|
|
- `get_post_by_id` - Get single post by ID
|
|
- `get_post_by_slug` - Get single post by slug
|
|
- `search_posts` - Search posts by title/content
|
|
- `get_pages` - Get published pages
|
|
- `get_page_by_id` - Get single page by ID
|
|
- `get_page_by_slug` - Get single page by slug
|
|
- `get_tags` - Get tags with filtering
|
|
- `get_tag_by_id` - Get single tag by ID
|
|
- `get_tag_by_slug` - Get single tag by slug
|
|
- `get_authors` - Get authors
|
|
- `get_author_by_id` - Get single author by ID
|
|
- `get_author_by_slug` - Get single author by slug
|
|
- `get_settings` - Get public settings
|
|
- `get_site_info` - Get basic site information
|
|
|
|
### Admin API Tools (Read/Write)
|
|
|
|
- `create_post` - Create new posts with full options
|
|
- `update_post` - Update existing posts
|
|
- `delete_post` - Delete posts
|
|
- `get_admin_posts` - Get posts including drafts
|
|
- `create_page` - Create new pages
|
|
- `create_tag` - Create new tags
|
|
|
|
### Utility Tools
|
|
|
|
- `check_ghost_connection` - Test connectivity and configuration
|
|
|
|
## 🔧 Configuration
|
|
|
|
Configuration is managed through environment variables with precedence:
|
|
|
|
1. Environment variables
|
|
2. `.env` file
|
|
3. Default values
|
|
|
|
### Required Variables
|
|
|
|
```bash
|
|
GHOST_URL=http://localhost:2368
|
|
GHOST_CONTENT_API_KEY=your_content_api_key_here
|
|
GHOST_ADMIN_API_KEY=your_admin_api_key_here
|
|
```
|
|
|
|
### Optional Variables
|
|
|
|
```bash
|
|
GHOST_VERSION=v5.0
|
|
GHOST_MODE=auto # auto, readonly, readwrite
|
|
GHOST_TIMEOUT=30
|
|
GHOST_MAX_RETRIES=3
|
|
GHOST_RETRY_BACKOFF_FACTOR=2.0
|
|
|
|
LOG_LEVEL=info # debug, info, warning, error
|
|
LOG_STRUCTURED=true
|
|
LOG_REQUEST_ID=true
|
|
```
|
|
|
|
## 🛠️ Development
|
|
|
|
### Project Structure
|
|
|
|
```
|
|
ghost-mcp/
|
|
├── src/ghost_mcp/
|
|
│ ├── server.py # FastMCP server entry point
|
|
│ ├── client.py # Ghost API client
|
|
│ ├── config.py # Configuration management
|
|
│ ├── auth/ # Authentication modules
|
|
│ ├── tools/
|
|
│ │ ├── content/ # Content API tools
|
|
│ │ └── admin/ # Admin API tools
|
|
│ ├── types/ # Type definitions
|
|
│ └── utils/ # Utilities
|
|
├── scripts/ # Setup and test scripts
|
|
├── contracts/ # API documentation
|
|
├── docker-compose.yml # Ghost + MySQL setup
|
|
├── Makefile # Development commands
|
|
└── pyproject.toml # Python project config
|
|
```
|
|
|
|
### Available Commands
|
|
|
|
```bash
|
|
make help # Show all commands
|
|
make setup # Complete setup from scratch
|
|
make install # Install dependencies with uv
|
|
make start-ghost # Start Ghost containers
|
|
make setup-tokens # Generate API keys
|
|
make test # Run tests
|
|
make test-connection # Test API connectivity
|
|
make run # Run MCP server
|
|
make status # Check system status
|
|
make clean # Clean up everything
|
|
```
|
|
|
|
## 🐳 Docker Environment
|
|
|
|
The project includes a complete Docker Compose setup:
|
|
|
|
- **Ghost**: Latest Ghost 5.x with Alpine Linux
|
|
- **MySQL 8.0**: Database with health checks
|
|
- **Development optimized**: Logging, auto-restart, volume persistence
|
|
|
|
### URLs
|
|
|
|
- **Ghost Admin**: http://localhost:2368/ghost/
|
|
- **Ghost Site**: http://localhost:2368/
|
|
- **Database**: localhost:3306
|
|
|
|
## 🔐 API Authentication
|
|
|
|
### Content API
|
|
- Uses query parameter authentication
|
|
- 26-character hex API key
|
|
- Read-only access to published content
|
|
|
|
### Admin API
|
|
- Uses JWT token authentication
|
|
- Format: `id:secret` (24-char + 64-char hex)
|
|
- 5-minute token expiration with automatic renewal
|
|
- Full read/write access
|
|
|
|
## 📊 Error Handling
|
|
|
|
Comprehensive error handling with 5 categories:
|
|
|
|
1. **Network Errors**: Connection timeouts, DNS failures
|
|
2. **Authentication Errors**: Invalid keys, expired tokens
|
|
3. **Ghost API Errors**: Ghost-specific errors with codes
|
|
4. **Validation Errors**: Invalid parameters, malformed data
|
|
5. **File Upload Errors**: Media upload failures
|
|
|
|
All errors include:
|
|
- Unique error ID
|
|
- Category classification
|
|
- Context information
|
|
- Request ID for tracing
|
|
|
|
## 🧪 Testing
|
|
|
|
```bash
|
|
# Test Ghost API connectivity
|
|
make test-connection
|
|
|
|
# Run all tests
|
|
make test
|
|
|
|
# Test specific functionality
|
|
python scripts/test-connection.py
|
|
```
|
|
|
|
## 📝 Logging
|
|
|
|
Structured logging with configurable levels:
|
|
|
|
- **Request IDs**: Track requests across components
|
|
- **Structured format**: JSON output for production
|
|
- **Context preservation**: Error context and debugging info
|
|
- **Performance metrics**: Request timing and retry information
|
|
|
|
## 🔄 Retry Logic
|
|
|
|
Robust retry mechanism:
|
|
|
|
- **Exponential backoff**: Configurable base delay and multiplier
|
|
- **Jitter**: Prevents thundering herd problems
|
|
- **Max retries**: Configurable retry limits
|
|
- **Circuit breaker**: Fail fast after repeated failures
|
|
|
|
## 📚 Documentation
|
|
|
|
- **API Contracts**: Complete Ghost API documentation in `contracts/`
|
|
- **Type Definitions**: Full type coverage with Pydantic models
|
|
- **Examples**: Working examples for all tools
|
|
- **Development Guide**: Step-by-step setup and usage
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make changes with tests
|
|
4. Run `make test` to verify
|
|
5. Submit a pull request
|
|
|
|
## 📄 License
|
|
|
|
MIT License - see LICENSE file for details
|
|
|
|
## 🆘 Support
|
|
|
|
- **Issues**: GitHub issues for bugs and features
|
|
- **Documentation**: Check `contracts/` for API details
|
|
- **Logs**: Use `make logs` for troubleshooting
|
|
- **Status**: Use `make status` for system health
|
|
|
|
---
|
|
|
|
**Built with FastMCP 2.12.3 and Ghost 5.x** 🚀 |