@jgardner04/ghost-mcp-server 1.7.0 → 1.9.0

package/src/schemas/newsletterSchemas.js

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+import { ghostIdSchema, emailSchema, slugSchema } from './common.js';
+
+/**
+ * Newsletter Schemas for Ghost CMS
+ * Provides input/output validation for newsletter operations
+ */
+
+// ----- Input Schemas -----
+
+/**
+ * Schema for creating a new newsletter
+ * Required: name
+ * Optional: description, sender details, design options, etc.
+ */
+export const createNewsletterSchema = 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(),
+  sender_name: z.string().max(191, 'Sender name cannot exceed 191 characters').optional(),
+  sender_email: emailSchema.optional(),
+  sender_reply_to: z
+    .enum(['newsletter', 'support'], {
+      errorMap: () => ({ message: 'Sender reply-to must be newsletter or support' }),
+    })
+    .default('newsletter'),
+  status: z
+    .enum(['active', 'archived'], {
+      errorMap: () => ({ message: 'Status must be active or archived' }),
+    })
+    .default('active'),
+  visibility: z
+    .enum(['members', 'paid'], {
+      errorMap: () => ({ message: 'Visibility must be members or paid' }),
+    })
+    .default('members'),
+  subscribe_on_signup: z
+    .boolean()
+    .default(true)
+    .describe('Whether new members are automatically subscribed'),
+  sort_order: z
+    .number()
+    .int()
+    .min(0, 'Sort order must be non-negative')
+    .optional()
+    .describe('Display order for newsletters'),
+  header_image: z.string().url('Invalid header image URL').optional(),
+  show_header_icon: z.boolean().default(true),
+  show_header_title: z.boolean().default(true),
+  title_font_category: z
+    .enum(['serif', 'sans-serif'], {
+      errorMap: () => ({ message: 'Title font category must be serif or sans-serif' }),
+    })
+    .default('sans-serif'),
+  title_alignment: z
+    .enum(['left', 'center'], {
+      errorMap: () => ({ message: 'Title alignment must be left or center' }),
+    })
+    .default('center'),
+  show_feature_image: z.boolean().default(true),
+  body_font_category: z
+    .enum(['serif', 'sans-serif'], {
+      errorMap: () => ({ message: 'Body font category must be serif or sans-serif' }),
+    })
+    .default('sans-serif'),
+  footer_content: z.string().optional(),
+  show_badge: z.boolean().default(true),
+  show_header_name: z.boolean().default(true).optional(),
+  show_post_title_section: z.boolean().default(true).optional(),
+});
+
+/**
+ * Schema for updating an existing newsletter
+ * All fields optional
+ */
+export const updateNewsletterSchema = createNewsletterSchema.partial();
+
+/**
+ * Schema for newsletter query/filter parameters
+ */
+export const newsletterQuerySchema = 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:active")'),
+  order: z
+    .string()
+    .optional()
+    .describe('Order results (e.g., "sort_order ASC", "created_at DESC")'),
+});
+
+/**
+ * Schema for newsletter ID parameter
+ */
+export const newsletterIdSchema = z.object({
+  id: ghostIdSchema,
+});
+
+/**
+ * Schema for newsletter slug parameter
+ */
+export const newsletterSlugSchema = z.object({
+  slug: slugSchema,
+});
+
+// ----- Output Schemas -----
+
+/**
+ * Schema for a Ghost newsletter object (as returned by the API)
+ */
+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']),
+  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(),
+  show_header_name: z.boolean().optional(),
+  show_post_title_section: z.boolean().optional(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  count: z
+    .object({
+      members: z.number().optional(),
+      posts: z.number().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * Schema for array of newsletters
+ */
+export const newslettersArraySchema = z.array(newsletterOutputSchema);
+
+/**
+ * Schema for paginated newsletter response
+ */
+export const newslettersPaginatedSchema = z.object({
+  newsletters: newslettersArraySchema,
+  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/pageSchemas.js

@@ -0,0 +1,215 @@
+import { z } from 'zod';
+import {
+  ghostIdSchema,
+  slugSchema,
+  titleSchema,
+  htmlContentSchema,
+  excerptSchema,
+  metaTitleSchema,
+  metaDescriptionSchema,
+  canonicalUrlSchema,
+  featureImageSchema,
+  featureImageAltSchema,
+  featuredSchema,
+  postStatusSchema,
+  visibilitySchema,
+  authorsSchema,
+  tagsSchema,
+  customExcerptSchema,
+  ogImageSchema,
+  twitterImageSchema,
+  isoDateSchema,
+} from './common.js';
+
+/**
+ * Page Schemas for Ghost CMS
+ * Pages are similar to posts but represent static content (About, Contact, etc.)
+ * Provides input/output validation for page operations
+ */
+
+// ----- Input Schemas -----
+
+/**
+ * Schema for creating a new page
+ * Required: title, html
+ * Optional: various metadata, feature image, authors, tags, etc.
+ * Note: Pages typically don't have tags, but Ghost API supports them
+ */
+export const createPageSchema = z.object({
+  title: titleSchema,
+  html: htmlContentSchema.describe('HTML content of the page'),
+  slug: slugSchema.optional(),
+  status: postStatusSchema.default('draft'),
+  visibility: visibilitySchema.default('public'),
+  featured: featuredSchema,
+  feature_image: featureImageSchema,
+  feature_image_alt: featureImageAltSchema,
+  feature_image_caption: z.string().max(500, 'Caption cannot exceed 500 characters').optional(),
+  excerpt: excerptSchema,
+  custom_excerpt: customExcerptSchema,
+  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(),
+  canonical_url: canonicalUrlSchema,
+  tags: tagsSchema.describe('Array of tag names or IDs (rarely used for pages)'),
+  authors: authorsSchema.describe('Array of author IDs or emails'),
+  published_at: isoDateSchema.optional().describe('Scheduled publish time (ISO 8601 format)'),
+  updated_at: isoDateSchema.optional(),
+  created_at: isoDateSchema.optional(),
+  codeinjection_head: z.string().optional(),
+  codeinjection_foot: z.string().optional(),
+  custom_template: z.string().optional().describe('Custom template filename'),
+  show_title_and_feature_image: z
+    .boolean()
+    .default(true)
+    .describe('Whether to show title and feature image on page'),
+});
+
+/**
+ * Schema for updating an existing page
+ * All fields optional
+ */
+export const updatePageSchema = createPageSchema.partial();
+
+/**
+ * Schema for page query/filter parameters
+ */
+export const pageQuerySchema = 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:published+featured:true")'),
+  include: z
+    .string()
+    .optional()
+    .describe('Comma-separated list of relations (e.g., "tags,authors")'),
+  fields: z.string().optional().describe('Comma-separated list of fields to return'),
+  formats: z
+    .string()
+    .optional()
+    .describe('Comma-separated list of formats (html, plaintext, mobiledoc)'),
+  order: z.string().optional().describe('Order results (e.g., "published_at DESC", "title ASC")'),
+});
+
+/**
+ * Schema for page ID parameter
+ */
+export const pageIdSchema = z.object({
+  id: ghostIdSchema,
+});
+
+/**
+ * Schema for page slug parameter
+ */
+export const pageSlugSchema = z.object({
+  slug: slugSchema,
+});
+
+// ----- Output Schemas -----
+
+/**
+ * Schema for an author object (nested in page)
+ * Reusing from postSchemas would be better, but duplicated here for independence
+ */
+export const authorOutputSchema = z.object({
+  id: ghostIdSchema,
+  name: z.string(),
+  slug: z.string(),
+  email: z.string().email().optional(),
+  profile_image: z.string().url().nullable().optional(),
+  cover_image: z.string().url().nullable().optional(),
+  bio: z.string().nullable().optional(),
+  website: z.string().url().nullable().optional(),
+  location: z.string().nullable().optional(),
+  facebook: z.string().nullable().optional(),
+  twitter: z.string().nullable().optional(),
+  url: z.string().url(),
+});
+
+/**
+ * Schema for a tag object (nested in page)
+ */
+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,
+  url: z.string().url(),
+});
+
+/**
+ * Schema for a Ghost page object (as returned by the API)
+ */
+export const pageOutputSchema = z.object({
+  id: ghostIdSchema,
+  uuid: z.string().uuid(),
+  title: z.string(),
+  slug: z.string(),
+  html: z.string().nullable().optional(),
+  comment_id: z.string().nullable().optional(),
+  feature_image: z.string().url().nullable().optional(),
+  feature_image_alt: z.string().nullable().optional(),
+  feature_image_caption: z.string().nullable().optional(),
+  featured: z.boolean(),
+  status: postStatusSchema,
+  visibility: visibilitySchema,
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  published_at: z.string().datetime().nullable().optional(),
+  custom_excerpt: z.string().nullable().optional(),
+  codeinjection_head: z.string().nullable().optional(),
+  codeinjection_foot: z.string().nullable().optional(),
+  custom_template: z.string().nullable().optional(),
+  canonical_url: z.string().url().nullable().optional(),
+  url: z.string().url(),
+  excerpt: z.string().nullable().optional(),
+  reading_time: z.number().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(),
+  meta_title: z.string().nullable().optional(),
+  meta_description: z.string().nullable().optional(),
+  show_title_and_feature_image: z.boolean().optional(),
+  authors: z.array(authorOutputSchema).optional(),
+  tags: z.array(tagOutputSchema).optional(),
+  primary_author: authorOutputSchema.nullable().optional(),
+  primary_tag: tagOutputSchema.nullable().optional(),
+});
+
+/**
+ * Schema for array of pages
+ */
+export const pagesArraySchema = z.array(pageOutputSchema);
+
+/**
+ * Schema for paginated page response
+ */
+export const pagesPaginatedSchema = z.object({
+  pages: pagesArraySchema,
+  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/postSchemas.js

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+import {
+  ghostIdSchema,
+  slugSchema,
+  titleSchema,
+  htmlContentSchema,
+  excerptSchema,
+  metaTitleSchema,
+  metaDescriptionSchema,
+  canonicalUrlSchema,
+  featureImageSchema,
+  featureImageAltSchema,
+  featuredSchema,
+  postStatusSchema,
+  visibilitySchema,
+  authorsSchema,
+  tagsSchema,
+  customExcerptSchema,
+  ogImageSchema,
+  twitterImageSchema,
+  isoDateSchema,
+} from './common.js';
+
+/**
+ * Post Schemas for Ghost CMS
+ * Provides input/output validation for post operations
+ */
+
+// ----- Input Schemas -----
+
+/**
+ * Schema for creating a new post
+ * Required: title, html
+ * Optional: various metadata, feature image, authors, tags, etc.
+ */
+export const createPostSchema = z.object({
+  title: titleSchema,
+  html: htmlContentSchema.describe('HTML content of the post'),
+  slug: slugSchema.optional(),
+  status: postStatusSchema.default('draft'),
+  visibility: visibilitySchema.default('public'),
+  featured: featuredSchema,
+  feature_image: featureImageSchema,
+  feature_image_alt: featureImageAltSchema,
+  feature_image_caption: z.string().max(500, 'Caption cannot exceed 500 characters').optional(),
+  excerpt: excerptSchema,
+  custom_excerpt: customExcerptSchema,
+  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(),
+  canonical_url: canonicalUrlSchema,
+  tags: tagsSchema.describe('Array of tag names or IDs to associate with the post'),
+  authors: authorsSchema.describe('Array of author IDs or emails'),
+  published_at: isoDateSchema.optional().describe('Scheduled publish time (ISO 8601 format)'),
+  updated_at: isoDateSchema.optional(),
+  created_at: isoDateSchema.optional(),
+  codeinjection_head: z.string().optional(),
+  codeinjection_foot: z.string().optional(),
+  custom_template: z.string().optional().describe('Custom template filename'),
+  email_only: z.boolean().default(false).describe('Whether post is email-only'),
+});
+
+/**
+ * Schema for updating an existing post
+ * All fields optional
+ */
+export const updatePostSchema = createPostSchema.partial();
+
+/**
+ * Schema for post query/filter parameters
+ */
+export const postQuerySchema = 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:published+featured:true")'),
+  include: z
+    .string()
+    .optional()
+    .describe('Comma-separated list of relations (e.g., "tags,authors")'),
+  fields: z.string().optional().describe('Comma-separated list of fields to return'),
+  formats: z
+    .string()
+    .optional()
+    .describe('Comma-separated list of formats (html, plaintext, mobiledoc)'),
+  order: z.string().optional().describe('Order results (e.g., "published_at DESC", "title ASC")'),
+});
+
+/**
+ * Schema for post ID parameter
+ */
+export const postIdSchema = z.object({
+  id: ghostIdSchema,
+});
+
+/**
+ * Schema for post slug parameter
+ */
+export const postSlugSchema = z.object({
+  slug: slugSchema,
+});
+
+// ----- Output Schemas -----
+
+/**
+ * Schema for an author object (nested in post)
+ */
+export const authorOutputSchema = z.object({
+  id: ghostIdSchema,
+  name: z.string(),
+  slug: z.string(),
+  email: z.string().email().optional(),
+  profile_image: z.string().url().nullable().optional(),
+  cover_image: z.string().url().nullable().optional(),
+  bio: z.string().nullable().optional(),
+  website: z.string().url().nullable().optional(),
+  location: z.string().nullable().optional(),
+  facebook: z.string().nullable().optional(),
+  twitter: z.string().nullable().optional(),
+  url: z.string().url(),
+});
+
+/**
+ * Schema for a tag object (nested in post)
+ */
+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,
+  url: z.string().url(),
+});
+
+/**
+ * Schema for a Ghost post object (as returned by the API)
+ */
+export const postOutputSchema = z.object({
+  id: ghostIdSchema,
+  uuid: z.string().uuid(),
+  title: z.string(),
+  slug: z.string(),
+  html: z.string().nullable().optional(),
+  comment_id: z.string().nullable().optional(),
+  feature_image: z.string().url().nullable().optional(),
+  feature_image_alt: z.string().nullable().optional(),
+  feature_image_caption: z.string().nullable().optional(),
+  featured: z.boolean(),
+  status: postStatusSchema,
+  visibility: visibilitySchema,
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  published_at: z.string().datetime().nullable().optional(),
+  custom_excerpt: z.string().nullable().optional(),
+  codeinjection_head: z.string().nullable().optional(),
+  codeinjection_foot: z.string().nullable().optional(),
+  custom_template: z.string().nullable().optional(),
+  canonical_url: z.string().url().nullable().optional(),
+  url: z.string().url(),
+  excerpt: z.string().nullable().optional(),
+  reading_time: z.number().nullable().optional(),
+  email_only: z.boolean().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(),
+  meta_title: z.string().nullable().optional(),
+  meta_description: z.string().nullable().optional(),
+  email_subject: z.string().nullable().optional(),
+  authors: z.array(authorOutputSchema).optional(),
+  tags: z.array(tagOutputSchema).optional(),
+  primary_author: authorOutputSchema.nullable().optional(),
+  primary_tag: tagOutputSchema.nullable().optional(),
+});
+
+/**
+ * Schema for array of posts
+ */
+export const postsArraySchema = z.array(postOutputSchema);
+
+/**
+ * Schema for paginated post response
+ */
+export const postsPaginatedSchema = z.object({
+  posts: postsArraySchema,
+  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(),
+    }),
+  }),
+});