@adsim/wordpress-mcp-server 5.4.0 → 5.5.0

package/companion/mcp-diagnostics.php

@@ -1,8 +1,8 @@
 <?php
 /**
  * Plugin Name: MCP Diagnostics Companion
- * Description: Exposes secure REST endpoints for WordPress MCP Server diagnostics (debug log, cron events, transients, hooks).
- * Version: 1.0.0
+ * Description: Exposes secure REST endpoints for WordPress MCP Server diagnostics (debug log, cron events, transients, hooks) and Elementor link insertion.
+ * Version: 1.1.0
  * Requires PHP: 7.4
  * Author: AdSim
  * License: MIT
@@ -272,6 +272,75 @@ function mcp_diagnostics_register_routes() {
 			),
 		),
 	) );
+
+	// ── Elementor: read data + insert link into widget content ──
+	// The _elementor_* meta is protected (underscore prefix): its values are
+	// hidden from the REST API even with context=edit, and post_content
+	// writes are regenerated from _elementor_data. These endpoints are the
+	// only reliable read/write channel for Elementor-built pages.
+	register_rest_route( $namespace, '/elementor/data/(?P<post_id>\d+)', array(
+		'methods'             => 'GET',
+		'callback'            => 'mcp_elementor_data_get',
+		'permission_callback' => 'mcp_diagnostics_schema_permission_check',
+		'args'                => array(
+			'post_id' => array(
+				'type'              => 'integer',
+				'required'          => true,
+				'sanitize_callback' => 'absint',
+			),
+		),
+	) );
+
+	register_rest_route( $namespace, '/elementor/insert-link/(?P<post_id>\d+)', array(
+		'methods'             => 'POST',
+		'callback'            => 'mcp_elementor_insert_link',
+		'permission_callback' => 'mcp_diagnostics_schema_permission_check',
+		'args'                => array(
+			'post_id' => array(
+				'type'              => 'integer',
+				'required'          => true,
+				'sanitize_callback' => 'absint',
+			),
+			// No sanitize_callback: the needle must match the stored widget
+			// HTML byte-for-byte (sanitizing would break entity/tag matching).
+			'exact_text' => array(
+				'type'     => 'string',
+				'required' => true,
+			),
+			'link_url' => array(
+				'type'     => 'string',
+				'required' => true,
+			),
+		),
+	) );
+
+	register_rest_route( $namespace, '/elementor/update-widget/(?P<post_id>\d+)', array(
+		'methods'             => 'POST',
+		'callback'            => 'mcp_elementor_update_widget',
+		'permission_callback' => 'mcp_diagnostics_schema_permission_check',
+		'args'                => array(
+			'post_id' => array(
+				'type'              => 'integer',
+				'required'          => true,
+				'sanitize_callback' => 'absint',
+			),
+			'widget_id' => array(
+				'type'              => 'string',
+				'required'          => true,
+				'sanitize_callback' => 'sanitize_text_field',
+			),
+			'setting_key' => array(
+				'type'              => 'string',
+				'required'          => true,
+				'sanitize_callback' => 'sanitize_key',
+			),
+			// Raw HTML value (rollback restores the exact previous content).
+			'value' => array(
+				'type'     => 'string',
+				'required' => true,
+			),
+		),
+	) );
 }
 
 /**
@@ -1347,3 +1416,323 @@ function mcp_diagnostics_wc_abandoned_carts( $request ) {
 	// No source available
 	return new WP_REST_Response( array( 'available' => false ), 200 );
 }
+
+// ============================================================
+// Elementor — data read + targeted link insertion
+// ============================================================
+
+/**
+ * Widget settings that hold user-visible HTML/text, per widget type.
+ * Only these settings can be searched and modified. Extensible via the
+ * mcp_elementor_editable_settings filter.
+ */
+function mcp_elementor_editable_settings() {
+	return apply_filters( 'mcp_elementor_editable_settings', array(
+		'text-editor' => array( 'editor' ),
+	) );
+}
+
+/**
+ * Load and validate the Elementor context for a post.
+ * Returns array( post, elements ) or WP_Error.
+ */
+function mcp_elementor_load_context( $post_id, $require_write = false ) {
+	$post = get_post( $post_id );
+	if ( ! $post ) {
+		return new WP_Error( 'not_found', __( 'Post not found.' ), array( 'status' => 404 ) );
+	}
+	if ( $require_write && ! current_user_can( 'edit_post', $post_id ) ) {
+		return new WP_Error( 'rest_forbidden', __( 'You cannot edit this post.' ), array( 'status' => 403 ) );
+	}
+	if ( ! class_exists( '\Elementor\Plugin' ) ) {
+		return new WP_Error( 'elementor_inactive', __( 'Elementor is not active on this site.' ), array( 'status' => 501 ) );
+	}
+	if ( get_post_meta( $post_id, '_elementor_edit_mode', true ) !== 'builder' ) {
+		return new WP_Error( 'not_elementor', __( 'This post is not built with Elementor.' ), array( 'status' => 409 ) );
+	}
+	$raw = get_post_meta( $post_id, '_elementor_data', true );
+	if ( empty( $raw ) ) {
+		return new WP_Error( 'no_elementor_data', __( 'No Elementor data found for this post.' ), array( 'status' => 409 ) );
+	}
+	$elements = is_array( $raw ) ? $raw : json_decode( $raw, true );
+	if ( ! is_array( $elements ) ) {
+		return new WP_Error( 'corrupt_elementor_data', __( 'Elementor data is not valid JSON.' ), array( 'status' => 500 ) );
+	}
+	return array( 'post' => $post, 'elements' => $elements );
+}
+
+/**
+ * Recursively collect occurrences of $needle inside editable widget settings.
+ * Each match: widget_id, widget_type, setting_key, pos, html, path (list of
+ * child indices from the root, each level descending through ['elements']).
+ */
+function mcp_elementor_find_occurrences( $elements, $needle, $path = array() ) {
+	$editable = mcp_elementor_editable_settings();
+	$matches  = array();
+
+	foreach ( $elements as $i => $el ) {
+		if ( ! is_array( $el ) ) {
+			continue;
+		}
+		$el_path     = array_merge( $path, array( $i ) );
+		$widget_type = isset( $el['widgetType'] ) ? $el['widgetType'] : null;
+
+		if ( $widget_type && isset( $editable[ $widget_type ] ) ) {
+			foreach ( $editable[ $widget_type ] as $key ) {
+				$html = isset( $el['settings'][ $key ] ) && is_string( $el['settings'][ $key ] ) ? $el['settings'][ $key ] : '';
+				if ( '' === $html ) {
+					continue;
+				}
+				$offset = 0;
+				while ( false !== ( $pos = strpos( $html, $needle, $offset ) ) ) {
+					$matches[] = array(
+						'widget_id'   => isset( $el['id'] ) ? $el['id'] : '',
+						'widget_type' => $widget_type,
+						'setting_key' => $key,
+						'pos'         => $pos,
+						'html'        => $html,
+						'path'        => $el_path,
+					);
+					$offset = $pos + strlen( $needle );
+				}
+			}
+		}
+
+		if ( ! empty( $el['elements'] ) && is_array( $el['elements'] ) ) {
+			$matches = array_merge( $matches, mcp_elementor_find_occurrences( $el['elements'], $needle, $el_path ) );
+		}
+	}
+
+	return $matches;
+}
+
+/**
+ * Apply $callback (by reference) to the element addressed by $path.
+ */
+function mcp_elementor_apply_at_path( &$elements, $path, $callback ) {
+	$ref = &$elements;
+	foreach ( $path as $depth => $index ) {
+		if ( $depth > 0 ) {
+			$ref = &$ref['elements'];
+		}
+		if ( ! isset( $ref[ $index ] ) ) {
+			return false;
+		}
+		$ref = &$ref[ $index ];
+	}
+	$callback( $ref );
+	return true;
+}
+
+/**
+ * True when the occurrence at $pos in $html sits inside an existing <a> tag.
+ */
+function mcp_elementor_inside_link( $html, $pos ) {
+	$before    = substr( $html, 0, $pos );
+	$open_pos  = strripos( $before, '<a' );
+	$close_pos = strripos( $before, '</a>' );
+	return ( false !== $open_pos ) && ( false === $close_pos || $close_pos < $open_pos );
+}
+
+/**
+ * Context snippet around an insertion point (for audit / preview).
+ */
+function mcp_elementor_snippet( $html, $pos, $len, $context = 80 ) {
+	$start = max( 0, $pos - $context );
+	return substr( $html, $start, ( $pos - $start ) + $len + $context );
+}
+
+/**
+ * Persist modified elements through Elementor's document API (regenerates
+ * CSS and fires Elementor save hooks). Returns true or WP_Error.
+ */
+function mcp_elementor_save_elements( $post_id, $elements ) {
+	try {
+		$document = \Elementor\Plugin::$instance->documents->get( $post_id, false );
+		if ( ! $document ) {
+			return new WP_Error( 'document_unavailable', __( 'Elementor document could not be loaded.' ), array( 'status' => 500 ) );
+		}
+		$saved = $document->save( array( 'elements' => $elements ) );
+		if ( ! $saved ) {
+			return new WP_Error( 'save_failed', __( 'Elementor refused to save the document.' ), array( 'status' => 500 ) );
+		}
+	} catch ( \Throwable $e ) {
+		return new WP_Error( 'save_exception', $e->getMessage(), array( 'status' => 500 ) );
+	}
+	// Force CSS regeneration on next render.
+	delete_post_meta( $post_id, '_elementor_css' );
+	return true;
+}
+
+/**
+ * GET /mcp-diagnostics/v1/elementor/data/{post_id}
+ * Reliable read channel for _elementor_data (hidden from the REST API).
+ */
+function mcp_elementor_data_get( $request ) {
+	$post_id = $request->get_param( 'post_id' );
+	$post    = get_post( $post_id );
+
+	if ( ! $post ) {
+		return new WP_Error( 'not_found', __( 'Post not found.' ), array( 'status' => 404 ) );
+	}
+
+	$raw      = get_post_meta( $post_id, '_elementor_data', true );
+	$elements = is_array( $raw ) ? $raw : ( $raw ? json_decode( $raw, true ) : null );
+
+	return new WP_REST_Response( array(
+		'post_id'   => $post_id,
+		'edit_mode' => get_post_meta( $post_id, '_elementor_edit_mode', true ) ?: null,
+		'elements'  => is_array( $elements ) ? $elements : array(),
+	), 200 );
+}
+
+/**
+ * POST /mcp-diagnostics/v1/elementor/insert-link/{post_id}
+ * Wrap ONE exact occurrence of exact_text with <a href="link_url"> inside an
+ * editable widget. Refuses on: text not found, ambiguous (multiple
+ * occurrences), or already inside a link.
+ */
+function mcp_elementor_insert_link( $request ) {
+	if ( mcp_diagnostics_is_read_only() ) {
+		return new WP_Error( 'read_only', __( 'Site is in read-only mode.' ), array( 'status' => 403 ) );
+	}
+
+	$post_id    = $request->get_param( 'post_id' );
+	$exact_text = (string) $request->get_param( 'exact_text' );
+	$link_url   = esc_url_raw( (string) $request->get_param( 'link_url' ) );
+
+	if ( '' === trim( $exact_text ) || strlen( $exact_text ) > 500 ) {
+		return new WP_Error( 'invalid_text', __( 'exact_text must be a non-empty string of at most 500 characters.' ), array( 'status' => 400 ) );
+	}
+	if ( '' === $link_url || ! preg_match( '#^https?://#i', $link_url ) ) {
+		return new WP_Error( 'invalid_url', __( 'link_url must be a valid http(s) URL.' ), array( 'status' => 400 ) );
+	}
+
+	$ctx = mcp_elementor_load_context( $post_id, true );
+	if ( is_wp_error( $ctx ) ) {
+		return $ctx;
+	}
+	$elements = $ctx['elements'];
+
+	$matches = mcp_elementor_find_occurrences( $elements, $exact_text );
+	if ( 0 === count( $matches ) ) {
+		return new WP_Error( 'text_not_found', __( 'exact_text was not found in any editable Elementor widget.' ), array( 'status' => 404 ) );
+	}
+	if ( count( $matches ) > 1 ) {
+		return new WP_Error( 'ambiguous_text', sprintf(
+			/* translators: %d: occurrence count */
+			__( 'exact_text appears %d times — cannot insert unambiguously.' ),
+			count( $matches )
+		), array( 'status' => 409, 'occurrences' => count( $matches ) ) );
+	}
+
+	$m = $matches[0];
+	if ( mcp_elementor_inside_link( $m['html'], $m['pos'] ) ) {
+		return new WP_Error( 'already_linked', __( 'exact_text is already inside an <a> tag.' ), array( 'status' => 409 ) );
+	}
+
+	$linked   = '<a href="' . esc_url( $link_url ) . '">' . $exact_text . '</a>';
+	$new_html = substr_replace( $m['html'], $linked, $m['pos'], strlen( $exact_text ) );
+
+	$setting_key = $m['setting_key'];
+	$applied     = mcp_elementor_apply_at_path( $elements, $m['path'], function ( &$el ) use ( $setting_key, $new_html ) {
+		$el['settings'][ $setting_key ] = $new_html;
+	} );
+	if ( ! $applied ) {
+		return new WP_Error( 'apply_failed', __( 'Could not address the target widget in the Elementor tree.' ), array( 'status' => 500 ) );
+	}
+
+	$saved = mcp_elementor_save_elements( $post_id, $elements );
+	if ( is_wp_error( $saved ) ) {
+		return $saved;
+	}
+
+	return new WP_REST_Response( array(
+		'post_id'        => $post_id,
+		'status'         => 'link_inserted',
+		'widget_id'      => $m['widget_id'],
+		'widget_type'    => $m['widget_type'],
+		'setting_key'    => $m['setting_key'],
+		'link_url'       => $link_url,
+		'anchor_text'    => $exact_text,
+		'snippet_before' => mcp_elementor_snippet( $m['html'], $m['pos'], strlen( $exact_text ) ),
+		'snippet_after'  => mcp_elementor_snippet( $new_html, $m['pos'], strlen( $linked ) ),
+		'rollback'       => array(
+			'widget_id'      => $m['widget_id'],
+			'setting_key'    => $m['setting_key'],
+			'previous_value' => $m['html'],
+		),
+	), 200 );
+}
+
+/**
+ * POST /mcp-diagnostics/v1/elementor/update-widget/{post_id}
+ * Set one editable setting of one widget (rollback primitive for
+ * insert-link: restore rollback.previous_value).
+ */
+function mcp_elementor_update_widget( $request ) {
+	if ( mcp_diagnostics_is_read_only() ) {
+		return new WP_Error( 'read_only', __( 'Site is in read-only mode.' ), array( 'status' => 403 ) );
+	}
+
+	$post_id     = $request->get_param( 'post_id' );
+	$widget_id   = (string) $request->get_param( 'widget_id' );
+	$setting_key = (string) $request->get_param( 'setting_key' );
+	$value       = (string) $request->get_param( 'value' );
+
+	$ctx = mcp_elementor_load_context( $post_id, true );
+	if ( is_wp_error( $ctx ) ) {
+		return $ctx;
+	}
+	$elements = $ctx['elements'];
+
+	// Locate the widget and check the setting is editable for its type.
+	$editable = mcp_elementor_editable_settings();
+	$found    = null;
+	$walk     = function ( $els, $path ) use ( &$walk, &$found, $widget_id ) {
+		foreach ( $els as $i => $el ) {
+			if ( ! is_array( $el ) || $found ) {
+				continue;
+			}
+			$el_path = array_merge( $path, array( $i ) );
+			if ( isset( $el['id'] ) && $el['id'] === $widget_id ) {
+				$found = array( 'el' => $el, 'path' => $el_path );
+				return;
+			}
+			if ( ! empty( $el['elements'] ) && is_array( $el['elements'] ) ) {
+				$walk( $el['elements'], $el_path );
+			}
+		}
+	};
+	$walk( $elements, array() );
+
+	if ( ! $found ) {
+		return new WP_Error( 'widget_not_found', __( 'No element with this widget_id.' ), array( 'status' => 404 ) );
+	}
+	$widget_type = isset( $found['el']['widgetType'] ) ? $found['el']['widgetType'] : null;
+	if ( ! $widget_type || ! isset( $editable[ $widget_type ] ) || ! in_array( $setting_key, $editable[ $widget_type ], true ) ) {
+		return new WP_Error( 'setting_not_editable', __( 'This setting is not editable for this widget type.' ), array( 'status' => 400 ) );
+	}
+
+	$previous = isset( $found['el']['settings'][ $setting_key ] ) ? $found['el']['settings'][ $setting_key ] : '';
+	$applied  = mcp_elementor_apply_at_path( $elements, $found['path'], function ( &$el ) use ( $setting_key, $value ) {
+		$el['settings'][ $setting_key ] = $value;
+	} );
+	if ( ! $applied ) {
+		return new WP_Error( 'apply_failed', __( 'Could not address the target widget in the Elementor tree.' ), array( 'status' => 500 ) );
+	}
+
+	$saved = mcp_elementor_save_elements( $post_id, $elements );
+	if ( is_wp_error( $saved ) ) {
+		return $saved;
+	}
+
+	return new WP_REST_Response( array(
+		'post_id'        => $post_id,
+		'status'         => 'widget_updated',
+		'widget_id'      => $widget_id,
+		'widget_type'    => $widget_type,
+		'setting_key'    => $setting_key,
+		'previous_value' => is_string( $previous ) ? $previous : '',
+	), 200 );
+}

