B2 MCP Standalone 使用手册

01它是什么

本插件把 B2 主题的专属配置能力暴露为标准 MCP 服务端（Streamable HTTP / JSON-RPC 2.0）。AI 客户端连上后，就能直接读取和修改主题设置、搭建首页模块、配置文章的付费阅读与下载资源、发布圈子话题、配置商品、读写用户与分类字段、改 SEO 与页脚。

与另两个插件的关系

同一套工作里共有三个插件，定位不同、可共存：

三者类名前缀不同（B2S_ / B2MCP_ / WBMCP_），不会冲突。本插件可与 workbuddy-mcp-for-7b2 同时启用，分工是「B2 专属字段」与「通用内容管理」。

核心设计：字段自动发现

插件不硬编码任何字段名。每次请求时从主题的 CMB2 注册信息实时读取字段定义，因此主题升级新增的设置项会自动跟上，不需要等插件更新。

CMB2 按对象类型把字段分到四类存储，一套读写层即可覆盖全部能力域：

02环境要求

03安装与启用

1. 上传并启用插件 后台 → 插件 → 安装插件 → 上传插件 → 选择 b2-mcp-standalone.zip → 立即安装 → 启用。
   启用时会自动生成一个 API Key，并写入默认设置。
2. 打开「B2 MCP」菜单做一次环境自检 左侧菜单出现 B2 MCP。检查三项：
   · B2 主题识别 显示为绿色「已识别」；
   · CMB2 字段注册库 显示「可用」；
   · 字段总数 不为 0（B2 主题通常在数百量级）。
3. 复制端点地址与 API Key 同一个页面的「客户端连接」卡片里，能看到完整端点 URL 与当前 API Key。Key 可在需要时点「重新生成」（旧 Key 立即失效）。
4. 确认「启用 MCP 服务」已勾选 设置卡片里的第一个开关。关闭后端点直接返回 404，不影响站点其他功能。
5. 连接后调一次 get_status 这是唯一能一次性确认「连通性 + 环境 + 字段是否真的被发现到」的调用。详见下一节。

04连接 AI 客户端

端点地址

/info 返回服务名、版本、支持的协议列表、B2 主题是否识别、是否只读、工具总数与可用认证方式，不含任何敏感数据，可安全用于连通性测试。

认证方式（任选其一）

客户端配置示例

{
  "mcpServers": {
    "b2-theme": {
      "url": "https://你的域名/wp-json/b2-mcp/v1/mcp",
      "headers": {
        "X-B2S-Key": "b2s_你的key"
      }
    }
  }
}

协议支持情况

首次连通性验证

1. 浏览器打开 /wp-json/b2-mcp/v1/info，确认 ok 为 true、tool_count 为 26。
2. 在 AI 客户端里让它调用 get_status。
3. 返回中确认 theme.active 为真、字段统计不为 0。

05工具总览

共 26 个工具，按 7 个能力域分组。只读 表示不会改动任何数据；可写 表示会落库。

06工具参数详解

下表为每个工具的完整入参。必填参数缺失时会被拒绝；可选参数留空即可。

概览与字段发现

主题设置

模块化首页

内容专属字段

社区与商城

用户与分类

SEO 与页脚

07权限模型

每次调用都经过两道关卡：站点级只读模式（如果有，先拦截写入）→ 能力级权限（按工具逐条判定）。权限以「API Key 执行身份」或「应用密码所属用户」的身份计算。

08预演与写保护

三道防线

1. 写入前强制校验 —— 枚举值（取自 CMB2 的 options）、附件存在性（数字按附件 ID 校验，字符串按 http/https 校验）、数值上下限、邮箱 / URL / 日期格式、必填项。字段不存在时直接报错并列出可用字段名，插件从不猜字段名。
2. 话题配套字段校验 —— 投票至少 2 个选项、你猜必须有答案、说说与提问必须有正文。缺字段时直接拒绝写入，不会生成让前台报错的脏数据。
3. 账目字段写保护 —— 销量、已购用户、悬赏结算状态、分成收益、财富流水等属于「账目」的字段只读不可写。积分余额同样不走直接改 user meta 的路径，以免造成「余额数字正确、财富流水里没有这笔账」的不一致。

预演（dry_run）支持情况

安全使用建议

