WordPress MCP

---

🔌 一个端点，适用于所有 AI 客户端

WordPress MCP 通过标准的 Streamable HTTP 使用开放的 Model Context Protocol。它不绑定任何一家 AI 供应商。只需在客户网站上安装，并连接你或团队使用的任意助手：Claude、ChatGPT、Codex、Gemini、Cursor、Copilot，或同时连接所有客户端。设置界面会为每个客户端生成可直接粘贴的配置。随后，Agent 就能查看真实网站并自行实施更改。无需复制粘贴，无需第二次 OAuth，也无需猜测客户使用的是哪个 SEO 插件。

---

目录

• 功能介绍
• 快速开始
• 连接你的 AI 客户端
• 提示词、资源、搜索与获取
• 使用 WordPress 登录（OAuth）
• 团队、客户端与审批
• 健康检查与连接测试
• WP-CLI
• 结构化输出与实时进度
• MCP Registry
• 适用对象
• 项目缘起
• 与众不同之处
• 架构
• 请求生命周期（线路）
• 安全性：试运行、撤销、审计
• 错误处理
• 能力模型
• 工具目录（165 个）
• 媒体与图片
• 页面构建器编辑
• 电商操作
• 与 SEO 引擎无关的 SEO 层
• 技术 SEO：链接、站点地图、IndexNow
• AEO / GEO 层
• 性能层
• 通过编码 Agent 编辑 WordPress
• Google Site Kit 桥接
• 安全模型
• 协议合规性
• 工作流：代理机构如何使用
• 扩展
• 发布历史
• 许可证

---

功能介绍

一个插件，一个端点，165 个类型化工具，还有现成的提示词和可浏览的资源。任何 MCP 客户端每个站点只需连接一次，之后就能完成全部工作，而不仅仅是描述如何完成：

📊 读取真实站点信息	已发布的内容、正在运行的 SEO 引擎、现有的 schema、Search Console 实际报告的数据、加载缓慢的内容、缺货商品。
👁️ 查看图片	get_image_bytes 返回的是图片，而不是文件名，因此替代文本和商品文案可以根据照片中的实际内容撰写。
✍️ 写入线上站点	通过客户端所用的 SEO 插件编辑 Meta、JSON-LD、文章、商品、价格、库存、菜单、小工具和主题文件。
🧩 安全编辑页面构建器页面	Elementor、Gutenberg、Divi 和 WPBakery 页面会在各自的数据结构中编辑，而不是将 post_content 扁平化处理。
🛒 运营商店	商品目录、变体、图片、批量调价、定时促销、库存和优惠券。订单和客户数据则由各自独立的开关保护。
🚀 提升站点速度	执行审计、应用可撤销的前端修复、清理数据库，并通过真实的 Core Web Vitals 验证改动效果。
↩️ 撤销所有改动	写入操作会记录在日志中。每次改动都会返回一个 operation_id；调用一次即可撤销。

---

快速开始

1. 通过 插件 → 安装新插件 → 上传插件 上传 Releases 中的 ZIP 文件，或将文件夹复制到 wp-content/plugins/wordpress-mcp/。
2. 启用 WordPress MCP。
3. 在管理菜单中打开 WordPress MCP。在 连接 AI 客户端 下，选择你的客户端并复制代码片段。网站的实际端点和密钥已自动填入。Claude 和 ChatGPT 只需要 URL：当它们提示时，你可以使用 WordPress 登录。
4. 点击 测试连接，确认 AI 客户端可以成功连接。此测试会检测被移除的标头、防火墙和缓存。
5. 启用你需要的功能组。默认设置是安全的。如需让其他人访问，请使用预设创建一个连接密钥，而不是分享你的密钥。

然后试着提出一个实际需求：

“审核此网站的 SEO，列出最差的十个页面，并修复缺失的元描述。”

需要 WordPress 5.6+ 和 PHP 7.4+。WooCommerce 和 Google Site Kit 为可选插件。只有启用这些插件时，才会显示相应的工具。

---

连接 AI 客户端

客户端	连接方式	提示词	资源	备注
Claude Code	claude mcp add + Bearer 标头	✅ /mcp__…	✅ @	最适合开发工作；支持文件和构建器
Claude 网页版和桌面版	自定义连接器：使用 WordPress 登录，或使用带 ?key= 的 URL	✅	✅	内置 OAuth 登录
ChatGPT	开发者模式：OAuth 登录，或使用带 ?key= 的 URL	否	否	写入工具需要确认；内置 search/fetch
OpenAI Codex	codex mcp add / config.toml	否	否	CLI 和 IDE 扩展共用此配置
Gemini CLI	gemini mcp add / httpUrl	✅ 斜杠命令	否	使用 httpUrl，而不是 url
Cursor	mcp.json	✅	✅
VS Code / Copilot	.vscode/mcp.json	✅	✅	密钥存储在 VS Code 的机密存储中
Windsurf	mcp_config.json	否	否	最多支持 100 个工具；使用 ?groups=
Zed · Cline · Continue · LM Studio	配置文件	不定	不定
其他客户端	Streamable HTTP，或通过 mcp-remote 使用 stdio	不定	不定	任何符合规范的客户端

_{提示词和资源支持情况取决于客户端，且经常变化。以上所有客户端均可使用工具。}

所有客户端都连接到同一个端点：

https://client.example.com/wp-json/wp-mcp/v1/mcp

客户端可以通过以下任一方式提供密钥：

方式	使用场景
Authorization: Bearer <key> 标头	任何带有标头字段的客户端。首选此方式，因为密钥不会出现在 URL 和日志中。
X-API-Key: <key> 标头	界面中带有“API 密钥标头”输入框的客户端。
URL 中的 ?key=<key>	只接受 URL 的客户端：Claude 网页版/桌面版连接器、ChatGPT 开发者模式、Continue。
使用 WordPress 登录（OAuth）	支持 MCP 登录的客户端（Claude、ChatGPT 等）。粘贴纯 URL；无需密钥。请参阅下文。

以下代码片段使用 my-site 和 YOUR_KEY。设置页面会使用你的实际值生成代码片段。

  Claude Code

claude mcp add --transport http my-site https://client.example.com/wp-json/wp-mcp/v1/mcp \
  --header "Authorization: Bearer YOUR_KEY"

  Claude（claude.ai 网页版和 Claude Desktop）

前往 **Settings → Connectors → Add custom connector**，粘贴纯端点 URL，然后点击 **Connect**。Claude 会将你带到网站，让你[登录并批准](#sign-in-with-wordpress-oauth)：

https://client.example.com/wp-json/wp-mcp/v1/mcp

如要跳过登录，请改为粘贴内置密钥的 URL：…/wp-json/wp-mcp/v1/mcp?key=YOUR_KEY。

  ChatGPT（开发者模式）

1. 前往 Settings → Apps & Connectors → Advanced settings，然后开启 Developer mode。
2. 点击 Create，粘贴纯端点 URL，然后选择 OAuth。ChatGPT 会将你带到网站，让你登录并批准。

https://client.example.com/wp-json/wp-mcp/v1/mcp

或者，选择 No authentication，并粘贴内置密钥的 URL：…/wp-json/wp-mcp/v1/mcp?key=YOUR_KEY。

ChatGPT 会在任何会写入数据的工具运行前请求确认。只读工具带有 readOnlyHint，因此 ChatGPT 会直接运行。search 和 fetch 工具遵循 ChatGPT 深度研究所需的格式。

  OpenAI Codex（CLI 和 IDE 扩展）

codex mcp add my-site --url https://client.example.com/wp-json/wp-mcp/v1/mcp \
  --bearer-token-env-var WPMCP_MY_SITE_KEY
export WPMCP_MY_SITE_KEY="YOUR_KEY"        # PowerShell: $env:WPMCP_MY_SITE_KEY="YOUR_KEY"

你也可以直接将其写入 ~/.codex/config.toml，CLI 和 IDE 扩展共用此文件：

[mcp_servers.my-site]
url = "https://client.example.com/wp-json/wp-mcp/v1/mcp"
http_headers = { "Authorization" = "Bearer YOUR_KEY" }
tool_timeout_sec = 120

  Gemini CLI

gemini mcp add --transport http --header "Authorization: Bearer YOUR_KEY" \
  my-site https://client.example.com/wp-json/wp-mcp/v1/mcp

或者将其放入 ~/.gemini/settings.json。请使用 httpUrl，因为 url 会选择旧版 SSE 传输方式：

{ "mcpServers": { "my-site": {
    "httpUrl": "https://client.example.com/wp-json/wp-mcp/v1/mcp",
    "headers": { "Authorization": "Bearer YOUR_KEY" },
    "timeout": 120000
} } }

此网站的提示词会在 Gemini CLI 中显示为斜杠命令，例如 /seo_audit。

  Cursor

将以下内容添加到 ~/.cursor/mcp.json，以用于所有项目；或添加到 .cursor/mcp.json，以用于单个项目：

{ "mcpServers": { "my-site": {
    "url": "https://client.example.com/wp-json/wp-mcp/v1/mcp",
    "headers": { "Authorization": "Bearer YOUR_KEY" }
} } }

  VS Code（GitHub Copilot Agent 模式）

将以下内容添加到 .vscode/mcp.json。VS Code 会提示输入一次密钥，并将其安全存储：

{
  "inputs": [{ "type": "promptString", "id": "wpmcp-key", "description": "WordPress MCP key", "password": true }],
  "servers": { "my-site": {
    "type": "http",
    "url": "https://client.example.com/wp-json/wp-mcp/v1/mcp",
    "headers": { "Authorization": "Bearer ${input:wpmcp-key}" }
  } }
}

  Windsurf

Windsurf 在所有服务中最多加载 100 个工具，因此请使用 ?groups= 缩小目录范围（见下文）：

{ "mcpServers": { "my-site": {
    "serverUrl": "https://client.example.com/wp-json/wp-mcp/v1/mcp?groups=content,woocommerce",
    "headers": { "Authorization": "Bearer YOUR_KEY" }
} } }

  Zed · Cline / Roo Code · Continue · LM Studio

// Zed: settings.json
{ "context_servers": { "my-site": { "url": "https://…/wp-json/wp-mcp/v1/mcp", "headers": { "Authorization": "Bearer YOUR_KEY" } } } }

// Cline / Roo Code: cline_mcp_settings.json
{ "mcpServers": { "my-site": { "type": "streamableHttp", "url": "https://…/wp-json/wp-mcp/v1/mcp", "headers": { "Authorization": "Bearer YOUR_KEY" } } } }

// LM Studio: mcp.json
{ "mcpServers": { "my-site": { "url": "https://…/wp-json/wp-mcp/v1/mcp", "headers": { "Authorization": "Bearer YOUR_KEY" } } } }

# Continue: .continue/mcpServers/my-site.yaml (agent mode)
mcpServers:
  - name: my-site
    type: streamable-http
    url: https://…/wp-json/wp-mcp/v1/mcp?key=${{ secrets.WPMCP_KEY }}

  其他客户端（包括仅支持 stdio 的客户端）

任何支持远程 Streamable HTTP MCP 服务的客户端都能使用。将其指向端点并发送 Bearer 标头即可。如果客户端只能启动本地（stdio）服务，可通过 mcp-remote 进行桥接：

{ "mcpServers": { "my-site": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://…/wp-json/wp-mcp/v1/mcp",
             "--header", "Authorization:${WPMCP_AUTH}", "--transport", "http-only"],
    "env": { "WPMCP_AUTH": "Bearer YOUR_KEY" }
} } }

