内容
# wp-blockmarkup-mcp-server
**用于发现、验证和索引古腾堡区块模式和标记的实验性本地/远程MCP服务器。**
> [!CAUTION]
> **早期通知：** 该仓库是一个实验性的分支/重构版本，基于原作者的作品。它对于本地开发和评估非常有用，但API、存储细节、验证覆盖范围和部署指南可能会发生变化。请在将其用于生产之前，在您自己的WordPress环境中验证生成的內容。
> [!IMPORTANT]
> **AI辅助重构：** 此分支中的更改——包括Docker部署、HTTP传输、Git/源策略模块、测试套件和重写的文档——是在人类审查的情况下由AI编码代理生成的。上游代码按照MIT许可证的要求进行归属；请参见[NOTICE](NOTICE)。
## 项目传承
原始项目由其作者在[pluginslab/wp-blockmarkup-mcp](https://github.com/pluginslab/wp-blockmarkup-mcp/)维护。本仓库是一个独立的分支/重构版本，由Zaher Ghaibeh创建；它不是上游项目的替代品或官方发布版本。
**分支基础：** 此分支是从上游提交[`e490fcd`](https://github.com/pluginslab/wp-blockmarkup-mcp/commit/e490fcded2b910f79eeb0ed087773a96e0d6dd30)（完整SHA `e490fcded2b910f79eeb0ed087773a96e0d6dd30`，上游v1.1.1，2026-05-13）创建的。代码、文档或此仓库中的配置，如果不是Zaher Ghaibeh的，则源自该提交或更早的版本。上游项目仍然是原始实现的参考。
### 这个分支有什么不同？
| 领域 | 原始项目 | 这个分支/重构版本 |
|------|------------------|--------------------|
| 分发 | 面向npm的示例 | 克隆仓库并在本地运行；不打算发布npm包 |
| 运行时 | 主要本地MCP使用 | 本地stdio加身份验证的只读流式HTTP模式 |
| 部署 | 本地进程 | Docker镜像和Docker Compose部署，带有持久化SQLite存储 |
| 源凭证 | 调用者选择的令牌配置 | 服务器拥有的`WP_BLOCKMARKUP_GITHUB_TOKEN`，用于私有GitHub源 |
| 源安全性 | 基本仓库配置 | 规范的`github.com` URL检查、安全引用验证、路径包含检查和有界Git执行 |
| HTTP安全性 | 本地集成关注 | 承载身份验证、源检查、主体限制、速率限制和批量请求拒绝 |
| 索引和验证 | 核心提取和标记验证 | 结构化索引结果（`success`、`degraded`、`failure`）、功能感知标记生成和更严格的古腾堡分隔符/保存函数验证 |
| 维护 | 上游发布流程 | 密封测试和此分支的linting；更改仍然是实验性的，可能与上游有所不同 |
两个仓库可能会独立演化。在假设某个功能、命令或数据库迁移存在于另一个仓库之前，请同时检查两个仓库。
## 为什么存在这个项目
AI助手通常从不完整或过时的训练数据中生成古腾堡内容。它们可能会发明属性、使用错误的CSS类约定、忽略嵌套规则或为动态区块发出静态HTML。然后，WordPress会报告无效区块并要求恢复。
这个分支和重构版本还使该项目能够作为共享的团队服务在线托管。团队可以部署一个经过身份验证的、连续索引的实例，而不是每个开发人员运行一个单独的本地副本，并从他们的MCP兼容客户端使用它。本地优先执行仍然适用于开发和测试，但共享在线托管是预期的一种操作方式。
该服务器索引WordPress核心、WooCommerce或其他基于区块的插件的实际源代码，以便MCP兼容的助手可以：
1. 搜索相关区块。
2. 读取它们的属性、支持、变化和保存模式。
3. 从验证的示例中生成标记。
4. 在将其发送到WordPress之前验证标记。
索引数据包括区块元数据、属性模式、支持配置、变化、UI映射、保存函数模式、区块类型分类和验证状态。
## 快速入门：从克隆运行
该项目故意优先考虑本地运行。克隆它，安装依赖项并运行已检出的源代码：
```bash
git clone https://github.com/zaherg/wp-blockmarkup-mcp-server.git
cd wp-blockmarkup-mcp-server
npm ci
```
需要Node.js 22、24或26。该仓库不打算作为npm包安装或发布。
### 索引源
从检出目录运行CLI。CLI的内部程序名称（在`--help`输出中使用）是`wp-blocks`：
```bash
node src/cli.js source:add \
--name gutenberg \
--type github-public \
--repo https://github.com/WordPress/gutenberg \
--branch trunk
```
其他源类型：
```bash
# 公共GitHub仓库
node src/cli.js source:add \
--name woocommerce-blocks \
--type github-public \
--repo https://github.com/woocommerce/woocommerce \
--subfolder plugins/woocommerce-blocks \
--branch trunk
# 私有GitHub仓库。令牌由服务器进程拥有。
export WP_BLOCKMARKUP_GITHUB_TOKEN=your-fine-grained-read-token
node src/cli.js source:add \
--name my-private-blocks \
--type github-private \
--repo https://github.com/your-org/your-blocks \
--branch main
# 正在开发的本地插件
node src/cli.js source:add \
--name my-local-blocks \
--type local-folder \
--path /absolute/path/to/wp-content/plugins/my-blocks
```
有用的命令：
```bash
node src/cli.js source:list
node src/cli.js index --source gutenberg
node src/cli.js search "image gallery"
node src/cli.js schema core/paragraph
node src/cli.js validate '<!-- wp:paragraph --><p>Hello</p><!-- /wp:paragraph -->'
node src/cli.js stats
node src/cli.js rebuild-index
```
### 连接本地MCP客户端
对于使用命令启动MCP服务器的客户端，请将其指向已检出的文件。例如，Claude Code样式配置为：
```json
{
"mcpServers": {
"wp-blockmarkup": {
"command": "node",
"args": ["/absolute/path/to/wp-blockmarkup-mcp-server/src/mcp-server.js"]
}
}
}
```
默认stdio服务器公开了读写工具和本地源管理工具。在使用管理操作时，请将进程保留在受信任的机器上。有关CLI与远程的比较，请参见下面的**CLI与远程：谁能做什么**。
## Docker安装和部署
仓库中包含Dockerfile和Compose文件。发布的镜像可供方便使用，而源代码仍然是运行和修改此实验性分支的规范方式：
```bash
git clone https://github.com/zaherg/wp-blockmarkup-mcp-server.git
cd wp-blockmarkup-mcp-server
# HTTP模式所需。使用至少32个UTF-8字节的随机值。
printf 'MCP_AUTH_TOKEN=%s\n' "$(openssl rand -hex 32)" > .env
docker compose pull
docker compose up -d
docker compose logs -f wp-blockmarkup-mcp-server
```
默认Compose绑定为`127.0.0.1:3000`；MCP端点为`http://127.0.0.1:3000/mcp`。SQLite数据库存储在名为`wp-data`的命名卷中，并在容器重新创建时存活。
在正在运行的容器中索引GitHub源：
```bash
docker compose exec wp-blockmarkup-mcp-server node src/cli.js source:add \
--name woocommerce-blocks \
--type github-public \
--repo https://github.com/woocommerce/woocommerce \
--subfolder plugins/woocommerce-blocks \
--branch trunk \
--no-index
docker compose exec wp-blockmarkup-mcp-server node src/cli.js index --source woocommerce-blocks
docker compose exec wp-blockmarkup-mcp-server node src/cli.js stats
```
对于私有仓库，请将`WP_BLOCKMARKUP_GITHUB_TOKEN`添加到`.env`并使用细粒度、只读令牌，限制在所需的仓库中。永远不要将凭证放入仓库URL中。
### 在本地构建镜像
要构建而不是拉取，请取消注释`docker-compose.yml`中的`build: .`并注释掉其`image:`行，然后运行：
```bash
docker compose build
docker compose up -d
```
Dockerfile使用Node 24 slim，并支持常见的`linux/amd64`和`linux/arm64`平台。请参阅[DEPLOYMENT.md](DEPLOYMENT.md)，了解有关入口、TLS、卷、环境变量和多架构的指导。
### 连接HTTP MCP客户端
将客户端配置为流式HTTP MCP服务器，并发送相同的承载令牌（`.env`中的`MCP_AUTH_TOKEN`值）：
```json
{
"mcpServers": {
"wp-blockmarkup": {
"url": "http://127.0.0.1:3000/mcp",
"headers": {
"Authorization": "Bearer replace-with-the-value-from-.env"
}
}
}
}
```
托管的HTTP默认情况下故意公开只读MCP工具。设置`MCP_ENABLE_HTTP_ADMIN=true`和有效的`MCP_AUTH_TOKEN`，以公开四个管理工具。默认情况下，管理工具处于关闭状态，如果没有令牌，启用它将导致启动失败，即使在环回地址上也是如此。如果服务绑定到环回地址以外，请将其放在HTTPS和受信任的入口后面，保持后端跳转私有，并配置一个强令牌和允许的源列表。
## MCP工具
服务器公开的每个工具都列在下面。动态区块使用有效的自闭合注释标记表示，并报告`attributes_only`，因为它们的最终HTML由WordPress站点上的PHP渲染。
| MCP工具 | 本地CLI等效工具 | 本地stdio MCP | 远程HTTP MCP |
|----------|----------------------|-----------------|------------------|
| `search_blocks` | `search`（等效搜索路径） | 是 | 是 |
| `get_block_schema` | `schema`（包括模式、属性、变化和示例） | 是 | 是 |
| `get_block_markup` | 部分通过`schema`示例；无专用CLI命令 | 是 | 是 |
| `validate_markup` | 部分通过`validate`（仅结构验证） | 是 | 是 |
| `list_block_attributes` | 部分通过`schema`；无专用CLI命令 | 是 | 是 |
| `search_variations` | 无直接CLI等效工具 | 是 | 是 |
| `source_list` | `source:list` | 是 | 是，仅启用`MCP_ENABLE_HTTP_ADMIN=true` |
| `source_add` | `source:add`，所有源类型 | 是，所有源类型 | 是，仅启用`MCP_ENABLE_HTTP_ADMIN=true`；仅GitHub类型 |
| `source_remove` | `source:remove` | 是 | 是，仅启用`MCP_ENABLE_HTTP_ADMIN=true` |
| `source_index` | `index` | 是 | 是，仅启用`MCP_ENABLE_HTTP_ADMIN=true`；受共享主体预算和MCP进程锁保护 |
`get_block_markup`返回可读的Markdown `content`响应和机器可读的`structuredContent`对象。结构化结果包含`block_name`、`count`和有序的`examples`数组。每个示例公开`title`、`description`（可为空）、`markup`、`validation_status`和`features_used`（字符串数组）。_stdio和Streamable HTTP共享相同的工具合约。
远程管理入口由`MCP_ENABLE_HTTP_ADMIN`在服务器启动时控制。每个客户端的授权在此版本中不受支持；请参阅[DEPLOYMENT.md](DEPLOYMENT.md)，了解两部署模式。
### CLI与远程：谁能做什么
> **本地CLI（`node src/cli.js`）** 在SQLite索引和GitHub令牌所在的同一台机器上运行，直接与数据库通信，是唯一可以运行立即`rebuild-index`或在没有运行的MCP服务器的情况下操作的用户。它还可以管理`local-folder`源，就像受信任的stdio MCP一样。使用CLI进行设置、恢复和一次性维护，您可能否则会使用`sqlite3`直接对数据库进行操作。
>
> **本地stdio MCP** 由MCP客户端在受信任的机器上启动。它公开了所有十个工具，包括四个管理工具，并且没有启用标志；假设启动进程的任何人已经具有与运行它的用户帐户相同的权限。使用它时，单个开发人员想要一个助手读取区块 **和管理源**，而无需离开他们的工作站。
>
> **远程HTTP MCP** 是多客户端路径。默认情况下，它与以前一样是只读的。当设置`MCP_ENABLE_HTTP_ADMIN=true`时，启动需要`MCP_AUTH_TOKEN`，即使在环回地址上也是如此，服务器公开四个管理工具给任何持有该令牌的人。因为启用是服务器范围的，所以每个经过身份验证的客户端都是同一个主体。将承载令牌视为数据库根密码：使用HTTPS终止、私有入口跳跃、入口侧洪水控制、强允许的源列表和首选的两个部署（管理员开启用于操作员，管理员关闭用于下游助手）。
>
> 远程路径不会执行两项操作，即使启用了管理工具：
> 1. 添加`local-folder`源。`local-folder`需要服务器文件系统上的路径，不适合暴露给网络调用者，因此在HTTP边界拒绝。
> 2. 在一个服务器进程中同时运行两个`source_index`/`source_remove`MCP操作。进程间锁涵盖HTTP和stdio MCP调用；第二个调用获得干净的`isError: true`结果和活动操作和获取时间。它不协调单独的CLI进程或服务器副本，因此操作员不得在同一个数据目录上并发运行这些操作。
## 索引和验证的工作原理
索引器发现`block.json`文件，解析元数据和JavaScript AST，将区块分类为静态、动态或混合，生成特定于功能的示例，并将结果存储在带有FTS5搜索的SQLite中。
生成的示例按层级进行检查：
1. **结构验证** 使用官方WordPress区块序列化解析器，检查分隔符语法、JSON属性、已知属性、类型、枚举和嵌套区块。
2. **保存函数验证** 检查静态/混合输出与提取的包装器、类、样式和`InnerBlocks`模式。
验证状态包括`verified`、`structural_only`、`attributes_only`和`invalid`。索引报告`success`、`degraded`或`failure`，以便部分源失败不会作为完整成功呈现。
## 存储和安全说明
默认情况下，本地数据存储在`~/.wp-blockmarkup-mcp-server/`下：
```text
~/.wp-blockmarkup-mcp-server/
blocks.db # SQLite数据库和FTS索引
cache/ # 缓存的Git仓库
```
重要的运行时控件包括：
- `MCP_TRANSPORT`（默认为`stdio`，托管模式为`http`）
- `MCP_HOST`和`MCP_PORT`
- `MCP_AUTH_TOKEN`（非环回HTTP和至少32个UTF-8字节所需；环回地址上启用`MCP_ENABLE_HTTP_ADMIN=true`时也需要）
- `MCP_ENABLE_HTTP_ADMIN`（HTTP上的管理工具，默认为关闭）
- `MCP_ALLOWED_ORIGINS`
- `MCP_BODY_LIMIT_BYTES`
- `MCP_RATE_LIMIT_REQUESTS`和`MCP_RATE_LIMIT_WINDOW_MS`
- `MCP_ADMIN_RATE_LIMIT_REQUESTS`和`MCP_ADMIN_RATE_LIMIT_WINDOW_MS`（启用管理时的共享主体预算）
- 私有GitHub源的`WP_BLOCKMARKUP_GITHUB_TOKEN`
Git操作运行有界定时和隔离的凭证/配置处理。仓库URL限制为凭证免费的HTTPS `github.com` URL，引用规范化，索引的子文件夹必须保持在检查出的源代码内。
## 开发
使用[Worktrunk](https://worktrunk.dev/)（`wt`）管理隔离的开发工作树。为每个功能或修复程序创建专用工作树，而不是直接在`main`上工作。仓库钩子定义在[.config/wt.toml](.config/wt.toml)中；运行`wt --help`获取您安装中可用的命令。
```bash
npm ci
npm test
npm run lint:check
```
`npm run lint:check`在`src`和`tests`（请参见`biome.json`获取规则集）上运行[Biome](https://biomejs.dev/)。启用格式器和linting工具。`npm run lint:fix`应用安全自动修复；`npm run format:fix`重新格式化源代码。
该项目当前针对Node.js 22、24和26在CI中运行。此分支仍处于实验阶段；通过的测试不能保证与每个WordPress版本、插件、主题、MCP客户端或生产入口的兼容性。
## 与主题感知内容生成的关系
该服务器描述区块模式和有效的标记模式。它不知道活动站点的颜色调色板、 typography 比例、间距令牌或其他`theme.json`值。将它与可以读取活动主题的WordPress/站点MCP配对，然后在发布之前在此处验证最终标记。
## 许可证
MIT。有关完整文本，请参见[LICENSE](LICENSE)。
该项目是[pluginslab/wp-blockmarkup-mcp](https://github.com/pluginslab/wp-blockmarkup-mcp/)的分支/重构版本，最初由**Marcel Schmitz**编写并在MIT许可证下发布。原始版权通知在LICENSE文件中保留，如该许可证要求。有关分支归属声明，请参见[NOTICE](NOTICE)。
分支使用npm名称`@zaherg/wp-blockmarkup-mcp-server`以与上游`wp-blockmarkup-mcp`区分开来。此分支不打算从npm安装或发布到npm - 从克隆中运行它。
