@jgardner04/ghost-mcp-server 1.13.4 → 1.13.5

package/README.md

@@ -278,6 +278,74 @@ For development, the following scripts are available:
 | `npm run lint`                | Check code for linting errors        |
 | `npm run lint:fix`            | Auto-fix linting errors              |
 
+## MCP Client Configuration
+
+The Ghost MCP Server works with any MCP-compatible client. Below are quickstart configurations for the most common clients. For a complete guide including WebSocket and HTTP/SSE transports, see [docs/MCP_CLIENT_SETUP.md](docs/MCP_CLIENT_SETUP.md).
+
+### Claude Code (including the Sidedoc project)
+
+Create a `.mcp.json` file at the root of your project (e.g., the [Sidedoc repository](https://github.com/jgardner04/sidedoc)):
+
+```json
+{
+  "mcpServers": {
+    "ghost": {
+      "command": "npx",
+      "args": ["-y", "@jgardner04/ghost-mcp-server"],
+      "env": {
+        "GHOST_ADMIN_API_URL": "https://your-ghost-site.com",
+        "GHOST_ADMIN_API_KEY": "your_admin_api_key"
+      }
+    }
+  }
+}
+```
+
+Claude Code will automatically detect this file and make all 34 Ghost MCP tools available within that project. You can also register the server globally:
+
+```bash
+claude mcp add ghost \
+  --scope user \
+  --command npx \
+  --args "-y @jgardner04/ghost-mcp-server" \
+  --env GHOST_ADMIN_API_URL=https://your-ghost-site.com \
+  --env GHOST_ADMIN_API_KEY=your_admin_api_key
+```
+
+> **Tip:** Do not commit `.mcp.json` files that contain real API keys. Add `.mcp.json` to your `.gitignore` or source credentials from a `.env` file.
+
+### Claude Desktop
+
+Add the server to your Claude Desktop configuration file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ghost": {
+      "command": "npx",
+      "args": ["-y", "@jgardner04/ghost-mcp-server"],
+      "env": {
+        "GHOST_ADMIN_API_URL": "https://your-ghost-site.com",
+        "GHOST_ADMIN_API_KEY": "your_admin_api_key"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving the file.
+
+### Cursor
+
+Open **Cursor Settings → Features → MCP Servers**, click **Add Server**, and provide:
+
+- **Name:** `ghost`
+- **Command:** `npx -y @jgardner04/ghost-mcp-server`
+- **Environment Variables:** `GHOST_ADMIN_API_URL` and `GHOST_ADMIN_API_KEY`
+
 ## Development Setup
 
 For contributors or advanced users who want to modify the source code:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgardner04/ghost-mcp-server",
-  "version": "1.13.4",
+  "version": "1.13.5",
   "description": "A Model Context Protocol (MCP) server for interacting with Ghost CMS via the Admin API",
   "author": "Jonathan Gardner",
   "type": "module",
@@ -43,12 +43,13 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write \"**/*.{js,json,md}\"",
     "format:check": "prettier --check \"**/*.{js,json,md}\"",
-    "prepare": "husky"
+    "prepare": "husky",
+    "prepublishOnly": "chmod +x src/mcp_server.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@tryghost/admin-api": "^1.13.12",
-    "axios": "^1.12.1",
+    "axios": "^1.15.0",
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.3",
     "dotenv": "^17.0.0",
@@ -86,6 +87,9 @@
       "prettier --write"
     ]
   },
+  "overrides": {
+    "axios": "^1.15.0"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.0",
     "@vitest/coverage-v8": "^4.0.15",

package/src/__tests__/helpers/testUtils.js

@@ -1,4 +1,18 @@
-import { vi } from 'vitest';
+import { expect, vi } from 'vitest';
+
+/**
+ * Asserts that a value is a ZodObject exposing a `.shape` property.
+ *
+ * Uses `expect` so Vitest reports a clean named assertion failure, and
+ * `schema?.shape` so a null/undefined `schema` is handled without a secondary
+ * TypeError — the exact opaque failure mode this helper eliminates.
+ *
+ * @param {unknown} schema - Value expected to be a ZodObject
+ * @param {string} toolName - Tool name included in the failure message
+ */
+export function assertZodShape(schema, toolName) {
+  expect(schema?.shape, `${toolName}: schema is not a ZodObject (missing .shape)`).toBeDefined();
+}
 
 /**
  * Creates a mock environment variable configuration.

package/src/__tests__/mcp_server.test.js

@@ -1,4 +1,8 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
+// zod/v4-mini is a subpath export of zod@^4 — used here because the MCP SDK's
+// internal JSON Schema converter (zod-json-schema-compat.js) uses this same module.
+import * as z4mini from 'zod/v4-mini';
+import { assertZodShape } from './helpers/testUtils.js';
 
 // Mock the McpServer to capture tool registrations
 const mockTools = new Map();
@@ -212,6 +216,7 @@ describe('mcp_server - ghost_get_posts tool', () => {
     expect(tool.description).toContain('posts');
     expect(tool.schema).toBeDefined();
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_get_posts');
     expect(tool.schema.shape.limit).toBeDefined();
     expect(tool.schema.shape.page).toBeDefined();
     expect(tool.schema.shape.status).toBeDefined();
@@ -250,6 +255,7 @@ describe('mcp_server - ghost_get_posts tool', () => {
   it('should validate limit is between 1 and 100', () => {
     const tool = mockTools.get('ghost_get_posts');
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_get_posts');
     const shape = tool.schema.shape;
 
     // Test that limit schema exists and has proper validation
@@ -262,6 +268,7 @@ describe('mcp_server - ghost_get_posts tool', () => {
   it('should validate page is at least 1', () => {
     const tool = mockTools.get('ghost_get_posts');
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_get_posts');
     const shape = tool.schema.shape;
 
     expect(shape.page).toBeDefined();
@@ -282,6 +289,7 @@ describe('mcp_server - ghost_get_posts tool', () => {
   it('should validate status enum values', () => {
     const tool = mockTools.get('ghost_get_posts');
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_get_posts');
     const shape = tool.schema.shape;
 
     expect(shape.status).toBeDefined();
@@ -449,6 +457,7 @@ describe('mcp_server - ghost_get_tags tool', () => {
     expect(tool.description).toContain('tags');
     expect(tool.schema).toBeDefined();
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_get_tags');
     expect(tool.schema.shape.limit).toBeDefined();
     expect(tool.schema.shape.page).toBeDefined();
     expect(tool.schema.shape.order).toBeDefined();
@@ -683,6 +692,7 @@ describe('mcp_server - ghost_get_post tool', () => {
     expect(tool.description).toContain('post');
     expect(tool.schema).toBeDefined();
     // In Zod v4, refined schemas expose .shape directly
+    assertZodShape(tool.schema, 'ghost_get_post');
     const shape = tool.schema.shape;
     expect(shape.id).toBeDefined();
     expect(shape.slug).toBeDefined();
@@ -849,6 +859,7 @@ describe('mcp_server - ghost_update_post tool', () => {
     expect(tool.description).toContain('Updates an existing post');
     expect(tool.schema).toBeDefined();
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_update_post');
     expect(tool.schema.shape.id).toBeDefined();
     expect(tool.schema.shape.title).toBeDefined();
     expect(tool.schema.shape.html).toBeDefined();
@@ -1120,6 +1131,7 @@ describe('mcp_server - ghost_delete_post tool', () => {
     expect(tool.description).toContain('permanent');
     expect(tool.schema).toBeDefined();
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_delete_post');
     expect(tool.schema.shape.id).toBeDefined();
   });
 
@@ -1199,6 +1211,7 @@ describe('mcp_server - ghost_search_posts tool', () => {
     expect(tool.description).toContain('Search');
     expect(tool.schema).toBeDefined();
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_search_posts');
     expect(tool.schema.shape.query).toBeDefined();
     expect(tool.schema.shape.status).toBeDefined();
     expect(tool.schema.shape.limit).toBeDefined();
@@ -1247,6 +1260,7 @@ describe('mcp_server - ghost_search_posts tool', () => {
   it('should validate limit is between 1 and 50', () => {
     const tool = mockTools.get('ghost_search_posts');
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_search_posts');
     const shape = tool.schema.shape;
 
     expect(shape.limit).toBeDefined();
@@ -1258,6 +1272,7 @@ describe('mcp_server - ghost_search_posts tool', () => {
   it('should validate status enum values', () => {
     const tool = mockTools.get('ghost_search_posts');
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_search_posts');
     const shape = tool.schema.shape;
 
     expect(shape.status).toBeDefined();
@@ -1356,6 +1371,7 @@ describe('ghost_get_tag', () => {
   it('should have correct schema with id and slug as optional', () => {
     const tool = mockTools.get('ghost_get_tag');
     // In Zod v4, refined schemas expose .shape directly
+    assertZodShape(tool.schema, 'ghost_get_tag');
     const shape = tool.schema.shape;
     expect(shape.id).toBeDefined();
     expect(shape.slug).toBeDefined();
@@ -1456,6 +1472,7 @@ describe('ghost_update_tag', () => {
   it('should have correct schema with all update fields', () => {
     const tool = mockTools.get('ghost_update_tag');
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_update_tag');
     expect(tool.schema.shape.id).toBeDefined();
     expect(tool.schema.shape.name).toBeDefined();
     expect(tool.schema.shape.slug).toBeDefined();
@@ -1602,6 +1619,7 @@ describe('ghost_delete_tag', () => {
   it('should have correct schema with id field', () => {
     const tool = mockTools.get('ghost_delete_tag');
     // Zod schemas store field definitions in schema.shape
+    assertZodShape(tool.schema, 'ghost_delete_tag');
     expect(tool.schema.shape.id).toBeDefined();
   });
 
@@ -1644,3 +1662,53 @@ describe('ghost_delete_tag', () => {
     expect(result.content[0].text).toContain('Failed to delete tag');
   });
 });
+
+// --- JSON Schema regression tests (JON-103) ---
+// Verifies that every registered MCP tool exposes a non-empty JSON Schema
+// to clients. Uses zod/v4-mini's toJSONSchema — the same converter the
+// MCP SDK calls internally (see zod-json-schema-compat.js).
+describe('tool schema JSON Schema output', () => {
+  // Matches the MCP SDK's internal conversion options (see zod-json-schema-compat.js)
+  const JSON_SCHEMA_OPTS = { target: 'draft-7', io: 'input' };
+
+  beforeAll(async () => {
+    if (mockTools.size === 0) {
+      await import('../mcp_server.js');
+    }
+  });
+
+  it('should produce non-empty properties for every registered tool', () => {
+    expect(mockTools.size).toBeGreaterThan(0);
+
+    for (const [name, tool] of mockTools) {
+      const schema = tool.schema;
+
+      // Schema must be a Zod object with a shape
+      assertZodShape(schema, name);
+      expect(Object.keys(schema.shape).length, `${name}: shape has no keys`).toBeGreaterThan(0);
+
+      // Convert via the same path the MCP SDK uses
+      const jsonSchema = z4mini.toJSONSchema(schema, JSON_SCHEMA_OPTS);
+
+      expect(jsonSchema.type, `${name}: type should be 'object'`).toBe('object');
+      expect(
+        Object.keys(jsonSchema.properties || {}).length,
+        `${name}: JSON Schema properties is empty`
+      ).toBeGreaterThan(0);
+    }
+  });
+
+  it('should declare title and html as required for ghost_create_post and ghost_create_page', () => {
+    for (const toolName of ['ghost_create_post', 'ghost_create_page']) {
+      const tool = mockTools.get(toolName);
+      expect(tool, `${toolName}: tool not found in registry`).toBeDefined();
+      const jsonSchema = z4mini.toJSONSchema(tool.schema, JSON_SCHEMA_OPTS);
+
+      expect(jsonSchema.properties, `${toolName}: properties missing`).toBeDefined();
+      expect(jsonSchema.required, `${toolName}: title not required`).toContain('title');
+      expect(jsonSchema.required, `${toolName}: html not required`).toContain('html');
+      expect(jsonSchema.properties.title.type, `${toolName}: title type`).toBe('string');
+      expect(jsonSchema.properties.html.type, `${toolName}: html type`).toBe('string');
+    }
+  });
+});

package/src/__tests__/mcp_server_pages.test.js

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { assertZodShape } from './helpers/testUtils.js';
 
 // Mock the McpServer to capture tool registrations
 const mockTools = new Map();
@@ -158,6 +159,7 @@ describe('mcp_server - ghost_get_pages tool', () => {
     expect(tool).toBeDefined();
     expect(tool.description).toContain('pages');
     expect(tool.schema).toBeDefined();
+    assertZodShape(tool.schema, 'ghost_get_pages');
     expect(tool.schema.shape.limit).toBeDefined();
     expect(tool.schema.shape.page).toBeDefined();
     expect(tool.schema.shape.include).toBeDefined();
@@ -194,6 +196,7 @@ describe('mcp_server - ghost_get_pages tool', () => {
     const tool = mockTools.get('ghost_get_pages');
     const schema = tool.schema;
 
+    assertZodShape(schema, 'ghost_get_pages');
     expect(schema.shape.limit).toBeDefined();
     expect(() => schema.shape.limit.parse(0)).toThrow();
     expect(() => schema.shape.limit.parse(101)).toThrow();
@@ -219,7 +222,7 @@ describe('mcp_server - ghost_get_pages tool', () => {
     const result = await tool.handler({});
 
     expect(result.isError).toBe(true);
-    expect(result.content[0].text).toContain('Error retrieving pages');
+    expect(result.content[0].text).toContain('Error in ghost_get_pages');
   });
 });
 
@@ -239,6 +242,7 @@ describe('mcp_server - ghost_get_page tool', () => {
     const tool = mockTools.get('ghost_get_page');
     expect(tool).toBeDefined();
     // In Zod v4, refined schemas expose .shape directly
+    assertZodShape(tool.schema, 'ghost_get_page');
     const shape = tool.schema.shape;
     expect(shape.id).toBeDefined();
     expect(shape.slug).toBeDefined();
@@ -279,6 +283,14 @@ describe('mcp_server - ghost_get_page tool', () => {
     expect(() => tool.schema.parse({ slug: 'about-us' })).not.toThrow();
   });
 
+  it('should return validation error when neither id nor slug provided', 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'));
 
@@ -286,7 +298,7 @@ describe('mcp_server - ghost_get_page tool', () => {
     const result = await tool.handler({ id: '507f1f77bcf86cd799439099' });
 
     expect(result.isError).toBe(true);
-    expect(result.content[0].text).toContain('Error retrieving page');
+    expect(result.content[0].text).toContain('Error in ghost_get_page');
   });
 });
 
@@ -306,6 +318,7 @@ describe('mcp_server - ghost_create_page tool', () => {
     const tool = mockTools.get('ghost_create_page');
     expect(tool).toBeDefined();
     expect(tool.description).toContain('page');
+    assertZodShape(tool.schema, 'ghost_create_page');
     expect(tool.schema.shape.title).toBeDefined();
     expect(tool.schema.shape.html).toBeDefined();
     expect(tool.schema.shape.status).toBeDefined();
@@ -361,7 +374,7 @@ describe('mcp_server - ghost_create_page tool', () => {
     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');
+    expect(result.content[0].text).toContain('Error in ghost_create_page');
   });
 });
 
@@ -381,6 +394,7 @@ describe('mcp_server - ghost_update_page tool', () => {
     const tool = mockTools.get('ghost_update_page');
     expect(tool).toBeDefined();
     expect(tool.description).toContain('page');
+    assertZodShape(tool.schema, 'ghost_update_page');
     expect(tool.schema.shape.id).toBeDefined();
     expect(tool.schema.shape.title).toBeDefined();
     expect(tool.schema.shape.html).toBeDefined();
@@ -433,7 +447,7 @@ describe('mcp_server - ghost_update_page tool', () => {
     const result = await tool.handler({ id: '507f1f77bcf86cd799439099', title: 'Test' });
 
     expect(result.isError).toBe(true);
-    expect(result.content[0].text).toContain('Error updating page');
+    expect(result.content[0].text).toContain('Error in ghost_update_page');
   });
 });
 
@@ -452,6 +466,7 @@ describe('mcp_server - ghost_delete_page tool', () => {
   it('should have correct schema with id required', () => {
     const tool = mockTools.get('ghost_delete_page');
     expect(tool).toBeDefined();
+    assertZodShape(tool.schema, 'ghost_delete_page');
     expect(tool.schema.shape.id).toBeDefined();
     expect(tool.description).toContain('permanent');
   });
@@ -473,7 +488,7 @@ describe('mcp_server - ghost_delete_page tool', () => {
     const result = await tool.handler({ id: '507f1f77bcf86cd799439099' });
 
     expect(result.isError).toBe(true);
-    expect(result.content[0].text).toContain('Error deleting page');
+    expect(result.content[0].text).toContain('Error in ghost_delete_page');
   });
 });
 
@@ -492,6 +507,7 @@ describe('mcp_server - ghost_search_pages tool', () => {
   it('should have correct schema with query required', () => {
     const tool = mockTools.get('ghost_search_pages');
     expect(tool).toBeDefined();
+    assertZodShape(tool.schema, 'ghost_search_pages');
     expect(tool.schema.shape.query).toBeDefined();
     expect(tool.schema.shape.status).toBeDefined();
     expect(tool.schema.shape.limit).toBeDefined();
@@ -535,6 +551,7 @@ describe('mcp_server - ghost_search_pages tool', () => {
     const tool = mockTools.get('ghost_search_pages');
     const schema = tool.schema;
 
+    assertZodShape(schema, 'ghost_search_pages');
     expect(schema.shape.limit).toBeDefined();
     expect(() => schema.shape.limit.parse(0)).toThrow();
     expect(() => schema.shape.limit.parse(51)).toThrow();
@@ -548,6 +565,6 @@ describe('mcp_server - ghost_search_pages tool', () => {
     const result = await tool.handler({ query: 'test' });
 
     expect(result.isError).toBe(true);
-    expect(result.content[0].text).toContain('Error searching pages');
+    expect(result.content[0].text).toContain('Error in ghost_search_pages');
   });
 });