@jgardner04/ghost-mcp-server 1.13.5 → 1.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgardner04/ghost-mcp-server",
-  "version": "1.13.5",
+  "version": "1.14.1",
   "description": "A Model Context Protocol (MCP) server for interacting with Ghost CMS via the Admin API",
   "author": "Jonathan Gardner",
   "type": "module",

package/src/__tests__/mcp_server.test.js

@@ -1712,3 +1712,86 @@ describe('tool schema JSON Schema output', () => {
     }
   });
 });
+
+// Regression tests for PR B — download size cap enforcement in ghost_upload_image.
+// axios does NOT enforce maxContentLength for responseType: 'stream', so the tool
+// must cap bytes itself via Content-Length pre-check and mid-stream byte tracking.
+describe('mcp_server - ghost_upload_image download size cap', () => {
+  const CAP = 50 * 1024 * 1024;
+  let handler;
+
+  beforeAll(async () => {
+    if (mockTools.size === 0) await import('../mcp_server.js');
+    handler = mockTools.get('ghost_upload_image').handler;
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockValidateImageUrl.mockReturnValue({
+      isValid: true,
+      sanitizedUrl: 'https://imgur.com/x.jpg',
+    });
+    mockCreateSecureAxiosConfig.mockReturnValue({ url: 'https://imgur.com/x.jpg' });
+  });
+
+  it('rejects up front when Content-Length header exceeds the cap', async () => {
+    const destroy = vi.fn();
+    mockAxios.mockResolvedValue({
+      headers: { 'content-length': String(CAP + 1) },
+      data: { destroy, on: vi.fn(), pipe: vi.fn() },
+    });
+
+    const result = await handler({ imageUrl: 'https://imgur.com/huge.jpg' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/exceeds .* byte limit/);
+    expect(destroy).toHaveBeenCalled();
+  });
+
+  it('aborts mid-stream when bytes exceed the cap', async () => {
+    // Build a controllable fake stream that the tool's `.on('data', ...)` hook
+    // can drive past the cap without allocating 50MB.
+    const listeners = {};
+    const destroyCalls = [];
+    const dataStream = {
+      on: (event, cb) => {
+        (listeners[event] ||= []).push(cb);
+        return dataStream;
+      },
+      pipe: vi.fn(),
+      destroy: (err) => {
+        destroyCalls.push(err);
+        (listeners.error || []).forEach((cb) => cb(err));
+      },
+    };
+    const writer = {
+      on: (event, cb) => {
+        // Resolve the finish/error promise via the writer path.
+        if (event === 'error' && destroyCalls.length > 0) {
+          cb(destroyCalls[0]);
+        }
+        return writer;
+      },
+    };
+    mockCreateWriteStream.mockReturnValue(writer);
+    mockAxios.mockResolvedValue({
+      headers: {},
+      data: dataStream,
+    });
+
+    // Kick off the handler, then simulate a single >cap chunk landing.
+    const promise = handler({ imageUrl: 'https://imgur.com/x.jpg' });
+    // Let all the handler's awaits resolve (loadServices, axios, Promise
+    // construction with listener attachments) before emitting the chunk.
+    await new Promise((r) => setTimeout(r, 20));
+    const dataCbs = listeners.data || [];
+    expect(dataCbs.length).toBeGreaterThan(0);
+    dataCbs.forEach((cb) => cb({ length: CAP + 1 }));
+
+    const result = await promise;
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/exceeds .* byte limit|Error uploading image/);
+    expect(destroyCalls.length).toBeGreaterThan(0);
+    expect(destroyCalls[0]).toBeInstanceOf(Error);
+  });
+});

package/src/controllers/__tests__/imageController.test.js

