@adsim/wordpress-mcp-server 4.5.0 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adsim/wordpress-mcp-server",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "A Model Context Protocol (MCP) server for WordPress REST API integration. Manage posts, search content, and interact with your WordPress site through any MCP-compatible client.",
   "type": "module",
   "main": "index.js",

package/src/plugins/IPluginAdapter.js

@@ -0,0 +1,95 @@
+/**
+ * Plugin Adapter Interface — contract every adapter must implement.
+ *
+ * @typedef {Object} IPluginAdapter
+ * @property {string} id
+ *   Unique identifier for the plugin (e.g. "acf", "elementor", "astra").
+ *
+ * @property {string} namespace
+ *   REST API namespace used for detection (e.g. "acf/v3", "elementor/v1").
+ *
+ * @property {"low"|"medium"|"high"|"critical"} riskLevel
+ *   Global risk level for audit logging.
+ *   - low:      read-only operations, zero side-effects
+ *   - medium:   modifies a single targeted resource
+ *   - high:     cascading modifications across multiple resources
+ *   - critical: site-wide visual / structural impact
+ *
+ * @property {Object} contextConfig
+ *   Context-size guardrails for this adapter.
+ * @property {number}   contextConfig.maxChars
+ *   Maximum serialised response size in characters (default 30 000).
+ * @property {string}   contextConfig.defaultMode
+ *   Default response mode if the caller omits it (typically "compact").
+ * @property {string[]} contextConfig.supportedModes
+ *   Modes the adapter's tools accept (e.g. ["raw", "compact", "summary", "ids_only"]).
+ *
+ * @property {Function} getTools
+ *   Returns an array of MCP tool definition objects
+ *   ({ name, description, inputSchema, handler }).
+ */
+
+const VALID_RISK_LEVELS = ['low', 'medium', 'high', 'critical'];
+
+const REQUIRED_FIELDS = [
+  { key: 'id', type: 'string' },
+  { key: 'namespace', type: 'string' },
+  { key: 'riskLevel', type: 'string', enum: VALID_RISK_LEVELS },
+  { key: 'contextConfig', type: 'object' },
+  { key: 'getTools', type: 'function' },
+];
+
+/**
+ * Validate that an adapter object satisfies the IPluginAdapter contract.
+ *
+ * @param {object} adapter  Adapter object to validate
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateAdapter(adapter) {
+  const errors = [];
+
+  if (!adapter || typeof adapter !== 'object') {
+    return { valid: false, errors: ['adapter must be a non-null object'] };
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    const value = adapter[field.key];
+
+    if (value === undefined || value === null) {
+      errors.push(`missing required field: "${field.key}"`);
+      continue;
+    }
+
+    if (field.type === 'function') {
+      if (typeof value !== 'function') {
+        errors.push(`"${field.key}" must be a function, got ${typeof value}`);
+      }
+    } else if (field.type === 'object') {
+      if (typeof value !== 'object' || Array.isArray(value)) {
+        errors.push(`"${field.key}" must be a plain object`);
+      }
+    } else if (typeof value !== field.type) {
+      errors.push(`"${field.key}" must be a ${field.type}, got ${typeof value}`);
+    }
+
+    if (field.enum && !field.enum.includes(value)) {
+      errors.push(`"${field.key}" must be one of: ${field.enum.join(', ')}; got "${value}"`);
+    }
+  }
+
+  // contextConfig sub-fields
+  if (adapter.contextConfig && typeof adapter.contextConfig === 'object') {
+    const cc = adapter.contextConfig;
+    if (cc.maxChars !== undefined && typeof cc.maxChars !== 'number') {
+      errors.push('"contextConfig.maxChars" must be a number');
+    }
+    if (cc.defaultMode !== undefined && typeof cc.defaultMode !== 'string') {
+      errors.push('"contextConfig.defaultMode" must be a string');
+    }
+    if (cc.supportedModes !== undefined && !Array.isArray(cc.supportedModes)) {
+      errors.push('"contextConfig.supportedModes" must be an array');
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

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

@@ -0,0 +1,181 @@
+/**
+ * ACF (Advanced Custom Fields) Adapter — read + write.
+ *
+ * Provides 4 tools for ACF data via the ACF REST API (acf/v3):
+ *   - acf_get_fields        Read custom fields for a post or page
+ *   - acf_list_field_groups  List registered field groups
+ *   - acf_get_field_group    Get full details of a field group by ID
+ *   - acf_update_fields      Update custom fields (write — blocked by WP_READ_ONLY)
+ *
+ * Read tools are riskLevel "low". The write tool checks WP_READ_ONLY before
+ * making any API call. All responses pass through contextGuard.
+ */
+
+import { applyContextGuard } from '../../contextGuard.js';
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function json(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+function auditLog(entry) {
+  console.error(`[AUDIT] ${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}`);
+}
+
+// ── Tool handlers ───────────────────────────────────────────────────────
+
+/**
+ * @param {object} args
+ * @param {Function} apiRequest  wpApiCall-compatible: (endpoint, options?) => JSON
+ */
+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 = data?.acf ?? data ?? {};
+
+  // Filter to requested keys
+  if (fields && fields.length > 0) {
+    const filtered = {};
+    for (const k of fields) {
+      if (k in acfData) filtered[k] = acfData[k];
+    }
+    acfData = filtered;
+  }
+
+  const guarded = applyContextGuard(
+    { id, post_type, fields_count: Object.keys(acfData).length, acf: acfData },
+    { toolName: 'acf_get_fields', mode, maxChars: 30000 }
+  );
+
+  auditLog({ tool: 'acf_get_fields', action: 'read_acf_fields', target: id, status: 'success', latency_ms: Date.now() - t0 });
+  return json(guarded);
+}
+
+async function handleListFieldGroups(args, apiRequest) {
+  const t0 = Date.now();
+
+  const groups = await apiRequest('/field-groups', { basePath: '/wp-json/acf/v3' });
+  const list = Array.isArray(groups) ? groups : [];
+
+  const summary = list.map(g => ({
+    id: g.id,
+    title: g.title?.rendered ?? g.title ?? '',
+    fields: (g.fields ?? []).map(f => f.name ?? f.key ?? f.label ?? ''),
+    location: g.location ?? [],
+  }));
+
+  auditLog({ tool: 'acf_list_field_groups', action: 'list_field_groups', status: 'success', latency_ms: Date.now() - t0, params: { count: summary.length } });
+  return json({ total: summary.length, field_groups: summary });
+}
+
+async function handleGetFieldGroup(args, apiRequest) {
+  const t0 = Date.now();
+  const { id } = args;
+
+  const group = await apiRequest(`/field-groups/${id}`, { basePath: '/wp-json/acf/v3' });
+
+  auditLog({ tool: 'acf_get_field_group', action: 'read_field_group', target: id, status: 'success', latency_ms: Date.now() - t0 });
+  return json(group);
+}
+
+async function handleUpdateFields(args, apiRequest) {
+  const t0 = Date.now();
+  const { id, post_type = 'posts', fields } = args;
+
+  // Validate id is a positive integer
+  if (typeof id !== 'number' || !Number.isInteger(id) || id <= 0) {
+    throw new Error('Validation error: "id" must be a positive integer');
+  }
+
+  // Validate fields is a non-empty object
+  if (!fields || typeof fields !== 'object' || Array.isArray(fields) || Object.keys(fields).length === 0) {
+    throw new Error('Validation error: "fields" must be a non-empty object of key/value pairs');
+  }
+
+  // Governance: WP_READ_ONLY check
+  if (process.env.WP_READ_ONLY === 'true') {
+    auditLog({ tool: 'acf_update_fields', action: 'update_acf_fields', target: id, status: 'blocked', latency_ms: Date.now() - t0 });
+    return json({ error: 'Blocked: READ-ONLY mode' });
+  }
+
+  const data = await apiRequest(`/${post_type}/${id}`, {
+    basePath: '/wp-json/acf/v3',
+    method: 'POST',
+    body: { fields },
+  });
+
+  const updatedFields = data?.acf ?? data ?? {};
+
+  auditLog({ tool: 'acf_update_fields', action: 'update_acf_fields', target: id, status: 'success', latency_ms: Date.now() - t0 });
+  return json({ id, post_type, updated_fields: updatedFields });
+}
+
+// ── Tool definitions (MCP format) ───────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'acf_get_fields',
+    description: 'Use to read ACF custom fields for a post or page. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number' },
+        post_type: { type: 'string', enum: ['posts', 'pages'], default: 'posts' },
+        fields: { type: 'array', items: { type: 'string' }, description: 'Return only these field keys (returns all if omitted)' },
+        mode: { type: 'string', enum: ['raw', 'compact', 'summary'], default: 'compact' },
+      },
+      required: ['id'],
+    },
+    handler: handleGetFields,
+  },
+  {
+    name: 'acf_list_field_groups',
+    description: 'Use to list ACF field groups registered on the site. Read-only.',
+    inputSchema: { type: 'object', properties: {} },
+    handler: handleListFieldGroups,
+  },
+  {
+    name: 'acf_get_field_group',
+    description: 'Use to get full details of an ACF field group by ID. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number' },
+      },
+      required: ['id'],
+    },
+    handler: handleGetFieldGroup,
+  },
+  {
+    name: 'acf_update_fields',
+    description: 'Use to update ACF custom fields for a post or page. Write — blocked by WP_READ_ONLY.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number' },
+        post_type: { type: 'string', enum: ['posts', 'pages'], default: 'posts' },
+        fields: { type: 'object', additionalProperties: true, description: 'Key/value pairs of ACF fields to update' },
+      },
+      required: ['id', 'fields'],
+    },
+    handler: handleUpdateFields,
+  },
+];
+
+// ── Adapter export ──────────────────────────────────────────────────────
+
+export const acfAdapter = {
+  id: 'acf',
+  namespace: 'acf/v3',
+  riskLevel: 'medium',
+  contextConfig: {
+    maxChars: 30000,
+    defaultMode: 'compact',
+    supportedModes: ['raw', 'compact', 'summary', 'ids_only'],
+  },
+  getTools: () => TOOLS,
+};

