History

WenPai Translation Bot 15fd1d68d0 docs: add 260 translated files		2026-03-09 19:53:58 +08:00
..
README.md	docs: add 260 translated files	2026-03-09 19:53:58 +08:00

README.md

title

post_status

comment_status

taxonomy

Model Context Protocol (MCP) 集成

publish

open

Model Context Protocol (MCP) 集成

简介

WooCommerce 提供了对 Model Context Protocol (MCP) 的原生支持，这使得 AI 助手和工具能够通过一种标准化的协议直接与 WooCommerce 商店进行交互。这种集成将 WooCommerce 的功能暴露为可发现的工具，AI 客户端可以使用这些工具在具有适当的身份验证和权限的情况下执行商店操作。

:::info

开发者预览通知 WooCommerce 中 MCP 的实现目前处于开发者预览阶段。随着该功能的成熟，实施细节、API 和集成模式可能会在未来的版本中发生变化。

:::

背景

Model Context Protocol (MCP) 是一种开放标准，它允许 AI 应用程序安全地连接到外部数据源和工具。 WooCommerce 的 MCP 集成建立在两个核心技术之上：

WordPress Abilities API - 一个在 WordPress 中注册功能的标准化系统
WordPress MCP Adapter - 核心 MCP 协议的实现

这种架构允许 WooCommerce 通过灵活的 WordPress Abilities 系统将操作暴露为 MCP 工具，同时保持现有的安全和权限模型。

可用功能

WooCommerce 的 MCP 集成为 AI 助手提供了对核心商店操作的结构化访问：

产品管理

带有过滤和分页的产品列表
检索详细的产品信息
创建新产品
更新现有产品
删除产品

订单管理

带有过滤和分页的订单列表
检索详细的订单信息
创建新订单
更新现有订单

所有操作都遵循 WooCommerce 现有的权限系统，并使用 WooCommerce REST API 密钥进行身份验证。

:::warning

数据隐私声明 订单和客户操作可能会暴露个人可识别信息 (PII)，包括姓名、Email 地址、物理地址和支付详情。您有责任确保符合适用的数据保护法规。使用最小权限的 API 范围，定期轮换和撤销 REST API 密钥，并遵循您组织的的数据保留和处理政策。

:::

架构

数据流概述

MCP 集成使用多层架构来连接 MCP 客户端和 WordPress：

AI 客户端 (Claude, etc.)
    ↓ (通过 stdio/JSON-RPC 的 MCP 协议)
本地 MCP 代理 (mcp-wordpress-remote)
    ↓ (带有身份验证的 HTTP/HTTPS 请求)
远程 WordPress MCP 服务器 (mcp-adapter)
    ↓ (WordPress Abilities API)
WooCommerce Abilities
    ↓ (REST API 调用或直接操作)
WooCommerce 核心

架构组件

本地 MCP 代理 (mcp-wordpress-remote)

在开发者的机器上作为 Node.js 进程运行
将 MCP 协议消息转换为 HTTP 请求
处理身份验证头注入
弥合 MCP 客户端和 WordPress REST 端点之间的协议差距

远程 WordPress MCP 服务器 (mcp-adapter)

作为插件在 WordPress 中运行
暴露 /wp-json/woocommerce/mcp 端点
处理传入的 HTTP 请求，并将其转换为 MCP 协议消息
管理工具发现和执行

WordPress 能力系统

提供了一种标准化的注册和执行能力的机制
作为 MCP 工具和实际操作之间的抽象层
允许灵活的实现方法（REST 桥接、直接数据库操作等）

核心组件

MCP 适配器提供者 (MCPAdapterProvider.php)

管理 MCP 服务器的初始化和配置
处理特性标志检查 (mcp_integration)
提供能力过滤和命名空间管理

能力注册表 (AbilitiesRegistry.php)

集中管理 WooCommerce 能力的注册
将 WordPress 能力 API 与 WooCommerce 操作连接
启用 MCP 服务器的能力发现

REST 桥接实现 (AbilitiesRestBridge.php)

当前的预览实现，它将 REST 操作映射到 WordPress 能力
提供明确的能力定义，以及产品和订单的结构化数据
演示了如何使用现有的 REST 控制器来实现能力

WooCommerce 传输层 (WooCommerceRestTransport.php)

处理 WooCommerce API 密钥身份验证
强制执行 HTTPS 要求
根据 API 密钥范围验证权限

实现方法

