Elementor v4 MCP Abilities 能力体系全解析基于 WordPress Abilities API 的外部智能体编排接口【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementorElementor 在 v4Atomic Builder中通过modules/mcp/module.php对外暴露了一套完整的PHP MCP abilities能力任何外部 MCP 主机如 Claude、自定义 Agent都可以借助它们查询组件 Schema、管理全局设计令牌变量与类并原子化构建/修改页面元素树。本文以仓库文档 docs/atomic-builder/mcp/abilities/README.md 为核心骨架逐一拆解 9 个能力的作用、输入输出契约与推荐调用顺序并结合modules/mcp/下的源码实现说明其底层原理帮助读者直接上手用 MCP 驱动 Elementor 完成读资源 → 建令牌 → 查 Schema → 构建组合的完整编排流程。一、背景v4 MCP abilities 是什么在 Elementor v4 架构中MCP 能力分为两条完全独立的面PHP abilities——通过 WordPress Abilities APIwp_register_ability注册的服务端工具与资源经由elementor-mcp-server或Mcp_Proxy_REST_API对外提供服务外部 MCP 主机使用JS in-editor registry——v4 编辑器包内的按域McpServer实例桥接 Angie 与 WebMCP供编辑器包内部使用。本文讨论的是第一条路径modules/mcp/module.php中注册的 v4 PHP abilities。需要注意外部的elementor/build-composition并不走 JS 的getMCPByDomain()二者不要混淆详见 overview。从 overview.md 可以看到三个关键注册钩子Hook用途wp_abilities_api_categories_init注册elementor能力分类wp_abilities_api_init注册所有 Elementor abilitiesmcp_adapter_init注册elementor-mcp-server工具与资源列表当McpAdapter与wp_register_ability同时存在时PHP abilities 会无条件注册。二、公共 API一切能力都继承自Abstract_Ability所有 v4 abilities 都继承同一个抽象基类Abstract_Ability形成统一契约对应源码 abstract-ability.phpSymbolSignaturePurposeAbstract_Abilityregister(): void调用wp_register_ability()并传入execute_callback*Ability子类execute( $input [] )能力的具体实现各子类还实现get_ability_id(): string返回稳定的能力 ID例如elementor/build-composition。这意味着外部主机只需学会一种调用范式——通过能力 ID 传入$input数组——即可使用全部 9 个能力。三、能力清单9 个可用能力一览仓库文档 abilities/README.md 给出了完整清单文档Ability IDbuild-compositionelementor/build-compositionget-widget-schemaelementor/get-widget-schemalist-widget-schemaselementor/list-widget-schemasmanage-classeselementor/manage-classesreorder-classeselementor/reorder-classesmanage-global-variableelementor/manage-global-variablemanage-elementselementor/manage-elementslist-componentselementor/list-componentsinteractions-schema-resourceelementor/interactions-schema-resource其中manage-global-variable还附带一个引导型能力elementor/manage-global-variable-guide对应资源elementor://variables/tools/manage-global-variable-guide用于向 Agent 提供命名规则与 Pro 类型清单。四、推荐调用顺序从读资源到持久化的完整工作流原文档明确指出完整的工作流见 composition-workflow.md推荐的调用顺序如下读取资源global-variables、global-classes、style/best-practicesmanage-global-variable→manage-classeslist-widget-schemassummary: true→list-components如果使用e-component按类型调用get-widget-schema→ 必要时读取interactions/schemabuild-composition先dry_run→ 用manage-elements做后续精修动态标签的发现走list-dynamic-tags见 dynamic-tags/discovery.md。使用原则从零构建整页布局或容器重设计走完整流程单个元素的小改动则在组合完成后用manage-elements处理。五、核心能力详解5.1elementor/build-composition用 XML 并行映射表构建元素树这是编排流程的中心环节由 build-composition-ability.php 实现负责把XML 骨架 三个并行配置映射表element_config、style、classes转换成 v4 元素树并持久化。权限要求edit_posts且对post_id有edit_post。必需输入字段类型说明post_idintegerElementor 文档对应的 WordPress 文章 IDxml_structurestring由 widget 标签构成、每个元素都带configuration-id的 XML可选输入字段默认值说明element_config{}configuration-id→ 普通 widget 设置见get-widget-schemastyle{}configuration-id→ 原始 CSS 声明property→ valueclasses{}configuration-id→ 全局类label数组parent_iddocument父元素 IDdocument表示根modeappendappend或replace_childrendry_runfalse仅校验不持久化XML 规则是使用中最重要的约束标签即 widget 类型e-flexbox、e-heading、e-button等每个元素必须有唯一且语义化的configuration-id属性禁止出现其他属性、class、元素 ID 与文本节点嵌套必须满足 widget schema 中的allowed_child_types/required_direct_children不要用 CDATA 包裹——会导致empty_composition错误。完整请求示例{ post_id: 123, xml_structure: e-flexbox configuration-id\hero-section\e-heading configuration-id\hero-title\/e-heading/e-flexbox, element_config: { hero-title: { tag: h2, title: Welcome } }, style: { hero-section: { padding-top: 6rem, padding-bottom: 6rem }, hero-title: { font-size: 3.5rem } }, classes: { hero-title: [text-muted] } }element_config格式要点使用与get-widget-schema输出一致的普通 JSON标准属性无需$$type包装文本属性e-heading的title、e-paragraph的paragraph、e-button的text直接传字符串而非{ content, children }动态值用{ name: post-title, settings: {} }图片用{ src: { url: ... }, size: full }。除非用户要求修改应省略llm_guidance.default_settings中列出的键。CSS 转换策略style中的 CSS 字符串会尽可能转换为原生原子样式部分形态会回退到custom_cssanimation会被丢弃。官方建议优先使用media(--breakpoint)而非像素查询、单值gap、字面量box-shadow以及padding/margin简写。mode与dry_run语义append在parent_id下追加子元素replace_children先移除parent_id的直接子元素再插入响应中包含removed_element_idsdry_run: true跑完整校验管线但不调用Composition_Persister。输出字段字段说明success成功为truepost_id文档 IDroot_element_ids创建的根级元素 IDdry_run时为空preview_url编辑器预览 URLversion文章修改时间戳resolved_xml嵌入了 Elementor 元素 ID 的 XMLllm_instructions给 Agent 的下一步提示warnings非致命跳过项未知属性、CSS 回退removed_element_idsmode: replace_children时存在底层管线modules/mcp/abilities/build-composition/子目录Xml_Parser解析configuration-id与composition-root包装→Widget_Type_Resolver标签 → widget 配置 子类型校验→Subtree_BuilderDOM → 元素树索引→Element_Config_Applier/Class_Applier/Style_Applier应用并行映射表→Composition_Persister通过Document_Mutator插入/保存。当变量实验启用时还会使用Css_Converter、Converter_Registry_Factory、Expander_Registry_Factory与Variable_Prop_Value_Transformer。5.2elementor/get-widget-schema单类型 Schema 的事实来源由 get-widget-schema-ability.php 实现返回单个 widget 类型的实时 JSON Schema是构造element_config的权威依据。权限edit_posts。输入widget_type必填即注册表中的标识符如e-heading、e-flexbox。输出v4 原子 widget具有atomic_props_schema时{ type: object, properties: { }, description: Widget description from meta, llm_guidance: { can_have_children: true, instructions: ..., default_styles: { }, default_settings: { }, nesting: { allowed_child_types: [e-heading, e-button], allowed_parents: [e-flexbox, document] }, required_direct_children: [e-tab-content] } }llm_guidance字段含义由Llm_Guidance_Builder依据 widget 配置构建字段含义can_have_children是否为容器meta.is_containerinstructions何时应从element_config省略default_styles/default_settingsdefault_styles基础样式 CSS 映射——仅在需要覆盖时传入default_settings基础设置——除非用户要求修改否则省略nesting.allowed_child_types合法的子 widget 类型nesting.allowed_parents合法的父类型来自 parents indexrequired_direct_children必须作为直接 XML 子节点出现的类型NON_CONFIGURABLE_PROP_KEYSclasses、attributes等中的属性会被排除除非设置了llm_configurablemeta。v3 回退没有atomic_props_schema但有传统控件的 widget 会返回widget_version: v3加说明消息build-composition只针对 v4 元素v3 回退仅作参考。错误缺少widget_type返回invalid_input未知类型或meta.llm_support: false返回elementor_not_found。Widget 作者通过 widget 配置中的meta.llm_support和define_props_schema()开启 LLM 支持Schema 过滤器为elementor/atomic-widgets/llm-json-schema见 atomic-widgets/hooks.md。5.3elementor/list-widget-schemasv4 widget 批量发现由 list-widget-schemas-ability.php 实现用于发现全部 v4 原子 widget。权限edit_posts。输入summary默认false。为true时只返回轻量列表。输出summary 模式{ widgets: [ { type: e-heading, description: Heading widget }, { type: e-flexbox, description: Flexbox container } ] }输出完整模式以 widget 类型为键的对象每个条目与get-widget-schema单类型输出同构含llm_guidancepayload 更大。v4 过滤仅当Widget_Context_Helper::get_widget_version()返回v4具备atomic_props_schema的 widget 才被列出v3 专用 widget 被排除还需满足meta.llm_support ! false并按标题排除 Component widget。使用建议第一遍用summary: true做轻量发现确定类型后对单个 widget 用get-widget-schema拿全量 Schema——更小且始终最新。批量拿全量 Schema 只在确实需要时才做。5.4elementor/manage-global-variable全局设计令牌批量 CRUD由 manage-variable-ability.php 与manage-variable-guide-ability.php实现对激活 Kit 上的全局设计令牌--label: value做批量增删改。权限manage_options。输入operations必填1–50 个操作对象的数组。变量类型type值值格式可用性global-color-variableCSS 颜色#FF0000、rgba(...)、hsl(...)始终可用global-font-variable仅字体族名Roboto、Playfair Display始终可用global-size-variable简单长度单位16px、1.5rem、2emElementor Proglobal-custom-size-variableCSS 函数/关键字auto、clamp(...)、calc(...)、300msElementor Pro切勿把 px/rem 值放进global-font-variable应使用 size 类型。操作形状action必填字段createtype、label、valueupdateid、label、valuedeleteid命名规则label 仅允许小写字母、数字、连字符与下划线不得含空格或特殊字符且必须唯一——创建前先读elementor://global-variables。示例Headline Primary→headline-primary。示例{ action: create, type: global-color-variable, label: brand-primary, value: #1A73E8 }{ action: update, id: abc123, label: brand-primary, value: #0D47A1 }输出status、results[]含index、action、status、id、label以及watermark——每成功处理一批就会递增用于检测对elementor://global-variables的过期读取。底层实现委托Variables_Service::process_batch()Variables_Repository作用于激活 Kit变更后清除文件缓存与运行时对象缓存。新变量类型通过Variable_Types_Registry与elementor/variables/register钩子注册见 variables/types.md。5.5elementor/manage-classes全局 CSS 类批量 CRUD由 manage-classes-ability.php 实现对激活 Kit 上的全局 CSS 类做批量增删改原始 CSS 经Css_Converter转为样式属性。权限edit_posts。输入operations必填1–50 个操作对象。操作形状action必填字段说明createlabel、csscss是{ property: value }映射服务端生成内部g-*idupdateid、label、cssid取自elementor://global-classes的键deleteid从 Kit 移除类css格式为属性 → 值的原始 CSS 声明对象{ action: create, label: hero-heading, css: { font-size: 3.5rem, font-weight: 700, color: var(--brand-primary) } }要点变量引用使用labelvar(--label)必须已存在于elementor://global-variables值为null或null时重置该属性非法变量引用返回invalid_css错误简写属性可能产生custom_css回退base64 存储。Label 引用约定在build-composition与manage-elements中类一律按label引用如classes: { hero-title: [hero-heading, text-muted] }内部g-*id 仅用于 update/delete 操作。重复 label 处理create/update 时重复 label 会被Global_Classes_Labels::generate_unique_label()自动加上DUP_前缀重命名响应中的modified_label: { original, modified }会报告重命名结果。输出{ status: completed, results: [ { index: 0, action: create, status: ok, id: g-abc123, label: hero-heading } ], order: [g-abc123, g-existing] }单个操作失败不中断批次错误包含index、action、code、message。限制单请求最多 50 个操作超出返回batch_size_exceededKit 上限为Global_Classes_REST_API::MAX_ITEMS超出时 create 被拒并返回global_classes_limit_exceeded。5.6elementor/reorder-classes调整全局类优先级由 reorder-classes-ability.php 实现。列表中的第一个类优先级最高当两个应用的类设置了同一 CSS 属性时靠前的类覆盖靠后的。用于解决多个全局类声明冲突导致的样式错误且不改变类定义本身。输入恰好提供moves或order之一。相对移动最多 50 个按顺序执行{ moves: [ { id: g-accent, position: before, ref: g-base }, { id: g-heading, position: start } ] }position可取before、after、start、endbefore/after必须带ref。显式顺序完整或部分优先级序列{ order: [g-heading, g-accent, g-base] }每个提供的 ID 必须存在且只能出现一次请求中省略的现有 ID 会按当前相对顺序追加到末尾并在appended_ids中返回。输出{ changed: true, order: [g-heading, g-accent, g-base], appended_ids: [], moves: [{ id: g-heading, from: 2, to: 0 }] }无变化的请求返回changed: false且不会使已生成的 CSS 失效。底层实现通过Global_Classes_Repository::apply_changes()写入仅含顺序的变更同步更新前端与预览的顺序元数据并触发全局 CSS 缓存失效。5.7elementor/manage-elements按元素 ID 的精细化编辑由 manage-elements-ability.php 实现对文档树中已存在的 v4 元素按元素 ID 做外科手术式编辑更新设置/样式/类、删除、移动、复制。权限edit_posts。公共输入字段必填说明action是update、delete、move或duplicatepost_id是WordPress 文章 IDelement_id是文档树中的目标元素 IDupdatesettings、style、classes至少提供其一。settings是部分普通设置映射与build-composition的element_config同形合并到现有值style为原始 CSS 声明null重置属性classes为要附加的全局类 label 数组前置到现有类之前。delete通过Document_Mutator::remove()移除元素及其后代。movenew_parent_id必填目标父元素 ID 或documentindex可选父内插入位置null为追加。duplicate克隆元素子树并生成全新 ID插入到源元素之后。成功输出{ status: ok, post_id: 123, element_id: abc456, version: 2026-07-26 09:00:00, warnings: [Optional non-fatal notices] }v4 特有依赖尽管名字通用update一旦携带style或classes就依赖 AtomicWidgets CSS 转换栈Css_Converter、Converter_Registry_Factory、Expander_Registry_Factory、Variable_Prop_Value_Transformer与build-composition、manage-classes走同一管线——这也是它被归入 v4 MCP 文档的原因它不适用于传统 v3 widget 的样式路径。错误invalid_input字段缺失/非法、elementor_forbidden无编辑权限、elementor_not_found元素或文档不存在。5.8elementor/list-components可复用组件发现由 list-components-ability.php 实现发现可复用组件及其可选的overridable_propsSchema。要求启用e_components实验。权限edit_posts。两步工作流不带component_ids调用——列出所有组件的id、name、uid、is_archived不含 Schema带component_ids: [42, 87]调用——只为将要嵌入的组件拉取 Schema。组件数量多时为每个组件都请求 Schema 是浪费的。输出字段字段说明id数字型文章 ID——用作element_config中的component_idname人类可读的组件标题uid稳定的字符串标识符is_archived已归档组件不得放入新组合overridable_props仅请求时出现override_key→{ label, group_id?, origin_prop_schema }覆盖值与get-widget-schema采用相同的普通值 JSON Schema 约定无$$type包装。对应的静态提示参考位于modules/mcp/static-resources/abilities/list-components.md。5.9elementor/interactions-schema-resource原生交互 Schema 资源由 interactions-schema-resource-ability.php 实现提供只读的原生交互项 JSON SchemaMIME 为application/json。权限edit_posts。Ability IDelementor/interactions-schema-resource资源 URIelementor://interactions/schema通过read-resource获取Payload 由Interaction_Item_Prop_Type经Widget_Context_Helper::to_plain_llm_schema()生成的 LLM 友好普通 JSON Schema 构成。使用场景向build-composition的element_config或manage-elements更新中发送交互对象之前用它校验交互项的结构避免猜测字段名或枚举值。六、配套资源写操作之前的只读数据源外部 Agent 在执行任何变更前应先读取相关资源详见 resources.mdURIAbility IDMIMEelementor://global-classeselementor/global-classes-resourceapplication/jsonelementor://global-variableselementor/global-variables-resourceapplication/jsonelementor://style/best-practiceselementor/style-best-practicestext/markdownelementor://wordpress/best-practiceselementor/wordpress-best-practicestext/markdownelementor://interactions/schemaelementor/interactions-schema-resourceapplication/jsonelementor://dynamic-tags仅 JSapplication/jsonelementor://variables/tools/manage-global-variable-guideelementor/manage-global-variable-guidetext/plain两条核心约定贯穿所有能力Label 优先资源暴露给作者引用的是label类用elementor://global-classes的 label变量用var(--label)不要向能力发送内部前缀g-*、e-gv-*优先级语义对于全局类classes列表中越靠前的类在同元素多类同属性冲突时越优先需要调整时用elementor/reorder-classes。global-variables返回的watermark值得缓存用于检测过期读取Read_Resource_Ability负责把 URI 映射到对应的执行器elementor://dynamic-tags仅存在于编辑器端不在 PHP 执行器映射表中。七、端到端实战编排示例综合以上内容一个完整的外部 MCP Agent 编排过程如下1. 读取 elementor://global-variables、elementor://global-classes、elementor://style/best-practices 2. 调用 elementor/manage-global-variable —— 创建缺失的设计令牌如 brand-primary 3. 调用 elementor/manage-classes —— 创建缺失的全局类如 hero-heading 4. 调用 elementor/list-widget-schemas?summarytrue —— 确认可用 widget 类型 5. 调用 elementor/get-widget-schema —— 按 widget 类型获取精确 Schema 6. 调用 elementor/build-composition不确定时先 dry_run: true—— 插入/替换元素树 7. 可选调用 elementor/manage-elements —— 对生成元素做精修改样式、移动、复制、删除注意第 2、3 步在build-composition的classes映射和style的var(--label)引用之前完成确保引用目标已存在第 4、5 步保证element_config的属性名、嵌套关系与llm_guidance完全一致第 6 步的dry_run模式可以在不落库的情况下完整跑一遍Xml_Parser→Subtree_Builder→ 各 Applier 的校验管线是上线前最稳妥的试运行手段。八、总结Elementor v4 的 MCP abilities 是一套以Abstract_Ability为统一契约、以modules/mcp/module.php为注册入口、通过 WordPress Abilities API 对外暴露的服务端能力体系。九大能力覆盖了设计令牌管理变量/类→ 组件发现widget/component Schema→ 组合构建XML 并行映射表→ 精细编辑按 ID 增删改移→ 优先级调整的完整生命周期配合只读资源 URI 形成先读后写、dry_run 先行的稳健编排范式。无论是外部 MCP 主机集成、Agent 驱动的页面生成还是编辑器工具扩展这套能力清单与调用顺序都是最直接的接入指南。进一步可研读 composition-workflow.md完整工作流、resources.md资源目录与 overview.md两条 MCP 面的边界以及 css-converter/overview.mdCSS 转换管线原理。【免费下载链接】elementorThe most advanced frontend drag drop page builder. Create high-end, pixel perfect websites at record speeds. Any theme, any page, any design.项目地址: https://gitcode.com/GitHub_Trending/el/elementor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考