@elementor/elementor-v3-mcp 4.1.0-754

package/src/tools/routes-tool.ts

@@ -0,0 +1,138 @@
+import { z } from '@elementor/schema';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import type { McpToolResult, ToolParams } from '../types';
+import { get$e } from '../utils';
+
+export function addRoutesTool( server: McpServer ): void {
+	const $e = get$e();
+	const routes = $e?.routes?.getAll?.() || [];
+	const components = $e?.components?.getAll?.() || [];
+	const availableToOpenComponents = components.filter(
+		( component: string ) => $e?.components?.get( component )?.getCommands?.()?.open
+	);
+	const availableToCloseComponents = components.filter(
+		( component: string ) => $e?.components?.get( component )?.getCommands?.()?.close
+	);
+
+	server.registerTool(
+		'routes',
+		{
+			description:
+				'Manage Elementor editor routing and navigation. Use this tool to open a component, navigate to a route, go back from a route or close components. Always prefer this tool when user is on the Elementor editor.' +
+				` Available routes to navigate to or back from: ${ routes.join( ', ' ) }`,
+			inputSchema: {
+				action: z.enum( [ 'open', 'navigate', 'go-back', 'close' ] ),
+				route: z
+					.string()
+					.optional()
+					.describe(
+						'The route to navigate to or back from it. Do not send this parameter if you only want to open a component.'
+					),
+				componentToOpen: z
+					.enum( ( availableToOpenComponents.length ? availableToOpenComponents : [ '' ] ) as [ string ] )
+					.optional()
+					.describe( 'The component to open or navigate to.' ),
+				componentToClose: z
+					.enum( ( availableToCloseComponents.length ? availableToCloseComponents : [ '' ] ) as [ string ] )
+					.optional()
+					.describe( 'The component to close.' ),
+			},
+			annotations: {
+				title: 'Manage Routes',
+			},
+		},
+		async ( params: ToolParams ) => {
+			switch ( params.action ) {
+				case 'open':
+					return await handleOpen( params );
+				case 'navigate':
+					return await handleNavigate( params );
+				case 'go-back':
+					return await handleGoBack( params );
+				case 'close':
+					return await handleClose( params );
+				default:
+					throw new Error( `Unknown action: ${ params.action }` );
+			}
+		}
+	);
+}
+
+async function handleOpen( params: ToolParams ): Promise< McpToolResult > {
+	const $e = get$e();
+	const component = ( params.componentToOpen || params.route ) as string;
+	const openCommand = $e?.components?.get( component )?.getCommands?.()?.open?.registerConfig.command;
+
+	if ( openCommand ) {
+		await $e?.run( openCommand, {} );
+	} else {
+		throw new Error( 'Could not open component' );
+	}
+
+	return {
+		content: [ { type: 'text', text: `Opened: ${ component }` } ],
+	};
+}
+
+async function handleNavigate( params: ToolParams ): Promise< McpToolResult > {
+	const $e = get$e();
+	const route = params.route as string;
+	const componentToOpen = params.componentToOpen as string;
+	const openCommand = $e?.components?.get( componentToOpen )?.getCommands?.()?.open?.registerConfig.command;
+
+	if ( openCommand ) {
+		await $e?.run( openCommand, {} );
+	}
+
+	const routeComponent = $e?.routes?.getComponent?.( route );
+	if ( routeComponent ) {
+		$e?.routes?.saveState?.( routeComponent.getNamespace() );
+	}
+
+	try {
+		$e?.routes?.to?.( route, {} );
+	} catch {
+		const openCommandFallback = $e?.components?.get( route )?.getCommands?.()?.open?.registerConfig.command;
+
+		if ( openCommandFallback ) {
+			await $e?.run( openCommandFallback, {} );
+		} else {
+			throw new Error( 'Could not navigate to route' );
+		}
+	}
+
+	return {
+		content: [ { type: 'text', text: `Navigated to: ${ route }` } ],
+	};
+}
+
+async function handleGoBack( params: ToolParams ): Promise< McpToolResult > {
+	const $e = get$e();
+	const route = params.route as string;
+	const component = $e?.routes?.getComponent?.( route );
+
+	if ( component ) {
+		$e?.routes?.back?.( component.getNamespace() );
+	}
+
+	return {
+		content: [ { type: 'text', text: `Go back to: ${ route }` } ],
+	};
+}
+
+async function handleClose( params: ToolParams ): Promise< McpToolResult > {
+	const $e = get$e();
+	const component = params.componentToClose as string;
+	const closeCommand = $e?.components?.get( component )?.getCommands?.()?.close?.registerConfig.command;
+
+	if ( closeCommand ) {
+		await $e?.run( closeCommand, {} );
+	} else {
+		throw new Error( 'Could not close component' );
+	}
+
+	return {
+		content: [ { type: 'text', text: `Closed: ${ component }` } ],
+	};
+}

