Tiendanube MCP Server

Tiendanube MCP服务器-Docker设置

一个完整的模型上下文协议（MCP）服务器，用于Tiendanube/Nuvmshop API，支持Docker和SSE传输。

🚀 特性

资源

• 产品：具有高级过滤功能的完整CRUD（库存、价格、类别、SKU）
• 订单：完整的订单管理和历史跟踪
• 客户：客户管理，包括地址和账单
• 分类：类别层次结构管理
• 优惠券：优惠券管理
• 商店：存储信息和设置

运输方式

• ✅ SSE（服务器发送事件） -对于基于web的客户端
• ✅ 流式HTTP -现代HTTP传输
• ✅ 工作室 -用于CLI/终端使用

📋 先决条件

• Docker和Docker Compose
• Tiendanube API证书：

- 访问令牌 - 店铺ID

🔧 设置

1.克隆或创建项目结构

mkdir tiendanube-mcp
cd tiendanube-mcp

创建以下文件：

• tiendanube_server.py （主服务器代码）
• Dockerfile
• docker-compose.yml
• requirements.txt
• .env （从 .env.example)

2.配置环境变量

创建 .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.构建和运行

# 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:

MCP_TRANSPORT=streamable-http

URL: http://localhost:8080/mcp

🔍 健康检查

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客户端连接

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连接

# 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
  }'

高级示例

# 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命令

# 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

🔐 安全说明

1. 永不承诺 .env 文件 -添加到 .gitignore
2. 使用特定于环境的令牌 -单独的开发/产品凭据
3. 启用HTTPS -使用反向代理（nginx/traefik）进行生产
4. 速率限制 -考虑增加生产速率限制
5. CORS配置 -如果公开，配置允许的来源

🔄 更新中

# Pull latest changes
git pull

# Rebuild
docker-compose down
docker-compose build --no-cache
docker-compose up -d

📝 日志记录

日志配置为轮换：

• 最大大小：每个文件10MB
• 最大文件数：3
• 位置：Docker日志（使用 docker-compose logs)

查看日志：

# All logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

# Specific service
docker-compose logs -f tiendanube-mcp

🐛 故障排除

服务器无法启动

# 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

权限错误

# Fix permissions
chmod +x start.sh

🌟 生产部署

使用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

docker stack deploy -c docker-compose.yml tiendanube

生产环境变量

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协议规范

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

欢迎投稿！请打开问题或提交拉取请求。

📧 支持

关于以下问题：

• 此MCP服务器：打开GitHub问题
• API：联系Tiendanube支持
• MCP协议：检查MCP文件