每个连接使用更少的工具：?groups=

每个模型从较短的列表中选择工具时都更可靠，而且有些客户端会限制加载的工具数量。如要在连接中仅公开部分功能组，请在端点 URL 中添加 ?groups=，或发送 X-WPMCP-Groups 标头：

https://client.example.com/wp-json/wp-mcp/v1/mcp?groups=content,woocommerce

组键包括 content、woocommerce、wc_orders、performance、builders、appearance、sitekit、diagnostics、site_mgmt、filesystem 和 database。Diagnostics 始终保持启用，使 Agent 能够了解当前环境。

?groups= 只能缩小公开范围，无法启用设置中已禁用的组。一种实用的配置方式是为同一网站建立两个连接：内容撰稿人使用 ?groups=content，开发者使用全部组。

HTTPS。 如果密钥随 URL 传输，请通过 HTTPS 提供网站服务，以加密传输中的密钥。如果 URL 曾被分享，请重新生成密钥。使用标头进行身份验证可完全避免在 URL 中包含密钥。

---

提示词、资源、搜索与获取

MCP 不只有工具，客户端对其他部分的使用方式也各不相同。此服务实现了以下实用功能：

提示词：现成的工作流。 它们会以命令的形式显示在客户端中，例如 Claude Code 中的 /mcp__my-site__seo_audit、Gemini CLI 中的 /seo_audit，以及 VS Code 和 Cursor 中的 / 菜单。营销人员无需了解工具目录，就能完成一整步工作。只有当网站启用了提示词所需的工具时，才会提供相应提示词。

提示词	功能
site_briefing	介绍技术栈、运行状况、SEO 引擎和功能，然后列出排名前五的机会。不会更改任何内容。
seo_audit	审查单个页面、一种文章类型或整个网站；提出准确的标题和描述；仅在获得批准后应用
write_seo_article	调研现有内容、拟定大纲、撰写文章，并保存包含 SEO 字段、内部链接和架构标记的草稿
ai_search_readiness	GEO/AEO 评分卡，涵盖 llms.txt、AI 爬虫规则、架构标记覆盖情况和站点地图运行状况
speed_checkup	运行审查、图片报告和 PageSpeed，然后预览优化计划
fix_broken_links	全面检查失效链接，并提出替换链接或 301 重定向建议
product_seo_sweep	WooCommerce：审查并检查图片，预览产品 SEO 和架构标记修复方案
search_performance_report	Site Kit：热门页面和查询、变化情况以及可快速见效的关键词

资源：可供附加的内容。 在 Claude Desktop、VS Code、Cursor、Zed 等客户端中，你可以直接通过 @ 提及或附加网站内容。wordpress://site/overview 提供技术栈和功能信息。wordpress://content/{id} 会以纯文本形式提供任意文章、页面或产品。你还可以浏览最近更新的内容。

search 和 fetch：通用检索。 search 返回 {results: [{id, title, url, text}]}，fetch 则会根据 ID 或网站上的 URL 返回 {id, title, text, url, metadata}。这正是 ChatGPT 深度研究和企业知识连接器所需的数据结构。它也让任何 Agent 都能以较低成本查找内容，并在使用更重量级的 list_content / get_content 之前先阅读内容。

---

使用 WordPress 登录（OAuth）

支持 MCP 登录的客户端（例如 Claude 和 ChatGPT）完全不需要密钥。只需添加普通的端点 URL，连接方式就像“使用 Google 登录”一样：

1. 客户端会自动查找此网站的登录信息（MCP 授权、RFC 9728 和 RFC 8414）。
2. 客户端会打开你网站上的授权页面。你像平常一样登录 WordPress。只有管理员可以批准。
3. 你可以选择连接可执行的操作：预设权限、只读，或“每次更改都先征求我的批准”。然后点击 Approve。
4. 客户端会收到一个有效期为一小时的访问令牌，以及一个每次使用都会轮换的刷新令牌。

每个已批准的登录都会显示在 Connection keys 下，并标注客户端名称，例如“ChatGPT（由 priya 登录）”。审计日志会在每次调用中记录客户端名称，点击 Revoke 即可立即撤销访问权限。

安全性	必须使用 PKCE（S256）。授权码只能使用一次，并会在 10 分钟后过期。重定向地址必须与客户端注册信息完全一致，且必须使用 https、环回地址或应用协议。授权页面不能嵌入到框架中。刷新令牌会轮换，因此被盗用的令牌会在真实客户端刷新后失效。
客户端注册	同时支持动态客户端注册（RFC 7591）和客户端 ID 元数据文档。
要求	必须启用美观固定链接，以确保端点不含查询字符串。WordPress 安装在子文件夹中时也可正常使用。
关闭方式	Capabilities → Sign in with WordPress。无论如何，密钥都仍可使用。

---

团队、客户端与审批

此插件适用于两种情况：个人管理自己的网站，以及代理机构管理多个客户的网站。两者归根结底都涉及同一个问题：谁能做什么，以及由谁检查？

连接密钥

所有者密钥（显示在设置页面上）拥有完整访问权限。对于其他任何人或事物，请在 连接密钥 → 新建密钥 下创建连接密钥：

设置	作用
标签	谁或什么在使用此密钥，例如“Priya，ChatGPT”或“Acme Ltd 员工”。审计日志中的每次调用都会标明密钥。
预设	一组预先配置好的能力组（见下表），也可以自行选择能力组。
只读	只能使用读取类工具。网站上的任何内容都无法更改。
需要审批	每项更改都要等待管理员审批（见下文）。
到期时间	在指定天数后到期，或永不到期。

密钥本身只显示一次，之后仅以哈希形式存储。撤销一个密钥不会影响其他密钥。

预设

预设	能力组	典型用途
full	设置中启用的所有功能	你自己管理自己的网站
writer	内容与 SEO	文案撰稿人或客户员工
seo	内容、Site Kit、页面构建器、性能	SEO 专家
store	内容、WooCommerce 商品目录、订单、Site Kit	商店管理员
developer	所有功能，包括文件、数据库和网站管理（启用时）	在工作期间使用的开发人员
readonly	内容、WooCommerce、性能、页面构建器、外观、Site Kit；仅限读取工具。不包含文件、原始数据库和网站管理，因为读取这些内容可能会暴露凭据。	审计、报告，或你正在试用的新 AI 工具

无需创建密钥，也可以在单个连接上使用预设。在端点 URL 中添加 ?preset=writer，或在 连接 AI 客户端 → 工具预设 中选择预设。预设、密钥能力组和 ?groups= 只能相互缩小权限范围。它们会在每次调用时强制执行，包括 batch 中的各个步骤。

审批

为客户团队创建一个启用了需要审批的密钥。他们的 AI 仍然可以读取所有内容并预览更改（dry_run=true）。任何会更改网站的操作都会保存为更改请求，并告知 Agent 正在等待审批：

update_content id=812 title="Summer Sale: 20% off all hoodies"
  → { "queued_for_approval": true, "request_id": "260924123533fb4f9c", … }

你可以在 WordPress MCP → 审批 中审核请求，其中会并排显示内容和 SEO 修改的差异。你可以批准或拒绝请求，并附上备注。批准后，系统会完全按照请求执行更改并记录操作，因此 undo_operation 仍可撤销该操作。Agent 会使用 list_change_requests 检查处理结果。你也可以在终端中使用 wp mcp approvals list 和 wp mcp approvals approve <id>。

典型的代理机构配置

Client site A
  ├─ Owner key ............. agency lead, full access (Claude Code)
  ├─ "Agency SEO team" ..... preset seo, expires in 90 days
  ├─ "Acme staff" .......... preset writer, needs approval
  └─ "ChatGPT (signed in by acme-admin)" ... read-only, via OAuth

---

健康检查与连接测试

连接失败通常不是 Bug。常见原因包括：主机移除了 Authorization 标头、防火墙返回 HTML 拦截页面、缓存重放旧响应，或网站未使用 HTTPS。以下三个工具可以查找这些问题，并说明如何逐一修复：

• 设置页面上的测试连接会从你的浏览器调用端点，模拟 AI 客户端的连接方式。它会依次尝试 Bearer 标头、X-API-Key、URL 中的密钥、tools/list 和 GET，然后运行服务器端检查。
• 工具 → 网站健康状况中会新增两项 WordPress MCP 检查：配置和端点可访问性。
• wp mcp doctor 会在终端中运行相同的检查。

这些检查可以检测 HTTPS 问题、普通固定链接、主机移除的 Authorization 标头（并提供用于修复的确切 .htaccess 配置行）、防火墙或 WAF 拦截页面、CDN 或页面缓存返回的 MCP 请求响应、响应缓慢、仍然启用的高风险能力组、未使用或已过期的密钥、待审批请求、PHP 执行时间限制过短，以及工具近期发生的 PHP 崩溃。

---

WP-CLI

设置页面上的所有功能也都可以通过 wp mcp 命令使用。借助 WP-CLI 别名，代理机构可以在一个终端中对每个客户站点运行这些命令。

wp mcp status                                    # endpoint, version, groups, keys, pending approvals
wp mcp key create "Acme staff" --preset=writer --approval --expires=90
wp mcp key list
wp mcp key revoke ab12cd34
wp mcp groups disable filesystem database site_mgmt
wp mcp approvals list
wp mcp approvals approve 260924123533fb4f9c --note="Looks good"
wp mcp doctor                                    # connection health checks
wp mcp tools --group=woocommerce
wp mcp connect codex                             # print the Codex config for this site

# Onboard every client site in one go
for site in @client-a @client-b @client-c; do
  wp $site plugin install wordpress-mcp --activate
  wp $site mcp key create "Agency SEO team" --preset=seo --expires=90
done

---

结构化输出和实时进度

