@jgardner04/ghost-mcp-server 1.9.0 → 1.11.0

package/package.json

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

package/src/mcp_server_improved.js

@@ -1019,6 +1019,125 @@ server.tool(
   }
 );
 
+// Get Members Tool
+server.tool(
+  'ghost_get_members',
+  'Retrieves a list of members (subscribers) from Ghost CMS with optional filtering, pagination, and includes.',
+  {
+    limit: z
+      .number()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe('Number of members to retrieve (1-100). Default is 15.'),
+    page: z.number().min(1).optional().describe('Page number for pagination (starts at 1).'),
+    filter: z
+      .string()
+      .optional()
+      .describe('Ghost NQL filter string (e.g., "status:free", "status:paid", "subscribed:true").'),
+    order: z.string().optional().describe('Order string (e.g., "created_at desc", "email asc").'),
+    include: z
+      .string()
+      .optional()
+      .describe('Comma-separated list of related data to include (e.g., "labels,newsletters").'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_get_members`);
+    try {
+      await loadServices();
+
+      const options = {};
+      if (input.limit !== undefined) options.limit = input.limit;
+      if (input.page !== undefined) options.page = input.page;
+      if (input.filter !== undefined) options.filter = input.filter;
+      if (input.order !== undefined) options.order = input.order;
+      if (input.include !== undefined) options.include = input.include;
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const members = await ghostServiceImproved.getMembers(options);
+      console.error(`Retrieved ${members.length} members from Ghost.`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(members, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_members:`, error);
+      return {
+        content: [{ type: 'text', text: `Error retrieving members: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Get Member Tool
+server.tool(
+  'ghost_get_member',
+  'Retrieves a single member from Ghost CMS by ID or email. Provide either id OR email.',
+  {
+    id: z.string().optional().describe('The ID of the member to retrieve.'),
+    email: z.string().email().optional().describe('The email of the member to retrieve.'),
+  },
+  async ({ id, email }) => {
+    console.error(`Executing tool: ghost_get_member for ${id ? `ID: ${id}` : `email: ${email}`}`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const member = await ghostServiceImproved.getMember({ id, email });
+      console.error(`Retrieved member: ${member.email} (ID: ${member.id})`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(member, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_member:`, error);
+      return {
+        content: [{ type: 'text', text: `Error retrieving member: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Search Members Tool
+server.tool(
+  'ghost_search_members',
+  'Searches for members by name or email in Ghost CMS.',
+  {
+    query: z.string().min(1).describe('Search query to match against member name or email.'),
+    limit: z
+      .number()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe('Maximum number of results to return (1-50). Default is 15.'),
+  },
+  async ({ query, limit }) => {
+    console.error(`Executing tool: ghost_search_members with query: ${query}`);
+    try {
+      await loadServices();
+
+      const options = {};
+      if (limit !== undefined) options.limit = limit;
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const members = await ghostServiceImproved.searchMembers(query, options);
+      console.error(`Found ${members.length} members matching "${query}".`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(members, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_search_members:`, error);
+      return {
+        content: [{ type: 'text', text: `Error searching members: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
 // =============================================================================
 // NEWSLETTER TOOLS
 // =============================================================================
@@ -1211,6 +1330,184 @@ server.tool(
   }
 );
 
+// --- Tier Tools ---
+
+// Get Tiers Tool
+server.tool(
+  'ghost_get_tiers',
+  'Retrieves a list of tiers (membership levels) from Ghost CMS with optional filtering by type (free/paid).',
+  {
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .optional()
+      .describe('Number of tiers to return (1-100, default 15)'),
+    filter: z.string().optional().describe('NQL filter string (e.g., "type:paid" or "type:free")'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_get_tiers`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const tiers = await ghostServiceImproved.getTiers(input);
+      console.error(`Retrieved ${tiers.length} tiers`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(tiers, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_tiers:`, error);
+      return {
+        content: [{ type: 'text', text: `Error getting tiers: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Get Tier Tool
+server.tool(
+  'ghost_get_tier',
+  'Retrieves a single tier (membership level) from Ghost CMS by ID.',
+  {
+    id: z.string().describe('The ID of the tier to retrieve.'),
+  },
+  async ({ id }) => {
+    console.error(`Executing tool: ghost_get_tier for tier ID: ${id}`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const tier = await ghostServiceImproved.getTier(id);
+      console.error(`Tier retrieved successfully. Tier ID: ${tier.id}`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(tier, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_get_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error getting tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Create Tier Tool
+server.tool(
+  'ghost_create_tier',
+  'Creates a new tier (membership level) in Ghost CMS with pricing and benefits.',
+  {
+    name: z.string().describe('Tier name (required)'),
+    description: z.string().optional().describe('Tier description'),
+    monthly_price: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('Monthly price in cents (e.g., 500 = $5.00)'),
+    yearly_price: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('Yearly price in cents (e.g., 5000 = $50.00)'),
+    currency: z.string().length(3).optional().describe('Currency code (e.g., "USD", "EUR")'),
+    benefits: z.array(z.string()).optional().describe('Array of benefit descriptions'),
+    welcome_page_url: z.string().url().optional().describe('Welcome page URL for new subscribers'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_create_tier`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const tier = await ghostServiceImproved.createTier(input);
+      console.error(`Tier created successfully. Tier ID: ${tier.id}`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(tier, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_create_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error creating tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Update Tier Tool
+server.tool(
+  'ghost_update_tier',
+  'Updates an existing tier (membership level) in Ghost CMS. Can update pricing, benefits, and other tier properties.',
+  {
+    id: z.string().describe('The ID of the tier to update (required)'),
+    name: z.string().optional().describe('Updated tier name'),
+    description: z.string().optional().describe('Updated description'),
+    monthly_price: z.number().int().min(0).optional().describe('Updated monthly price in cents'),
+    yearly_price: z.number().int().min(0).optional().describe('Updated yearly price in cents'),
+    currency: z.string().length(3).optional().describe('Updated currency code'),
+    benefits: z.array(z.string()).optional().describe('Updated array of benefit descriptions'),
+  },
+  async (input) => {
+    console.error(`Executing tool: ghost_update_tier for tier ID: ${input.id}`);
+    try {
+      await loadServices();
+
+      const { id, ...updateData } = input;
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      const updatedTier = await ghostServiceImproved.updateTier(id, updateData);
+      console.error(`Tier updated successfully. Tier ID: ${updatedTier.id}`);
+
+      return {
+        content: [{ type: 'text', text: JSON.stringify(updatedTier, null, 2) }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_update_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error updating tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
+// Delete Tier Tool
+server.tool(
+  'ghost_delete_tier',
+  'Deletes a tier (membership level) from Ghost CMS by ID. This operation is permanent and cannot be undone.',
+  {
+    id: z.string().describe('The ID of the tier to delete.'),
+  },
+  async ({ id }) => {
+    console.error(`Executing tool: ghost_delete_tier for tier ID: ${id}`);
+    try {
+      await loadServices();
+
+      const ghostServiceImproved = await import('./services/ghostServiceImproved.js');
+      await ghostServiceImproved.deleteTier(id);
+      console.error(`Tier deleted successfully. Tier ID: ${id}`);
+
+      return {
+        content: [{ type: 'text', text: `Tier ${id} has been successfully deleted.` }],
+      };
+    } catch (error) {
+      console.error(`Error in ghost_delete_tier:`, error);
+      return {
+        content: [{ type: 'text', text: `Error deleting tier: ${error.message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+
 // --- Main Entry Point ---
 
 async function main() {
@@ -1224,8 +1521,9 @@ async function main() {
     'Available tools: ghost_get_tags, ghost_create_tag, ghost_get_tag, ghost_update_tag, ghost_delete_tag, ghost_upload_image, ' +
       'ghost_create_post, ghost_get_posts, ghost_get_post, ghost_search_posts, ghost_update_post, ghost_delete_post, ' +
       'ghost_get_pages, ghost_get_page, ghost_create_page, ghost_update_page, ghost_delete_page, ghost_search_pages, ' +
-      'ghost_create_member, ghost_update_member, ghost_delete_member, ' +
-      'ghost_get_newsletters, ghost_get_newsletter, ghost_create_newsletter, ghost_update_newsletter, ghost_delete_newsletter'
+      'ghost_create_member, ghost_update_member, ghost_delete_member, ghost_get_members, ghost_get_member, ghost_search_members, ' +
+      'ghost_get_newsletters, ghost_get_newsletter, ghost_create_newsletter, ghost_update_newsletter, ghost_delete_newsletter, ' +
+      'ghost_get_tiers, ghost_get_tier, ghost_create_tier, ghost_update_tier, ghost_delete_tier'
   );
 }
 

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

@@ -60,7 +60,15 @@ vi.mock('fs/promises', () => ({
 }));
 
 // Import after setting up mocks
-import { createMember, updateMember, deleteMember, api } from '../ghostServiceImproved.js';
+import {
+  createMember,
+  updateMember,
+  deleteMember,
+  getMembers,
+  getMember,
+  searchMembers,
+  api,
+} from '../ghostServiceImproved.js';
 
 describe('ghostServiceImproved - Members', () => {
   beforeEach(() => {
@@ -258,4 +266,283 @@ describe('ghostServiceImproved - Members', () => {
       await expect(deleteMember('non-existent')).rejects.toThrow();
     });
   });
+
+  describe('getMembers', () => {
+    it('should return all members with default options', async () => {
+      const mockMembers = [
+        { id: 'member-1', email: 'test1@example.com', status: 'free' },
+        { id: 'member-2', email: 'test2@example.com', status: 'paid' },
+      ];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      const result = await getMembers();
+
+      expect(api.members.browse).toHaveBeenCalled();
+      expect(result).toEqual(mockMembers);
+    });
+
+    it('should accept pagination options', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'test1@example.com' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ limit: 50, page: 2 });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 50,
+          page: 2,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept filter options', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'test1@example.com', status: 'paid' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ filter: 'status:paid' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: 'status:paid',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept order options', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'test1@example.com' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ order: 'created_at desc' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          order: 'created_at desc',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept include options', async () => {
+      const mockMembers = [
+        { id: 'member-1', email: 'test1@example.com', labels: [], newsletters: [] },
+      ];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await getMembers({ include: 'labels,newsletters' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          include: 'labels,newsletters',
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should throw validation error for invalid limit', async () => {
+      await expect(getMembers({ limit: 0 })).rejects.toThrow('Member query validation failed');
+      await expect(getMembers({ limit: 101 })).rejects.toThrow('Member query validation failed');
+    });
+
+    it('should throw validation error for invalid page', async () => {
+      await expect(getMembers({ page: 0 })).rejects.toThrow('Member query validation failed');
+    });
+
+    it('should return empty array when no members found', async () => {
+      api.members.browse.mockResolvedValue([]);
+
+      const result = await getMembers();
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle Ghost API errors', async () => {
+      api.members.browse.mockRejectedValue(new Error('Ghost API Error'));
+
+      await expect(getMembers()).rejects.toThrow();
+    });
+  });
+
+  describe('getMember', () => {
+    it('should get member by ID', async () => {
+      const mockMember = {
+        id: 'member-1',
+        email: 'test@example.com',
+        name: 'John Doe',
+        status: 'free',
+      };
+
+      api.members.read.mockResolvedValue(mockMember);
+
+      const result = await getMember({ id: 'member-1' });
+
+      expect(api.members.read).toHaveBeenCalledWith(expect.any(Object), { id: 'member-1' });
+      expect(result).toEqual(mockMember);
+    });
+
+    it('should get member by email', async () => {
+      const mockMember = {
+        id: 'member-1',
+        email: 'test@example.com',
+        name: 'John Doe',
+        status: 'free',
+      };
+
+      api.members.browse.mockResolvedValue([mockMember]);
+
+      const result = await getMember({ email: 'test@example.com' });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: expect.stringContaining('test@example.com'),
+        }),
+        expect.any(Object)
+      );
+      expect(result).toEqual(mockMember);
+    });
+
+    it('should throw validation error when neither id nor email provided', async () => {
+      await expect(getMember({})).rejects.toThrow('Member lookup validation failed');
+    });
+
+    it('should throw validation error for invalid email format', async () => {
+      await expect(getMember({ email: 'invalid-email' })).rejects.toThrow(
+        'Member lookup validation failed'
+      );
+    });
+
+    it('should throw not found error when member not found by ID', async () => {
+      api.members.read.mockRejectedValue({
+        response: { status: 404 },
+        message: 'Member not found',
+      });
+
+      await expect(getMember({ id: 'non-existent' })).rejects.toThrow();
+    });
+
+    it('should throw not found error when member not found by email', async () => {
+      api.members.browse.mockResolvedValue([]);
+
+      await expect(getMember({ email: 'notfound@example.com' })).rejects.toThrow(
+        'Member not found'
+      );
+    });
+
+    it('should prioritize ID over email when both provided', async () => {
+      const mockMember = {
+        id: 'member-1',
+        email: 'test@example.com',
+        status: 'free',
+      };
+
+      api.members.read.mockResolvedValue(mockMember);
+
+      await getMember({ id: 'member-1', email: 'test@example.com' });
+
+      // Should use read (ID) instead of browse (email)
+      expect(api.members.read).toHaveBeenCalled();
+      expect(api.members.browse).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('searchMembers', () => {
+    it('should search members by query', async () => {
+      const mockMembers = [{ id: 'member-1', email: 'john@example.com', name: 'John Doe' }];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      const result = await searchMembers('john');
+
+      expect(api.members.browse).toHaveBeenCalled();
+      expect(result).toEqual(mockMembers);
+    });
+
+    it('should apply default limit of 15', async () => {
+      const mockMembers = [];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await searchMembers('test');
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 15,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept custom limit', async () => {
+      const mockMembers = [];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      await searchMembers('test', { limit: 25 });
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          limit: 25,
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should throw validation error for empty query', async () => {
+      await expect(searchMembers('')).rejects.toThrow('Search query validation failed');
+      await expect(searchMembers('   ')).rejects.toThrow('Search query validation failed');
+    });
+
+    it('should throw validation error for non-string query', async () => {
+      await expect(searchMembers(123)).rejects.toThrow('Search query validation failed');
+      await expect(searchMembers(null)).rejects.toThrow('Search query validation failed');
+    });
+
+    it('should throw validation error for invalid limit', async () => {
+      await expect(searchMembers('test', { limit: 0 })).rejects.toThrow(
+        'Search options validation failed'
+      );
+      await expect(searchMembers('test', { limit: 51 })).rejects.toThrow(
+        'Search options validation failed'
+      );
+      await expect(searchMembers('test', { limit: 100 })).rejects.toThrow(
+        'Search options validation failed'
+      );
+    });
+
+    it('should sanitize query to prevent NQL injection', async () => {
+      const mockMembers = [];
+
+      api.members.browse.mockResolvedValue(mockMembers);
+
+      // Query with special NQL characters
+      await searchMembers("test'value");
+
+      expect(api.members.browse).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filter: expect.stringContaining("\\'"),
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should return empty array when no matches found', async () => {
+      api.members.browse.mockResolvedValue([]);
+
+      const result = await searchMembers('nonexistent');
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle Ghost API errors', async () => {
+      api.members.browse.mockRejectedValue(new Error('Ghost API Error'));
+
+      await expect(searchMembers('test')).rejects.toThrow();
+    });
+  });
 });