@jgardner04/ghost-mcp-server 1.3.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.3.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_improved.test.js

@@ -49,6 +49,7 @@ const mockValidateImageUrl = vi.fn();
 const mockCreateSecureAxiosConfig = vi.fn();
 const mockUpdatePost = vi.fn();
 const mockDeletePost = vi.fn();
+const mockSearchPosts = vi.fn();
 
 vi.mock('../services/ghostService.js', () => ({
   getPosts: (...args) => mockGetPosts(...args),
@@ -65,6 +66,7 @@ vi.mock('../services/postService.js', () => ({
 vi.mock('../services/ghostServiceImproved.js', () => ({
   updatePost: (...args) => mockUpdatePost(...args),
   deletePost: (...args) => mockDeletePost(...args),
+  searchPosts: (...args) => mockSearchPosts(...args),
 }));
 
 vi.mock('../services/imageProcessingService.js', () => ({
@@ -754,3 +756,154 @@ describe('mcp_server_improved - ghost_delete_post tool', () => {
     expect(result.content[0].text).toContain('Network error');
   });
 });
+
+describe('mcp_server_improved - ghost_search_posts tool', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    // Don't clear mockTools - they're registered once on module load
+    if (mockTools.size === 0) {
+      await import('../mcp_server_improved.js');
+    }
+  });
+
+  it('should register ghost_search_posts tool', () => {
+    expect(mockTools.has('ghost_search_posts')).toBe(true);
+  });
+
+  it('should have correct schema with required query and optional parameters', () => {
+    const tool = mockTools.get('ghost_search_posts');
+    expect(tool).toBeDefined();
+    expect(tool.description).toContain('Search');
+    expect(tool.schema).toBeDefined();
+    expect(tool.schema.query).toBeDefined();
+    expect(tool.schema.status).toBeDefined();
+    expect(tool.schema.limit).toBeDefined();
+  });
+
+  it('should search posts with query only', async () => {
+    const mockPosts = [
+      { id: '1', title: 'JavaScript Tips', slug: 'javascript-tips', status: 'published' },
+      { id: '2', title: 'JavaScript Tricks', slug: 'javascript-tricks', status: 'published' },
+    ];
+    mockSearchPosts.mockResolvedValue(mockPosts);
+
+    const tool = mockTools.get('ghost_search_posts');
+    const result = await tool.handler({ query: 'JavaScript' });
+
+    expect(mockSearchPosts).toHaveBeenCalledWith('JavaScript', {});
+    expect(result.content[0].text).toContain('JavaScript Tips');
+    expect(result.content[0].text).toContain('JavaScript Tricks');
+  });
+
+  it('should search posts with query and status filter', async () => {
+    const mockPosts = [
+      { id: '1', title: 'Published Post', slug: 'published-post', status: 'published' },
+    ];
+    mockSearchPosts.mockResolvedValue(mockPosts);
+
+    const tool = mockTools.get('ghost_search_posts');
+    await tool.handler({ query: 'test', status: 'published' });
+
+    expect(mockSearchPosts).toHaveBeenCalledWith('test', { status: 'published' });
+  });
+
+  it('should search posts with query and limit', async () => {
+    const mockPosts = [{ id: '1', title: 'Test Post', slug: 'test-post' }];
+    mockSearchPosts.mockResolvedValue(mockPosts);
+
+    const tool = mockTools.get('ghost_search_posts');
+    await tool.handler({ query: 'test', limit: 10 });
+
+    expect(mockSearchPosts).toHaveBeenCalledWith('test', { limit: 10 });
+  });
+
+  it('should validate limit is between 1 and 50', () => {
+    const tool = mockTools.get('ghost_search_posts');
+    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 validate status enum values', () => {
+    const tool = mockTools.get('ghost_search_posts');
+    const schema = tool.schema;
+
+    expect(schema.status).toBeDefined();
+    expect(() => schema.status.parse('invalid')).toThrow();
+    expect(schema.status.parse('published')).toBe('published');
+    expect(schema.status.parse('draft')).toBe('draft');
+    expect(schema.status.parse('scheduled')).toBe('scheduled');
+    expect(schema.status.parse('all')).toBe('all');
+  });
+
+  it('should pass all parameters combined', async () => {
+    const mockPosts = [{ id: '1', title: 'Test Post' }];
+    mockSearchPosts.mockResolvedValue(mockPosts);
+
+    const tool = mockTools.get('ghost_search_posts');
+    await tool.handler({
+      query: 'JavaScript',
+      status: 'published',
+      limit: 20,
+    });
+
+    expect(mockSearchPosts).toHaveBeenCalledWith('JavaScript', {
+      status: 'published',
+      limit: 20,
+    });
+  });
+
+  it('should handle errors from searchPosts', async () => {
+    mockSearchPosts.mockRejectedValue(new Error('Search query is required'));
+
+    const tool = mockTools.get('ghost_search_posts');
+    const result = await tool.handler({ query: '' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Search query is required');
+  });
+
+  it('should handle Ghost API errors', async () => {
+    mockSearchPosts.mockRejectedValue(new Error('Ghost API error'));
+
+    const tool = mockTools.get('ghost_search_posts');
+    const result = await tool.handler({ query: 'test' });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('Ghost API error');
+  });
+
+  it('should return formatted JSON response', async () => {
+    const mockPosts = [
+      {
+        id: '1',
+        title: 'Test Post',
+        slug: 'test-post',
+        html: '<p>Content</p>',
+        status: 'published',
+      },
+    ];
+    mockSearchPosts.mockResolvedValue(mockPosts);
+
+    const tool = mockTools.get('ghost_search_posts');
+    const result = await tool.handler({ query: 'Test' });
+
+    expect(result.content).toBeDefined();
+    expect(result.content[0].type).toBe('text');
+    expect(result.content[0].text).toContain('"id": "1"');
+    expect(result.content[0].text).toContain('"title": "Test Post"');
+  });
+
+  it('should return empty array when no results found', async () => {
+    mockSearchPosts.mockResolvedValue([]);
+
+    const tool = mockTools.get('ghost_search_posts');
+    const result = await tool.handler({ query: 'nonexistent' });
+
+    expect(result.content[0].text).toBe('[]');
+    expect(result.isError).toBeUndefined();
+  });
+});