Ghost MCP Server

import { MCPServer, Resource, Tool, } from "@modelcontextprotocol/sdk/server/index.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 fs from "fs"; import path from "path"; import os from "os"; import { v4 as uuidv4 } from "uuid"; import { validateImageUrl, createSecureAxiosConfig } from "./utils/urlValidator.js"; import { createContextLogger } from "./utils/logger.js"; // Load environment variables (might be redundant if loaded elsewhere, but safe) dotenv.config(); // Initialize logger for MCP server const logger = createContextLogger('mcp-server'); logger.info('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.", // iconUrl: '...', }, }); // --- Define Resources --- logger.info('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", }, // Add other relevant tag fields if needed (e.g., feature_image, visibility) }, required: ["id", "name", "slug"], }, }); mcpServer.addResource(ghostTagResource); logger.info('Added MCP Resource', { resourceName: 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: ["published", "draft", "scheduled"], description: "Publication status", }, visibility: { type: "string", enum: ["public", "members", "paid"], description: "Access level", }, created_at: { type: "string", format: "date-time", description: "Date/time post was created", }, updated_at: { type: "string", format: "date-time", description: "Date/time post was last updated", }, published_at: { type: ["string", "null"], format: "date-time", description: "Date/time post was published or scheduled", }, custom_excerpt: { type: ["string", "null"], description: "Custom excerpt for the post", }, meta_title: { type: ["string", "null"], description: "Custom SEO title" }, meta_description: { type: ["string", "null"], description: "Custom SEO description", }, tags: { type: "array", description: "Tags associated with the post", items: { $ref: "#/definitions/ghost/tag" }, // Reference the ghost/tag resource }, // Add authors or other relevant fields if needed }, required: [ "id", "uuid", "title", "slug", "status", "visibility", "created_at", "updated_at", ], definitions: { // Make the referenced tag resource available within this schema's scope "ghost/tag": ghostTagResource.schema, }, }, }); mcpServer.addResource(ghostPostResource); logger.info('Added MCP Resource', { resourceName: ghostPostResource.name }); // --- Define Tools (Subtasks 8.4 - 8.7) --- // Placeholder comments for where tools will be added // --- End Resource/Tool Definitions --- logger.info('Defining MCP Tools'); // Create Post Tool (Adding this missing tool) const createPostTool = new Tool({ name: "ghost_create_post", description: "Creates a new post in Ghost CMS. Handles tag creation/lookup. Returns the created post data.", inputSchema: { type: "object", properties: { title: { type: "string", description: "The title for the new post." }, html: { type: "string", description: "The HTML content for the new post.", }, status: { type: "string", enum: ["published", "draft", "scheduled"], default: "draft", description: "The status for the post (published, draft, scheduled). Defaults to draft.", }, tags: { type: "array", items: { type: "string" }, description: "Optional: An array of tag names (strings) to associate with the post.", }, published_at: { type: "string", format: "date-time", description: "Optional: The ISO 8601 date/time for publishing or scheduling. 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) => { logger.toolExecution(createPostTool.name, input); try { const createdPost = await createPostService(input); logger.toolSuccess(createPostTool.name, createdPost, { postId: createdPost.id }); return createdPost; } catch (error) { logger.toolError(createPostTool.name, error); throw new Error(`Failed to create Ghost post: ${error.message}`); } }, }); mcpServer.addTool(createPostTool); logger.info('Added MCP Tool', { toolName: 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.", }, // filenameHint: { type: 'string', description: 'Optional: A hint for the original filename, used for default alt text generation.' } }, 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) => { logger.toolExecution(uploadImageTool.name, { imageUrl: 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); // Generate a unique temporary filename const tempDir = os.tmpdir(); const extension = path.extname(imageUrl.split("?")[0]) || ".tmp"; // Basic extension extraction 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); }); logger.fileOperation('download', downloadedPath); // --- 3. Process the image (Optional) --- // Using the service from subtask 4.2 processedPath = await processImage(downloadedPath, tempDir); logger.fileOperation('process', processedPath); // --- 4. Determine Alt Text --- // Using similar logic from subtask 4.4 const defaultAlt = getDefaultAltText(originalFilenameHint); const finalAltText = alt || defaultAlt; logger.debug('Generated alt text', { altText: finalAltText }); // --- 5. Upload processed image to Ghost --- const uploadResult = await uploadGhostImage(processedPath); logger.info('Image uploaded to Ghost', { ghostUrl: uploadResult.url }); // --- 6. Return result --- return { url: uploadResult.url, alt: finalAltText, }; } catch (error) { logger.toolError(uploadImageTool.name, error, { imageUrl }); // Add more specific error handling (download failed, processing failed, upload failed) throw new Error( `Failed to upload image from URL ${imageUrl}: ${error.message}` ); } finally { // --- 7. Cleanup temporary files --- if (downloadedPath) { fs.unlink(downloadedPath, (err) => { if (err) logger.warn('Failed to delete temporary downloaded file', { file: path.basename(downloadedPath), error: err.message }); }); } if (processedPath && processedPath !== downloadedPath) { fs.unlink(processedPath, (err) => { if (err) logger.warn('Failed to delete temporary processed file', { file: path.basename(processedPath), error: err.message }); }); } } }, }); // Helper function for default alt text (similar to imageController) 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}-?/, ""); // Remove UUIDs too return nameWithoutIds.replace(/[-_]/g, " ").trim() || "Uploaded image"; } catch (e) { return "Uploaded image"; } }; mcpServer.addTool(uploadImageTool); logger.info('Added MCP Tool', { toolName: 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: The exact name of the tag to search for.", }, }, }, outputSchema: { type: "array", items: { $ref: "ghost/tag#/schema" }, // Output is an array of ghost/tag resources }, implementation: async (input) => { logger.toolExecution(getTagsTool.name, input); try { const tags = await getGhostTags(input?.name); // Pass name if provided logger.toolSuccess(getTagsTool.name, tags, { tagCount: tags.length }); // TODO: Validate/map output against schema if necessary return tags; } catch (error) { logger.toolError(getTagsTool.name, error); throw new Error(`Failed to get Ghost tags: ${error.message}`); } }, }); mcpServer.addTool(getTagsTool); logger.info('Added MCP Tool', { toolName: getTagsTool.name }); // Create Tag Tool const createTagTool = new Tool({ name: "ghost_create_tag", description: "Creates a new tag in Ghost CMS. Returns the created tag.", inputSchema: { type: "object", properties: { name: { type: "string", description: "The name for the new tag." }, description: { type: "string", description: "Optional: A description for the tag (max 500 chars).", }, slug: { type: "string", description: "Optional: A URL-friendly slug. If omitted, Ghost generates one from the name.", }, // Add other createable fields like color, feature_image etc. if needed }, required: ["name"], }, outputSchema: { $ref: "ghost/tag#/schema", // Output is a single ghost/tag resource }, implementation: async (input) => { logger.toolExecution(createTagTool.name, input); try { // Basic validation happens via inputSchema, more specific validation (like slug format) could be added here if not in service const newTag = await createGhostTag(input); logger.toolSuccess(createTagTool.name, newTag, { tagId: newTag.id }); // TODO: Validate/map output against schema if necessary return newTag; } catch (error) { logger.toolError(createTagTool.name, error); throw new Error(`Failed to create Ghost tag: ${error.message}`); } }, }); mcpServer.addTool(createTagTool); logger.info('Added MCP Tool', { toolName: createTagTool.name }); // --- End Tool Definitions --- // Function to start the MCP server // We might integrate this with the Express server later or run separately const startMCPServer = async (port = 3001) => { try { // Ensure resources/tools are added before starting logger.info('Starting MCP Server', { port }); await mcpServer.listen({ port }); const resources = mcpServer.listResources().map((r) => r.name); const tools = mcpServer.listTools().map((t) => t.name); logger.info('MCP Server started successfully', { port, resourceCount: resources.length, toolCount: tools.length, resources, tools, type: 'server_start' }); } catch (error) { logger.error('Failed to start MCP Server', { port, error: error.message, stack: error.stack, type: 'server_start_error' }); process.exit(1); } }; // Export the server instance and start function if needed elsewhere export { mcpServer, startMCPServer }; // Optional: Automatically start if this file is run directly // This might conflict if we integrate with Express later // if (require.main === module) { // startMCPServer(); // }