package/src/tools/styling-tool.ts

@@ -0,0 +1,131 @@
+import { z } from '@elementor/schema';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SamplingMessageSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import type { McpToolResult } from '../types';
+import { getElementor } from '../utils';
+
+export function addStylingTool( server: McpServer ): void {
+	server.registerTool(
+		'styling',
+		{
+			description: `This tool provides AI-powered custom CSS styling for Elementor elements. Use this when users want advanced styling that goes beyond Elementor capabilities and can't be targeted using the element settings.
+
+**When to use this tool:**
+- Visual effects: shadows, filters, pseudo-elements, advanced selectors
+- Complex animations with custom keyframes or CSS transitions
+- Styling that requires media queries or complex CSS rules
+- Click-triggered effects or other non-motion triggers
+- Custom hover effects that don't involve motion (color changes, opacity, etc.)
+
+**When NOT to use this tool:**
+- Basic styling achievable through Elementor settings (colors, typography, spacing, borders, simple hover effects) -> use the elementor__elements with "update-settings" action.
+
+**Do NOT use this tool if the user mentions motion effects with supported triggers:**
+- "on hover" with motion (movement, rotation, scaling) → use motion-effects tool
+- "on scroll" with motion effects → use motion-effects tool  
+- "mouse move" / "follow mouse" → use motion-effects tool
+- "entrance" / "fade in" / "slide in" animations → use motion-effects tool
+
+**Actions available:**
+- **custom-css**: Generate and apply AI-powered custom CSS to elements
+
+This tool generates CSS code using AI, provides preview functionality, and handles user approval workflow for applying custom styles.`,
+			inputSchema: {
+				action: z
+					.enum( [ 'custom-css' ] )
+					.describe(
+						'The styling operation to perform. Currently supports custom-css for AI-generated CSS styling.'
+					),
+				elementId: z
+					.string()
+					.describe(
+						'The ID of the Elementor element to apply custom styling to. This element will receive the generated CSS code.'
+					),
+				prompt: z
+					.string()
+					.describe(
+						'A detailed description of the desired styling. Include specific visual requirements, colors, effects, layout modifications, or any custom styling needs. The more detailed the prompt, the better the generated CSS will match your requirements.'
+					),
+			},
+			annotations: {
+				title: 'Apply Custom Styling',
+			},
+		},
+		async ( params ) => {
+			switch ( params.action ) {
+				case 'custom-css':
+					return await handleCustomCss( params.elementId as string, params.prompt as string, server );
+				default:
+					throw new Error( `Unknown action: ${ params.action }` );
+			}
+		}
+	);
+}
+
+async function handleCustomCss( elementId: string, prompt: string, server: McpServer ): Promise< McpToolResult > {
+	const container = getElementor()?.getContainer( elementId );
+	if ( ! container ) {
+		throw new Error( `Element with ID ${ elementId } not found.` );
+	}
+
+	const htmlMarkup = container.view?.el?.outerHTML || '';
+
+	const parseCSS = ( css: string ) => {
+		return css && css.replace( /`/g, '' ).replace( /^css\s*/i, '' );
+	};
+
+	const samplingCssResult = await server.server.request(
+		{
+			method: 'sampling/createMessage',
+			params: {
+				messages: [
+					{
+						role: 'user',
+						content: {
+							type: 'text',
+							text: prompt,
+						},
+					},
+				],
+				maxTokens: 1000,
+				modelPreferences: {
+					hints: [
+						{
+							name: 'elementor-css',
+						},
+					],
+				},
+				metadata: {
+					element_id: elementId,
+					html_markup: htmlMarkup,
+				},
+			},
+		},
+		SamplingMessageSchema
+	);
+
+	const content = samplingCssResult?.content;
+	const block = Array.isArray( content ) ? content.find( ( b ) => b.type === 'text' ) : content;
+	const cssText = block?.type === 'text' ? block.text : undefined;
+
+	if ( ! cssText ) {
+		throw new Error( 'Failed to generate CSS: No text content received from API.' );
+	}
+
+	const parsedCssString = parseCSS( cssText );
+
+	return {
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify( {
+					success: true,
+					message: 'Custom CSS generated. The CSS needs to be applied through the editor.',
+					generatedCss: parsedCssString,
+					elementId,
+				} ),
+			},
+		],
+	};
+}

package/src/tools/ui-tool.ts

@@ -0,0 +1,100 @@
+import { z } from '@elementor/schema';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import type { McpToolResult, ToolParams } from '../types';
+import { get$e, getElementor } from '../utils';
+
+export function addUiTool( server: McpServer ): void {
+	server.registerTool(
+		'ui',
+		{
+			description:
+				'Manage Elementor editor UI operations. This tool provides control over editor interface actions including responsive preview modes and widget favorites. Use this when you need to: switch between device preview modes (desktop/tablet/mobile), manage favorite widgets, or paste previously copied content. Note: For undo/redo operations, use the page tool instead. The tool interacts directly with the Elementor editor UI and does not modify page content itself.',
+			inputSchema: {
+				action: z
+					.enum( [ 'change-device-mode', 'toggle-favorite', 'ui-paste' ] )
+					.describe(
+						'The UI operation to perform: change-device-mode (switch responsive preview), toggle-favorite (add/remove widget from favorites), ui-paste (paste clipboard content into an existing element)'
+					),
+				deviceMode: z
+					.enum( [ 'desktop', 'tablet', 'mobile' ] )
+					.optional()
+					.describe( 'Required for change-device-mode. The device mode to switch to for responsive preview' ),
+				widgetType: z
+					.string()
+					.optional()
+					.describe(
+						'Required for toggle-favorite. The widget type name (e.g., "heading", "button", "image") to add or remove from favorites'
+					),
+				elementId: z
+					.string()
+					.optional()
+					.describe(
+						'Required for ui-paste. The ID of an existing container element where clipboard content should be pasted. Note: The element must exist and content must be in clipboard first'
+					),
+			},
+			annotations: {
+				title: 'Manage UI',
+			},
+		},
+		async ( params: ToolParams ) => {
+			switch ( params.action ) {
+				case 'change-device-mode':
+					return await handleChangeDeviceMode( params );
+				case 'toggle-favorite':
+					return await handleToggleFavorite( params );
+				case 'ui-paste':
+					return await handleUiPaste( params );
+				default:
+					throw new Error( `Unknown action: ${ params.action }` );
+			}
+		}
+	);
+}
+
+async function handleChangeDeviceMode( params: ToolParams ): Promise< McpToolResult > {
+	if ( ! params.deviceMode ) {
+		throw new Error( 'deviceMode is required for change-device-mode action' );
+	}
+
+	get$e()?.run( 'panel/change-device-mode', {
+		device: params.deviceMode,
+	} );
+
+	return {
+		content: [ { type: 'text', text: `Device mode changed to ${ params.deviceMode }.` } ],
+	};
+}
+
+async function handleToggleFavorite( params: ToolParams ): Promise< McpToolResult > {
+	if ( ! params.widgetType ) {
+		throw new Error( 'widgetType is required for toggle-favorite action' );
+	}
+
+	get$e()?.run( 'favorites/toggle', {
+		name: params.widgetType,
+	} );
+
+	return {
+		content: [ { type: 'text', text: `Favorite status toggled for ${ params.widgetType }.` } ],
+	};
+}
+
+async function handleUiPaste( params: ToolParams ): Promise< McpToolResult > {
+	if ( ! params.elementId ) {
+		throw new Error( 'elementId is required for ui-paste action' );
+	}
+
+	const container = getElementor()?.getContainer( params.elementId as string );
+	if ( ! container ) {
+		throw new Error( `Element with ID ${ params.elementId } not found.` );
+	}
+
+	get$e()?.run( 'document/ui/paste', {
+		container,
+	} );
+
+	return {
+		content: [ { type: 'text', text: `UI paste performed on element ${ params.elementId }.` } ],
+	};
+}

package/src/types.ts

@@ -0,0 +1,120 @@
+export type ToolParams = {
+	[ key: string ]: unknown;
+	action: string;
+};
+
+export type McpToolResult = {
+	content: Array< {
+		type: 'text';
+		text: string;
+	} >;
+};
+
+export interface ElementorContainer {
+	id: string;
+	model: {
+		id: string;
+		attributes?: Record< string, unknown >;
+		editor_settings?: { title?: string };
+		get?: ( key: string ) => unknown;
+	};
+	settings: {
+		attributes?: Record< string, unknown >;
+		controls?: Record< string, unknown >;
+		get: ( key: string ) => unknown;
+	};
+	children?: ElementorContainer[];
+	view?: {
+		el: HTMLElement;
+	};
+	parent?: ElementorContainer;
+}
+
+export interface ElementorControls {
+	[ key: string ]: {
+		type: string;
+		default?: unknown;
+		options?: Record< string, string >;
+		fields?: ElementorControls;
+	};
+}
+
+export type ElementorControlsMapped = {
+	[ key: string ]: {
+		default: unknown;
+		options?: string[];
+		onValue?: string;
+		size_units?: string[];
+		range?: { min: number; max: number };
+		type: string;
+		fields?: ElementorControlsMapped;
+	};
+};
+
+export interface ElementorDocument {
+	id: string;
+	container: ElementorContainer & { children: ElementorContainer[] };
+	config: {
+		type: string;
+		settings: Record< string, unknown > & {
+			controls?: ElementorControls;
+			settings?: Record< string, unknown >;
+		};
+	};
+}
+
+export interface ElementorInstance {
+	documents: {
+		getCurrent: () => ElementorDocument | null;
+		get: ( id: string ) => {
+			config?: {
+				settings: {
+					controls: ElementorControls;
+					settings: Record< string, unknown >;
+				};
+			};
+		} | null;
+	};
+	getContainer: ( id: string ) => ElementorContainer | null;
+	getCurrentElement: () => { model: { id: string } } | null;
+	selection: {
+		elements: Record< string, unknown >;
+	};
+	widgetsCache: Record< string, { controls: ElementorControls } >;
+	config: {
+		controls: Record< string, unknown >;
+	};
+	dynamicTags?: {
+		getConfig: ( key: string ) => Record< string, { categories: string[] } >;
+		tagDataToTagText: ( id: string, name: string, settings: Record< string, unknown > ) => string;
+	};
+}
+
+export interface ElementorCommandsInstance {
+	run: ( command: string, args?: Record< string, unknown > ) => Promise< unknown >;
+	data: {
+		get: ( key: string ) => Promise< { data: Record< string, { value: unknown } > } >;
+	};
+	routes: {
+		getAll: () => string[];
+		getComponent: ( route: string ) => { getNamespace: () => string };
+		saveState: ( namespace: string ) => void;
+		to: ( route: string, args: Record< string, unknown > ) => void;
+		back: ( namespace: string ) => void;
+	};
+	components: {
+		getAll: () => string[];
+		get: ( name: string ) => {
+			getCommands: () => {
+				open?: { registerConfig: { command: string } };
+				close?: { registerConfig: { command: string } };
+			};
+		};
+	};
+}
+
+export interface ElementorCommonInstance {
+	helpers?: {
+		getUniqueId?: () => number | string;
+	};
+}

package/src/utils.ts

@@ -0,0 +1,211 @@
+import type {
+	ElementorCommandsInstance,
+	ElementorCommonInstance,
+	ElementorContainer,
+	ElementorInstance,
+} from './types';
+import { widgetMandatoryFields } from './widget-mandatory-fields';
+
+interface McpWindow {
+	elementor?: ElementorInstance;
+	$e?: ElementorCommandsInstance;
+	elementorCommon?: ElementorCommonInstance;
+}
+
+export const getElementor = (): ElementorInstance | undefined => ( window as unknown as McpWindow ).elementor;
+
+export const get$e = (): ElementorCommandsInstance | undefined => ( window as unknown as McpWindow ).$e;
+
+export const getElementorCommon = (): ElementorCommonInstance | undefined =>
+	( window as unknown as McpWindow ).elementorCommon;
+
+export async function updateRepeaterControl(
+	container: ElementorContainer,
+	repeaterName: string,
+	widgetType: string,
+	settings: Record< string, unknown >
+): Promise< Record< string, unknown >[] > {
+	const repeaterControl = getElementor()?.widgetsCache?.[ widgetType ]?.controls?.[ repeaterName ] as {
+		fields?: Record< string, { default?: unknown } >;
+	};
+	const existingAttribute = container.settings?.attributes?.[ repeaterName ] as { models?: unknown[] };
+	let existingItemsCount = existingAttribute?.models?.length ?? 0;
+	const repeaterModel: Record< string, unknown > = {};
+	const insertedModels: Record< string, unknown >[] = [];
+
+	Object.keys( repeaterControl?.fields ?? {} ).forEach( ( fieldKey ) => {
+		const field = repeaterControl?.fields?.[ fieldKey ];
+		repeaterModel[ fieldKey ] = field?.default || '';
+	} );
+
+	const repeaterValues = settings[ repeaterName ] as Record< string, unknown >[];
+	repeaterValues.forEach( ( val ) => {
+		const itemModel: Record< string, unknown > = {};
+		Object.keys( repeaterModel ).forEach( ( fieldKey ) => {
+			itemModel[ fieldKey ] = val[ fieldKey ] ?? repeaterModel[ fieldKey ];
+		} );
+		itemModel._id = getElementorCommon()?.helpers?.getUniqueId?.();
+
+		get$e()?.run( 'document/repeater/insert', {
+			container,
+			name: repeaterName,
+			model: itemModel,
+		} );
+
+		insertedModels.push( itemModel );
+	} );
+
+	while ( existingItemsCount-- ) {
+		await get$e()?.run( 'document/repeater/remove', { container, name: repeaterName, index: 0 } );
+	}
+
+	return insertedModels;
+}
+
+export function addMandatoryFields( settings: Record< string, unknown > ): Record< string, unknown > {
+	const missingFields: Record< string, unknown > = {};
+
+	Object.keys( settings ).forEach( ( settingKey ) => {
+		const mandatoryFields = widgetMandatoryFields[ settingKey ];
+
+		mandatoryFields?.forEach( ( mandatoryField ) => {
+			if ( ! settings[ mandatoryField.mandatory ] ) {
+				settings[ mandatoryField.mandatory ] = mandatoryField.default;
+				missingFields[ mandatoryField.mandatory ] = mandatoryField.default;
+			}
+		} );
+	} );
+
+	return missingFields;
+}
+
+export function getCurrentSelection(): string[] {
+	return Object.keys( getElementor()?.selection?.elements || {} );
+}
+
+export async function restoreCurrentSelection( selectedElementId: string | null ): Promise< void > {
+	const elementor = getElementor();
+	const $e = get$e();
+	if ( selectedElementId && elementor && $e ) {
+		try {
+			await $e.run( 'document/elements/select', {
+				container: elementor.getContainer( selectedElementId ),
+			} );
+		} catch {
+			// Unable to restore selection
+		}
+	}
+}
+
+function convertToGlobalFormat( settings: Record< string, unknown > ): Record< string, string > {
+	const converted: Record< string, string > = {};
+
+	for ( const [ key, value ] of Object.entries( settings ) ) {
+		if ( typeof value === 'string' && value.startsWith( 'globals/' ) ) {
+			converted[ key ] = value;
+		} else if ( key.includes( 'typography' ) ) {
+			converted[ key ] = `globals/typography?id=${ value }`;
+		} else {
+			converted[ key ] = `globals/colors?id=${ value }`;
+		}
+	}
+
+	return converted;
+}
+
+export async function extractAndApplyGlobalStyles(
+	settings: Record< string, unknown >,
+	elementId: string
+): Promise< { globalStyles: Record< string, string >; remainingSettings: Record< string, unknown > } > {
+	const globalStyles = ( settings.__globals__ || {} ) as Record< string, string >;
+	const remainingSettings: Record< string, unknown > = {};
+
+	Object.keys( settings ).forEach( ( key ) => {
+		if ( key === '__globals__' ) {
+			return;
+		}
+		remainingSettings[ key ] = settings[ key ];
+	} );
+
+	const $e = get$e();
+	if ( ! $e?.data?.get ) {
+		return { globalStyles, remainingSettings };
+	}
+
+	const globalColorsResult = ( await $e.data.get( 'globals/colors' ) ) as
+		| {
+				data: Record< string, { value: unknown } >;
+		  }
+		| undefined;
+	const globalTypographyResult = ( await $e.data.get( 'globals/typography' ) ) as
+		| {
+				data: Record< string, { value: unknown } >;
+		  }
+		| undefined;
+
+	const globalColors = globalColorsResult?.data ?? {};
+	const globalTypography = globalTypographyResult?.data ?? {};
+
+	const keysToRemove: string[] = [];
+
+	Object.keys( remainingSettings ).forEach( ( key ) => {
+		const value = remainingSettings[ key ];
+		if ( typeof value === 'string' && value ) {
+			if ( globalColors[ value ] || globalTypography[ value ] ) {
+				globalStyles[ key ] = value;
+				keysToRemove.push( key );
+			} else {
+				const globalColorKey = Object.keys( globalColors ).find(
+					( globalKey ) => globalColors[ globalKey ]?.value === value
+				);
+				const globalTypographyKey = Object.keys( globalTypography ).find( ( globalKey ) => {
+					const globalTypo = globalTypography[ globalKey ];
+					return globalTypo && JSON.stringify( globalTypo.value ) === JSON.stringify( value );
+				} );
+
+				if ( globalColorKey ) {
+					globalStyles[ key ] = globalColorKey;
+					keysToRemove.push( key );
+				} else if ( globalTypographyKey ) {
+					globalStyles[ key ] = globalTypographyKey;
+					keysToRemove.push( key );
+				}
+			}
+		}
+	} );
+
+	const finalSettings: Record< string, unknown > = {};
+	Object.keys( remainingSettings ).forEach( ( key ) => {
+		if ( ! keysToRemove.includes( key ) ) {
+			finalSettings[ key ] = remainingSettings[ key ];
+		}
+	} );
+
+	const elementor = getElementor();
+	if ( Object.keys( globalStyles ).length > 0 && elementor ) {
+		const container = elementor.getContainer( elementId );
+		if ( container ) {
+			const convertedSettings = convertToGlobalFormat( globalStyles );
+			await $e?.run( 'document/globals/enable', {
+				container,
+				settings: convertedSettings,
+			} );
+		}
+	}
+
+	return { globalStyles, remainingSettings: finalSettings };
+}
+
+export function encodeToolJson( data: unknown ): string {
+	return JSON.stringify( data ).replaceAll( '"', "'" );
+}
+
+export function getElementType( elementId: string ): string {
+	const container = getElementor()?.getContainer( elementId );
+
+	if ( ! container ) {
+		throw new Error( `Container with ID ${ elementId } not found.` );
+	}
+
+	return ( container.model.attributes?.widgetType ?? 'container' ) as string;
+}