package/src/plugins/adapters/elementor/elementorAdapter.js

@@ -0,0 +1,176 @@
+/**
+ * Elementor Adapter — read-only.
+ *
+ * Provides 3 tools for reading Elementor data via the REST API (elementor/v1):
+ *   - elementor_list_templates   List templates (page, section, block, popup)
+ *   - elementor_get_template     Get full template content and elements
+ *   - elementor_get_page_data    Get Elementor editor data for a post/page
+ *
+ * All tools are read-only (riskLevel: "low") and pass responses through
+ * contextGuard to prevent oversized payloads from consuming LLM context.
+ */
+
+import { applyContextGuard } from '../../contextGuard.js';
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function json(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+function auditLog(entry) {
+  console.error(`[AUDIT] ${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}`);
+}
+
+// ── Tool handlers ───────────────────────────────────────────────────────
+
+async function handleListTemplates(args, apiRequest) {
+  const t0 = Date.now();
+  const { limit = 20, type } = args;
+
+  const data = await apiRequest('/templates', { basePath: '/wp-json/elementor/v1' });
+  let list = Array.isArray(data) ? data : [];
+
+  // Filter by type if requested
+  if (type) {
+    list = list.filter(t => t.type === type);
+  }
+
+  // Apply limit
+  list = list.slice(0, limit);
+
+  const templates = list.map(t => ({
+    id: t.id,
+    title: t.title?.rendered ?? t.title ?? '',
+    type: t.type ?? 'unknown',
+    author: t.author ?? null,
+    date: t.date ?? null,
+    source: t.source ?? 'local',
+  }));
+
+  auditLog({ tool: 'elementor_list_templates', action: 'list_templates', status: 'success', latency_ms: Date.now() - t0, params: { count: templates.length, type: type || 'all' } });
+  return json({ total: templates.length, templates });
+}
+
+async function handleGetTemplate(args, apiRequest) {
+  const t0 = Date.now();
+  const { id } = args;
+
+  if (typeof id !== 'number' || !Number.isInteger(id) || id <= 0) {
+    throw new Error('Validation error: "id" must be a positive integer');
+  }
+
+  const data = await apiRequest(`/templates/${id}`, { basePath: '/wp-json/elementor/v1' });
+
+  const result = {
+    id: data.id ?? id,
+    title: data.title?.rendered ?? data.title ?? '',
+    type: data.type ?? 'unknown',
+    content: data.content ?? data.elements ?? data,
+  };
+
+  const guarded = applyContextGuard(result, { toolName: 'elementor_get_template', mode: 'compact', maxChars: 50000 });
+
+  auditLog({ tool: 'elementor_get_template', action: 'read_template', target: id, status: 'success', latency_ms: Date.now() - t0 });
+  return json(guarded);
+}
+
+async function handleGetPageData(args, apiRequest) {
+  const t0 = Date.now();
+  const { post_id } = args;
+
+  if (typeof post_id !== 'number' || !Number.isInteger(post_id) || post_id <= 0) {
+    throw new Error('Validation error: "post_id" must be a positive integer');
+  }
+
+  let data;
+  try {
+    data = await apiRequest(`/document/${post_id}`, { basePath: '/wp-json/elementor/v1' });
+  } catch {
+    // Fallback: read post meta _elementor_data via WP REST API
+    const post = await apiRequest(`/posts/${post_id}`, { basePath: '/wp-json/wp/v2' });
+    data = post?.meta?._elementor_data ?? null;
+  }
+
+  // Parse elements to extract widget info
+  const elements = Array.isArray(data?.elements) ? data.elements : (Array.isArray(data) ? data : []);
+  const widgetsUsed = new Set();
+  let elementsCount = 0;
+
+  function walkElements(els) {
+    for (const el of els) {
+      elementsCount++;
+      if (el.widgetType) widgetsUsed.add(el.widgetType);
+      if (el.elType === 'widget' && el.widgetType) widgetsUsed.add(el.widgetType);
+      if (Array.isArray(el.elements)) walkElements(el.elements);
+    }
+  }
+  walkElements(elements);
+
+  const result = {
+    post_id,
+    elementor_status: elements.length > 0 ? 'active' : 'inactive',
+    widgets_used: [...widgetsUsed],
+    elements_count: elementsCount,
+  };
+
+  const guarded = applyContextGuard(result, { toolName: 'elementor_get_page_data', mode: 'compact', maxChars: 50000 });
+
+  auditLog({ tool: 'elementor_get_page_data', action: 'read_page_data', target: post_id, status: 'success', latency_ms: Date.now() - t0 });
+  return json(guarded);
+}
+
+// ── Tool definitions (MCP format) ───────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'elementor_list_templates',
+    description: 'Use to list Elementor templates (page, section, block, popup). Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: { type: 'number', default: 20, description: 'Max templates to return (default 20)' },
+        type: { type: 'string', enum: ['page', 'section', 'block', 'popup'], description: 'Filter by template type (optional)' },
+      },
+    },
+    handler: handleListTemplates,
+  },
+  {
+    name: 'elementor_get_template',
+    description: 'Use to get full Elementor template content and elements. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Template ID' },
+      },
+      required: ['id'],
+    },
+    handler: handleGetTemplate,
+  },
+  {
+    name: 'elementor_get_page_data',
+    description: 'Use to get Elementor editor data for a post or page. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        post_id: { type: 'number', description: 'Post or page ID' },
+      },
+      required: ['post_id'],
+    },
+    handler: handleGetPageData,
+  },
+];
+
+// ── Adapter export ──────────────────────────────────────────────────────
+
+export const elementorAdapter = {
+  id: 'elementor',
+  namespace: 'elementor/v1',
+  riskLevel: 'low',
+  contextConfig: {
+    maxChars: 50000,
+    defaultMode: 'compact',
+    supportedModes: ['raw', 'compact', 'summary', 'ids_only'],
+  },
+  getTools: () => TOOLS,
+};

