@jgardner04/ghost-mcp-server 1.6.0 → 1.8.0

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

@@ -0,0 +1,262 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createTagSchema,
+  updateTagSchema,
+  tagQuerySchema,
+  tagIdSchema,
+  tagOutputSchema,
+} from '../tagSchemas.js';
+
+describe('Tag Schemas', () => {
+  describe('createTagSchema', () => {
+    it('should accept valid tag creation data', () => {
+      const validTag = {
+        name: 'Technology',
+        slug: 'technology',
+        description: 'Posts about technology',
+        visibility: 'public',
+      };
+
+      expect(() => createTagSchema.parse(validTag)).not.toThrow();
+    });
+
+    it('should accept minimal tag creation data (name only)', () => {
+      const minimalTag = {
+        name: 'News',
+      };
+
+      const result = createTagSchema.parse(minimalTag);
+      expect(result.name).toBe('News');
+      expect(result.visibility).toBe('public'); // default value
+    });
+
+    it('should accept tag with all optional fields', () => {
+      const fullTag = {
+        name: 'Technology',
+        slug: 'tech',
+        description: 'Tech posts',
+        feature_image: 'https://example.com/image.jpg',
+        visibility: 'public',
+        meta_title: 'Technology Posts',
+        meta_description: 'All about tech',
+        og_image: 'https://example.com/og.jpg',
+        og_title: 'Tech on Our Blog',
+        og_description: 'Technology articles',
+        twitter_image: 'https://example.com/twitter.jpg',
+        twitter_title: 'Tech Posts',
+        twitter_description: 'Latest tech news',
+        codeinjection_head: '<script>console.log("head")</script>',
+        codeinjection_foot: '<script>console.log("foot")</script>',
+        canonical_url: 'https://example.com/tech',
+        accent_color: '#FF5733',
+      };
+
+      expect(() => createTagSchema.parse(fullTag)).not.toThrow();
+    });
+
+    it('should reject tag without name', () => {
+      const invalidTag = {
+        slug: 'tech',
+      };
+
+      expect(() => createTagSchema.parse(invalidTag)).toThrow();
+    });
+
+    it('should reject tag with invalid slug', () => {
+      const invalidTag = {
+        name: 'Technology',
+        slug: 'Tech_Posts', // uppercase and underscore not allowed
+      };
+
+      expect(() => createTagSchema.parse(invalidTag)).toThrow();
+    });
+
+    it('should reject tag with invalid accent color', () => {
+      const invalidTag = {
+        name: 'Technology',
+        accent_color: 'red', // must be hex format
+      };
+
+      expect(() => createTagSchema.parse(invalidTag)).toThrow();
+    });
+
+    it('should reject tag with too long description', () => {
+      const invalidTag = {
+        name: 'Technology',
+        description: 'A'.repeat(501),
+      };
+
+      expect(() => createTagSchema.parse(invalidTag)).toThrow();
+    });
+
+    it('should reject tag with invalid visibility', () => {
+      const invalidTag = {
+        name: 'Technology',
+        visibility: 'private', // not a valid value
+      };
+
+      expect(() => createTagSchema.parse(invalidTag)).toThrow();
+    });
+  });
+
+  describe('updateTagSchema', () => {
+    it('should accept partial tag updates', () => {
+      const update = {
+        description: 'Updated description',
+      };
+
+      expect(() => updateTagSchema.parse(update)).not.toThrow();
+    });
+
+    it('should accept empty update object', () => {
+      expect(() => updateTagSchema.parse({})).not.toThrow();
+    });
+
+    it('should accept full tag update', () => {
+      const update = {
+        name: 'Updated Name',
+        slug: 'updated-slug',
+        description: 'Updated description',
+      };
+
+      expect(() => updateTagSchema.parse(update)).not.toThrow();
+    });
+  });
+
+  describe('tagQuerySchema', () => {
+    it('should accept valid query parameters', () => {
+      const query = {
+        name: 'Technology',
+        limit: 20,
+        page: 2,
+      };
+
+      expect(() => tagQuerySchema.parse(query)).not.toThrow();
+    });
+
+    it('should accept query with NQL filter', () => {
+      const query = {
+        filter: 'visibility:public+featured:true',
+        limit: 10,
+      };
+
+      expect(() => tagQuerySchema.parse(query)).not.toThrow();
+    });
+
+    it('should accept query with include parameter', () => {
+      const query = {
+        include: 'count.posts',
+      };
+
+      expect(() => tagQuerySchema.parse(query)).not.toThrow();
+    });
+
+    it('should accept query with order parameter', () => {
+      const query = {
+        order: 'name ASC',
+      };
+
+      expect(() => tagQuerySchema.parse(query)).not.toThrow();
+    });
+
+    it('should reject query with invalid filter characters', () => {
+      const query = {
+        filter: 'status;DROP TABLE',
+      };
+
+      expect(() => tagQuerySchema.parse(query)).toThrow();
+    });
+
+    it('should accept empty query object', () => {
+      const result = tagQuerySchema.parse({});
+      expect(result).toBeDefined();
+      // Note: optional fields with defaults don't apply when field is omitted
+    });
+  });
+
+  describe('tagIdSchema', () => {
+    it('should accept valid Ghost ID', () => {
+      const validId = {
+        id: '507f1f77bcf86cd799439011',
+      };
+
+      expect(() => tagIdSchema.parse(validId)).not.toThrow();
+    });
+
+    it('should reject invalid Ghost ID', () => {
+      const invalidId = {
+        id: 'invalid-id',
+      };
+
+      expect(() => tagIdSchema.parse(invalidId)).toThrow();
+    });
+  });
+
+  describe('tagOutputSchema', () => {
+    it('should accept valid tag output from Ghost API', () => {
+      const apiTag = {
+        id: '507f1f77bcf86cd799439011',
+        name: 'Technology',
+        slug: 'technology',
+        description: 'Tech posts',
+        feature_image: 'https://example.com/image.jpg',
+        visibility: 'public',
+        meta_title: 'Tech Posts',
+        meta_description: 'Technology articles',
+        og_image: 'https://example.com/og.jpg',
+        og_title: 'Tech',
+        og_description: 'Tech posts',
+        twitter_image: 'https://example.com/twitter.jpg',
+        twitter_title: 'Tech',
+        twitter_description: 'Tech posts',
+        codeinjection_head: null,
+        codeinjection_foot: null,
+        canonical_url: 'https://example.com/tech',
+        accent_color: '#FF5733',
+        created_at: '2024-01-15T10:30:00.000Z',
+        updated_at: '2024-01-15T10:30:00.000Z',
+        url: 'https://example.com/tag/technology',
+      };
+
+      expect(() => tagOutputSchema.parse(apiTag)).not.toThrow();
+    });
+
+    it('should accept tag with null optional fields', () => {
+      const apiTag = {
+        id: '507f1f77bcf86cd799439011',
+        name: 'Technology',
+        slug: 'technology',
+        description: null,
+        feature_image: null,
+        visibility: 'public',
+        meta_title: null,
+        meta_description: null,
+        og_image: null,
+        og_title: null,
+        og_description: null,
+        twitter_image: null,
+        twitter_title: null,
+        twitter_description: null,
+        codeinjection_head: null,
+        codeinjection_foot: null,
+        canonical_url: null,
+        accent_color: null,
+        created_at: '2024-01-15T10:30:00.000Z',
+        updated_at: '2024-01-15T10:30:00.000Z',
+        url: 'https://example.com/tag/technology',
+      };
+
+      expect(() => tagOutputSchema.parse(apiTag)).not.toThrow();
+    });
+
+    it('should reject tag output without required fields', () => {
+      const invalidTag = {
+        name: 'Technology',
+        slug: 'technology',
+        // missing id, created_at, updated_at, url, visibility
+      };
+
+      expect(() => tagOutputSchema.parse(invalidTag)).toThrow();
+    });
+  });
+});

