@jgardner04/ghost-mcp-server 1.12.5 → 1.13.1

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

@@ -172,6 +172,106 @@ describe('Tag Schemas', () => {
       expect(result).toBeDefined();
       // Note: optional fields with defaults don't apply when field is omitted
     });
+
+    it('should accept limit as "all" string', () => {
+      const query = {
+        limit: 'all',
+      };
+
+      const result = tagQuerySchema.parse(query);
+      expect(result.limit).toBe('all');
+    });
+
+    it('should accept limit as number within range', () => {
+      const query = {
+        limit: 50,
+      };
+
+      const result = tagQuerySchema.parse(query);
+      expect(result.limit).toBe(50);
+    });
+
+    it('should reject limit as invalid string', () => {
+      const query = {
+        limit: 'invalid',
+      };
+
+      expect(() => tagQuerySchema.parse(query)).toThrow();
+    });
+
+    it('should reject limit greater than 100', () => {
+      const query = {
+        limit: 101,
+      };
+
+      expect(() => tagQuerySchema.parse(query)).toThrow();
+    });
+
+    it('should reject limit less than 1', () => {
+      const query = {
+        limit: 0,
+      };
+
+      expect(() => tagQuerySchema.parse(query)).toThrow();
+    });
+
+    it('should accept limit as string number and transform to number', () => {
+      const query = {
+        limit: '50',
+      };
+
+      const result = tagQuerySchema.parse(query);
+      expect(result.limit).toBe(50);
+      expect(typeof result.limit).toBe('number');
+    });
+
+    it('should accept page as string number and transform to number', () => {
+      const query = {
+        page: '3',
+      };
+
+      const result = tagQuerySchema.parse(query);
+      expect(result.page).toBe(3);
+      expect(typeof result.page).toBe('number');
+    });
+
+    it('should reject query with both name and filter parameters', () => {
+      const query = {
+        name: 'Technology',
+        filter: 'visibility:public',
+      };
+
+      expect(() => tagQuerySchema.parse(query)).toThrow();
+      try {
+        tagQuerySchema.parse(query);
+      } catch (error) {
+        expect(error.errors[0].message).toContain('Cannot specify both "name" and "filter"');
+      }
+    });
+
+    it('should reject name with invalid characters', () => {
+      const query = {
+        name: 'test;DROP',
+      };
+
+      expect(() => tagQuerySchema.parse(query)).toThrow(/invalid characters/);
+    });
+
+    it('should accept name with apostrophe', () => {
+      const query = {
+        name: "O'Reilly",
+      };
+
+      expect(() => tagQuerySchema.parse(query)).not.toThrow();
+    });
+
+    it('should accept name with spaces, hyphens, and underscores', () => {
+      const query = {
+        name: 'Tech News 2024-Web_Dev',
+      };
+
+      expect(() => tagQuerySchema.parse(query)).not.toThrow();
+    });
   });
 
   describe('tagIdSchema', () => {

package/src/schemas/tagSchemas.js

@@ -57,14 +57,33 @@ export const createTagSchema = z.object({
 export const updateTagSchema = createTagSchema.partial();
 
 /**
- * Schema for tag query/filter parameters
+ * Base schema for tag query/filter parameters (without refinement)
+ * Exported for use in MCP server where .partial() is needed
  */
-export const tagQuerySchema = z.object({
-  name: z.string().optional().describe('Filter by exact tag name'),
+export const tagQueryBaseSchema = z.object({
+  name: z
+    .string()
+    .regex(
+      /^[a-zA-Z0-9\s\-_']+$/,
+      'Tag name contains invalid characters. Only letters, numbers, spaces, hyphens, underscores, and apostrophes are allowed'
+    )
+    .optional()
+    .describe('Filter by exact tag name (legacy parameter, converted to filter internally)'),
   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(),
+  limit: z
+    .union([
+      z.number().int().min(1).max(100),
+      z.string().regex(/^\d+$/).transform(Number),
+      z.literal('all'),
+    ])
+    .default(15)
+    .optional()
+    .describe('Number of tags to return (1-100) or "all" for all tags'),
+  page: z
+    .union([z.number().int().min(1), z.string().regex(/^\d+$/).transform(Number)])
+    .default(1)
+    .optional(),
   filter: z
     .string()
     .regex(/^[a-zA-Z0-9_\-:.'"\s,[\]<>=!+]+$/, 'Invalid filter: contains disallowed characters')
@@ -77,6 +96,15 @@ export const tagQuerySchema = z.object({
   order: z.string().optional().describe('Order results (e.g., "name ASC", "created_at DESC")'),
 });
 
+/**
+ * Schema for tag query/filter parameters with validation
+ * Note: Only one of 'name' or 'filter' should be provided, not both
+ */
+export const tagQuerySchema = tagQueryBaseSchema.refine((data) => !(data.name && data.filter), {
+  message: 'Cannot specify both "name" and "filter" parameters. Use "filter" for advanced queries.',
+  path: ['filter'],
+});
+
 /**
  * Schema for tag ID parameter
  */

package/src/services/__tests__/ghostService.test.js

@@ -276,24 +276,7 @@ describe('ghostService', () => {
   });
 
   describe('getTags', () => {
-    it('should reject tag names with invalid characters', async () => {
-      await expect(getTags("'; DROP TABLE tags; --")).rejects.toThrow(
-        'Tag name contains invalid characters'
-      );
-    });
-
-    it('should accept valid tag names', async () => {
-      const validNames = ['Test Tag', 'test-tag', 'test_tag', 'Tag123'];
-      const expectedTags = [{ id: '1', name: 'Tag' }];
-      api.tags.browse.mockResolvedValue(expectedTags);
-
-      for (const name of validNames) {
-        const result = await getTags(name);
-        expect(result).toEqual(expectedTags);
-      }
-    });
-
-    it('should handle tags without filter when name is not provided', async () => {
+    it('should get all tags when no options provided', async () => {
       const expectedTags = [
         { id: '1', name: 'Tag1' },
         { id: '2', name: 'Tag2' },
@@ -303,17 +286,41 @@ describe('ghostService', () => {
       const result = await getTags();
 
       expect(result).toEqual(expectedTags);
-      expect(api.tags.browse).toHaveBeenCalledWith({ limit: 'all' }, {});
+      expect(api.tags.browse).toHaveBeenCalledWith({ limit: 15 }, {});
     });
 
-    it('should properly escape tag names in filter', async () => {
-      const expectedTags = [{ id: '1', name: "Tag's Name" }];
+    it('should pass options to browse endpoint', async () => {
+      const expectedTags = [{ id: '1', name: 'Tag' }];
       api.tags.browse.mockResolvedValue(expectedTags);
 
-      // This should work because we properly escape single quotes
-      const result = await getTags('Valid Tag');
+      const result = await getTags({ limit: 5, filter: "name:'Test'" });
 
       expect(result).toEqual(expectedTags);
+      expect(api.tags.browse).toHaveBeenCalledWith({ limit: 5, filter: "name:'Test'" }, {});
+    });
+
+    it('should return empty array on null response', async () => {
+      api.tags.browse.mockResolvedValue(null);
+
+      const result = await getTags();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle errors and rethrow', async () => {
+      const error = new Error('API error');
+      api.tags.browse.mockRejectedValue(error);
+
+      await expect(getTags()).rejects.toThrow('API error');
+    });
+
+    it('should merge default limit with custom options', async () => {
+      const expectedTags = [{ id: '1', name: 'Tag' }];
+      api.tags.browse.mockResolvedValue(expectedTags);
+
+      await getTags({ filter: "name:'Custom'" });
+
+      expect(api.tags.browse).toHaveBeenCalledWith({ limit: 15, filter: "name:'Custom'" }, {});
     });
   });
 });

package/src/services/__tests__/ghostServiceImproved.tags.test.js

@@ -0,0 +1,475 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createMockContextLogger } from '../../__tests__/helpers/mockLogger.js';
+import { mockDotenv } from '../../__tests__/helpers/testUtils.js';
+
+// Mock the Ghost Admin API with tags support
+vi.mock('@tryghost/admin-api', () => ({
+  default: vi.fn(function () {
+    return {
+      posts: {
+        add: vi.fn(),
+        browse: vi.fn(),
+        read: vi.fn(),
+        edit: vi.fn(),
+        delete: vi.fn(),
+      },
+      pages: {
+        add: vi.fn(),
+        browse: vi.fn(),
+        read: vi.fn(),
+        edit: vi.fn(),
+        delete: vi.fn(),
+      },
+      tags: {
+        add: vi.fn(),
+        browse: vi.fn(),
+        read: vi.fn(),
+        edit: vi.fn(),
+        delete: vi.fn(),
+      },
+      members: {
+        add: vi.fn(),
+        browse: vi.fn(),
+        read: vi.fn(),
+        edit: vi.fn(),
+        delete: vi.fn(),
+      },
+      site: {
+        read: vi.fn(),
+      },
+      images: {
+        upload: vi.fn(),
+      },
+    };
+  }),
+}));
+
+// Mock dotenv
+vi.mock('dotenv', () => mockDotenv());
+
+// Mock logger
+vi.mock('../../utils/logger.js', () => ({
+  createContextLogger: createMockContextLogger(),
+}));
+
+// Mock fs for validateImagePath
+vi.mock('fs/promises', () => ({
+  default: {
+    access: vi.fn(),
+  },
+}));
+
+// Import after setting up mocks
+import {
+  getTags,
+  getTag,
+  createTag,
+  updateTag,
+  deleteTag,
+  api,
+  ghostCircuitBreaker,
+} from '../ghostServiceImproved.js';
+
+describe('ghostServiceImproved - Tags', () => {
+  beforeEach(() => {
+    // Reset all mocks before each test
+    vi.clearAllMocks();
+
+    // Reset circuit breaker to closed state
+    if (ghostCircuitBreaker) {
+      ghostCircuitBreaker.state = 'CLOSED';
+      ghostCircuitBreaker.failureCount = 0;
+      ghostCircuitBreaker.lastFailureTime = null;
+      ghostCircuitBreaker.nextAttempt = null;
+    }
+  });
+
+  describe('getTags', () => {
+    it('should return all tags with default options', async () => {
+      const mockTags = [
+        { id: 'tag-1', name: 'JavaScript', slug: 'javascript' },
+        { id: 'tag-2', name: 'TypeScript', slug: 'typescript' },
+      ];
+
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      const result = await getTags();
+
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 15,
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockTags);
+    });
+
+    it('should accept custom limit option', async () => {
+      const mockTags = [{ id: 'tag-1', name: 'JavaScript', slug: 'javascript' }];
+
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      await getTags({ limit: 50 });
+
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 50,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept pagination options (page)', async () => {
+      const mockTags = [{ id: 'tag-1', name: 'JavaScript', slug: 'javascript' }];
+
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      await getTags({ limit: 20, page: 2 });
+
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 20,
+          page: 2,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept filter options', async () => {
+      const mockTags = [{ id: 'tag-1', name: 'JavaScript', slug: 'javascript' }];
+
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      await getTags({ filter: "name:'JavaScript'" });
+
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 15,
+          filter: "name:'JavaScript'",
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept order options', async () => {
+      const mockTags = [
+        { id: 'tag-1', name: 'JavaScript', slug: 'javascript' },
+        { id: 'tag-2', name: 'TypeScript', slug: 'typescript' },
+      ];
+
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      await getTags({ order: 'name asc' });
+
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 15,
+          order: 'name asc',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept include options', async () => {
+      const mockTags = [
+        { id: 'tag-1', name: 'JavaScript', slug: 'javascript', count: { posts: 10 } },
+      ];
+
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      await getTags({ include: 'count.posts' });
+
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 15,
+          include: 'count.posts',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept multiple options together', async () => {
+      const mockTags = [{ id: 'tag-1', name: 'JavaScript', slug: 'javascript' }];
+
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      await getTags({
+        limit: 25,
+        page: 3,
+        filter: 'visibility:public',
+        order: 'slug desc',
+        include: 'count.posts',
+      });
+
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 25,
+          page: 3,
+          filter: 'visibility:public',
+          order: 'slug desc',
+          include: 'count.posts',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should return empty array when no tags found', async () => {
+      api.tags.browse.mockResolvedValue([]);
+
+      const result = await getTags();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array when API returns null', async () => {
+      api.tags.browse.mockResolvedValue(null);
+
+      const result = await getTags();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle Ghost API errors', async () => {
+      const apiError = new Error('Ghost API Error');
+      api.tags.browse.mockRejectedValue(apiError);
+
+      // Errors are wrapped by handleApiRequest with "External service error: Ghost API"
+      await expect(getTags()).rejects.toThrow(/External service error: Ghost API/);
+    });
+
+    it('should handle network errors with retry logic', async () => {
+      const networkError = new Error('Network timeout');
+      api.tags.browse.mockRejectedValue(networkError);
+
+      // Network errors are wrapped by handleApiRequest
+      await expect(getTags()).rejects.toThrow(/External service error: Ghost API/);
+    });
+
+    it('should reject requests when circuit breaker is open', async () => {
+      // Force circuit breaker to open state
+      ghostCircuitBreaker.state = 'OPEN';
+      ghostCircuitBreaker.nextAttempt = Date.now() + 60000;
+
+      await expect(getTags()).rejects.toThrow(/circuit.*open/i);
+    });
+
+    it('should succeed when circuit breaker is closed', async () => {
+      const mockTags = [{ id: 'tag-1', name: 'JavaScript', slug: 'javascript' }];
+
+      // Ensure circuit breaker is closed
+      ghostCircuitBreaker.state = 'CLOSED';
+      api.tags.browse.mockResolvedValue(mockTags);
+
+      const result = await getTags();
+
+      expect(result).toEqual(mockTags);
+      expect(api.tags.browse).toHaveBeenCalled();
+    });
+  });
+
+  describe('getTag', () => {
+    it('should get tag by ID', async () => {
+      const mockTag = {
+        id: 'tag-1',
+        name: 'JavaScript',
+        slug: 'javascript',
+      };
+
+      api.tags.read.mockResolvedValue(mockTag);
+
+      const result = await getTag('tag-1');
+
+      expect(api.tags.read).toHaveBeenCalledWith(expect.any(Object), expect.objectContaining({}));
+      expect(result).toEqual(mockTag);
+    });
+
+    it('should throw validation error for missing tag ID', async () => {
+      await expect(getTag(null)).rejects.toThrow('Tag ID is required');
+    });
+
+    it('should throw not found error when tag does not exist', async () => {
+      api.tags.read.mockRejectedValue({
+        response: { status: 404 },
+        message: 'Tag not found',
+      });
+
+      await expect(getTag('non-existent')).rejects.toThrow();
+    });
+  });
+
+  describe('createTag', () => {
+    it('should create a tag with required name', async () => {
+      const tagData = {
+        name: 'JavaScript',
+      };
+
+      const mockCreatedTag = {
+        id: 'tag-1',
+        name: 'JavaScript',
+        slug: 'javascript',
+      };
+
+      api.tags.add.mockResolvedValue(mockCreatedTag);
+
+      const result = await createTag(tagData);
+
+      expect(api.tags.add).toHaveBeenCalled();
+      expect(result).toEqual(mockCreatedTag);
+    });
+
+    it('should throw validation error for missing tag name', async () => {
+      await expect(createTag({})).rejects.toThrow('Tag validation failed');
+    });
+
+    it('should throw validation error for empty tag name', async () => {
+      await expect(createTag({ name: '   ' })).rejects.toThrow('Tag validation failed');
+    });
+
+    it('should throw validation error for invalid slug format', async () => {
+      await expect(createTag({ name: 'Test', slug: 'INVALID_SLUG!' })).rejects.toThrow(
+        'Tag validation failed'
+      );
+    });
+
+    it('should accept valid slug with lowercase letters, numbers, and hyphens', async () => {
+      const tagData = {
+        name: 'Test Tag',
+        slug: 'valid-slug-123',
+      };
+
+      const mockCreatedTag = {
+        id: 'tag-1',
+        name: 'Test Tag',
+        slug: 'valid-slug-123',
+      };
+
+      api.tags.add.mockResolvedValue(mockCreatedTag);
+
+      const result = await createTag(tagData);
+
+      expect(result).toEqual(mockCreatedTag);
+    });
+
+    it('should auto-generate slug if not provided', async () => {
+      const tagData = {
+        name: 'JavaScript & TypeScript',
+      };
+
+      const mockCreatedTag = {
+        id: 'tag-1',
+        name: 'JavaScript & TypeScript',
+        slug: 'javascript-typescript',
+      };
+
+      api.tags.add.mockResolvedValue(mockCreatedTag);
+
+      await createTag(tagData);
+
+      // Verify that slug is auto-generated
+      expect(api.tags.add).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'JavaScript & TypeScript',
+          slug: expect.stringMatching(/javascript-typescript/),
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should handle duplicate tag errors gracefully', async () => {
+      const tagData = {
+        name: 'JavaScript',
+      };
+
+      // First call fails with duplicate error
+      api.tags.add.mockRejectedValue({
+        response: { status: 422 },
+        message: 'Tag already exists',
+      });
+
+      // getTags returns existing tag when called with name filter
+      api.tags.browse.mockResolvedValue([{ id: 'tag-1', name: 'JavaScript', slug: 'javascript' }]);
+
+      const result = await createTag(tagData);
+
+      // Verify getTags was called with correct filter for duplicate lookup
+      expect(api.tags.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: "name:'JavaScript'",
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual({ id: 'tag-1', name: 'JavaScript', slug: 'javascript' });
+    });
+  });
+
+  describe('updateTag', () => {
+    it('should update tag with valid ID and data', async () => {
+      const tagId = 'tag-1';
+      const updateData = {
+        name: 'Updated JavaScript',
+        description: 'Updated description',
+      };
+
+      const mockExistingTag = {
+        id: tagId,
+        name: 'JavaScript',
+        slug: 'javascript',
+      };
+
+      const mockUpdatedTag = {
+        ...mockExistingTag,
+        ...updateData,
+      };
+
+      api.tags.read.mockResolvedValue(mockExistingTag);
+      api.tags.edit.mockResolvedValue(mockUpdatedTag);
+
+      const result = await updateTag(tagId, updateData);
+
+      expect(api.tags.read).toHaveBeenCalled();
+      expect(api.tags.edit).toHaveBeenCalled();
+      expect(result).toEqual(mockUpdatedTag);
+    });
+
+    it('should throw validation error for missing tag ID', async () => {
+      await expect(updateTag(null, { name: 'Test' })).rejects.toThrow(
+        'Tag ID is required for update'
+      );
+    });
+
+    it('should throw not found error if tag does not exist', async () => {
+      api.tags.read.mockRejectedValue({
+        response: { status: 404 },
+        message: 'Tag not found',
+      });
+
+      await expect(updateTag('non-existent', { name: 'Test' })).rejects.toThrow();
+    });
+  });
+
+  describe('deleteTag', () => {
+    it('should delete tag with valid ID', async () => {
+      const tagId = 'tag-1';
+
+      api.tags.delete.mockResolvedValue({ deleted: true });
+
+      const result = await deleteTag(tagId);
+
+      expect(api.tags.delete).toHaveBeenCalledWith(tagId, expect.any(Object));
+      expect(result).toEqual({ deleted: true });
+    });
+
+    it('should throw validation error for missing tag ID', async () => {
+      await expect(deleteTag(null)).rejects.toThrow('Tag ID is required for deletion');
+    });
+
+    it('should throw not found error if tag does not exist', async () => {
+      api.tags.delete.mockRejectedValue({
+        response: { status: 404 },
+        message: 'Tag not found',
+      });
+
+      await expect(deleteTag('non-existent')).rejects.toThrow();
+    });
+  });
+});