@jgardner04/ghost-mcp-server 1.6.0 → 1.8.0

package/src/schemas/tagSchemas.js

@@ -0,0 +1,136 @@
+import { z } from 'zod';
+import {
+  ghostIdSchema,
+  slugSchema,
+  tagNameSchema,
+  metaTitleSchema,
+  metaDescriptionSchema,
+  canonicalUrlSchema,
+  featureImageSchema,
+  visibilitySchema,
+  ogImageSchema,
+  twitterImageSchema,
+} from './common.js';
+
+/**
+ * Tag Schemas for Ghost CMS
+ * Provides input/output validation for tag operations
+ */
+
+// ----- Input Schemas -----
+
+/**
+ * Schema for creating a new tag
+ * Required: name
+ * Optional: slug, description, feature_image, visibility, meta fields
+ */
+export const createTagSchema = z.object({
+  name: tagNameSchema,
+  slug: slugSchema.optional(),
+  description: z.string().max(500, 'Description cannot exceed 500 characters').optional(),
+  feature_image: featureImageSchema,
+  visibility: visibilitySchema.default('public'),
+  meta_title: metaTitleSchema,
+  meta_description: metaDescriptionSchema,
+  og_image: ogImageSchema,
+  og_title: z.string().max(300, 'OG title cannot exceed 300 characters').optional(),
+  og_description: z.string().max(500, 'OG description cannot exceed 500 characters').optional(),
+  twitter_image: twitterImageSchema,
+  twitter_title: z.string().max(300, 'Twitter title cannot exceed 300 characters').optional(),
+  twitter_description: z
+    .string()
+    .max(500, 'Twitter description cannot exceed 500 characters')
+    .optional(),
+  codeinjection_head: z.string().optional(),
+  codeinjection_foot: z.string().optional(),
+  canonical_url: canonicalUrlSchema,
+  accent_color: z
+    .string()
+    .regex(/^#[0-9A-Fa-f]{6}$/, 'Accent color must be a hex color code (e.g., #FF5733)')
+    .optional(),
+});
+
+/**
+ * Schema for updating an existing tag
+ * All fields optional except when doing full replacement
+ */
+export const updateTagSchema = createTagSchema.partial();
+
+/**
+ * Schema for tag query/filter parameters
+ */
+export const tagQuerySchema = z.object({
+  name: z.string().optional().describe('Filter by exact tag name'),
+  slug: z.string().optional().describe('Filter by tag slug'),
+  visibility: visibilitySchema.optional().describe('Filter by visibility'),
+  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'),
+  include: z
+    .string()
+    .optional()
+    .describe('Comma-separated list of relations to include (e.g., "count.posts")'),
+  order: z.string().optional().describe('Order results (e.g., "name ASC", "created_at DESC")'),
+});
+
+/**
+ * Schema for tag ID parameter
+ */
+export const tagIdSchema = z.object({
+  id: ghostIdSchema,
+});
+
+// ----- Output Schemas -----
+
+/**
+ * Schema for a Ghost tag object (as returned by the API)
+ */
+export const tagOutputSchema = z.object({
+  id: ghostIdSchema,
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable().optional(),
+  feature_image: z.string().url().nullable().optional(),
+  visibility: visibilitySchema,
+  meta_title: z.string().nullable().optional(),
+  meta_description: z.string().nullable().optional(),
+  og_image: z.string().url().nullable().optional(),
+  og_title: z.string().nullable().optional(),
+  og_description: z.string().nullable().optional(),
+  twitter_image: z.string().url().nullable().optional(),
+  twitter_title: z.string().nullable().optional(),
+  twitter_description: z.string().nullable().optional(),
+  codeinjection_head: z.string().nullable().optional(),
+  codeinjection_foot: z.string().nullable().optional(),
+  canonical_url: z.string().url().nullable().optional(),
+  accent_color: z.string().nullable().optional(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  url: z.string().url(),
+});
+
+/**
+ * Schema for array of tags
+ */
+export const tagsArraySchema = z.array(tagOutputSchema);
+
+/**
+ * Schema for paginated tag response
+ */
+export const tagsPaginatedSchema = z.object({
+  tags: tagsArraySchema,
+  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(),
+    }),
+  }),
+});