对于此开发预览版，WooCommerce 能力是通过桥接现有的 REST API 端点来实现的。这种方法允许我们快速暴露核心功能，同时利用成熟的 REST 控制器。但是，WordPress 能力 API 旨在具有灵活性 - 能力可以通过多种方式实现，而不仅仅是通过 REST 端点代理，包括直接数据库操作、自定义业务逻辑或与外部服务的集成。

启用 MCP 集成

MCP 功能由 mcp_integration 功能标志控制。您可以编程方式启用它：

add_filter( 'woocommerce_features', function( $features ) {
    $features['mcp_integration'] = true;
    return $features;
});

或者，您可以通过 WooCommerce CLI 启用它：

wp option update woocommerce_feature_mcp_integration_enabled yes

身份验证和安全

API 密钥要求

MCP 客户端使用 WooCommerce REST API 密钥，通过 X-MCP-API-Key 头部进行身份验证：

X-MCP-API-Key: ck_your_consumer_key:cs_your_consumer_secret

要创建 API 密钥：

导航到 WooCommerce → 设置 → 高级 → REST API
点击 添加密钥
设置适当的权限 (read, write, 或 read_write)
生成并安全地存储消费者密钥和密钥

HTTPS 强制

默认情况下，MCP 请求需要 HTTPS。对于本地开发，您可以禁用此要求：

add_filter( 'woocommerce_mcp_allow_insecure_transport', '__return_true' );

权限验证

传输层会根据 API 密钥的权限验证操作：

read 权限：允许 GET 请求
write 权限：允许 POST, PUT, PATCH, DELETE 请求
read_write 权限：允许所有操作

服务器端点

WooCommerce MCP 服务器位于：

https://yourstore.com/wp-json/woocommerce/mcp

连接到 MCP 服务器

代理架构

当前的 MCP 实现使用 本地代理方法，将 MCP 客户端与 WordPress 服务器连接起来：

MCP 客户端（例如 Claude Code）使用 MCP 协议通过 stdio/JSON-RPC 进行通信
本地代理 (@automattic/mcp-wordpress-remote) 运行在您的机器上，并将 MCP 协议消息转换为 HTTP 请求
WordPress MCP 服务器 接收 HTTP 请求，并通过 WordPress Abilities 系统处理它们

这种代理模式通常用于 MCP 集成，以弥合协议差异并处理身份验证。mcp-wordpress-remote 包充当协议转换器，将客户端期望的基于 stdio 的 MCP 通信转换为 WordPress 理解的 HTTP REST API 调用。

未来发展: 虽然这种代理方法提供了坚实的基础，但未来的实现可能会探索在 WordPress 中直接支持 MCP 协议或作为 MCP 生态系统发展的替代连接方法。

Claude Code 集成

要将 Claude Code 连接到您的 WooCommerce MCP 服务器：

转到 WooCommerce → 设置 → 高级 → REST API
创建一个具有 "读/写" 权限的新 API 密钥
使用 Claude Code 配置 MCP，并使用您的 API 密钥：

claude mcp add woocommerce_mcp \
  --env WP_API_URL=https://yourstore.com/wp-json/woocommerce/mcp \
  --env CUSTOM_HEADERS='{"X-MCP-API-Key": "YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET"}' \
  -- npx -y @automattic/mcp-wordpress-remote@latest

手册：MCP 客户端配置

对于其他 MCP 客户端，请将以下配置添加到您的 MCP 设置中。此配置指示 MCP 客户端在本地运行 mcp-wordpress-remote 代理，该代理将处理与您的 WordPress 服务器的通信：

{
  "mcpServers": {
    "woocommerce_mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@automattic/mcp-wordpress-remote@latest"
      ],
      "env": {
        "WP_API_URL": "https://yourstore.com/wp-json/woocommerce/mcp",
        "CUSTOM_HEADERS": "{\"X-MCP-API-Key\": \"YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET\"}"
      }
    }
  }
}

重要提示: 将 YOUR_CONSUMER_KEY:YOUR_CONSUMER_SECRET 替换为您的实际 WooCommerce API 凭据。

故障排除: 如果在本地环境中遇到与 npx 版本或 SSL 相关的常见设置问题，请参阅 mcp-wordpress-remote 故障排除指南。

扩展 MCP 功能

添加自定义功能