package/src/schemas/common.js

@@ -0,0 +1,227 @@
+import { z } from 'zod';
+
+/**
+ * Common Zod schemas for validation across all Ghost MCP resources.
+ * These validators provide consistent validation and security controls.
+ */
+
+// ----- Basic Type Validators -----
+
+/**
+ * Email validation schema
+ * Validates proper email format
+ */
+export const emailSchema = z.string().email('Invalid email format');
+
+/**
+ * URL validation schema
+ * Validates proper URL format (http/https)
+ */
+export const urlSchema = z.string().url('Invalid URL format');
+
+/**
+ * ISO 8601 datetime validation schema
+ * Validates ISO datetime strings
+ */
+export const isoDateSchema = z.string().datetime('Invalid ISO 8601 datetime format');
+
+/**
+ * Slug validation schema
+ * Validates URL-friendly slugs (lowercase alphanumeric with hyphens)
+ */
+export const slugSchema = z
+  .string()
+  .regex(/^[a-z0-9-]+$/, 'Slug must contain only lowercase letters, numbers, and hyphens');
+
+/**
+ * Ghost ID validation schema
+ * Validates 24-character hexadecimal Ghost object IDs
+ */
+export const ghostIdSchema = z
+  .string()
+  .regex(/^[a-f0-9]{24}$/, 'Invalid Ghost ID format (must be 24 hex characters)');
+
+// ----- Security Validators -----
+
+/**
+ * NQL (Ghost Query Language) filter validation schema
+ * Prevents injection attacks by restricting allowed characters
+ * Allows: alphanumeric, underscores, hyphens, colons, dots, quotes, spaces, commas, brackets, comparison operators
+ */
+export const nqlFilterSchema = z
+  .string()
+  .regex(/^[a-zA-Z0-9_\-:.'"\s,[\]<>=!+]+$/, 'Invalid NQL filter: contains disallowed characters')
+  .optional();
+
+// ----- Pagination Validators -----
+
+/**
+ * Limit validation schema for pagination
+ * Restricts result count between 1 and 100
+ */
+export const limitSchema = z
+  .number()
+  .int('Limit must be an integer')
+  .min(1, 'Limit must be at least 1')
+  .max(100, 'Limit cannot exceed 100')
+  .default(15);
+
+/**
+ * Page number validation schema for pagination
+ * Must be a positive integer starting from 1
+ */
+export const pageSchema = z
+  .number()
+  .int('Page must be an integer')
+  .min(1, 'Page must be at least 1')
+  .default(1);
+
+/**
+ * Complete pagination options schema
+ */
+export const paginationSchema = z.object({
+  limit: limitSchema,
+  page: pageSchema,
+});
+
+// ----- Status Enum Validators -----
+
+/**
+ * Post/Page status validation schema
+ * Valid values: draft, published, scheduled
+ */
+export const postStatusSchema = z.enum(['draft', 'published', 'scheduled'], {
+  errorMap: () => ({ message: 'Status must be draft, published, or scheduled' }),
+});
+
+/**
+ * Visibility validation schema
+ * Controls content visibility (public, members, paid, tiers)
+ */
+export const visibilitySchema = z.enum(['public', 'members', 'paid', 'tiers'], {
+  errorMap: () => ({ message: 'Visibility must be public, members, paid, or tiers' }),
+});
+
+// ----- Common Field Validators -----
+
+/**
+ * HTML content validation schema
+ * Validates that content is a non-empty string
+ * Note: HTML sanitization should be performed separately
+ */
+export const htmlContentSchema = z.string().min(1, 'HTML content cannot be empty');
+
+/**
+ * Title validation schema
+ * Validates post/page titles (1-255 characters)
+ */
+export const titleSchema = z
+  .string()
+  .min(1, 'Title cannot be empty')
+  .max(255, 'Title cannot exceed 255 characters');
+
+/**
+ * Excerpt/description validation schema
+ * Optional text snippet (max 500 characters)
+ */
+export const excerptSchema = z.string().max(500, 'Excerpt cannot exceed 500 characters').optional();
+
+/**
+ * Meta title validation schema (SEO)
+ * Optional SEO title (max 300 characters)
+ */
+export const metaTitleSchema = z
+  .string()
+  .max(300, 'Meta title cannot exceed 300 characters')
+  .optional();
+
+/**
+ * Meta description validation schema (SEO)
+ * Optional SEO description (max 500 characters)
+ */
+export const metaDescriptionSchema = z
+  .string()
+  .max(500, 'Meta description cannot exceed 500 characters')
+  .optional();
+
+/**
+ * Featured flag validation schema
+ * Boolean indicating if content is featured
+ */
+export const featuredSchema = z.boolean().default(false);
+
+/**
+ * Feature image URL validation schema
+ * Optional URL for featured image
+ */
+export const featureImageSchema = z.string().url('Invalid feature image URL').optional();
+
+/**
+ * Feature image alt text validation schema
+ * Optional alt text for accessibility
+ */
+export const featureImageAltSchema = z
+  .string()
+  .max(125, 'Feature image alt text cannot exceed 125 characters')
+  .optional();
+
+/**
+ * Tag name validation schema
+ * Tag names (1-191 characters)
+ */
+export const tagNameSchema = z
+  .string()
+  .min(1, 'Tag name cannot be empty')
+  .max(191, 'Tag name cannot exceed 191 characters');
+
+/**
+ * Authors array validation schema
+ * Array of Ghost author IDs or email addresses
+ */
+export const authorsSchema = z.array(z.string()).optional();
+
+/**
+ * Tags array validation schema
+ * Array of tag names or Ghost tag IDs
+ */
+export const tagsSchema = z.array(z.string()).optional();
+
+// ----- Utility Validators -----
+
+/**
+ * Canonical URL validation schema
+ * Optional canonical URL for SEO
+ */
+export const canonicalUrlSchema = z.string().url('Invalid canonical URL').optional();
+
+/**
+ * Code injection validation schema
+ * Optional HTML/JS code injection (use with caution)
+ */
+export const codeInjectionSchema = z
+  .object({
+    head: z.string().optional(),
+    foot: z.string().optional(),
+  })
+  .optional();
+
+/**
+ * OG (Open Graph) image validation schema
+ * Optional social media image URL
+ */
+export const ogImageSchema = z.string().url('Invalid OG image URL').optional();
+
+/**
+ * Twitter image validation schema
+ * Optional Twitter card image URL
+ */
+export const twitterImageSchema = z.string().url('Invalid Twitter image URL').optional();
+
+/**
+ * Custom excerpt validation schema for social media
+ * Optional custom excerpt for social sharing
+ */
+export const customExcerptSchema = z
+  .string()
+  .max(300, 'Custom excerpt cannot exceed 300 characters')
+  .optional();

package/src/schemas/index.js

@@ -0,0 +1,39 @@
+/**
+ * Centralized Zod Schema Library for Ghost MCP Server
+ *
+ * This module exports all validation schemas for Ghost CMS resources.
+ * Use these schemas for consistent input/output validation across all MCP tools.
+ *
+ * @example
+ * import { createPostSchema, tagQuerySchema } from './schemas/index.js';
+ *
+ * // Validate input
+ * const validatedPost = createPostSchema.parse(inputData);
+ *
+ * // Safe parse with error handling
+ * const result = tagQuerySchema.safeParse(queryParams);
+ * if (!result.success) {
+ *   console.error(result.error);
+ * }
+ */
+
+// Common validators and utilities
+export * from './common.js';
+
+// Post schemas
+export * from './postSchemas.js';
+
+// Page schemas
+export * from './pageSchemas.js';
+
+// Tag schemas
+export * from './tagSchemas.js';
+
+// Member schemas
+export * from './memberSchemas.js';
+
+// Newsletter schemas
+export * from './newsletterSchemas.js';
+
+// Tier (membership/product) schemas
+export * from './tierSchemas.js';

package/src/schemas/memberSchemas.js

@@ -0,0 +1,188 @@
+import { z } from 'zod';
+import { ghostIdSchema, emailSchema } from './common.js';
+
+/**
+ * Member Schemas for Ghost CMS
+ * Provides input/output validation for member operations
+ */
+
+// ----- Input Schemas -----
+
+/**
+ * Schema for creating a new member
+ * Required: email
+ * Optional: name, note, subscribed, labels, etc.
+ */
+export const createMemberSchema = z.object({
+  email: emailSchema,
+  name: z.string().max(191, 'Name cannot exceed 191 characters').optional(),
+  note: z.string().max(2000, 'Note cannot exceed 2000 characters').optional(),
+  subscribed: z.boolean().default(true).describe('Whether member is subscribed to newsletter'),
+  comped: z.boolean().default(false).describe('Whether member has complimentary subscription'),
+  labels: z.array(z.string()).optional().describe('Array of label names to associate with member'),
+  newsletters: z
+    .array(ghostIdSchema)
+    .optional()
+    .describe('Array of newsletter IDs to subscribe member to'),
+});
+
+/**
+ * Schema for updating an existing member
+ * All fields optional
+ */
+export const updateMemberSchema = createMemberSchema.partial();
+
+/**
+ * Schema for member query/filter parameters
+ */
+export const memberQuerySchema = z.object({
+  limit: z.number().int().min(1).max(100).default(15).optional(),
+  page: z.number().int().min(1).default(1).optional(),
+  filter: z
+    .string()
+    .regex(/^[a-zA-Z0-9_\-:.'"\s,[\]<>=!+]+$/, 'Invalid filter: contains disallowed characters')
+    .optional()
+    .describe('NQL filter string (e.g., "status:paid+subscribed:true")'),
+  include: z
+    .string()
+    .optional()
+    .describe('Comma-separated list of relations (e.g., "labels,newsletters")'),
+  order: z.string().optional().describe('Order results (e.g., "created_at DESC", "name ASC")'),
+  search: z.string().optional().describe('Search members by name or email'),
+});
+
+/**
+ * Schema for member ID parameter
+ */
+export const memberIdSchema = z.object({
+  id: ghostIdSchema,
+});
+
+/**
+ * Schema for member email parameter
+ */
+export const memberEmailSchema = z.object({
+  email: emailSchema,
+});
+
+// ----- Output Schemas -----
+
+/**
+ * Schema for a label object (nested in member)
+ */
+export const labelOutputSchema = z.object({
+  id: ghostIdSchema,
+  name: z.string(),
+  slug: z.string(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+/**
+ * Schema for a newsletter object (nested in member)
+ */
+export const newsletterOutputSchema = z.object({
+  id: ghostIdSchema,
+  uuid: z.string().uuid(),
+  name: z.string(),
+  description: z.string().nullable().optional(),
+  slug: z.string(),
+  sender_name: z.string().nullable().optional(),
+  sender_email: z.string().email().nullable().optional(),
+  sender_reply_to: z.enum(['newsletter', 'support']).optional(),
+  status: z.enum(['active', 'archived']),
+  visibility: z.enum(['members', 'paid']),
+  subscribe_on_signup: z.boolean(),
+  sort_order: z.number(),
+  header_image: z.string().url().nullable().optional(),
+  show_header_icon: z.boolean(),
+  show_header_title: z.boolean(),
+  title_font_category: z.string(),
+  title_alignment: z.enum(['left', 'center']),
+  show_feature_image: z.boolean(),
+  body_font_category: z.string(),
+  footer_content: z.string().nullable().optional(),
+  show_badge: z.boolean(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+/**
+ * Schema for member subscription (tier/product)
+ */
+export const memberSubscriptionSchema = z.object({
+  id: z.string(),
+  customer: z.object({
+    id: z.string(),
+    name: z.string().nullable().optional(),
+    email: z.string().email(),
+  }),
+  plan: z.object({
+    id: z.string(),
+    nickname: z.string(),
+    amount: z.number(),
+    interval: z.enum(['month', 'year']),
+    currency: z.string(),
+  }),
+  status: z.enum(['active', 'trialing', 'past_due', 'canceled', 'unpaid']),
+  start_date: z.string().datetime(),
+  current_period_end: z.string().datetime(),
+  cancel_at_period_end: z.boolean(),
+  cancellation_reason: z.string().nullable().optional(),
+  trial_start_date: z.string().datetime().nullable().optional(),
+  trial_end_date: z.string().datetime().nullable().optional(),
+});
+
+/**
+ * Schema for a Ghost member object (as returned by the API)
+ */
+export const memberOutputSchema = z.object({
+  id: ghostIdSchema,
+  uuid: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string().nullable().optional(),
+  note: z.string().nullable().optional(),
+  geolocation: z.string().nullable().optional(),
+  enable_comment_notifications: z.boolean(),
+  email_count: z.number(),
+  email_opened_count: z.number(),
+  email_open_rate: z.number().nullable().optional(),
+  status: z.enum(['free', 'paid', 'comped']),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  subscribed: z.boolean(),
+  comped: z.boolean(),
+  email_suppression: z
+    .object({
+      suppressed: z.boolean(),
+      info: z.string().nullable().optional(),
+    })
+    .nullable()
+    .optional(),
+  labels: z.array(labelOutputSchema).optional(),
+  subscriptions: z.array(memberSubscriptionSchema).optional(),
+  newsletters: z.array(newsletterOutputSchema).optional(),
+  avatar_image: z.string().url().nullable().optional(),
+});
+
+/**
+ * Schema for array of members
+ */
+export const membersArraySchema = z.array(memberOutputSchema);
+
+/**
+ * Schema for paginated member response
+ */
+export const membersPaginatedSchema = z.object({
+  members: membersArraySchema,
+  meta: z.object({
+    pagination: z.object({
+      page: z.number(),
+      limit: z.number(),
+      pages: z.number(),
+      total: z.number(),
+      next: z.number().nullable(),
+      prev: z.number().nullable(),
+    }),
+  }),
+});