@adsim/wordpress-mcp-server 5.1.0 → 5.3.1

package/README.md

@@ -10,7 +10,7 @@
 
 The enterprise governance layer for Claude-to-WordPress integrations — secure, auditable, and multi-site.
 
-**v5.1.0 Enterprise** · 175 tools · ~1101 Vitest tests · GitHub Actions CI
+**v5.3.1 Enterprise** · 176 tools · ~1109 Vitest tests · GitHub Actions CI
 
 ---
 
@@ -1300,6 +1300,22 @@ npx @modelcontextprotocol/inspector node index.js
 
 ## Changelog
 
+### v5.3.1 (2026-03-11) — ACF REST Integration Fix
+
+- Fix: `wp_get_post` and `wp_get_page` now include `acf_fields` from WP REST `acf` field
+- Fix: `wp_get_post_meta` includes `acf_fields` alongside meta via `?_fields=meta,acf`
+- Fix: `acf_get_fields` second fallback via `wp/v2?_fields=acf` when acf/v3 returns empty
+- Hint displayed when ACF data is empty (Show in REST API diagnostic)
+- 176 tools · ~1109 Vitest tests
+
+### v5.3.0 (2026-03-11) — ACF Fallback + Post Meta
+
+- `wp_get_post_meta`: generic post meta reader — ACF, Elementor, Yoast, any custom meta
+- ACF adapter: WP Core meta fallback when acf/v3 returns 404 (ACF free support)
+- ACF adapter: diagnostic warning with causes when fields are empty
+- Auto-parse JSON meta values (_elementor_data, etc.)
+- 176 tools · ~1109 Vitest tests
+
 ### v5.1.0 (2026-03-11) — Workflow Orchestrator
 
 - `wp_run_workflow`: execute named or custom tool sequences in a single call

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adsim/wordpress-mcp-server",
-  "version": "5.1.0",
+  "version": "5.3.1",
   "description": "Enterprise WordPress MCP Server — 180 tools, modular architecture, governance, audit trail, WooCommerce, Schema.org, multilingual.",
   "type": "module",
   "main": "index.js",

package/src/plugins/adapters/acf/acfAdapter.js

