@adsim/wordpress-mcp-server 4.5.1 → 5.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adsim/wordpress-mcp-server",
-  "version": "4.5.1",
-  "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.",
+  "version": "5.1.0",
+  "description": "Enterprise WordPress MCP Server — 180 tools, modular architecture, governance, audit trail, WooCommerce, Schema.org, multilingual.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -24,18 +24,26 @@
     "claude",
     "ai",
     "automation",
-    "cms"
+    "cms",
+    "seo",
+    "woocommerce",
+    "schema-org",
+    "multilingual",
+    "security-audit",
+    "performance",
+    "enterprise",
+    "full-site-editing"
   ],
   "author": "Georges Cordewiener <georges@adsim.be>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/adsimbe/wordpress-mcp-server.git"
+    "url": "git+https://github.com/GeorgesAdSim/wordpress-mcp-server.git"
   },
   "bugs": {
-    "url": "https://github.com/adsimbe/wordpress-mcp-server/issues"
+    "url": "https://github.com/GeorgesAdSim/wordpress-mcp-server/issues"
   },
-  "homepage": "https://github.com/adsimbe/wordpress-mcp-server#readme",
+  "homepage": "https://github.com/GeorgesAdSim/wordpress-mcp-server#readme",
   "engines": {
     "node": ">=18.0.0"
   },

package/src/data/plugin-performance-data.json