package/src/schemas/tierSchemas.js

@@ -0,0 +1,206 @@
+import { z } from 'zod';
+import { ghostIdSchema, slugSchema } from './common.js';
+
+/**
+ * Tier (Membership/Product) Schemas for Ghost CMS
+ * Tiers represent membership levels and pricing plans
+ * Provides input/output validation for tier operations
+ */
+
+// ----- Input Schemas -----
+
+/**
+ * Schema for tier benefits (features)
+ */
+export const tierBenefitSchema = z.object({
+  name: z.string().min(1, 'Benefit name cannot be empty').max(191, 'Benefit name too long'),
+});
+
+/**
+ * Schema for monthly price configuration
+ */
+export const monthlyPriceSchema = z.object({
+  amount: z.number().int().min(0, 'Monthly price must be non-negative'),
+  currency: z
+    .string()
+    .length(3, 'Currency must be 3-letter ISO code (e.g., USD, EUR)')
+    .regex(/^[A-Z]{3}$/, 'Currency must be uppercase 3-letter code'),
+});
+
+/**
+ * Schema for yearly price configuration
+ */
+export const yearlyPriceSchema = z.object({
+  amount: z.number().int().min(0, 'Yearly price must be non-negative'),
+  currency: z
+    .string()
+    .length(3, 'Currency must be 3-letter ISO code (e.g., USD, EUR)')
+    .regex(/^[A-Z]{3}$/, 'Currency must be uppercase 3-letter code'),
+});
+
+/**
+ * Schema for creating a new tier
+ * Required: name
+ * Optional: description, benefits, pricing, visibility
+ */
+export const createTierSchema = z.object({
+  name: z.string().min(1, 'Name cannot be empty').max(191, 'Name cannot exceed 191 characters'),
+  description: z.string().max(2000, 'Description cannot exceed 2000 characters').optional(),
+  slug: slugSchema.optional(),
+  active: z.boolean().default(true).describe('Whether tier is currently active/available'),
+  type: z
+    .enum(['free', 'paid'], {
+      errorMap: () => ({ message: 'Type must be free or paid' }),
+    })
+    .default('paid'),
+  welcome_page_url: z.string().url('Invalid welcome page URL').optional(),
+  visibility: z
+    .enum(['public', 'none'], {
+      errorMap: () => ({ message: 'Visibility must be public or none' }),
+    })
+    .default('public'),
+  trial_days: z
+    .number()
+    .int()
+    .min(0, 'Trial days must be non-negative')
+    .default(0)
+    .describe('Number of trial days for paid tiers'),
+  currency: z
+    .string()
+    .length(3, 'Currency must be 3-letter ISO code')
+    .regex(/^[A-Z]{3}$/, 'Currency must be uppercase')
+    .optional(),
+  monthly_price: z.number().int().min(0, 'Monthly price must be non-negative').optional(),
+  yearly_price: z.number().int().min(0, 'Yearly price must be non-negative').optional(),
+  benefits: z.array(z.string()).optional().describe('Array of benefit names/descriptions'),
+});
+
+/**
+ * Schema for updating an existing tier
+ * All fields optional
+ */
+export const updateTierSchema = createTierSchema.partial();
+
+/**
+ * Schema for tier query/filter parameters
+ */
+export const tierQuerySchema = 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., "type:paid+active:true")'),
+  include: z.string().optional().describe('Comma-separated list of relations to include'),
+  order: z
+    .string()
+    .optional()
+    .describe('Order results (e.g., "monthly_price ASC", "created_at DESC")'),
+});
+
+/**
+ * Schema for tier ID parameter
+ */
+export const tierIdSchema = z.object({
+  id: ghostIdSchema,
+});
+
+/**
+ * Schema for tier slug parameter
+ */
+export const tierSlugSchema = z.object({
+  slug: slugSchema,
+});
+
+// ----- Output Schemas -----
+
+/**
+ * Schema for a benefit object (as returned by the API)
+ */
+export const benefitOutputSchema = z.object({
+  id: ghostIdSchema,
+  name: z.string(),
+  slug: z.string(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+/**
+ * Schema for monthly price object (as returned by the API)
+ */
+export const monthlyPriceOutputSchema = z.object({
+  id: z.string(),
+  tier_id: ghostIdSchema,
+  nickname: z.string(),
+  amount: z.number(),
+  interval: z.literal('month'),
+  type: z.enum(['recurring', 'one-time']),
+  currency: z.string(),
+  active: z.boolean(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+/**
+ * Schema for yearly price object (as returned by the API)
+ */
+export const yearlyPriceOutputSchema = z.object({
+  id: z.string(),
+  tier_id: ghostIdSchema,
+  nickname: z.string(),
+  amount: z.number(),
+  interval: z.literal('year'),
+  type: z.enum(['recurring', 'one-time']),
+  currency: z.string(),
+  active: z.boolean(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+/**
+ * Schema for a Ghost tier object (as returned by the API)
+ */
+export const tierOutputSchema = z.object({
+  id: ghostIdSchema,
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().nullable().optional(),
+  active: z.boolean(),
+  type: z.enum(['free', 'paid']),
+  welcome_page_url: z.string().url().nullable().optional(),
+  visibility: z.enum(['public', 'none']),
+  trial_days: z.number(),
+  currency: z.string().nullable().optional(),
+  monthly_price: z.number().nullable().optional(),
+  yearly_price: z.number().nullable().optional(),
+  monthly_price_id: z.string().nullable().optional(),
+  yearly_price_id: z.string().nullable().optional(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  benefits: z.array(benefitOutputSchema).optional(),
+  monthly_price_object: monthlyPriceOutputSchema.nullable().optional(),
+  yearly_price_object: yearlyPriceOutputSchema.nullable().optional(),
+});
+
+/**
+ * Schema for array of tiers
+ */
+export const tiersArraySchema = z.array(tierOutputSchema);
+
+/**
+ * Schema for paginated tier response
+ */
+export const tiersPaginatedSchema = z.object({
+  tiers: tiersArraySchema,
+  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(),
+    }),
+  }),
+});

package/src/services/ghostServiceImproved.js

@@ -173,6 +173,27 @@ const validators = {
     }
   },
 
+  validateTagUpdateData(updateData) {
+    const errors = [];
+
+    // Name is optional in updates, but if provided, it cannot be empty
+    if (updateData.name !== undefined && updateData.name.trim().length === 0) {
+      errors.push({ field: 'name', message: 'Tag name cannot be empty' });
+    }
+
+    // Validate slug format if provided
+    if (updateData.slug && !/^[a-z0-9-]+$/.test(updateData.slug)) {
+      errors.push({
+        field: 'slug',
+        message: 'Slug must contain only lowercase letters, numbers, and hyphens',
+      });
+    }
+
+    if (errors.length > 0) {
+      throw new ValidationError('Tag update validation failed', errors);
+    }
+  },
+
   async validateImagePath(imagePath) {
     if (!imagePath || typeof imagePath !== 'string') {
       throw new ValidationError('Image path is required and must be a string');
@@ -693,13 +714,13 @@ export async function getTags(name) {
   }
 }
 
-export async function getTag(tagId) {
+export async function getTag(tagId, options = {}) {
   if (!tagId) {
     throw new ValidationError('Tag ID is required');
   }
 
   try {
-    return await handleApiRequest('tags', 'read', { id: tagId });
+    return await handleApiRequest('tags', 'read', { id: tagId }, options);
   } catch (error) {
     if (error instanceof GhostAPIError && error.ghostStatusCode === 404) {
       throw new NotFoundError('Tag', tagId);
@@ -713,7 +734,7 @@ export async function updateTag(tagId, updateData) {
     throw new ValidationError('Tag ID is required for update');
   }
 
-  validators.validateTagData({ name: 'dummy', ...updateData }); // Validate update data
+  validators.validateTagUpdateData(updateData); // Validate update data
 
   try {
     const existingTag = await getTag(tagId);