commercevault-edd-ecommerce-api

# CommerceVault EDD MCP Server > Skill by [ara.so](https://ara.so) — MCP Skills collection. CommerceVault (mcp-edd-analytics-vantage) is an MCP (Model Context Protocol) server that provides structured access to Easy Digital Downloads (EDD) APIs for sales analytics, product management, customer data, and license/entitlement tracking. It acts as a middleware orchestrator between AI agents and WordPress EDD installations, exposing REST endpoints through a standardized interface. ## What It Does - **Product Catalog Access**: Query, filter, and synchronize digital product listings with pricing, categories, and metadata - **Order Management**: Retrieve order history, payment status, fulfillment data, and refund information - **Customer Analytics**: Access customer profiles, lifetime value, purchase frequency, and segmentation data - **Sales Reporting**: Real-time analytics for revenue, GMV, AOV, churn rate, and cohort analysis - **License Management**: Track license keys, activation codes, and entitlement tiers for digital products - **Webhook Integration**: Bidirectional event relay for order completions, refunds, and customer updates ## Installation ### Prerequisites - Node.js 18+ or Python 3.9+ - Access to an Easy Digital Downloads WordPress installation - EDD REST API credentials (API key and token) ### MCP Server Setup 1. **Clone the repository**: ```bash git clone https://github.com/dhapat3927/mcp-edd-analytics-vantage.git cd mcp-edd-analytics-vantage ``` 2. **Install dependencies** (Node.js example): ```bash npm install ``` 3. **Configure environment variables**: ```bash # .env EDD_API_URL=https://your-store.com/edd-api/v2 EDD_API_KEY=your_edd_api_key EDD_API_TOKEN=your_edd_api_token CACHE_ENABLED=true REDIS_URL=redis://localhost:6379 WEBHOOK_SECRET=your_webhook_signing_secret ``` 4. **Start the MCP server**: ```bash npm start # or python main.py ``` ### MCP Client Configuration Add to your MCP client settings (e.g., Claude Desktop `claude_desktop_config.json`): ```json { "mcpServers": { "commercevault-edd": { "command": "node", "args": ["/path/to/mcp-edd-analytics-vantage/dist/index.js"], "env": { "EDD_API_URL": "https://your-store.com/edd-api/v2", "EDD_API_KEY": "${EDD_API_KEY}", "EDD_API_TOKEN": "${EDD_API_TOKEN}" } } } } ``` ## Core API Methods ### Products **List all products**: ```javascript const products = await mcp.callTool("commercevault-edd", "list_products", { per_page: 50, page: 1, status: "publish", category: "software" }); ``` **Get product details**: ```javascript const product = await mcp.callTool("commercevault-edd", "get_product", { product_id: 123 }); ``` **Search products**: ```javascript const results = await mcp.callTool("commercevault-edd", "search_products", { query: "wordpress plugin", price_min: 19.99, price_max: 99.99 }); ``` ### Orders **Fetch recent orders**: ```javascript const orders = await mcp.callTool("commercevault-edd", "list_orders", { status: "completed", date_start: "2026-01-01", date_end: "2026-06-30", per_page: 100 }); ``` **Get order details**: ```javascript const order = await mcp.callTool("commercevault-edd", "get_order", { order_id: 45678 }); ``` **Process refund**: ```javascript const refund = await mcp.callTool("commercevault-edd", "create_refund", { order_id: 45678, amount: 29.99, reason: "Customer request" }); ``` ### Customers **Get customer data**: ```javascript const customer = await mcp.callTool("commercevault-edd", "get_customer", { customer_id: 789, include_purchases: true }); ``` **List customers by segment**: ```javascript const highValue = await mcp.callTool("commercevault-edd", "list_customers", { ltv_min: 500, order_count_min: 5, sort: "ltv_desc" }); ``` ### Analytics **Revenue report**: ```javascript const revenue = await mcp.callTool("commercevault-edd", "get_revenue_report", { period: "monthly", start_date: "2026-01-01", end_date: "2026-06-30", group_by: "product" }); ``` **Sales metrics**: ```javascript const metrics = await mcp.callTool("commercevault-edd", "get_sales_metrics", { period: "last_30_days", metrics: ["gmv", "aov", "conversion_rate", "refund_rate"] }); ``` **Cohort analysis**: ```javascript const cohorts = await mcp.callTool("commercevault-edd", "analyze_cohorts", { cohort_by: "signup_month", metric: "retention_rate", months: 12 }); ``` ### Licenses **Get license info**: ```javascript const license = await mcp.callTool("commercevault-edd", "get_license", { license_key: "abc123def456" }); ``` **Activate license**: ```javascript const activation = await mcp.callTool("commercevault-edd", "activate_license", { license_key: "abc123def456", site_url: "https://customer-site.com", product_id: 123 }); ``` ## Configuration ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `EDD_API_URL` | Yes | Base URL for EDD REST API | | `EDD_API_KEY` | Yes | EDD API public key | | `EDD_API_TOKEN` | Yes | EDD API secret token | | `CACHE_ENABLED` | No | Enable Redis caching (default: false) | | `REDIS_URL` | No | Redis connection string | | `WEBHOOK_SECRET` | No | HMAC secret for webhook verification | | `RATE_LIMIT_MAX` | No | Max requests per window (default: 100) | | `RATE_LIMIT_WINDOW` | No | Rate limit window in seconds (default: 60) | ### Adapter Configuration Create `config/adapter.json` for custom EDD endpoint mappings: ```json { "adapter": "edd", "version": "2.0", "endpoints": { "products": "/products", "orders": "/sales", "customers": "/customers", "licenses": "/licenses" }, "auth": { "type": "bearer", "header": "X-EDD-Token" }, "cache": { "ttl_products": 3600, "ttl_orders": 300, "ttl_customers": 600 } } ``` ## Real-World Examples ### Example 1: Daily Sales Dashboard ```javascript async function generateDailySalesDashboard(date) { // Fetch today's orders const orders = await mcp.callTool("commercevault-edd", "list_orders", { date_start: date, date_end: date, status: "completed" }); // Calculate metrics const totalRevenue = orders.reduce((sum, order) => sum + order.total, 0); const avgOrderValue = totalRevenue / orders.length; // Get top products const productSales = {}; orders.forEach(order => { order.items.forEach(item => { productSales[item.product_id] = (productSales[item.product_id] || 0) + item.quantity; }); }); // Get refunds const refunds = await mcp.callTool("commercevault-edd", "list_orders", { date_start: date, date_end: date, status: "refunded" }); return { date, totalOrders: orders.length, totalRevenue, avgOrderValue, refundCount: refunds.length, topProducts: Object.entries(productSales) .sort((a, b) => b[1] - a[1]) .slice(0, 5) }; } ``` ### Example 2: Customer Lifetime Value Analysis ```javascript async function analyzeCustomerLTV(customerIds) { const results = []; for (const customerId of customerIds) { const customer = await mcp.callTool("commercevault-edd", "get_customer", { customer_id: customerId, include_purchases: true }); const orders = await mcp.callTool("commercevault-edd", "list_orders", { customer_id: customerId, status: "completed" }); const ltv = orders.reduce((sum, order) => sum + order.total, 0); const firstPurchase = orders[orders.length - 1]?.date; const daysSinceFirst = Math.floor( (new Date() - new Date(firstPurchase)) / (1000 * 60 * 60 * 24) ); results.push({ customerId, email: customer.email, ltv, orderCount: orders.length, avgOrderValue: ltv / orders.length, daysSinceFirst, purchaseFrequency: orders.length / (daysSinceFirst / 30) // orders per month }); } return results.sort((a, b) => b.ltv - a.ltv); } ``` ### Example 3: License Management Automation ```javascript async function renewExpiredLicenses() { const licenses = await mcp.callTool("commercevault-edd", "list_licenses", { status: "expired", expiry_date_end: new Date().toISOString().split('T')[0] }); const renewalResults = []; for (const license of licenses) { try { // Get customer info const customer = await mcp.callTool("commercevault-edd", "get_customer", { customer_id: license.customer_id }); // Create renewal order const renewal = await mcp.callTool("commercevault-edd", "create_order", { customer_id: license.customer_id, products: [{ product_id: license.product_id, price: license.renewal_price }], license_renewal: license.license_key }); renewalResults.push({ license: license.license_key, customer: customer.email, status: "renewed", orderId: renewal.order_id }); } catch (error) { renewalResults.push({ license: license.license_key, status: "failed", error: error.message }); } } return renewalResults; } ``` ## Common Patterns ### Caching Strategy ```javascript // Enable cache for frequently accessed data const getCachedProduct = async (productId) => { const cacheKey = `product:${productId}`; const cached = await mcp.callTool("commercevault-edd", "cache_get", { key: cacheKey }); if (cached) return cached; const product = await mcp.callTool("commercevault-edd", "get_product", { product_id: productId }); await mcp.callTool("commercevault-edd", "cache_set", { key: cacheKey, value: product, ttl: 3600 }); return product; }; ``` ### Pagination Handling ```javascript async function getAllOrders(filters) { let page = 1; let allOrders = []; let hasMore = true;