woodmart-mcp

通过 MCP abilities 使用 WoodMart

使用实时 ability 文档

所有操作都通过 wood MCP adapter 执行。使用 mcp-adapter-discover-abilities 获取当前 ability 列表；首次使用写入 ability 前，或不确定其参数时，使用 mcp-adapter-get-ability-info。以实时说明、输入架构、响应字段、警告和 user_instruction 为准；不要依赖记忆中的参数列表。

使用 mcp-adapter-execute-ability 并提供 ability_name 和 parameters 来执行 ability。

路由

意图	从这里开始
查找页面、文章、产品、作品集项目或 HTML 区块	woodmart/search-content
创建页面、文章、作品集项目或 HTML 区块	woodmart/create-content
重命名、发布、更改 slug 或更改内容的父级	woodmart/update-content
读取目标的区块树	woodmart/gutenberg-get-content
更改非空目标中的区块	woodmart/gutenberg-edit-blocks
填充空目标或有意重建整个目标	woodmart/gutenberg-add-pending-change
发现区块及其属性	woodmart/gutenberg-list-blocks，然后使用 woodmart/gutenberg-describe-block
重用演示区块或页面	woodmart/gutenberg-search-templates，然后使用 woodmart/gutenberg-get-template
读取或更改主题设置	woodmart/list-theme-settings，然后使用 woodmart/get-theme-setting
替换 Header Builder 徽标	woodmart/replace-header-logo
发现、创建或分配布局	woodmart/list-layout-types，然后使用相关布局 ability

search-content 返回的 id，或 list-layouts 返回的布局 target_id，可作为 Gutenberg abilities 的 target_id。

区块写入规则

这些规则必须严格遵守，因为违反规则可能会在不发出提示的情况下丢失内容或样式。

1. 切勿为了更改目标中的一部分而重建整个目标。 使用 gutenberg-get-content 读取目标，然后使用 gutenberg-edit-blocks，并且只发送需要更改的操作和属性键。这也适用于“更新页面上的所有文本”之类的请求。必须省略未触及的区块和属性。
2. 仅当目标为空，或用户明确要求替换／重建整个目标时，才使用 gutenberg-add-pending-change。
3. 在 gutenberg-describe-block 的 contentAttribute 指定的属性中编写文本和内容。更新内容时不要手动编写 innerHTML。现有的 innerHTML 是用于往返保留内容的数据，或是有意插入的原样标记。
4. 只有 wd/* 区块具有稳定的 blockId 值，且可通过 id 定位。核心区块会原样传递，但不能单独更新、删除、移动或用作锚点。
5. 创建或插入 wd/* 区块时，省略 attributes.blockId；规范化过程会生成该值。仅将从 gutenberg-get-content 复制的 id 用作操作选择器或锚点；切勿编造、复制、重用 id，也不要将其放入更新的 attributes 中。
6. 编辑时传入最新 gutenberg-get-content 响应中的 expected_content_hash。发生冲突时，重新读取目标，并根据新区块树重建预期操作。

如果有意进行的完整替换可能会影响已注册区块之外的经典／自由格式内容，请先使用 include_raw_content: true 读取；否则，block_spec 无法表示这类内容。不要将完整替换用作此限制的变通方法。

选择写入路径

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

编辑文本时，如果尚不清楚内容属性，先描述区块，然后只更新该属性：

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

从头开始编写

1. 使用 gutenberg-list-blocks，然后对要编写的每个区块使用 gutenberg-describe-block。
2. 仅在需要相应样式时，才使用 gutenberg-describe-attribute-group 获取引用的 styleGroups 或 composites。
3. 遵循返回的 composition、nesting、conventions、示例、单位、响应式属性和数据解析器提示。不要臆造区块属性或特定于站点的 ID。
4. 对于布局，将 list-layout-types 返回的相关类型的 block_categories 传递给 gutenberg-list-blocks。
5. 如果库模板与所需区块或页面匹配，优先使用该模板。使用其返回的 block_spec；演示图片会在最终定稿时本地化。

最终定稿

每次区块内容写入都会进入队列，只有其批次达到 finalized 状态后才会生效。元数据、主题设置、页眉 Logo、预定义布局和布局条件的写入不使用区块队列。

1. 遵循队列响应中的 user_instruction。请用户在 wp-admin 中保持 WoodMart → Tools → AI Block Queue 页面打开。
2. 如果响应表明批次仍处于草稿状态，请调用 gutenberg-enable-finalization。使用 block_spec 调用 create-content 或 create-layout 时，批次已标记为就绪，因此不要再次启用。
3. 轮询 gutenberg-get-pending-batch，直到状态变为 finalized、failed 或 conflicted。
4. 如果状态为 conflicted，请重新读取目标，并基于当前内容重复编辑。

每个目标只能存在一个待处理的活动变更。排入替代变更前，请使用 gutenberg-delete-pending-batch 取消已过时且尚未定稿的批次。

即时写入与报告

内容元数据

update-content 会立即更改元数据，且不会更改区块。

• 发布会对外显示。只有在用户提出请求或明确确认时，才设置 status: "publish"。
• 更改已发布内容的 slug 或父项会改变其公开 URL。除非用户明确要求更改该 URL，否则请先征求确认。
• 阅读并转达响应中的 warnings、实际的 after.slug 和生成的 URL。已发布的层级页面不会获得 WordPress 旧 slug 重定向；其旧 URL 可能会返回 404。
• 不支持移至回收站或删除内容。不要通过清空区块内容来模拟删除。

主题设置与 Logo

• 使用 list-theme-settings 查找主题设置 ID；不要猜测。
• 写入前立即使用 get-theme-setting 读取完整描述信息。遵循 writable、value_format、options、current_value 和 has_preset_overrides。
• update-theme-setting 写入基础层。预设覆盖项仍可能决定可见值；请报告这一情况，不要盲目重试。
• replace-header-logo 需要媒体库中已有图片的 attachment_id，并会更新所有已保存的页眉。请读取各页眉的状态和 totals；如果有页眉被跳过或更新失败，应如实报告，不要声称全部成功。

布局

• 从 list-layout-types 开始。使用其中实时返回的 type、block_categories、predefined 和 condition_types 数据，不要维护本地枚举。
• 使用 Gutenberg 功能，通过现有布局的 target_id 编辑其区块；不要仅为了更改内容而重新创建布局。
• set-layout-conditions 会替换整组条件。请传入所有需要保留的条件；[] 会取消布局分配。
• 根据所选布局类型的 condition_types 条目及其 query_kind（none、scalar、array 或 number_range）构建每个条件。
• 在 MCP 中，is_assigned 取决于请求上下文。请检查已存储的 conditions；不要仅因 is_assigned 为 false 就重写这些条件。

作品集和站点专属 ID

作品集项目是 portfolio 文章类型的内容；查找或创建该项目，并像编辑页面一样编辑其中的 Gutenberg 区块。single_portfolio 和 portfolio_archive 是控制项目或归档页面呈现方式的布局。作品集内容要求启用 Portfolio 主题选项。

切勿编造产品、分类、分类法、媒体、文章或模板 ID。使用相关的实时查询／搜索功能解析这些 ID；如果不需要明确的 ID，也可以使用动态区块查询。