结构化输出。 结果格式稳定的工具会声明 outputSchema，并以类型化的 structuredContent 同时返回结果。这样，客户端就可以渲染表格，并直接将数据传递给代码，而不必从文本中解析 JSON。这些工具包括 search、fetch、site_info、seo_status、get_seo、list_content、list_operations、list_change_requests 和 mcp_status。

实时进度。 seo_audit、find_broken_links、product_seo_fix 和 regenerate_thumbnails 等耗时任务会在执行期间发送进度通知，前提是客户端请求接收通知。客户端通过发送 progressToken 并接受 text/event-stream 来发出请求。这些调用会以简短的事件流作为响应，其他所有调用仍返回普通 JSON。不发出请求的客户端仍可通过第二个连接轮询 get_progress。

---

MCP Registry

此插件在 server.json 中进行了描述，以供官方 MCP Registry 使用。支持 Registry 的客户端和目录可以列出此插件；设置时只需输入网站域名，也可以选择输入密钥。GitHub Actions 工作流（.github/workflows/publish-mcp-registry.yml）可在 Actions 选项卡中手动运行时发布此插件，并会先检查列出的版本是否与插件版本一致。

---

适用对象

你是……	你将获得……
SEO 代理机构／自由职业者，负责管理多个 WordPress 客户	每个客户安装一个插件 → 将每个站点接入团队使用的任意 AI。以代理机构规模审核、规划并实施 SEO/AEO/GEO，并为每次写入操作提供撤销日志。
数字营销人员，日常使用 ChatGPT、Claude 或 Gemini	用通俗英语提问；它会读取 Search Console、找出快速见效的机会、撰写元数据并发布文章。
开发者／高级用户	为 Codex、Claude Code、Gemini CLI、Cursor 或 Copilot 提供符合标准的 MCP 服务：165 个类型化工具、文件系统和原始 SQL 访问权限（受权限控制）、批处理，以及两步添加自定义工具的方式。
WooCommerce 商店所有者	Agent 可处理产品文案、图片、定价、库存、分类和符合 Merchant 标准的产品架构数据。

内容和 SEO 功能默认强大。通过配置，为所有危险操作提供安全保障。

---

为什么要开发它

你需要为许多 WordPress 客户管理 SEO。问题在于：AI 助手无法查看客户的网站（已发布哪些内容、有哪些架构数据、产品图片实际展示了什么、Search Console 报告了什么），也无法对网站执行操作，除非你在不同工具之间来回传递数据。

WordPress MCP 打通了这一流程。它将每个客户站点变成一个远程 MCP 服务。你只需在每个站点上通过一条命令或粘贴配置连接一次 AI 客户端；之后，Agent 就可以列出内容、审核 SEO、查看图片、将元数据写入客户使用的任意 SEO 插件、生成架构数据、发布优化后的文章和产品、管理 llms.txt／robots／重定向／站点地图，以及获取实时 Google 数据，所有操作都通过一个经过身份验证的端点完成。

设计原则：核心 SEO 和内容工作始终可用，且可安全委托；高风险功能（文件系统、原始 SQL、用户和插件管理）虽然存在，但默认关闭，需要通过明确的功能开关启用；任何写入操作都可以先预览，之后也可以撤销。

---

它有何不同

许多工具都能与 WordPress 对话。真正重要的是，当 Agent 获得客户线上站点的实际操作权限时，会发生什么。

0. 适配你已在使用的 AI

没有供应商绑定，也不需要为每个助手单独安装插件。一个符合标准的 MCP 端点即可服务 Claude、ChatGPT、Codex、Gemini、Cursor、Copilot，以及任何支持该协议的产品。团队中的不同成员可以同时使用不同助手访问同一个网站。→ 连接 AI 客户端

1. 写入客户端已有的 SEO 插件

你无需告诉 Agent 用的是 Yoast 还是 Rank Math。一组标准化字段会映射到正确的元键，包括大多数集成都只能正确处理一半的社交图片字段对。→ 与引擎无关的 SEO 层

2. 编辑页面构建器页面而不破坏页面

覆盖 Elementor 或 Divi 页面的 post_content 毫无作用，甚至会破坏布局。这些工具会将页面读取为可寻址的树，并在构建器自身的数据中重写其中一个元素。→ 页面构建器编辑

3. 每次写入都可撤销

在大多数工具中，批量调价、全站搜索替换和 SEO 扫描都是不可逆的操作。这里每次经过检测的写入都会记录被覆盖的值，并通过 undo_operation 将其恢复。→ 安全性：试运行、撤销、审计

4. Agent 能查看图片

根据文件名编写替代文本只是在猜测。get_image_bytes 会将实际图片提供给模型，因此替代文本、说明文字和产品描述都能准确描述图片内容。你还可以确认商品是否关联了正确的照片。→ 媒体和图片

5. 失败后可以恢复，而不只是收到报告

每个错误都包含稳定的 code、面向用户的 message、可执行的 hint 和结构化的 details。Agent 可以修正自己的调用，而无需猜测。→ 错误处理

6. 长任务也能完成

三千件商品的审计不会因 PHP 执行时间限制而中止。扫描会提前停止、返回恢复偏移量，并在运行期间通过第二个连接报告进度。→ 安全性：试运行、撤销、审计

7. 一次请求完成两百次编辑

batch 可在一次往返中运行最多 50 次工具调用，每次调用都有各自的结果或错误，并且可作为一个操作整体撤销。

8. 每个站点、每次合作期间，危险功能均需主动启用

文件系统、原始 SQL、站点管理和客户数据各自都有独立开关，并由服务端强制执行。内容相关的合作任务无法读取用户电子邮件。→ 功能权限模型

---

架构

一个引导文件负责连接各司其职的类。除常量和一个访问器外，没有任何全局内容。

wordpress-mcp.php                 Bootstrap: constants, requires, register wpmcp(), activation hook
│
└── includes/
    ├── class-wpmcp-plugin.php      Singleton orchestrator: builds collaborators, registers hooks
    ├── class-wpmcp-settings.php    Single option row: API key + capability-group flags
    ├── class-wpmcp-rest.php        Streamable HTTP transport: dual-era JSON-RPC routing, auth, throttle
    ├── class-wpmcp-tools.php       Registry: catalogue, capability gate, validation, dispatch, wire shaping
    ├── class-wpmcp-prompts.php     MCP prompts: ready-made workflows surfaced as client commands
    ├── class-wpmcp-resources.php   MCP resources: site overview and content by wordpress:// URI
    ├── class-wpmcp-clients.php     Ready-to-paste connection recipes for each MCP client
    ├── class-wpmcp-keys.php        Connection keys, presets, OAuth tokens (hashed)
    ├── class-wpmcp-oauth.php       OAuth 2.1 sign-in: metadata, client registration, consent, tokens
    ├── class-wpmcp-approvals.php   Change requests held for an administrator's approval
    ├── class-wpmcp-health.php      Site Health checks, connection test, wp mcp doctor
    ├── class-wpmcp-cli.php         wp mcp … commands
    ├── class-wpmcp-error.php       Typed tool exception, error codes, rolling log, fatal guard
    ├── class-wpmcp-validator.php   Argument validation and coercion against each inputSchema
    ├── class-wpmcp-journal.php     Undo journal: records what each write overwrites
    ├── class-wpmcp-audit.php       Rolling log of every tool call, arguments redacted
    ├── class-wpmcp-progress.php    Progress heartbeat + the execution-time budget
    ├── class-wpmcp-util.php        Multibyte counting, value coercion, PHP syntax checking
    ├── class-wpmcp-media.php       Shared image ingest: sources, dedup, SEO filenames, processing
    ├── class-wpmcp-seo.php         Engine-agnostic Yoast / Rank Math normalised read+write
    ├── class-wpmcp-schema.php      Product / ProductGroup structured data builder
    ├── class-wpmcp-sitekit.php     Read-only Google Site Kit data bridge (runs as connected admin)
    ├── class-wpmcp-performance.php Front-end speed flags + measurement helpers
    ├── class-wpmcp-frontend.php    Public output: JSON-LD, /llms.txt, robots.txt, redirects, IndexNow key
    ├── class-wpmcp-admin.php       Material-3 settings screen: key, toggles, status, error log
    │
    └── tools/                      One trait per capability group: definitions + handlers
        ├── trait-wpmcp-content.php      38 tools  content, SEO, terms, meta, revisions, comments
        ├── trait-wpmcp-search.php        2 tools  search + fetch (universal retrieval shape)
        ├── trait-wpmcp-woocommerce.php  29 tools  products, variations, images, inventory, coupons
        ├── trait-wpmcp-sitemgmt.php     16 tools  plugins, themes, users, options, cron, permalinks
        ├── trait-wpmcp-filesystem.php   13 tools  read/write/search/backup/restore, child themes
        ├── trait-wpmcp-integrations.php 13 tools  Site Kit data + diagnostics + self-check
        ├── trait-wpmcp-appearance.php    9 tools  menus, widgets, customizer, site identity
        ├── trait-wpmcp-orders.php        8 tools  orders, refunds, customers (own group, off by default)
        ├── trait-wpmcp-performance.php   8 tools  audit, optimise, cleanup, cache, images
        ├── trait-wpmcp-builders.php      8 tools  Elementor/Gutenberg/Divi/WPBakery layout editing
        ├── trait-wpmcp-media.php         7 tools  view, optimise, regenerate, dedupe, orphans, alt text
        ├── trait-wpmcp-ops.php           6 tools  batch, undo, restore points, progress, audit log
        ├── trait-wpmcp-seotech.php       4 tools  broken links, sitemaps, IndexNow
        └── trait-wpmcp-database.php      3 tools  guarded raw SQL + schema inspection

一个工具包含两部分，放在同一处：追加到 defs_*() 方法中的定义，以及与之并列的 tool_<name>( $args ) 处理器。registry() 按约定将二者映射起来，因此添加工具时无需修改任何中央代码。

职责划分

层	类	职责
传输	WPMCP_REST	HTTP 路由、身份验证、暴力破解限流、协议版本协商、JSON-RPC 封套、MCP 路由、内容块
分发	WPMCP_Tools	工具目录、能力门控、每连接作用域、验证、dispatch() → 处理器、跨客户端架构塑形和注释
工具之外	WPMCP_Prompts、WPMCP_Resources	工作流提示词；可附加的网站内容
接入	WPMCP_Clients	Claude、ChatGPT、Codex、Gemini、Cursor、VS Code、Windsurf、Zed、Cline、mcp-remote 的连接配置片段
故障处理	WPMCP_Errors、WPMCP_Validator	带代码和提示的类型化错误；参数检查；滚动日志
可逆性	WPMCP_Journal	记录每次写入覆盖的内容；撤销时按相反顺序重放
问责	WPMCP_Audit	每次调用：工具、已脱敏参数、状态、耗时、IP、撤销句柄
节流	WPMCP_Progress	长时间运行任务的心跳；使任务能够干净停止的时间预算
领域	WPMCP_SEO、WPMCP_Schema、WPMCP_Media、WPMCP_SiteKit、WPMCP_Performance	SEO 字段映射；产品结构化数据；图像导入和处理；Google 数据；速度标志
持久化/配置	WPMCP_Settings	API 密钥、能力标志（单条 wp_options 记录）
公共接口	WPMCP_Frontend	<head> 中的 JSON-LD、/llms.txt、robots.txt 规则、重定向、IndexNow 密钥文件
控制平面	WPMCP_Admin	设置界面 + 表单处理器
接线	WPMCP_Plugin	在正确的钩子上构造并注册所有内容

