abilities-catalog

# 能力目录 **能力目录为WordPress代理提供了两个相互需要的大规模功能：一个庞大的wp-admin能力目录和一个基于搜索的MCP服务器，允许代理在不需要加载整个目录的情况下使用它。** 目录在WordPress能力API上注册了230+个WordPress核心管理操作。每个能力都有模式、类别元数据、服务器端能力检查和风险注释。 搜索MCP服务器通过一个高效的端点将这些能力暴露给代理。代理描述任务，获取一个小型排名结果集，读取所选能力的确切模式，然后在服务器端执行它。代理不需要预先列出数百或数千个工具。 这两个部分在这个插件中同样重要： - **目录** 定义了WordPress可以执行的操作。 - **搜索MCP服务器** 使该能力在目录跨核心和插件增长时对代理来说是实用的。 MCP服务器是可选的，默认情况下是关闭的。目录仍然在能力API上注册，供任何读取该API的消费者使用。然而，对于MCP客户端，搜索服务器是预期的可扩展表面。 ## 快速入门 通过四个步骤将MCP客户端连接到您的站点： 1. 安装并激活能力目录。 使用来自 [发布页面](https://github.com/galatanovidiu/abilities-catalog/releases) 的发布ZIP包，并像安装其他WordPress插件一样安装它。 如果您是从git检出运行的，请在插件目录中运行 `composer install` ，然后再启用MCP服务器。发布ZIP包已经包含所需的 `vendor/` 文件。 2. 启用MCP服务器。在 `wp-config.php` 中添加以下内容： ```php define( 'ABILITIES_CATALOG_MCP_ENABLED', true ); ``` 您也可以在 **设置 -> MCP服务器** 处使用切换开关。 3. 在 **用户 -> 配置文件 -> 应用程序密码** 处创建一个应用程序密码。WordPress需要HTTPS来创建它。 4. 将您的MCP客户端指向： ```text https://您的站点/wp-json/abilities-catalog/v1/mcp-search ``` 使用您的WordPress用户名和应用程序密码进行身份验证。 每个能力都以MCP执行禁用状态启动。在 **设置 -> MCP服务器** 处启用代理所需的能力。 ## 要求 - WordPress 6.9 或更高版本，核心中包含能力API。 - PHP 8.1 或更高版本。 ## 目录注册内容 核心目录包括 230+ 个能力，涵盖 21 个 wp-admin 区域： `评论`, `连接器`, `内容`, `Cron`, `仪表盘`, `字体`, `媒体`, `菜单`, `网络`, `插件`, `隐私`, `搜索`, `设置`, `站点健康`, `模板`, `术语`, `主题`, `工具`, `更新`, `用户`, `小部件`. 每个能力都是 `includes/Abilities/Core/<Domain>/` 下的一个PHP类。`Registry` 递归发现这些类并使用 `wp_register_ability()` 将它们注册。 能力名称使用 `domain/verb-noun` 格式，例如： - `og-plugins/list-plugins` - `og-comments/approve-comment` - `og-content/create-post` 每个能力都声明： - 输入模式和输出模式； - 类别； - 服务器端 `permission_callback` ； - 风险注释，如 `readonly` 、 `destructive` 、 `idempotent` 和 `dangerous` 。 ## 插件 插件在同一个能力API上注册它们自己的能力。当启用搜索MCP服务器时，这些能力可以通过与核心能力相同的端点出现。代理不需要为每个插件提供单独的服务器。 当前插件： - [abilities-catalog-woo](https://github.com/galatanovidiu/abilities-catalog-woo)：WooCommerce商店操作。 - [abilities-catalog-yoast-seo](https://github.com/galatanovidiu/abilities-catalog-yoast-seo)：Yoast SEO。 - [abilities-catalog-cf7](https://github.com/galatanovidiu/abilities-catalog-cf7)：Contact Form 7表单。 这些是单独的插件，不是核心目录的一部分。 参见 [构建插件](docs/building-add-ons.md) 以获取扩展模式。 ## 为什么基于搜索的MCP存在 WordPress能力API提供了一种标准的方法来描述可执行的能力。这为MCP创建了一个规模问题：一个真正的站点可能有数百种来自核心、WooCommerce、SEO、表单、会员资格、备份和自定义业务插件的能力。 列出每个能力作为MCP工具并不具备可扩展性。它在代理执行任何工作之前都会消耗上下文，并且成本随着目录大小的增加而增长。 搜索MCP服务器保持MCP表面小且固定。发现过程变为： 1. 获取站点功能的紧凑概述。 2. 用普通语言搜索任务。 3. 描述一个匹配的能力。 4. 执行该能力。 结果集是有界的。目录可以增长而不会将MCP发现变成工具转储。 ## 搜索MCP服务器 搜索服务器基于 [`wordpress/mcp-adapter`](https://github.com/WordPress/mcp-adapter) 构建，并在启用时注册此端点： ```text /wp-json/abilities-catalog/v1/mcp-search ``` 它暴露了五个工具： - **`overview`** - 返回一个紧凑的能力映射：类别、标签、描述、能力计数、启用计数和每个类别的几个示例。 - **`search-abilities`** - 通过普通语言任务描述搜索实时能力注册。结果包括能力名称、标签、描述、类别、紧凑输入签名、安全注释以及能力是否启用MCP执行。 - **`describe-ability`** - 返回一个确切的能力名称的完整输入/输出模式和元数据。 - **`execute-ability`** - 在 `input` 下使用参数运行一个确切的能力名称。 - **`knowledge`** - 提供基于文件的OKF概念包：任务配方、创作指南和代理的实时站点事实。 `knowledge` 工具是实验性的。这是此插件的文件基桥，直到WordPress在核心中有官方的 `wp-knowledge` 标准。它允许代理读取任务配方和创作指南而不是猜测。 通常的代理循环是： ```text overview -> search-abilities -> describe-ability -> execute-ability ``` 发现显示禁用的能力，以便代理可以了解存在什么。执行在站点管理员在 **设置 -> MCP服务器** 处启用能力之前无法运行。 ## 其他MCP表面 当启用MCP服务器时，此插件具有多个MCP表面。它们服务于不同的目的。 ### 搜索服务器 端点： ```text /wp-json/abilities-catalog/v1/mcp-search ``` 这是代理的推荐服务器。它是用于大型目录和插件的可扩展表面。 ### 精选域服务器 端点： ```text /wp-json/abilities-catalog/v1/mcp ``` 此旧服务器为每个精选域公开一个工具。每个域工具都支持 `list` 、 `describe` 和 `execute` 。 它对于核心目录来说是有用的且易于阅读，但它依赖于维护的域分类法，并且随着任意插件添加数百或数千种能力，它变得不那么有吸引力。对于新客户端，优先使用搜索服务器。 ### 适配器默认服务器 捆绑的适配器也有自己的默认服务器。在此插件中，只有精选和所有者启用的能力被标记为该默认表面的公共能力。这保持了暴露门的完整性，但它仍然不是首选的大目录工作流程。 当代理需要高效地处理整个目录时，请使用搜索服务器。 ## 连接客户端 大多数桌面MCP客户端可以通过 [`@automattic/mcp-wordpress-remote`](https://www.npmjs.com/package/@automattic/mcp-wordpress-remote) 连接。 示例配置： ```json { "mcpServers": { "wordpress": { "command": "npx", "args": [ "-y", "@automattic/mcp-wordpress-remote@latest" ], "env": { "WP_API_URL": "https://您的站点/wp-json/abilities-catalog/v1/mcp-search", "WP_API_USERNAME": "您的用户名", "WP_API_PASSWORD": "您的应用程序密码" } } } } ``` 支持远程MCP服务器的客户端可以直接使用以下方式调用端点： ```text Authorization: Basic <base64 of "username:application-password"> ``` 端点作为经过身份验证的WordPress用户运行。因此，WordPress能力检查是按用户进行的，就像wp-admin一样。 ## 安全 安全有两层： - 能力检查。 - MCP暴露门。 ### 能力检查 能力是硬性防护。每个能力都有一个服务器端 `permission_callback` ，调用 `current_user_can()` 。这在每次执行时运行，独立于任何MCP客户端或UI。 ### 风险注释 风险注释为消费者分类能力。它们是元数据，而不是权限系统。 - **只读**：无副作用。声明 `readonly: true` 。 - **写入**：更改数据但不删除它。声明 `readonly: false` 和 `destructive: false` 。 - **破坏性**：删除、放入回收站或永久删除数据。声明 `destructive: true` 。 - **危险**：可以安装、更新或删除插件和主题，运行更新，写入广泛的选项或触发隐私导出。声明 `dangerous: true` 并在专用防护后面运行。 注册拒绝模糊的写入能力。写入能力必须显式设置 `annotations.destructive` 为布尔值。 ### MCP暴露门 MCP服务器默认关闭。启用后，每个能力仍然被禁用，直到管理员启用它。 发现可以显示禁用的能力。执行不能运行它们。 每次MCP执行都会运行两个检查： 1. MCP暴露门必须允许该能力。 2. 身份验证的WordPress用户必须通过能力检查。 > [!WARNING] > MCP客户端充当经过身份验证的WordPress用户。如果您启用写入、破坏或危险能力，客户端可以进行实际更改。在启用高风险能力之前备份站点，并仅启用代理所需的能力。例如，启用 `og-plugins/install-plugin` 允许经过身份验证的管理员通过MCP安装可执行代码。 ## 危险能力防护 危险能力在 `includes/Support/` 下使用额外的支持代码。例如： - 文件系统检查； - 插件和主题安装的wp.org源验证； - 选项允许列表； - 升级器锁定。 核心更新执行和不可逆转的擦除执行被故意排除。 ## 未来发展 这个插件是一个工作桥梁，而WordPress核心和插件正在发展自己的官方能力。 随着官方能力的出现，应删除此目录中的重复项。目录应为核心和插件拥有的定义腾出空间，而不是与它们竞争。 搜索服务器也是 `wordpress/mcp-adapter` 的候选上游，因为有界搜索是大规模WordPress能力目录的实用发现模型。 ## 架构 ```text abilities-catalog/ abilities-catalog.php # 插件头，PSR-4 自动加载，引导 includes/ Registry.php # 发现，分类和注册能力 Contracts/ # 能力提供者和类别提供者合约 Abilities/<Group>/<Domain>/ # 每个能力一个类 Support/ # 危险能力的防护 Mcp/ # 可选的MCP服务器和搜索索引 Admin/ # 设置页面和REST API assets/js/ # 无构建的React设置应用 docs/ # 面向用户的文档 tests/phpunit/ # 单元和集成测试 ``` `GalatanOvidiu\AbilitiesCatalog\` 映射到 `includes/` 。 ## 开发 主机上运行静态检查： ```bash composer lint composer phpstan ``` 通过 `wp-env` 在Docker中运行测试： ```bash npm run wp-env:test start npm run test:php:setup npm run test:php ``` ## 贡献 能力目录是一个开源项目。欢迎在 [GitHub问题跟踪器](https://github.com/galatanovidiu/abilities-catalog/issues) 上报告错误、建议和问题。 也欢迎拉取请求。 ## 许可证 MIT。参见 [LICENSE](LICENSE)。