@adsim/wordpress-mcp-server 4.6.0 → 5.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adsim/wordpress-mcp-server",
-  "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.",
+  "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/shared/api.js

@@ -0,0 +1,79 @@
+/**
+ * WordPress REST API caller with retry, timeout & audit — extracted from index.js (v5.0.0 refactor Step A).
+ * index.js still contains its own copy; this will replace it in Step B+.
+ *
+ * NOTE: wpApiCall depends on runtime state (currentTarget, fetch, log, VERSION)
+ * that lives in index.js. For now this file exports the constants and a factory.
+ * The actual migration will wire these up in a later step.
+ */
+
+// ── API configuration constants ──
+export const MAX_RETRIES = parseInt(process.env.WP_MCP_MAX_RETRIES || '3', 10);
+export const TIMEOUT_MS = parseInt(process.env.WP_MCP_TIMEOUT || '30000', 10);
+export const RETRY_BASE_DELAY_MS = 1000;
+
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+/**
+ * Creates a wpApiCall function bound to dependencies.
+ * @param {Object} deps - { fetch, getActiveAuth, log, VERSION }
+ * @returns {Function} wpApiCall(endpoint, options)
+ */
+export function createWpApiCall({ fetch, getActiveAuth, log, VERSION }) {
+  return async function wpApiCall(endpoint, options = {}) {
+    const { url: baseUrl, auth: activeAuth } = getActiveAuth();
+    const basePath = options.basePath || '/wp-json/wp/v2';
+    const url = `${baseUrl}${basePath}${endpoint}`;
+    const method = options.method || 'GET';
+    const headers = {
+      'Authorization': `Basic ${activeAuth}`,
+      'User-Agent': `WordPress-MCP-Server/${VERSION}`,
+      ...options.headers
+    };
+    if (!options.isMultipart) headers['Content-Type'] = 'application/json';
+
+    let lastError;
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      const controller = new AbortController();
+      const tid = setTimeout(() => controller.abort(), TIMEOUT_MS);
+      try {
+        log.debug(`${method} ${endpoint} (${attempt}/${MAX_RETRIES})`);
+        const t0 = Date.now();
+        const fetchOpts = { method, headers, signal: controller.signal };
+        if (options.body) fetchOpts.body = options.body;
+        const response = await fetch(url, fetchOpts);
+        clearTimeout(tid);
+        log.debug(`${response.status} in ${Date.now() - t0}ms`);
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          const sc = response.status;
+          if (sc >= 400 && sc < 500 && sc !== 429) {
+            const hints = { 400: 'Bad Request', 401: 'Unauthorized', 403: 'Forbidden', 404: 'Not Found', 405: 'Method Not Allowed' };
+            throw new Error(`WP API ${sc}: ${hints[sc] || ''}\n${errorText}`);
+          }
+          lastError = new Error(`WP API ${sc}: ${errorText}`);
+          if (sc === 429) { await sleep(parseInt(response.headers.get('retry-after') || '5', 10) * 1000); continue; }
+          if (attempt < MAX_RETRIES) { await sleep(RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1)); continue; }
+          throw lastError;
+        }
+        const ct = response.headers.get('content-type');
+        if (!ct || !ct.includes('application/json')) return { success: true, status: response.status };
+        const jsonData = await response.json();
+        const wpTotal = response.headers.get('x-wp-total');
+        if (wpTotal !== null && jsonData !== null && typeof jsonData === 'object') {
+          Object.defineProperty(jsonData, '_wpTotal', { value: parseInt(wpTotal, 10), enumerable: false, configurable: true });
+          Object.defineProperty(jsonData, '_wpTotalPages', { value: parseInt(response.headers.get('x-wp-totalpages') || '0', 10), enumerable: false, configurable: true });
+        }
+        return jsonData;
+      } catch (error) {
+        clearTimeout(tid);
+        if (error.name === 'AbortError') lastError = new Error(`Timeout ${TIMEOUT_MS}ms`);
+        else if (error.message.includes('WP API 4')) throw error;
+        else lastError = error;
+        if (attempt < MAX_RETRIES) await sleep(RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1));
+      }
+    }
+    throw lastError || new Error(`Failed after ${MAX_RETRIES} attempts`);
+  };
+}