@@ -25,7 +25,7 @@ vi.mock('crypto', () => ({
 const mockUploadGhostImage = vi.fn();
 const mockProcessImage = vi.fn();
 
-vi.mock('../../services/ghostService.js', () => ({
+vi.mock('../../services/images.js', () => ({
   uploadImage: (...args) => mockUploadGhostImage(...args),
 }));
 
@@ -167,7 +167,7 @@ describe('imageController', () => {
             path: '/tmp/mcp-upload-123-abc.jpg',
           },
           body: {
-            alt: 'a'.repeat(501), // exceeds 500 char limit
+            alt: 'a'.repeat(192), // exceeds 191 char limit (Ghost varchar(191))
           },
         });
         const res = createMockResponse();

package/src/controllers/imageController.js

@@ -5,8 +5,9 @@ import os from 'os'; // Import the os module
 import Joi from 'joi';
 import crypto from 'crypto';
 import { createContextLogger } from '../utils/logger.js';
-import { uploadImage as uploadGhostImage } from '../services/ghostService.js'; // Assuming uploadImage is in ghostService
-import { processImage } from '../services/imageProcessingService.js'; // Import the processing service
+import { uploadImage as uploadGhostImage } from '../services/images.js';
+import { processImage } from '../services/imageProcessingService.js';
+import { featureImageAltSchema } from '../schemas/common.js';
 
 // --- Use OS temporary directory for uploads ---
 const uploadDir = os.tmpdir(); // Use the OS default temp directory
@@ -194,15 +195,15 @@ const handleImageUpload = async (req, res, next) => {
     processedPath = await processImage(originalPath, uploadDir);
 
     // --- Handle Alt Text ---
-    // Validate and sanitize alt text from the request body
-    const altSchema = Joi.string().max(500).allow('').optional();
-    const { error, value: sanitizedAlt } = altSchema.validate(req.body.alt);
-
-    if (error) {
-      return res.status(400).json({ message: `Invalid alt text: ${error.details[0].message}` });
+    // Validate via the canonical schema shared with the MCP tool.
+    // Ghost's posts.feature_image_alt is varchar(191).
+    const altParse = featureImageAltSchema.safeParse(req.body.alt ?? undefined);
+    if (!altParse.success) {
+      return res
+        .status(400)
+        .json({ message: `Invalid alt text: ${altParse.error.issues[0].message}` });
     }
-
-    const providedAlt = sanitizedAlt;
+    const providedAlt = altParse.data;
     // Generate a default alt text from the original filename if none provided
     const defaultAlt = getDefaultAltText(req.file.originalname);
     const altText = providedAlt || defaultAlt;

package/src/mcp_server.js

@@ -8,9 +8,11 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
-import { ValidationError } from './errors/index.js';
 import { validateToolInput } from './utils/validation.js';
+import { formatErrorResponse } from './utils/formatErrorResponse.js';
+import { createContextLogger } from './utils/logger.js';
 import { trackTempFile, cleanupTempFiles } from './utils/tempFileManager.js';
+import { resolveLocalImagePath, decodeBase64ToTempFile } from './utils/imageInputResolver.js';
 import {
   createTagSchema,
   updateTagSchema,
@@ -37,6 +39,24 @@ import {
 // Load environment variables
 dotenv.config({ quiet: true });
 
+const mcpLogger = createContextLogger('mcp-server');
+
+/**
+ * Emit structured log fields for a caught error. Never passes the raw error
+ * object to the logger — Ghost SDK errors carry request headers/URLs that
+ * include credentials.
+ */
+const logToolError = (toolName, error, extra = {}) => {
+  mcpLogger.error(`Tool ${toolName} failed`, {
+    tool: toolName,
+    errorName: error?.name,
+    errorMessage: error?.message,
+    errorCode: error?.code,
+    ghostStatusCode: error?.ghostStatusCode,
+    ...extra,
+  });
+};
+
 // Lazy-loaded modules (to avoid Node.js v25 Buffer compatibility issues at startup)
 let ghostService = null;
 let postService = null;
@@ -98,7 +118,6 @@ const escapeNqlValue = (value) => {
  * @returns {Function} Wrapped async handler for server.registerTool
  */
 const withErrorHandling = (toolName, schema, handler) => {
-  const zodContext = toolName.replace('ghost_', '').replace(/_/g, ' ');
   return async (rawInput) => {
     console.error(`Executing tool: ${toolName}`);
     const validation = validateToolInput(schema, rawInput, toolName);
@@ -110,18 +129,8 @@ const withErrorHandling = (toolName, schema, handler) => {
       await loadServices();
       return await handler(validation.data);
     } catch (error) {
-      console.error(`Error in ${toolName}:`, error);
-      if (error.name === 'ZodError') {
-        const validationError = ValidationError.fromZod(error, zodContext);
-        return {
-          content: [{ type: 'text', text: JSON.stringify(validationError.toJSON(), null, 2) }],
-          isError: true,
-        };
-      }
-      return {
-        content: [{ type: 'text', text: `Error in ${toolName}: ${error.message}` }],
-        isError: true,
-      };
+      logToolError(toolName, error);
+      return formatErrorResponse(error, toolName);
     }
   };
 };
@@ -267,97 +276,274 @@ server.registerTool(
 );
 
 // --- Image Schema ---
-const uploadImageSchema = z.object({
-  imageUrl: z.string().meta({ description: 'The publicly accessible URL of the image to upload.' }),
+// Base object (plain ZodObject — keeps `.shape` available for MCP schema
+// introspection). Runtime XOR validation is applied at the tool level
+// via a manual check so we never wrap with ZodEffects.
+const imageInputFields = {
+  imageUrl: z.string().optional().meta({
+    description: 'The publicly accessible URL of the image to download and upload.',
+  }),
+  imagePath: z.string().optional().meta({
+    description:
+      'Absolute path to a local image file. Only accepted when the GHOST_MCP_IMAGE_ROOT env var is set; paths must resolve inside that root.',
+  }),
+  imageBase64: z.string().optional().meta({
+    description:
+      'Base64-encoded image bytes (with or without data: URI prefix). Decoded size capped at 5MB to respect MCP transport limits. Requires mimeType.',
+  }),
+  mimeType: z.string().optional().meta({
+    description:
+      'MIME type for imageBase64 input (e.g. image/png, image/jpeg, image/svg+xml). Required when imageBase64 is used.',
+  }),
   alt: z.string().optional().meta({
     description:
       'Alt text for the image. If omitted, a default will be generated from the filename.',
   }),
-});
+  purpose: z.enum(['image', 'profile_image', 'icon']).optional().meta({
+    description:
+      'Intended use. Ghost validates format/size per purpose (icon/profile_image must be square; icon also accepts ICO).',
+  }),
+  ref: z.string().max(200).optional().meta({
+    description:
+      'Caller-supplied identifier (e.g. original filename). Ghost echoes it back in the response.',
+  }),
+};
+
+const uploadImageSchema = z.object(imageInputFields);
+
+function validateImageInputXor(data) {
+  const count = Number(!!data.imageUrl) + Number(!!data.imagePath) + Number(!!data.imageBase64);
+  if (count !== 1) return 'Provide exactly one of imageUrl, imagePath, or imageBase64.';
+  if (data.imageBase64 && !data.mimeType) {
+    return 'mimeType is required when imageBase64 is provided.';
+  }
+  return null;
+}
+
+// Axios does not enforce `maxContentLength` for responseType: 'stream',
+// so we cap downloads here by watching bytes on the response stream and
+// destroying it on overflow. Mirrors the config value in urlValidator.js.
+const DOWNLOAD_CAP_BYTES = 50 * 1024 * 1024;
+
+async function acquireImageForUpload({ imageUrl, imagePath: localPath, imageBase64, mimeType }) {
+  const tempDir = os.tmpdir();
+
+  if (imageUrl) {
+    const urlValidation = urlValidator.validateImageUrl(imageUrl);
+    if (!urlValidation.isValid) {
+      throw new Error(`Invalid image URL: ${urlValidation.error}`);
+    }
+    const axiosConfig = urlValidator.createSecureAxiosConfig(urlValidation.sanitizedUrl);
+    const response = await axios(axiosConfig);
+
+    const declared = Number(response.headers['content-length']);
+    if (Number.isFinite(declared) && declared > DOWNLOAD_CAP_BYTES) {
+      response.data.destroy();
+      throw new Error(
+        `Image exceeds ${DOWNLOAD_CAP_BYTES} byte limit (server declared ${declared})`
+      );
+    }
+
+    const extension = path.extname(imageUrl.split('?')[0]) || '.tmp';
+    const filenameHint =
+      path.basename(imageUrl.split('?')[0]) || `image-${generateUuid()}${extension}`;
+    const downloadedPath = path.join(tempDir, `mcp-download-${generateUuid()}${extension}`);
+
+    let bytes = 0;
+    response.data.on('data', (chunk) => {
+      bytes += chunk.length;
+      if (bytes > DOWNLOAD_CAP_BYTES) {
+        response.data.destroy(new Error(`Image exceeds ${DOWNLOAD_CAP_BYTES} byte limit`));
+      }
+    });
+
+    const writer = fs.createWriteStream(downloadedPath);
+    response.data.pipe(writer);
+    await new Promise((resolve, reject) => {
+      writer.on('finish', resolve);
+      writer.on('error', reject);
+      response.data.on('error', reject);
+    });
+    return { acquiredPath: downloadedPath, filenameHint, source: 'url' };
+  }
+
+  if (localPath) {
+    const resolved = await resolveLocalImagePath(localPath);
+    return { acquiredPath: resolved, filenameHint: path.basename(resolved), source: 'path' };
+  }
+
+  if (imageBase64) {
+    const decodedPath = await decodeBase64ToTempFile(imageBase64, mimeType);
+    return {
+      acquiredPath: decodedPath,
+      filenameHint: path.basename(decodedPath),
+      source: 'base64',
+    };
+  }
+
+  throw new Error('No image input provided'); // unreachable — schema enforces one
+}
+
+/**
+ * Acquire → process → upload an image from a validated input. Owns its
+ * own temp-file lifecycle. Returns { uploadResult, filenameHint, finalAltText }.
+ * Does NOT delete the caller's imagePath file.
+ */
+async function performImageUpload(data) {
+  await loadServices();
+
+  let acquiredPath = null;
+  let processedPath = null;
+
+  try {
+    const acquired = await acquireImageForUpload(data);
+    acquiredPath = acquired.acquiredPath;
+    if (acquired.source !== 'path') trackTempFile(acquiredPath);
+
+    processedPath = await imageProcessingService.processImage(
+      acquiredPath,
+      os.tmpdir(),
+      data.purpose ? { purpose: data.purpose } : {}
+    );
+    if (processedPath !== acquiredPath) trackTempFile(processedPath);
+
+    const uploadOpts = {};
+    if (data.purpose) uploadOpts.purpose = data.purpose;
+    if (data.ref) uploadOpts.ref = data.ref;
+    else if (acquired.filenameHint) uploadOpts.ref = acquired.filenameHint.slice(0, 200);
+
+    const uploadResult = await ghostService.uploadImage(processedPath, uploadOpts);
+    const finalAltText = data.alt || getDefaultAltText(acquired.filenameHint);
+
+    return { uploadResult, filenameHint: acquired.filenameHint, finalAltText };
+  } finally {
+    const toClean = [];
+    if (acquiredPath && !data.imagePath) toClean.push(acquiredPath);
+    if (processedPath && processedPath !== acquiredPath) toClean.push(processedPath);
+    if (toClean.length > 0) await cleanupTempFiles(toClean, console);
+  }
+}
 
-// Upload Image Tool — unique handler with finally-clause cleanup
+/**
+ * Runs the standard tool-input validation then the XOR image-input check.
+ * Returns { success: true, data } or { success: false, errorResponse }
+ * so both image tools can collapse their validation prelude to one call.
+ */
+function validateAndXorImageInput(schema, rawInput, toolName) {
+  const validation = validateToolInput(schema, rawInput, toolName);
+  if (!validation.success) return validation;
+  const xorError = validateImageInputXor(validation.data);
+  if (xorError) {
+    return {
+      success: false,
+      errorResponse: { content: [{ type: 'text', text: xorError }], isError: true },
+    };
+  }
+  return validation;
+}
+
+// Upload Image Tool
 server.registerTool(
   '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.',
+      'Uploads an image to Ghost CMS. Accepts a remote URL, a local file path (when GHOST_MCP_IMAGE_ROOT is configured), or a base64 payload. Returns the Ghost image URL, alt text, and ref (when Ghost echoes it).',
     inputSchema: uploadImageSchema,
   },
   async (rawInput) => {
-    const validation = validateToolInput(uploadImageSchema, rawInput, 'ghost_upload_image');
-    if (!validation.success) {
-      return validation.errorResponse;
-    }
-    const { imageUrl, alt } = validation.data;
-
-    console.error(`Executing tool: ghost_upload_image for URL: ${imageUrl}`);
-    let downloadedPath = null;
-    let processedPath = null;
+    const validation = validateAndXorImageInput(uploadImageSchema, rawInput, 'ghost_upload_image');
+    if (!validation.success) return validation.errorResponse;
 
     try {
-      await loadServices();
-
-      // 1. Validate URL for SSRF protection
-      const urlValidation = urlValidator.validateImageUrl(imageUrl);
-      if (!urlValidation.isValid) {
-        throw new Error(`Invalid image URL: ${urlValidation.error}`);
-      }
-
-      // 2. Download the image with security controls
-      const axiosConfig = urlValidator.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-${generateUuid()}${extension}`;
-      downloadedPath = path.join(tempDir, `mcp-download-${generateUuid()}${extension}`);
-
-      const writer = fs.createWriteStream(downloadedPath);
-      response.data.pipe(writer);
-
-      await new Promise((resolve, reject) => {
-        writer.on('finish', resolve);
-        writer.on('error', reject);
-      });
-      // Track temp file for cleanup on process exit
-      trackTempFile(downloadedPath);
-      console.error(`Downloaded image to temporary path: ${downloadedPath}`);
-
-      // 3. Process the image
-      processedPath = await imageProcessingService.processImage(downloadedPath, tempDir);
-      // Track processed file for cleanup on process exit
-      if (processedPath !== downloadedPath) {
-        trackTempFile(processedPath);
-      }
-      console.error(`Processed image path: ${processedPath}`);
+      const { uploadResult, finalAltText } = await performImageUpload(validation.data);
+      const result = { url: uploadResult.url, alt: finalAltText };
+      if (uploadResult.ref) result.ref = uploadResult.ref;
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (error) {
+      logToolError('ghost_upload_image', error);
+      return formatErrorResponse(error, 'ghost_upload_image');
+    }
+  }
+);
 
-      // 4. Determine Alt Text
-      const defaultAlt = getDefaultAltText(originalFilenameHint);
-      const finalAltText = alt || defaultAlt;
-      console.error(`Using alt text: "${finalAltText}"`);
+// --- Set Feature Image Tool ---
+// Combined upload-and-assign flow. Ghost has no delete-image endpoint,
+// so when the post/page update fails after a successful upload, the
+// image is orphaned in Ghost's storage — we surface its URL in the
+// error response so the caller can reuse or record it.
+const setFeatureImageSchema = uploadImageSchema.extend({
+  type: z.enum(['post', 'page']).meta({
+    description: 'Which resource to attach the feature image to.',
+  }),
+  id: ghostIdSchema.meta({ description: 'ID of the post or page.' }),
+  caption: z.string().max(5000).optional().meta({
+    description: 'Optional HTML caption for the feature image (max 5000 chars).',
+  }),
+});
 
-      // 5. Upload processed image to Ghost
-      const uploadResult = await ghostService.uploadImage(processedPath);
-      console.error(`Uploaded processed image to Ghost: ${uploadResult.url}`);
+server.registerTool(
+  'ghost_set_feature_image',
+  {
+    description:
+      'Uploads an image and assigns it as the feature image of a post or page (with optional alt text and caption) in one call. Accepts the same imageUrl/imagePath/imageBase64 input modes as ghost_upload_image. Returns the updated resource. If the update fails after the upload, the error response includes the orphaned image URL.',
+    inputSchema: setFeatureImageSchema,
+  },
+  async (rawInput) => {
+    const validation = validateAndXorImageInput(
+      setFeatureImageSchema,
+      rawInput,
+      'ghost_set_feature_image'
+    );
+    if (!validation.success) return validation.errorResponse;
+
+    const { type, id, caption } = validation.data;
+
+    let uploadedUrl;
+    let uploadedRef;
+    let altText;
+    try {
+      const { uploadResult, finalAltText } = await performImageUpload(validation.data);
+      uploadedUrl = uploadResult.url;
+      uploadedRef = uploadResult.ref;
+      altText = finalAltText;
+    } catch (error) {
+      logToolError('ghost_set_feature_image', error, { phase: 'upload' });
+      return formatErrorResponse(error, 'ghost_set_feature_image');
+    }
 
-      // 6. Return result
-      const result = {
-        url: uploadResult.url,
-        alt: finalAltText,
-      };
+    const updatePayload = {
+      feature_image: uploadedUrl,
+      feature_image_alt: altText,
+    };
+    if (caption !== undefined) updatePayload.feature_image_caption = caption;
 
+    try {
+      const updated =
+        type === 'post'
+          ? await ghostService.updatePost(id, updatePayload)
+          : await ghostService.updatePage(id, updatePayload);
+      console.error(`ghost_set_feature_image: ${type} ${id} updated with ${uploadedUrl}`);
       return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              { uploaded: { url: uploadedUrl, ref: uploadedRef, alt: altText }, [type]: updated },
+              null,
+              2
+            ),
+          },
+        ],
       };
     } catch (error) {
-      console.error(`Error in ghost_upload_image:`, error);
-      return {
-        content: [{ type: 'text', text: `Error uploading image: ${error.message}` }],
-        isError: true,
-      };
-    } finally {
-      // Cleanup temporary files with proper async/await
-      await cleanupTempFiles([downloadedPath, processedPath], console);
+      logToolError('ghost_set_feature_image', error, {
+        phase: 'update',
+        orphanedUrl: uploadedUrl,
+      });
+      return formatErrorResponse(error, 'ghost_set_feature_image', {
+        orphanedImage: { url: uploadedUrl, ref: uploadedRef, alt: altText },
+        hint: 'Ghost does not expose a delete-image endpoint; reuse this URL or leave it orphaned.',
+      });
     }
   }
 );

package/src/routes/__tests__/imageRoutes.test.js

@@ -41,8 +41,8 @@ vi.mock('../../services/imageProcessingService.js', () => ({
   processImage: vi.fn().mockResolvedValue('/tmp/processed-image.jpg'),
 }));
 
-// Mock the ghost service
-vi.mock('../../services/ghostService.js', () => ({
+// Mock the image upload service (now in images.js, re-exported via ghostServiceImproved.js)
+vi.mock('../../services/images.js', () => ({
   uploadImage: vi.fn().mockResolvedValue({ url: 'https://ghost.com/image.jpg' }),
 }));
 

package/src/schemas/__tests__/common.test.js

@@ -336,12 +336,12 @@ describe('Common Schemas', () => {
   describe('featureImageAltSchema', () => {
     it('should accept valid alt text', () => {
       expect(() => featureImageAltSchema.parse('Image description')).not.toThrow();
-      expect(() => featureImageAltSchema.parse('A'.repeat(125))).not.toThrow();
+      expect(() => featureImageAltSchema.parse('A'.repeat(191))).not.toThrow();
       expect(() => featureImageAltSchema.parse(undefined)).not.toThrow();
     });
 
-    it('should reject too long alt text', () => {
-      expect(() => featureImageAltSchema.parse('A'.repeat(126))).toThrow();
+    it('should reject too long alt text (>191, matches Ghost varchar(191))', () => {
+      expect(() => featureImageAltSchema.parse('A'.repeat(192))).toThrow();
     });
   });
 

package/src/schemas/__tests__/pageSchemas.test.js

@@ -115,16 +115,25 @@ describe('Page Schemas', () => {
       expect(() => createPageSchema.parse(invalidPage)).toThrow();
     });
 
-    it('should reject page with too long feature_image_caption', () => {
+    it('should reject page with too long feature_image_caption (>5000)', () => {
       const invalidPage = {
         title: 'Page',
         html: '<p>Content</p>',
-        feature_image_caption: 'A'.repeat(501),
+        feature_image_caption: 'A'.repeat(5001),
       };
 
       expect(() => createPageSchema.parse(invalidPage)).toThrow();
     });
 
+    it('should accept a 5000-char feature_image_caption', () => {
+      const page = {
+        title: 'Page',
+        html: '<p>Content</p>',
+        feature_image_caption: 'A'.repeat(5000),
+      };
+      expect(() => createPageSchema.parse(page)).not.toThrow();
+    });
+
     it('should reject page with too long og_title', () => {
       const invalidPage = {
         title: 'Page',

package/src/schemas/common.js

@@ -205,11 +205,12 @@ export const featureImageSchema = z.string().url('Invalid feature image URL').op
 
 /**
  * Feature image alt text validation schema
- * Optional alt text for accessibility
+ * Optional alt text for accessibility. Ghost's posts.feature_image_alt
+ * column is varchar(191); anything longer is rejected server-side.
  */
 export const featureImageAltSchema = z
   .string()
-  .max(125, 'Feature image alt text cannot exceed 125 characters')
+  .max(191, 'Feature image alt text cannot exceed 191 characters')
   .optional();
 
 /**

package/src/schemas/pageSchemas.js

@@ -44,7 +44,7 @@ export const createPageSchema = z.object({
   featured: featuredSchema,
   feature_image: featureImageSchema,
   feature_image_alt: featureImageAltSchema,
-  feature_image_caption: z.string().max(500, 'Caption cannot exceed 500 characters').optional(),
+  feature_image_caption: z.string().max(5000, 'Caption cannot exceed 5000 characters').optional(),
   excerpt: excerptSchema,
   custom_excerpt: customExcerptSchema,
   meta_title: metaTitleSchema,

package/src/schemas/postSchemas.js

@@ -42,7 +42,7 @@ export const createPostSchema = z.object({
   featured: featuredSchema,
   feature_image: featureImageSchema,
   feature_image_alt: featureImageAltSchema,
-  feature_image_caption: z.string().max(500, 'Caption cannot exceed 500 characters').optional(),
+  feature_image_caption: z.string().max(5000, 'Caption cannot exceed 5000 characters').optional(),
   excerpt: excerptSchema,
   custom_excerpt: customExcerptSchema,
   meta_title: metaTitleSchema,