@jgardner04/ghost-mcp-server 1.4.0 → 1.5.0

package/README.md

@@ -1,10 +1,15 @@
 # Ghost MCP Server
 
+[![npm version](https://badge.fury.io/js/%40jgardner04%2Fghost-mcp-server.svg)](https://badge.fury.io/js/%40jgardner04%2Fghost-mcp-server)
+[![CI](https://github.com/jgardner04/Ghost-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/jgardner04/Ghost-MCP-Server/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](https://github.com/jgardner04/Ghost-MCP-Server)
+
 This project (`ghost-mcp-server`) implements a **Model Context Protocol (MCP) Server** that allows an MCP client (like Cursor or Claude Desktop) to interact with a Ghost CMS instance via defined tools.
 
 ## Requirements
 
-- Node.js 14.0.0 or higher
+- Node.js 18.0.0 or higher
 - Ghost Admin API URL and Key
 
 ## Ghost MCP Server Details
@@ -62,13 +67,70 @@ Below is a guide for using the available MCP tools:
       - `meta_description` (string, optional): Custom SEO description.
     - **Output**: The created `ghost/post` resource.
 
-## Installation and Running
+## Installation
+
+### NPM Installation (Recommended)
+
+Install globally using npm:
+
+```bash
+npm install -g @jgardner04/ghost-mcp-server
+```
+
+Or use npx to run without installing:
+
+```bash
+npx @jgardner04/ghost-mcp-server
+```
+
+### Available Commands
+
+After installation, the following CLI commands are available:
+
+- **`ghost-mcp-server`**: Starts the Express REST API server and MCP server (default)
+- **`ghost-mcp`**: Starts the improved MCP server with transport configuration support
+
+### Configuration
+
+Before running the server, configure your Ghost Admin API credentials:
+
+1. Create a `.env` file in your working directory:
+
+   ```dotenv
+   # Required:
+   GHOST_ADMIN_API_URL=https://your-ghost-site.com
+   GHOST_ADMIN_API_KEY=your_admin_api_key
+   ```
+
+2. Find your Ghost Admin API URL and Key in your Ghost Admin settings under Integrations -> Custom Integrations.
+
+### Running the Server
+
+After installation and configuration:
+
+```bash
+# Using the global installation
+ghost-mcp-server
+
+# Or using npx
+npx @jgardner04/ghost-mcp-server
+
+# Run the MCP server with transport options
+ghost-mcp
+
+# Or with specific transport
+MCP_TRANSPORT=stdio ghost-mcp
+```
+
+## Development Setup
+
+For contributors or advanced users who want to modify the source code:
 
 1.  **Clone the Repository**:
 
     ```bash
-    git clone <repository_url>
-    cd ghost-mcp-server
+    git clone https://github.com/jgardner04/Ghost-MCP-Server.git
+    cd Ghost-MCP-Server
     ```
 
 2.  **Install Dependencies**:
@@ -78,20 +140,9 @@ Below is a guide for using the available MCP tools:
     ```
 
 3.  **Configure Environment Variables**:
-    Create a `.env` file in the project root and add your Ghost Admin API credentials:
-
-    ```dotenv
-    # Required:
-    GHOST_ADMIN_API_URL=https://your-ghost-site.com
-    GHOST_ADMIN_API_KEY=your_admin_api_key
-
-    # If using 1Password CLI for secrets:
-    # You might store the API key in 1Password and use `op run --env-file=.env -- ...`
-    ```
-
-    - Find your Ghost Admin API URL and Key in your Ghost Admin settings under Integrations -> Custom Integrations.
+    Create a `.env` file in the project root (see Configuration section above).
 
-4.  **Run the Server**:
+4.  **Run from Source**:
 
     ```bash
     npm start
@@ -99,8 +150,6 @@ Below is a guide for using the available MCP tools:
     # node src/index.js
     ```
 
-    This command will start the MCP server.
-
 5.  **Development Mode (using nodemon)**:
     For development with automatic restarting:
     ```bash
@@ -112,4 +161,5 @@ Below is a guide for using the available MCP tools:
 - **401 Unauthorized Error from Ghost:** Check that your `GHOST_ADMIN_API_URL` and `GHOST_ADMIN_API_KEY` in the `.env` file are correct and that the Custom Integration in Ghost is enabled.
 - **MCP Server Connection Issues:** Ensure the MCP server is running (check console logs). Verify the port (`MCP_PORT`, default 3001) is not blocked by a firewall. Check that the client is connecting to the correct address and port.
 - **Tool Execution Errors:** Check the server console logs for detailed error messages from the specific tool implementation (e.g., `ghost_create_post`, `ghost_upload_image`). Common issues include invalid input (check against tool schemas in `src/mcp_server.js` and the README guide), problems downloading from `imageUrl`, image processing failures, or upstream errors from the Ghost API.
-- **Dependency Installation Issues:** Ensure you have a compatible Node.js version installed (see Requirements section). Try removing `node_modules` and `package-lock.json` and running `npm install` again.
+- **Command Not Found:** If `ghost-mcp-server` or `ghost-mcp` commands are not found after global installation, ensure npm's global bin directory is in your PATH. You can find it with `npm bin -g`.
+- **Dependency Installation Issues:** Ensure you have a compatible Node.js version installed (Node.js 18.0.0 or higher - see Requirements section). For global installation issues, try `npm install -g @jgardner04/ghost-mcp-server --force`. For development setup, try removing `node_modules` and `package-lock.json` and running `npm install` again.

package/package.json

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

package/src/__tests__/mcp_server_pages.test.js

@@ -0,0 +1,520 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock the McpServer to capture tool registrations
+const mockTools = new Map();
+
+vi.mock('@modelcontextprotocol/sdk/server/mcp.js', () => {
+  return {
+    McpServer: class MockMcpServer {
+      constructor(config) {
+        this.config = config;
+      }
+
+      tool(name, description, schema, handler) {
+        mockTools.set(name, { name, description, schema, handler });
+      }
+
+      connect(_transport) {
+        return Promise.resolve();
+      }
+    },
+  };
+});
+
+vi.mock('@modelcontextprotocol/sdk/server/stdio.js', () => {
+  return {
+    StdioServerTransport: class MockStdioServerTransport {},
+  };
+});
+
+// Mock dotenv
+vi.mock('dotenv', () => ({
+  default: { config: vi.fn() },
+}));
+
+// Mock crypto
+vi.mock('crypto', () => ({
+  default: { randomUUID: vi.fn().mockReturnValue('test-uuid-1234') },
+}));
+
+// Mock services for pages
+const mockGetPages = vi.fn();
+const mockGetPage = vi.fn();
+const mockUpdatePage = vi.fn();
+const mockDeletePage = vi.fn();
+const mockSearchPages = vi.fn();
+const mockCreatePageService = vi.fn();
+
+// Also mock post and tag services to avoid errors
+const mockGetPosts = vi.fn();
+const mockGetPost = vi.fn();
+const mockGetTags = vi.fn();
+const mockCreateTag = vi.fn();
+const mockUploadImage = vi.fn();
+const mockCreatePostService = vi.fn();
+const mockUpdatePost = vi.fn();
+const mockDeletePost = vi.fn();
+const mockSearchPosts = vi.fn();
+const mockProcessImage = vi.fn();
+const mockValidateImageUrl = vi.fn();
+const mockCreateSecureAxiosConfig = vi.fn();
+
+vi.mock('../services/ghostService.js', () => ({
+  getPosts: (...args) => mockGetPosts(...args),
+  getPost: (...args) => mockGetPost(...args),
+  getTags: (...args) => mockGetTags(...args),
+  createTag: (...args) => mockCreateTag(...args),
+  uploadImage: (...args) => mockUploadImage(...args),
+}));
+
+vi.mock('../services/postService.js', () => ({
+  createPostService: (...args) => mockCreatePostService(...args),
+}));
+
+vi.mock('../services/pageService.js', () => ({
+  createPageService: (...args) => mockCreatePageService(...args),
+}));
+
+vi.mock('../services/ghostServiceImproved.js', () => ({
+  updatePost: (...args) => mockUpdatePost(...args),
+  deletePost: (...args) => mockDeletePost(...args),
+  searchPosts: (...args) => mockSearchPosts(...args),
+  getPages: (...args) => mockGetPages(...args),
+  getPage: (...args) => mockGetPage(...args),
+  updatePage: (...args) => mockUpdatePage(...args),
+  deletePage: (...args) => mockDeletePage(...args),
+  searchPages: (...args) => mockSearchPages(...args),
+}));
+
+vi.mock('../services/imageProcessingService.js', () => ({
+  processImage: (...args) => mockProcessImage(...args),
+}));
+
+vi.mock('../utils/urlValidator.js', () => ({
+  validateImageUrl: (...args) => mockValidateImageUrl(...args),
+  createSecureAxiosConfig: (...args) => mockCreateSecureAxiosConfig(...args),
+}));
+
+// Mock axios
+const mockAxios = vi.fn();
+vi.mock('axios', () => ({
+  default: (...args) => mockAxios(...args),
+}));
+
+// Mock fs
+const mockUnlink = vi.fn((path, cb) => cb(null));
+const mockCreateWriteStream = vi.fn();
+vi.mock('fs', () => ({
+  default: {
+    unlink: (...args) => mockUnlink(...args),
+    createWriteStream: (...args) => mockCreateWriteStream(...args),
+  },
+}));
+
+// Mock os
+vi.mock('os', () => ({
+  default: { tmpdir: vi.fn().mockReturnValue('/tmp') },
+}));
+
+// Mock path
+vi.mock('path', async () => {
+  const actual = await vi.importActual('path');
+  return {
+    default: actual,
+    ...actual,
+  };
+});
+
+describe('mcp_server_improved - ghost_get_pages tool', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    // Import the module to register tools (only first time)
+    if (mockTools.size === 0) {
+      await import('../mcp_server_improved.js');
+    }
+  });
+
+  it('should register ghost_get_pages tool', () => {
+    expect(mockTools.has('ghost_get_pages')).toBe(true);
+  });
+
+  it('should have correct schema with all optional parameters', () => {
+    const tool = mockTools.get('ghost_get_pages');
+    expect(tool).toBeDefined();
+    expect(tool.description).toContain('pages');
+    expect(tool.schema).toBeDefined();
+    expect(tool.schema.limit).toBeDefined();
+    expect(tool.schema.page).toBeDefined();
+    expect(tool.schema.status).toBeDefined();
+    expect(tool.schema.include).toBeDefined();
+    expect(tool.schema.filter).toBeDefined();
+    expect(tool.schema.order).toBeDefined();
+  });
+
+  it('should retrieve pages with default options', async () => {
+    const mockPages = [
+      { id: '1', title: 'About Us', slug: 'about-us', status: 'published' },
+      { id: '2', title: 'Contact', slug: 'contact', status: 'draft' },
+    ];
+    mockGetPages.mockResolvedValue(mockPages);
+
+    const tool = mockTools.get('ghost_get_pages');
+    const result = await tool.handler({});
+
+    expect(mockGetPages).toHaveBeenCalledWith({});
+    expect(result.content[0].text).toContain('About Us');
+    expect(result.content[0].text).toContain('Contact');
+  });
+
+  it('should pass limit and page parameters', async () => {
+    const mockPages = [{ id: '1', title: 'Page 1', slug: 'page-1' }];
+    mockGetPages.mockResolvedValue(mockPages);
+
+    const tool = mockTools.get('ghost_get_pages');
+    await tool.handler({ limit: 10, page: 2 });
+
+    expect(mockGetPages).toHaveBeenCalledWith({ limit: 10, page: 2 });
+  });
+
+  it('should validate limit is between 1 and 100', () => {
+    const tool = mockTools.get('ghost_get_pages');
+    const schema = tool.schema;
+
+    expect(schema.limit).toBeDefined();
+    expect(() => schema.limit.parse(0)).toThrow();
+    expect(() => schema.limit.parse(101)).toThrow();
+    expect(schema.limit.parse(50)).toBe(50);
+  });
+
+  it('should pass status filter', async () => {
+    const mockPages = [{ id: '1', title: 'Published Page', status: 'published' }];
+    mockGetPages.mockResolvedValue(mockPages);
+
+    const tool = mockTools.get('ghost_get_pages');
+    await tool.handler({ status: 'published' });
+
+    expect(mockGetPages).toHaveBeenCalledWith({ status: 'published' });
+  });
+
+  it('should handle errors gracefully', async () => {
+    mockGetPages.mockRejectedValue(new Error('API error'));
+
+    const tool = mockTools.get('ghost_get_pages');
+    const result = await tool.handler({});
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Error retrieving pages');
+  });
+});
+
+describe('mcp_server_improved - ghost_get_page tool', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    if (mockTools.size === 0) {
+      await import('../mcp_server_improved.js');
+    }
+  });
+
+  it('should register ghost_get_page tool', () => {
+    expect(mockTools.has('ghost_get_page')).toBe(true);
+  });
+
+  it('should have correct schema with id and slug options', () => {
+    const tool = mockTools.get('ghost_get_page');
+    expect(tool).toBeDefined();
+    expect(tool.schema.id).toBeDefined();
+    expect(tool.schema.slug).toBeDefined();
+    expect(tool.schema.include).toBeDefined();
+  });
+
+  it('should retrieve page by ID', async () => {
+    const mockPage = { id: 'page-123', title: 'About Us', slug: 'about-us' };
+    mockGetPage.mockResolvedValue(mockPage);
+
+    const tool = mockTools.get('ghost_get_page');
+    const result = await tool.handler({ id: 'page-123' });
+
+    expect(mockGetPage).toHaveBeenCalledWith('page-123', {});
+    expect(result.content[0].text).toContain('About Us');
+  });
+
+  it('should retrieve page by slug', async () => {
+    const mockPage = { id: 'page-123', title: 'About Us', slug: 'about-us' };
+    mockGetPage.mockResolvedValue(mockPage);
+
+    const tool = mockTools.get('ghost_get_page');
+    const result = await tool.handler({ slug: 'about-us' });
+
+    expect(mockGetPage).toHaveBeenCalledWith('slug/about-us', {});
+    expect(result.content[0].text).toContain('About Us');
+  });
+
+  it('should require either id or slug', async () => {
+    const tool = mockTools.get('ghost_get_page');
+    const result = await tool.handler({});
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Either id or slug is required');
+  });
+
+  it('should handle errors gracefully', async () => {
+    mockGetPage.mockRejectedValue(new Error('Page not found'));
+
+    const tool = mockTools.get('ghost_get_page');
+    const result = await tool.handler({ id: 'nonexistent' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Error retrieving page');
+  });
+});
+
+describe('mcp_server_improved - ghost_create_page tool', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    if (mockTools.size === 0) {
+      await import('../mcp_server_improved.js');
+    }
+  });
+
+  it('should register ghost_create_page tool', () => {
+    expect(mockTools.has('ghost_create_page')).toBe(true);
+  });
+
+  it('should have correct schema with required and optional fields', () => {
+    const tool = mockTools.get('ghost_create_page');
+    expect(tool).toBeDefined();
+    expect(tool.description).toContain('NOT support tags');
+    expect(tool.schema.title).toBeDefined();
+    expect(tool.schema.html).toBeDefined();
+    expect(tool.schema.status).toBeDefined();
+    expect(tool.schema.feature_image).toBeDefined();
+    expect(tool.schema.meta_title).toBeDefined();
+    expect(tool.schema.meta_description).toBeDefined();
+    // Should NOT have tags
+    expect(tool.schema.tags).toBeUndefined();
+  });
+
+  it('should create page with minimal input', async () => {
+    const createdPage = { id: 'page-123', title: 'New Page', status: 'draft' };
+    mockCreatePageService.mockResolvedValue(createdPage);
+
+    const tool = mockTools.get('ghost_create_page');
+    const result = await tool.handler({ title: 'New Page', html: '<p>Content</p>' });
+
+    expect(mockCreatePageService).toHaveBeenCalledWith({
+      title: 'New Page',
+      html: '<p>Content</p>',
+    });
+    expect(result.content[0].text).toContain('New Page');
+  });
+
+  it('should create page with all optional fields', async () => {
+    const fullInput = {
+      title: 'Complete Page',
+      html: '<p>Content</p>',
+      status: 'published',
+      custom_excerpt: 'Excerpt',
+      feature_image: 'https://example.com/image.jpg',
+      feature_image_alt: 'Alt text',
+      feature_image_caption: 'Caption',
+      meta_title: 'SEO Title',
+      meta_description: 'SEO Description',
+    };
+    const createdPage = { id: 'page-123', ...fullInput };
+    mockCreatePageService.mockResolvedValue(createdPage);
+
+    const tool = mockTools.get('ghost_create_page');
+    const result = await tool.handler(fullInput);
+
+    expect(mockCreatePageService).toHaveBeenCalledWith(fullInput);
+    expect(result.content[0].text).toContain('Complete Page');
+  });
+
+  it('should handle errors gracefully', async () => {
+    mockCreatePageService.mockRejectedValue(new Error('Invalid input'));
+
+    const tool = mockTools.get('ghost_create_page');
+    const result = await tool.handler({ title: 'Test', html: '<p>Content</p>' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Error creating page');
+  });
+});
+
+describe('mcp_server_improved - ghost_update_page tool', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    if (mockTools.size === 0) {
+      await import('../mcp_server_improved.js');
+    }
+  });
+
+  it('should register ghost_update_page tool', () => {
+    expect(mockTools.has('ghost_update_page')).toBe(true);
+  });
+
+  it('should have correct schema with id required and other fields optional', () => {
+    const tool = mockTools.get('ghost_update_page');
+    expect(tool).toBeDefined();
+    expect(tool.description).toContain('NOT support tags');
+    expect(tool.schema.id).toBeDefined();
+    expect(tool.schema.title).toBeDefined();
+    expect(tool.schema.html).toBeDefined();
+    expect(tool.schema.status).toBeDefined();
+    // Should NOT have tags
+    expect(tool.schema.tags).toBeUndefined();
+  });
+
+  it('should update page with new title', async () => {
+    const updatedPage = { id: 'page-123', title: 'Updated Title' };
+    mockUpdatePage.mockResolvedValue(updatedPage);
+
+    const tool = mockTools.get('ghost_update_page');
+    const result = await tool.handler({ id: 'page-123', title: 'Updated Title' });
+
+    expect(mockUpdatePage).toHaveBeenCalledWith('page-123', { title: 'Updated Title' });
+    expect(result.content[0].text).toContain('Updated Title');
+  });
+
+  it('should update page with multiple fields', async () => {
+    const updatedPage = { id: 'page-123', title: 'New Title', status: 'published' };
+    mockUpdatePage.mockResolvedValue(updatedPage);
+
+    const tool = mockTools.get('ghost_update_page');
+    const result = await tool.handler({
+      id: 'page-123',
+      title: 'New Title',
+      status: 'published',
+      html: '<p>Updated content</p>',
+    });
+
+    expect(mockUpdatePage).toHaveBeenCalledWith('page-123', {
+      title: 'New Title',
+      status: 'published',
+      html: '<p>Updated content</p>',
+    });
+    expect(result.content[0].text).toContain('New Title');
+  });
+
+  it('should handle errors gracefully', async () => {
+    mockUpdatePage.mockRejectedValue(new Error('Page not found'));
+
+    const tool = mockTools.get('ghost_update_page');
+    const result = await tool.handler({ id: 'nonexistent', title: 'Test' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Error updating page');
+  });
+});
+
+describe('mcp_server_improved - ghost_delete_page tool', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    if (mockTools.size === 0) {
+      await import('../mcp_server_improved.js');
+    }
+  });
+
+  it('should register ghost_delete_page tool', () => {
+    expect(mockTools.has('ghost_delete_page')).toBe(true);
+  });
+
+  it('should have correct schema with id required', () => {
+    const tool = mockTools.get('ghost_delete_page');
+    expect(tool).toBeDefined();
+    expect(tool.schema.id).toBeDefined();
+    expect(tool.description).toContain('permanent');
+  });
+
+  it('should delete page by ID', async () => {
+    mockDeletePage.mockResolvedValue({ id: 'page-123' });
+
+    const tool = mockTools.get('ghost_delete_page');
+    const result = await tool.handler({ id: 'page-123' });
+
+    expect(mockDeletePage).toHaveBeenCalledWith('page-123');
+    expect(result.content[0].text).toContain('successfully deleted');
+  });
+
+  it('should handle errors gracefully', async () => {
+    mockDeletePage.mockRejectedValue(new Error('Page not found'));
+
+    const tool = mockTools.get('ghost_delete_page');
+    const result = await tool.handler({ id: 'nonexistent' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Error deleting page');
+  });
+});
+
+describe('mcp_server_improved - ghost_search_pages tool', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    if (mockTools.size === 0) {
+      await import('../mcp_server_improved.js');
+    }
+  });
+
+  it('should register ghost_search_pages tool', () => {
+    expect(mockTools.has('ghost_search_pages')).toBe(true);
+  });
+
+  it('should have correct schema with query required', () => {
+    const tool = mockTools.get('ghost_search_pages');
+    expect(tool).toBeDefined();
+    expect(tool.schema.query).toBeDefined();
+    expect(tool.schema.status).toBeDefined();
+    expect(tool.schema.limit).toBeDefined();
+  });
+
+  it('should search pages with query', async () => {
+    const mockPages = [{ id: '1', title: 'About Us', slug: 'about-us' }];
+    mockSearchPages.mockResolvedValue(mockPages);
+
+    const tool = mockTools.get('ghost_search_pages');
+    const result = await tool.handler({ query: 'about' });
+
+    expect(mockSearchPages).toHaveBeenCalledWith('about', {});
+    expect(result.content[0].text).toContain('About Us');
+  });
+
+  it('should pass status filter', async () => {
+    const mockPages = [{ id: '1', title: 'Published Page' }];
+    mockSearchPages.mockResolvedValue(mockPages);
+
+    const tool = mockTools.get('ghost_search_pages');
+    await tool.handler({ query: 'test', status: 'published' });
+
+    expect(mockSearchPages).toHaveBeenCalledWith('test', { status: 'published' });
+  });
+
+  it('should pass limit option', async () => {
+    const mockPages = [];
+    mockSearchPages.mockResolvedValue(mockPages);
+
+    const tool = mockTools.get('ghost_search_pages');
+    await tool.handler({ query: 'test', limit: 5 });
+
+    expect(mockSearchPages).toHaveBeenCalledWith('test', { limit: 5 });
+  });
+
+  it('should validate limit is between 1 and 50', () => {
+    const tool = mockTools.get('ghost_search_pages');
+    const schema = tool.schema;
+
+    expect(schema.limit).toBeDefined();
+    expect(() => schema.limit.parse(0)).toThrow();
+    expect(() => schema.limit.parse(51)).toThrow();
+    expect(schema.limit.parse(25)).toBe(25);
+  });
+
+  it('should handle errors gracefully', async () => {
+    mockSearchPages.mockRejectedValue(new Error('Search failed'));
+
+    const tool = mockTools.get('ghost_search_pages');
+    const result = await tool.handler({ query: 'test' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Error searching pages');
+  });
+});