package/index.js

@@ -22,6 +22,7 @@ import { calculateReadabilityScore, extractHeadingsOutline, detectContentSection
 import { detectSeoPlugin, getRenderedHead, parseRenderedHead } from './src/pluginDetector.js';
 import { PluginRegistry } from './src/plugins/registry.js';
 import { acfAdapter } from './src/plugins/adapters/acf/acfAdapter.js';
+import { elementorAdapter } from './src/plugins/adapters/elementor/elementorAdapter.js';
 import { rt, initRuntime } from './src/shared/context.js';
 import { getHandler, getTools, ALL_DEFINITIONS } from './src/tools/index.js';
 import { json, strip, buildPaginationMeta, validateBlocks } from './src/shared/utils.js';
@@ -29,7 +30,7 @@ import { validateInput } from './src/shared/governance.js';
 
 // ── Configuration ──────────────────────────────────────────────
 
-const VERSION = '5.0.0';
+const VERSION = '5.5.0';
 const VERBOSE = process.env.WP_MCP_VERBOSE === 'true' || process.argv.includes('--verbose');
 const MAX_RETRIES = parseInt(process.env.WP_MCP_MAX_RETRIES || '3', 10);
 const TIMEOUT_MS = parseInt(process.env.WP_MCP_TIMEOUT || '30000', 10);
@@ -60,7 +61,7 @@ function checkRateLimit() {
 }
 
 function enforceReadOnly(toolName) {
-  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'];
+  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', 'elementor_insert_link', 'elementor_update_widget'];
   if (getActiveControls().read_only && writeTools.includes(toolName))
     throw new Error(`Blocked: Server is in READ-ONLY mode (WP_READ_ONLY=true). Tool "${toolName}" is not allowed.`);
 }
@@ -325,7 +326,7 @@ async function healthCheck() {
 // ── Plugin layer ───────────────────────────────────────────────
 
 const pluginRegistry = new PluginRegistry();
-const PLUGIN_ADAPTERS = [acfAdapter];
+const PLUGIN_ADAPTERS = [acfAdapter, elementorAdapter];
 
 async function initializePluginLayer() {
   try {

package/package.json

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

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

@@ -1,17 +1,26 @@
 /**
- * Elementor Adapter — read-only.
+ * Elementor Adapter.
  *
- * Provides 3 tools for reading Elementor data via the REST API (elementor/v1):
+ * Read tools (REST API elementor/v1, fallback MCP Companion):
  *   - 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.
+ * Write tools (require the MCP Companion mu-plugin ≥ 1.1 — the _elementor_*
+ * meta is protected and post_content writes are regenerated from
+ * _elementor_data, so the companion is the only reliable write channel):
+ *   - elementor_insert_link      Wrap ONE exact text occurrence with <a href>
+ *   - elementor_update_widget    Set one widget setting (rollback primitive)
+ *
+ * All responses pass through contextGuard to prevent oversized payloads.
  */
 
 import { applyContextGuard } from '../../contextGuard.js';
 
+const COMPANION_BASE = '/wp-json/mcp-diagnostics/v1';
+const COMPANION_FIX =
+  'Install or update the MCP Companion plugin (companion/mcp-diagnostics.php, version ≥ 1.1) as a must-use plugin: copy it to wp-content/mu-plugins/mcp-diagnostics.php and retry.';
+
 // ── Helpers ─────────────────────────────────────────────────────────────
 
 function json(data) {
@@ -87,9 +96,16 @@ async function handleGetPageData(args, apiRequest) {
   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;
+    try {
+      // Fallback 1: MCP Companion — reliable read of the protected
+      // _elementor_data meta (hidden from the REST API even in edit context).
+      const companion = await apiRequest(`/elementor/data/${post_id}`, { basePath: COMPANION_BASE });
+      data = companion?.elements ?? null;
+    } catch {
+      // Fallback 2: post meta via WP REST API (usually empty — protected meta)
+      const post = await apiRequest(`/posts/${post_id}`, { basePath: '/wp-json/wp/v2' });
+      data = post?.meta?._elementor_data ?? null;
+    }
   }
 
   // Parse elements to extract widget info
@@ -120,6 +136,77 @@ async function handleGetPageData(args, apiRequest) {
   return json(guarded);
 }
 
+async function handleInsertLink(args, apiRequest) {
+  const t0 = Date.now();
+  const { post_id, exact_text, link_url } = 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');
+  }
+  if (typeof exact_text !== 'string' || exact_text.trim().length === 0 || exact_text.length > 500) {
+    throw new Error('Validation error: "exact_text" must be a non-empty string of at most 500 characters');
+  }
+  if (typeof link_url !== 'string' || !/^https?:\/\//i.test(link_url)) {
+    throw new Error('Validation error: "link_url" must be a valid http(s) URL');
+  }
+
+  let data;
+  try {
+    data = await apiRequest(`/elementor/insert-link/${post_id}`, {
+      basePath: COMPANION_BASE,
+      method: 'POST',
+      body: JSON.stringify({ exact_text, link_url }),
+    });
+  } catch (error) {
+    if (/rest_no_route/.test(error.message)) {
+      throw new Error(`Elementor link insertion requires the MCP Companion plugin. ${COMPANION_FIX}`);
+    }
+    throw error;
+  }
+
+  const guarded = applyContextGuard(data, { toolName: 'elementor_insert_link', mode: 'compact', maxChars: 50000 });
+
+  auditLog({ tool: 'elementor_insert_link', action: 'insert_link', target: post_id, status: 'success', latency_ms: Date.now() - t0, params: { link_url, widget_id: data?.widget_id ?? null } });
+  return json(guarded);
+}
+
+async function handleUpdateWidget(args, apiRequest) {
+  const t0 = Date.now();
+  const { post_id, widget_id, setting_key, value } = 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');
+  }
+  if (typeof widget_id !== 'string' || widget_id.trim().length === 0) {
+    throw new Error('Validation error: "widget_id" must be a non-empty string');
+  }
+  if (typeof setting_key !== 'string' || setting_key.trim().length === 0) {
+    throw new Error('Validation error: "setting_key" must be a non-empty string');
+  }
+  if (typeof value !== 'string') {
+    throw new Error('Validation error: "value" must be a string');
+  }
+
+  let data;
+  try {
+    data = await apiRequest(`/elementor/update-widget/${post_id}`, {
+      basePath: COMPANION_BASE,
+      method: 'POST',
+      body: JSON.stringify({ widget_id, setting_key, value }),
+    });
+  } catch (error) {
+    if (/rest_no_route/.test(error.message)) {
+      throw new Error(`Elementor widget update requires the MCP Companion plugin. ${COMPANION_FIX}`);
+    }
+    throw error;
+  }
+
+  const guarded = applyContextGuard(data, { toolName: 'elementor_update_widget', mode: 'compact', maxChars: 50000 });
+
+  auditLog({ tool: 'elementor_update_widget', action: 'update_widget', target: post_id, status: 'success', latency_ms: Date.now() - t0, params: { widget_id, setting_key } });
+  return json(guarded);
+}
+
 // ── Tool definitions (MCP format) ───────────────────────────────────────
 
 const TOOLS = [
@@ -159,6 +246,35 @@ const TOOLS = [
     },
     handler: handleGetPageData,
   },
+  {
+    name: 'elementor_insert_link',
+    description: 'Use to insert a link into an Elementor-built page: wraps ONE exact occurrence of exact_text with <a href="link_url"> inside an editable widget (text-editor). Refuses if the text is missing, ambiguous (multiple occurrences) or already linked. Returns a rollback payload (widget_id, setting_key, previous_value) for elementor_update_widget. Write — blocked by WP_READ_ONLY. Requires the MCP Companion mu-plugin ≥ 1.1.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        post_id: { type: 'number', description: 'Post or page ID (must be built with Elementor)' },
+        exact_text: { type: 'string', description: 'Text already present in the page, matched byte-for-byte (max 500 chars). Becomes the anchor text.' },
+        link_url: { type: 'string', description: 'Absolute http(s) URL for the link' },
+      },
+      required: ['post_id', 'exact_text', 'link_url'],
+    },
+    handler: handleInsertLink,
+  },
+  {
+    name: 'elementor_update_widget',
+    description: 'Use to set one editable setting of one Elementor widget (e.g. restore rollback.previous_value returned by elementor_insert_link). Only whitelisted settings per widget type are writable. Write — blocked by WP_READ_ONLY. Requires the MCP Companion mu-plugin ≥ 1.1.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        post_id: { type: 'number', description: 'Post or page ID (must be built with Elementor)' },
+        widget_id: { type: 'string', description: 'Elementor element id of the widget' },
+        setting_key: { type: 'string', description: 'Setting to write (e.g. "editor" for text-editor widgets)' },
+        value: { type: 'string', description: 'Raw HTML value to store' },
+      },
+      required: ['post_id', 'widget_id', 'setting_key', 'value'],
+    },
+    handler: handleUpdateWidget,
+  },
 ];
 
 // ── Adapter export ──────────────────────────────────────────────────────