---

请求生命周期（线路）

每次交互都是向单一端点发送一个 POST，通过 MCP 的 Streamable HTTP 传输使用 JSON-RPC 2.0。响应为纯 application/json，该传输在每个协议修订版中都允许这种格式，且所有客户端均支持。

MCP client                      WordPress MCP                         WordPress core
─────────────────────────────────────────────────────────────────────────────────────
POST /wp-json/wp-mcp/v1/mcp
Authorization: Bearer <key>  ─► WPMCP_REST::check_auth()
{ "jsonrpc":"2.0",              │   brute-force lockout?  ── 429 if IP over limit
  "method":"tools/call",        │   hash_equals( key ) over header / X-API-Key / ?key  ── 401 on mismatch
  "params":{                    ▼
    "name":"set_seo",        WPMCP_REST::handle()  ── routes by JSON-RPC method
    "arguments":{...} } }        │
                                 ├─ initialize          → negotiated version + capabilities + instructions
                                 ├─ server/discover     → same, for stateless (2026-07-28) clients
                                 ├─ tools/list          → WPMCP_Tools::exposed_definitions()
                                 │                          (enabled groups ∩ ?groups scope, deps present,
                                 │                           titles + annotations, schema shaped for every model)
                                 ├─ prompts/list|get    → WPMCP_Prompts
                                 ├─ resources/list|read → WPMCP_Resources
                                 └─ tools/call          → WPMCP_Tools::dispatch(name,args)
                                                            │
                                                            ├─ registry lookup (unknown → did-you-mean)
                                                            ├─ WPMCP_Settings::can(group)?  ── disabled → error
                                                            ├─ WPMCP_Validator::check(schema,args)
                                                            ├─ WPMCP_Progress::boot()    time budget starts
                                                            ├─ WPMCP_Journal::open()     writes only
                                                            ├─ tool_<name>($args) ──────────► WP_Query / wp_insert_post
                                                            │                                 update_post_meta / $wpdb …
                                                            ├─ WPMCP_Journal::close()    → operation_id
                                                            └─ WPMCP_Audit::record()     → audit log
                                 ◄─ { result:{ content:[{type:"text",text:"<json>"}] } }
                                    (images add {type:"image",data,mimeType} blocks)
                                    (errors → { result:{ isError:true, content:[…] } })

已实现的 MCP 方法： initialize、server/discover、ping、logging/setLevel、tools/list、tools/call、prompts/list、prompts/get、resources/list、resources/templates/list、resources/read。通知会以 202 接受。请参阅协议合规性。

每次 tools/call 都有两道门控：

1. 传输身份验证：有效密钥（恒定时间比较）+ 暴力破解限流，否则返回 401/429。
2. 能力门控：工具所属组必须在设置中启用，否则返回工具错误。所属组已关闭的工具也会从 tools/list 中隐藏，因此 Agent 不会看到它们。

连接时的站点概况。 initialize 会返回一段 instructions 字符串，描述此站点：站点名称、检测到的 SEO 引擎、WooCommerce 是否启用、已启用的组、写入操作会记录日志且可撤销，以及 batch 的存在。Agent 从一开始就能了解站点情况，无需进行探测。

---

安全：试运行、撤销、审计

设置了三个彼此独立的层，因为每一层要应对的故障都不同：“别这么做”、“把它恢复原样”，以及*“上周二它做了什么？”*

预览：dry_run

任何会进行广泛写入的操作默认都设置为 dry_run=true，并准确返回将会发生哪些变更：bulk_update_products、bulk_update_content、search_replace_content、bulk_set_seo、bulk_set_image_alt、product_seo_fix、bulk_assign_variation_images、optimize_site、optimize_image、database_cleanup、indexnow_submit，以及针对整个分类的 update_inventory。再次执行并设置 dry_run=false 即可应用变更。

Reverse：撤销日志

每次写入都会经过日志，先快照即将被覆盖的值。如果工具没有更改任何内容，就不会存储任何记录，因此读取调用不会产生开销。

update_product id=4821 regular_price="24.00"
   → { "success": true, …, "operation_id": "260824182233a91f",
       "undo_with": "undo_operation id=260824182233a91f" }

undo_operation id=260824182233a91f
   → { "restored": 1, "success": true }

记录内容	文章元数据、分类法元数据、文章列、选项、规范化后的 SEO 字段集，以及通过 WooCommerce 自有 setter 修改的字段
涵盖范围	批量调价、库存、搜索和替换、批量内容与 SEO 写入、架构、替代文本、商品图片、还原点、整个批次
list_operations	最近 40 次写入操作：工具、时间、受影响的记录，以及是否已撤销
create_restore_point	在执行高风险操作前，快照某个完整文章类型的 SEO、架构，以及可选的内容。一个 ID 即可还原全部内容
防护措施	对每个目标采用首次写入优先，因此循环即使两次修改同一个键，撤销时仍会恢复到初始状态。拒绝重复撤销。无法完整记录的超大型操作会标记为不完整，需要设置 force=true。撤销操作本身不会记入日志。

并非所有操作都可撤销，插件也不会假装如此：database_cleanup 会永久删除行，而文件写入由各自的备份系统（list_backups / restore_file）负责，而非由日志记录。

Account：审计日志

get_audit_log 会返回服务处理过的每次调用：工具、已隐藏机密的参数、成功或失败、耗时、请求方 IP、结果摘要，以及可用于撤销该操作的 operation_id。可按工具、writes_only、errors_only 或 since 筛选。错误日志会说明出了什么问题；这里记录的是执行了什么操作。

Finish：进度与时间预算

过去，对整个目录进行扫描时，能否在 max_execution_time 限制内完成全凭运气。现在：

• get_progress：运行期间通过第二个连接调用它，即可查看工具、已完成数量与总数量、已耗时秒数以及当前处理项。
• 预算：达到服务器执行时限的 70% 时，长时间扫描会停止，返回 stopped_early 和 next_offset，并说明如何继续。适用于 seo_audit、product_seo_audit、product_seo_fix、find_broken_links、sitemap_audit、optimize_image、regenerate_thumbnails、find_unused_media、create_restore_point 和 batch。

减少往返调用：batch

{ "tool": "batch", "arguments": { "operations": [
    { "id": "a", "tool": "set_seo",        "args": { "id": 12, "fields": { "title": "…" } } },
    { "id": "b", "tool": "update_product", "args": { "id": 44, "regular_price": "24.00" } }
] } }

最多支持 50 个步骤。每个步骤都会返回自身结果或自身的类型化错误，因此一个步骤失败不会影响其余步骤。整个批次作为一个操作撤销。批次中不能包含另一个批次。

---

错误处理

Agent 只能从自己能理解的故障中恢复。因此，所有通过网络传输的错误都是结构化的，而非描述性文字：

{
  "error": true,
  "tool": "update_product",
  "code": "not_found",
  "message": "Product 4821 was not found.",
  "hint": "Use list_products to find the right ID, or pass sku to get_product.",
  "details": { "id": 4821 }
}

code 稳定且机器可读：invalid_argument、missing_argument、not_found、capability_disabled、dependency_missing、permission_denied、conflict、io_failed、upstream_failed、unknown_tool、tool_failed、fatal_error。

五层处理，按从外到内的顺序排列

层	捕获的情况
传输层	格式错误的 JSON、未知方法（以有效的 JSON-RPC 响应，而非裸 500 响应返回）
预检层	未知工具（附带 你是否想找 建议）、已禁用的分组、缺少依赖项、参数错误
验证层	类型不匹配；在合理情况下进行强制转换（"42" → 42、"a,b" → ["a","b"]），否则以明确的消息拒绝
处理程序层	将 WooCommerce/WordPress 的拒绝转换为包含修复方法的类型化错误
致命错误防护层	即使处理程序内部发生崩溃，也会通过关机钩子返回可读的 JSON-RPC 错误

不止于报告。 调用期间触发的 PHP 警告会被捕获，并通过 _warnings 随成功结果一同返回，因此主题钩子中的弃用问题会显现出来，而非悄无声息。警告捕获支持重入，因此在 batch 内运行的工具不会清除外层调用的状态。每次故障都会记录在滚动保留最近 30 条记录的日志中，可通过 get_error_log 读取，也会显示在设置页面上。mcp_status 会报告插件对自身状态的视图：已启用的分组、已公开与已定义的工具数量、依赖项状态、内存用量及近期故障。

写入失败仍可撤销。 如果处理程序在批量运行中途抛出异常，日志会保留而非丢弃，因为未完成的更改正是你最想撤销的内容。

防止无法恢复的故障。 向在线站点写入有问题的 PHP 会导致站点和此端点同时宕机。之后无法再通过第二次调用来修复。因此，每次写入前都会解析 PHP；如果代码无法编译，就会拒绝写入。每次覆盖或删除都会保留带时间戳的备份，可通过 restore_file 回滚。

功能组

每个工具都只属于一个功能组。必须先启用某个组，才能公开或运行其中的工具。此门控在服务端的 dispatch() 中强制执行，而不只是从界面中隐藏。默认设置以安全为先：破坏性较强的组默认关闭。

组	默认状态	范围	风险
内容与 SEO	开启（锁定）	文章／页面／任意自定义文章类型、术语、元数据、媒体库、修订版本、评论、JSON-LD、llms.txt、robots、重定向、站点地图、失效链接、IndexNow、Yoast／Rank Math 字段，以及批量处理、撤销和还原点	核心功能。可安全委派。
WooCommerce 商品目录	开启*	商品、变体、属性、分类、图片、批量调价、库存、优惠券、商店设置、商品架构、销售报告	商业数据写入
WooCommerce 订单与客户	关闭	订单、订单备注、退款、客户记录	高（个人数据 + 资金）
性能	开启	速度审计、前端优化标记、数据库清理、缓存清除、图片报告	中（更改可撤销）
页面构建器	开启	Elementor／Gutenberg／Divi／WPBakery／Beaver 布局读取和元素级编辑、全局样式	中（编辑实际页面布局）
外观	开启	菜单、小工具、自定义器主题修改、站点标识	低（可见但可撤销）
Google Site Kit	开启*	只读 Search Console／GA4／PageSpeed／关键词机会	只读
诊断	开启	站点健康状态、环境、插件／主题清单、MCP 自检、错误日志、实时进度、审计日志	只读
站点管理	关闭	安装／更新／删除插件和主题、用户、选项、cron、固定链接	高（站点控制）
文件系统	关闭	读取／搜索／写入／编辑／复制／移动／删除文件、子主题脚手架	严重（写入 PHP = RCE）
原始数据库	关闭	原始 SELECT + 受保护的写入 SQL + 架构检查	严重（无法撤销）

