教程 ↗

让 WordPress Ability 被 MCP 看见:公开标记、权限回调和类别前置条件

基于 WordPress MCP Adapter v0.7.1 的官方文档,说明 Ability 默认私有时如何显式开放给 MCP、为何 permission_callback 仍是执行边界,以及遗漏 category 为什么会在生产环境表现为静默失败。

WordPress Ability 从注册、MCP 公开到权限检查的关系图

给 WordPress 插件加了一个 Ability,MCP 客户端却找不到它时,先按顺序检查公开标记、已注册的 category 和 permission_callback。默认情况下,Ability 不会通过默认 MCP server 公开;公开后,permission_callback 仍会决定当前调用者能否执行;遗漏或未注册的 category 会让 wp_register_ability() 直接返回 null。

这篇文章把这三层拆开,使用官方 WordPress/mcp-adapter v0.7.1 文档中的 API 规则,写一个只读的站点信息示例。本文没有安装插件、激活 WordPress、建立认证连接或发送 MCP 请求,代码用于说明注册边界,尚未在 WordPress 站点运行。

先决定该 Ability 应该被谁发现

MCP Adapter 把 WordPress Abilities API 接到 Model Context Protocol。插件 v0.7.1 的发布物要求 WordPress 6.9 及以上、PHP 7.4 及以上;它会创建默认 HTTP 端点 /wp-json/mcp/mcp-adapter-default-server。这个端点不意味着站点里的每个 Ability 都自动出现在客户端中。

官方的 Creating Abilities 指南 把默认值写得很明确:Ability 默认不对 default server 可见。公开规则有三个实用分支:

目标注册时的 meta适用结果
同时向一般客户端和 MCP 公开public => trueMCP Adapter 会把它视为可公开的 Ability
只向 MCP 公开mcp => [ 'public' => true ]不必同时把它开放给其他客户端通道
Ability 已整体公开,但不想交给 MCPpublic => true 加 mcp => [ 'public' => false ]MCP 专用标记会覆盖高层公开值

public 解决的是发现和暴露范围,不能替代授权设计。真正执行时,permission_callback 仍会根据当前 WordPress 身份决定是否放行。一个适合普通编辑流程的 Ability,未必适合让所有连接到 MCP 的身份调用。

WordPress MCP Adapter 的官方迁移文档,说明 v0.7.0 后 standalone plugin 与 bundled Composer library 的边界

官方迁移文档把 standalone plugin 与旧的 bundled Composer library 分开说明。

一个只读站点信息示例

下面的代码使用核心已注册的 site 类别,公开范围只限 MCP,并把执行权限留给 current_user_can( 'read' )。返回内容也只包含公开站点名称和首页 URL。它适合演示结构,不适合作为已经完成认证、审计或发布策略的替代品。

add_action( 'wp_abilities_api_init', function () {
    wp_register_ability( 'example/get-site-info', [
        'label'       => 'Get site info',
        'description' => 'Returns a small, read-only site summary.',
        'category'    => 'site',
        'input_schema' => [
            'type'                 => 'object',
            'additionalProperties' => false,
        ],
        'execute_callback' => function () {
            return [
                'name' => get_bloginfo( 'name' ),
                'url'  => home_url( '/' ),
            ];
        },
        'permission_callback' => function () {
            return current_user_can( 'read' );
        },
        'meta' => [
            'mcp' => [
                'public' => true,
                'type'   => 'tool',
            ],
        ],
    ] );
} );

这里有两个容易混在一起的判断。meta.mcp.public 让这个 Ability 能被 MCP 发现,permission_callback 则在实际调用时检查身份。若要读私有文章、写草稿、清缓存或调用外部服务,应该按那个动作所需的角色和输入校验重写回调,不要因为 Ability 只在 MCP 里出现,就把权限检查放宽。

type 没有填写时默认是 tool。同一套注册机制还可以声明 resource 与 prompt,但它们各自还需要文档要求的 URI 或 arguments。本文先保持一个无输入、只读的 tool,便于把公开范围和执行权限看清。

category 不是可省略的标签

每个 Ability 都必须带一个已注册的 category。核心已提供 site 和 user 两个类别,因此示例可以直接采用 site。插件要使用自己的分类时,应先在 wp_abilities_api_categories_init 钩子注册分类,再在较后的 wp_abilities_api_init 钩子注册引用它的 Ability。

这个顺序值得在开发环境先验证。省略 category,或填入尚未注册的值时,wp_register_ability() 返回 null,并不返回 WP_Error。当 WP_DEBUG 关闭时,核心只留下 _doing_it_wrong() 相关的开发提示,站点上看起来就像一段注册代码什么也没有发生。先确认注册结果、类别钩子顺序和客户端发现结果,比在 MCP 客户端里反复改连接参数更快找到问题。

default server 的三步发现流程

默认 server 不会把所有 Ability 平铺成一串独立工具。官方 README 说明,它通过三个 meta-tools 工作:mcp-adapter/discover-abilities、mcp-adapter/get-ability-info 和 mcp-adapter/execute-ability。客户端需要先发现能力,再读取其输入和输出信息,最后才执行指定 Ability。

这会影响排错顺序:如果 tools/list 里只看见 Adapter 的 meta-tools,先检查目标 Ability 有没有 opt-in、类别有没有注册、当前身份是否能通过权限回调;不要立即把它判断成 REST 端点失效。本批没有发出实际请求,因此也没有验证认证方式、客户端对 meta-tools 的呈现方式或任何 Ability 的执行结果。

meta.public 与 REST 的关系还依赖 WordPress 版本。在 WordPress 6.9 和 7.0 中,MCP Adapter 会尊重该字段的 MCP 公开规则,但 REST 仍需显式设置 meta.show_in_rest。WordPress core 从 7.1 起才把 meta.public 映射给 REST。只打算服务 MCP 的例子无需因此增加 REST 暴露;需要 REST 的插件应把这个版本差异写进自己的测试条件。

从 bundled library 迁到 standalone plugin 时,先确认集成方式

v0.7.0 把 MCP Adapter 定位为 canonical standalone plugin。作为 Composer library bundled 进另一个插件的做法已经废弃,目前仍可运行,但后续版本会移除这条路径。若你的插件只是作为 standalone Adapter 的使用者,继续注册 Abilities 不需要改写这些声明和回调。

迁移时优先确认项目到底属于哪一类:只注册 Ability 的插件、直接调用 Adapter 或 schema API 的插件,以及把 Adapter 打包进自身发布物的插件,需要处理的变化不同。官方 v0.7.1 release notes 还列出了会话可靠性、插件加载和不可用 Ability 的错误提示调整,升级前应在自己的 WordPress 与客户端组合里走一次发现和权限测试。

如果你还在为网站接口设计响应边界,可以结合 Trylog 的动态响应、CSP 与会话隐私检查先列出哪些数据应该由浏览器、REST 或 MCP 获得。先限定数据和角色,再决定给哪个通道加公开标记,后续扩展 Ability 时不容易把“能发现”误当成“应当执行”。

← 返回列表