• 改动站点设置前，先 get_settings_schema 看清字段类型与枚举，再 get_settings 看当前值，最后 dry_run 预演。
• 调整首页模块时，先 list_home_modules 拿到准确的序号（index），序号在增删后会变化。
• 发布话题先用 status: "draft" 落草稿，后台确认无误再发布。
• 首次接入或怀疑 AI 行为越界时，直接在后台打开只读模式——所有写入类工具立即停用，读取不受影响。

09后台设置项

位置：后台左侧菜单 B2 MCP。

页面上的其他信息

客户端连接

完整端点 URL、当前 API Key、Key 绑定的执行用户 ID，以及「重新生成 API Key」按钮（旧 Key 立即失效）。

B2 引擎状态

主题识别结果与判定依据（用于排查「为什么没识别到主题」）、CMB2 是否可用、设置分组数 / Box 总数 / 字段总数。

已注册工具

按 7 个能力域列出的全部 26 个工具，含类型（只读 / 可写）与说明，方便核对当前版本能力。

10使用示例

不需要记工具名，直接用中文描述目标即可。下面是按能力域整理的示例，可以直接照抄。

环境确认

• 「先调 get_status，告诉我主题识别结果和发现了多少个设置字段。」
• 「帮我找出所有跟『备案』有关的设置项在哪个分组。」

主题设置

• 「把首页的标题分隔符改成 丨。」
• 「看一下现在全站字体相关的设置有哪些可选值，先别改。」

模块化首页

• 「列出首页现在的模块顺序。」
• 「给首页加一个文章列表模块，三列 6 篇，排在幻灯后面。」
• 「把第二个模块的标题改成『精选推荐』，其他配置别动。」

内容专属字段

• 「给文章 123 设成 20 积分付费可见，再挂两个下载链接。」
• 「文章 456 的付费阅读配置先给我看现状，再预演一下改成 VIP 可见的改动。」

社区与商城

• 「在问答圈发个提问，带 50 积分悬赏，先存草稿。」
• 「发个投票：标题『你更喜欢哪种风格』，选项 A / B / C。」
• 「把商品 456 改成 99 元、库存 200、开自动发卡。」

用户与分类

• 「看下用户 7 现在的 VIP 等级和有效期。」
• 「把用户 7 的 VIP 等级设为年费会员。」
• 「把圈子『资源分享』的加入门槛设成 30 积分的收费规则。」

SEO 与页脚

• 「把首页 description 补上，页脚备案号改成…，先 dry_run 给我看。」

11故障排查

12开发者钩子

当启发式探测在你的站点上不适用时，用这些过滤器手动指定，而不是去改插件源码。

// 示例：衍生主题识别失败时手动指定
add_filter( 'b2s_theme_detection', function ( $detected ) {
    $detected['active']   = true;
    $detected['name']     = '我的 B2 衍生主题';
    $detected['evidence'] = array( '由主题作者在 functions.php 中手动指定' );
    return $detected;
} );

13卸载

后台停用并删除即可。卸载脚本只清理插件自己的三个选项：

• b2s_settings — 插件设置
• b2s_api_key — API Key
• b2s_log — 调用日志

14验证边界

已完成

• 18 个 PHP 文件语法校验全部通过，0 失败。
• 跨文件类与方法引用一致性检查，0 问题。
• Server 骨架沿用已在同架构插件中验证过的 JSON-RPC 实现；工具层契约（定义格式、调用链、错误包装）与 Server 逐条核对。

需要你在真实站点确认

以下三处采用启发式探测，因为不同 B2 版本与衍生主题的实现可能有差异。探测失败时会明确报错，不会写坏数据；确认真实结构后可用第 12 节的过滤器手动指定。

建议的首次实测顺序

1. 启用插件并打开后台页确认主题识别、CMB2、字段统计三项正常。
2. 验证连通性浏览器打开 /wp-json/b2-mcp/v1/info，确认 ok: true、tool_count: 26。
3. 调用 get_status确认 AI 客户端能看到工具并成功调用。
4. 只读链路验证用 get_settings 读一个设置分组，用 list_home_modules 看模块列表。
5. 低风险写入验证用 update_settings + dry_run: true 预演一次，确认返回的改动符合预期再去掉预演。
6. 逐步开放先测内容字段，再测首页模块；商城与用户字段最后测。

已知限制

• 首页模块的增删改排不支持预演，会直接落库。
• 发布话题不支持预演，建议用草稿状态分两步走。
• 不提供 resources 与 prompts，只提供 tools。
• 不提供 SSE 订阅流，GET /mcp 按规范返回 405。
• 积分余额不通过直接改 user meta 实现（会造成账目不一致），只写受保护的账目字段会被拒绝。