Wp Blockmarkup MCP

wp块标记mcp

给你的人工智能助手一个经过验证的块标记数据库，而不是让它猜测Gutenberg HTML。

wp块标记mcp是一个本地 MCP服务器 它从WordPress核心、WooCommerce或您使用的任何基于块的插件中提取、验证和索引每个Gutenberg块。它为像Claude Code这样的人工智能工具提供了一个经过验证的块模式、属性和经过验证的标记示例数据库来查询，而不是依赖于训练数据来产生块结构、发明属性，并在编辑器中生成触发“尝试块恢复”的标记。

当前验证结果： 121个核心Gutenberg块被索引——100%的静态块标记示例通过了结构和保存功能验证。

为什么存在

人工智能助手越来越多地用于以编程方式生成WordPress内容——通过REST API构建页面，在平台之间迁移内容，填充无头前端。但每个AI模型都有相同的盲点： 块标记来自训练数据，而不是实际的块源代码.

这意味着：

• 模型发明了不存在的属性 — fontSize 作为一个数字，当它预期一个字符串slug时，就像 "large"
• 类命名模式错误 — has-background-color-vivid-red 而不是 has-vivid-red-background-color
• 块嵌套规则被忽略 --将块放在不支撑的容器内 InnerBlocks
• 动态块获取静态标记 --为只接受带属性的注释分隔符的块生成HTML
• 第三方区块不可见 --WooCommerce块、Kadence块、ACF块都是训练数据未知的
• 细微的不匹配会悄无声息地打破 --标记看起来正确，但编辑器将其标记为无效，需要手动恢复

只有当内容进入编辑器并且每个块都显示黄色警告栏时，您才会发现这些问题。在人工智能自主生成和推送内容的代理工作流程中，糟糕的标记意味着页面损坏。

解决方案

向AI提供真实块数据。 与其希望模型记住正确的标记格式，不如给它一个经过验证的数据库来查询和验证。

wp-blockmark-ucp解析任何基于块的插件的实际源代码，提取每个块的模式，以及 通过两层管道验证生成的标记 --首先使用官方的WordPress块解析器进行结构正确性分析，然后根据块的 save() AST功能。您的AI助手在生成内容之前查询此数据库，并可以在推送之前验证其输出。

这自然适合内容生成工作流。当Claude Code（或任何兼容MCP的助手）需要生成Gutenberg块标记时，它：

1. 搜索 相关块的索引数据库
2. 检索 完整的属性模式和经过验证的标记示例
3. 产生 使用经过验证的模式的内容
4. 确认 在推送块之前，根据块的实际保存函数生成的标记

没有“尝试阻止恢复”。没有损坏的页面。没有猜测。

什么会被索引：

AI为每个区块获得什么：

• 包含类型、默认值和约束的完整属性表
• 支持配置（块启用的功能）
• 不同特征组合的验证标记示例（基本、带颜色、带排版、带间距、功能齐全）
• 块类型分类（静态/动态/混合）
• 验证状态(verified / structural_only / attributes_only)
• 具有预配置属性和标记的变体

快速开始

安装

npm install -g wp-blockmarkup-mcp

或者直接使用npx运行（无需安装）：

npx wp-blockmarkup-mcp

索引你的第一个来源

每 source:add 命令克隆仓库并自动为其建立索引：

# WordPress Gutenberg core blocks (121 blocks)
wp-blocks source:add \
  --name gutenberg \
  --type github-public \
  --repo https://github.com/WordPress/gutenberg \
  --branch trunk

就是这样。提取、验证和索引了121个核心块——60个静态块完全验证，61个动态块具有验证的属性。

连接到克劳德代码

将MCP服务器添加到您的Claude Code配置中。创建或编辑 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "wp-blockmarkup": {
      "command": "npx",
      "args": ["wp-blockmarkup-mcp"]
    }
  }
}

这取决于任何版本 npx 已在本地缓存（请参见 更新 用于权衡和如何固定）。

现在，当你要求Claude Code使用Gutenberg块生成WordPress内容时，它会自动搜索块模式，并根据你的索引源验证标记。

更新

