MCP woo

MCP WooCommerce服务器

模型上下文协议（MCP）服务器，提供与WooCommerce REST API交互的工具。

特性

• 搜索产品：按名称或SKU搜索产品
• 产品列表：检索所有带分页的产品
• 创建订单：使用行项目创建新订单
• 获取订单：按ID检索特定订单
• 列出订单：列出带有可选筛选器的订单
• 🔐 认证：API基于密钥的身份验证，用于安全访问

设置

1. 克隆此存储库

1. 复制 .env.example 到 .env 并填写您的WooCommerce API证书：

   WOO_URL=https://yourstore.com
   WOO_CONSUMER_KEY=your_consumer_key
   WOO_CONSUMER_SECRET=your_consumer_secret
   MCP_API_KEY=your_secure_api_key_here

1. 获取您的WooCommerce API证书：

- 前往WooCommerce>设置>高级>REST API - 创建具有读/写权限的新密钥 - 复制消费者密钥和消费者秘密

1. 为MCP身份验证生成一个安全的API密钥：

   # Generate a random API key (Linux/Mac)
   openssl rand -hex 32

   # Or use Python
   python -c "import secrets; print(secrets.token_hex(32))"

安全

认证

服务器实现 API密钥验证 以防止未经授权的访问。当 MCP_API_KEY 如果已配置，则所有请求都必须在 Authorization 头球

无身份验证（仅用于开发）

如果 MCP_API_KEY 如果未设置，出于开发目的，服务器将在没有身份验证的情况下运行。

带身份验证（建议生产）

当 MCP_API_KEY 如果已设置，客户端必须包括：

Authorization: Bearer YOUR_API_KEY_HERE

安全最佳实践

• 始终设置 MCP_API_KEY 在生产环境中
• 使用随机生成的强API密钥（32个字符以上）
• 定期旋转API键
• 在生产环境中使用HTTPS
• 仅将网络访问限制在可信来源
• 监控访问日志中的可疑活动

本地运行

使用Docker Compose

docker-compose up --build

服务器将于启动 http://localhost:8200/mcp 采用模块化架构。

使用Python

pip install -r requirements.txt
python -m src.server

建筑

该项目采用模块化架构，结构如下：

• src/server.py -具有MCP集成和身份验证的FastAPI应用程序
• src/tools.py -MCP工具实施（WooCommerce运营的5个工具）
• src/config.py -环境配置和验证
• src/woo_client.py -WooCommerce API客户端包装器
• src/models.py -结构化数据的Pydantic模型
• test/client_authenticated.py -全功能认证MCP客户端（推荐）
• test/client_example.py -使用官方库的基本MCP客户端（有限的身份验证支持）
• test/list_tools.py -简单的工具列表脚本

客户端兼容性矩阵

¹ *有限支持：当需要API密钥时，可能会因身份验证错误而失败*

API终点

服务器公开了以下MCP工具：

• search_products(query: str, per_page: int = 10) -搜索产品
• list_products(per_page: int = 20, page: int = 1) -列出所有产品
• create_order(customer_id: int, line_items: List[Dict], billing: Dict, shipping: Optional[Dict]) -创建订单
• get_order(order_id: int) -获取特定订单
• list_orders(customer_id: Optional[int], status: Optional[str], per_page: int = 10) -列出订单

WooCommerce API要求

• WooCommerce 3.5+
• WordPress 4.4+
• 启用了漂亮的永久链接
• 已启用REST API（默认）

测试MCP服务器

使用示例客户端

该项目包括测试服务器的示例MCP客户端：

经过身份验证的客户端（推荐）

python test/client_authenticated.py

这是 推荐客户 用于测试。它提供：

• ✅ 完全支持API密钥身份验证
• ✅ 正确的SSE响应解析
• ✅ 完成工具测试（列出产品、搜索产品等）
• ✅ 带有产品信息的详细输出
• ✅ 错误处理和会话管理

简单工具列表器

python test/list_tools.py

此脚本连接到MCP服务器，并列出所有可用工具及其描述和参数。

基本示例客户端（有限）

python test/client_example.py

此客户端使用官方MCP库，但有局限性：

• ❌ 有限的身份验证支持（API密钥身份验证可能失败）
• ❌ 可能会遇到与经过身份验证的服务器的连接错误
• ✅ 有助于理解MCP协议结构

测试脚本

该项目包括curl脚本，便于测试：

# Update the AUTH_HEADER in the scripts with your API key
# Then run:
./test/curl_list_products.sh
./test/curl_search_products.sh pulseras
./test/curl_create_order.sh

这些脚本演示了正确的身份验证和SSE响应处理。

认证测试

# Run authentication tests
./test/test_auth.sh

此脚本通过测试不同的场景来验证身份验证是否正常工作。

数据摄入示例

该项目包括从MCP服务器获取产品数据的示例脚本：

Bash脚本（推荐用于自动化）

# Run the ingestion script
./ingestion_example.sh

此脚本演示了MCP请求的正确格式并处理SSE响应。

Python 脚本

# Activate virtual environment and run
source .venv/bin/activate
python ingestion_example.py

这个Python客户端展示了如何通过适当的错误处理以编程方式摄取数据。

MCP请求格式

在构建自己的摄取脚本时，使用此格式可以避免406错误：

# 1. Initialize session (required)
curl -X POST http://localhost:8200/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "ingestion-client", "version": "1.0.0"}}}'

# 2. Call tools with session ID
curl -X POST http://localhost:8200/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "list_products", "arguments": {"per_page": 50}}}'

重要标题：

• Content-Type: application/json
• Accept: application/json, text/event-stream
• Authorization: Bearer YOUR_API_KEY
• Mcp-Session-Id: YOUR_SESSION_ID （初始化后）