package/src/shared/audit.js

@@ -0,0 +1,39 @@
+/**
+ * Audit logging — extracted from index.js (v5.0.0 refactor Step A).
+ * index.js still contains its own copy; this will replace it in Step B+.
+ */
+
+const AUDIT_LOG = process.env.WP_AUDIT_LOG !== 'off';
+
+/**
+ * Log an audit record to stderr.
+ * @param {Object} entry - Audit entry fields
+ * @param {Object} [context] - Runtime context { currentTarget }
+ */
+export function auditLog(entry, context = {}) {
+  if (!AUDIT_LOG) return;
+  const record = {
+    timestamp: new Date().toISOString(),
+    tool: entry.tool,
+    target: entry.target || null,
+    target_type: entry.target_type || null,
+    action: entry.action || null,
+    status: entry.status,
+    latency_ms: entry.latency_ms,
+    site: entry.site || context.currentTargetName || 'default',
+    params: entry.params || {},
+    error: entry.error || null,
+    ...(entry.effective_controls ? { effective_controls: entry.effective_controls } : {})
+  };
+  console.error(`[AUDIT] ${JSON.stringify(record)}`);
+}
+
+/**
+ * Sanitize params for audit (remove content/body to keep logs small).
+ */
+export function sanitizeParams(args) {
+  const safe = { ...args };
+  if (safe.content && safe.content.length > 100) safe.content = `[${safe.content.length} chars]`;
+  if (safe.body) safe.body = '[binary]';
+  return safe;
+}

package/src/shared/context.js

@@ -0,0 +1,15 @@
+/**
+ * Runtime context — holds dependencies that require index.js state.
+ * Populated by index.js at startup via initRuntime().
+ * Handler modules import `rt` and destructure what they need.
+ *
+ * Uses Object.defineProperties to preserve getters for mutable state
+ * like currentTarget and targets.
+ */
+
+export const rt = {};
+
+export function initRuntime(deps) {
+  const descriptors = Object.getOwnPropertyDescriptors(deps);
+  Object.defineProperties(rt, descriptors);
+}

package/src/shared/governance.js

