woodmart-mcp

Working with WoodMart via MCP abilities

Use live ability documentation

Everything runs through the wood MCP adapter. Use mcp-adapter-discover-abilities for the current ability list and mcp-adapter-get-ability-info before the first use of a write ability, or whenever its parameters are uncertain. Treat the live description, input schema, response fields, warnings, and user_instruction as authoritative; do not rely on remembered parameter lists.

Use mcp-adapter-execute-ability with ability_name and parameters to execute an ability.

Routing

Intent	Start with
Find a page, post, product, portfolio project, or HTML block	woodmart/search-content
Create a page, post, portfolio project, or HTML block	woodmart/create-content
Rename, publish, re-slug, or re-parent content	woodmart/update-content
Read a target's block tree	woodmart/gutenberg-get-content
Change blocks in a non-empty target	woodmart/gutenberg-edit-blocks
Fill an empty target or deliberately rebuild all of it	woodmart/gutenberg-add-pending-change
Discover blocks and their attributes	woodmart/gutenberg-list-blocks, then woodmart/gutenberg-describe-block
Reuse a demo section or page	woodmart/gutenberg-search-templates, then woodmart/gutenberg-get-template
Read or change a theme setting	woodmart/list-theme-settings, then woodmart/get-theme-setting
Replace Header Builder logos	woodmart/replace-header-logo
Discover, create, or assign layouts	woodmart/list-layout-types, then the relevant layout ability

An id from search-content, or a layout's target_id from list-layouts, is the target_id for Gutenberg abilities.

Block-write rules

These rules are non-negotiable because violating them can silently lose content or styling.

1. Never rebuild a target to change only part of it. Read it with gutenberg-get-content, then use gutenberg-edit-blocks and send only the operations and attribute keys that change. This includes requests such as “update all texts on the page.” Untouched blocks and attributes must be omitted.
2. Use gutenberg-add-pending-change only for an empty target or when the user explicitly asks to replace/rebuild the entire target.
3. Author text and content in the attribute named by gutenberg-describe-block's contentAttribute. Do not hand-write innerHTML for content updates. Existing innerHTML is round-trip data for content the agent is preserving, or verbatim markup supplied for an intentional insert.
4. Only wd/* blocks have stable blockId values and can be addressed by id. Core blocks pass through but cannot be individually updated, deleted, moved, or used as anchors.
5. Omit attributes.blockId when authoring or inserting a wd/* block; normalization creates it. Use ids copied from gutenberg-get-content only as operation selectors or anchors—never invent, copy, reuse, or send one inside update attributes.
6. Pass expected_content_hash from the latest gutenberg-get-content response when editing. On a conflict, re-read the target and rebuild the intended operations against the new tree.

If a deliberate full replacement might touch classic/freeform content outside registered blocks, first read with include_raw_content: true; block_spec otherwise cannot represent that content. Do not use full replacement as a workaround for this limitation.

Choosing the write path

Existing blocks?
├── no  → create-content with block_spec, or gutenberg-add-pending-change
└── yes → Explicit full rebuild requested?
          ├── no  → gutenberg-edit-blocks
          └── yes → gutenberg-add-pending-change

For a text edit, describe the block if the content attribute is not already known, then update only that attribute:

{
  "target_id": 123,
  "expected_content_hash": "...",
  "operations": [
    { "op": "update", "blockId": "a1b2", "attributes": { "content": "New heading" } }
  ]
}

Authoring from scratch

1. Use gutenberg-list-blocks, then gutenberg-describe-block for every block being authored.
2. Fetch referenced styleGroups or composites with gutenberg-describe-attribute-group only when that styling is needed.
3. Follow the returned composition, nesting, conventions, examples, units, responsive attributes, and data-resolver hints. Do not invent block attributes or site-specific ids.
4. For layouts, pass the relevant type's block_categories from list-layout-types to gutenberg-list-blocks.
5. Prefer a library template when it matches the requested section or page. Use its returned block_spec; demo images are localized during finalization.

Finalization

Every block-content write is queued and is not live until its batch reaches finalized. Metadata, theme-setting, header-logo, predefined-layout, and layout-condition writes do not use the block queue.

1. Follow the queue response's user_instruction. Ask the user to keep WoodMart → Tools → AI Block Queue open in wp-admin.
2. Call gutenberg-enable-finalization when the response says the batch is still a draft. create-content or create-layout with block_spec already marks its batch ready, so do not enable it again.
3. Poll gutenberg-get-pending-batch until finalized, failed, or conflicted.
4. On conflicted, re-read the target and repeat the edit against the current content.

Only one active pending change may exist per target. Cancel an obsolete non-finalized batch with gutenberg-delete-pending-batch before queuing a replacement.

Immediate writes and reporting

Content metadata

update-content changes metadata immediately and never changes blocks.

• Publishing is outward-facing. Set status: "publish" only when the user requested it or explicitly confirmed it.
• Changing the slug or parent of published content moves its public URL. Obtain confirmation unless the user explicitly requested that URL change.
• Read and relay the response's warnings, actual after.slug, and resulting URL. Published hierarchical pages do not receive WordPress's old-slug redirect; their old URL can become a 404.
• There is no trash/delete-content ability. Do not simulate deletion by blanking block content.

Theme settings and logos

• Find a theme-setting id with list-theme-settings; do not guess it.
• Read the full descriptor with get-theme-setting immediately before writing. Honor writable, value_format, options, current_value, and has_preset_overrides.
• update-theme-setting writes the base layer. A preset override may still determine the visible value; report that instead of retrying blindly.
• replace-header-logo requires an existing media-library image attachment_id and updates every saved header. Read the per-header statuses and totals; report skipped or failed headers rather than claiming blanket success.

Layouts

• Start with list-layout-types. Use its live type, block_categories, predefined, and condition_types data rather than maintaining local enums.
• Edit an existing layout's blocks with Gutenberg abilities against its target_id; do not recreate the layout merely to change its content.
• set-layout-conditions replaces the complete condition set. Send every condition that must remain; [] unassigns the layout.
• Build each condition using the selected layout type's condition_types entry and its query_kind (none, scalar, array, or number_range).
• is_assigned is request-context-dependent over MCP. Inspect stored conditions; do not rewrite them solely because is_assigned is false.

Portfolio and site-specific ids

A portfolio project is content of post type portfolio; find/create it and edit its Gutenberg blocks like a page. single_portfolio and portfolio_archive are layouts controlling how projects or archives render. Portfolio content requires the Portfolio theme option to be enabled.

Never invent product, category, taxonomy, media, post, or template ids. Resolve them with the relevant live query/search ability, or use a dynamic block query when explicit ids are unnecessary.