WPGuard MCP

WPGuard

让 AI 助手为 WordPress 工作。预览编辑内容。保留重要的修正。

WPGuard 将 MCP 客户端连接到 WordPress，使其能够检查网站、更新内容和设置，并返回更改记录。教会它一项受支持的修正后，今后对该确切目标进行的编辑都会在应用前接受检查。

它是 WP MCP Server 背后的开源服务。可在自己的机器或服务器上运行，并通过 SSH 或配套插件连接 WordPress 网站。

开始使用 · 产品网站 · 安全 · MIT 许可证

实用工作，且有内容可供审阅

让助手：

• 在更改页面前，检查当前主题、插件、内容类型和可用字段。
• 查找目标页面和经批准的参考内容，比较它们完整的已存储内容，并预览范围明确的整页差异。
• 替换 Gutenberg 或经典页面正文，同时证明指定文案得以保留，并拒绝覆盖之后的人工作出的编辑。
• 以结构化方式更新一个 Gutenberg 区块，然后验证写入操作创建的原生 WordPress 修订版本。
• 在已注册的暂存网站上测试页面更改，并在提交生产环境审批前获取桌面端和移动端证据。
• 通过版本锁定、健康检查和失败后自动还原来更新一个插件或主题。
• 在应用内容替换、设置更新或文件编辑之前预览更改。
• 在之后对同一目标进行编辑时，保留经批准的文本片段、字段值或链接。
• 检索某个确切客户端的先前工作，并显示其来源证据。
• 审阅更改包，以及受支持的变更工具捕获的快照。

这些工具提供 WordPress 访问能力和更改记录。MCP 客户端提供助手及其推理能力。

教它一次。检查下一次编辑。

假设某餐厅的预订页面必须保留指向 /reserve、标签为 预订餐位 的链接。

你可以用一个不合格示例、一个合格示例及其来源来记录此要求。WPGuard 会先验证检查能否区分这两个示例。之后，如果某次内容编辑移除了该链接，就会在预览检查中失败，并在助手尝试应用更改时被阻止。

这个合成示例在注册网站后使用 wp_correction_record MCP 工具：

wp_correction_record(
    site="restaurant-staging",
    target="post:84:content",
    human_correction="Keep the reservations link on this page.",
    source_ref="review:reservation-link-example",
    human_requested_basis="The site owner requested this link in the example review.",
    kind="html_link",
    expected={"href": "/reserve", "text": "Reserve a table"},
    rejected_value="<p>Contact us to book.</p>",
    accepted_value='<p><a href="/reserve">Reserve a table</a></p>',
)

此要求仅适用于这个已注册网站和这个文章正文。它不会成为适用于所有页面或其他客户端的规则。停用修正会保留其历史记录和停用原因。

支持的检查包括：精确文本的存在或缺失、标量值相等、JSON Pointer 指定位置的值，以及 HTML 锚点的目标地址和文本。链接检查会检查 HTML 结构；它无法证明目标地址有效，也无法证明链接在浏览器中可见。

从源码开始

需要 Python 3.10 或更高版本。这些命令用于安装本仓库；它们不依赖已发布的软件包或容器镜像。

git clone https://github.com/cgallic/wpguard-mcp.git
cd wpguard-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install ".[browser]"
playwright install chromium
export WPGUARD_TOKEN_ADMIN="$(python -c 'import secrets; print(secrets.token_hex(32))')"
wpguard-mcp

服务会在 http://127.0.0.1:8642/mcp 上监听。连接支持 MCP Streamable HTTP 且带有 Authorization: Bearer <token> 请求头的客户端，并使用服务环境中的 WPGUARD_TOKEN_ADMIN 值。

然后注册网站并调用 wp_site_context。注册会保存连接详情；不会导入或修改网站内容。

设置指南涵盖 Windows、Docker 构建、两种 WordPress 连接方式，以及带有可审阅预览的首次编辑。

包含内容