@@ -0,0 +1,98 @@
+/**
+ * Enterprise governance controls — extracted from index.js (v5.0.0 refactor Step A).
+ * index.js still contains its own copy; this will replace it in Step B+.
+ *
+ * NOTE: enforceReadOnly and getActiveControls depend on runtime state (currentTarget).
+ * For now these are exported as factories or standalone functions that accept context.
+ * The actual migration will wire these up in a later step.
+ */
+
+// ── Governance constants ──
+export const READ_ONLY = process.env.WP_READ_ONLY === 'true';
+export const DRAFT_ONLY = process.env.WP_DRAFT_ONLY === 'true';
+export const DISABLE_DELETE = process.env.WP_DISABLE_DELETE === 'true';
+export const DISABLE_PLUGIN_MANAGEMENT = process.env.WP_DISABLE_PLUGIN_MANAGEMENT === 'true';
+export const REQUIRE_APPROVAL = process.env.WP_REQUIRE_APPROVAL === 'true';
+export const CONFIRM_DESTRUCTIVE = process.env.WP_CONFIRM_DESTRUCTIVE === 'true';
+export const MAX_CALLS_PER_MINUTE = parseInt(process.env.WP_MAX_CALLS_PER_MINUTE || '0', 10);
+export const ALLOWED_TYPES = process.env.WP_ALLOWED_TYPES ? process.env.WP_ALLOWED_TYPES.split(',').map(s => s.trim()) : null;
+export const ALLOWED_STATUSES = process.env.WP_ALLOWED_STATUSES ? process.env.WP_ALLOWED_STATUSES.split(',').map(s => s.trim()) : null;
+export const AUDIT_LOG_ENABLED = process.env.WP_AUDIT_LOG !== 'off';
+export const VISUAL_STAGING = process.env.WP_VISUAL_STAGING === 'true';
+
+/**
+ * Compute active controls by merging global env vars with per-target overrides.
+ * @param {Object} [currentTarget] - The current target config (with optional .controls)
+ */
+export function getActiveControls(currentTarget = null) {
+  const tc = currentTarget?.controls || {};
+  const globalMaxCpm = parseInt(process.env.WP_MAX_CALLS_PER_MINUTE || '0', 10);
+  const targetMaxCpm = tc.max_calls_per_minute || 0;
+  let effectiveMaxCpm;
+  if (globalMaxCpm > 0 && targetMaxCpm > 0) effectiveMaxCpm = Math.min(globalMaxCpm, targetMaxCpm);
+  else if (globalMaxCpm > 0) effectiveMaxCpm = globalMaxCpm;
+  else if (targetMaxCpm > 0) effectiveMaxCpm = targetMaxCpm;
+  else effectiveMaxCpm = 0;
+
+  return {
+    read_only: process.env.WP_READ_ONLY === 'true' || tc.read_only === true,
+    draft_only: process.env.WP_DRAFT_ONLY === 'true' || tc.draft_only === true,
+    disable_delete: process.env.WP_DISABLE_DELETE === 'true' || tc.disable_delete === true,
+    disable_plugin_management: process.env.WP_DISABLE_PLUGIN_MANAGEMENT === 'true' || tc.disable_plugin_management === true,
+    require_approval: process.env.WP_REQUIRE_APPROVAL === 'true' || tc.require_approval === true,
+    confirm_destructive: process.env.WP_CONFIRM_DESTRUCTIVE === 'true' || tc.confirm_destructive === true,
+    max_calls_per_minute: effectiveMaxCpm,
+  };
+}
+
+/**
+ * Compute control sources (global vs target vs both).
+ * @param {Object} [currentTarget] - The current target config
+ */
+export function getControlSources(currentTarget = null) {
+  const tc = currentTarget?.controls || {};
+  const src = (g, t) => (g && t) ? 'both' : g ? 'global' : t ? 'target' : 'none';
+  const globalMaxCpm = parseInt(process.env.WP_MAX_CALLS_PER_MINUTE || '0', 10);
+  const targetMaxCpm = tc.max_calls_per_minute || 0;
+  return {
+    read_only_source: src(process.env.WP_READ_ONLY === 'true', tc.read_only === true),
+    draft_only_source: src(process.env.WP_DRAFT_ONLY === 'true', tc.draft_only === true),
+    disable_delete_source: src(process.env.WP_DISABLE_DELETE === 'true', tc.disable_delete === true),
+    disable_plugin_management_source: src(process.env.WP_DISABLE_PLUGIN_MANAGEMENT === 'true', tc.disable_plugin_management === true),
+    require_approval_source: src(process.env.WP_REQUIRE_APPROVAL === 'true', tc.require_approval === true),
+    confirm_destructive_source: src(process.env.WP_CONFIRM_DESTRUCTIVE === 'true', tc.confirm_destructive === true),
+    max_calls_per_minute_source: (globalMaxCpm > 0 && targetMaxCpm > 0) ? 'both' : (globalMaxCpm > 0 ? 'global' : (targetMaxCpm > 0 ? 'target' : 'none')),
+  };
+}
+
+/**
+ * Validate input arguments against a rules object.
+ */
+export function validateInput(args, rules) {
+  const errors = [];
+  for (const [field, rule] of Object.entries(rules)) {
+    const value = args[field];
+    if (rule.required && (value === undefined || value === null || value === '')) { errors.push(`"${field}" is required`); continue; }
+    if (value === undefined || value === null) continue;
+    if (rule.type === 'number') {
+      if (typeof value !== 'number' || isNaN(value)) errors.push(`"${field}" must be a number`);
+      else { if (rule.min !== undefined && value < rule.min) errors.push(`"${field}" >= ${rule.min}`); if (rule.max !== undefined && value > rule.max) errors.push(`"${field}" <= ${rule.max}`); }
+    }
+    if (rule.type === 'string' && typeof value !== 'string') errors.push(`"${field}" must be a string`);
+    else if (rule.type === 'string' && rule.enum && !rule.enum.includes(value)) errors.push(`"${field}" must be: ${rule.enum.join(', ')}`);
+    if (rule.type === 'array' && !Array.isArray(value)) errors.push(`"${field}" must be an array`);
+  }
+  if (errors.length > 0) throw new Error(`Validation:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+}
+
+/**
+ * Enforce read-only mode — throws if tool is a write tool and read_only is active.
+ * @param {string} toolName
+ * @param {Object} controls - Result of getActiveControls()
+ */
+export function enforceReadOnly(toolName, controls) {
+  const writeTools = ['wp_create_post', 'wp_update_post', 'wp_delete_post', 'wp_create_page', 'wp_update_page', 'wp_upload_media', 'wp_create_comment', 'wp_create_taxonomy_term', 'wp_update_seo_meta', 'wp_activate_plugin', 'wp_deactivate_plugin', 'wp_restore_revision', 'wp_delete_revision', 'wp_submit_for_review', 'wp_approve_post', 'wp_reject_post', 'wp_create_staging_draft', 'wp_merge_staging_to_live', 'wp_discard_staging_draft', 'wc_list_products', 'wc_get_product', 'wc_list_orders', 'wc_get_order', 'wc_list_customers', 'wc_inventory_alert', 'wc_order_intelligence', 'wc_seo_product_audit', 'wc_suggest_product_links', 'wc_update_product', 'wc_update_stock', 'wc_update_order_status', 'wp_create_template', 'wp_update_template', 'wp_delete_template', 'wp_create_template_part', 'wp_update_template_part', 'wp_delete_template_part', 'wp_update_global_styles', 'wp_create_block_pattern', 'wp_delete_block_pattern', 'wp_create_navigation_menu', 'wp_update_navigation_menu', 'wp_delete_navigation_menu', 'wp_update_widget', 'wp_delete_widget', 'wp_create_user', 'wp_update_user', 'wp_delete_user', 'wp_reset_user_password', 'wp_revoke_application_password', 'wp_bulk_update'];
+  if (controls.read_only && writeTools.includes(toolName)) {
+    throw new Error(`Blocked: Server is in READ-ONLY mode (WP_READ_ONLY=true). Tool "${toolName}" is not allowed.`);
+  }
+}

package/src/shared/utils.js

@@ -0,0 +1,148 @@
+/**
+ * Shared utility functions — extracted from index.js (v5.0.0 refactor Step A).
+ * index.js still contains its own copies; these will replace them in Step B+.
+ */
+
+// ── Compact JSON output ──
+const WP_COMPACT_JSON = process.env.WP_COMPACT_JSON !== 'false';
+
+export function json(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, WP_COMPACT_JSON ? 0 : 2) }] };
+}
+
+// ── HTML strip ──
+export function strip(html) {
+  return (html || '').replace(/<[^>]*>/g, '').trim();
+}
+
+// ── Pagination helper ──
+export function buildPaginationMeta(total, page, perPage) {
+  return {
+    page: parseInt(page),
+    per_page: parseInt(perPage),
+    total: parseInt(total),
+    total_pages: Math.ceil(parseInt(total) / parseInt(perPage)),
+    has_more: (parseInt(page) * parseInt(perPage)) < parseInt(total),
+    next_page: ((parseInt(page) * parseInt(perPage)) < parseInt(total)) ? parseInt(page) + 1 : null
+  };
+}
+
+// ── Gutenberg block validator ──
+export const DEPRECATED_BLOCKS = [
+  'core/subhead', 'core/text-columns', 'core/cover-image', 'core/button',
+  'core/blocks-gallery', 'core/latest-posts', 'core/categories',
+  'core/archives', 'core/calendar', 'core/tag-cloud'
+];
+
+export const SELF_CLOSING_BLOCKS = [
+  'core/separator', 'core/spacer', 'core/nextpage', 'core/more', 'core/missing'
+];
+
+export const NO_NEST_IN_SELF = [
+  'core/paragraph', 'core/heading', 'core/code', 'core/preformatted', 'core/verse'
+];
+
+export function validateBlocks(content, strict = false, fixSuggestions = true) {
+  const errors = [];
+  const warnings = [];
+  const suggestions = [];
+  const blockCounts = {};
+  const lines = content.split('\n');
+
+  const openStack = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+
+    let match;
+    const openRe = /<!--\s*wp:([a-z][a-z0-9-]*\/)?([a-z][a-z0-9-]*)\s*(\{.*?\})?\s*(\/)?-->/g;
+    while ((match = openRe.exec(line)) !== null) {
+      const ns = match[1] || 'core/';
+      const blockName = `${ns}${match[2]}`;
+      const attrJson = match[3];
+      const selfClosing = match[4] === '/';
+
+      blockCounts[blockName] = (blockCounts[blockName] || 0) + 1;
+
+      if (DEPRECATED_BLOCKS.includes(blockName)) {
+        warnings.push({ type: 'deprecated_block', block: blockName, message: `Block "${blockName}" is deprecated` });
+        if (fixSuggestions) suggestions.push({ issue: `Deprecated block "${blockName}"`, fix: `Replace with its modern equivalent` });
+      }
+
+      if (attrJson) {
+        try { JSON.parse(attrJson); } catch (e) {
+          errors.push({ type: 'malformed_json', block: blockName, line: lineNum, message: `Malformed JSON attributes in ${blockName}: ${e.message}` });
+          if (fixSuggestions) suggestions.push({ issue: `Invalid JSON in ${blockName} at line ${lineNum}`, fix: `Fix JSON syntax: ${attrJson}` });
+        }
+      } else if (strict && !selfClosing && !SELF_CLOSING_BLOCKS.includes(blockName)) {
+        errors.push({ type: 'missing_attributes', block: blockName, line: lineNum, message: `Block "${blockName}" has no attributes (strict mode)` });
+      }
+
+      if (openStack.length > 0 && NO_NEST_IN_SELF.includes(blockName)) {
+        const parent = openStack[openStack.length - 1];
+        if (NO_NEST_IN_SELF.includes(parent.name)) {
+          errors.push({ type: 'invalid_nesting', block: blockName, line: lineNum, message: `"${blockName}" cannot be nested inside "${parent.name}"` });
+          if (fixSuggestions) suggestions.push({ issue: `Invalid nesting at line ${lineNum}`, fix: `Close "${parent.name}" before opening "${blockName}"` });
+        }
+      }
+
+      if (!selfClosing) {
+        openStack.push({ name: blockName, line: lineNum });
+      }
+    }
+
+    const closeRe = /<!--\s*\/wp:([a-z][a-z0-9-]*\/)?([a-z][a-z0-9-]*)\s*-->/g;
+    while ((match = closeRe.exec(line)) !== null) {
+      const ns = match[1] || 'core/';
+      const closeName = `${ns}${match[2]}`;
+      if (openStack.length === 0) {
+        errors.push({ type: 'unexpected_close', block: closeName, line: lineNum, message: `Closing comment for "${closeName}" without matching opening` });
+      } else {
+        const top = openStack[openStack.length - 1];
+        if (top.name === closeName) {
+          openStack.pop();
+        } else {
+          errors.push({ type: 'mismatched_close', block: closeName, line: lineNum, message: `Expected closing for "${top.name}" (opened line ${top.line}), found "${closeName}"` });
+          if (fixSuggestions) suggestions.push({ issue: `Mismatched block at line ${lineNum}`, fix: `Close "${top.name}" before closing "${closeName}"` });
+        }
+      }
+    }
+  }
+
+  for (const open of openStack) {
+    errors.push({ type: 'unclosed_block', block: open.name, line: open.line, message: `Block "${open.name}" opened at line ${open.line} is never closed` });
+    if (fixSuggestions) suggestions.push({ issue: `Unclosed "${open.name}" at line ${open.line}`, fix: `Add <!-- /wp:${open.name.replace('core/', '')} --> after the block content` });
+  }
+
+  const htmlContent = content.replace(/<!--.*?-->/gs, '');
+  const voidElements = new Set(['area','base','br','col','embed','hr','img','input','link','meta','param','source','track','wbr']);
+  const openTags = [];
+  const tagRe = /<\/?([a-zA-Z][a-zA-Z0-9]*)[^>]*\/?>/g;
+  let match;
+  while ((match = tagRe.exec(htmlContent)) !== null) {
+    const fullMatch = match[0];
+    const tagName = match[1].toLowerCase();
+    if (voidElements.has(tagName) || fullMatch.endsWith('/>')) continue;
+    if (fullMatch.startsWith('</')) {
+      if (openTags.length > 0 && openTags[openTags.length - 1] === tagName) openTags.pop();
+    } else {
+      openTags.push(tagName);
+    }
+  }
+  for (const tag of openTags) {
+    warnings.push({ type: 'unclosed_html_tag', block: null, message: `HTML tag <${tag}> may not be properly closed` });
+  }
+
+  const blocksFound = Object.entries(blockCounts).map(([name, count]) => ({ name, count }));
+  const totalBlocks = blocksFound.reduce((s, b) => s + b.count, 0);
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    suggestions: fixSuggestions ? suggestions : undefined,
+    blocks_found: blocksFound,
+    summary: `${errors.length} error${errors.length !== 1 ? 's' : ''}, ${warnings.length} warning${warnings.length !== 1 ? 's' : ''} found in ${totalBlocks} block${totalBlocks !== 1 ? 's' : ''}`
+  };
+}

package/src/tools/comments.js

@@ -0,0 +1,50 @@
+// src/tools/comments.js — engagement tools (2)
+// Definitions + handlers (v5.0.0 refactor Step B+C)
+
+import { json, strip, buildPaginationMeta } from '../shared/utils.js';
+import { validateInput } from '../shared/governance.js';
+import { rt } from '../shared/context.js';
+
+export const definitions = [
+  { name: 'wp_list_comments', _category: 'engagement', description: 'Use to list comments filtered by post or status (approved/hold/spam). 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 }, post: { type: 'number' }, status: { type: 'string' }, orderby: { type: 'string', default: 'date_gmt' }, order: { type: 'string', default: 'desc' }, 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_create_comment', _category: 'engagement', description: 'Use to post a comment or reply on any post. Write — blocked by WP_READ_ONLY.', inputSchema: { type: 'object', properties: { post: { type: 'number' }, content: { type: 'string' }, parent: { type: 'number', default: 0 }, author_name: { type: 'string' }, author_email: { type: 'string' }, status: { type: 'string', default: 'approved' } }, required: ['post', 'content'] }}
+];
+
+export const handlers = {};
+
+handlers['wp_list_comments'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  const { per_page = 10, page = 1, post, status, orderby = 'date_gmt', order = 'desc', search, mode = 'full' } = args;
+  let ep = `/comments?per_page=${per_page}&page=${page}&orderby=${orderby}&order=${order}`;
+  if (post) ep += `&post=${post}`; if (status) ep += `&status=${status}`; if (search) ep += `&search=${encodeURIComponent(search)}`;
+  const comments = await wpApiCall(ep);
+  const cmtPg = comments._wpTotal !== undefined ? buildPaginationMeta(comments._wpTotal, page, per_page) : undefined;
+  if (mode === 'ids_only') {
+    result = json({ total: comments.length, page, mode: 'ids_only', ids: comments.map(c => c.id), ...(cmtPg && { pagination: cmtPg }) });
+    auditLog({ tool: name, action: 'list', status: 'success', latency_ms: Date.now() - t0 });
+    return result;
+  }
+  if (mode === 'summary') {
+    result = json({ total: comments.length, page, mode: 'summary', comments: comments.map(c => ({ id: c.id, post: c.post, author_name: c.author_name, date: c.date, status: c.status })), ...(cmtPg && { pagination: cmtPg }) });
+    auditLog({ tool: name, action: 'list', status: 'success', latency_ms: Date.now() - t0 });
+    return result;
+  }
+  result = json({ total: comments.length, page, comments: comments.map(c => ({ id: c.id, post: c.post, parent: c.parent, author_name: c.author_name, date: c.date, status: c.status, content: strip(c.content.rendered).substring(0, 300), link: c.link })), ...(cmtPg && { pagination: cmtPg }) });
+  auditLog({ tool: name, action: 'list', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wp_create_comment'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { post: { type: 'number', required: true }, content: { type: 'string', required: true } });
+  const { post, content, parent = 0, author_name, author_email, status = 'approved' } = args;
+  const data = { post, content, parent, status };
+  if (author_name) data.author_name = author_name; if (author_email) data.author_email = author_email;
+  const c = await wpApiCall('/comments', { method: 'POST', body: JSON.stringify(data) });
+  result = json({ success: true, message: 'Comment created', comment: { id: c.id, post: c.post, status: c.status, content: strip(c.content.rendered).substring(0, 200) } });
+  auditLog({ tool: name, target: c.id, target_type: 'comment', action: 'create', status: 'success', latency_ms: Date.now() - t0, params: { post } });
+  return result;
+};