_{* 无论开关状态如何，当依赖插件未启用时，WooCommerce 和 Site Kit 工具都会自动隐藏。}

内容与 SEO组处于锁定开启状态。这是该插件存在的原因，并且它包含其他所有功能所依赖的撤销工具。用户元数据访问（电子邮件、权限）不属于此组；它需要启用站点管理，因此“仅限内容”的连接无法读取用户电子邮件或提升用户角色。

---

工具目录（165）

内容与 SEO（56）：search、fetch、batch、list_change_requests、list_operations、undo_operation、create_restore_point、find_broken_links、get_sitemap、sitemap_audit、indexnow_submit、get_image_bytes、list_content、get_content、publish_content、update_content、delete_content、duplicate_content、bulk_update_content、search_replace_content、get_seo、set_seo、bulk_set_seo、serp_preview、set_schema、get_schema、generate_schema、analyze_content、internal_link_opportunities、manage_llms_txt、manage_robots_txt、manage_redirects、seo_audit、list_post_types、list_taxonomies、list_terms、save_term、delete_term、get_meta、set_meta、delete_meta、upload_media、list_media、delete_media、set_image_alt、bulk_set_image_alt、set_featured_image、optimize_image、restore_image、regenerate_thumbnails、find_duplicate_media、find_unused_media、list_revisions、restore_revision、list_comments、moderate_comment

启用 PSEOEWP 时（另有 4 项）：ai_readiness_audit、set_short_answer、ai_visibility_report、pseoewp_settings。参见 PSEOEWP。 WooCommerce 目录（29）：list_products、get_product、create_product、update_product、delete_product、duplicate_product、bulk_update_products、list_product_variations、save_product_variation、delete_product_variation、generate_product_variations、bulk_assign_variation_images、list_product_attributes、save_product_attribute、list_product_categories、save_product_category、delete_product_category、manage_product_images、update_inventory、inventory_report、product_seo_audit、product_seo_fix、generate_product_schema、list_coupons、save_coupon、delete_coupon、store_report、get_store_settings、update_store_settings

WooCommerce 订单与客户（8）：list_orders、get_order、update_order、add_order_note、refund_order、list_customers、get_customer、customer_insights

性能（8）：performance_audit、optimize_site、performance_settings、database_cleanup、clear_cache、image_optimization_report、analyze_page_speed、list_autoloaded_options

页面构建器（8）：detect_page_builder、get_page_structure、edit_page_element、insert_page_section、delete_page_element、list_builder_templates、manage_global_styles、render_page_preview

外观（9）：list_menus、list_menu_items、save_menu、delete_menu、manage_menu_items、list_widgets、save_widget、theme_customizer、manage_site_identity

Google Site Kit（6）：sitekit_status、sitekit_search_analytics、sitekit_analytics_report、sitekit_pagespeed、sitekit_keyword_opportunities、sitekit_get

诊断（9）：get_progress、get_audit_log、site_info、site_health、seo_status、list_plugins、list_themes、mcp_status、get_error_log

站点管理（16）：install_plugin、activate_plugin、deactivate_plugin、update_plugin、delete_plugin、install_theme、switch_theme、delete_theme、get_option、update_option、delete_option、list_users、save_user、delete_user、manage_cron、manage_permalinks

文件系统（13）：list_files、read_file、write_file、edit_file、search_files、copy_file、move_file、make_dir、delete_file、file_info、list_backups、restore_file、create_child_theme

原始数据库（3）：sql_query、sql_execute、describe_tables

每个工具都提供 JSON Schema inputSchema、展示用的 title，以及行为注释：readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint。客户端会根据这些注释判断哪些操作需要用户确认。服务器会在处理程序运行前验证并转换参数，因此类型错误会返回 id must be an integer, got string，而不是深入调用栈数层后才出现 PHP 错误。

这些 Schema 均限定在每个主要模型提供商都接受的子集中。每个属性都只有一种类型，每个数组都声明了其项目类型，也不使用 anyOf、$ref 或类型联合。因此，同一目录无需修改即可加载到 Claude、ChatGPT/Codex（OpenAI 函数调用）和 Gemini 中。对于 set_meta / update_option 等自由格式值，如果需要传递结构化数据，则以字符串形式并通过 value_format=json 传递。

---

媒体和图片

媒体库的所有入口（upload_media、商品图片、变体图片和批量工具）都经过同一个导入引擎，因此行为一致。

manage_product_images product_id=812
  main:    { url: "https://supplier.example/IMG_2831.JPG", alt: "…" }
  gallery: [ { base64: "…", filename: "back.jpg" },
             { path: "wp-content/uploads/import/side.jpg" },
             1422 ]
  mode: "replace"   max_dimension: 2000   convert: "webp"

  → downloaded / decoded / copied, de-duplicated by content hash,
    renamed black-cotton-hoodie.jpg, -2, -3 …,
    downscaled and converted before they become attachments,
    alt text filled, gallery ordered exactly as sent,
    and any single bad source reported without losing the rest

四种来源，一种格式	现有附件的 id、由服务器下载的 url、原始 base64（也支持数据 URI），或服务器上已有文件的 path（需要 Filesystem 功能）
SEO 文件名	IMG_2831.JPG 会保存为 black-cotton-hoodie.jpg，并按画廊顺序编号。这是真正的图片排名信号，而旧的侧载方式无法控制这一点
去重	导入时对字节进行哈希处理。同一张照片导入到 20 个商品时，会重复使用同一个附件
存储前处理	max_dimension、convert（WebP/AVIF）和 quality 会在文件成为附件之前应用，因此媒体库不会保存 5 MB 的原始文件及其生成的 8 种尺寸
可编辑的画廊	mode（replace / append / prepend）、remove_ids、reorder、detach_main，以及每张图片的标题、说明文字和描述
部分失败也能继续	每个来源都会报告各自的错误；其他内容仍会保存

查看图片。 get_image_bytes 可按 ID、文章（特色图片）或商品（主图加画廊）返回附件的真实内嵌图片。图片会缩小并重新编码后再传输，原图不会被修改。这样一来，替代文本、说明文字和商品描述就能描述照片本身，而非文件名；你也可以询问 “正确的图片是否放在了正确的商品上？” 并得到答案。

媒体库维护。 optimize_image 会缩小、转换并重新编码已存储的图片。它会保留可还原的原图，绝不会用更大的文件替换原图；转换导致旧 URL 发生变化时，还可选择改写文章内容和 Elementor 数据中的旧 URL；restore_image 则可撤销这些操作。媒体库工具还包括 regenerate_thumbnails（分批执行，可恢复）、find_duplicate_media（查找字节完全相同的分组，并指出实际正在使用的副本）、find_unused_media（查找没有被引用的媒体，并检查特色图片、商品画廊、文章内容和页面构建器布局）以及 bulk_set_image_alt（为整个媒体库批量套用模板设置替代文本）。

---

页面构建器编辑

在经典站点中，WordPress 页面才只是“post_content 中的 HTML”。Elementor 会在文章元数据中保存 JSON 树；Gutenberg 会在内容中保存区块注释；Divi 和 WPBakery 会保存嵌套短代码；Beaver Builder 会保存序列化对象。在这些构建器中覆盖 post_content，要么不起作用，要么会破坏布局，因为构建器会根据自己的数据重新渲染页面。

因此，这些工具会检测页面实际使用的构建器，并以该构建器自身的结构进行编辑。

detect_page_builder id=42     → "elementor", write_support: full,
                                 safe_to_overwrite_post_content: false

get_page_structure id=42      → every section, column, widget and block as a flat,
                                 addressable tree:
                                 [ { element_id: "a1b2c3d", type: "heading",
                                     text: "Our Services", level: 3 },
                                   { element_id: "e4f5g6h", type: "button",
                                     text: "Get a quote", link: "/contact" }, … ]

edit_page_element id=42 element_id="a1b2c3d" text="What We Do"
                              → rewrites that one widget, regenerates the builder's
                                 CSS cache, leaves everything else untouched

render_page_preview id=42     → fetches the live page and returns the rendered
                                 headings, text, images and links: what the visitor
                                 actually sees, not what the data says

构建器	检测方式	支持情况
Elementor	_elementor_edit_mode + _elementor_data	完整：读取、编辑、插入、删除；保存时重新生成 CSS 缓存
Gutenberg 区块	has_blocks()	完整：解析后重新序列化，因此区块属性和包装结构都会保留
Divi	_et_pb_use_builder、[et_pb_section]	文本和属性（拒绝重写包含子模块的容器）
WPBakery	_wpb_vc_js_status、[vc_row]	文本和属性
Beaver Builder	_fl_builder_enabled	读取（序列化对象过于脆弱，不能在未检查的情况下重写）
Oxygen / Bricks / Breakdance / SiteOrigin	自有元数据键	读取
经典 HTML	回退方式	完整：可逐个区块寻址

此外还有：insert_page_section（标题、段落、图片、按钮、间隔区块或原始构建器数据，可放在开头、结尾或现有元素旁边，并根据页面构建器生成正确格式），delete_page_element、list_builder_templates（Elementor 库、可复用区块、区块样式、Divi 和 Beaver 布局），以及 manage_global_styles，用于管理 Elementor kit 的颜色和字体，或区块主题的 theme.json 调色板，一次性重设整个网站的样式，而非逐页调整。

对于只读构建器，工具会明确报错，而不会悄悄破坏布局：错误会指出构建器名称、说明支持的操作，并指向可用的工具。

---

商务运营

WooCommerce 功能面向实际店铺运营，而不只是描述店铺。

DISCOVER   list_products (search, category, type, stock, price band, on-sale, SKU)
           get_product   → every field, including variations, attributes, downloads, ratings
           inventory_report / store_report / product_seo_audit

RANK       product_seo_fix         bulk-repair missing titles, descriptions, alt text, schema
           generate_product_schema Product / ProductGroup JSON-LD with gtin, brand, shipping,
                                   returns, price validity and variants