package/src/plugins/contextGuard.js

@@ -0,0 +1,57 @@
+/**
+ * Context Guard — prevents oversized responses from consuming LLM context.
+ *
+ * Every plugin-layer tool handler must pass its response through
+ * applyContextGuard() before returning. If the serialised JSON exceeds
+ * maxChars and the caller did not request mode='raw', the response is
+ * truncated and a warning is attached.
+ */
+
+/**
+ * @param {*} data           Raw response data (object, array, string…)
+ * @param {object} options
+ * @param {string} options.toolName   Tool name for logging
+ * @param {string} [options.mode]     Caller-requested mode (raw = no truncation)
+ * @param {number} [options.maxChars] Max serialised chars (default 50 000)
+ * @returns {*}  Original data or truncated wrapper
+ */
+export function applyContextGuard(data, options = {}) {
+  const { toolName = 'unknown', mode, maxChars = 50000 } = options;
+  const serialised = JSON.stringify(data);
+  const size = serialised.length;
+
+  if (size > maxChars && mode !== 'raw') {
+    console.error(JSON.stringify({
+      tool: toolName,
+      event: 'context_overflow',
+      size_chars: size,
+      max_chars: maxChars,
+      truncated: true,
+    }));
+
+    const truncated = serialised.substring(0, maxChars);
+
+    // Try to parse the truncated JSON back into an object; fall back to string
+    let parsed;
+    try {
+      // Find last complete JSON boundary to avoid broken UTF-8 / structure
+      const lastBrace = Math.max(truncated.lastIndexOf('}'), truncated.lastIndexOf(']'));
+      if (lastBrace > 0) {
+        parsed = JSON.parse(truncated.substring(0, lastBrace + 1));
+      } else {
+        parsed = truncated;
+      }
+    } catch {
+      parsed = truncated;
+    }
+
+    return {
+      _truncated: true,
+      _original_size: size,
+      _warning: "Response truncated. Use mode='raw' to get full data.",
+      data: parsed,
+    };
+  }
+
+  return data;
+}

