wp-claude-mcp

# wp-claude-mcp 赋予Claude（或任何MCP兼容的AI客户端）对自托管WordPress站点的完全编辑权限。两个小型插件，无需SaaS，无需数据路径中的第三方服务。 ### 按顺序安装以下三个组件： WordPress MCP适配器 - 从wordpress.org插件目录安装，激活它。这是官方插件，按名称搜索即可。 本插件 - 从GitHub下载editorial-abilities.php，上传到WordPress的插件 → 新增 → 上传。激活它。 连接Claude - 在Claude的设置中，添加一个MCP服务器，指向站点的URL（https://your-site.com/wp-json/mcp/v1），使用WordPress用户名和应用程序密码（在WP管理后台 → 用户 → 个人资料 → 应用程序密码中生成）。 安装完成后，AI代理可以列出和编辑帖子、页面、管理媒体库、更新站点设置和自定义CSS、注入页脚JavaScript，并读取/写入编辑者通常通过`/wp-admin`执行的所有操作 - 所有操作均通过[模型上下文协议](https://modelcontextprotocol.io/)进行。 ``` ┌─────────────┐ MCP ┌──────────────────────┐ 能力 API ┌──────────────┐ │ Claude（或 │ ──────────────▶ │ WordPress MCP │ ────────────────────▶ │ 本插件的能力│ │ 任意MCP │ （HTTP，JSON） │ 适配器 │ （进程内调用） │ 20+ 能力 │ │ 客户端） │ ◀────────────── │ /wp-json/mcp/v1/... │ ◀──────────────────── │ │ └─────────────┘ └──────────────────────┘ └──────────────┘ ``` --- ## v1.2.0 新增功能 此版本在所有20种能力中应用了[mcp-builder技能](https://www.anthropic.com/)的最佳实践： - **输出模式** - 每个能力现在都声明了一个`output_schema`，以便MCP客户端了解返回数据的确切形状和类型，从而实现结构化内容渲染和可靠的下游链接。 - **真实的分页元数据** - 每个列表操作都返回`total_count`、`page`、`per_page`、`has_more`和`next_page`，以便客户端可以迭代大型数据集而无需猜测。 - **MCP工具注释** - `readOnlyHint`、`destructiveHint`、`idempotentHint`和`openWorldHint`通过`meta.mcp.annotations`按能力设置。列表操作是只读的；创建操作是非幂等的；删除和覆盖操作被标记为破坏性的。客户端使用这些提示来决定向用户确认什么。 - **可操作错误消息** - 每个错误都包含一个`建议：...`提示，指向代理下一次尝试的方向（例如，“使用editorial/list-posts查找正确的ID”）。该错误模型基于mcp-builder原则，即错误应减少代理的调试循环。 这些更改是向后兼容的。现有客户端继续工作；新客户端获得更丰富的元数据。 --- ## 为什么存在这个插件 WordPress具有强大的REST API，但直接向AI客户端公开REST API很麻烦 - 没有模式发现，没有权限合同，在开放的Web上公开需要仔细的应用程序密码管理。 MCP适配器解决了这个问题。它通过MCP公开WordPress**能力**（小型、类型化、权限检查的操作）。该插件在开箱即用的基础上添加了编辑者实际需要的可写能力。 --- ## 包含内容 ### 1. `enable-mcp-abilities` 一个10行的过滤器，标记每个注册的能力为MCP公开。**这是“公开标志”机制**，它对于理解安全边界非常重要，因为它是“注册”和“公开”之间的安全边界： ```php add_filter( 'wp_ability_meta', function( $meta, $name ) { if ( ! isset( $meta['mcp'] ) ) $meta['mcp'] = array(); $meta['mcp']['public'] = true; return $meta; }, 10, 2 ); ``` MCP适配器仅公开具有`meta.mcp.public = true`的能力。没有它的能力仍然在WordPress中注册，仍然可以从PHP调用，但对MCP客户端不可见。此插件为所有能力启用了该标志。如果您希望按能力启用，可以删除此插件并直接在特定的`wp_register_ability()`调用中添加元数据。 > **注意**：这里的“公开”意味着对MCP可见。每个能力仍然运行其自己的`permission_callback`（例如`current_user_can('edit_posts')`），因此连接的用户必须是具有正确权限的身份验证WP用户。公开 ≠ 未认证。 ### 2. `editorial-abilities` 二十种编辑能力，分为七个组： | 类别 | 能力 | |---|---| | **帖子** | `list-posts`、`get-post`、`create-post`、`update-post`、`delete-post` | | **页面** | `list-pages`、`get-page`、`create-page`、`update-page` | | **媒体** | `list-media` | | **站点设置** | `get-settings`、`update-settings` | | **自定义CSS** | `get-custom-css`、`set-custom-css` | | **页脚JS** | `get-footer-js`、`set-footer-js` | | **分类/主题** | `list-categories`、`list-tags`、`list-menus`、`get-theme-info`、`list-comments` | 每个能力都使用JSON模式进行输入验证，并在严格的权限回调下运行。 #### 页脚JS - 为什么存在 WordPress的`wp_kses_post()`会从帖子或页面内容中剥离`<script>`标签。这是正确的安全行为。但是，这意味着AI客户端无法仅通过编辑页面主体为页面添加交互行为。页脚JS能力通过在选项（`mcp_footer_js`）中存储JavaScript并通过`wp_footer`钩子在每个页面上注入来解决这个问题。 AI客户端获得了一个干净的读写界面，用于站点范围的JS，而无需绕过帖子净化器。 --- ## 安装 ### 先决条件 - WordPress **6.9+** （Abilities API在6.9中稳定） - 已安装并激活 [WordPress MCP适配器](https://wordpress.org/plugins/mcp-adapter/) 插件 ### 安装 1. 将两个插件文件夹放入 `wp-content/plugins/`： ``` wp-content/plugins/enable-mcp-abilities/ wp-content/plugins/editorial-abilities/ ``` 2. 在 `/wp-admin` 的插件部分激活它们。 3. 验证能力是否注册。从WP管理后台或通过WP-CLI： ```bash wp eval 'print_r( wp_get_abilities() );' ``` 您应该看到所有 `editorial/*` 能力都被列出。 ### 连接Claude 将MCP服务器添加到Claude配置（Claude Desktop，Claude Code或任何MCP客户端）。端点URL是MCP适配器公开的URL，通常是： ``` https://your-site.example.com/wp-json/mcp/v1 ``` 身份验证使用WordPress应用程序密码。有关当前连接格式，请参阅MCP适配器的文档。 --- ## 可用能力（完整参考） <details> <summary><strong>帖子</strong></summary> - `editorial/list-posts` — 带状态/搜索筛选的分页列表 - `editorial/get-post` — 通过ID获取帖子的完整内容 - `editorial/create-post` — 标题、内容、摘要、状态 - `editorial/update-post` — 通过ID部分更新 - `editorial/delete-post` — 软删除（移动到回收站） </details> <details> <summary><strong>页面</strong></summary> - `editorial/list-pages` - `editorial/get-page` - `editorial/create-page` — 支持parent_id和slug - `editorial/update-page` </details> <details> <summary><strong>媒体、设置、分类</strong></summary> - `editorial/list-media` — 按查询和MIME类型搜索 - `editorial/get-settings` / `editorial/update-settings` — 常见的站点选项（blogname、description、posts_per_page、timezone） - `editorial/list-categories`、`editorial/list-tags`、`editorial/list-menus`、`editorial/list-comments` - `editorial/get-theme-info` </details> <details> <summary><strong>自定义CSS</strong></summary> - `editorial/get-custom-css` — 返回活动主题的额外CSS - `editorial/set-custom-css` — 通过`wp_update_custom_css_post()`替换它 </details> <details> <summary><strong>页脚JavaScript</strong></summary> - `editorial/get-footer-js` — 读取存储的代码段 - `editorial/set-footer-js` — 替换存储的代码段（通过`wp_footer`渲染在每个页面上） </details> --- ## 架构和设计笔记 ### 钩子顺序 能力**必须**在`wp_abilities_api_init`钩子上注册，而不是`init`。类别必须在`wp_abilities_api_categories_init`钩子上注册。在错误的钩子上注册会静默失败 - 能力对MCP不可见，也不会出现错误。 ### 必需的类别字段 每个能力必须包含一个`'category' => '...'`键。在WP 6.9之前，这是一个软要求，6.9之后成为硬要求。缺少类别会导致注册静默失败。 ### 权限模型 每个能力都使用标准的WP权限检查： - 帖子：`edit_posts`、`publish_posts`、`delete_posts` - 页面：`edit_pages`、`publish_pages` - 媒体：`upload_files` - 设置：`manage_options` - CSS：`edit_css` - 页脚JS / 菜单 / 主题：`edit_theme_options` - 评论：`moderate_comments` 如果您以编辑者的身份连接MCP客户端，他们将获得编辑操作但无权访问站点设置。作为管理员，他们将获得所有功能。 ### `wp_kses_post` 和您 帖子和页面内容在输入时通过`wp_kses_post()`进行净化，这会剥离`<script>`、`<style>`、`<iframe>`和大多数数据属性。请围绕以下内容进行规划： - 全局JS通过`editorial/set-footer-js` - 全局CSS通过`editorial/set-custom-css` - 帖子内容中的内联SVG被剥离 - 而是使用`<img src="...">`并将SVG托管在`/wp-content/uploads/`中 --- ## 示例交互 连接后，AI客户端可以执行以下操作： ``` "列出我的最后5个草稿帖子。" "更新帖子142 - 将标题更改为'我如何在2026年建立了我的投资组合'并发布它。" "用以下CSS块替换站点的自定义CSS：[...]" "添加此JavaScript到页脚以启用平滑滚动：[...]" "创建一个名为'Now'的新页面，内容如下：[...]" ``` --- ## 扩展 要添加您自己的能力，请在`wp_abilities_api_init`钩子上注册它们，使用新或现有的类别，它们将自动通过MCP公开（`enable-mcp-abilities`插件为您处理公开标志）： ```php add_action( 'wp_abilities_api_init', function() { wp_register_ability( 'mything/do-something', array( 'label' => '执行某事', 'description' => '执行一些有用的操作。', 'category' => 'editorial', 'input_schema' => array( 'type' => 'object', 'required' => array( 'name' ), 'properties' => array( 'name' => array( 'type' => 'string' ), ), ), 'permission_callback' => function() { return current_user_can( 'edit_posts' ); }, 'execute_callback' => function( $args ) { return array( 'message' => 'Hello, ' . $args['name'] ); }, ) ); } ); ``` --- ## 致谢和荣誉 **本项目建立在：** - [模型上下文协议](https://modelcontextprotocol.io/) - Anthropic的开放规范，定义了AI客户端如何与外部工具通信。 - [WordPress MCP适配器](https://wordpress.org/plugins/mcp-adapter/) - 实际上通过MCP公开WordPress的插件。本项目在适配器的基础上添加了可写的编辑能力；适配器处理身份验证、模式验证和HTTP传输。 - WordPress能力API（WordPress 6.9+中的核心）- 能力插件入驻的底层注册、权限和执行层。 如果没有这三个组件，什么都不会实现。应有的荣誉归于它们。 **关于实现：** 该插件与[Claude](https://claude.ai)（Anthropic的AI助手）合作开发 - 考虑到Claude是本插件设计的MCP客户端之一。该存储库中的PHP代码由Claude在我的指导下编写。我做出了架构决策（公开哪些20种能力，如何组织它们，七类别结构），调试了出现的问题（`wp_abilities_api_init`钩子顺序陷阱，WP 6.9类别要求，`wp_kses_post`从帖子内容中剥离`<script>`标签 - 这导致了页脚JS变通方法），审查和测试了每个更改，部署并公开了源代码。 这种协作模式在2026年越来越多地用于软件开发。我宁愿透明地说明，而不是假装不是这样 - 而且实际上，这个项目中有趣的工作是设计、调试和集成，而不是打字。 **生产环境中使用：** [brodykretz.com](https://brodykretz.com)投资组合站点完全通过此插件进行编辑 - 页面、帖子、自定义CSS、页脚JS等。如果您访问它，您会看到这些20种能力的输出。 --- ## 许可证 MIT - 请参阅 [`LICENSE`](LICENSE)。 ## 贡献 欢迎提出问题和PR。插件故意保持小巧且无依赖；请保持这一特性。