# Tiendanube MCP Server - Docker Setup
A complete Model Context Protocol (MCP) server for Tiendanube/Nuvemshop API with Docker support and SSE transport.
## 🚀 Features
### Resources
- **Products**: Full CRUD with advanced filtering (stock, price, categories, SKU)
- **Orders**: Complete order management with history tracking
- **Customers**: Customer management with addresses and billing
- **Categories**: Category hierarchy management
- **Coupons**: Discount coupon management
- **Store**: Store information and settings
### Transport Modes
- ✅ **SSE (Server-Sent Events)** - For web-based clients
- ✅ **Streamable HTTP** - Modern HTTP transport
- ✅ **STDIO** - For CLI/terminal usage
## 📋 Prerequisites
- Docker and Docker Compose
- Tiendanube API credentials:
- Access Token
- Store ID
## 🔧 Setup
### 1. Clone or Create Project Structure
```bash
mkdir tiendanube-mcp
cd tiendanube-mcp
```
Create the following files:
- `tiendanube_server.py` (main server code)
- `Dockerfile`
- `docker-compose.yml`
- `requirements.txt`
- `.env` (from `.env.example`)
### 2. Configure Environment Variables
Create `.env` file:
```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 and Run
```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
```
## 🌐 Accessing the Server
### SSE Transport (Default)
```
URL: http://localhost:8080/sse
```
### Streamable HTTP Transport
Change `.env`:
```env
MCP_TRANSPORT=streamable-http
```
```
URL: http://localhost:8080/mcp
```
## 🔍 Health Check
```bash
curl http://localhost:8080/health
```
## 📊 API Endpoints
### Products
- `list_products` - List/search products with filters
- `get_product` - Get product by ID
- `get_product_by_sku` - Get product by SKU
- `create_product` - Create new product with variants
- `update_product` - Update product information
- `delete_product` - Delete product
- `update_product_stock_price` - Bulk update stock/prices
### Orders
- `list_orders` - List orders with filters
- `get_order` - Get order details
- `get_order_history_values` - Get value change history
- `get_order_history_editions` - Get edition changelog
- `create_order` - Create new order
- `update_order` - Update order
- `close_order` - Close order
- `open_order` - Reopen order
- `cancel_order` - Cancel order
### Customers
- `list_customers` - List/search customers
- `get_customer` - Get customer details
- `create_customer` - Create new customer
- `update_customer` - Update customer
- `delete_customer` - Delete customer
### Categories
- `list_categories` - List all categories
- `get_category` - Get category details
- `create_category` - Create category
- `update_category` - Update category
- `delete_category` - Delete category
### Coupons
- `list_coupons` - List all coupons
- `get_coupon` - Get coupon details
- `create_coupon` - Create discount coupon
### Store
- `get_store` - Get store information
## 🎯 Usage Examples
### Connect from Python Client
```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())
```
### Connect from 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
}'
```
### Advanced Examples
```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 Commands
```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
```
## 🔐 Security Notes
1. **Never commit `.env` file** - Add to `.gitignore`
2. **Use environment-specific tokens** - Separate dev/prod credentials
3. **Enable HTTPS** - Use reverse proxy (nginx/traefik) for production
4. **Rate limiting** - Consider adding rate limits for production
5. **CORS configuration** - Configure allowed origins if exposing publicly
## 🔄 Updating
```bash
# Pull latest changes
git pull
# Rebuild
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```
## 📝 Logging
Logs are configured with rotation:
- Max size: 10MB per file
- Max files: 3
- Location: Docker logs (use `docker-compose logs`)
View logs:
```bash
# All logs
docker-compose logs -f
# Last 100 lines
docker-compose logs --tail=100
# Specific service
docker-compose logs -f tiendanube-mcp
```
## 🐛 Troubleshooting
### Server won't start
```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
```
### Connection refused
- Verify port 8080 is not in use: `netstat -tuln | grep 8080`
- Check firewall settings
- Ensure container is running: `docker ps`
### Permission errors
```bash
# Fix permissions
chmod +x start.sh
```
## 🌟 Production Deployment
### With Nginx Reverse Proxy
```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;
}
}
```
### With Docker Swarm
```bash
docker stack deploy -c docker-compose.yml tiendanube
```
### Environment Variables for Production
```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
```
## 📚 Resources
- [Tiendanube API Documentation](https://tiendanube.github.io/api-documentation/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Docker Documentation](https://docs.docker.com/)
## 📄 License
MIT License - See LICENSE file for details
## 🤝 Contributing
Contributions are welcome! Please open an issue or submit a pull request.
## 📧 Support
For issues related to:
- **This MCP Server**: Open a GitHub issue
- **Tiendanube API**: Contact Tiendanube support
- **MCP Protocol**: Check MCP documentation
