@adsim/wordpress-mcp-server 4.5.1 → 5.1.0

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

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