BUILD      create_product          simple | variable | grouped | external
           save_product_attribute  global attribute + its terms in one call
           generate_product_variations
                                   builds every missing attribute combination, skips existing
           manage_product_images   main image + gallery from attachment IDs, URLs, base64 or a
                                   server path; SEO filenames, de-duplication, downscale/WebP,
                                   gallery reorder and removal, per-image error reporting
           bulk_assign_variation_images
                                   attribute value → image, applied across every variation

MERCHANDISE
           bulk_update_products    reprice by %/fixed/set across a filtered set
                                   start and end sales on a schedule
                                   move stock status, categories, visibility, featured
           save_coupon             percent / fixed cart / fixed product, limits, restrictions
           update_inventory        per-item lists, or a whole category; absolute or relative

OPERATE    (wc_orders group, off by default)
           list_orders / get_order / update_order / add_order_note
           refund_order            manual by default; via_gateway=true to move real money
           list_customers / get_customer / customer_insights

Merchant Center 接受的产品结构化数据。 单独的 Product + Offer 组合即使通过验证，也不会带来任何收益。generate_product_schema 会根据 WooCommerce 已知的信息，以及只有商家才能提供的少数政策信息，构建完整对象：gtin / mpn / sku、brand（会检查五种品牌分类法）、priceValidUntil、shippingDetails、hasMerchantReturnPolicy、itemCondition、颜色 / 尺寸 / 材质、重量、评分和嵌入式评价。可变产品会转换为 ProductGroup，并将每个变体作为 hasVariant 报价。配送和退货政策可以通过 save_defaults 保存一次，并在整个商品目录中复用；该工具还会报告仍然缺少哪些信息，而不会悄悄生成不完整的对象。

在线店铺中很重要的保护措施：bulk_update_products 和按类别执行的 update_inventory 会在写入前提供预览，并且写入后可以撤销；refund_order 不会允许退款金额超过可退款余额，除非明确要求调用支付网关，否则会记录为手动退款；update_store_settings 只接受白名单中的键，因此没有任何路径可以访问支付凭据；设置库存数量时，会自动保持库存状态一致。

---

与引擎无关的 SEO 层

你无需告诉 Agent 客户端使用的是哪款 SEO 插件。WPMCP_SEO 会检测当前启用的引擎，并将一组标准化字段映射到相应的元数据键：

normalised field          Yoast key                         Rank Math key
──────────────────────────────────────────────────────────────────────────────
title                  →  _yoast_wpseo_title             →  rank_math_title
description            →  _yoast_wpseo_metadesc          →  rank_math_description
focus_keyword          →  _yoast_wpseo_focuskw           →  rank_math_focus_keyword
canonical              →  _yoast_wpseo_canonical         →  rank_math_canonical_url
og_title / og_desc     →  _yoast_wpseo_opengraph-*       →  rank_math_facebook_*
og_image               →  _yoast_wpseo_opengraph-image   →  rank_math_facebook_image
                          (+ …-image-id)                    (+ …_image_id)
twitter_title / _desc  →  _yoast_wpseo_twitter-*         →  rank_math_twitter_*
twitter_image          →  _yoast_wpseo_twitter-image     →  rank_math_twitter_image
                          (+ …-image-id)                    (+ …_image_id)
noindex / nofollow     →  _yoast_wpseo_meta-robots-*     →  rank_math_robots[]

• Yoast：通过 WPSEO_VERSION / WPSEO_Options 检测。
• Rank Math：通过 RankMath / RANK_MATH_VERSION 检测。
• 两者都未启用 → 值会存储为标准文章元数据；启用受支持的引擎后即可显示。

所有写入操作都会经过 sanitize_text_field。相同的标准化处理也适用于术语（分类/标签 SEO）和 WooCommerce 产品，并且每次 SEO 写入都会记录到日志中，因此出现错误时，只需一次调用即可撤销整批操作。

图片字段既接受附件 ID，也接受 URL，并且始终会同时写入 URL 和附件 ID。社交图片只设置其中一项，通常就是预览未能正常显示的原因。

大规模处理。 bulk_set_seo 会将模板（{title}、{category}、{brand}、{sku}、{price}、{site}、{separator}）应用于整个文章类型；product_seo_fix 会根据产品自身信息修复 product_seo_audit 报告的问题。两者都会根据渲染后的像素宽度（而非字符数）检查每项结果。serp_preview 展示了这为何重要：Illinois 和 MMMMMMMM 都有八个字符，但其中一个的宽度是另一个的三倍。

---

技术 SEO：链接、站点地图、IndexNow

find_broken_links post_type=post
   → internal links resolved against the database first (exact, free),
     the rest requested over HTTP with redirects followed
   → broken URLs grouped, each naming every post that links to it
   → redirects reported separately: something to update, not something broken
   → results cached 6h; the crawl resumes where the execution budget stopped it

get_sitemap        → detects core / Yoast / Rank Math, follows an index into its
                     children, reports URL counts, newest lastmod and samples

sitemap_audit      → noindexed URLs sitting in the sitemap
                     published content missing from it
                     URLs that 404 or redirect (sampled over HTTP)
                     stale lastmod dates
                     (the check that explains "Google indexed the wrong pages")

indexnow_submit    → pushes URLs to Bing, Yandex, Naver and Seznam
                     verification key generated and served at /<key>.txt automatically
                     send explicit URLs, post IDs, or everything changed in N days

---

AEO / GEO 层

与 PSEOEWP 搭配使用。 PSEOEWP 是同一开发者开发的开源 SEO、AEO 和 GEO 插件。启用该插件后，WordPress MCP 会通过 PSEOEWP 的 API 写入 SEO 字段、重定向、llms.txt 和 IndexNow，还会添加用于审核页面对答案引擎的适配情况、设置可引用的简短答案，以及报告 AI 助手和爬虫访问情况的工具。可以这样提问：“审核我最新发布的十篇文章，检查其 AI 就绪情况，并修复你能处理的问题。”

由 Agent 管理、由 WPMCP_Frontend 渲染的答案引擎和生成式引擎优化：

• JSON-LD 架构：按文章存储于 _wpmcp_jsonld，写入时进行验证，并在单篇内容视图的 wp_head 中输出。输出会进行十六进制转义（JSON_HEX_TAG|HEX_AMP|HEX_QUOT|HEX_APOS），因此字符串值绝不会逸出 <script> 元素。generate_schema 会直接根据文章数据生成 Article/FAQPage/HowTo/BreadcrumbList/Product JSON-LD；对于真正的 WooCommerce 产品，则会交由 WPMCP_Schema 生成完整的 Product / ProductGroup 对象。
• llms.txt：通过重写规则在 /llms.txt 提供单个全站文档（text/plain），并通过 manage_llms_txt 管理。该文件会告知生成式引擎网站的性质以及如何使用该网站。
• robots.txt 控制：manage_robots_txt 会将受管理的指令追加到虚拟 robots.txt 中，其中包括针对 AI 爬虫（GPTBot、ClaudeBot、Google-Extended、PerplexityBot、CCBot、……）的明确允许/拒绝规则。这是 GEO 爬取控制的入口。
• 重定向：manage_redirects 会存储 301/302/307/308 规则，并通过 template_redirect 在早期调用 wp_safe_redirect 提供服务，让重组后的内容保留其链接权重。
• 即时索引：对支持的引擎使用 indexnow_submit；Google 仍会通过站点地图发现变更，而 sitemap_audit 会确保站点地图内容准确。

---

性能层

“让我的网站更快”会触发一个由三次调用组成的循环。

1. performance_audit            read-only. Measures the live page (response time, HTML weight,
                                render-blocking scripts, compression, cache headers, lazy-loading),
                                inspects the platform (PHP version, object cache, OPcache, caching
                                plugin, plugin count), and the database (autoload bloat, revisions,
                                transients, orphaned meta).
                                → ranked issues, each with a concrete fix, and a score out of 100.

2. optimize_site                dry run by default; shows every planned change with its risk first.
   preset=safe                  emoji script, oEmbed script, wp_head cleanup, self-pingbacks,
                                Heartbeat throttle, revision limit, expired transients
   preset=aggressive            + Dashicons, jQuery Migrate, XML-RPC, WooCommerce cart fragments,
                                revision purge, database cleanup, cache purge

3. analyze_page_speed           re-measure, with real Core Web Vitals from PageSpeed Insights
                                when Site Kit is connected. Prove the change.

每项前端调整都会以标记的形式存储，仅应用于公开页面；performance_settings 会列出这些调整及其风险等级，并且可以随时撤销。这里的操作不会修改主题文件，也不会安装其他插件。配套工具包括：database_cleanup、clear_cache（对象缓存、重写规则、OPcache 和十一个缓存插件）、image_optimization_report、list_autoloaded_options。

图片通常是报告中占比最大的部分，而真正能降低图片体积的是 optimize_image 工具（参见媒体和图片）。

---

通过编码 Agent 编辑 WordPress

连接插件后，Claude Code、Codex、Gemini CLI、Cursor 或 Copilot 等编码 Agent 操作网站的方式，就像操作代码仓库一样。

你想要……	工具
查找某项内容的定义位置	search_files（在整个安装目录中使用 grep 搜索）、file_info
编辑主题或插件代码	read_file、edit_file（精确匹配替换、追加、前置）、write_file（检查 PHP 语法并创建备份）
撤销错误的编辑	list_backups、restore_file
撤销错误的数据变更	list_operations、undo_operation
正确地自定义主题	create_child_theme 用于搭建子主题，copy_file 用于复制模板以进行覆盖
编辑使用 Elementor/Divi/WPBakery/区块构建的页面	detect_page_builder、get_page_structure、edit_page_element、insert_page_section、render_page_preview
重新设置整个网站的样式	manage_global_styles
调整导航结构	list_menus、save_menu、manage_menu_items
更改侧边栏	list_widgets、save_widget
重塑品牌形象	manage_site_identity、theme_customizer
批量修复内容	search_replace_content（试运行）、bulk_update_content、batch
回滚页面	list_revisions、restore_revision
管理技术栈	update_plugin、install_theme、save_user、manage_cron、manage_permalinks
调试	mcp_status、get_error_log、get_audit_log、site_health、describe_tables

文件系统和站点管理工具组默认关闭。执行相关工作时启用，用完后再关闭。

---

Google Site Kit 桥接

如果客户端已经运行并连接了 Google Site Kit，此插件会复用其 OAuth，因此无需再次授权，也不会存储我们自己的 Google 凭据。WPMCP_SiteKit 会临时切换到已连接的管理员账户，并向 Site Kit 自己的 REST 路由发送内部 GET 请求，然后在 finally 代码块中恢复之前的用户：