@@ -166,7 +282,9 @@ const TOOLS = [
 export const elementorAdapter = {
   id: 'elementor',
   namespace: 'elementor/v1',
-  riskLevel: 'low',
+  // medium: elementor_insert_link / elementor_update_widget modify a single
+  // targeted widget; the remaining tools are read-only.
+  riskLevel: 'medium',
   contextConfig: {
     maxChars: 50000,
     defaultMode: 'compact',

package/tests/unit/plugins/elementor/elementorAdapter.test.js

@@ -204,3 +204,147 @@ describe('Elementor Adapter', () => {
     expect(errors).toEqual([]);
   });
 });
+
+// =========================================================================
+// Write tools — elementor_insert_link / elementor_update_widget (Companion)
+// =========================================================================
+
+/**
+ * Route-aware apiRequest mock: dispatches on basePath + endpoint regex.
+ * Unmatched routes behave like a missing REST route (rest_no_route).
+ */
+function mockApiRouted(routes) {
+  const calls = [];
+  const fn = async (endpoint, options = {}) => {
+    const basePath = options.basePath || '/wp-json/wp/v2';
+    calls.push({ endpoint, basePath, method: options.method || 'GET', body: options.body });
+    for (const r of routes) {
+      if (r.basePath === basePath && r.match.test(endpoint)) {
+        if (r.error) throw new Error(r.error);
+        return r.data;
+      }
+    }
+    throw new Error('WP API 404: Not Found\n{"code":"rest_no_route","message":"No route was found"}');
+  };
+  fn.calls = calls;
+  return fn;
+}
+
+const COMPANION = '/wp-json/mcp-diagnostics/v1';
+
+const mockInsertResponse = {
+  post_id: 42,
+  status: 'link_inserted',
+  widget_id: 'a1b2c3d',
+  widget_type: 'text-editor',
+  setting_key: 'editor',
+  link_url: 'https://example.com/cible',
+  anchor_text: 'stratégie digitale',
+  snippet_before: '…votre stratégie digitale mérite…',
+  snippet_after: '…votre <a href="https://example.com/cible">stratégie digitale</a> mérite…',
+  rollback: { widget_id: 'a1b2c3d', setting_key: 'editor', previous_value: '<p>votre stratégie digitale mérite mieux</p>' },
+};
+
+describe('Elementor Adapter — write tools', () => {
+
+  const insertTool = () => elementorAdapter.getTools().find(t => t.name === 'elementor_insert_link');
+  const updateTool = () => elementorAdapter.getTools().find(t => t.name === 'elementor_update_widget');
+
+  it('exposes the 2 write tools with WP_READ_ONLY + Companion mentions', () => {
+    for (const tool of [insertTool(), updateTool()]) {
+      expect(tool).toBeDefined();
+      expect(tool.description).toContain('WP_READ_ONLY');
+      expect(tool.description).toContain('Companion');
+    }
+  });
+
+  it('elementor_insert_link POSTs to the companion endpoint and returns the payload', async () => {
+    const api = mockApiRouted([
+      { basePath: COMPANION, match: /^\/elementor\/insert-link\/42$/, data: mockInsertResponse },
+    ]);
+    const result = await insertTool().handler(
+      { post_id: 42, exact_text: 'stratégie digitale', link_url: 'https://example.com/cible' },
+      api
+    );
+    const data = parseResult(result);
+    expect(data.status).toBe('link_inserted');
+    expect(data.rollback.previous_value).toContain('stratégie digitale');
+
+    expect(api.calls).toHaveLength(1);
+    expect(api.calls[0].method).toBe('POST');
+    expect(JSON.parse(api.calls[0].body)).toEqual({ exact_text: 'stratégie digitale', link_url: 'https://example.com/cible' });
+
+    const entry = getAuditLogs().find(l => l.tool === 'elementor_insert_link');
+    expect(entry.action).toBe('insert_link');
+    expect(entry.target).toBe(42);
+    expect(entry.status).toBe('success');
+  });
+
+  it('elementor_insert_link validates inputs before any API call', async () => {
+    const api = mockApiRouted([]);
+    await expect(insertTool().handler({ post_id: 'x', exact_text: 'ok', link_url: 'https://a.b' }, api)).rejects.toThrow('post_id');
+    await expect(insertTool().handler({ post_id: 1, exact_text: '   ', link_url: 'https://a.b' }, api)).rejects.toThrow('exact_text');
+    await expect(insertTool().handler({ post_id: 1, exact_text: 'x'.repeat(501), link_url: 'https://a.b' }, api)).rejects.toThrow('exact_text');
+    await expect(insertTool().handler({ post_id: 1, exact_text: 'ok', link_url: 'javascript:alert(1)' }, api)).rejects.toThrow('link_url');
+    expect(api.calls).toHaveLength(0);
+  });
+
+  it('elementor_insert_link maps rest_no_route to a Companion install hint', async () => {
+    const api = mockApiRouted([]); // no companion route registered
+    await expect(
+      insertTool().handler({ post_id: 42, exact_text: 'ok', link_url: 'https://a.b' }, api)
+    ).rejects.toThrow(/MCP Companion plugin/);
+  });
+
+  it('elementor_insert_link propagates companion business errors (ambiguous, not built with Elementor…)', async () => {
+    const api = mockApiRouted([
+      { basePath: COMPANION, match: /^\/elementor\/insert-link\/42$/, error: 'WP API 409: \n{"code":"ambiguous_text","message":"exact_text appears 3 times"}' },
+    ]);
+    await expect(
+      insertTool().handler({ post_id: 42, exact_text: 'ok', link_url: 'https://a.b' }, api)
+    ).rejects.toThrow(/ambiguous_text/);
+  });
+
+  it('elementor_update_widget POSTs the rollback payload and audits', async () => {
+    const api = mockApiRouted([
+      { basePath: COMPANION, match: /^\/elementor\/update-widget\/42$/, data: { post_id: 42, status: 'widget_updated', widget_id: 'a1b2c3d', setting_key: 'editor', previous_value: '<p>avec lien</p>' } },
+    ]);
+    const result = await updateTool().handler(
+      { post_id: 42, widget_id: 'a1b2c3d', setting_key: 'editor', value: '<p>votre stratégie digitale mérite mieux</p>' },
+      api
+    );
+    const data = parseResult(result);
+    expect(data.status).toBe('widget_updated');
+    expect(api.calls[0].method).toBe('POST');
+    expect(JSON.parse(api.calls[0].body).setting_key).toBe('editor');
+
+    const entry = getAuditLogs().find(l => l.tool === 'elementor_update_widget');
+    expect(entry.action).toBe('update_widget');
+    expect(entry.status).toBe('success');
+  });
+
+  it('elementor_update_widget validates inputs and maps rest_no_route', async () => {
+    const api = mockApiRouted([]);
+    await expect(updateTool().handler({ post_id: 0, widget_id: 'a', setting_key: 'editor', value: '' }, api)).rejects.toThrow('post_id');
+    await expect(updateTool().handler({ post_id: 1, widget_id: '', setting_key: 'editor', value: '' }, api)).rejects.toThrow('widget_id');
+    await expect(updateTool().handler({ post_id: 1, widget_id: 'a', setting_key: '', value: '' }, api)).rejects.toThrow('setting_key');
+    await expect(updateTool().handler({ post_id: 1, widget_id: 'a', setting_key: 'editor', value: 42 }, api)).rejects.toThrow('value');
+    expect(api.calls).toHaveLength(0);
+
+    await expect(
+      updateTool().handler({ post_id: 1, widget_id: 'a', setting_key: 'editor', value: '' }, api)
+    ).rejects.toThrow(/MCP Companion plugin/);
+  });
+
+  it('elementor_get_page_data falls back to the companion data endpoint', async () => {
+    const api = mockApiRouted([
+      // elementor/v1 absent → the companion becomes the source of truth
+      { basePath: COMPANION, match: /^\/elementor\/data\/42$/, data: { post_id: 42, edit_mode: 'builder', elements: mockPageData.elements } },
+    ]);
+    const tool = elementorAdapter.getTools().find(t => t.name === 'elementor_get_page_data');
+    const result = await tool.handler({ post_id: 42 }, api);
+    const data = parseResult(result);
+    expect(data.elementor_status).toBe('active');
+    expect(data.widgets_used).toContain('text-editor');
+  });
+});