工作	工具和行为
了解站点	wp_site_context、wp_recon、wp_schema_recon 和 wp_design_context 会公开站点清单和配置信息。识别出插件并不代表已实现完整的原生集成。
完成一个页面	wp_page_list、wp_page_get 和 wp_page_compare 用于确定目标和参考页面。wp_page_replace_content 会预览完整替换内容，检查受保护文案和修正项，要求提供已审核的 etag 和精确数据包，捕获快照，然后读取已存储的结果。wp_page_render_verify 会捕获桌面端和移动端截图，并检查哈希和 DOM，且不会更改 WordPress。
在生产环境前测试	wp_page_stage_and_test 会预览两个已注册的对等站点，仅应用到单独获批的暂存站点，捕获渲染证据，并返回新的生产环境预览。它绝不会自动发布。
编辑内容和设置	wp_mutate_post_content、wp_mutate_post_meta 和 wp_mutate_option 默认会生成预览，检查适用的修正项，并在获批写入前捕获先前的值。
处理文件和区块	文件工具会提供读取和编辑预览。wp_mutate_block 会在相同的摘要、ETag、修正项、快照和数据包控制下，选择并修补一个已解析的 Gutenberg 区块。创建文章时默认设为草稿。
更新组件	wp_vulnerability_scan 会返回缓存的 clean、vulnerable 或 unknown 结果。对于 SSH 站点，可以预览并应用精确的插件／主题更新，并在更新后执行健康检查；如果失败，会自动恢复到先前版本。
恢复内容	列出并检查原生 WordPress 修订版本，或预览并批准 wp_revert_to_revision。WPGuard 会通过完整内容哈希验证生成的修订版本。
无人值守运行	管理员可以创建范围严格的预批准策略，将其绑定到站点、来源、精确动词、目标模式和最高风险等级。匹配的运行会获得一个精确数据包；未匹配的工作仍会被阻止。
记住修正项	记录、列出并停用精确目标检查。适用检查失败或无法评估时，会阻止上述三个修改工具。
查阅先前工作	导入数据包 CSV 或修正事件 JSONL，并检索其来源记录，同时不会将导入的文本转化为可执行指令。
审核更改	更改数据包会记录提案、批准和结果。wpguard audit 会显示本地账本；支持的快照可用于回滚工具。

该服务还提供高级 PHP、SQL、CLI、代码片段和访问权限工具。这些工具的权限和副作用各不相同，不受上述修正检查机制覆盖。

导入你自己的历史记录

导入历史记录会在实例的状态目录中保留原始记录、哈希和来源信息。重复导入完全相同的内容具有幂等性；发生变化的记录会保留先前版本。

数据包导出使用三种 CSV 架构：

packets:    id,client_slug,site,status,risk,created_at,summary
status:     client_canonical,total_packets,verified,open,blocked,rolled_back
categories: category,packets,distinct_clients,top_clients

python -m wpguard_mcp.history import \
  --packets packets.csv --status status.csv --categories categories.csv \
  --human-requested-basis "The operator confirmed these categories describe human-requested changes."

如需导入更丰富的会话历史记录：

python -m wpguard_mcp.history import-episodes \
  --episodes episodes.jsonl --lessons lessons.md --coverage coverage.md

每条 JSONL 记录都必须包含非空的 episode_id、client 和 site 字符串；其他证据字段会予以保留。wp_history_episodes(client_slug=...) 会与原始 client 值精确匹配。数据包查询会与数据包导出的 client_slug 精确匹配。系统不会推断两个导出文件之间的别名映射。

导入的状态和接受标签会作为历史报告保留。记录有效修正项是单独的操作，需要提供未通过和通过该检查的示例。调用方提供的接受引用会作为证明记录，不会被独立验证为已批准。

导入内容会保留在实例中，直到被查询或由其操作员以其他方式共享。查询会将所选记录发送给已连接的 MCP 客户端。请勿将私有历史记录放入公共代码库或可发布产物中。

了解边界

• **校正覆盖范围明确：**选项、文章元数据、文章内容、整页、区块和原生修订内容写入都会评估适用的目标规则。原始 PHP、SQL、文件编辑、新建文章、组件更新以及在 WPGuard 之外进行的更改，会采用不同的防护措施。
• 渲染验证的范围有限。wp_page_render_verify 会在桌面和移动设备尺寸下检查解析后的实时页面是否存在 HTTP 错误、水平溢出、渲染后图像损坏以及可选的预期文本。它会在 state/render-evidence/ 下存储经过哈希处理的截图和 JSON 回执，但不会评判视觉质量，也不会测试交互和链接。
• **权限不等于人工审批。**具有 mutate 权限范围的调用方可以审批数据包。具有 admin 权限范围的调用方可以记录或撤销校正。请在周边工作流中决定谁可以执行这些操作。
• **快照因工具而异。**无法保证每项已公开的操作都可撤销。请维护网站的常规备份。
• **配套插件具有管理功能。**建议使用由专用管理员账户持有的 WordPress 应用程序密码。现有安装仍可使用旧版共享密钥。服务端令牌等级无法保护直接联系插件的调用方。
• **本地账本假定只有一个写入方。**它们不是共享的多写入方数据库。成功重放或测试并不能证明已部署到实时生产环境。

内容校正检查需要更新后的配套插件。该插件会在预览期间返回源内容，并在应用内容替换前检查其摘要。旧版插件的响应无法满足此功能检查。

开发

python -m pip install -e ".[dev]"
ruff check .
mypy
pytest -q

CI 会在 Python 3.10–3.12 上运行 lint、类型检查和测试。运行配套处理器测试需要 PHP CLI；若未安装 PHP CLI，这些测试会跳过。所有公开的测试示例均为合成数据。

WPGuard 使用 MIT 许可证。请参阅 LICENSE。