package/src/plugins/registry.js

@@ -0,0 +1,94 @@
+/**
+ * Plugin Layer Registry — runtime detection and tool aggregation.
+ *
+ * Detects active WordPress plugins (ACF, Elementor, Astra) by inspecting
+ * the REST API namespaces at /wp-json/. Aggregates tools from active adapters
+ * and respects the WP_DISABLE_PLUGIN_LAYERS governance flag.
+ */
+
+const KNOWN_PLUGINS = [
+  { id: 'acf', namespace: 'acf/v3' },
+  { id: 'elementor', namespace: 'elementor/v1' },
+  { id: 'astra', namespace: 'astra/v1' },
+];
+
+export class PluginRegistry {
+  constructor() {
+    /** @type {Map<string, { id: string, namespace: string, version: string|null, tools: object[] }>} */
+    this.active = new Map();
+  }
+
+  /**
+   * Detect active plugins by calling GET /wp-json/ and inspecting namespaces.
+   *
+   * @param {Function} apiRequest  A function that takes (endpoint, options) and
+   *   returns parsed JSON. Must support basePath override to hit /wp-json/.
+   * @returns {Promise<{ active: string[], disabled_by_env: boolean }>}
+   */
+  async initialize(apiRequest) {
+    const discovery = await apiRequest('/', { basePath: '/wp-json' });
+    const namespaces = discovery?.namespaces || [];
+
+    for (const known of KNOWN_PLUGINS) {
+      if (namespaces.includes(known.namespace)) {
+        this.active.set(known.id, {
+          id: known.id,
+          namespace: known.namespace,
+          version: null,
+          tools: [],
+        });
+        console.error(JSON.stringify({
+          event: 'plugin_layer_detected',
+          plugin: known.id,
+          namespaces_found: namespaces.filter(ns => ns.startsWith(known.id)),
+        }));
+      }
+    }
+
+    return this.getSummary();
+  }
+
+  /**
+   * Return all tools from active adapters.
+   * Returns [] if WP_DISABLE_PLUGIN_LAYERS is true.
+   *
+   * @returns {object[]}
+   */
+  getAvailableTools() {
+    if (process.env.WP_DISABLE_PLUGIN_LAYERS === 'true') return [];
+    return [...this.active.values()].flatMap(a => a.tools ?? []);
+  }
+
+  /**
+   * Check whether a plugin is detected as active.
+   *
+   * @param {string} pluginId  e.g. "acf", "elementor", "astra"
+   * @returns {boolean}
+   */
+  isActive(pluginId) {
+    return this.active.has(pluginId);
+  }
+
+  /**
+   * Return a summary of the registry state.
+   *
+   * @returns {{ active: string[], disabled_by_env: boolean }}
+   */
+  getSummary() {
+    return {
+      active: [...this.active.keys()],
+      disabled_by_env: process.env.WP_DISABLE_PLUGIN_LAYERS === 'true',
+    };
+  }
+
+  /**
+   * Register an adapter's tools for a detected plugin.
+   *
+   * @param {string} pluginId
+   * @param {object[]} tools
+   */
+  registerTools(pluginId, tools) {
+    const entry = this.active.get(pluginId);
+    if (entry) entry.tools = tools;
+  }
+}