Build-page (composite)

emcp-tools/build-page

Creates a new WordPress page or post with an Elementor element tree. Supply a title and a structure array. You do not need to call create-page first, and this tool does not accept an existing post_id as its target.

For a guided example, see Build your first Elementor page. For changes to an existing page, use the layout and element tools.

Input

{
  title: string,
  status?: 'draft' | 'publish', // default: draft; set it explicitly
  post_type?: 'page' | 'post',  // default: page
  page_settings?: Record<string, unknown>,
  dry_run?: boolean,
  structure: (Container | Widget)[]
}

type Container = {
  type: 'container',
  settings?: Record<string, unknown>,
  children?: (Container | Widget)[]
}

type Widget = {
  type: 'widget',
  widget_type: string,
  settings?: Record<string, unknown>
}

Read the schema exposed by your installed version. Discover available widgets and inspect their settings before building. page_settings applies to the new document; it is not an instruction to update the site’s global kit.

Validate before creating

Set dry_run: true to normalize the proposed structure and return an element count and warnings without creating a page:

{
  "title": "My first Elementor draft",
  "status": "draft",
  "dry_run": true,
  "structure": [
    {
      "type": "container",
      "settings": { "flex_direction": "column" },
      "children": [
        {
          "type": "widget",
          "widget_type": "heading",
          "settings": {
            "title": "A clearer start for your next idea.",
            "header_size": "h1"
          }
        }
      ]
    }
  ]
}

A dry-run response contains dry_run, would_create and warnings. Review every warning. Shorthand types can be coerced, and a widget without a widget type can be skipped. Prefer the explicit node shapes above.

A dry run is not a rendered preview or proof that every widget is available. After validation, send the same input with dry_run: false to create the draft once.

Result and readback

A successful creation response contains:

{
  post_id: number,
  title: string,
  edit_url: string,
  preview_url: string,
  elements_created: number,
  warnings?: string[]
}

Read the returned page ID back with get-page-structure and get-page-snapshot. Confirm the saved status, sections, widgets and responsive settings. Open the draft through WordPress while signed in to review the rendered layout.

Do not assume the operation is atomic or retry blindly. Post creation and element saving are separate steps. A failed or timed-out request can leave a page behind. Inspect the page list and any returned ID before retrying; another build-page call creates another page.

Layout behavior and limits

• A row container can give its child containers equal percentage widths when explicit width or flex sizing is absent. Direct widgets in a row can be wrapped in containers. Inspect the resulting tree rather than assuming the input and saved element counts match exactly.
• Use explicit tablet/mobile direction, width and spacing settings for a stacked layout. Desktop columns do not by themselves prove a usable mobile layout.
• Native Flexbox Container support must be enabled in Elementor for this tool’s container output to render.
• Large structures can exceed a remote connector’s timeout. The implementation warns above 150 elements; this is not a universal transport limit. For a large build, create one draft and add sections incrementally with the layout/widget tools. Do not split it into repeated build-page calls expecting one document.

Use page-local settings or existing global references for styling. Updating the shared global kit is a separate operation with site-wide effects.