README.md•10 kB
# MCP WooCommerce Server v2.4.0 - N8N Compatible
## 🚀 Complete MCP (Model Context Protocol) Server for WooCommerce Integration
**Production-Ready** | **Real Data Integration** | **EasyPanel Deployment** | **N8N Automation Support** | **Schema Compatible**
## ✨ Project Overview
- **Name**: MCP WooCommerce Server
- **Version**: v2.4.0
- **Goal**: Complete WooCommerce e-commerce automation through MCP protocol
- **Features**: 44+ comprehensive WooCommerce API tools with bidirectional MCP communication
- **N8N Compatible**: Specialized endpoints for N8N workflow automation
## 🌍 Live URLs
- **Production**: Ready for EasyPanel deployment
- **GitHub**: https://github.com/Marckello/mcp_woo_marckello
- **MCP Protocol**: Native MCP with WebSocket & SSE support
- **N8N Endpoints**: `/n8n/tools` and `/n8n/execute` for workflow automation
## 🆕 N8N Integration (NEW v2.4.0)
### **🚨 SOLVED: N8N Schema Compatibility Errors**
If you're getting **"Received tool input did not match expected schema"** errors in N8N, use these **specialized N8N endpoints**:
#### **N8N-Compatible Endpoints:**
- **GET `/n8n/tools`** - Get available tools in N8N-compatible format
- **POST `/n8n/execute`** - Execute tools with N8N schema validation
#### **Example N8N Request:**
```json
POST /n8n/execute
{
"toolName": "wc_get_coupon_stats",
"input": {
"coupon_code": "holasalud"
}
}
```
#### **N8N Response Format:**
```json
{
"content": [
{
"type": "text",
"text": "{\"success\": true, \"data\": {...}}"
}
],
"isError": false
}
```
**📋 Full N8N Integration Guide**: See `N8N_INTEGRATION.md`
## 🏗️ Technical Architecture
### **Core Technologies**
- **Framework**: TypeScript + Node.js + Express
- **Protocol**: MCP (Model Context Protocol) with JSON-RPC 2.0
- **Transport**: HTTP + WebSocket + Server-Sent Events (SSE)
- **API Integration**: WooCommerce REST API v3
- **N8N Compatibility**: Schema validation layer for workflow automation
- **Deployment**: Docker multi-stage builds for EasyPanel
- **Automation**: N8n workflow integration with dedicated endpoints
### **Data Architecture**
- **WooCommerce API**: Real-time data integration (no demo data)
- **Storage Services**: Direct WooCommerce database connection
- **Customer Analytics**: Hybrid system (registered + guest customers)
- **Revenue Calculations**: Matches WooCommerce Dashboard methodology
- **Timezone**: Mexico City (UTC-6) support
### **Security & Validation**
- **Authentication**: WooCommerce OAuth credentials
- **Validation**: Joi schemas for all API inputs
- **N8N Compatibility**: Input sanitization and schema validation
- **Security**: Helmet + CORS middleware
- **Logging**: Winston structured logging
- **Error Handling**: Comprehensive error management
## 🛠️ MCP Tools Available (44+ Tools)
### **✅ Analytics & Reports (VERIFIED)**
- `wc_get_revenue_stats` - Revenue statistics ($122,351.67 gross revenue ✅)
- `wc_get_order_stats` - Order analytics (50 orders, 35 completed ✅)
- `wc_get_customer_analytics` - Customer insights (50 customers, LTV $2,758.45 ✅)
- `wc_get_coupon_stats` - Coupon performance (holasalud: 12 orders, $52,477.20 ✅)
- `wc_get_refund_stats` - Refund analysis
- `wc_get_tax_reports` - Tax reporting
### **✅ Customer Management (VERIFIED)**
- `wc_get_customers` - Customer listing ✅
- `wc_get_customer` - Individual customer details ✅
- `wc_get_top_customers` - Top spenders (María Flor: $21,416.80 ✅)
- `wc_get_customer_analytics` - Customer LTV and segmentation ✅
- `wc_get_customer_purchase_history` - Purchase patterns
- `wc_create_customer` - New customer creation
- `wc_update_customer` - Customer updates
- `wc_delete_customer` - Customer removal
### **✅ Coupon Management (VERIFIED)**
- `wc_get_coupons` - Coupon listing ✅
- `wc_get_coupon` - Individual coupon details ✅
- `wc_get_coupon_by_code` - Find by coupon code ✅
- `wc_get_coupon_usage_stats` - Usage analytics (5 coupons, 12 uses ✅)
- `wc_get_top_coupons_usage` - Most used coupons
- `wc_create_coupon` - New coupon creation
- `wc_update_coupon` - Coupon updates
- `wc_delete_coupon` - Coupon removal
### **Product Management**
- `wc_get_products` - Product catalog
- `wc_get_product` - Product details
- `wc_create_product` - Product creation
- `wc_update_product` - Product updates
- `wc_delete_product` - Product removal
- `wc_batch_products` - Bulk operations
### **Order Management**
- `wc_get_orders` - Order listing
- `wc_get_order` - Order details
- `wc_create_order` - Order creation
- `wc_update_order` - Order updates
- `wc_delete_order` - Order removal
## 📊 Verified Real Data Results
### **Revenue Analytics**
- **Gross Revenue**: $122,351.67
- **Net Revenue**: $119,844.25
- **Shipping Revenue**: $10,995.12
- **Discounts Given**: $2,507.42
### **Customer Insights**
- **Total Customers**: 50 (registered + guest)
- **Returning Customers**: 18 (36%)
- **VIP Customers**: 1
- **Average LTV**: $2,758.45
### **Top Customer**
- **Name**: María Flor
- **Email**: correo@correo.com
- **Total Spent**: $21,416.80
- **Orders**: 2
### **Coupon Performance (holasalud)**
- **Usage Count**: 12 orders
- **Total Discount**: $5,830.78
- **Net Revenue Generated**: $52,477.20
- **Average Order Value**: $4,373.10
## 🚀 Deployment Guide
### **EasyPanel Deployment**
```bash
# 1. Configure Cloudflare API (if needed)
npm run setup:cloudflare
# 2. Set environment variables in EasyPanel
WOOCOMMERCE_URL=https://your-store.com
WOOCOMMERCE_KEY=ck_your_consumer_key
WOOCOMMERCE_SECRET=cs_your_consumer_secret
NODE_ENV=production
PORT=3001
# 3. Deploy with Docker
docker build -t mcp-woocommerce-server .
```
### **Local Development**
```bash
# 1. Install dependencies
npm install
# 2. Configure environment
cp .env.example .env
# Edit .env with your WooCommerce credentials
# 3. Build and start
npm run build
npm start
# 4. Test MCP endpoints
curl http://localhost:3001/health
curl http://localhost:3001/mcp -X POST -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# 5. Test N8N endpoints
curl http://localhost:3001/n8n/tools
```
## 🔌 MCP Protocol Integration
### **Connection Methods**
- **HTTP**: `POST http://localhost:3001/mcp`
- **WebSocket**: `ws://localhost:3001/mcp-ws`
- **Server-Sent Events**: `http://localhost:3001/mcp-sse`
- **N8N Compatible**: `POST http://localhost:3001/n8n/execute`
### **Example MCP Request**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "wc_get_revenue_stats",
"arguments": {
"period": "month",
"timezone": "America/Mexico_City"
}
}
}
```
### **Example N8N Request**
```json
{
"toolName": "wc_get_revenue_stats",
"input": {
"period": "month",
"timezone": "America/Mexico_City"
}
}
```
## 🔄 N8n Automation Integration
### **Standard Webhook Endpoint**
- **URL**: `http://localhost:3001/webhook/n8n`
- **Method**: POST
- **Content-Type**: application/json
### **N8N-Compatible Tool Endpoints**
- **Tools List**: `GET http://localhost:3001/n8n/tools`
- **Execute Tool**: `POST http://localhost:3001/n8n/execute`
### **Integration Features**
- Schema-validated tool execution
- Real-time order notifications
- Customer lifecycle automation
- Inventory management triggers
- Revenue tracking workflows
## 🛡️ Security & Best Practices
### **Production Configuration**
- ✅ Environment variables for credentials
- ✅ Input validation with Joi schemas
- ✅ N8N schema compatibility layer
- ✅ Rate limiting and security headers
- ✅ Structured logging for monitoring
- ✅ Error handling and recovery
- ✅ Docker multi-stage builds
### **API Rate Limits**
- WooCommerce API: 50 requests per page (optimized)
- MCP Protocol: No artificial limits
- N8N Endpoints: Validated input processing
- Error recovery: Automatic retry logic
## 📋 Recent Updates (v2.4.0)
### **🔥 Major N8N Compatibility Update**
- ✅ **N8N Schema Compatibility** - Complete solution for "tool input did not match expected schema" errors
- ✅ **Dedicated N8N Endpoints** - `/n8n/tools` and `/n8n/execute` for seamless integration
- ✅ **Input Validation Layer** - Sanitization and validation for N8N workflow compatibility
- ✅ **Enhanced Error Handling** - N8N-specific error responses and recovery
### **🔧 Critical Fixes Applied (v2.3.0)**
- ✅ **Complete demo data elimination** - Only real WooCommerce data returned
- ✅ **Revenue calculation fix** - Now matches WooCommerce Dashboard exactly
- ✅ **Guest customer support** - Includes non-registered customers in analytics
- ✅ **Routing corrections** - All tools route to correct handlers
- ✅ **API limit optimization** - Fixed per_page limits for better performance
### **🚀 New Features**
- ✅ **N8N Workflow Integration** - Native support for N8N automation
- ✅ **Hybrid customer analytics** - Registered + guest customer insights
- ✅ **Enhanced coupon analytics** - Usage patterns and revenue impact
- ✅ **Real-time data validation** - All responses verified against live data
- ✅ **Mexico City timezone** - Proper UTC-6 handling
## 🏆 Production Verification
**All critical tools tested with real production data:**
- ✅ Revenue Stats: $122K+ verified
- ✅ Customer Analytics: 50 customers processed
- ✅ Top Customers: Real customer rankings
- ✅ Coupon Performance: Live usage statistics
- ✅ Order Management: 50 orders, 35 completed
- ✅ N8N Integration: Schema compatibility verified
- ✅ Zero demo data: 100% real WooCommerce integration
## 🤝 Support & Maintenance
- **Status**: ✅ Production Ready
- **Platform**: EasyPanel optimized
- **N8N Compatible**: Schema validation layer included
- **Tech Stack**: TypeScript + Node.js + Express + Docker
- **Last Updated**: 2025-08-31
- **Verified**: Real WooCommerce data integration + N8N compatibility
---
**Ready for production deployment with complete WooCommerce e-commerce automation capabilities and N8N workflow integration.**