@elementor/elementor-v3-mcp 4.1.0-754

package/src/resources.ts

@@ -0,0 +1,186 @@
+import { type McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import { getPageOverView, loadDocumentSchema, loadDocumentSettings } from './context';
+import type { ElementorControls } from './types';
+import { encodeToolJson, getElementor } from './utils';
+
+export const RESOURCE_NAME_ELEMENT_SETTINGS = 'elementor-element-settings';
+export const RESOURCE_URI_ELEMENT_SETTINGS_TEMPLATE = 'elementor://editor/element-settings/{elementId}';
+
+export const RESOURCE_NAME_WIDGET_CONFIG = 'elementor-widget-config';
+export const RESOURCE_URI_WIDGET_CONFIG_TEMPLATE = 'elementor://editor/widget-config/{widgetType}';
+
+export const RESOURCE_NAME_PAGE_OVERVIEW = 'elementor-page-overview';
+export const RESOURCE_URI_PAGE_OVERVIEW = 'elementor://editor/page-overview';
+
+export const RESOURCE_NAME_PAGE_SETTINGS = 'elementor-page-settings';
+export const RESOURCE_URI_PAGE_SETTINGS = 'elementor://editor/page-settings';
+
+export function decodeResourceVariable( value: string ): string {
+	try {
+		let decoded = decodeURIComponent( value ).replace( /[·]/g, '' );
+		decoded = decoded.replace( /^{|}$/g, '' );
+		return decoded;
+	} catch {
+		return value;
+	}
+}
+
+async function handleGetWidgetSettings( params: { elementId: string; action: string } ): Promise< {
+	content: [ { type: 'text'; text: string } ];
+} > {
+	const elementor = getElementor();
+	const container = elementor?.getContainer( params.elementId );
+	if ( ! container ) {
+		throw new Error( `Element with ID ${ params.elementId } not found.` );
+	}
+
+	const settings = container.settings.attributes || {};
+	return {
+		content: [ { type: 'text', text: encodeToolJson( settings ) } ],
+	};
+}
+
+async function handleGetWidgetSchema( params: { widgetType: string; action: string } ): Promise< {
+	content: [ { type: 'text'; text: string } ];
+} > {
+	const elementor = getElementor();
+	const controls = elementor?.widgetsCache[ params.widgetType ]?.controls as ElementorControls | undefined;
+	if ( ! controls ) {
+		throw new Error( `Widget type ${ params.widgetType } not found.` );
+	}
+
+	return {
+		content: [ { type: 'text', text: encodeToolJson( controls ) } ],
+	};
+}
+
+export function addElementorResources( server: McpServer ): void {
+	server.resource(
+		RESOURCE_NAME_PAGE_OVERVIEW,
+		RESOURCE_URI_PAGE_OVERVIEW,
+		{
+			description:
+				'Complete page structure showing all elements, containers, and their hierarchical relationships on the current Elementor page',
+		},
+		async ( uri ) => {
+			const overview = getPageOverView();
+
+			if ( ! overview || overview.error ) {
+				throw new Error( overview?.error || 'Failed to retrieve page overview' );
+			}
+
+			return {
+				contents: [
+					{
+						uri: uri.toString(),
+						mimeType: 'application/json',
+						text: encodeToolJson( overview ),
+					},
+				],
+			};
+		}
+	);
+
+	server.resource(
+		RESOURCE_NAME_PAGE_SETTINGS,
+		RESOURCE_URI_PAGE_SETTINGS,
+		{
+			description:
+				'Page/document settings schema and current values including title, template, margins, padding, and backgrounds',
+		},
+		async ( uri ) => {
+			const elementor = getElementor();
+			const currentDocument = elementor?.documents?.getCurrent();
+			if ( ! currentDocument ) {
+				throw new Error( 'No active document found' );
+			}
+
+			const documentSchema = loadDocumentSchema( currentDocument.id );
+			const documentSettings = loadDocumentSettings( currentDocument.id );
+
+			if ( ! documentSchema || ! documentSettings ) {
+				throw new Error( 'Failed to retrieve page settings' );
+			}
+
+			const result = {
+				schema: documentSchema,
+				currentSettings: documentSettings,
+			};
+
+			return {
+				contents: [
+					{
+						uri: uri.toString(),
+						mimeType: 'application/json',
+						text: encodeToolJson( result ),
+					},
+				],
+			};
+		}
+	);
+
+	server.resource(
+		RESOURCE_NAME_ELEMENT_SETTINGS,
+		new ResourceTemplate( RESOURCE_URI_ELEMENT_SETTINGS_TEMPLATE, {
+			list: undefined,
+		} ),
+		{
+			description:
+				'Complete settings schema and current values for a specific element, including all available configuration options and their current state',
+		},
+		async ( uri, variables ) => {
+			let elementId = Array.isArray( variables.elementId ) ? variables.elementId[ 0 ] : variables.elementId;
+
+			if ( ! elementId ) {
+				throw new Error( 'Element ID is required' );
+			}
+
+			elementId = decodeResourceVariable( elementId );
+
+			const result = await handleGetWidgetSettings( { elementId, action: 'get-widget-settings' } );
+
+			return {
+				contents: [
+					{
+						uri: uri.toString(),
+						mimeType: 'text/plain',
+						text: result.content[ 0 ].text,
+					},
+				],
+			};
+		}
+	);
+
+	server.resource(
+		RESOURCE_NAME_WIDGET_CONFIG,
+		new ResourceTemplate( RESOURCE_URI_WIDGET_CONFIG_TEMPLATE, {
+			list: undefined,
+		} ),
+		{
+			description:
+				'Complete configuration schema for a specific widget type, showing all available settings, properties, and their expected formats',
+		},
+		async ( uri, variables ) => {
+			let widgetType = Array.isArray( variables.widgetType ) ? variables.widgetType[ 0 ] : variables.widgetType;
+
+			if ( ! widgetType ) {
+				throw new Error( 'Widget type is required' );
+			}
+
+			widgetType = decodeResourceVariable( widgetType );
+
+			const result = await handleGetWidgetSchema( { widgetType, action: 'get-widget-schema' } );
+
+			return {
+				contents: [
+					{
+						uri: uri.toString(),
+						mimeType: 'text/plain',
+						text: result.content[ 0 ].text,
+					},
+				],
+			};
+		}
+	);
+}

package/src/tools/ai-tool.ts

@@ -0,0 +1,58 @@
+import { z } from '@elementor/schema';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import type { McpToolResult } from '../types';
+import { get$e } from '../utils';
+
+export function addAiTool( server: McpServer ): void {
+	server.registerTool(
+		'ai',
+		{
+			description: 'Manage Elementor AI integration features and interfaces.',
+			inputSchema: {
+				action: z
+					.enum( [ 'open-brand-voice', 'open-choose-element', 'open-text-to-elementor' ] )
+					.describe( 'The AI operation to perform' ),
+			},
+			annotations: {
+				title: 'Manage AI Integration',
+			},
+		},
+		async ( params ) => {
+			switch ( params.action ) {
+				case 'open-brand-voice':
+					return await handleOpenBrandVoice();
+				case 'open-choose-element':
+					return await handleOpenChooseElement();
+				case 'open-text-to-elementor':
+					return await handleOpenTextToElementor();
+				default:
+					throw new Error( `Unknown action: ${ params.action }` );
+			}
+		}
+	);
+}
+
+async function handleOpenBrandVoice(): Promise< McpToolResult > {
+	await get$e()?.run( 'ai-integration/open-brand-voice' );
+
+	return {
+		content: [ { type: 'text', text: 'Brand Voice interface opened.' } ],
+	};
+}
+
+async function handleOpenChooseElement(): Promise< McpToolResult > {
+	await get$e()?.run( 'ai-integration/open-choose-element' );
+
+	return {
+		content: [ { type: 'text', text: 'Choose Element interface opened.' } ],
+	};
+}
+
+async function handleOpenTextToElementor(): Promise< McpToolResult > {
+	await get$e()?.run( 'ai-integration/open-text-to-elementor' );
+
+	return {
+		content: [ { type: 'text', text: 'Text to Elementor interface opened.' } ],
+	};
+}

package/src/tools/dynamic-tool.ts

@@ -0,0 +1,236 @@
+import { z } from '@elementor/schema';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import type { ElementorContainer, McpToolResult, ToolParams } from '../types';
+import { get$e, getElementor, getElementorCommon } from '../utils';
+import { validateDynamicTagDisabled, validateDynamicTagEnabled } from '../validation-helpers';
+
+export function addDynamicTool( server: McpServer ): void {
+	server.registerTool(
+		'dynamic',
+		{
+			description:
+				'Manage dynamic-tags content for Elementor elements including getting dynamic settings, enabling and disabling dynamic tags.',
+			inputSchema: {
+				action: z
+					.enum( [ 'get-settings', 'enable', 'disable' ] )
+					.describe( 'The dynamic content operation to perform' ),
+				elementId: z.string().describe( 'The ID of the element to modify' ),
+				controlName: z.string().describe( 'The name of the control/setting to make dynamic' ),
+				dynamicName: z
+					.string()
+					.optional()
+					.describe(
+						'The name of the dynamic tag to enable. Required for enable action. Output of get-settings action.'
+					),
+				settings: z
+					.object( {} )
+					.catchall( z.unknown() )
+					.optional()
+					.describe(
+						'The settings to apply to the dynamic tag. Used with enable action. Output of get-settings action.'
+					),
+				hasRunGetDynamicSettings: z
+					.boolean()
+					.optional()
+					.describe(
+						'Whether the get-settings action has already been run. Must be set to true when using enable action.'
+					),
+			},
+			annotations: {
+				title: 'Manage Dynamic Content',
+			},
+		},
+		async ( params: ToolParams ) => {
+			switch ( params.action ) {
+				case 'get-settings':
+					return await handleGetDynamicSettings( params );
+				case 'enable':
+					if ( params.hasRunGetDynamicSettings !== true ) {
+						throw new Error(
+							'get-dynamic-settings action has not been run. Run it first before using the enable action.'
+						);
+					}
+					if ( ! params.elementId || ! params.controlName || ! params.dynamicName || ! params.settings ) {
+						throw new Error(
+							'elementId, controlName, dynamicName, and settings are required for dynamic enable'
+						);
+					}
+					return await handleDynamicEnable( params );
+				case 'disable':
+					if ( ! params.elementId || ! params.controlName ) {
+						throw new Error( 'elementId and controlName are required for dynamic disable' );
+					}
+					return await handleDynamicDisable( params );
+				default:
+					throw new Error( `Unknown action: ${ params.action }` );
+			}
+		}
+	);
+}
+
+async function handleGetDynamicSettings( params: ToolParams ): Promise< McpToolResult > {
+	if ( ! params.elementId || ! params.controlName ) {
+		throw new Error( 'elementId and controlName are required for get-settings' );
+	}
+
+	const elementor = getElementor();
+	const container = elementor?.getContainer( params.elementId as string );
+	if ( ! container ) {
+		throw new Error( `Element with ID ${ params.elementId } not found.` );
+	}
+
+	const controls = container.settings.controls as Record< string, { dynamic?: { categories?: string[] } } >;
+	const control = controls[ params.controlName as string ];
+
+	if ( ! control ) {
+		throw new Error( `Control "${ params.controlName }" not found on element ${ params.elementId }.` );
+	}
+
+	if ( ! control.dynamic?.categories ) {
+		throw new Error( `Control "${ params.controlName }" does not support dynamic content.` );
+	}
+
+	const { categories } = control.dynamic;
+	const dynamicTags = elementor?.dynamicTags;
+
+	if ( ! dynamicTags?.getConfig ) {
+		throw new Error( 'Dynamic tags API is not available.' );
+	}
+
+	const tags = dynamicTags.getConfig( 'tags' ) as Record< string, { categories: string[] } >;
+	const relevantTags = Object.values( tags ).filter( ( tag ) =>
+		tag.categories.find( ( category ) => categories.includes( category ) )
+	);
+
+	return {
+		content: [ { type: 'text', text: JSON.stringify( relevantTags, null, 2 ) } ],
+	};
+}
+
+async function handleDynamicEnable( params: ToolParams ): Promise< McpToolResult > {
+	if ( ! params.elementId || ! params.controlName || ! params.dynamicName ) {
+		throw new Error( 'elementId, controlName, and dynamicName are required for dynamic enable' );
+	}
+
+	if ( params.hasRunGetDynamicSettings !== true ) {
+		throw new Error( 'get-dynamic-settings action has not been run. Run it first before using the enable action.' );
+	}
+
+	const elementor = getElementor();
+	const container = elementor?.getContainer( params.elementId as string );
+	if ( ! container ) {
+		throw new Error( `Element with ID ${ params.elementId } not found.` );
+	}
+
+	const dynamicName = ( params.dynamicName as string )
+		.toLowerCase()
+		.replace( /\s+/g, '-' )
+		.replace( /_/g, '-' )
+		.replace( /[^a-z0-9-]/g, '' );
+
+	const settings = ( params.settings || {} ) as Record< string, unknown > & {
+		toJSON?: () => Record< string, unknown >;
+	};
+	settings.toJSON = () => settings;
+
+	const elementorCommon = getElementorCommon();
+	if ( ! elementorCommon?.helpers?.getUniqueId ) {
+		throw new Error( 'Elementor Common API is not available.' );
+	}
+
+	const uniqueId = elementorCommon.helpers.getUniqueId();
+
+	const dynamicTags = elementor?.dynamicTags;
+
+	if ( ! dynamicTags?.tagDataToTagText ) {
+		throw new Error( 'Dynamic tags API is not available.' );
+	}
+
+	const tagText = dynamicTags.tagDataToTagText( String( uniqueId ), dynamicName, settings );
+
+	await get$e()?.run( 'document/dynamic/enable', {
+		container,
+		settings: { [ params.controlName as string ]: tagText },
+	} );
+
+	validateDynamicTagEnabled( container, params.controlName as string );
+
+	return {
+		content: [
+			{
+				type: 'text',
+				text: `Dynamic content enabled for element ${ params.elementId }, control "${ params.controlName }" with dynamic tag "${ dynamicName }": ${ tagText }`,
+			},
+		],
+	};
+}
+
+async function handleDynamicDisable( params: ToolParams ): Promise< McpToolResult > {
+	if ( ! params.elementId || ! params.controlName ) {
+		throw new Error( 'elementId and controlName are required for dynamic disable' );
+	}
+
+	const container = getElementor()?.getContainer( params.elementId as string );
+	if ( ! container ) {
+		throw new Error( `Element with ID ${ params.elementId } not found.` );
+	}
+
+	const getElementDynamicSetting = ( elementContainer: ElementorContainer ) => {
+		const modelSettings = ( elementContainer.model?.attributes?.settings || {} ) as Record< string, unknown >;
+
+		const dynamicContent: Record< string, unknown > = {};
+
+		Object.keys( modelSettings ).forEach( ( key ) => {
+			const value = modelSettings[ key ];
+			let dynamicData = null;
+
+			if ( value && typeof value === 'object' && ( value as { __dynamic__?: unknown } ).__dynamic__ ) {
+				dynamicData = ( value as { __dynamic__: unknown } ).__dynamic__;
+			}
+
+			if ( dynamicData ) {
+				dynamicContent[ key ] = dynamicData;
+			}
+		} );
+
+		return {
+			settingsNames: Object.keys(
+				( dynamicContent as { attributes?: Record< string, unknown > } ).attributes || {}
+			),
+			dynamicContent,
+		};
+	};
+
+	const availableDynamicSettingNames = getElementDynamicSetting( container ).settingsNames;
+
+	if ( ! availableDynamicSettingNames.includes( params.controlName as string ) ) {
+		throw new Error(
+			`Setting "${ params.controlName }" on element ${
+				params.elementId
+			} does not have dynamic content enabled. here is the list of dynamic settings available: ${ JSON.stringify(
+				availableDynamicSettingNames,
+				null,
+				2
+			) }`
+		);
+	}
+
+	await get$e()?.run( 'document/dynamic/disable', {
+		container,
+		settings: {
+			[ params.controlName as string ]: '',
+		},
+	} );
+
+	validateDynamicTagDisabled( container, params.controlName as string );
+
+	return {
+		content: [
+			{
+				type: 'text',
+				text: `Dynamic content disabled for setting "${ params.controlName }" on element ${ params.elementId }.`,
+			},
+		],
+	};
+}

package/src/tools/index.ts

@@ -0,0 +1,6 @@
+export { addAiTool } from './ai-tool';
+export { addDynamicTool } from './dynamic-tool';
+export { addPageTool } from './page-tool';
+export { addRoutesTool } from './routes-tool';
+export { addStylingTool } from './styling-tool';
+export { addUiTool } from './ui-tool';

package/src/tools/page-tool.ts

@@ -0,0 +1,222 @@
+import { z } from '@elementor/schema';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import { RESOURCE_URI_PAGE_SETTINGS } from '../resources';
+import type { ElementorContainer, McpToolResult, ToolParams } from '../types';
+import { encodeToolJson, get$e, getElementor } from '../utils';
+import { validateDocumentSettingsUpdated } from '../validation-helpers';
+
+export function addPageTool( server: McpServer ): void {
+	server.registerTool(
+		'page',
+		{
+			description: `Manage page and document operations including undo/redo, saving, page settings, and page information. Use this tool when you need to: 
+		- Undo or redo changes (history-undo, history-redo, history-undo-all) - Use these when user asks to undo, revert, or redo recent changes
+		- Save page changes (save-draft, save-publish, save-update, save-discard)
+		- Get or update page settings like page title, description, keywords, styling (get-settings, update-settings)
+		- Open or preview pages (open, preview)
+		This tool handles document-level operations and change history.`,
+			inputSchema: {
+				action: z
+					.enum( [
+						'save-draft',
+						'save-publish',
+						'save-update',
+						'save-discard',
+						'history-undo',
+						'history-redo',
+						'history-undo-all',
+						'get-settings',
+						'update-settings',
+						'open',
+						'preview',
+					] )
+					.describe(
+						'The page operation to perform: history-undo (revert the last change - use when user says "undo"), history-redo (reapply last undone change - use when user says "redo"), history-undo-all (revert all changes), save-draft (save as draft), save-publish (publish page), save-update (update published page), save-discard (discard unsaved changes), get-settings (retrieve page settings), update-settings (modify page settings), open (open a different page), preview (preview the page)'
+					),
+				pageId: z.string().optional().describe( 'Page/document ID for open action' ),
+				settings: z
+					.record( z.unknown() )
+					.optional()
+					.describe(
+						'Settings object containing the specific page settings you want to update. REQUIRED for update-settings action. Only include settings you want to change, not all settings. Example: {"hide_title": "yes", "template": "elementor_canvas"}.'
+					),
+			},
+			annotations: {
+				title: 'Manage Page',
+			},
+			_meta: {
+				'angie:required-resources': [
+					{
+						uri: RESOURCE_URI_PAGE_SETTINGS,
+						whenToUse:
+							'When updating page settings (action=update-settings) to understand the page schema, available settings, their allowed values, and current page configuration',
+					},
+				],
+			},
+		},
+		async ( params: ToolParams ) => {
+			switch ( params.action ) {
+				case 'save-draft':
+					return await handleSavePageDraft();
+				case 'save-publish':
+					return await handleSavePagePublish();
+				case 'save-update':
+					return await handleSavePageUpdate();
+				case 'save-discard':
+					return await handleSavePageDiscard();
+				case 'history-undo':
+					return await handleHistoryUndo();
+				case 'history-redo':
+					return await handleHistoryRedo();
+				case 'history-undo-all':
+					return await handleHistoryUndoAll();
+				case 'get-settings':
+					return await handleGetDocumentSettings();
+				case 'update-settings':
+					return await handleUpdateDocumentSettings( params );
+				case 'open':
+					return await handleOpenPage( params );
+				case 'preview':
+					return await handlePreviewPage();
+				default:
+					throw new Error( `Unknown action: ${ params.action }` );
+			}
+		}
+	);
+}
+
+async function handleSavePageDraft(): Promise< McpToolResult > {
+	await get$e()?.run( 'document/save/draft' );
+	return {
+		content: [ { type: 'text', text: 'Page saved as draft.' } ],
+	};
+}
+
+async function handleSavePagePublish(): Promise< McpToolResult > {
+	await get$e()?.run( 'document/save/publish' );
+	return {
+		content: [ { type: 'text', text: 'Page published.' } ],
+	};
+}
+
+async function handleSavePageUpdate(): Promise< McpToolResult > {
+	await get$e()?.run( 'document/save/update' );
+	return {
+		content: [ { type: 'text', text: 'Page updated.' } ],
+	};
+}
+
+async function handleSavePageDiscard(): Promise< McpToolResult > {
+	await get$e()?.run( 'document/save/discard' );
+	return {
+		content: [ { type: 'text', text: 'Page changes discarded.' } ],
+	};
+}
+
+async function handleHistoryUndo(): Promise< McpToolResult > {
+	await get$e()?.run( 'document/history/undo' );
+	return {
+		content: [ { type: 'text', text: 'Undo performed.' } ],
+	};
+}
+
+async function handleHistoryRedo(): Promise< McpToolResult > {
+	await get$e()?.run( 'document/history/redo' );
+	return {
+		content: [ { type: 'text', text: 'Redo performed.' } ],
+	};
+}
+
+async function handleHistoryUndoAll(): Promise< McpToolResult > {
+	await get$e()?.run( 'document/history/undo-all', { document: getElementor()?.documents.getCurrent() } );
+	return {
+		content: [ { type: 'text', text: 'All changes undone.' } ],
+	};
+}
+
+async function handleOpenPage( params: ToolParams ): Promise< McpToolResult > {
+	if ( ! params.pageId ) {
+		throw new Error( 'pageId is required for open action' );
+	}
+
+	await get$e()?.run( 'editor/documents/open', {
+		id: params.pageId,
+	} );
+
+	return {
+		content: [ { type: 'text', text: `Page ${ params.pageId } opened.` } ],
+	};
+}
+
+async function handlePreviewPage(): Promise< McpToolResult > {
+	await get$e()?.run( 'editor/documents/preview' );
+	return {
+		content: [ { type: 'text', text: 'Page preview opened.' } ],
+	};
+}
+
+async function handleGetDocumentSettings(): Promise< McpToolResult > {
+	const document = getElementor()?.documents?.getCurrent();
+	if ( ! document ) {
+		throw new Error( 'No active document found.' );
+	}
+
+	const settings = document.config?.settings || {};
+
+	return {
+		content: [
+			{
+				type: 'text',
+				text: encodeToolJson( {
+					documentId: document.id,
+					documentType: document.config?.type,
+					settings,
+				} ),
+			},
+		],
+	};
+}
+
+async function handleUpdateDocumentSettings( params: ToolParams ): Promise< McpToolResult > {
+	const currentDocument = getElementor()?.documents?.getCurrent();
+	if ( ! currentDocument ) {
+		throw new Error( 'No active document found.' );
+	}
+
+	if ( ! params.settings || typeof params.settings !== 'object' ) {
+		throw new Error( 'settings object is required for update-settings action' );
+	}
+
+	await get$e()?.run( 'document/elements/settings', {
+		container: currentDocument.container,
+		settings: params.settings,
+		options: {
+			external: true,
+		},
+	} );
+
+	const updatedDocument = getElementor()?.documents?.getCurrent();
+	if ( ! updatedDocument?.container ) {
+		throw new Error( 'Document container not found after update' );
+	}
+	validateDocumentSettingsUpdated( updatedDocument.container as unknown as ElementorContainer );
+
+	return {
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify( {
+					success: true,
+					message: `Document settings updated successfully. Settings: ${ JSON.stringify(
+						params.settings,
+						null,
+						2
+					) }`,
+					saveChangesSuggestion: 'Suggest the following quick user replies: "Publish Changes", "Save Draft"',
+					nextStep: 'Page settings updated in editor. User should save the page to persist changes.',
+				} ),
+			},
+		],
+	};
+}