第三方插件可以使用 WordPress Abilities API 注册额外的功能。功能可以通过多种方式实现，例如 REST 接口桥接、直接操作、自定义逻辑或外部集成。以下是一个基本示例：

add_action( 'abilities_api_init', function() {
    wp_register_ability(
        'your-plugin/custom-operation',
        array(
            'label'       => __( '自定义商店操作', 'your-plugin' ),
            'description' => __( '执行自定义商店操作。', 'your-plugin' ),
            'execute_callback' => 'your_custom_ability_handler',
            'permission_callback' => function () {
                return current_user_can( 'manage_woocommerce' );
            },
            'input_schema' => array(
                'type' => 'object',
                'properties' => array(
                    'store_id' => array(
                        'type' => 'integer',
                        'description' => '商店标识符'
                    )
                ),
                'required' => array( 'store_id' )
            ),
            'output_schema' => array(
                'type' => 'object',
                'properties' => array(
                    'success' => array(
                        'type' => 'boolean',
                        'description' => '操作结果'
                    )
                )
            )
        )
    );
});

将自定义功能包含在 WooCommerce MCP 服务器中

默认情况下，只有 woocommerce/ 命名空间的才能包含功能。要包含来自其他命名空间的，请执行以下操作：

add_filter( 'woocommerce_mcp_include_ability', function( $include, $ability_id ) {
    if ( str_starts_with( $ability_id, 'your-plugin/' ) ) {
        return true;
    }
    return $include;
}, 10, 2 );

开发示例

要了解完整的可运行示例，请参阅 WooCommerce MCP Ability Demo Plugin。此演示插件展示了第三方开发者如何：

使用 WordPress Abilities API 注册自定义能力
定义全面的输入和输出结构化数据
实现适当的权限处理
与 WooCommerce MCP 服务器集成

该演示插件创建了一个 woocommerce-demo/store-info 能力，用于检索商店信息和统计数据，展示了扩展 WooCommerce MCP 功能的集成模式，同时采用直接实现方法，而不是 REST 接口桥接。

故障排除

常见问题

MCP 服务器不可用

验证 mcp_integration 功能标志是否已启用
检查 MCP 适配器是否已正确加载
检查 WooCommerce 日志以查找初始化错误

身份验证失败

确认 API 密钥格式：consumer_key:consumer_secret
验证 API 密钥的权限是否与操作要求匹配
确保使用 HTTPS 或明确允许用于开发

能力未找到

确认在 abilities_api_init 期间注册了能力
使用 woocommerce_mcp_include_ability 过滤器检查命名空间是否包含
验证能力回调是否可访问

请检查 WooCommerce → 状态 → 日志，查找源为 woocommerce-mcp 的条目。

重要注意事项

开发者预览版: 此功能处于预览状态，可能会发生更改
实现方法: 当前能力使用 REST 接口桥接作为预览实现
破坏性更改: 未来的更新可能会引入破坏性更改
生产环境测试: 在部署到生产环境之前，请进行彻底的测试
API 稳定性: WordPress Abilities API 和 MCP 适配器正在不断发展

README.md

Model Context Protocol (MCP) 集成

简介

背景

可用功能

产品管理

订单管理

架构

数据流概述

架构组件

WordPress 能力系统

核心组件

实现方法

启用 MCP 集成

身份验证和安全

API 密钥要求

HTTPS 强制

权限验证

服务器端点

连接到 MCP 服务器

代理架构

Claude Code 集成

手册：MCP 客户端配置

扩展 MCP 功能

添加自定义功能

将自定义功能包含在 WooCommerce MCP 服务器中

开发示例

故障排除

常见问题

MCP 服务器不可用

身份验证失败

能力未找到

重要注意事项

相关资源

菲码源库

快速导航

产品服务

生态伙伴

README.md Unescape Escape

Model Context Protocol (MCP) 集成

简介

背景

可用功能

产品管理

订单管理

架构

数据流概述

架构组件

WordPress 能力系统

核心组件

实现方法

启用 MCP 集成

身份验证和安全

API 密钥要求

HTTPS 强制

权限验证

服务器端点

连接到 MCP 服务器

代理架构

Claude Code 集成

手册：MCP 客户端配置

扩展 MCP 功能

添加自定义功能

将自定义功能包含在 WooCommerce MCP 服务器中

开发示例

故障排除

常见问题

MCP 服务器不可用

身份验证失败

能力未找到

重要注意事项

相关资源

菲码源库

快速导航

产品服务

生态伙伴

README.md