@@ -33,9 +33,37 @@ async function handleGetFields(args, apiRequest) {
   const t0 = Date.now();
   const { id, post_type = 'posts', fields, mode = 'compact' } = args;
 
-  const data = await apiRequest(`/${post_type}/${id}`, { basePath: '/wp-json/acf/v3' });
+  let acfData = {};
+  let source = 'acf_rest_api';
+  let fallbackMeta = null;
+
+  try {
+    const data = await apiRequest(`/${post_type}/${id}`, { basePath: '/wp-json/acf/v3' });
+    acfData = data?.acf ?? data ?? {};
+  } catch (e) {
+    // Fallback: read from WP Core meta if acf/v3 returns 404
+    if (e.message.includes('404') || e.message.includes('rest_no_route')) {
+      try {
+        const post = await apiRequest(`/${post_type}/${id}?_fields=meta`, { basePath: '/wp-json/wp/v2' });
+        acfData = post?.meta ?? {};
+        source = 'wp_core_meta';
+        fallbackMeta = acfData;
+      } catch { throw e; }
+    } else {
+      throw e;
+    }
+  }
 
-  let acfData = data?.acf ?? data ?? {};
+  // Second fallback: try WP REST acf field if acf/v3 returned empty
+  if (Object.keys(acfData).length === 0 && source === 'acf_rest_api') {
+    try {
+      const post = await apiRequest(`/${post_type}/${id}?_fields=acf`, { basePath: '/wp-json/wp/v2' });
+      if (post?.acf && Object.keys(post.acf).length > 0) {
+        acfData = post.acf;
+        source = 'wp_rest_acf_field';
+      }
+    } catch { /* ignore — will show diagnostic below */ }
+  }
 
   // Filter to requested keys
   if (fields && fields.length > 0) {
@@ -46,8 +74,32 @@ async function handleGetFields(args, apiRequest) {
     acfData = filtered;
   }
 
+  // Diagnostic if empty
+  if (Object.keys(acfData).length === 0) {
+    const result = {
+      id, post_type, fields_count: 0, acf: {},
+      source,
+      warning: 'No ACF fields returned. Possible causes:',
+      causes: [
+        '1. Field group has Show in REST API = No → Enable in ACF Admin > Field Groups > Settings',
+        '2. ACF free version without REST support → Upgrade to ACF Pro or add acf_rest_api filter',
+        '3. Post type not in field group location rules',
+        '4. Post ID incorrect'
+      ],
+    };
+    if (fallbackMeta !== null) result.fallback_meta = fallbackMeta;
+    auditLog({ tool: 'acf_get_fields', action: 'read_acf_fields', target: id, status: 'empty', latency_ms: Date.now() - t0 });
+    return json(result);
+  }
+
+  const responseData = { id, post_type, fields_count: Object.keys(acfData).length, acf: acfData };
+  if (source !== 'acf_rest_api') {
+    responseData.source = source;
+    responseData.warning = 'ACF REST API not available. Data read from WP Core meta. Enable Show in REST API in field group settings.';
+  }
+
   const guarded = applyContextGuard(
-    { id, post_type, fields_count: Object.keys(acfData).length, acf: acfData },
+    responseData,
     { toolName: 'acf_get_fields', mode, maxChars: 30000 }
   );
 

package/src/tools/content.js

@@ -1,4 +1,4 @@
-// src/tools/content.js — content tools (12)
+// src/tools/content.js — content tools (13)
 // Definitions + handlers (v5.0.0 refactor Step B+C)
 
 import { json, strip, buildPaginationMeta, validateBlocks } from '../shared/utils.js';
@@ -19,7 +19,9 @@ export const definitions = [
   { name: 'wp_list_pages', _category: 'content', description: 'Use to browse pages with hierarchy and templates. Supports parent filter, menu_order sort. Read-only. Hint: use mode=\'summary\' for listings, \'ids_only\' for batch ops.', inputSchema: { type: 'object', properties: { per_page: { type: 'number', default: 10 }, page: { type: 'number', default: 1 }, status: { type: 'string', default: 'publish' }, parent: { type: 'number' }, orderby: { type: 'string', default: 'menu_order' }, order: { type: 'string', default: 'asc' }, search: { type: 'string' }, mode: { type: 'string', enum: ['full', 'summary', 'ids_only'], default: 'full', description: 'full=all fields, summary=key fields only, ids_only=flat ID array' } }}},
   { name: 'wp_get_page', _category: 'content', description: 'Use to read a single page with content and template. Read-only. Warning: Elementor pages can exceed 100k chars.', inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] }},
   { name: 'wp_create_page', _category: 'content', description: 'Use to create a page (defaults to draft). Supports parent, template, menu_order. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { title: { type: 'string' }, content: { type: 'string' }, status: { type: 'string', default: 'draft' }, parent: { type: 'number', default: 0 }, template: { type: 'string' }, menu_order: { type: 'number', default: 0 }, excerpt: { type: 'string' }, slug: { type: 'string' }, featured_media: { type: 'number' }, meta: { type: 'object' } }, required: ['title', 'content'] }},
-  { name: 'wp_update_page', _category: 'content', description: 'Use to modify any page field. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, title: { type: 'string' }, content: { type: 'string' }, status: { type: 'string' }, parent: { type: 'number' }, template: { type: 'string' }, menu_order: { type: 'number' }, excerpt: { type: 'string' }, slug: { type: 'string' }, featured_media: { type: 'number' }, meta: { type: 'object' } }, required: ['id'] }}
+  { name: 'wp_update_page', _category: 'content', description: 'Use to modify any page field. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { id: { type: 'number' }, title: { type: 'string' }, content: { type: 'string' }, status: { type: 'string' }, parent: { type: 'number' }, template: { type: 'string' }, menu_order: { type: 'number' }, excerpt: { type: 'string' }, slug: { type: 'string' }, featured_media: { type: 'number' }, meta: { type: 'object' } }, required: ['id'] }},
+  { name: 'wp_get_post_meta', _category: 'content', description: 'Read post meta fields. Use for ACF data if acf/v3 unavailable, or for any custom meta (_elementor_data, _yoast_wpseo_*, etc.). Returns all meta if meta_key omitted.',
+        inputSchema: { type: 'object', properties: { post_id: { type: 'number' }, post_type: { type: 'string', default: 'posts', description: 'posts or pages' }, meta_key: { type: 'string', description: 'Specific key. Omit for all meta.' }, parse_json: { type: 'boolean', default: true, description: 'Auto-parse JSON strings (e.g. _elementor_data)' } }, required: ['post_id'] }}
 ];
 
 export const handlers = {};
@@ -55,6 +57,8 @@ handlers['wp_get_post'] = async (args) => {
   const { content_format = 'html', fields: requestedFields } = args;
   const p = await wpApiCall(`/posts/${args.id}`);
   let postData = { id: p.id, title: p.title.rendered, content: p.content.rendered, excerpt: p.excerpt.rendered, status: p.status, date: p.date, modified: p.modified, link: p.link, slug: p.slug, categories: p.categories, tags: p.tags, author: p.author, featured_media: p.featured_media, comment_status: p.comment_status, meta: p.meta || {} };
+  if (p.acf && Object.keys(p.acf).length > 0) { postData.acf_fields = p.acf; }
+  else { postData.acf_fields = {}; postData.acf_hint = 'ACF returned empty. Verify Show in REST API is enabled in each Field Group settings in WordPress Admin.'; }
   const { url: siteUrl } = getActiveAuth();
   postData = applyContentFormat(postData, content_format, siteUrl);
   if (requestedFields && requestedFields.length > 0) postData = summarizePost(postData, requestedFields);
@@ -320,7 +324,10 @@ handlers['wp_get_page'] = async (args) => {
   const { wpApiCall, auditLog, name } = rt;
   validateInput(args, { id: { type: 'number', required: true, min: 1 } });
   const pg = await wpApiCall(`/pages/${args.id}`);
-  result = json({ id: pg.id, title: pg.title.rendered, content: pg.content.rendered, excerpt: pg.excerpt.rendered, status: pg.status, date: pg.date, modified: pg.modified, link: pg.link, slug: pg.slug, parent: pg.parent, menu_order: pg.menu_order, template: pg.template, author: pg.author, featured_media: pg.featured_media, meta: pg.meta || {} });
+  const pageData = { id: pg.id, title: pg.title.rendered, content: pg.content.rendered, excerpt: pg.excerpt.rendered, status: pg.status, date: pg.date, modified: pg.modified, link: pg.link, slug: pg.slug, parent: pg.parent, menu_order: pg.menu_order, template: pg.template, author: pg.author, featured_media: pg.featured_media, meta: pg.meta || {} };
+  if (pg.acf && Object.keys(pg.acf).length > 0) { pageData.acf_fields = pg.acf; }
+  else { pageData.acf_fields = {}; pageData.acf_hint = 'ACF returned empty. Verify Show in REST API is enabled in each Field Group settings in WordPress Admin.'; }
+  result = json(pageData);
   auditLog({ tool: name, target: args.id, target_type: 'page', action: 'read', status: 'success', latency_ms: Date.now() - t0 });
   return result;
 };
@@ -351,3 +358,38 @@ handlers['wp_update_page'] = async (args) => {
   auditLog({ tool: name, target: id, target_type: 'page', action: 'update', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(upd) });
   return result;
 };
+handlers['wp_get_post_meta'] = async (args) => {
+  const t0 = Date.now();
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { post_id: { type: 'number', required: true, min: 1 }, post_type: { type: 'string', enum: ['posts', 'pages'] } });
+  const { post_id, post_type = 'posts', meta_key, parse_json = true } = args;
+  let meta, acfFields = {};
+  try {
+    const post = await wpApiCall(`/${post_type}/${post_id}?_fields=meta,acf`);
+    meta = post?.meta ?? {};
+    acfFields = post?.acf ?? {};
+  } catch (e) {
+    if (post_type === 'posts' && e.message.includes('404')) {
+      const post = await wpApiCall(`/pages/${post_id}?_fields=meta,acf`);
+      meta = post?.meta ?? {};
+      acfFields = post?.acf ?? {};
+    } else { throw e; }
+  }
+  // Auto-parse JSON strings
+  if (parse_json) {
+    for (const [k, v] of Object.entries(meta)) {
+      if (typeof v === 'string' && v.length > 1 && (v[0] === '[' || v[0] === '{')) {
+        try { meta[k] = JSON.parse(v); } catch { /* keep as string */ }
+      }
+    }
+  }
+  let result;
+  if (meta_key) {
+    const value = meta[meta_key] !== undefined ? meta[meta_key] : (acfFields[meta_key] !== undefined ? acfFields[meta_key] : null);
+    result = json({ post_id, meta_key, value });
+  } else {
+    result = json({ post_id, meta, acf_fields: acfFields, source: Object.keys(acfFields).length > 0 ? 'acf_rest' : 'wp_meta_only' });
+  }
+  auditLog({ tool: name, target: post_id, action: 'read_meta', status: 'success', latency_ms: Date.now() - t0, params: { meta_key: meta_key || 'all' } });
+  return result;
+};

package/src/tools/index.js

@@ -30,7 +30,7 @@ export const toolModules = [
   fse, health, performance, schema, security, editorial,
 ];
 
-/** All static definitions (175 tools), unfiltered */
+/** All static definitions (176 tools), unfiltered */
 export const ALL_DEFINITIONS = toolModules.flatMap(m => m.definitions);
 
 /** All handlers merged into a single lookup */

package/tests/unit/plugins/acf/acfAdapter.test.js

@@ -137,12 +137,50 @@ describe('ACF Adapter', () => {
     expect(data._warning).toContain('truncated');
   });
 
-  // 5. acf_get_fields — 404
-  it('acf_get_fields propagates 404 error', async () => {
+  // 5. acf_get_fields — fallback to WP Core meta on 404
+  it('acf_get_fields falls back to WP Core meta when acf/v3 returns 404', async () => {
+    let callCount = 0;
+    const fallbackApi = async (endpoint, opts) => {
+      callCount++;
+      if (opts?.basePath === '/wp-json/acf/v3') throw new Error('WP API 404: Not Found');
+      // WP Core fallback
+      return { meta: { hero_title: 'From Core', _elementor_data: '[]' } };
+    };
     const tool = acfAdapter.getTools().find(t => t.name === 'acf_get_fields');
-    await expect(
-      tool.handler({ id: 99999 }, mockApi(null, true))
-    ).rejects.toThrow('404');
+    const result = await tool.handler({ id: 42 }, fallbackApi);
+    const data = parseResult(result);
+    expect(data.source).toBe('wp_core_meta');
+    expect(data.warning).toContain('ACF REST API not available');
+    expect(data.acf.hero_title).toBe('From Core');
+    expect(callCount).toBe(2);
+  });
+
+  // 5b. acf_get_fields — fallback via ?_fields=acf when acf/v3 returns empty
+  it('acf_get_fields falls back to wp/v2?_fields=acf when acf/v3 returns empty', async () => {
+    let calls = [];
+    const fallbackApi = async (endpoint, opts) => {
+      calls.push({ endpoint, basePath: opts?.basePath });
+      if (opts?.basePath === '/wp-json/acf/v3') return { acf: {} };
+      if (endpoint.includes('_fields=acf')) return { acf: { hero: 'from_wp_rest' } };
+      return {};
+    };
+    const tool = acfAdapter.getTools().find(t => t.name === 'acf_get_fields');
+    const result = await tool.handler({ id: 42 }, fallbackApi);
+    const data = parseResult(result);
+    expect(data.acf.hero).toBe('from_wp_rest');
+    expect(data.source).toBe('wp_rest_acf_field');
+    expect(calls).toHaveLength(2);
+  });
+
+  // 5c. acf_get_fields — diagnostic warning when empty
+  it('acf_get_fields returns diagnostic when fields are empty', async () => {
+    const tool = acfAdapter.getTools().find(t => t.name === 'acf_get_fields');
+    const result = await tool.handler({ id: 42 }, mockApi({ acf: {} }));
+    const data = parseResult(result);
+    expect(data.fields_count).toBe(0);
+    expect(data.warning).toContain('No ACF fields returned');
+    expect(data.causes).toHaveLength(4);
+    expect(data.causes[0]).toContain('Show in REST API');
   });
 
   // 6. acf_list_field_groups — success

package/tests/unit/tools/dynamicFiltering.test.js

@@ -111,11 +111,11 @@ describe('Combined filtering counts', () => {
     process.env.WC_CONSUMER_KEY = 'ck_test';
     process.env.WP_REQUIRE_APPROVAL = 'true';
     process.env.WP_ENABLE_PLUGIN_INTELLIGENCE = 'true';
-    expect(getFilteredTools()).toHaveLength(175);
+    expect(getFilteredTools()).toHaveLength(176);
   });
 
   it('returns 145 tools with no optional features (174 - 20wc - 3editorial - 6pi)', () => {
-    expect(getFilteredTools()).toHaveLength(146);
+    expect(getFilteredTools()).toHaveLength(147);
   });
 });
 
@@ -188,13 +188,13 @@ describe('WP_TOOL_CATEGORIES filtering', () => {
     process.env.WP_TOOL_CATEGORIES = '';
     const tools = getFilteredTools();
     // Same as default (no category filter) — 143 base tools
-    expect(tools).toHaveLength(146);
+    expect(tools).toHaveLength(147);
   });
 
   it('WP_TOOL_CATEGORIES undefined → all tools exposed', () => {
     delete process.env.WP_TOOL_CATEGORIES;
     const tools = getFilteredTools();
-    expect(tools).toHaveLength(146);
+    expect(tools).toHaveLength(147);
   });
 
   it('core tools (wp_site_info, wp_set_target) always present regardless of config', () => {
@@ -216,7 +216,7 @@ describe('WP_TOOL_CATEGORIES filtering', () => {
   });
 
   it('total TOOLS_DEFINITIONS count is 174', () => {
-    expect(TOOLS_DEFINITIONS).toHaveLength(175);
+    expect(TOOLS_DEFINITIONS).toHaveLength(176);
   });
 
   it('getEnabledCategories reflects WP_TOOL_CATEGORIES', () => {

package/tests/unit/tools/postMeta.test.js

@@ -0,0 +1,105 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+vi.mock('node-fetch', () => ({ default: vi.fn() }));
+
+import fetch from 'node-fetch';
+import { handleToolCall } from '../../../index.js';
+import { mockSuccess, mockError, makeRequest, parseResult } from '../../helpers/mockWpRequest.js';
+
+function call(name, args = {}) {
+  return handleToolCall(makeRequest(name, args));
+}
+
+let consoleSpy;
+beforeEach(() => { fetch.mockReset(); consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {}); });
+afterEach(() => { consoleSpy.mockRestore(); });
+
+// =========================================================================
+// wp_get_post_meta
+// =========================================================================
+
+describe('wp_get_post_meta', () => {
+  it('SUCCESS — returns all meta fields', async () => {
+    mockSuccess({ meta: { _yoast_wpseo_title: 'SEO Title', custom_field: 'value' } });
+
+    const res = await call('wp_get_post_meta', { post_id: 42 });
+    const data = parseResult(res);
+
+    expect(data.post_id).toBe(42);
+    expect(data.meta._yoast_wpseo_title).toBe('SEO Title');
+    expect(data.meta.custom_field).toBe('value');
+  });
+
+  it('SUCCESS — filters by meta_key', async () => {
+    mockSuccess({ meta: { _yoast_wpseo_title: 'SEO Title', other: 'x' } });
+
+    const res = await call('wp_get_post_meta', { post_id: 42, meta_key: '_yoast_wpseo_title' });
+    const data = parseResult(res);
+
+    expect(data.post_id).toBe(42);
+    expect(data.meta_key).toBe('_yoast_wpseo_title');
+    expect(data.value).toBe('SEO Title');
+  });
+
+  it('SUCCESS — auto-parses JSON strings', async () => {
+    mockSuccess({ meta: { _elementor_data: '[{"elType":"section"}]', plain: 'text' } });
+
+    const res = await call('wp_get_post_meta', { post_id: 10, parse_json: true });
+    const data = parseResult(res);
+
+    expect(Array.isArray(data.meta._elementor_data)).toBe(true);
+    expect(data.meta._elementor_data[0].elType).toBe('section');
+    expect(data.meta.plain).toBe('text');
+  });
+
+  it('FALLBACK — retries on pages if posts returns 404', async () => {
+    // First call (posts) → 404
+    fetch.mockImplementationOnce(() => Promise.resolve({
+      ok: false, status: 404,
+      headers: { get: () => null },
+      text: () => Promise.resolve('Not found')
+    }));
+    // Second call (pages) → success
+    mockSuccess({ meta: { page_field: 'from_pages' } });
+
+    const res = await call('wp_get_post_meta', { post_id: 5, post_type: 'posts' });
+    const data = parseResult(res);
+
+    expect(data.post_id).toBe(5);
+    expect(data.meta.page_field).toBe('from_pages');
+  });
+});
+
+// =========================================================================
+// wp_get_post — ACF fields integration
+// =========================================================================
+
+describe('wp_get_post — ACF fields', () => {
+  const fullPost = (acf) => ({
+    id: 1, title: { rendered: 'T' }, content: { rendered: '' }, excerpt: { rendered: '' },
+    status: 'publish', date: '2026-01-01', modified: '2026-01-01', link: 'https://test.example.com/?p=1',
+    slug: 'test', categories: [], tags: [], author: 1, featured_media: 0, comment_status: 'open', meta: {},
+    acf,
+  });
+
+  it('includes acf_fields when post.acf has data', async () => {
+    mockSuccess(fullPost({ hero_title: 'Hello', price: 29 }));
+
+    const res = await call('wp_get_post', { id: 1 });
+    const data = parseResult(res);
+
+    expect(data.acf_fields.hero_title).toBe('Hello');
+    expect(data.acf_fields.price).toBe(29);
+    expect(data.acf_hint).toBeUndefined();
+  });
+
+  it('includes acf_hint when post.acf is empty', async () => {
+    mockSuccess(fullPost({}));
+
+    const res = await call('wp_get_post', { id: 1 });
+    const data = parseResult(res);
+
+    expect(data.acf_fields).toEqual({});
+    expect(data.acf_hint).toContain('Show in REST API');
+  });
+});

package/tests/unit/tools/site.test.js

@@ -80,7 +80,7 @@ describe('wp_site_info', () => {
 
     // Server info
     expect(data.server.mcp_version).toBeDefined();
-    expect(data.server.tools_total).toBe(175);
+    expect(data.server.tools_total).toBe(176);
     expect(typeof data.server.tools_exposed).toBe('number');
     expect(Array.isArray(data.server.filtered_out)).toBe(true);
   });