Ghost MCP Server

import { MCPServer, Resource, Tool } from '@modelcontextprotocol/sdk/server/index.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js'; import { WebSocketServerTransport } from '@modelcontextprotocol/sdk/server/websocket.js'; import dotenv from 'dotenv'; import { createPostService } from './services/postService.js'; import { uploadImage as uploadGhostImage, getTags as getGhostTags, createTag as createGhostTag, } from './services/ghostService.js'; import { processImage } from './services/imageProcessingService.js'; import axios from 'axios'; import { validateImageUrl, createSecureAxiosConfig } from './utils/urlValidator.js'; import fs from 'fs'; import path from 'path'; import os from 'os'; import { v4 as uuidv4 } from 'uuid'; import express from 'express'; import { WebSocketServer } from 'ws'; // Load environment variables dotenv.config(); console.log('Initializing MCP Server...'); // Define the server instance const mcpServer = new MCPServer({ metadata: { name: 'Ghost CMS Manager', description: 'MCP Server to manage a Ghost CMS instance using the Admin API.', version: '1.0.0', }, }); // --- Error Response Standardization --- class MCPError extends Error { constructor(message, code = 'UNKNOWN_ERROR', details = {}) { super(message); this.code = code; this.details = details; } } const handleToolError = (error, toolName) => { console.error(`Error in tool ${toolName}:`, error); // Standardized error response return { error: { code: error.code || 'TOOL_EXECUTION_ERROR', message: error.message || 'An unexpected error occurred', tool: toolName, details: error.details || {}, timestamp: new Date().toISOString(), }, }; }; // --- Define Resources --- console.log('Defining MCP Resources...'); // Ghost Tag Resource const ghostTagResource = new Resource({ name: 'ghost/tag', description: 'Represents a tag in Ghost CMS.', schema: { type: 'object', properties: { id: { type: 'string', description: 'Unique ID of the tag' }, name: { type: 'string', description: 'The name of the tag' }, slug: { type: 'string', description: 'URL-friendly version of the name' }, description: { type: ['string', 'null'], description: 'Optional description for the tag', }, }, required: ['id', 'name', 'slug'], }, // Resource fetching handler async fetch(uri) { try { // Extract tag ID from URI (e.g., "ghost/tag/123") const tagId = uri.split('/').pop(); const tags = await getGhostTags(); const tag = tags.find((t) => t.id === tagId || t.slug === tagId); if (!tag) { throw new MCPError(`Tag not found: ${tagId}`, 'RESOURCE_NOT_FOUND'); } return tag; } catch (error) { return handleToolError(error, 'ghost_tag_fetch'); } }, }); mcpServer.addResource(ghostTagResource); console.log(`Added Resource: ${ghostTagResource.name}`); // Ghost Post Resource const ghostPostResource = new Resource({ name: 'ghost/post', description: 'Represents a post in Ghost CMS.', schema: { type: 'object', properties: { id: { type: 'string', description: 'Unique ID of the post' }, uuid: { type: 'string', description: 'UUID of the post' }, title: { type: 'string', description: 'The title of the post' }, slug: { type: 'string', description: 'URL-friendly version of the title', }, html: { type: ['string', 'null'], description: 'The post content as HTML', }, plaintext: { type: ['string', 'null'], description: 'The post content as plain text', }, feature_image: { type: ['string', 'null'], description: 'URL of the featured image', }, feature_image_alt: { type: ['string', 'null'], description: 'Alt text for the featured image', }, feature_image_caption: { type: ['string', 'null'], description: 'Caption for the featured image', }, featured: { type: 'boolean', description: 'Whether the post is featured', }, status: { type: 'string', enum: ['draft', 'published', 'scheduled'], description: 'The status of the post', }, visibility: { type: 'string', enum: ['public', 'members', 'paid', 'tiers'], description: 'The visibility level of the post', }, created_at: { type: 'string', format: 'date-time', description: 'Date/time when the post was created', }, updated_at: { type: 'string', format: 'date-time', description: 'Date/time when the post was last updated', }, published_at: { type: ['string', 'null'], format: 'date-time', description: 'Date/time when the post was published', }, custom_excerpt: { type: ['string', 'null'], description: 'Custom excerpt for the post', }, tags: { type: 'array', items: { $ref: 'ghost/tag#/schema' }, description: 'Associated tags', }, meta_title: { type: ['string', 'null'], description: 'Custom meta title for SEO', }, meta_description: { type: ['string', 'null'], description: 'Custom meta description for SEO', }, }, required: ['id', 'uuid', 'title', 'slug', 'status'], }, // Resource fetching handler async fetch(uri) { try { // Extract post ID from URI (e.g., "ghost/post/123") const postId = uri.split('/').pop(); // You'll need to implement a getPost service method // For now, returning an error as this would require adding to ghostService.js throw new MCPError('Post fetching not yet implemented', 'NOT_IMPLEMENTED', { postId }); } catch (error) { return handleToolError(error, 'ghost_post_fetch'); } }, }); mcpServer.addResource(ghostPostResource); console.log(`Added Resource: ${ghostPostResource.name}`); // --- Define Tools (with improved error handling) --- console.log('Defining MCP Tools...'); // Create Post Tool const createPostTool = new Tool({ name: 'ghost_create_post', description: 'Creates a new post in Ghost CMS.', inputSchema: { type: 'object', properties: { title: { type: 'string', description: 'The title of the post.', }, html: { type: 'string', description: 'The HTML content of the post.', }, status: { type: 'string', enum: ['draft', 'published', 'scheduled'], default: 'draft', description: "The status of the post. Use 'scheduled' with a future published_at date.", }, tags: { type: 'array', items: { type: 'string' }, description: "Optional: List of tag names to associate with the post. Tags will be created if they don't exist.", }, published_at: { type: 'string', format: 'date-time', description: "Optional: ISO 8601 date/time to publish the post. Required if status is 'scheduled'.", }, custom_excerpt: { type: 'string', description: 'Optional: A custom short summary for the post.', }, feature_image: { type: 'string', format: 'url', description: 'Optional: URL of the image (e.g., from ghost_upload_image tool) to use as the featured image.', }, feature_image_alt: { type: 'string', description: 'Optional: Alt text for the featured image.', }, feature_image_caption: { type: 'string', description: 'Optional: Caption for the featured image.', }, meta_title: { type: 'string', description: 'Optional: Custom title for SEO (max 300 chars). Defaults to post title if omitted.', }, meta_description: { type: 'string', description: 'Optional: Custom description for SEO (max 500 chars). Defaults to excerpt or generated summary if omitted.', }, }, required: ['title', 'html'], }, outputSchema: { $ref: 'ghost/post#/schema', }, implementation: async (input) => { console.log(`Executing tool: ${createPostTool.name} with input keys:`, Object.keys(input)); try { const createdPost = await createPostService(input); console.log(`Tool ${createPostTool.name} executed successfully. Post ID: ${createdPost.id}`); return createdPost; } catch (error) { return handleToolError(error, createPostTool.name); } }, }); mcpServer.addTool(createPostTool); console.log(`Added Tool: ${createPostTool.name}`); // Upload Image Tool const uploadImageTool = new Tool({ name: 'ghost_upload_image', description: 'Downloads an image from a URL, processes it, uploads it to Ghost CMS, and returns the final Ghost image URL and alt text.', inputSchema: { type: 'object', properties: { imageUrl: { type: 'string', format: 'url', description: 'The publicly accessible URL of the image to upload.', }, alt: { type: 'string', description: 'Optional: Alt text for the image. If omitted, a default will be generated from the filename.', }, }, required: ['imageUrl'], }, outputSchema: { type: 'object', properties: { url: { type: 'string', format: 'url', description: 'The final URL of the image hosted on Ghost.', }, alt: { type: 'string', description: 'The alt text determined for the image.', }, }, required: ['url', 'alt'], }, implementation: async (input) => { console.log(`Executing tool: ${uploadImageTool.name} for URL:`, input.imageUrl); const { imageUrl, alt } = input; let downloadedPath = null; let processedPath = null; try { // --- 1. Validate URL for SSRF protection --- const urlValidation = validateImageUrl(imageUrl); if (!urlValidation.isValid) { throw new Error(`Invalid image URL: ${urlValidation.error}`); } // --- 2. Download the image with security controls --- const axiosConfig = createSecureAxiosConfig(urlValidation.sanitizedUrl); const response = await axios(axiosConfig); const tempDir = os.tmpdir(); const extension = path.extname(imageUrl.split('?')[0]) || '.tmp'; const originalFilenameHint = path.basename(imageUrl.split('?')[0]) || `image-${uuidv4()}${extension}`; downloadedPath = path.join(tempDir, `mcp-download-${uuidv4()}${extension}`); const writer = fs.createWriteStream(downloadedPath); response.data.pipe(writer); await new Promise((resolve, reject) => { writer.on('finish', resolve); writer.on('error', reject); }); console.log(`Downloaded image to temporary path: ${downloadedPath}`); // --- 2. Process the image --- processedPath = await processImage(downloadedPath, tempDir); console.log(`Processed image path: ${processedPath}`); // --- 3. Determine Alt Text --- const defaultAlt = getDefaultAltText(originalFilenameHint); const finalAltText = alt || defaultAlt; console.log(`Using alt text: "${finalAltText}"`); // --- 4. Upload processed image to Ghost --- const uploadResult = await uploadGhostImage(processedPath); console.log(`Uploaded processed image to Ghost: ${uploadResult.url}`); // --- 5. Return result --- return { url: uploadResult.url, alt: finalAltText, }; } catch (error) { return handleToolError( new MCPError(`Failed to upload image from URL ${imageUrl}`, 'IMAGE_UPLOAD_ERROR', { imageUrl, originalError: error.message, }), uploadImageTool.name ); } finally { // --- 6. Cleanup temporary files --- if (downloadedPath) { fs.unlink(downloadedPath, (err) => { if (err) console.error('Error deleting temporary downloaded file:', downloadedPath, err); }); } if (processedPath && processedPath !== downloadedPath) { fs.unlink(processedPath, (err) => { if (err) console.error('Error deleting temporary processed file:', processedPath, err); }); } } }, }); // Helper function for default alt text const getDefaultAltText = (filePath) => { try { const originalFilename = path.basename(filePath).split('.').slice(0, -1).join('.'); const nameWithoutIds = originalFilename .replace(/^(processed-|mcp-download-|mcp-upload-)\d+-\d+-?/, '') .replace(/^[a-f0-9]{8}-(?:[a-f0-9]{4}-){3}[a-f0-9]{12}-?/, ''); return nameWithoutIds.replace(/[-_]/g, ' ').trim() || 'Uploaded image'; } catch (e) { return 'Uploaded image'; } }; mcpServer.addTool(uploadImageTool); console.log(`Added Tool: ${uploadImageTool.name}`); // Get Tags Tool const getTagsTool = new Tool({ name: 'ghost_get_tags', description: 'Retrieves a list of tags from Ghost CMS. Can optionally filter by tag name.', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Optional: Filter tags by exact name. If omitted, all tags are returned.', }, }, }, outputSchema: { type: 'array', items: { $ref: 'ghost/tag#/schema' }, }, implementation: async (input) => { console.log(`Executing tool: ${getTagsTool.name}`); try { const tags = await getGhostTags(); if (input.name) { const filteredTags = tags.filter( (tag) => tag.name.toLowerCase() === input.name.toLowerCase() ); console.log( `Filtered tags by name "${input.name}". Found ${filteredTags.length} match(es).` ); return filteredTags; } console.log(`Retrieved ${tags.length} tags from Ghost.`); return tags; } catch (error) { return handleToolError(error, getTagsTool.name); } }, }); mcpServer.addTool(getTagsTool); console.log(`Added Tool: ${getTagsTool.name}`); // Create Tag Tool const createTagTool = new Tool({ name: 'ghost_create_tag', description: 'Creates a new tag in Ghost CMS.', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'The name of the tag.', }, description: { type: 'string', description: 'Optional: A description for the tag.', }, slug: { type: 'string', pattern: '^[a-z0-9\\-]+$', description: 'Optional: A URL-friendly slug for the tag. Will be auto-generated from the name if omitted.', }, }, required: ['name'], }, outputSchema: { $ref: 'ghost/tag#/schema', }, implementation: async (input) => { console.log(`Executing tool: ${createTagTool.name} with name:`, input.name); try { const createdTag = await createGhostTag(input); console.log(`Tool ${createTagTool.name} executed successfully. Tag ID: ${createdTag.id}`); return createdTag; } catch (error) { return handleToolError(error, createTagTool.name); } }, }); mcpServer.addTool(createTagTool); console.log(`Added Tool: ${createTagTool.name}`); // --- Transport Configuration --- /** * Start MCP Server with specified transport * @param {string} transport - Transport type: 'stdio', 'http', 'websocket' * @param {object} options - Transport-specific options */ const startMCPServer = async (transport = 'http', options = {}) => { try { console.log(`Starting MCP Server with ${transport} transport...`); switch (transport) { case 'stdio': // Standard I/O transport - best for CLI tools const stdioTransport = new StdioServerTransport(); await mcpServer.connect(stdioTransport); console.log('MCP Server running on stdio transport'); break; case 'http': case 'sse': // HTTP with Server-Sent Events - good for web clients const port = options.port || 3001; const app = express(); // CORS configuration for web clients app.use((req, res, next) => { res.header('Access-Control-Allow-Origin', options.cors || '*'); res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS'); res.header('Access-Control-Allow-Headers', 'Content-Type'); next(); }); // SSE endpoint const sseTransport = new SSEServerTransport(); app.get('/mcp/sse', sseTransport.handler()); // Health check app.get('/mcp/health', (req, res) => { res.json({ status: 'ok', transport: 'sse', resources: mcpServer.listResources().map((r) => r.name), tools: mcpServer.listTools().map((t) => t.name), }); }); await mcpServer.connect(sseTransport); const server = app.listen(port, () => { console.log(`MCP Server (SSE) listening on port ${port}`); console.log(`SSE endpoint: http://localhost:${port}/mcp/sse`); console.log(`Health check: http://localhost:${port}/mcp/health`); }); // Store server instance for cleanup mcpServer._httpServer = server; break; case 'websocket': // WebSocket transport - best for real-time bidirectional communication const wsPort = options.port || 3001; const wss = new WebSocketServer({ port: wsPort }); wss.on('connection', async (ws) => { console.log('New WebSocket connection'); const wsTransport = new WebSocketServerTransport(ws); await mcpServer.connect(wsTransport); }); console.log(`MCP Server (WebSocket) listening on port ${wsPort}`); console.log(`WebSocket URL: ws://localhost:${wsPort}`); // Store WebSocket server instance for cleanup mcpServer._wss = wss; break; default: throw new Error(`Unknown transport type: ${transport}`); } console.log( 'Available Resources:', mcpServer.listResources().map((r) => r.name) ); console.log( 'Available Tools:', mcpServer.listTools().map((t) => t.name) ); } catch (error) { console.error('Failed to start MCP Server:', error); process.exit(1); } }; // Graceful shutdown handler const shutdown = async () => { console.log('\nShutting down MCP Server...'); if (mcpServer._httpServer) { mcpServer._httpServer.close(); } if (mcpServer._wss) { mcpServer._wss.close(); } await mcpServer.close(); process.exit(0); }; process.on('SIGINT', shutdown); process.on('SIGTERM', shutdown); // Export the server instance and start function export { mcpServer, startMCPServer, MCPError }; // If running directly, start with transport from environment or default to HTTP if (import.meta.url === `file://${process.argv[1]}`) { const transport = process.env.MCP_TRANSPORT || 'http'; const port = parseInt(process.env.MCP_PORT || '3001'); const cors = process.env.MCP_CORS || '*'; startMCPServer(transport, { port, cors }); }