npx wp-blockmarkup-mcp 通过以下方式缓存包 (name + args) hash in ~/.npm/_npx/ 并在每次调用时重用该缓存——确实如此 不 自动获取新版本。有两种方法可以更新，最后一步你不能跳过：

选项A——最新浮动（简单，手动刷新）：

# Clear the npx cache for this package, then restart the MCP server.
npm cache clean --force        # or: rm -rf ~/.npm/_npx

如果改为全局安装(npm install -g):

npm update -g wp-blockmarkup-mcp

选项B——固定版本（可复制、有意升级）：

{
  "mcpServers": {
    "wp-blockmarkup": {
      "command": "npx",
      "args": ["-y", "wp-blockmarkup-mcp@1.1.1"]
    }
  }
}

当你想要新版本时，可以对固定版本进行缓冲。

无论哪种方式，重新启动MCP服务器 --正在运行的stdio进程将旧代码保存在内存中，直到重新启动。在克劳德代码中： /mcp → 重新连接 wp-blockmarkup，或完全重新启动Claude Code。

索引源

古腾堡核心块

npx wp-blocks source:add \
  --name gutenberg \
  --type github-public \
  --repo https://github.com/WordPress/gutenberg \
  --branch trunk

WooCommerce区块

npx wp-blocks source:add \
  --name woocommerce-blocks \
  --type github-public \
  --repo https://github.com/woocommerce/woocommerce \
  --subfolder plugins/woocommerce-blocks \
  --branch trunk

任何公共阻止插件

# Example: Kadence Blocks
npx wp-blocks source:add \
  --name kadence-blocks \
  --type github-public \
  --repo https://github.com/stellarwp/kadence-blocks

# Example: GenerateBlocks
npx wp-blocks source:add \
  --name generateblocks \
  --type github-public \
  --repo https://github.com/suspended-developer/generateblocks

您的私人插件

对于私有GitHub仓库，将您的令牌存储在环境变量中（永远不要在配置中）：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

npx wp-blocks source:add \
  --name my-custom-blocks \
  --type github-private \
  --repo https://github.com/yourorg/your-blocks \
  --token-env GITHUB_TOKEN

本地区块开发

直接指向计算机上的文件夹——非常适合您正在积极开发的块：

npx wp-blocks source:add \
  --name my-local-blocks \
  --type local-folder \
  --path /path/to/wp-content/plugins/my-blocks

源选项

CLI参考

npx wp-blocks source:add           Add a source and index it
npx wp-blocks source:list          List all sources with indexed status
npx wp-blocks source:remove  Remove a source and all its data
npx wp-blocks index                Re-index all sources (or --source )
npx wp-blocks search        Full-text search across blocks
npx wp-blocks schema   Show full schema for a block
npx wp-blocks validate     Validate block markup structurally
npx wp-blocks stats                Show block counts and validation coverage per source
npx wp-blocks rebuild-index        Rebuild full-text search indexes

CLI示例

# Search for image-related blocks
npx wp-blocks search "image gallery"

# Search only blocks from a specific source
npx wp-blocks search "product" --source woocommerce-blocks

# Filter by block type
npx wp-blocks search "posts" --type dynamic

# Get full schema for a specific block
npx wp-blocks schema core/paragraph

# Validate block markup (use a file or quoted string)
npx wp-blocks validate "$(cat my-block.html)"

# Re-index a specific source after updates
npx wp-blocks index --source gutenberg

# Force full re-index (ignore content hash cache)
npx wp-blocks index --force

# See what you have indexed
npx wp-blocks stats

MCP工具

当连接到Claude Code（或任何兼容MCP的客户端）时，有六个工具可用：

search_blocks

全文搜索，BM25在所有索引块中排名。按名称、标题、描述或类别搜索。支持源、类别和块类型（静态/动态）的过滤器。

get_block_schema

返回块的完整架构：包含类型和默认值、支持配置、变体、验证状态和块类型的完整属性表。这就是AI在生成标记之前理解块接受什么的方式。

get_block_markup

返回块的标记示例及其验证状态，可选择按使用的特征（颜色、排版、间距、对齐方式）进行筛选。筛选到 validated_only: true 仅获取通过结构和保存函数验证的示例。每 verified 该示例已通过管道的两层进行了验证。

validate_markup

