@adsim/wordpress-mcp-server 4.6.0 → 5.1.0

package/src/tools/woocommerce.js

@@ -0,0 +1,1008 @@
+// src/tools/woocommerce.js — woocommerce tools (20)
+// Definitions + handlers (v5.0.0 refactor Step B+C)
+
+import { json, strip } from '../shared/utils.js';
+import { validateInput } from '../shared/governance.js';
+import { rt } from '../shared/context.js';
+
+export const definitions = [
+  { name: 'wc_list_products', _category: 'woocommerce', description: 'Use to browse WooCommerce products. Filter by status, category, or search. Read-only.',
+        inputSchema: { type: 'object', properties: { per_page: { type: 'number', default: 10 }, page: { type: 'number', default: 1 }, status: { type: 'string', default: 'any', description: 'any, draft, pending, private, publish' }, search: { type: 'string' }, category: { type: 'number' }, orderby: { type: 'string', default: 'date', description: 'date, id, title, price, popularity' }, order: { type: 'string', default: 'desc' } }}},
+  { name: 'wc_get_product', _category: 'woocommerce', description: 'Use to get full product details including variations summary. Read-only.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] }},
+  { name: 'wc_list_orders', _category: 'woocommerce', description: 'Use to browse WooCommerce orders. Filter by status or customer. Read-only.',
+        inputSchema: { type: 'object', properties: { per_page: { type: 'number', default: 10 }, page: { type: 'number', default: 1 }, status: { type: 'string', default: 'any', description: 'any, pending, processing, on-hold, completed, cancelled, refunded, failed' }, customer: { type: 'number' }, orderby: { type: 'string', default: 'date' }, order: { type: 'string', default: 'desc' } }}},
+  { name: 'wc_get_order', _category: 'woocommerce', description: 'Use to get order details with line items, shipping, billing, and payment info. Read-only.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] }},
+  { name: 'wc_list_customers', _category: 'woocommerce', description: 'Use to list WooCommerce customers with search and role filtering. Read-only.',
+        inputSchema: { type: 'object', properties: { per_page: { type: 'number', default: 10 }, page: { type: 'number', default: 1 }, search: { type: 'string' }, orderby: { type: 'string', default: 'date_created' }, order: { type: 'string', default: 'desc' }, role: { type: 'string', default: 'customer' } }}},
+  { name: 'wc_price_guardrail', _category: 'woocommerce', description: 'Use BEFORE changing a product price. Analyzes safety of proposed price change. Read-only, always allowed.',
+        inputSchema: { type: 'object', properties: { product_id: { type: 'number' }, new_price: { type: 'number' }, threshold_percent: { type: 'number', default: 20, description: 'default 20' } }, required: ['product_id', 'new_price'] }},
+  { name: 'wc_inventory_alert', _category: 'woocommerce', description: 'Use to identify low-stock and out-of-stock products below a threshold, sorted by urgency. Read-only.',
+        inputSchema: { type: 'object', properties: { threshold: { type: 'number', default: 5, description: 'default 5' }, per_page: { type: 'number', default: 50 }, include_out_of_stock: { type: 'boolean', default: true, description: 'include out-of-stock' } }}},
+  { name: 'wc_order_intelligence', _category: 'woocommerce', description: 'Use to analyze a customer\'s purchase history: lifetime value, average order, favorite products, frequency. Read-only.',
+        inputSchema: { type: 'object', properties: { customer_id: { type: 'number' } }, required: ['customer_id'] }},
+  { name: 'wc_seo_product_audit', _category: 'woocommerce', description: 'Use to audit WooCommerce product listings for SEO issues (missing descriptions, images, alt text, generic slugs). Read-only.',
+        inputSchema: { type: 'object', properties: { per_page: { type: 'number', default: 20 }, page: { type: 'number', default: 1 } }}},
+  { name: 'wc_suggest_product_links', _category: 'woocommerce', description: 'Use to suggest WooCommerce products to link from a blog post based on keyword relevance. Read-only.',
+        inputSchema: { type: 'object', properties: { post_id: { type: 'number' }, max_suggestions: { type: 'number', default: 3, description: 'Maximum suggestions (1-5)' } }, required: ['post_id'] }},
+  { name: 'wc_audit_product_seo', _category: 'woocommerce', description: 'Use to audit WooCommerce product SEO: title length, description, slug quality, image alt, schema presence. Scoring 0-100. Read-only.',
+        inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'default 100, max 500' }, category_id: { type: 'number' }, min_score: { type: 'number', description: 'default 0 (all)' } }}},
+  { name: 'wc_find_abandoned_carts_pattern', _category: 'woocommerce', description: 'Use to analyze abandoned cart patterns: hourly/daily trends, top abandoned products, estimated revenue loss. Requires Abandoned Cart Lite, CartFlows, or WC sessions. Read-only.',
+        inputSchema: { type: 'object', properties: { days: { type: 'number', description: 'default 30 days' }, min_cart_value: { type: 'number', description: 'default 0' } }}},
+  { name: 'wc_audit_checkout_friction', _category: 'woocommerce', description: 'Use to audit checkout friction: guest checkout, required fields count, coupon fields, multi-step, post-purchase redirect. Scores 0-10. Read-only.',
+        inputSchema: { type: 'object', properties: {} }},
+  { name: 'wc_get_product_performance', _category: 'woocommerce', description: 'Use to get product performance metrics with period comparison: units sold, revenue, refund rate, trend direction. Read-only.',
+        inputSchema: { type: 'object', properties: { product_id: { type: 'number', description: 'Product ID' }, period: { type: 'string', enum: ['30d', '90d', 'year'], description: 'Analysis period (default "30d")' } }, required: ['product_id'] }},
+  { name: 'wc_audit_stock_alerts', _category: 'woocommerce', description: 'Use to audit stock levels: out-of-stock, low-stock with last sale date. Includes variations. Read-only.',
+        inputSchema: { type: 'object', properties: { threshold: { type: 'number', description: 'default 5' }, include_zero_stock: { type: 'boolean', description: 'default true' }, include_variations: { type: 'boolean', description: 'default true' }, post_types: { type: 'array', items: { type: 'string' }, description: 'Product types (default ["simple","variable"])' } }}},
+  { name: 'wc_find_duplicate_products', _category: 'woocommerce', description: 'Use to find duplicate products by SKU, title similarity (Levenshtein), or slug similarity. Read-only.',
+        inputSchema: { type: 'object', properties: { similarity_threshold: { type: 'number', description: 'default 0.8 (0-1)' }, check_sku: { type: 'boolean', description: 'default true' }, check_title: { type: 'boolean', description: 'default true' }, check_slug: { type: 'boolean', description: 'default true' }, limit: { type: 'number', description: 'default 200' } }}},
+  { name: 'wc_audit_pricing_consistency', _category: 'woocommerce', description: 'Use to find pricing inconsistencies: sale >= regular, empty prices, expired sales, suspicious discounts. Read-only.',
+        inputSchema: { type: 'object', properties: { include_drafts: { type: 'boolean', description: 'Include draft products (default false)' }, include_variations: { type: 'boolean', description: 'Include variations (default true)' } }}},
+  { name: 'wc_update_product', _category: 'woocommerce', description: 'Use to update product fields (title, description, price, stock, status). Write — blocked by WP_READ_ONLY. Hint: call wc_price_guardrail first for price changes.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' }, name: { type: 'string' }, description: { type: 'string' }, short_description: { type: 'string' }, regular_price: { type: 'string', description: 'Format "19.99"' }, sale_price: { type: 'string' }, status: { type: 'string', description: 'publish, draft, or private' }, price_guardrail_confirmed: { type: 'boolean', default: false, description: 'Set true to bypass price guardrail after calling wc_price_guardrail' } }, required: ['id'] }},
+  { name: 'wc_update_stock', _category: 'woocommerce', description: 'Use to update stock quantity of a product or variation. Write — blocked by WP_READ_ONLY.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' }, stock_quantity: { type: 'number' }, variation_id: { type: 'number', description: 'Variation ID (for variable products)' } }, required: ['id', 'stock_quantity'] }},
+  { name: 'wc_update_order_status', _category: 'woocommerce', description: 'Use to transition order status (e.g. processing → completed). Write — blocked by WP_READ_ONLY.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' }, status: { type: 'string', description: 'processing, completed, cancelled, refunded, on-hold, failed' }, note: { type: 'string' } }, required: ['id', 'status'] }}
+];
+
+export const handlers = {};
+
+handlers['wc_list_products'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  validateInput(args, { per_page: { type: 'number', min: 1, max: 100 }, page: { type: 'number', min: 1 } });
+  const { per_page = 10, page = 1, status = 'any', search, category, orderby = 'date', order = 'desc' } = args;
+  const { url: baseUrl } = getActiveAuth();
+  let ep = `/products?per_page=${per_page}&page=${page}&orderby=${orderby}&order=${order}`;
+  if (status && status !== 'any') ep += `&status=${status}`;
+  if (search) ep += `&search=${encodeURIComponent(search)}`;
+  if (category) ep += `&category=${category}`;
+  const products = await wcApiCall(ep, {}, baseUrl);
+  result = json({ total: products.length, page, products: products.map(p => ({ id: p.id, name: p.name, slug: p.slug, status: p.status, price: p.price, regular_price: p.regular_price, sale_price: p.sale_price, stock_status: p.stock_status, stock_quantity: p.stock_quantity, categories: (p.categories || []).map(c => ({ id: c.id, name: c.name })), image: p.images?.[0]?.src || null, permalink: p.permalink })) });
+  auditLog({ tool: name, action: 'list', target_type: 'product', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_get_product'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 } });
+  const { url: baseUrl } = getActiveAuth();
+  const p = await wcApiCall(`/products/${args.id}`, {}, baseUrl);
+  const productData = { ...p };
+  if (p.type === 'variable' && p.variations && p.variations.length > 0) {
+    try {
+      const vars = await wcApiCall(`/products/${args.id}/variations?per_page=100`, {}, baseUrl);
+      productData.variations_detail = vars.map(v => ({ id: v.id, sku: v.sku, price: v.price, regular_price: v.regular_price, sale_price: v.sale_price, stock_status: v.stock_status, stock_quantity: v.stock_quantity, attributes: v.attributes }));
+    } catch { productData.variations_detail = []; }
+  }
+  result = json(productData);
+  auditLog({ tool: name, target: args.id, target_type: 'product', action: 'read', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wc_list_orders'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  validateInput(args, { per_page: { type: 'number', min: 1, max: 100 }, page: { type: 'number', min: 1 } });
+  const { per_page = 10, page = 1, status = 'any', customer, orderby = 'date', order = 'desc' } = args;
+  const { url: baseUrl } = getActiveAuth();
+  let ep = `/orders?per_page=${per_page}&page=${page}&orderby=${orderby}&order=${order}`;
+  if (status && status !== 'any') ep += `&status=${status}`;
+  if (customer) ep += `&customer=${customer}`;
+  const orders = await wcApiCall(ep, {}, baseUrl);
+  result = json({ total: orders.length, page, orders: orders.map(o => ({ id: o.id, number: o.number, status: o.status, date_created: o.date_created, customer_id: o.customer_id, billing_name: `${o.billing?.first_name || ''} ${o.billing?.last_name || ''}`.trim(), billing_email: o.billing?.email || '', total: o.total, currency: o.currency, line_items: (o.line_items || []).map(li => ({ name: li.name, quantity: li.quantity, total: li.total })) })) });
+  auditLog({ tool: name, action: 'list', target_type: 'order', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_get_order'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 } });
+  const { url: baseUrl } = getActiveAuth();
+  const o = await wcApiCall(`/orders/${args.id}`, {}, baseUrl);
+  result = json(o);
+  auditLog({ tool: name, target: args.id, target_type: 'order', action: 'read', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wc_list_customers'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  validateInput(args, { per_page: { type: 'number', min: 1, max: 100 }, page: { type: 'number', min: 1 } });
+  const { per_page = 10, page = 1, search, orderby = 'date_created', order = 'desc', role = 'customer' } = args;
+  const { url: baseUrl } = getActiveAuth();
+  let ep = `/customers?per_page=${per_page}&page=${page}&orderby=${orderby}&order=${order}&role=${role}`;
+  if (search) ep += `&search=${encodeURIComponent(search)}`;
+  const customers = await wcApiCall(ep, {}, baseUrl);
+  result = json({ total: customers.length, page, customers: customers.map(c => ({ id: c.id, first_name: c.first_name, last_name: c.last_name, email: c.email, date_created: c.date_created, orders_count: c.orders_count, total_spent: c.total_spent, username: c.username })) });
+  auditLog({ tool: name, action: 'list', target_type: 'customer', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_price_guardrail'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { product_id: { type: 'number', required: true, min: 1 }, new_price: { type: 'number', required: true }, threshold_percent: { type: 'number', min: 0 } });
+  const { product_id, new_price, threshold_percent = 20 } = args;
+  const { url: baseUrl } = getActiveAuth();
+  const p = await wcApiCall(`/products/${product_id}`, {}, baseUrl);
+  const current_price = parseFloat(p.price);
+  if (isNaN(current_price) || current_price <= 0) {
+    result = json({ safe: false, product_id, product_name: p.name, current_price: p.price, new_price, change_percent: null, message: 'Cannot evaluate: current price is zero or invalid' });
+    auditLog({ tool: name, target: product_id, target_type: 'product', action: 'price_check', status: 'success', latency_ms: Date.now() - t0, params: { new_price, threshold_percent } });
+    return result;
+  }
+  const change_percent = Math.round(Math.abs(new_price - current_price) / current_price * 10000) / 100;
+  const safe = change_percent <= threshold_percent;
+  result = json({
+    safe, product_id, product_name: p.name, current_price, new_price, change_percent,
+    ...(safe
+      ? { message: 'Price change within threshold' }
+      : { requires_confirmation: true, message: `Price change of ${change_percent}% exceeds threshold of ${threshold_percent}%. Use wp_update_product with confirm=true to proceed.` })
+  });
+  auditLog({ tool: name, target: product_id, target_type: 'product', action: 'price_check', status: 'success', latency_ms: Date.now() - t0, params: { current_price, new_price, change_percent, threshold_percent, safe } });
+  return result;
+};
+handlers['wc_inventory_alert'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { threshold: { type: 'number', min: 0 }, per_page: { type: 'number', min: 1, max: 100 } });
+  const { threshold = 5, per_page = 50, include_out_of_stock = true } = args;
+  const { url: baseUrl } = getActiveAuth();
+  const fetchSize = Math.min(per_page * 2, 100);
+  let allProducts = [];
+  const instock = await wcApiCall(`/products?stock_status=instock&per_page=${fetchSize}`, {}, baseUrl);
+  allProducts.push(...instock);
+  if (include_out_of_stock) {
+    const oos = await wcApiCall(`/products?stock_status=outofstock&per_page=${fetchSize}`, {}, baseUrl);
+    allProducts.push(...oos);
+  }
+  const alerts = allProducts.filter(p => {
+    if (p.stock_status === 'outofstock') return true;
+    if (p.stock_quantity !== null && p.stock_quantity !== undefined && p.stock_quantity <= threshold) return true;
+    return false;
+  });
+  alerts.sort((a, b) => (a.stock_quantity ?? -1) - (b.stock_quantity ?? -1));
+  const out_of_stock_count = alerts.filter(p => p.stock_status === 'outofstock').length;
+  const low_stock_count = alerts.length - out_of_stock_count;
+  result = json({
+    products: alerts.map(p => ({ id: p.id, name: p.name, sku: p.sku || '', stock_quantity: p.stock_quantity, stock_status: p.stock_status, price: p.price, permalink: p.permalink })),
+    summary: { total_alerts: alerts.length, out_of_stock_count, low_stock_count, threshold_used: threshold }
+  });
+  auditLog({ tool: name, action: 'inventory_alert', target_type: 'product', status: 'success', latency_ms: Date.now() - t0, params: { threshold, include_out_of_stock } });
+  return result;
+};
+handlers['wc_order_intelligence'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { customer_id: { type: 'number', required: true, min: 1 } });
+  const { customer_id } = args;
+  const { url: baseUrl } = getActiveAuth();
+  const orders = await wcApiCall(`/orders?customer=${customer_id}&per_page=100&orderby=date&order=desc`, {}, baseUrl);
+  const total_orders = orders.length;
+  if (total_orders === 0) {
+    result = json({ customer_id, total_orders: 0, total_spent: 0, average_order_value: 0, first_order_date: null, last_order_date: null, order_frequency_days: null, favourite_products: [], statuses_breakdown: {}, recent_orders: [] });
+    auditLog({ tool: name, target: customer_id, target_type: 'customer', action: 'order_intelligence', status: 'success', latency_ms: Date.now() - t0 });
+    return result;
+  }
+  const total_spent = Math.round(orders.reduce((sum, o) => sum + parseFloat(o.total || '0'), 0) * 100) / 100;
+  const average_order_value = Math.round(total_spent / total_orders * 100) / 100;
+  const last_order_date = orders[0].date_created;
+  const first_order_date = orders[orders.length - 1].date_created;
+  let order_frequency_days = null;
+  if (total_orders > 1) {
+    const firstMs = new Date(first_order_date).getTime();
+    const lastMs = new Date(last_order_date).getTime();
+    order_frequency_days = Math.round((lastMs - firstMs) / (1000 * 60 * 60 * 24) / total_orders);
+  }
+  const productFreq = {};
+  for (const o of orders) {
+    for (const li of (o.line_items || [])) {
+      productFreq[li.name] = (productFreq[li.name] || 0) + li.quantity;
+    }
+  }
+  const favourite_products = Object.entries(productFreq).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([pname, quantity]) => ({ name: pname, quantity }));
+  const statuses_breakdown = {};
+  for (const o of orders) { statuses_breakdown[o.status] = (statuses_breakdown[o.status] || 0) + 1; }
+  const recent_orders = orders.slice(0, 5).map(o => ({ id: o.id, date: o.date_created, total: o.total, status: o.status }));
+  result = json({ customer_id, total_orders, total_spent, average_order_value, first_order_date, last_order_date, order_frequency_days, favourite_products, statuses_breakdown, recent_orders });
+  auditLog({ tool: name, target: customer_id, target_type: 'customer', action: 'order_intelligence', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wc_seo_product_audit'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { per_page: { type: 'number', min: 1, max: 100 }, page: { type: 'number', min: 1 } });
+  const { per_page = 20, page = 1 } = args;
+  const { url: baseUrl } = getActiveAuth();
+  const products = await wcApiCall(`/products?per_page=${per_page}&page=${page}&status=publish`, {}, baseUrl);
+  let totalScore = 0;
+  const audited = products.map(p => {
+    const issues = [];
+    const descText = strip(p.description || '');
+    if (descText.length === 0) issues.push('missing_description');
+    else if (descText.length < 50) issues.push('description_too_short');
+    if (!p.short_description || strip(p.short_description).length === 0) issues.push('missing_short_description');
+    if (p.slug && p.slug.includes('product-')) issues.push('generic_slug');
+    if (!p.images || p.images.length === 0 || !p.images[0]?.src) issues.push('missing_image');
+    else if (!p.images[0]?.alt || p.images[0].alt.trim() === '') issues.push('missing_image_alt');
+    if (!p.price || p.price === '') issues.push('missing_price');
+    const score = Math.max(0, 100 - issues.length * 15);
+    totalScore += score;
+    return { id: p.id, name: p.name, score, issues, permalink: p.permalink };
+  });
+  const average_score = audited.length > 0 ? Math.round(totalScore / audited.length) : 0;
+  result = json({
+    average_score, total_audited: audited.length, products: audited,
+    summary: { perfect_score_count: audited.filter(p => p.score === 100).length, needs_attention_count: audited.filter(p => p.score < 70).length }
+  });
+  auditLog({ tool: name, action: 'seo_product_audit', target_type: 'product', status: 'success', latency_ms: Date.now() - t0, params: { per_page, page, avg_score: average_score } });
+  return result;
+};
+handlers['wc_suggest_product_links'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, wcApiCall, getActiveAuth, auditLog, name, extractFocusKeyword } = rt;
+  validateInput(args, { post_id: { type: 'number', required: true, min: 1 }, max_suggestions: { type: 'number', min: 1, max: 5 } });
+  const { post_id, max_suggestions = 3 } = args;
+  const { url: baseUrl } = getActiveAuth();
+  const post = await wpApiCall(`/posts/${post_id}`);
+  const postTitle = strip(post.title?.rendered || '');
+  const postMeta = post.meta || {};
+  const focusKw = extractFocusKeyword(postMeta);
+  const keywords = [];
+  if (focusKw) keywords.push(focusKw);
+  const titleWords = postTitle.split(/\s+/).filter(w => w.length > 3).slice(0, 3);
+  for (const w of titleWords) {
+    if (!keywords.some(k => k.toLowerCase() === w.toLowerCase())) keywords.push(w);
+  }
+  const candidateMap = new Map();
+  for (const kw of keywords.slice(0, 2)) {
+    try {
+      const prods = await wcApiCall(`/products?search=${encodeURIComponent(kw)}&per_page=10&status=publish`, {}, baseUrl);
+      if (Array.isArray(prods)) {
+        for (const p of prods) { if (!candidateMap.has(p.id)) candidateMap.set(p.id, p); }
+      }
+    } catch { /* search failed */ }
+  }
+  const scored = [];
+  for (const [, p] of candidateMap) {
+    let relevance_score = 0;
+    const nameLower = (p.name || '').toLowerCase();
+    const descLower = strip(p.description || '').toLowerCase();
+    for (const kw of keywords) {
+      const kwLower = kw.toLowerCase();
+      if (nameLower.includes(kwLower)) relevance_score += 3;
+      if (descLower.includes(kwLower)) relevance_score += 2;
+    }
+    if (p.stock_status === 'instock') relevance_score += 1;
+    if (p.images && p.images.length > 0 && p.images[0]?.src) relevance_score += 1;
+    scored.push({ product_id: p.id, product_name: p.name, product_url: p.permalink, anchor_text: (p.name || '').substring(0, 50), price: p.price, relevance_score, in_stock: p.stock_status === 'instock' });
+  }
+  scored.sort((a, b) => b.relevance_score - a.relevance_score);
+  const suggestions = scored.slice(0, max_suggestions);
+  result = json({ post_id, post_title: postTitle, keywords_used: keywords, suggestions });
+  auditLog({ tool: name, target: post_id, target_type: 'post', action: 'suggest_product_links', status: 'success', latency_ms: Date.now() - t0, params: { post_id, suggestion_count: suggestions.length } });
+  return result;
+};
+handlers['wc_audit_product_seo'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  const seoLimit = Math.min(args.limit || 100, 500);
+  const seoCatId = args.category_id || null;
+  const seoMinScore = args.min_score || 0;
+  const { url: baseUrl } = getActiveAuth();
+
+  let allProducts = [];
+  let seoPage = 1;
+  while (allProducts.length < seoLimit) {
+    const perPage = Math.min(100, seoLimit - allProducts.length);
+    let ep = `/products?per_page=${perPage}&page=${seoPage}&status=publish`;
+    if (seoCatId) ep += `&category=${seoCatId}`;
+    const batch = await wcApiCall(ep, {}, baseUrl);
+    if (!Array.isArray(batch) || batch.length === 0) break;
+    allProducts.push(...batch);
+    if (batch.length < perPage) break;
+    seoPage++;
+  }
+
+  let totalScore = 0;
+  const seoProducts = allProducts.map(p => {
+    let score = 100;
+    const issues = [];
+    const nameLen = (p.name || '').length;
+    if (nameLen < 30) { score -= 15; issues.push({ field: 'name', severity: 'medium', detail: `Title too short (${nameLen} chars)`, recommendation: 'Aim for 30-60 characters with primary keyword' }); }
+    else if (nameLen > 60) { score -= 10; issues.push({ field: 'name', severity: 'low', detail: `Title too long (${nameLen} chars)`, recommendation: 'Keep title under 60 characters for search results' }); }
+
+    const descLen = strip(p.description || '').length;
+    if (descLen < 50) { score -= 25; issues.push({ field: 'description', severity: 'high', detail: `Description too short (${descLen} chars)`, recommendation: 'Write at least 150 characters of unique product description' }); }
+    else if (descLen < 150) { score -= 10; issues.push({ field: 'description', severity: 'medium', detail: `Description could be longer (${descLen} chars)`, recommendation: 'Expand to 150+ characters for better SEO' }); }
+
+    if (p.slug && (/product-\d/.test(p.slug) || /-\d+$/.test(p.slug))) { score -= 20; issues.push({ field: 'slug', severity: 'high', detail: `Generic slug "${p.slug}"`, recommendation: 'Use descriptive keyword-rich slug' }); }
+
+    const mainImg = p.images?.[0];
+    if (!mainImg || !mainImg.src) { score -= 15; issues.push({ field: 'image', severity: 'high', detail: 'No product image', recommendation: 'Add a main product image with descriptive alt text' }); }
+    else if (!mainImg.alt || mainImg.alt.trim() === '') { score -= 15; issues.push({ field: 'image_alt', severity: 'high', detail: 'Main image missing alt text', recommendation: 'Add descriptive alt text to main product image' }); }
+
+    const meta = p.meta_data || p.meta || {};
+    const metaObj = Array.isArray(meta) ? meta.reduce((acc, m) => { acc[m.key] = m.value; return acc; }, {}) : meta;
+    let hasSchema = false;
+    if (metaObj._custom_schema_jsonld) hasSchema = true;
+    else if (metaObj.rank_math_schema) {
+      try { const s = typeof metaObj.rank_math_schema === 'string' ? JSON.parse(metaObj.rank_math_schema) : metaObj.rank_math_schema; if (JSON.stringify(s).includes('Product')) hasSchema = true; } catch {}
+    }
+    else if (metaObj._yoast_wpseo_schema_page_type === 'Product' || metaObj.wpseo_schema_page_type === 'Product') hasSchema = true;
+    if (!hasSchema) { score -= 15; issues.push({ field: 'schema', severity: 'medium', detail: 'No Product schema detected', recommendation: 'Add Product schema via RankMath, Yoast, or wp_inject_schema' }); }
+
+    score = Math.max(0, score);
+    totalScore += score;
+    return { id: p.id, name: p.name, slug: p.slug, score, issues };
+  });
+
+  const filtered = seoMinScore > 0 ? seoProducts.filter(p => p.score < seoMinScore) : seoProducts;
+  const avgScore = seoProducts.length > 0 ? Math.round(totalScore / seoProducts.length) : 0;
+  const byRange = { '90-100': 0, '70-89': 0, '50-69': 0, '0-49': 0 };
+  seoProducts.forEach(p => { if (p.score >= 90) byRange['90-100']++; else if (p.score >= 70) byRange['70-89']++; else if (p.score >= 50) byRange['50-69']++; else byRange['0-49']++; });
+
+  result = json({ products: filtered, summary: { total_audited: seoProducts.length, avg_score: avgScore, critical_count: seoProducts.filter(p => p.score < 50).length, by_score_range: byRange }, audit_config: { schema_sources_checked: ['custom_jsonld', 'rankmath', 'yoast', 'wc_native'] } });
+  auditLog({ tool: name, action: 'audit_product_seo', target_type: 'product', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_find_abandoned_carts_pattern'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  const acDays = args.days || 30;
+  const acMinValue = args.min_cart_value || 0;
+
+  let acData;
+  try {
+    acData = await wpApiCall(`/wc-abandoned-carts?days=${acDays}&min_value=${acMinValue}`, { basePath: '/wp-json/mcp-diagnostics/v1' });
+  } catch (e) {
+    result = json({ available: false, source: null, message: 'Companion mu-plugin not installed or endpoint unavailable. Copy mcp-diagnostics.php to wp-content/mu-plugins/', setup_options: ['Install WooCommerce Abandoned Cart Lite (free)', 'Install CartFlows', 'Install companion mu-plugin for WC session analysis'] });
+    auditLog({ tool: name, action: 'find_abandoned_carts', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+    return result;
+  }
+
+  if (!acData.available) {
+    result = json({ available: false, source: null, period_days: acDays, message: 'No abandoned cart data source found', setup_options: ['Install WooCommerce Abandoned Cart Lite (free)', 'Install CartFlows', 'Companion mu-plugin installed but no cart data tables detected'] });
+    auditLog({ tool: name, action: 'find_abandoned_carts', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+    return result;
+  }
+
+  const carts = acData.carts || [];
+  const totalAbandoned = carts.length;
+  const totalValue = carts.reduce((s, c) => s + (c.cart_value || 0), 0);
+  const avgValue = totalAbandoned > 0 ? Math.round(totalValue / totalAbandoned * 100) / 100 : 0;
+
+  // Patterns by hour and weekday
+  const byHour = Array.from({ length: 24 }, (_, h) => ({ hour: h, count: 0 }));
+  const byWeekday = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'].map(d => ({ day: d, count: 0 }));
+  const productFreq = {};
+  for (const c of carts) {
+    if (c.abandoned_at) {
+      const d = new Date(c.abandoned_at);
+      byHour[d.getHours()].count++;
+      byWeekday[d.getDay()].count++;
+    }
+    for (const item of (c.products || [])) {
+      const key = item.product_id || item.name || 'unknown';
+      productFreq[key] = productFreq[key] || { id: item.product_id, name: item.name || `Product ${item.product_id}`, frequency: 0 };
+      productFreq[key].frequency++;
+    }
+  }
+  byHour.forEach(h => { h.percentage = totalAbandoned > 0 ? Math.round(h.count / totalAbandoned * 10000) / 100 : 0; });
+  const topProducts = Object.values(productFreq).sort((a, b) => b.frequency - a.frequency).slice(0, 5);
+
+  // Estimate abandonment rate
+  let completedOrders = 0;
+  try {
+    const { url: baseUrl } = getActiveAuth();
+    const dateMin = new Date(Date.now() - acDays * 86400000).toISOString().split('T')[0];
+    const orders = await wcApiCall(`/orders?status=completed&after=${dateMin}T00:00:00&per_page=1`, {}, baseUrl);
+    // WC API returns total in headers, but we just count what we get
+    completedOrders = Array.isArray(orders) ? orders.length : 0;
+    // Try to get a better count
+    try {
+      const report = await wcApiCall(`/reports/sales?date_min=${dateMin}`, {}, baseUrl);
+      if (Array.isArray(report) && report[0]?.total_orders) completedOrders = parseInt(report[0].total_orders, 10);
+    } catch {}
+  } catch {}
+
+  const recommendations = [];
+  if (avgValue > 50) recommendations.push(`High average cart value (${avgValue}). Consider exit-intent popup with discount.`);
+  const peakHour = byHour.reduce((max, h) => h.count > max.count ? h : max, byHour[0]);
+  if (peakHour.count > 0) recommendations.push(`Peak abandonment at ${peakHour.hour}:00. Schedule recovery emails for ${(peakHour.hour + 1) % 24}:00.`);
+  if (topProducts.length > 0) recommendations.push(`Most abandoned product: "${topProducts[0].name}". Review its pricing, shipping, and checkout experience.`);
+  recommendations.push('Enable guest checkout to reduce friction.');
+  recommendations.push('Add trust badges near checkout button.');
+
+  result = json({ available: true, source: acData.source, period_days: acDays, total_abandoned: totalAbandoned, avg_cart_value: avgValue, estimated_revenue_loss: Math.round(totalValue * 100) / 100, patterns: { by_hour: byHour.filter(h => h.count > 0), by_weekday: byWeekday, top_abandoned_products: topProducts }, recommendations: recommendations.slice(0, 5) });
+  auditLog({ tool: name, action: 'find_abandoned_carts', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_audit_checkout_friction'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveAuth, VERSION, fetch, auditLog, sanitizeParams, name } = rt;
+  const { url: siteBaseUrl } = getActiveAuth();
+  let frictionScore = 0;
+  const frictionChecks = [];
+  const dataSources = ['wc_options'];
+
+  // Layer 1: WooCommerce options
+  let guestCheckout = 'yes';
+  let couponCart = 'yes';
+  let couponCheckout = 'yes';
+  let checkoutPageId = null;
+  try {
+    const opts = await wpApiCall('/settings/general', { basePath: '/wp-json/wc/v3' });
+    if (Array.isArray(opts)) {
+      for (const o of opts) {
+        if (o.id === 'woocommerce_enable_guest_checkout') guestCheckout = o.value || 'yes';
+        if (o.id === 'woocommerce_enable_coupons') { couponCart = o.value || 'yes'; couponCheckout = o.value || 'yes'; }
+      }
+    }
+  } catch { /* settings not accessible, use defaults */ }
+
+  try {
+    const checkoutOpts = await wpApiCall('/settings/advanced', { basePath: '/wp-json/wc/v3' });
+    if (Array.isArray(checkoutOpts)) {
+      for (const o of checkoutOpts) {
+        if (o.id === 'woocommerce_checkout_page_id') checkoutPageId = o.value;
+      }
+    }
+  } catch {}
+
+  // Guest checkout check
+  if (guestCheckout !== 'yes') {
+    frictionScore += 1.5;
+    frictionChecks.push({ name: 'guest_checkout', value: 'disabled', friction_points: 1.5, recommendation: 'Enable guest checkout to reduce cart abandonment' });
+  } else {
+    frictionChecks.push({ name: 'guest_checkout', value: 'enabled', friction_points: 0, recommendation: null });
+  }
+
+  // Coupon fields
+  if (couponCart !== 'yes' && couponCheckout !== 'yes') {
+    frictionScore += 1.0;
+    frictionChecks.push({ name: 'coupon_fields', value: 'disabled', friction_points: 1.0, recommendation: 'Enable coupon field to improve conversion for returning customers' });
+  } else {
+    frictionChecks.push({ name: 'coupon_fields', value: 'enabled', friction_points: 0, recommendation: null });
+  }
+
+  // Layer 2: HTML analysis (if guest checkout enabled and page accessible)
+  let requiredFieldCount = 0;
+  let hasMultiStep = false;
+  let hasPhoneRequired = false;
+  let hasCompanyRequired = false;
+  let htmlAnalyzed = false;
+
+  if (guestCheckout === 'yes') {
+    try {
+      const checkoutUrl = checkoutPageId ? `${siteBaseUrl.replace(/\/wp-json.*$/, '')}/?page_id=${checkoutPageId}` : `${siteBaseUrl.replace(/\/wp-json.*$/, '')}/checkout/`;
+      const controller = new AbortController();
+      const tid = setTimeout(() => controller.abort(), 10000);
+      const resp = await fetch(checkoutUrl, { headers: { 'User-Agent': `WordPress-MCP-Server/${VERSION}` }, signal: controller.signal, redirect: 'follow' });
+      clearTimeout(tid);
+      if (resp.ok) {
+        const html = await resp.text();
+        if (!html.includes('my-account') || html.includes('woocommerce-checkout')) {
+          dataSources.push('html_analysis');
+          htmlAnalyzed = true;
+          const requiredMatches = html.match(/<input[^>]*required[^>]*>/gi) || [];
+          const selectRequired = html.match(/<select[^>]*required[^>]*>/gi) || [];
+          requiredFieldCount = requiredMatches.length + selectRequired.length;
+          hasMultiStep = /wc-checkout-step|checkout-step|multi-step/i.test(html);
+          hasPhoneRequired = /name=["']billing_phone["'][^>]*required/i.test(html);
+          hasCompanyRequired = /name=["']billing_company["'][^>]*required/i.test(html);
+        }
+      }
+    } catch { /* checkout not accessible */ }
+  }
+
+  if (requiredFieldCount > 10) {
+    frictionScore += 1.5;
+    frictionChecks.push({ name: 'required_fields', value: requiredFieldCount, friction_points: 1.5, recommendation: `Reduce required fields from ${requiredFieldCount} to under 10` });
+  } else if (requiredFieldCount > 6) {
+    frictionScore += 1.0;
+    frictionChecks.push({ name: 'required_fields', value: requiredFieldCount, friction_points: 1.0, recommendation: 'Consider reducing required fields' });
+  } else {
+    frictionChecks.push({ name: 'required_fields', value: htmlAnalyzed ? requiredFieldCount : 'unknown', friction_points: 0, recommendation: null });
+  }
+
+  if (hasMultiStep) {
+    frictionScore += 1.0;
+    frictionChecks.push({ name: 'multi_step_checkout', value: true, friction_points: 1.0, recommendation: 'Consider single-page checkout for fewer steps' });
+  } else {
+    frictionChecks.push({ name: 'multi_step_checkout', value: false, friction_points: 0, recommendation: null });
+  }
+
+  if (hasPhoneRequired) {
+    frictionScore += 0.5;
+    frictionChecks.push({ name: 'phone_required', value: true, friction_points: 0.5, recommendation: 'Make phone field optional unless required for shipping' });
+  }
+  if (hasCompanyRequired) {
+    frictionScore += 0.5;
+    frictionChecks.push({ name: 'company_required', value: true, friction_points: 0.5, recommendation: 'Make company field optional for B2C stores' });
+  }
+
+  frictionScore = Math.round(frictionScore * 10) / 10;
+  const frictionGrade = frictionScore <= 3 ? 'Low' : frictionScore <= 6 ? 'Medium' : 'High';
+  const quickWins = frictionChecks.filter(c => c.friction_points > 0).sort((a, b) => b.friction_points - a.friction_points).map(c => c.recommendation).filter(Boolean);
+
+  result = json({ friction_score: frictionScore, friction_grade: frictionGrade, data_sources: dataSources, checks: frictionChecks, quick_wins: quickWins });
+  auditLog({ tool: name, action: 'audit_checkout_friction', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_get_product_performance'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  validateInput(args, { product_id: { type: 'number', required: true, min: 1 } });
+  const { product_id: perfProdId, period: perfPeriod = '30d' } = args;
+  const { url: baseUrl } = getActiveAuth();
+
+  const product = await wcApiCall(`/products/${perfProdId}`, {}, baseUrl);
+
+  const periodDays = perfPeriod === 'year' ? 365 : perfPeriod === '90d' ? 90 : 30;
+  const now = new Date();
+  const dateMax = now.toISOString().split('T')[0];
+  const dateMin = new Date(now.getTime() - periodDays * 86400000).toISOString().split('T')[0];
+  const prevDateMax = new Date(now.getTime() - periodDays * 86400000).toISOString().split('T')[0];
+  const prevDateMin = new Date(now.getTime() - periodDays * 2 * 86400000).toISOString().split('T')[0];
+
+  // Current period sales
+  let unitsSold = 0, revenue = 0, ordersCount = 0, refundsCount = 0;
+  try {
+    const orders = await wcApiCall(`/orders?product=${perfProdId}&after=${dateMin}T00:00:00&per_page=100&status=completed,processing,refunded`, {}, baseUrl);
+    if (Array.isArray(orders)) {
+      for (const o of orders) {
+        if (o.status === 'refunded') { refundsCount++; continue; }
+        ordersCount++;
+        for (const li of (o.line_items || [])) {
+          if (li.product_id === perfProdId || li.variation_id === perfProdId) {
+            unitsSold += li.quantity;
+            revenue += parseFloat(li.total || '0');
+          }
+        }
+      }
+    }
+  } catch {}
+
+  // Previous period for trend
+  let prevUnitsSold = 0, prevRevenue = 0;
+  try {
+    const prevOrders = await wcApiCall(`/orders?product=${perfProdId}&after=${prevDateMin}T00:00:00&before=${prevDateMax}T23:59:59&per_page=100&status=completed,processing`, {}, baseUrl);
+    if (Array.isArray(prevOrders)) {
+      for (const o of prevOrders) {
+        for (const li of (o.line_items || [])) {
+          if (li.product_id === perfProdId || li.variation_id === perfProdId) {
+            prevUnitsSold += li.quantity;
+            prevRevenue += parseFloat(li.total || '0');
+          }
+        }
+      }
+    }
+  } catch {}
+
+  const unitsDelta = prevUnitsSold > 0 ? Math.round((unitsSold - prevUnitsSold) / prevUnitsSold * 10000) / 100 : (unitsSold > 0 ? 100 : 0);
+  const revenueDelta = prevRevenue > 0 ? Math.round((revenue - prevRevenue) / prevRevenue * 10000) / 100 : (revenue > 0 ? 100 : 0);
+  const direction = Math.abs(unitsDelta) <= 5 ? 'stable' : unitsDelta > 0 ? 'up' : 'down';
+
+  // Top sellers rank
+  let rank = null;
+  try {
+    const topSellers = await wcApiCall(`/reports/top_sellers?period=month`, {}, baseUrl);
+    if (Array.isArray(topSellers)) {
+      const idx = topSellers.findIndex(t => t.product_id === perfProdId);
+      if (idx >= 0) rank = idx + 1;
+    }
+  } catch {}
+
+  const avgOrderValue = ordersCount > 0 ? Math.round(revenue / ordersCount * 100) / 100 : 0;
+  const refundRate = (ordersCount + refundsCount) > 0 ? Math.round(refundsCount / (ordersCount + refundsCount) * 10000) / 100 : 0;
+
+  result = json({
+    product: { id: product.id, name: product.name, sku: product.sku || '', status: product.status, stock_quantity: product.stock_quantity, price: product.price },
+    period: { start: dateMin, end: dateMax, days: periodDays },
+    metrics: { units_sold: unitsSold, revenue: Math.round(revenue * 100) / 100, orders_count: ordersCount, avg_order_value: avgOrderValue, refunds_count: refundsCount, refund_rate: refundRate },
+    trend: { units_sold_delta_pct: unitsDelta, revenue_delta_pct: revenueDelta, direction },
+    rank_in_top_sellers: rank,
+    ga4_note: 'Connect GA4 for view-to-purchase conversion rate'
+  });
+  auditLog({ tool: name, target: perfProdId, target_type: 'product', action: 'get_product_performance', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_audit_stock_alerts'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  const stockThreshold = args.threshold || 5;
+  const stockIncludeZero = args.include_zero_stock !== false;
+  const stockIncludeVars = args.include_variations !== false;
+  const { url: baseUrl } = getActiveAuth();
+
+  const outOfStock = [];
+  const lowStock = [];
+
+  // Fetch products page by page
+  let stockPage = 1;
+  let hasMore = true;
+  while (hasMore) {
+    const products = await wcApiCall(`/products?per_page=100&page=${stockPage}&status=publish`, {}, baseUrl);
+    if (!Array.isArray(products) || products.length === 0) break;
+
+    for (const p of products) {
+      if (p.manage_stock) {
+        if (p.stock_quantity === 0 || p.stock_status === 'outofstock') {
+          if (stockIncludeZero) {
+            let lastSaleDate = null;
+            try {
+              const recentOrders = await wcApiCall(`/orders?product=${p.id}&per_page=1&orderby=date&order=desc`, {}, baseUrl);
+              if (Array.isArray(recentOrders) && recentOrders[0]) lastSaleDate = recentOrders[0].date_created;
+            } catch {}
+            outOfStock.push({ id: p.id, name: p.name, sku: p.sku || '', type: p.type, parent_id: null, last_sale_date: lastSaleDate, admin_url: `${baseUrl.replace('/wp-json', '')}/wp-admin/post.php?post=${p.id}&action=edit` });
+          }
+        } else if (p.stock_quantity !== null && p.stock_quantity <= stockThreshold) {
+          let lastSaleDate = null;
+          try {
+            const recentOrders = await wcApiCall(`/orders?product=${p.id}&per_page=1&orderby=date&order=desc`, {}, baseUrl);
+            if (Array.isArray(recentOrders) && recentOrders[0]) lastSaleDate = recentOrders[0].date_created;
+          } catch {}
+          lowStock.push({ id: p.id, name: p.name, sku: p.sku || '', type: p.type, stock_quantity: p.stock_quantity, threshold: stockThreshold, last_sale_date: lastSaleDate, admin_url: `${baseUrl.replace('/wp-json', '')}/wp-admin/post.php?post=${p.id}&action=edit` });
+        }
+      }
+
+      // Variations
+      if (stockIncludeVars && p.type === 'variable' && p.variations && p.variations.length > 0) {
+        try {
+          const vars = await wcApiCall(`/products/${p.id}/variations?per_page=100`, {}, baseUrl);
+          if (Array.isArray(vars)) {
+            for (const v of vars) {
+              if (!v.manage_stock) continue;
+              if (v.stock_quantity === 0 || v.stock_status === 'outofstock') {
+                if (stockIncludeZero) outOfStock.push({ id: v.id, name: `${p.name} - ${(v.attributes || []).map(a => a.option).join(', ')}`, sku: v.sku || '', type: 'variation', parent_id: p.id, last_sale_date: null, admin_url: `${baseUrl.replace('/wp-json', '')}/wp-admin/post.php?post=${p.id}&action=edit` });
+              } else if (v.stock_quantity !== null && v.stock_quantity <= stockThreshold) {
+                lowStock.push({ id: v.id, name: `${p.name} - ${(v.attributes || []).map(a => a.option).join(', ')}`, sku: v.sku || '', type: 'variation', stock_quantity: v.stock_quantity, threshold: stockThreshold, last_sale_date: null, admin_url: `${baseUrl.replace('/wp-json', '')}/wp-admin/post.php?post=${p.id}&action=edit` });
+              }
+            }
+          }
+        } catch {}
+      }
+    }
+
+    if (products.length < 100) break;
+    stockPage++;
+    if (stockPage > 5) break; // safety limit
+  }
+
+  result = json({ out_of_stock: outOfStock, low_stock: lowStock, summary: { out_of_stock_count: outOfStock.length, low_stock_count: lowStock.length, estimated_lost_revenue: 'N/A (connect GA4 for traffic data)' }, alert: outOfStock.length > 0 });
+  auditLog({ tool: name, action: 'audit_stock_alerts', target_type: 'product', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_find_duplicate_products'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  const dupThreshold = args.similarity_threshold || 0.8;
+  const dupCheckSku = args.check_sku !== false;
+  const dupCheckTitle = args.check_title !== false;
+  const dupCheckSlug = args.check_slug !== false;
+  const dupLimit = Math.min(args.limit || 200, 500);
+  const { url: baseUrl } = getActiveAuth();
+
+  let dupProducts = [];
+  let dupPage = 1;
+  while (dupProducts.length < dupLimit) {
+    const perPage = Math.min(100, dupLimit - dupProducts.length);
+    const batch = await wcApiCall(`/products?per_page=${perPage}&page=${dupPage}`, {}, baseUrl);
+    if (!Array.isArray(batch) || batch.length === 0) break;
+    dupProducts.push(...batch);
+    if (batch.length < perPage) break;
+    dupPage++;
+  }
+
+  // Levenshtein distance
+  function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0) return n;
+    if (n === 0) return m;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++) dp[i][0] = i;
+    for (let j = 0; j <= n; j++) dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      }
+    }
+    return dp[m][n];
+  }
+  function similarity(a, b) {
+    if (!a || !b) return 0;
+    const al = a.toLowerCase(), bl = b.toLowerCase();
+    if (al === bl) return 1;
+    return 1 - levenshtein(al, bl) / Math.max(al.length, bl.length);
+  }
+
+  // Union-Find
+  const parent = {};
+  function find(x) { if (parent[x] !== x) parent[x] = find(parent[x]); return parent[x]; }
+  function union(x, y) { parent[find(x)] = find(y); }
+  dupProducts.forEach(p => { parent[p.id] = p.id; });
+
+  const matchInfo = {};
+
+  // SKU exact matches
+  if (dupCheckSku) {
+    const skuMap = {};
+    for (const p of dupProducts) {
+      if (p.sku && p.sku.trim()) {
+        if (skuMap[p.sku]) { union(p.id, skuMap[p.sku].id); matchInfo[`${p.id}-${skuMap[p.sku].id}`] = { type: 'sku_exact', score: 1.0 }; }
+        else skuMap[p.sku] = p;
+      }
+    }
+  }
+
+  // Title and slug similarity
+  for (let i = 0; i < dupProducts.length; i++) {
+    for (let j = i + 1; j < dupProducts.length; j++) {
+      const a = dupProducts[i], b = dupProducts[j];
+      if (dupCheckTitle) {
+        const titleSim = similarity(a.name, b.name);
+        if (titleSim >= dupThreshold) { union(a.id, b.id); matchInfo[`${a.id}-${b.id}`] = { type: 'title_similar', score: titleSim }; }
+      }
+      if (dupCheckSlug) {
+        const slugSim = similarity(a.slug, b.slug);
+        if (slugSim >= dupThreshold) { union(a.id, b.id); if (!matchInfo[`${a.id}-${b.id}`]) matchInfo[`${a.id}-${b.id}`] = { type: 'slug_similar', score: slugSim }; }
+      }
+    }
+  }
+
+  // Group by root
+  const groups = {};
+  for (const p of dupProducts) {
+    const root = find(p.id);
+    if (!groups[root]) groups[root] = [];
+    groups[root].push(p);
+  }
+
+  const dupGroups = [];
+  let groupId = 1;
+  for (const [root, members] of Object.entries(groups)) {
+    if (members.length < 2) continue;
+    const types = new Set();
+    let maxScore = 0;
+    for (const [key, info] of Object.entries(matchInfo)) {
+      const ids = key.split('-').map(Number);
+      if (members.some(m => ids.includes(m.id))) { types.add(info.type); maxScore = Math.max(maxScore, info.score); }
+    }
+    const matchType = types.size > 1 ? 'multiple' : [...types][0] || 'unknown';
+    dupGroups.push({
+      group_id: groupId++,
+      match_type: matchType,
+      similarity_score: Math.round(maxScore * 100) / 100,
+      products: members.map(p => ({ id: p.id, name: p.name, sku: p.sku || '', slug: p.slug, status: p.status, price: p.price, admin_url: `${baseUrl.replace('/wp-json', '')}/wp-admin/post.php?post=${p.id}&action=edit` })),
+      recommendation: `Keep ID ${members[0].id}, review/delete others`
+    });
+    if (dupGroups.length >= 50) break;
+  }
+
+  const totalDups = dupGroups.reduce((s, g) => s + g.products.length, 0);
+  result = json({ duplicate_groups: dupGroups, summary: { total_groups: dupGroups.length, total_duplicates: totalDups, products_analyzed: dupProducts.length }, ...(dupGroups.length >= 50 ? { note: 'Showing top 50 groups' } : {}) });
+  auditLog({ tool: name, action: 'find_duplicate_products', target_type: 'product', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_audit_pricing_consistency'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  const priceIncludeDrafts = args.include_drafts || false;
+  const priceIncludeVars = args.include_variations !== false;
+  const { url: baseUrl } = getActiveAuth();
+
+  const inconsistencies = [];
+  let totalChecked = 0;
+  let cleanCount = 0;
+  const summary = { critical: 0, high: 0, medium: 0, low: 0, products_with_issues: 0, total_checked: 0 };
+
+  let pricePage = 1;
+  let priceHasMore = true;
+  while (priceHasMore) {
+    const status = priceIncludeDrafts ? 'any' : 'publish';
+    const products = await wcApiCall(`/products?per_page=100&page=${pricePage}&status=${status}`, {}, baseUrl);
+    if (!Array.isArray(products) || products.length === 0) break;
+
+    for (const p of products) {
+      totalChecked++;
+      let hasIssue = false;
+
+      const checkPricing = (id, name, varId, regular, sale, onSale, dateSaleEnd) => {
+        const rp = parseFloat(regular);
+        const sp = parseFloat(sale);
+
+        if (p.type === 'simple' || varId) {
+          if ((!regular || regular === '') && p.status === 'publish') {
+            inconsistencies.push({ product_id: id, product_name: name, variation_id: varId, type: 'empty_price', severity: 'critical', detail: 'Published product with empty price', current_values: { regular_price: regular, sale_price: sale, on_sale: onSale }, recommendation: 'Set a regular price or move to draft' });
+            summary.critical++; hasIssue = true;
+          }
+        }
+
+        if (sale && sale !== '' && !isNaN(sp)) {
+          if (!isNaN(rp) && sp >= rp) {
+            inconsistencies.push({ product_id: id, product_name: name, variation_id: varId, type: 'sale_gte_regular', severity: 'critical', detail: `Sale price (${sp}) >= regular price (${rp})`, current_values: { regular_price: regular, sale_price: sale, on_sale: onSale }, recommendation: 'Sale price should be lower than regular price' });
+            summary.critical++; hasIssue = true;
+          } else if (sp === 0 && onSale) {
+            inconsistencies.push({ product_id: id, product_name: name, variation_id: varId, type: 'zero_sale_price', severity: 'critical', detail: 'Sale price is 0 on a product marked on sale', current_values: { regular_price: regular, sale_price: sale, on_sale: onSale }, recommendation: 'Set a valid sale price or remove the sale' });
+            summary.critical++; hasIssue = true;
+          } else if (!isNaN(rp) && rp > 0 && sp > rp * 0.9) {
+            inconsistencies.push({ product_id: id, product_name: name, variation_id: varId, type: 'minimal_discount', severity: 'high', detail: `Discount less than 10% (sale: ${sp}, regular: ${rp})`, current_values: { regular_price: regular, sale_price: sale, on_sale: onSale }, recommendation: 'Review — minimal discounts may confuse customers' });
+            summary.high++; hasIssue = true;
+          }
+        }
+
+        if (rp === 0 && p.price !== '0' && p.price !== '') {
+          inconsistencies.push({ product_id: id, product_name: name, variation_id: varId, type: 'zero_regular_price', severity: 'medium', detail: 'Regular price is 0', current_values: { regular_price: regular, sale_price: sale, on_sale: onSale }, recommendation: 'Verify this is intentionally free' });
+          summary.medium++; hasIssue = true;
+        }
+
+        if (dateSaleEnd) {
+          const endDate = new Date(dateSaleEnd);
+          if (endDate < new Date() && onSale) {
+            inconsistencies.push({ product_id: id, product_name: name, variation_id: varId, type: 'expired_sale', severity: 'low', detail: `Sale ended ${dateSaleEnd} but still marked on sale`, current_values: { regular_price: regular, sale_price: sale, on_sale: onSale }, recommendation: 'Remove expired sale or update end date' });
+            summary.low++; hasIssue = true;
+          }
+        }
+      };
+
+      checkPricing(p.id, p.name, null, p.regular_price, p.sale_price, p.on_sale, p.date_on_sale_to);
+
+      // Variations
+      if (priceIncludeVars && p.type === 'variable' && p.variations && p.variations.length > 0) {
+        try {
+          const vars = await wcApiCall(`/products/${p.id}/variations?per_page=100`, {}, baseUrl);
+          if (Array.isArray(vars)) {
+            for (const v of vars) {
+              totalChecked++;
+              checkPricing(p.id, p.name, v.id, v.regular_price, v.sale_price, v.on_sale, v.date_on_sale_to);
+              if (!v.regular_price && !v.sale_price) {
+                inconsistencies.push({ product_id: p.id, product_name: p.name, variation_id: v.id, type: 'variation_no_price', severity: 'high', detail: 'Variation has no price set', current_values: { regular_price: v.regular_price, sale_price: v.sale_price, on_sale: v.on_sale }, recommendation: 'Set a price for this variation' });
+                summary.high++; hasIssue = true;
+              }
+            }
+          }
+        } catch {}
+      }
+
+      if (!hasIssue) cleanCount++;
+    }
+
+    if (products.length < 100) break;
+    pricePage++;
+    if (pricePage > 5) break;
+  }
+
+  summary.total_checked = totalChecked;
+  summary.products_with_issues = totalChecked - cleanCount;
+  result = json({ inconsistencies, summary, clean_count: cleanCount });
+  auditLog({ tool: name, action: 'audit_pricing_consistency', target_type: 'product', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wc_update_product'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, sanitizeParams, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 }, status: { type: 'string', enum: ['publish', 'draft', 'private'] } });
+  const { id, name: prodName, description, short_description, regular_price, sale_price, status: prodStatus, price_guardrail_confirmed = false } = args;
+  const { url: baseUrl } = getActiveAuth();
+
+  // Price guardrail check
+  if (regular_price !== undefined || sale_price !== undefined) {
+    const current = await wcApiCall(`/products/${id}`, {}, baseUrl);
+    const checks = [];
+    if (regular_price !== undefined) checks.push({ label: 'regular_price', current: parseFloat(current.regular_price), proposed: parseFloat(regular_price) });
+    if (sale_price !== undefined && sale_price !== '') checks.push({ label: 'sale_price', current: parseFloat(current.sale_price || '0'), proposed: parseFloat(sale_price) });
+
+    for (const chk of checks) {
+      if (!isNaN(chk.current) && chk.current > 0) {
+        const changePct = Math.round(Math.abs(chk.proposed - chk.current) / chk.current * 10000) / 100;
+        if (changePct > 20 && !price_guardrail_confirmed) {
+          auditLog({ tool: name, target: id, target_type: 'product', action: 'update_product', status: 'blocked', latency_ms: Date.now() - t0, params: sanitizeParams(args), error: 'PRICE_GUARDRAIL_TRIGGERED' });
+          return { content: [{ type: 'text', text: JSON.stringify({ error: 'PRICE_GUARDRAIL_TRIGGERED', message: `Price change of ${changePct}% exceeds 20% threshold. Call wc_price_guardrail first, then retry with price_guardrail_confirmed: true`, current_price: chk.current, new_price: chk.proposed, change_percent: changePct }, null, 2) }], isError: true };
+        }
+      }
+    }
+  }
+
+  const updateData = {};
+  if (prodName !== undefined) updateData.name = prodName;
+  if (description !== undefined) updateData.description = description;
+  if (short_description !== undefined) updateData.short_description = short_description;
+  if (regular_price !== undefined) updateData.regular_price = regular_price;
+  if (sale_price !== undefined) updateData.sale_price = sale_price;
+  if (prodStatus !== undefined) updateData.status = prodStatus;
+
+  const updated = await wcApiCall(`/products/${id}`, { method: 'PUT', body: JSON.stringify(updateData) }, baseUrl);
+  const auditParams = { id, ...updateData };
+  if (regular_price !== undefined || sale_price !== undefined) auditParams.price_change = true;
+  result = json({ success: true, message: `Product ${id} updated`, product: { id: updated.id, name: updated.name, status: updated.status, regular_price: updated.regular_price, sale_price: updated.sale_price, permalink: updated.permalink } });
+  auditLog({ tool: name, target: id, target_type: 'product', action: 'update_product', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(auditParams) });
+  return result;
+};
+handlers['wc_update_stock'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 }, stock_quantity: { type: 'number', required: true, min: 0 }, variation_id: { type: 'number', min: 1 } });
+  const { id, stock_quantity, variation_id } = args;
+  const { url: baseUrl } = getActiveAuth();
+
+  // Fetch current product/variation for audit
+  let previousStock;
+  if (variation_id) {
+    const currentVar = await wcApiCall(`/products/${id}/variations/${variation_id}`, {}, baseUrl);
+    previousStock = currentVar.stock_quantity;
+    await wcApiCall(`/products/${id}/variations/${variation_id}`, { method: 'PUT', body: JSON.stringify({ stock_quantity, manage_stock: true }) }, baseUrl);
+  } else {
+    const currentProd = await wcApiCall(`/products/${id}`, {}, baseUrl);
+    previousStock = currentProd.stock_quantity;
+    await wcApiCall(`/products/${id}`, { method: 'PUT', body: JSON.stringify({ stock_quantity, manage_stock: true }) }, baseUrl);
+  }
+
+  result = json({ success: true, message: variation_id ? `Variation ${variation_id} stock updated` : `Product ${id} stock updated`, product_id: id, variation_id: variation_id || null, previous_stock: previousStock, new_stock: stock_quantity });
+  auditLog({ tool: name, target: id, target_type: 'product', action: 'update_stock', status: 'success', latency_ms: Date.now() - t0, params: { id, variation_id: variation_id || null, previous_stock: previousStock, new_stock: stock_quantity } });
+  return result;
+};
+handlers['wc_update_order_status'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wcApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 }, status: { type: 'string', required: true } });
+  const { id, status: newStatus, note } = args;
+  const { url: baseUrl } = getActiveAuth();
+
+  const VALID_TRANSITIONS = {
+    'pending': ['processing', 'cancelled', 'on-hold'],
+    'processing': ['completed', 'cancelled', 'refunded', 'on-hold'],
+    'on-hold': ['processing', 'cancelled'],
+    'completed': ['refunded'],
+    'cancelled': [],
+    'refunded': [],
+    'failed': ['processing', 'cancelled']
+  };
+
+  const order = await wcApiCall(`/orders/${id}`, {}, baseUrl);
+  const currentStatus = order.status;
+  const validNext = VALID_TRANSITIONS[currentStatus];
+
+  if (validNext === undefined) {
+    auditLog({ tool: name, target: id, target_type: 'order', action: 'update_order_status', status: 'error', latency_ms: Date.now() - t0, params: { current_status: currentStatus, requested_status: newStatus }, error: 'UNKNOWN_STATUS' });
+    return { content: [{ type: 'text', text: JSON.stringify({ error: 'UNKNOWN_STATUS', current_status: currentStatus, requested_status: newStatus, message: `Unknown current status "${currentStatus}"` }, null, 2) }], isError: true };
+  }
+
+  if (!validNext.includes(newStatus)) {
+    auditLog({ tool: name, target: id, target_type: 'order', action: 'update_order_status', status: 'error', latency_ms: Date.now() - t0, params: { current_status: currentStatus, requested_status: newStatus }, error: 'INVALID_TRANSITION' });
+    return { content: [{ type: 'text', text: JSON.stringify({ error: 'INVALID_TRANSITION', current_status: currentStatus, requested_status: newStatus, valid_transitions: validNext, message: validNext.length === 0 ? `Order status "${currentStatus}" is terminal — no transitions allowed` : `Cannot transition from "${currentStatus}" to "${newStatus}". Valid: ${validNext.join(', ')}` }, null, 2) }], isError: true };
+  }
+
+  await wcApiCall(`/orders/${id}`, { method: 'PUT', body: JSON.stringify({ status: newStatus }) }, baseUrl);
+
+  let noteAdded = false;
+  if (note) {
+    await wcApiCall(`/orders/${id}/notes`, { method: 'POST', body: JSON.stringify({ note, customer_note: false }) }, baseUrl);
+    noteAdded = true;
+  }
+
+  result = json({ success: true, message: `Order ${id} status updated: ${currentStatus} → ${newStatus}`, order_id: id, previous_status: currentStatus, new_status: newStatus, note_added: noteAdded });
+  auditLog({ tool: name, target: id, target_type: 'order', action: 'update_order_status', status: 'success', latency_ms: Date.now() - t0, params: { previous_status: currentStatus, new_status: newStatus, note_added: noteAdded } });
+  return result;
+};