@@ -0,0 +1,59 @@
+{
+  "_meta": {
+    "version": "1.0.0",
+    "description": "Estimated performance impact of common WordPress plugins. Impact scores are relative (1=minimal, 5=heavy). Data compiled from WebPageTest benchmarks, Query Monitor profiling, and community reports.",
+    "last_updated": "2025-03-01"
+  },
+  "plugins": {
+    "elementor/elementor.php": { "name": "Elementor", "impact": 4, "category": "page-builder", "notes": "Heavy DOM, inline CSS, multiple JS files. Use with landing pages only if possible." },
+    "elementor-pro/elementor-pro.php": { "name": "Elementor Pro", "impact": 5, "category": "page-builder", "notes": "Adds motion effects, popups, form widgets. Significant render cost." },
+    "js_composer/js_composer.php": { "name": "WPBakery Page Builder", "impact": 5, "category": "page-builder", "notes": "Legacy shortcode-based builder. Heavy inline styles and scripts." },
+    "beaver-builder-lite-version/fl-builder.php": { "name": "Beaver Builder", "impact": 3, "category": "page-builder", "notes": "Cleaner output than Elementor. Moderate JS footprint." },
+    "divi-builder/divi-builder.php": { "name": "Divi Builder", "impact": 5, "category": "page-builder", "notes": "Very heavy CSS and JS. One of the heaviest page builders." },
+    "wordpress-seo/wp-seo.php": { "name": "Yoast SEO", "impact": 2, "category": "seo", "notes": "Schema output and sitemap generation. Moderate admin overhead." },
+    "seo-by-rank-math/rank-math.php": { "name": "Rank Math", "impact": 2, "category": "seo", "notes": "Similar to Yoast. Slightly leaner frontend output." },
+    "wp-seopress/seopress.php": { "name": "SEOPress", "impact": 1, "category": "seo", "notes": "Lightweight SEO plugin with minimal frontend impact." },
+    "all-in-one-seo-pack/all_in_one_seo_pack.php": { "name": "All in One SEO", "impact": 2, "category": "seo", "notes": "Moderate impact, similar to Yoast." },
+    "woocommerce/woocommerce.php": { "name": "WooCommerce", "impact": 4, "category": "ecommerce", "notes": "Large plugin with many DB queries. Cart fragments AJAX is a known bottleneck." },
+    "woocommerce-payments/woocommerce-payments.php": { "name": "WooCommerce Payments", "impact": 2, "category": "ecommerce", "notes": "External Stripe JS loaded on checkout." },
+    "contact-form-7/wp-contact-form-7.php": { "name": "Contact Form 7", "impact": 2, "category": "forms", "notes": "Loads CSS/JS on all pages by default. Use conditional loading." },
+    "wpforms-lite/wpforms.php": { "name": "WPForms Lite", "impact": 2, "category": "forms", "notes": "Loads assets only on pages with forms (better than CF7 defaults)." },
+    "gravityforms/gravityforms.php": { "name": "Gravity Forms", "impact": 2, "category": "forms", "notes": "Premium form plugin. Moderate impact, conditional loading available." },
+    "ninja-forms/ninja-forms.php": { "name": "Ninja Forms", "impact": 3, "category": "forms", "notes": "React-based frontend can be heavy. Multiple JS bundles." },
+    "wordfence/wordfence.php": { "name": "Wordfence", "impact": 3, "category": "security", "notes": "Filesystem scanning and firewall rules add server-side latency. Minimal frontend impact." },
+    "better-wp-security/better-wp-security.php": { "name": "iThemes Security", "impact": 2, "category": "security", "notes": "Moderate server-side overhead for brute force protection and scanning." },
+    "sucuri-scanner/sucuri.php": { "name": "Sucuri Security", "impact": 2, "category": "security", "notes": "File integrity monitoring. Low frontend impact when using CDN firewall." },
+    "all-in-one-wp-security-and-firewall/wp-security.php": { "name": "All In One WP Security", "impact": 2, "category": "security", "notes": "Feature-rich security plugin. Moderate DB overhead." },
+    "wp-rocket/wp-rocket.php": { "name": "WP Rocket", "impact": -3, "category": "performance", "notes": "Page caching, CSS/JS minification, lazy loading. Significant positive impact." },
+    "w3-total-cache/w3-total-cache.php": { "name": "W3 Total Cache", "impact": -2, "category": "performance", "notes": "Complex caching plugin. Positive impact when configured correctly." },
+    "litespeed-cache/litespeed-cache.php": { "name": "LiteSpeed Cache", "impact": -3, "category": "performance", "notes": "Server-level cache integration. Excellent performance on LiteSpeed servers." },
+    "wp-super-cache/wp-cache.php": { "name": "WP Super Cache", "impact": -2, "category": "performance", "notes": "Simple page caching. Good basic performance improvement." },
+    "autoptimize/autoptimize.php": { "name": "Autoptimize", "impact": -2, "category": "performance", "notes": "CSS/JS minification and concatenation. Good complement to caching plugins." },
+    "wp-fastest-cache/wpFastestCache.php": { "name": "WP Fastest Cache", "impact": -2, "category": "performance", "notes": "Simple caching with minification. Easy to configure." },
+    "jetpack/jetpack.php": { "name": "Jetpack", "impact": 4, "category": "multi-purpose", "notes": "Loads many modules by default. External API calls on every page load. Disable unused modules." },
+    "jetpack-boost/jetpack-boost.php": { "name": "Jetpack Boost", "impact": -2, "category": "performance", "notes": "Lightweight performance module. CSS optimization and lazy images." },
+    "akismet/akismet.php": { "name": "Akismet", "impact": 1, "category": "anti-spam", "notes": "External API call for comment processing. Minimal frontend impact." },
+    "classic-editor/classic-editor.php": { "name": "Classic Editor", "impact": 0, "category": "editor", "notes": "Disables Gutenberg. No frontend impact." },
+    "advanced-custom-fields/acf.php": { "name": "Advanced Custom Fields", "impact": 1, "category": "custom-fields", "notes": "Minimal frontend impact. Admin-side overhead for field rendering." },
+    "advanced-custom-fields-pro/acf.php": { "name": "ACF Pro", "impact": 1, "category": "custom-fields", "notes": "Same as ACF with additional field types. Low impact." },
+    "revslider/revslider.php": { "name": "Slider Revolution", "impact": 5, "category": "slider", "notes": "Very heavy. Large JS/CSS payload, render-blocking. Consider alternatives." },
+    "LayerSlider/layerslider.php": { "name": "LayerSlider", "impact": 4, "category": "slider", "notes": "Heavy animation library. Significant CLS and LCP impact." },
+    "smart-slider-3/smart-slider-3.php": { "name": "Smart Slider 3", "impact": 3, "category": "slider", "notes": "Moderate impact. Lazy loading available." },
+    "wp-smushit/wp-smush.php": { "name": "Smush", "impact": -1, "category": "image-optimization", "notes": "Image compression and lazy loading. Positive impact on image-heavy sites." },
+    "imagify/imagify.php": { "name": "Imagify", "impact": -1, "category": "image-optimization", "notes": "Image optimization with WebP conversion. Reduces page weight." },
+    "shortpixel-image-optimiser/wp-shortpixel.php": { "name": "ShortPixel", "impact": -1, "category": "image-optimization", "notes": "Image compression service. Low overhead, good optimization." },
+    "ewww-image-optimizer/ewww-image-optimizer.php": { "name": "EWWW Image Optimizer", "impact": -1, "category": "image-optimization", "notes": "Local and cloud image optimization. WebP support." },
+    "google-analytics-for-wordpress/googleanalytics.php": { "name": "MonsterInsights", "impact": 3, "category": "analytics", "notes": "Loads GA script plus its own tracking layer. Use native GA tag instead." },
+    "google-site-kit/google-site-kit.php": { "name": "Google Site Kit", "impact": 2, "category": "analytics", "notes": "Admin dashboard overhead. Minimal frontend impact if using native GA tag." },
+    "mailchimp-for-wp/mailchimp-for-wp.php": { "name": "MC4WP Mailchimp", "impact": 1, "category": "email-marketing", "notes": "Minimal impact. Loads form assets conditionally." },
+    "the-events-calendar/the-events-calendar.php": { "name": "The Events Calendar", "impact": 3, "category": "events", "notes": "Custom post type with complex queries. Moderate frontend overhead." },
+    "tablepress/tablepress.php": { "name": "TablePress", "impact": 2, "category": "content", "notes": "DataTables JS library loaded on table pages. Moderate impact." },
+    "updraftplus/updraftplus.php": { "name": "UpdraftPlus", "impact": 1, "category": "backup", "notes": "Runs on cron schedule. No frontend impact during normal browsing." },
+    "duplicator/duplicator.php": { "name": "Duplicator", "impact": 0, "category": "backup", "notes": "Only active during migrations. Zero runtime impact." },
+    "redirection/redirection.php": { "name": "Redirection", "impact": 1, "category": "seo", "notes": "DB query per request for redirect rules. Minimal for small rule sets." },
+    "broken-link-checker/broken-link-checker.php": { "name": "Broken Link Checker", "impact": 4, "category": "seo", "notes": "Background scanning causes high server load. Use sparingly or via CLI." },
+    "regenerate-thumbnails/regenerate-thumbnails.php": { "name": "Regenerate Thumbnails", "impact": 0, "category": "media", "notes": "Only active when running regeneration. Zero runtime impact." },
+    "wordpress-popular-posts/wordpress-popular-posts.php": { "name": "WordPress Popular Posts", "impact": 3, "category": "content", "notes": "DB writes on every page view for tracking. Use caching or external tracking." },
+    "amp/amp.php": { "name": "AMP", "impact": 2, "category": "performance", "notes": "Generates AMP versions. Can conflict with other plugins. Mixed impact." }
+  }
+}

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;
+}