@elementor/editor-canvas 3.33.0-271 → 3.33.0-273

package/src/mcp/tools/configure-element/prompt.ts

@@ -0,0 +1,92 @@
+import { STYLE_SCHEMA_URI, WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
+
+export const configureElementToolPrompt = `Configure an existing element on the page.
+
+# **CRITICAL - REQUIRED RESOURCES (Must read before using this tool)**
+1. [${ WIDGET_SCHEMA_URI }]
+   Required to understand which widgets are available, and what are their configuration schemas.
+   Every widgetType (i.e. e-heading, e-button) that is supported has it's own property schema, that you must follow in order to apply property values correctly.
+2. [${ STYLE_SCHEMA_URI }]
+   Required to understand the styles schema for the widgets. All widgets share the same styles schema, grouped by categories.
+   Use this resource to understand which style properties are available for each element, and how to structure the "_styles" configuration property.
+
+Before using this tool, check the definitions of the elements PropTypes at the resource "widget-schema-by-type" at editor-canvas__elementor://widgets/schema/{widgetType}
+All widgets share a common _style property for styling, which uses the common styles schema.
+Retreive and check the common styles schema at the resource list "styles-schema" at editor-canvas__elementor://styles/schema/{category}
+
+Unless specifically noted, attempt to use the _style property "custom_css" for any styling, read the resource editor-canvas__elementor://styles/schema/custom_css for more information.
+
+# Parameters
+- propertiesToChange: An object containing the properties to change, with their new values. MANDATORY
+- elementId: The ID of the element to configure. MANDATORY
+- elementType: The type of the element to configure (i.e. e-heading, e-button). MANDATORY
+
+# When to use this tool
+When a user requires to change anything in an element, such as updating text, colors, sizes, or other configurable properties.
+This tool handles elements of type "widget".
+This tool handles styling elements, using the _styles property in the configuration.
+
+The element's schema must be known before using this tool.
+
+Attached resource link describing how PropType schema should be parsed as PropValue for this tool.
+
+Read carefully the PropType Schema of the element and it's styles, then apply correct PropValue according to the schema.
+
+PropValue structure:
+{
+    "$$type": string, // MANDATORY as defined in the PropType schema under the "key" property
+    value: unknown // The value according to the PropType schema for kinds of "array", use array with PropValues items inside. For "object", read the shape property of the PropType schema. For "plain", use strings.
+}
+
+<IMPORTANT>
+ALWAYS MAKE SURE you have the PropType schemas for the element you are configuring, and the common-styles schema for styling. If you are not sure, retreive the schema from the resources mentioned above.
+</IMPORTANT>
+
+You can use multiple property changes at once by providing multiple entries in the propertiesToChange object, including _style alongside non-style props.
+Some properties are nested, use the root property name, then objects with nested values inside, as the complete schema suggests.
+Nested properties, such as for the _styles, should include a "_styles" property with object containing the definitions to change.
+
+Make sure you have the "widget-schema-by-type" resource available to retreive the PropType schema for the element type you are configuring.
+
+# How to configure elements
+We use a dedicated PropType Schema for configuring elements, including styles. When you configure an element, you must use the EXACT PropType Value as defined in the schema.
+For _styles, use the style schema provided, as it also uses the PropType format.
+For all non-primitive types, provide the key property as defined in the schema as $$type in the generated objecct, as it is MANDATORY for parsing.
+
+Use the EXACT "PROP-TYPE" Schema given, and ALWAYS include the "key" property from the original configuration for every property you are changing.
+
+# Example
+\`\`\`json
+{
+  propertiesToChange: {
+    title: {
+      $$type: 'string',
+      value: 'New Title Text'
+    },
+    border: {
+      $$type: 'boolean',
+      value: false
+    },
+    _styles: {
+      'line-height': {
+        $$type: 'size',
+        value: {
+          size: {
+            $$type: 'number',
+            value: 20
+          },
+          unit: {
+            $$type: 'string',
+            value: 'px'
+          }
+        }
+      }
+    }
+  }
+};
+\`\`\`
+
+<IMPORTANT>
+The $$type property is MANDATORY for every value, it is required to parse the value and apply application-level effects.
+</IMPORTANT>
+`;

package/src/mcp/tools/configure-element/schema.ts

@@ -0,0 +1,25 @@
+import { z } from '@elementor/schema';
+
+export const inputSchema = {
+	propertiesToChange: z
+		.record(
+			z
+				.string()
+				.describe(
+					'The property name. If nested property, provide the root property name, and the object delta only.'
+				),
+			z.any().describe( "The property's value" )
+		)
+		.describe( 'An object record containing property names and their new values to be set on the element' )
+		.optional(),
+	elementType: z.string().describe( 'The type of the element to retreive the schema' ),
+	elementId: z.string().describe( 'The unique id of the element to configure' ),
+};
+
+export const outputSchema = {
+	success: z
+		.boolean()
+		.describe(
+			'Whether the configuration change was successful, only if propertyName and propertyValue are provided'
+		),
+};

package/src/mcp/tools/configure-element/tool.ts

@@ -0,0 +1,67 @@
+import { type MCPRegistryEntry } from '@elementor/editor-mcp';
+
+import { WIDGET_SCHEMA_URI } from '../../resources/widgets-schema-resource';
+import { doUpdateElementProperty } from '../../utils/do-update-element-property';
+import { configureElementToolPrompt } from './prompt';
+import { inputSchema as schema, outputSchema } from './schema';
+
+export const initConfigureElementTool = ( reg: MCPRegistryEntry ) => {
+	const { addTool } = reg;
+
+	addTool( {
+		name: 'configure-element',
+		description: configureElementToolPrompt,
+		schema,
+		outputSchema,
+		handler: ( { elementId, propertiesToChange, elementType } ) => {
+			if ( ! propertiesToChange ) {
+				throw new Error(
+					'propertiesToChange is required to configure an element. Now that you have this information, ensure you have the schema and try again.'
+				);
+			}
+			const toUpdate = Object.entries( propertiesToChange );
+			for ( const [ propertyName, propertyValue ] of toUpdate ) {
+				if ( ! propertyName && ! elementId && ! elementType ) {
+					throw new Error(
+						'propertyName, elementId, elementType are required to configure an element. If you want to retreive the schema, use the get-element-configuration-schema tool.'
+					);
+				}
+
+				try {
+					doUpdateElementProperty( {
+						elementId,
+						elementType,
+						propertyName,
+						propertyValue,
+					} );
+				} catch ( error ) {
+					const errorMessage = createUpdateErrorMessage( {
+						propertyName,
+						elementId,
+						elementType,
+						error: error as Error,
+					} );
+					throw new Error( errorMessage );
+				}
+			}
+			return {
+				success: true,
+			};
+		},
+	} );
+};
+
+function createUpdateErrorMessage( opts: {
+	propertyName: string;
+	elementId: string;
+	elementType: string;
+	error: Error;
+} ) {
+	const { propertyName, elementId, elementType, error } = opts;
+	return `Failed to update property "${ propertyName }" on element "${ elementId }": ${ error.message }.
+Check the element's PropType schema at the resource [${ WIDGET_SCHEMA_URI.replace(
+		'{widgetType}',
+		elementType
+	) }] for type "${ elementType }" to ensure the property exists and the value matches the expected PropType.
+Now that you have this information, ensure you have the schema and try again.`;
+}

package/src/mcp/utils/do-update-element-property.ts

@@ -0,0 +1,115 @@
+import {
+	createElementStyle,
+	getElementStyles,
+	getWidgetsCache,
+	updateElementSettings,
+	updateElementStyle,
+} from '@elementor/editor-elements';
+import { getPropSchemaFromCache, type PropValue, Schema, type TransformablePropValue } from '@elementor/editor-props';
+import { type CustomCss, getStylesSchema } from '@elementor/editor-styles';
+
+type OwnParams = {
+	elementId: string;
+	elementType: string;
+	propertyName: string;
+	propertyValue: string | PropValue | TransformablePropValue< string, unknown >;
+};
+
+function resolvePropValue( value: unknown, forceKey?: string ): PropValue {
+	return Schema.adjustLlmPropValueSchema( value as PropValue, forceKey );
+}
+
+export const doUpdateElementProperty = ( params: OwnParams ) => {
+	const { elementId, propertyName, propertyValue, elementType } = params;
+
+	if ( propertyName === '_styles' ) {
+		const elementStyles = getElementStyles( elementId ) || {};
+		const propertyMapValue = propertyValue as Record< string, PropValue >;
+		const styleSchema = getStylesSchema();
+		const transformedStyleValues = Object.fromEntries(
+			Object.entries( propertyMapValue ).map( ( [ key, val ] ) => {
+				if ( key === 'custom_css' ) {
+					return [ key, val ];
+				}
+				const { key: propKey, kind } = styleSchema?.[ key ] || {};
+				if ( ! propKey && kind !== 'union' ) {
+					throw new Error( `_styles property ${ key } is not supported.` );
+				}
+				return [ key, resolvePropValue( val, propKey ) ];
+			} )
+		);
+		let customCss: CustomCss | undefined;
+		Object.keys( propertyMapValue as Record< string, unknown > ).forEach( ( stylePropName ) => {
+			const propertyRawSchema = styleSchema[ stylePropName ];
+			if ( stylePropName === 'custom_css' ) {
+				customCss = {
+					raw: btoa( propertyMapValue[ stylePropName ] as string ),
+				};
+				return;
+			}
+			const isSupported = !! propertyRawSchema;
+			if ( ! isSupported ) {
+				throw new Error( `_styles property ${ stylePropName } is not supported.` );
+			}
+			if ( propertyRawSchema.kind === 'plain' ) {
+				if ( typeof ( propertyMapValue as Record< string, unknown > )[ stylePropName ] !== 'object' ) {
+					const propUtil = getPropSchemaFromCache( propertyRawSchema.key );
+					if ( propUtil ) {
+						const plainValue = propUtil.create( propertyMapValue[ stylePropName ] );
+						propertyMapValue[ stylePropName ] = plainValue;
+					}
+				}
+			}
+		} );
+		const localStyle = Object.values( elementStyles ).find( ( style ) => style.label === 'local' );
+		if ( ! localStyle ) {
+			createElementStyle( {
+				elementId,
+				custom_css: customCss,
+				classesProp: 'classes',
+				label: 'local',
+				meta: {
+					breakpoint: 'desktop',
+					state: null,
+				},
+				props: {
+					...transformedStyleValues,
+				},
+			} );
+		} else {
+			updateElementStyle( {
+				elementId,
+				styleId: localStyle.id,
+				meta: {
+					breakpoint: 'desktop',
+					state: null,
+				},
+				props: {
+					...transformedStyleValues,
+				},
+			} );
+		}
+		return;
+	}
+
+	const elementPropSchema = getWidgetsCache()?.[ elementType ]?.atomic_props_schema;
+	if ( ! elementPropSchema ) {
+		throw new Error( `No prop schema found for element type: ${ elementType }` );
+	}
+	if ( ! elementPropSchema[ propertyName ] ) {
+		const propertyNames = Object.keys( elementPropSchema );
+		throw new Error(
+			`Property "${ propertyName }" does not exist on element type "${ elementType }". Available properties are: ${ propertyNames.join(
+				', '
+			) }`
+		);
+	}
+	const value = resolvePropValue( propertyValue );
+	updateElementSettings( {
+		id: elementId,
+		props: {
+			[ propertyName ]: value,
+		},
+		withHistory: false,
+	} );
+};

package/src/mcp/utils/generate-available-tags.ts

@@ -0,0 +1,23 @@
+import { getWidgetsCache, type V1ElementConfig } from '@elementor/editor-elements';
+
+type ElTypedElementConfig = V1ElementConfig< {
+	elType?: string;
+} >;
+
+export const generateAvailableTags = () => {
+	const cache = getWidgetsCache< ElTypedElementConfig >();
+	if ( ! cache ) {
+		return [];
+	}
+	const customTags = Object.entries( cache )
+		.filter( ( [ , widgetData ] ) => !! widgetData.atomic_controls )
+		.map( ( [ widgetType, widgetData ] ) => {
+			const configurationSchema = widgetData; //getElementSchemaAsJsonSchema( widgetType );
+			return {
+				tag: `${ widgetType }`,
+				description: widgetData.title || widgetData.elType || `A ${ widgetType } element`,
+				configurationSchema: JSON.stringify( configurationSchema ),
+			};
+		} );
+	return customTags;
+};