此指南适用于开发环境或通过Git管理的生产环境。Docker环境可用。

核心概念

MCP Adapter既可以作为Composer库被其他插件引用（推荐），也可以作为独立插件运行。

• 依赖管理：该插件不包含vendor目录（第三方库），必须在本地通过Composer生成。
• 运行环境：需要PHP 7.4+和WordPress 6.8+。

首次安装流程

步骤A：下载源码

进入WordPress的插件目录并克隆仓库：

cd /path/to/wp-content/plugins/
git clone https://github.com/WordPress/mcp-adapter.git
cd mcp-adapter

步骤B：安装依赖

此步骤用于生成vendor/autoload.php文件。若跳过此步，插件将无法运行。

Docker环境下的命令：

docker run --rm \
    -v $(pwd):/app \
    composer install

会下载wordpress/abilities-api等核心依赖并生成自动加载映射。

步骤C：激活插件

# 使用 WP-CLI 或在后台激活
wp plugin activate mcp-adapter

HTTPS协议一致性

配置WP_API_URL时，必须严格匹配站点的实际协议。

• ❌ 错误做法：站点强制 HTTPS，但填写http://yousite.com/...
• ✅ 正确做法：填写https://yousite.com/...

如果站点强制使用 HTTPS（生产环境标准配置），而在配置中填写了http://，WordPress或服务器（Nginx/Apache）会返回一个301 Redirect跳转到HTTPS。在这个跳转过程中，出于安全规范，客户端发送的Authorization标头（包含密码）通常会被丢弃。这将导致请求虽然到达了最终地址，但因丢失凭据而报401 Unauthorized错误。

后续更新流程

由于插件通过Git安装，勿使用WordPress后台的“更新”按钮，以免覆盖Git配置。应按照以下步骤进行更新：

第一步：同步代码

获取最新的功能和修复：

cd /path/to/wp-content/plugins/mcp-adapter
git pull origin trunk

第二步：同步依赖

代码更新可能包含依赖包版本的变化（composer.lock变更）。每次git pull后运行：

docker run --rm \
    -v $(pwd):/app \
    composer install

如果跳过此步，可能会因为缺少新引入的类文件导致网站出现Fatal Error。

常见问题

• Plugin could not be activated (Fatal Error):
  • 原因：忘记执行composer install，导致vendor/autoload.php缺失。
  • 解决：重新执行安装流程中的步骤B。
• 类名冲突:
  • 原因：如果有多个插件都使用了MCP Adapter。
  • 解决：文档建议使用Jetpack Autoloader来解决多版本冲突（composer require automattic/jetpack-autoloader），但在单插件模式下非必须。
• API 404 错误:
  • 解决：确保WordPress的固定链接（Permalinks）设置不是“朴素 (Plain)”，需要设置为“文章名 (Post name)”或其他结构。
• API 401 错误 (Unauthorized):
  • 现象：MCP error -32603: WordPress API error (401)，且确认密码无误。
  • 解决：检查mcp.json中的WP_API_URL是否误写为了http://。将其修改为https://以避免重定向导致的凭据丢失。