sitekit_search_analytics      ─► request('search-console','searchanalytics', …)
sitekit_keyword_opportunities ─► search-console queries, filtered to positions 5 to 20
sitekit_analytics_report      ─► request('analytics-4','report', …)
sitekit_pagespeed             ─► request('pagespeed-insights','pagespeed', …)
sitekit_get                   ─► request(<module>,<datapoint>, …)   // GET passthrough, read-only

所有 Site Kit 访问均为只读（仅限 GET 数据端点）。

---

安全模型

威胁模型。 一个 API 密钥用于对端点进行身份验证。在已启用的功能组内，该密钥被信任，可以执行操作，因此它是最重要的资产。此设计将默认攻击面控制在较小范围，并通过明确的开关限制所有危险操作。

已实施的控制措施

• 恒定时间认证。 对每个提交的凭据（Bearer 标头、X-API-Key / X-WP-MCP-Key、?key=）使用 hash_equals()，不会提前退出。密钥为 48 个字符，且可安全用于 URL。在设置中重新生成密钥会立即使旧密钥失效。

• 可与其他认证插件协同工作。 JWT 及类似插件会在整个站点拦截所有 Bearer 标头，并在请求到达此端点前将其拒绝。仅对此路由，携带有效 MCP 密钥的请求会清除这些插件返回的错误。其他所有 REST 路由仍受其保护。在会剥离该标头的 Apache CGI/FastCGI 主机上，还会从 REDIRECT_HTTP_AUTHORIZATION 恢复 Authorization 标头。

• 认证失败时返回简洁响应。 缺少密钥或密钥错误时，返回包含 JSON-RPC 正文的 401 响应，以及不包含 OAuth 元数据的纯 WWW-Authenticate: Bearer 质询。这样客户端会提示“需要密钥”，而不会启动注定无法成功的 OAuth 发现流程。

• 来源验证（可选择严格模式）。 端点绝不接受 Cookie，因此来自其他来源的浏览器页面即使访问该端点，没有密钥也无济于事；默认情况下接受任何来源。通过 wpmcp_allowed_origins 过滤器返回列表，即可拒绝其他来源的请求并返回 403。

• 暴力破解锁定。 按 IP 记录失败次数（瞬态数据）：失败 10 次后，端点会在 15 分钟内返回 429。认证成功后会清除计数器。为部署在许多公共客户端站点上的密钥增加保护。

• 无 Cookie/CSRF 攻击面。 端点仅使用 API 密钥进行认证；不会接受 WordPress 登录 Cookie，因此跨站请求无法借用管理员会话。

• 服务端能力检查。 在 dispatch() 中强制执行，而不只是从 tools/list 中隐藏。已禁用组的工具无法访问。

• 默认安全的分组。 全新安装时，Filesystem、Raw Database 和 Site Management 均为关闭状态。

• 强化媒体导入安全性。 所有上传路径（URL、base64、服务器路径）都会使用 get_allowed_mime_types() 验证文件名，拒绝脚本/可执行文件扩展名（php、phtml、phar、svg、html 等），并通过 wp_check_filetype_and_ext 重新验证写入的字节，从而堵住将 shell.php 上传到 /uploads 的远程代码执行漏洞。此外，通过服务器 path 读取图像需要 Filesystem 能力，并受 realpath 限制在 WordPress 根目录内。

• 验证出站请求。 传递给 wp_remote_* 的 URL（包括 sideload、链接检查、站点地图获取和页面测量）都会通过 wp_http_validate_url() 验证，因此服务器无法被用于探测 localhost 或私有网段。

• 路径包含范围限制。 safe_path() 会拒绝 .. 片段和 NUL 字节，使用 realpath 解析路径，并通过尾部分隔符比较确认结果是 WP 根目录或其真正的子目录（因此 /var/www/htmlX 这样的同级目录无法伪装成 /var/www/html 的内部路径）。新的嵌套路径会相对于最近的现有父级路径解析。

• “只读” SQL 确实只读。 sql_query 要求语句以 SELECT/SHOW/DESCRIBE/EXPLAIN 开头，并且会阻止 INTO OUTFILE、INTO DUMPFILE 和 LOAD_FILE()。

• 受保护的写入 SQL。 sql_execute 会拒绝 DROP、TRUNCATE，以及没有 WHERE 子句的 DELETE/UPDATE，除非传入 confirm=true；并且会在两个 SQL 工具中阻止 SQL 级别的文件 I/O，避免利用数据库分组绕过文件系统权限检查。

• 强化存储型 XSS 防护。 JSON-LD 输出经过十六进制转义；llms.txt、robots.txt 规则和 IndexNow 密钥文件均以纯文本形式提供。

• 用户数据访问范围。 读取/写入用户元数据（电子邮件、wp_capabilities）需要 Site Management 能力。

• 个人数据使用独立开关。 订单、退款和客户记录位于 wc_orders 中，默认关闭，因此目录或 SEO 工作不会附带姓名、电子邮件和地址的访问权限。

• 日志中绝不记录机密。 审计日志和撤销日志会在存储前对 content、base64、password、api_key、key、secret 和 token 参数进行脱敏。

• 写入前先解析 PHP。 如果文件写入后无法编译，则会拒绝写入，因为主题文件中的致命错误会导致整个站点以及此端点停止运行，使你无法再进入站点修复问题。

• 自动创建可还原的备份。 每次覆盖或删除都会将旧版本复制到 uploads 下的受保护目录（通过 .htaccess 禁止访问，并包含 index.php）；可使用 restore_file 还原，最多保留 100 个条目。

• 商店设置采用白名单。 update_store_settings 只接受固定列表中的 WooCommerce 选项，无法通过该功能访问支付网关凭据。

• 默认手动退款。 refund_order 会记录退款，但除非设置 via_gateway=true，否则不会调用支付网关；退款金额也绝不会超过仍可退还的金额。

• 自我保护。 插件拒绝停用或删除自身，也拒绝删除存储其自身 API 密钥的选项，避免在会话中途悄无声息地断开连接。

• HTTPS 提示。 如果端点未使用 HTTPS，设置页面会发出警告，因为每个请求都会携带密钥。

• 错误信息不会泄露路径。 错误响应中的文件路径均以相对于 WordPress 根目录的形式呈现，绝不会显示服务器绝对路径。 连接和密钥

• 每次调用都会执行所有限制。 每次调用时，分发器都会检查密钥的预设、分组和只读标记，包括 batch 的每个步骤和每次资源读取。这些限制并非只在 tools/list 中隐藏工具。访问其他分组数据的工具也会检查该分组。读取用户元数据需要连接上的 Site Management 权限，从服务器路径读取图片需要连接上的 Filesystem 权限。

• 审批不能扩大密钥权限。 将 batch 加入队列时，会根据请求密钥检查每个步骤。审批后会以请求密钥的身份执行更改，权限范围也与该密钥一致，绝不会使用审核者的权限。排队后已撤销的密钥所发出的请求无法获批。只有确实提供预览功能的工具才会在 dry_run=true 时跳过队列。

• 工具以真实用户身份运行，对受限密钥启用 HTML 过滤。 所有者密钥以管理员身份运行。其他密钥则以创建或批准该密钥的管理员身份运行，因此文章会有作者，但 WordPress 的 HTML 过滤（kses）仍会启用。受限密钥无法在访客或管理员会加载的内容中存储脚本。wpmcp_owner_user_id 筛选器用于选择用户。

• 撤销历史按密钥区分。 一个连接只能列出和撤销其自身的操作。所有者密钥可以查看全部操作。

• 密钥以哈希形式存储。 连接密钥和 OAuth 令牌会经过 SHA-256 哈希处理，且只显示一次。刷新令牌会轮换，并与其客户端绑定。

• 无法被反过来利用的锁定机制。 有效密钥始终可以通过，即使请求来自已被锁定的地址。过期令牌和已撤销密钥不会计作猜测次数，因此繁忙的共享代理不会导致所有人都被锁定。

Agent 无法触碰的数据

• 受保护的元数据密钥。 通用元数据工具会拒绝 WordPress 视为可信内部状态的密钥，例如附件文件路径、附件元数据、页面模板、用户权限和会话令牌，以及此插件自己的 _wpmcp_* 密钥。每种数据都有专用且经过验证的工具。
• 文件操作仅限上传目录。 图片优化、还原和缩略图清理只会更改文件位于上传目录内的附件。
• 机密信息会得到保护。 read_file、search_files 和 copy_file 会拒绝访问 wp-config.php、.env 文件、私钥和此插件的备份。选项工具会拒绝访问此插件的选项和 WordPress 的盐值。站点所有者可以使用 wpmcp_allow_secret_file 筛选器允许访问特定文件。
• 禁止访问私有文章类型。 内容工具会拒绝访问 WooCommerce 订单、隐私请求和其他内部类型。订单有自己的分组，默认关闭。
• 获取工具无法伪造请求。 获取 URL 的工具会使用 WordPress 的安全 HTTP 函数，该函数会拒绝私有地址和环回地址，包括重定向后的地址。媒体下载和 Base64 上传的大小上限为 25 MB。
• 备份隐藏存放。 文件备份存放在随机命名的文件夹中，文件名也是随机的，并设置了 Apache 和 IIS 的拒绝规则，因此即使服务器忽略 .htaccess，也无法猜到备份位置。
• 反斜杠会保留。 所有由 Agent 输入写入的内容都会按 WordPress 的预期进行转义，因此区块标记（\u003c）、Windows 路径和元数据中的 JSON 都能逐字节还原。

登录（OAuth）

• 未登录的访客不会触发任何操作。用户必须先在授权页面登录，因此该页面无法被用作开放重定向，也无法诱使站点获取任意 URL。
• 授权页面会将每个应用标记为未经验证，显示完整的返回地址，并默认选中只读访问权限。
• 只有登录完成后才会创建密钥，再次登录会复用已有密钥。注册有大小上限，并按地址进行速率限制。

运营指南

• 为每个客户端使用单独的密钥；切勿重复使用。
• 仅在需要时启用 Filesystem / Raw Database / Site Management，完成后立即关闭。
• 通过公共互联网连接前，请先通过 HTTPS 提供客户端网站。
• 无人值守运行后，请查看 get_audit_log。它记录了 Agent 实际执行的操作。
• 将密钥视同管理员密码：任何持有密钥的人都能执行已启用组所允许的操作。

---

工作流：代理机构如何使用

1. ONBOARD a client
   └─ Install + activate the plugin on their WP site
   └─ Copy endpoint + key from the WordPress MCP screen
   └─ Paste the snippet for your AI client (Claude, ChatGPT, Codex, Gemini, Cursor, Copilot …)
   └─ Run the site_briefing prompt

