Tiendanube MCP服务器-Docker设置
一个完整的模型上下文协议(MCP)服务器,用于Tiendanube/Nuvmshop API,支持Docker和SSE传输。
🚀 特性
资源
- 产品:具有高级过滤功能的完整CRUD(库存、价格、类别、SKU)
- 订单:完整的订单管理和历史跟踪
- 客户:客户管理,包括地址和账单
- 分类:类别层次结构管理
- 优惠券:优惠券管理
- 商店:存储信息和设置
运输方式
- ✅ SSE(服务器发送事件) -对于基于web的客户端
- ✅ 流式HTTP -现代HTTP传输
- ✅ 工作室 -用于CLI/终端使用
📋 先决条件
- Docker和Docker Compose
- Tiendanube API证书:
- 访问令牌
- 店铺ID
🔧 设置
1.克隆或创建项目结构```bash
mkdir tiendanube-mcp
cd tiendanube-mcp
创建以下文件:
- `tiendanube_server.py` (主服务器代码)
- `Dockerfile`
- `docker-compose.yml`
- `requirements.txt`
- `.env` (从 `.env.example`)
### 2.配置环境变量
创建 `.env` 文件:```env
TIENDANUBE_ACCESS_TOKEN=your_access_token_here
TIENDANUBE_STORE_ID=your_store_id_here
TIENDANUBE_BASE_URL=https://api.tiendanube.com/v1
# Server Configuration
MCP_TRANSPORT=sse
MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=INFO
3.构建和运行```bash
Build the Docker image
docker-compose build
Start the server
docker-compose up -d
View logs
docker-compose logs -f
Stop the server
docker-compose down
## 🌐 访问服务器
### 苏格兰和南方能源公司运输(默认)```
URL: http://localhost:8080/sse
可流式HTTP传输
改变 .env:```env
MCP_TRANSPORT=streamable-http
``````
URL: http://localhost:8080/mcp
## 🔍 健康检查```bash
curl http://localhost:8080/health
📊 API终点
产品
list_products-使用过滤器列出/搜索产品get_product-按ID获取产品get_product_by_sku-按SKU获取产品create_product-创建具有变体的新产品update_product-更新产品信息delete_product-删除产品update_product_stock_price-批量更新库存/价格
订单
list_orders-使用筛选器列出订单get_order-获取订单详细信息get_order_history_values-获取值更改历史记录get_order_history_editions-获取版本更新日志create_order-创建新订单update_order-更新订单close_order-关闭订单open_order-重新打开订单cancel_order-取消订单
客户
list_customers-列出/搜索客户get_customer-获取客户详细信息create_customer-创建新客户update_customer-更新客户delete_customer-删除客户
分类
list_categories-列出所有类别get_category-获取类别详细信息create_category-创建类别update_category-更新类别delete_category-删除类别
优惠券
list_coupons-列出所有优惠券get_coupon-获取优惠券详细信息create_coupon-创建折扣券
商店
get_store-获取店铺信息
🎯 用法示例
从Python客户端连接```python
import requests
import json
SSE endpoint
url = "http://localhost:8080/sse"
List products
payload = {
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_products",
"arguments": {
"query": "shirt",
"per_page": 10
}
},
"id": 1
}
response = requests.post(url, json=payload)
print(response.json())
### 从cURL连接```bash
# List products
curl -X POST http://localhost:8080/sse \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_products",
"arguments": {
"published": true,
"per_page": 20
}
},
"id": 1
}'
高级示例```bash
Get low stock products
curl -X POST http://localhost:8080/sse \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_products",
"arguments": {
"max_stock": 10,
"published": true
}
},
"id": 1
}'
Create order
curl -X POST http://localhost:8080/sse \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_order",
"arguments": {
"products": [{"variant_id": 123456, "quantity": 2}],
"customer": {
"name": "John Doe",
"email": "john@example.com"
},
"payment_status": "paid"
}
},
"id": 1
}'
## 🐳 Docker命令```bash
# Build
docker-compose build
# Start
docker-compose up -d
# Logs
docker-compose logs -f tiendanube-mcp
# Restart
docker-compose restart
# Stop
docker-compose down
# Remove everything
docker-compose down -v --rmi all
# Shell access
docker exec -it tiendanube-mcp-server bash
🔐 安全说明
- 永不承诺
.env文件 -添加到.gitignore - 使用特定于环境的令牌 -单独的开发/产品凭据
- 启用HTTPS -使用反向代理(nginx/traefik)进行生产
- 速率限制 -考虑增加生产速率限制
- CORS配置 -如果公开,配置允许的来源
🔄 更新中```bash
Pull latest changes
git pull
Rebuild
docker-compose down
docker-compose build --no-cache
docker-compose up -d
## 📝 日志记录
日志配置为轮换:
- 最大大小:每个文件10MB
- 最大文件数:3
- 位置:Docker日志(使用 `docker-compose logs`)
查看日志:```bash
# All logs
docker-compose logs -f
# Last 100 lines
docker-compose logs --tail=100
# Specific service
docker-compose logs -f tiendanube-mcp
🐛 故障排除
服务器无法启动```bash
Check logs
docker-compose logs tiendanube-mcp
Verify environment variables
docker-compose config
Test API credentials
curl -H "Authentication: bearer YOUR_TOKEN" \
https://api.tiendanube.com/v1/YOUR_STORE_ID/store
### 连接被拒绝
- 验证端口8080是否未使用: `netstat -tuln | grep 8080`
- 检查防火墙设置
- 确保容器正在运行: `docker ps`
### 权限错误```bash
# Fix permissions
chmod +x start.sh
🌟 生产部署
使用Nginx反向代理```nginx
server {
listen 443 ssl http2;
server_name mcp.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location /sse {
proxy_pass http://localhost:8080/sse;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
SSE specific
proxy_buffering off;
proxy_read_timeout 86400;
}
}
### 使用Docker Swarm```bash
docker stack deploy -c docker-compose.yml tiendanube
生产环境变量```env
TIENDANUBE_ACCESS_TOKEN=prod_token
TIENDANUBE_STORE_ID=prod_store_id
MCP_TRANSPORT=sse
MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=WARNING
```
📚 资源
- Tiendanube API文件
- MCP协议规范
- Docker文档
📄 许可证
MIT许可证-有关详细信息,请参阅许可证文件
🤝 贡献
欢迎投稿!请打开问题或提交拉取请求。
📧 支持
关于以下问题:
- 此MCP服务器:打开GitHub问题
- API:联系Tiendanube支持
- MCP协议:检查MCP文件
