@jgardner04/ghost-mcp-server 1.13.4 → 1.14.0

package/src/services/imageProcessingService.js

@@ -1,96 +1,140 @@
 import sharp from 'sharp';
 import path from 'path';
-import fs from 'fs';
-import Joi from 'joi';
+import fsp from 'fs/promises';
+import { z } from 'zod';
 import { createContextLogger } from '../utils/logger.js';
 
-// Define processing parameters (e.g., max width)
 const MAX_WIDTH = 1200;
-const OUTPUT_QUALITY = 80; // JPEG quality
+const JPEG_QUALITY = 80;
 
-/**
- * Processes an image: resizes if too large, ensures JPEG format (configurable).
- * @param {string} inputPath - Path to the original uploaded image.
- * @param {string} outputDir - Directory to save the processed image.
- * @returns {Promise<string>} Path to the processed image.
- */
-// Validation schema for processing parameters
-const processImageSchema = Joi.object({
-  inputPath: Joi.string().required(),
-  outputDir: Joi.string().required(),
+// Formats we re-encode via sharp when the image is oversized.
+// Everything else is passed through untouched to preserve fidelity
+// (SVG vectors, GIF animation, ICO, exotic formats).
+const RESIZABLE_FORMATS = new Set(['jpeg', 'png', 'webp']);
+
+const EXT_BY_FORMAT = {
+  jpeg: '.jpg',
+  png: '.png',
+  webp: '.webp',
+  gif: '.gif',
+  svg: '.svg',
+  // ICO has no sharp `format` name; detected by extension.
+};
+
+const processImageParamsSchema = z.object({
+  inputPath: z.string().min(1),
+  outputDir: z.string().min(1),
 });
 
-const processImage = async (inputPath, outputDir) => {
+const processImageOptsSchema = z
+  .object({
+    purpose: z.enum(['image', 'profile_image', 'icon']).optional(),
+  })
+  .optional();
+
+/**
+ * Process an image for upload to Ghost.
+ *
+ * Preserves the original format. Resizes (preserving format) only for
+ * raster formats sharp can safely re-encode — JPEG, PNG, WEBP — when
+ * wider than MAX_WIDTH. SVG, GIF, ICO, and unrecognized formats are
+ * copied byte-for-byte so vectors, animation frames, and icon metadata
+ * survive the round trip.
+ *
+ * @param {string} inputPath - Absolute path to the source image.
+ * @param {string} outputDir - Directory to write the processed file into.
+ * @param {{ purpose?: 'image'|'profile_image'|'icon' }} [opts]
+ * @returns {Promise<string>} Absolute path to the processed (or copied) file.
+ */
+export async function processImage(inputPath, outputDir, opts = {}) {
   const logger = createContextLogger('image-processing');
 
-  // Validate inputs to prevent path injection
-  const { error } = processImageSchema.validate({ inputPath, outputDir });
-  if (error) {
-    logger.error('Invalid processing parameters', {
-      error: error.details[0].message,
-      inputPath: inputPath ? path.basename(inputPath) : 'undefined',
-      outputDir: outputDir ? path.basename(outputDir) : 'undefined',
-    });
+  const params = processImageParamsSchema.safeParse({ inputPath, outputDir });
+  if (!params.success) {
     throw new Error('Invalid processing parameters');
   }
+  processImageOptsSchema.parse(opts);
 
-  // Ensure paths are safe
-  const resolvedInputPath = path.resolve(inputPath);
+  const resolvedInput = path.resolve(inputPath);
   const resolvedOutputDir = path.resolve(outputDir);
 
-  // Verify input file exists
-  if (!fs.existsSync(resolvedInputPath)) {
+  try {
+    await fsp.access(resolvedInput);
+  } catch {
     throw new Error('Input file does not exist');
   }
 
-  const filename = path.basename(resolvedInputPath);
-  const nameWithoutExt = filename.split('.').slice(0, -1).join('.');
-  // Use timestamp for unique output filename
+  const inputExt = path.extname(resolvedInput).toLowerCase();
+  const baseName = path.basename(resolvedInput, path.extname(resolvedInput));
   const timestamp = Date.now();
-  const outputFilename = `processed-${timestamp}-${nameWithoutExt}.jpg`;
-  const outputPath = path.join(resolvedOutputDir, outputFilename);
 
   try {
-    logger.info('Processing image', {
-      inputFile: path.basename(inputPath),
-      outputDir: path.basename(outputDir),
-    });
-    const image = sharp(inputPath);
+    // Non-raster passthrough: SVG and ICO are never handed to sharp.
+    // (sharp can read SVG but would rasterize it, destroying the vector.)
+    if (inputExt === '.svg' || inputExt === '.ico') {
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, inputExt);
+    }
+
+    const image = sharp(resolvedInput);
     const metadata = await image.metadata();
+    const format = metadata.format; // 'jpeg' | 'png' | 'webp' | 'gif' | 'svg' | ...
 
-    let processedImage = image;
+    // GIF: never re-encode — sharp would drop animation frames.
+    // SVG (if it slipped through by extension mismatch): also passthrough.
+    if (format === 'gif' || format === 'svg') {
+      const ext = EXT_BY_FORMAT[format] || inputExt || '';
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, ext);
+    }
 
-    // Resize if wider than MAX_WIDTH
-    if (metadata.width && metadata.width > MAX_WIDTH) {
-      logger.info('Resizing image', {
-        originalWidth: metadata.width,
-        targetWidth: MAX_WIDTH,
+    // Unknown / unsupported format: safest is passthrough.
+    if (!RESIZABLE_FORMATS.has(format)) {
+      logger.info('Unknown format, passing through', {
+        format,
         inputFile: path.basename(inputPath),
       });
-      processedImage = processedImage.resize({ width: MAX_WIDTH });
+      return await passthrough(resolvedInput, resolvedOutputDir, baseName, timestamp, inputExt);
     }
 
-    // Convert to JPEG with specified quality
-    // You could add options for PNG/WebP etc. if needed
-    await processedImage.jpeg({ quality: OUTPUT_QUALITY }).toFile(outputPath);
+    const ext = EXT_BY_FORMAT[format];
+    const outputPath = path.join(resolvedOutputDir, `processed-${timestamp}-${baseName}${ext}`);
 
-    logger.info('Image processing completed', {
+    // Passthrough when no resize is needed — avoids generation loss.
+    if (!metadata.width || metadata.width <= MAX_WIDTH) {
+      await fsp.copyFile(resolvedInput, outputPath);
+      logger.info('Image within size limits, passthrough copy', {
+        format,
+        width: metadata.width,
+        inputFile: path.basename(inputPath),
+      });
+      return outputPath;
+    }
+
+    logger.info('Resizing image', {
+      format,
+      originalWidth: metadata.width,
+      targetWidth: MAX_WIDTH,
       inputFile: path.basename(inputPath),
-      outputFile: path.basename(outputPath),
-      originalSize: metadata.size,
-      quality: OUTPUT_QUALITY,
     });
+
+    // sharp picks the encoder from outputPath extension (EXT_BY_FORMAT),
+    // so only JPEG needs the explicit call here to set quality. PNG/WEBP
+    // would be redundant.
+    let pipeline = image.resize({ width: MAX_WIDTH });
+    if (format === 'jpeg') pipeline = pipeline.jpeg({ quality: JPEG_QUALITY });
+
+    await pipeline.toFile(outputPath);
     return outputPath;
   } catch (error) {
     logger.error('Image processing failed', {
       inputFile: path.basename(inputPath),
       error: error.message,
-      stack: error.stack,
     });
-    // If processing fails, maybe fall back to using the original?
-    // Or throw the error to fail the upload.
     throw new Error('Image processing failed: ' + error.message, { cause: error });
   }
-};
+}
 
-export { processImage };
+async function passthrough(inputPath, outputDir, baseName, timestamp, ext) {
+  const outputPath = path.join(outputDir, `processed-${timestamp}-${baseName}${ext}`);
+  await fsp.copyFile(inputPath, outputPath);
+  return outputPath;
+}

package/src/services/images.js

@@ -0,0 +1,54 @@
+import { GhostAPIError, ValidationError } from '../errors/index.js';
+import { handleApiRequest } from './ghostApiClient.js';
+import { validators } from './validators.js';
+
+const ALLOWED_PURPOSES = new Set(['image', 'profile_image', 'icon']);
+const REF_MAX_LENGTH = 200;
+
+/**
+ * Uploads an image to Ghost CMS from a local file path.
+ *
+ * @param {string} imagePath - Absolute path to the image file.
+ * @param {object} [opts]
+ * @param {'image'|'profile_image'|'icon'} [opts.purpose] - Intended use.
+ *   Ghost applies format/size validation per purpose (icon/profile_image
+ *   must be square; icon also accepts ICO).
+ * @param {string} [opts.ref] - Caller-supplied identifier (e.g. original
+ *   filename). Ghost echoes it back in the response. Max 200 chars.
+ * @returns {Promise<Object>} The uploaded image object with URL (and ref,
+ *   if provided and the SDK forwards it).
+ * @throws {ValidationError} If inputs are invalid or upload fails.
+ * @throws {NotFoundError} If the file does not exist.
+ * @throws {GhostAPIError} If the API request fails.
+ */
+export async function uploadImage(imagePath, opts = {}) {
+  await validators.validateImagePath(imagePath);
+
+  const { purpose, ref } = opts;
+  if (purpose !== undefined && !ALLOWED_PURPOSES.has(purpose)) {
+    throw new ValidationError(
+      `Invalid purpose "${purpose}". Must be one of: ${[...ALLOWED_PURPOSES].join(', ')}`
+    );
+  }
+  if (ref !== undefined) {
+    if (typeof ref !== 'string') {
+      throw new ValidationError('ref must be a string');
+    }
+    if (ref.length > REF_MAX_LENGTH) {
+      throw new ValidationError(`ref cannot exceed ${REF_MAX_LENGTH} characters`);
+    }
+  }
+
+  const imageData = { file: imagePath };
+  if (purpose !== undefined) imageData.purpose = purpose;
+  if (ref !== undefined) imageData.ref = ref;
+
+  try {
+    return await handleApiRequest('images', 'upload', imageData);
+  } catch (error) {
+    if (error instanceof GhostAPIError) {
+      throw new ValidationError(`Image upload failed: ${error.originalError}`);
+    }
+    throw error;
+  }
+}

package/src/services/members.js

@@ -0,0 +1,127 @@
+import { GhostAPIError, NotFoundError } from '../errors/index.js';
+import { sanitizeNqlValue } from '../utils/nqlSanitizer.js';
+import { handleApiRequest } from './ghostApiClient.js';
+import { createResourceService } from './createResourceService.js';
+
+const service = createResourceService({
+  resource: 'members',
+  label: 'Member',
+  listDefaults: { limit: 15 },
+  // Input validation is performed at the MCP tool layer using Zod schemas
+});
+
+/**
+ * Creates a new member (subscriber) in Ghost CMS
+ * @param {Object} memberData - The member data
+ * @param {string} memberData.email - Member email (required)
+ * @param {string} [memberData.name] - Member name
+ * @param {string} [memberData.note] - Notes about the member (HTML will be sanitized)
+ * @param {string[]} [memberData.labels] - Array of label names
+ * @param {Object[]} [memberData.newsletters] - Array of newsletter objects with id
+ * @param {boolean} [memberData.subscribed] - Email subscription status
+ * @param {Object} [options] - Additional options for the API request
+ * @returns {Promise<Object>} The created member object
+ * @throws {ValidationError} If validation fails
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const createMember = service.create;
+
+/**
+ * Updates an existing member in Ghost CMS
+ * @param {string} memberId - The member ID to update
+ * @param {Object} updateData - The member update data
+ * @param {string} [updateData.email] - Member email
+ * @param {string} [updateData.name] - Member name
+ * @param {string} [updateData.note] - Notes about the member (HTML will be sanitized)
+ * @param {string[]} [updateData.labels] - Array of label names
+ * @param {Object[]} [updateData.newsletters] - Array of newsletter objects with id
+ * @param {boolean} [updateData.subscribed] - Email subscription status
+ * @param {Object} [options] - Additional options for the API request
+ * @returns {Promise<Object>} The updated member object
+ * @throws {ValidationError} If validation fails
+ * @throws {NotFoundError} If the member is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const updateMember = service.update;
+
+/**
+ * Deletes a member from Ghost CMS
+ * @param {string} memberId - The member ID to delete
+ * @returns {Promise<Object>} Deletion confirmation object
+ * @throws {ValidationError} If member ID is not provided
+ * @throws {NotFoundError} If the member is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const deleteMember = service.remove;
+
+/**
+ * List members from Ghost CMS with optional filtering and pagination
+ * @param {Object} [options] - Query options
+ * @param {number} [options.limit] - Number of members to return (1-100)
+ * @param {number} [options.page] - Page number (1+)
+ * @param {string} [options.filter] - NQL filter string (e.g., 'status:paid')
+ * @param {string} [options.order] - Order string (e.g., 'created_at desc')
+ * @param {string} [options.include] - Include string (e.g., 'labels,newsletters')
+ * @returns {Promise<Array>} Array of member objects
+ * @throws {ValidationError} If validation fails
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getMembers = service.getList;
+
+/**
+ * Get a single member from Ghost CMS by ID or email
+ * @param {Object} params - Lookup parameters (id OR email required)
+ * @param {string} [params.id] - Member ID
+ * @param {string} [params.email] - Member email
+ * @returns {Promise<Object>} The member object
+ * @throws {ValidationError} If validation fails
+ * @throws {NotFoundError} If the member is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function getMember(params) {
+  const { id, email } = params;
+
+  try {
+    if (id) {
+      return await handleApiRequest('members', 'read', { id }, { id });
+    } else {
+      const sanitizedEmail = sanitizeNqlValue(email);
+      const members = await handleApiRequest(
+        'members',
+        'browse',
+        {},
+        { filter: `email:'${sanitizedEmail}'`, limit: 1 }
+      );
+
+      if (!members || members.length === 0) {
+        throw new NotFoundError('Member', email);
+      }
+
+      return members[0];
+    }
+  } catch (error) {
+    if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
+      throw new NotFoundError('Member', id || email);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Search members by name or email
+ * @param {string} query - Search query (searches name and email fields)
+ * @param {Object} [options] - Additional options
+ * @param {number} [options.limit] - Maximum number of results (default: 15)
+ * @returns {Promise<Array>} Array of matching member objects
+ * @throws {ValidationError} If validation fails
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function searchMembers(query, options = {}) {
+  const sanitizedQuery = sanitizeNqlValue(query.trim());
+  const limit = options.limit || 15;
+
+  const filter = `name:~'${sanitizedQuery}',email:~'${sanitizedQuery}'`;
+
+  const members = await handleApiRequest('members', 'browse', {}, { filter, limit });
+  return members || [];
+}

package/src/services/newsletters.js

@@ -0,0 +1,63 @@
+import { createResourceService } from './createResourceService.js';
+import { validators } from './validators.js';
+
+const service = createResourceService({
+  resource: 'newsletters',
+  label: 'Newsletter',
+  listDefaults: { limit: 'all' },
+  validateCreate: (data) => validators.validateNewsletterData(data),
+  catch422OnUpdate: true,
+});
+
+/**
+ * Lists all newsletters with optional filtering and pagination.
+ * @param {Object} [options={}] - Query options
+ * @param {string|number} [options.limit='all'] - Number of newsletters to return (default: 'all')
+ * @returns {Promise<Array>} Array of newsletter objects (empty array if none found)
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getNewsletters = service.getList;
+
+/**
+ * Retrieves a single newsletter by ID.
+ * @param {string} newsletterId - The newsletter ID to retrieve
+ * @returns {Promise<Object>} The newsletter object
+ * @throws {ValidationError} If the newsletter ID is missing
+ * @throws {NotFoundError} If the newsletter is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getNewsletter = service.getOne;
+
+/**
+ * Creates a new newsletter in Ghost CMS.
+ * @param {Object} newsletterData - The newsletter data
+ * @param {string} newsletterData.name - Newsletter name (required)
+ * @param {string} [newsletterData.description] - Newsletter description
+ * @param {string} [newsletterData.sender_name] - Sender name
+ * @param {string} [newsletterData.sender_email] - Sender email
+ * @returns {Promise<Object>} The created newsletter object
+ * @throws {ValidationError} If validation fails or Ghost returns a 422
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const createNewsletter = service.create;
+
+/**
+ * Updates an existing newsletter with optimistic concurrency control.
+ * @param {string} newsletterId - The newsletter ID to update
+ * @param {Object} updateData - Fields to update on the newsletter
+ * @returns {Promise<Object>} The updated newsletter object
+ * @throws {ValidationError} If the newsletter ID is missing or Ghost returns a 422
+ * @throws {NotFoundError} If the newsletter is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const updateNewsletter = service.update;
+
+/**
+ * Deletes a newsletter by ID.
+ * @param {string} newsletterId - The newsletter ID to delete
+ * @returns {Promise<Object>} Deletion confirmation
+ * @throws {ValidationError} If the newsletter ID is missing
+ * @throws {NotFoundError} If the newsletter is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const deleteNewsletter = service.remove;

package/src/services/pageService.js

@@ -41,8 +41,8 @@ const pageInputSchema = Joi.object({
   published_at: Joi.string().isoDate().optional(),
   // NO tags field - pages don't support tags
   feature_image: Joi.string().uri().optional(),
-  feature_image_alt: Joi.string().max(255).optional(),
-  feature_image_caption: Joi.string().max(500).optional(),
+  feature_image_alt: Joi.string().max(191).optional(),
+  feature_image_caption: Joi.string().max(5000).optional(),
   meta_title: Joi.string().max(70).optional(),
   meta_description: Joi.string().max(160).optional(),
 });

package/src/services/pages.js

@@ -0,0 +1,116 @@
+import { ValidationError } from '../errors/index.js';
+import { sanitizeNqlValue } from '../utils/nqlSanitizer.js';
+import { handleApiRequest, readResource } from './ghostApiClient.js';
+import { createResourceService } from './createResourceService.js';
+import { validators } from './validators.js';
+
+const service = createResourceService({
+  resource: 'pages',
+  label: 'Page',
+  createDefaults: { status: 'draft' },
+  createOptions: { source: 'html' },
+  listDefaults: { limit: 15, include: 'authors' },
+  validateCreate: (data) => validators.validatePageData(data),
+  validateUpdate: async (id, updateData) => {
+    if (updateData.status || updateData.published_at) {
+      let validationData = updateData;
+      if (!updateData.status && updateData.published_at) {
+        const existing = await readResource('pages', id, 'Page');
+        validationData = { ...updateData, status: existing.status };
+      }
+      validators.validateScheduledStatus(validationData, 'Page');
+    }
+  },
+});
+
+/**
+ * Creates a new page in Ghost CMS.
+ * @param {Object} pageData - The page data
+ * @param {string} pageData.title - Page title (required)
+ * @param {string} [pageData.html] - HTML content (required if mobiledoc not provided)
+ * @param {string} [pageData.mobiledoc] - Mobiledoc content (required if html not provided)
+ * @param {string} [pageData.status='draft'] - Page status ('draft', 'published', 'scheduled')
+ * @param {string} [pageData.published_at] - ISO 8601 date for scheduled pages
+ * @param {Object} [options={ source: 'html' }] - API request options
+ * @returns {Promise<Object>} The created page object
+ * @throws {ValidationError} If validation fails or Ghost returns a 422
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const createPage = service.create;
+
+/**
+ * Updates an existing page with optimistic concurrency control.
+ * Validates scheduling fields when status or published_at is being changed.
+ * @param {string} pageId - The page ID to update
+ * @param {Object} updateData - Fields to update on the page
+ * @param {Object} [options={}] - API request options
+ * @returns {Promise<Object>} The updated page object
+ * @throws {ValidationError} If the page ID is missing or scheduling validation fails
+ * @throws {NotFoundError} If the page is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const updatePage = service.update;
+
+/**
+ * Deletes a page by ID.
+ * @param {string} pageId - The page ID to delete
+ * @returns {Promise<Object>} Deletion confirmation
+ * @throws {ValidationError} If the page ID is missing
+ * @throws {NotFoundError} If the page is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const deletePage = service.remove;
+
+/**
+ * Retrieves a single page by ID.
+ * @param {string} pageId - The page ID to retrieve
+ * @param {Object} [options={}] - API request options (e.g., includes)
+ * @returns {Promise<Object>} The page object
+ * @throws {ValidationError} If the page ID is missing
+ * @throws {NotFoundError} If the page is not found
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getPage = service.getOne;
+
+/**
+ * Lists pages with optional filtering and pagination.
+ * @param {Object} [options={}] - Query options
+ * @param {number} [options.limit=15] - Number of pages to return
+ * @param {string} [options.include='authors'] - Related resources to include
+ * @param {string} [options.filter] - NQL filter string
+ * @param {string} [options.order] - Order string
+ * @returns {Promise<Array>} Array of page objects
+ * @throws {GhostAPIError} If the API request fails
+ */
+export const getPages = service.getList;
+
+/**
+ * Searches pages by title using Ghost NQL fuzzy matching.
+ * @param {string} query - Search query string (required, non-empty)
+ * @param {Object} [options={}] - Additional search options
+ * @param {string} [options.status] - Filter by status ('draft', 'published', 'scheduled', or 'all')
+ * @param {number} [options.limit=15] - Maximum number of results
+ * @returns {Promise<Array>} Array of matching page objects
+ * @throws {ValidationError} If the query is empty
+ * @throws {GhostAPIError} If the API request fails
+ */
+export async function searchPages(query, options = {}) {
+  if (!query || query.trim().length === 0) {
+    throw new ValidationError('Search query is required');
+  }
+
+  const sanitizedQuery = sanitizeNqlValue(query);
+
+  const filterParts = [`title:~'${sanitizedQuery}'`];
+  if (options.status && options.status !== 'all') {
+    filterParts.push(`status:${options.status}`);
+  }
+
+  const searchOptions = {
+    limit: options.limit || 15,
+    include: 'authors',
+    filter: filterParts.join('+'),
+  };
+
+  return handleApiRequest('pages', 'browse', {}, searchOptions);
+}