2. ORIENT (read-only, default-safe)
   └─ site_info / mcp_status / seo_status     → stack, engine, what is enabled
   └─ detect_page_builder <id>                → what actually builds their pages
   └─ seo_audit / product_seo_audit           → missing meta, thin content, dupes, missing alt
   └─ sitemap_audit / find_broken_links       → what Google is being told, and what is dead
   └─ performance_audit                       → ranked speed issues and a score
   └─ sitekit_keyword_opportunities           → striking-distance quick wins (pos 5-20)

3. PLAN
   └─ analyze_content <id>                    → per-page keyword placement, structure, AEO gaps
   └─ internal_link_opportunities <id>        → where inbound links should come from
   └─ inventory_report / store_report         → what is out of stock, what actually sells

4. SNAPSHOT before anything risky
   └─ create_restore_point post_type=product  → one ID that puts the whole set back

5. IMPLEMENT
   └─ get_image_bytes                         → look at the photo before writing about it
   └─ set_seo / bulk_set_seo / product_seo_fix → meta written to the live engine, dry run first
   └─ generate_product_schema apply=true      → Merchant-grade JSON-LD
   └─ publish_content / update_content        → ship optimised posts and pages
   └─ edit_page_element                       → change builder pages without breaking layout
   └─ bulk_update_products                    → copy, pricing, sales, stock (preview first)
   └─ batch                                   → fifty edits in one request
   └─ manage_llms_txt / manage_robots_txt     → AEO/GEO crawl signals
   └─ manage_redirects / indexnow_submit      → 301 old URLs, then tell the engines

6. SPEED UP
   └─ optimize_site preset=safe dry_run=true  → review the plan
   └─ optimize_site preset=safe dry_run=false → apply
   └─ optimize_image / database_cleanup       → cut page weight, clear the junk

7. VERIFY
   └─ render_page_preview / analyze_content   → confirm what actually landed
   └─ analyze_page_speed                      → prove the speed change
   └─ get_audit_log / get_error_log           → what was done, and whether anything failed quietly
   └─ undo_operation <id>                     → if the client hates it, take it back

8. (optional) DEEP OPS: enable a powerful group only when needed
   └─ read_file / edit_file / create_child_theme   → filesystem
   └─ update_plugin / save_user / manage_cron      → site_mgmt
   └─ sql_query / describe_tables                  → database
   …then switch the group back off.

可端到端执行的提示词

“让我的网站更快。” → performance_audit → optimize_site（先预览，再应用）→ optimize_image → analyze_page_speed，展示优化前后的对比。

“为每张产品照片撰写恰当的替代文本。” → get_image_bytes → 查看图片 → manage_product_images 或 bulk_set_image_alt。

“更改服务页面上的主视觉标题。” → detect_page_builder → get_page_structure → edit_page_element → render_page_preview。

“将 Winter 类别中的所有商品打 8 折，持续到 31 日。” → 使用 price_adjust 和 sale_to 调用 bulk_update_products，先进行试运行；如果客户端改变主意，再调用 undo_operation。

“为什么 Google 没有为我们的新页面编入索引？” → sitemap_audit → 使用 set_seo 修复 noindex → indexnow_submit。

“哪些产品在搜索中拖了后腿？” → product_seo_audit → sitekit_search_analytics → product_seo_fix。

---

扩展

分两步添加工具，代码位于其所属组的 trait 中（includes/tools/trait-wpmcp-*.php）：

1. 在该 trait 的 defs_*() 方法中追加定义（group、name、description、inputSchema）。
2. 在旁边添加 tool_<name>( $args ) 处理器，并返回可序列化数组。

registry() 按约定将 name → tool_<name> 映射起来，因此无需更改中央代码。参数验证、能力门控、错误类型、撤销日志、审计日志和 JSON-RPC 封装都会自动生效。

妥善处理失败。 抛出带有代码和提示的异常，而不是裸字符串。这样 Agent 才能自行恢复：

WPMCP_Errors::fail(
    WPMCP_Errors::NOT_FOUND,
    sprintf( 'Product %d was not found.', $id ),
    'Use list_products to find the right ID, or pass sku to get_product.',
    [ 'id' => $id ]
);

WPMCP_Errors::from_wp_error( $wp_error, $code, $hint ) 会转换 WP_Error 并保留其数据。处理器抛出的其他异常都会被捕获、分类、记录，并以 tool_failed 返回，因此即使出现错误，也会得到清晰易懂的答复，而不是 500 错误。

让写入操作可撤销。 覆盖数据前先创建快照；处理器执行期间，日志已自动开启：

WPMCP_Journal::post_meta( $post_id, '_my_meta_key' );   // or ::post_seo(), ::option(),
update_post_meta( $post_id, '_my_meta_key', $value );   // ::post_fields(), ::product()

就这些：dispatch() 会关闭日志，在结果中返回 operation_id，而 undo_operation 会重放日志以撤销操作。

在长时间运行中保持良好表现。 如果工具需要遍历大量数据，请报告进度并遵守预算：

WPMCP_Progress::start( 'my_tool', count( $items ) );
foreach ( $items as $i => $item ) {
    if ( WPMCP_Progress::should_stop() ) {
        return WPMCP_Progress::stopped_early( $offset + $i, $total, 'my_tool' );
    }
    WPMCP_Progress::tick();
    …
}

建议遵循的约定

• 任何会写入整个网站的操作都应接受 dry_run，并默认设为 true。
• 使用 WPMCP_Util::word_count() / ::len()，而不是 str_word_count() / strlen()，以便正确计算非拉丁语网站的内容。
• 返回 success、受影响的 id，以及足够的信息，方便调用方无需再次调用即可验证结果。
• 对于暗示后续操作的结果，请添加 next_step。它能将工具串联成工作流。

如需添加整个能力组：将其加入 WPMCP_Settings::groups()，创建 includes/tools/trait-wpmcp-<group>.php，然后在 class-wpmcp-tools.php 中添加 require_once 和 use，并将其 defs_*() 加入 definitions()。

---

发布历史

每个版本的完整说明：发布版本。

版本	概要	工具
2.1.0	与同一开发者开发的开源 SEO、AEO 和 GEO 插件 PSEOEWP 配套使用。启用该插件后，SEO 工具会读取和写入 PSEOEWP 字段，manage_redirects 新增 410 和正则表达式规则，llms.txt 和 IndexNow 共用一个事实来源，并新增四个工具：ai_readiness_audit、set_short_answer、ai_visibility_report 和 pseoewp_settings。未启用 PSEOEWP 时不会有任何变化。	165 + 4
2.0.0	兼容所有 MCP 客户端，团队也可以安全地共享站点。连接密钥支持预设、只读访问、过期时间和审批队列。使用 WordPress 登录（OAuth 2.1）。提供连接测试和站点健康检查。提供 wp mcp WP-CLI 命令。支持结构化输出和实时进度。列入 MCP Registry，推出新徽标和官方客户端标识。协议支持：符合规范的 Streamable HTTP，支持 2024-11-05 至 2026-07-28 版本的协议，包括无状态的 server/discover。工具架构可在 Claude、OpenAI 和 Gemini 中加载，解决了 set_meta / update_option 被拒绝的问题。新增工具注释和标题、预置提示词、wordpress:// 资源、search / fetch、按连接进行 ?groups= 范围限定、X-API-Key 身份验证、兼容 JWT 风格的身份验证插件，以及适用于 11 个客户端的连接代码片段。撤销功能现覆盖 search_replace_content、update_content、set_meta 和 update_option。	165
1.4.0	Agent 可以查看图像；每次写入都可撤销；每个请求最多 50 次调用。媒体导入引擎（URL / base64 / 服务器路径、SEO 文件名、去重、WebP）、撤销日志和还原点、batch、失效链接检查、站点地图审计、IndexNow、符合 Merchant 规范的产品架构、社交图片 SEO 字段、审计日志、实时进度，以及长时间运行的时间预算。	162
1.3.0	支持页面构建器的编辑功能（Elementor、Gutenberg、Divi、WPBakery）、完整的 WooCommerce 商店操作（包括订单和退款）、站点速度审计和优化器、菜单和小工具，以及结构化错误处理（包含语法检查的文件写入和自动备份）。	140
1.2.0	深度 SEO/AEO/GEO：内容分析、架构生成、内链查找器、AI 爬虫 robots.txt 控制、托管重定向、Search Console 关键词机会、就地文件编辑、防暴力破解身份验证保护。	55
1.1.0	支持仅 URL 连接器使用 URL 中的密钥，并修复 Site Kit 用户解析问题。	46
1.0.0	初始版本：JSON-RPC MCP 端点、与引擎无关的 SEO、WooCommerce、Site Kit、JSON-LD、llms.txt、功能组。	46

---

协议合规性

基于 MCP 规范构建。已使用官方 TypeScript 和 Python SDK 客户端以及 Claude Code 进行了端到端测试，并验证了与 Gemini CLI 的连接。

区域	行为
传输	Streamable HTTP，单一端点。POST 返回 application/json。GET 和 DELETE 返回 405，并带有 Allow: POST，因为没有由服务端发起的流，也没有需要结束的会话。
版本	握手时期 2024-11-05、2025-03-26、2025-06-18、2025-11-25：initialize 会回显受支持的版本，否则提供 2025-11-25。无状态时期 2026-07-28：携带 _meta["io.modelcontextprotocol/protocolVersion"] 的请求会获得 server/discover、resultType、列表的 ttlMs / cacheScope，以及 Mcp-Method / Mcp-Name 标头检查。
标头	不受支持的 MCP-Protocol-Version 会返回 400。响应会回显协商后的版本。CORS 允许并向基于浏览器的客户端公开 MCP 标头。
消息	通知和客户端响应会返回无正文的 202。批量请求（2025-03-26 修订版允许）会得到应答。解析错误返回 -32700，未知方法返回 -32601。
会话	无状态。不签发 Mcp-Session-Id，客户端发送的该标头会被忽略。
身份验证	静态 API 密钥（MCP 授权为可选）。401 会携带纯 Bearer 挑战，不含 OAuth 资源元数据。
工具	提供 title、annotations 和可移植的 inputSchema。错误以 isError 结果返回，并附带机器可读的 code 和 hint。图像使用原生 image 内容块。

---

许可证

GPL-2.0-or-later。请参阅 LICENSE。

客户端徽标是各公司品牌资源包中的官方标识。Gemini 图标来自 Simple Icons（CC0），因为使用 Google 的资源包需要合作伙伴登录。所有徽标均为其所有者的商标，仅用于展示兼容性。这不代表存在任何关联或认可。来源和使用条款：assets/clients/。

作者

由 Konko Maji 构建（LinkedIn）。