接受原始块标记，并使用官方WordPress块解析器进行验证(@wordpress/block-serialization-default-parser)--与WordPress内部运行的解析器相同：

• 结构性的 --像WordPress一样解析注释分隔符，验证JSON属性
• 模式 --检查块的架构中是否存在属性名称，验证值类型和枚举约束
• 块分辨率 --确认块名称存在于索引源中，标识动态块与静态块

退货 VALID, INVALID 存在特定错误，或 VALID (attributes only) 对于动态块。

list_block_attributes

返回块的所有属性及其类型、默认值、允许值、源和选择器。当AI需要构建特定的属性组合时很有用。

search_variations

按名称或描述搜索块变体。返回具有预配置属性和验证标记的匹配变体。

运作原理

提取管道

1. 来源 通过CLI注册——每个都指向GitHub仓库或本地文件夹
2. 区块发现 扫描 block.json 在整个源代码中递归文件
3. 解析 每个块运行四个分析器：

- block-json-parser --元数据、属性、支持、上下文 - edit-parser --UI控件和属性映射的Babel AST分析 - save-parser --HTML输出模式、类名、样式的Babel AST分析 - variations-parser --预配置块变化

1. 分类 确定块类型：

- 静态 --有 save() 返回JSX（可以进行完全验证） - 动态的 — save() 返回null，由PHP呈现（仅用于属性验证） - 混合 --两者都有 save() JSX和 render.php

1. 标记生成 为每个块创建具有不同特征组合（基本、对齐、颜色、排版、间距、全功能）的示例
2. 验证 在每个生成的示例上运行两层管道并存储结果

验证流程

在索引过程中，每个生成的标记示例都会经过一个分层验证管道。验证状态按示例存储，并汇总到块级别。

第1层——结构验证（所有模块）

用途 @wordpress/block-serialization-default-parser --与WordPress内部运行的解析器完全相同：

• 使用WordPress自己的标记器正则表达式解析注释分隔符
• 提取块名、JSON属性和innerHTML
• 验证块的架构中是否存在属性名称（以及全局属性，如 className, anchor, style, backgroundColor, textColor, fontSize, align)
• 类型根据架构检查属性值(string, number, boolean, array, object)
• 验证架构定义允许值的枚举约束
• 递归验证嵌套的内部块

第2层——保存功能模式匹配（仅限静态/混合块）

使用区块的AST分析 save() 用于验证生成的HTML是否与预期模式匹配的函数：

• 包装元素 --确认HTML使用了正确的根元素(`

, , 等等）匹配什么 save()` 回报

• CSS类结构 --验证 wp-block-* 类、颜色类(has-{slug}-background-color, has-text-color, has-background)，字体大小类别(has-{slug}-font-size)，对齐类
• 样式属性 --检查注释中的间距/排版属性是否反映在HTML中 style 属性（填充、边距、行高）
• 内部块 --验证 InnerBlocks.Content 使用情况 save() 与嵌套块的存在一致

这种方法验证输出模式，而不需要完整的WordPress块编辑器运行时，使其快速且无需依赖。

动态块

动态块(save() 返回null）跳过第2层：

• 通过第1层验证注释分隔符+属性
• 存储自动关闭格式： ``
• 标记为 validation_status: 'attributes_only' -WordPress通过REST API接受此格式，并通过PHP呈现HTML服务器端

验证状态：

这 置信度分数 （0–100%）反映了源代码的提取质量。这 验证状态 反映了标记的正确性。标记了一个块 verified 在块级别，当其所有标记示例都通过这两个层时。

增量更新

• git pull 在缓存的存储库上（或重新读取本地文件夹）
• 每个块目录的内容哈希值--跳过未更改的块
• 仅重新提取和验证更改的块
• 软删除块，其 block.json 已删除

数据存储

所有数据都存在于 ~/.wp-blockmarkup-mcp/:

~/.wp-blockmarkup-mcp/
  blocks.db           # SQLite database (FTS5, WAL mode)
  cache/              # Cloned repositories

数据库模式

sources         — registered repos/folders with indexing metadata
blocks          — block metadata, type, validation status, confidence
attributes      — per-block attributes with types, defaults, constraints
supports        — per-block feature support configurations
markup_examples — validated markup examples with features used
variations      — block variations with attributes and markup
blocks_fts      — FTS5 full-text search index

动态块

动态块（最新帖子、搜索、类别等）有自己的 save() 函数返回 null --HTML输出由PHP基于当前数据和主题在服务器端呈现。

对于这些块，wp-blockmark-ucp：

• 从中提取完整的属性架构 block.json
• 验证属性类型和约束
• 存储 仅注释的自动关闭标记格式: ``
• 将它们标记为 validation_status: 'attributes_only'

此格式是有效的，并且被WordPress REST API接受。WordPress将在显示帖子时在服务器端呈现可视化HTML。AI可以使用此标记插入具有正确属性的动态块——视觉输出仅取决于服务器环境。

配套工具：wp-devdocs-mcp

它们共同涵盖了WordPress AI辅助的两个方面：

• wp-devdocs-mcp --用于编写插件/主题的已验证挂钩 代码
• wp块标记mcp --用于生成的验证块模式 内容

相同的源注册工作流。相同的MCP集成。同一AI助手的补充工具。

主题感知内容生成

wp块标记mcp知道 如何正确写入块 --模式、属性、标记格式、验证。它故意不知道的是 你的主题提供了哪些设计标志 --颜色、字体大小、间距比例、渐变。这些来自 theme.json 并且对于每个站点都是不同的。

这是设计出来的。将主题与块模式一起索引会将特定于站点的数据与通用块知识混合在一起，从而产生主题中不存在的颜色和字体的建议。

它在实践中是如何工作的

预期的工作流程将此MCP服务器与了解您活动主题的WordPress站点MCP配对。LLM位于首位，负责协调以下两个方面：

You: "Build a hero section with our brand colors, a heading, and a CTA to /pricing"

LLM thinks:
  1. Ask WordPress MCP → what colors does the active theme provide?
     → learns: "primary" (#1a1a2e), "accent" (#e94560), font sizes sm/md/lg/xl
  2. Ask wp-blockmarkup-mcp → search_blocks("cover"), get_block_schema("core/cover")
     → learns: dimRatio, contentAlign, overlayColor attributes and correct markup format
  3. Ask wp-blockmarkup-mcp → get_block_schema("core/buttons")
     → learns: button block structure and nesting rules
  4. Combine both → generates markup using "primary" slug (from theme)
     with correct attribute names (from block schema)
  5. Ask wp-blockmarkup-mcp → validate_markup(generated)
     → confirms it's structurally correct

MCP配置

这两台服务器都已在MCP客户端配置中注册。克劳德代码(.mcp.json):

{
  "mcpServers": {
    "wp-blockmarkup": {
      "command": "npx",
      "args": ["--prefix", "/path/to/wp-blockmarkup-mcp", "wp-blockmarkup-mcp"]
    },
    "wordpress": {
      "command": "wordpress-mcp",
      "args": ["--url", "https://yoursite.com"]
    }
  }
}

LLM可以看到来自两个服务器的所有工具，并可以推断何时使用每个工具。要使工作流明确，请添加 CLAUDE.md 对于您的项目：

## WordPress Content Generation

When generating Gutenberg block markup:
1. Use `wordpress.get_theme_settings` to get the active color palette,
   font sizes, and spacing scale from theme.json
2. Use `wp-blockmarkup.search_blocks` to find correct block names
3. Use `wp-blockmarkup.get_block_schema` to verify attribute names and types
4. Use theme-specific slugs (from step 1) for colors — not default palette values
5. Use `wp-blockmarkup.validate_markup` before outputting final markup

验证器接受什么

验证管道已经与slug无关。它检查JSON属性和HTML类 彼此同意 --并不是说色块来自特定的调色板。如果你的标记说 backgroundColor: "primary"，验证器会检查 has-primary-background-color 和 has-background 出现在HTML类中。它不在乎是否 "primary" 来自WordPress默认设置或您的自定义主题。

这意味着使用特定主题令牌生成的标记可以正确验证，而无需此工具进行任何主题感知。

需求

• Node.js 20+
• 每个大型插件源（Gutenberg、WooCommerce）约500MB磁盘空间

许可证

麻省理工学院