@shoppexio/mcp-commerce-server 0.7.0 → 0.8.0

package/README.md

@@ -2,18 +2,20 @@
 
 Model Context Protocol server for Shoppex commerce operations.
 
-Connect Claude Desktop, Claude Code, Cursor, Windsurf, or Codex to your Shoppex store. Read products, orders, customers, and analytics, create payment links, manage coupons, and create or update products — directly from chat.
+Connect Claude Desktop, Claude Code, Cursor, Windsurf, or Codex to your Shoppex store — manage products, orders, customers, coupons, payment links, subscriptions, tickets, licenses, blacklist, analytics, and more. 51 tools, 5 resources, 6 workflow prompts.
 
 ## Install
 
+The fastest way is the one-shot installer:
+
 ```bash
-npm install -g @shoppexio/mcp-commerce-server
+npx @shoppexio/mcp-shoppex install --api-key shx_your_dev_api_key
 ```
 
-Or run without installing:
+That installs both commerce and theme MCPs. Or install commerce standalone:
 
 ```bash
-npx -y @shoppexio/mcp-commerce-server
+npm install -g @shoppexio/mcp-commerce-server
 ```
 
 ## Claude Desktop
@@ -34,63 +36,131 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 }
 ```
 
-Restart Claude Desktop. Tools accept a `shop_api_key` argument on each call; the env var is available for clients that forward env to tool arguments.
+Restart Claude Desktop.
 
-## Cursor / Windsurf / Other
+## Cursor / Windsurf / Claude Code
 
-Any MCP client with stdio transport works. Set the same env var and point to `shoppex-mcp-commerce-server` as the command.
+Any MCP client with stdio transport works. Set the same env var and point to `shoppex-mcp-commerce-server` as the command — or use the `@shoppexio/cli` helper: `shoppex mcp install --client cursor|windsurf|claude-code`.
 
-## Tools (12)
+## Tools (51)
 
-### Read
+### Products
+- `products_list` — search or list products
+- `products_get` — fetch one by id/uniqid
+- `products_create` — create (service, serials, dynamic, file)
+- `products_update` — price, title, gateways, stock, visibility
+- `products_delete` — soft-delete
+- `products_duplicate` — clone
+- `products_upload_serials` — bulk-add license keys
 
-| Tool | Purpose |
-|------|---------|
-| `products.list` | Search or list products |
-| `products.get` | Fetch one product by id or uniqid |
-| `orders.list` | List recent orders, optionally filtered |
-| `orders.get` | Fetch one order with line items |
-| `customers.get` | Fetch a customer by id or email |
-| `coupons.list` | List active coupons |
-| `analytics.revenue` | Revenue totals for a date range |
+### Orders
+- `orders_list` — list, filter by status/email
+- `orders_get` — fetch one with line items
+- `orders_update` — notes, internal notes
+- `orders_fulfill` — mark delivered
 
-### Write
+### Customers
+- `customers_list` — list with filter expressions
+- `customers_get` — fetch by id or email
+- `customers_wallet_credit` — credit wallet balance
 
-| Tool | Purpose |
-|------|---------|
-| `products.create` | Create a product (service, serials, dynamic, file) |
-| `products.update` | Update a product's price, title, gateways, stock, visibility |
-| `coupons.create` | Create a coupon (percentage or fixed discount) |
-| `coupons.update` | Update an existing coupon |
-| `payment_links.create` | Create a payment link |
+### Invoices
+- `invoices_list` — filter by status, customer
+- `invoices_get` — fetch one
 
-## Required Scopes
+### Coupons
+- `coupons_list` — list active
+- `coupons_get` — fetch one
+- `coupons_create` — percentage or fixed
+- `coupons_update` — update any field
+- `coupons_delete` — remove
 
-Your Shoppex Dev API key needs the scopes matching the tools you use (e.g. `products.read`, `products.write`, `orders.read`, `coupons.write`, `analytics.read`, `payment_links.write`).
+### Payment Links
+- `payment_links_list` / `_get` / `_update` / `_delete` / `_toggle`
+- `payment_links_create` — one-click checkout URLs
 
-Create one at [dashboard.shoppex.io/developer/api](https://dashboard.shoppex.io/developer/api).
+### Categories
+- `categories_list` / `_create` / `_update`
 
-## Environment Variables
+### Webhooks
+- `webhooks_list` / `_create`
 
-| Variable | Required | Default |
-|----------|----------|---------|
-| `SHOPPEX_SHOP_API_KEY` | passed per call, or set here | — |
-| `SHOPPEX_API_BASE_URL` | no | `https://api.shoppex.io` |
-| `SHOPPEX_DEV_API_TIMEOUT_MS` | no | `10000` |
+### Tickets (support inbox)
+- `tickets_list` / `_get` / `_create` / `_reply` / `_close`
+
+### Disputes
+- `disputes_list` / `_get`
+
+### Licenses
+- `licenses_list` / `_get` / `_update` (revoke/extend/reset HWID locks)
+
+### Subscriptions
+- `subscriptions_list` / `_cancel`
+
+### Affiliates
+- `affiliates_list`
+
+### Blacklist
+- `blacklist_list` / `_add` / `_remove`
+
+### Analytics
+- `analytics_revenue` — revenue totals
+- `analytics_reports_list` — custom reports
+- `analytics_report_generate` — re-generate a report
+
+## Resources (5)
 
-## Example Prompts
+Claude Desktop surfaces these as attachable context documents. Drag them into any chat to ground the conversation in live shop data:
 
-Once connected in Claude Desktop:
+| URI | What |
+|------|------|
+| `shoppex://products` | Full product catalog with variants |
+| `shoppex://orders/recent` | Last 50 orders |
+| `shoppex://analytics/summary` | MTD revenue snapshot |
+| `shoppex://categories` | Category tree |
+| `shoppex://tickets/open` | Open support tickets |
+
+## Prompts (6)
+
+Pre-built workflows available as slash commands:
+
+| Prompt | What it does |
+|--------|--------------|
+| `/shoppex_daily_brief` | Morning summary: revenue, orders, attention items |
+| `/shoppex_launch_product` | End-to-end product launch (args: product_name, price) |
+| `/shoppex_fraud_check` | Suspicious-orders scan + blacklist suggestions |
+| `/shoppex_weekly_recap` | 7-day performance recap |
+| `/shoppex_customer_care` | Full customer timeline + draft reply (args: email) |
+| `/shoppex_theme_refresh` | Active-theme structural review |
+
+## Example prompts
 
 - "Create a Discord Nitro 3-month product for $14.99 paid in crypto."
 - "Show me this month's top 10 customers by revenue."
 - "Generate a 20% off coupon for my Discord members, valid until end of month."
 - "Update the price of product `prd_abc123` to $12.99."
-- "Make a payment link for a $50 USDT one-time purchase."
+- "Refund customer alice@example.com for invoice `inv_xyz`."
+- "Are there any fraud patterns in the last 48h?"
+- `/shoppex_daily_brief`
+
+## Environment Variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SHOPPEX_SHOP_API_KEY` | yes (or passed per call) | — |
+| `SHOPPEX_API_BASE_URL` | no | `https://api.shoppex.io` |
+| `SHOPPEX_DEV_API_TIMEOUT_MS` | no | `10000` |
+
+Create an API key at [dashboard.shoppex.io/developer/api](https://dashboard.shoppex.io/developer/api).
 
 ## Companion
 
-Pair with [`@shoppexio/mcp-theme-server`](https://www.npmjs.com/package/@shoppexio/mcp-theme-server) for storefront theme operations.
+Pair with [`@shoppexio/mcp-theme-server`](https://www.npmjs.com/package/@shoppexio/mcp-theme-server) for storefront theme operations including `theme_ai_apply` (natural-language theme editing).
+
+## Agent Templates
+
+Paste-ready agent personalities (customer care, product launch, fraud investigator, analyst, theme editor):
+[`docs/agents/`](https://github.com/ShoppexIO/shoppex/tree/main/docs/agents)
 
 ## Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/mcp-commerce-server",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Shoppex MCP server for commerce operations over the Dev API",
   "type": "module",
   "repository": {
@@ -47,6 +47,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
-    "zod": "^4.1.12"
+    "zod": "^4.3.6"
   }
 }

package/src/server.mjs

@@ -435,9 +435,15 @@ export class ShoppexCommerceDevApiClient {
   }
 }
 
+// SECURITY: `api_base_url` is intentionally NOT a tool argument.
+// The Shoppex shop API bearer token is attached to every request, so the
+// destination origin must never be chosen by an (untrusted) tool caller —
+// that would allow exfiltrating the credential to an attacker-controlled host
+// (SSRF / credential disclosure, CWE-918/CWE-200). The API base URL is resolved
+// solely from server-side env (`SHOPPEX_API_BASE_URL`/`API_URL`) via
+// `resolveBaseUrl`, which the operator controls, not the caller.
 const BaseToolSchema = {
   shop_api_key: z.string().trim().min(1).optional(),
-  api_base_url: z.string().trim().url().optional(),
 };
 
 function resolveShopApiKey(explicitValue) {
@@ -457,9 +463,10 @@ function resolveShopApiKey(explicitValue) {
 }
 
 function createClient(args) {
+  // Do not pass any caller-supplied base URL here. The destination origin is
+  // resolved from server env only (see BaseToolSchema security note).
   return new ShoppexCommerceDevApiClient({
     shopApiKey: resolveShopApiKey(args.shop_api_key),
-    apiBaseUrl: args.api_base_url,
   });
 }
 
@@ -761,39 +768,43 @@ export function createCommerceToolCatalog() {
     },
     {
       name: 'categories_create',
-      description: 'Create a product category.',
+      description: 'Create a product category. Fields match POST /dev/v1/categories.',
       inputSchema: {
         ...BaseToolSchema,
-        name: z.string().trim().min(1).max(128),
-        description: z.string().optional(),
-        parent_id: z.string().trim().min(1).optional().nullable(),
-        image_id: z.string().trim().min(1).optional().nullable(),
+        title: z.string().trim().min(1).max(64),
+        unlisted: z.boolean().optional(),
+        products_bound: z.array(z.string().trim().min(1)).optional(),
+        groups_bound: z.array(z.string().trim().min(1)).optional(),
+        sort_priority: z.number().int().optional(),
       },
       execute: async (args) => {
-        const body = { name: args.name };
-        if (args.description !== undefined) body.description = args.description;
-        if (args.parent_id !== undefined) body.parent_id = args.parent_id;
-        if (args.image_id !== undefined) body.image_id = args.image_id;
+        const body = { title: args.title };
+        if (args.unlisted !== undefined) body.unlisted = args.unlisted;
+        if (args.products_bound !== undefined) body.products_bound = args.products_bound;
+        if (args.groups_bound !== undefined) body.groups_bound = args.groups_bound;
+        if (args.sort_priority !== undefined) body.sort_priority = args.sort_priority;
         return createClient(args).categoriesCreate(body);
       },
     },
     {
       name: 'categories_update',
-      description: 'Update a category by id. Only provided fields change.',
+      description: 'Update a category by uniqid. Only provided fields change. Uses the same field shape as categories_create.',
       inputSchema: {
         ...BaseToolSchema,
         category_id: z.string().trim().min(1),
-        name: z.string().trim().min(1).max(128).optional(),
-        description: z.string().optional(),
-        parent_id: z.string().trim().min(1).optional().nullable(),
-        image_id: z.string().trim().min(1).optional().nullable(),
+        title: z.string().trim().min(1).max(64).optional(),
+        unlisted: z.boolean().optional(),
+        products_bound: z.array(z.string().trim().min(1)).optional(),
+        groups_bound: z.array(z.string().trim().min(1)).optional(),
+        sort_priority: z.number().int().optional(),
       },
       execute: async (args) => {
         const body = {};
-        if (args.name !== undefined) body.name = args.name;
-        if (args.description !== undefined) body.description = args.description;
-        if (args.parent_id !== undefined) body.parent_id = args.parent_id;
-        if (args.image_id !== undefined) body.image_id = args.image_id;
+        if (args.title !== undefined) body.title = args.title;
+        if (args.unlisted !== undefined) body.unlisted = args.unlisted;
+        if (args.products_bound !== undefined) body.products_bound = args.products_bound;
+        if (args.groups_bound !== undefined) body.groups_bound = args.groups_bound;
+        if (args.sort_priority !== undefined) body.sort_priority = args.sort_priority;
         return createClient(args).categoriesUpdate(args.category_id, body);
       },
     },
@@ -899,18 +910,20 @@ export function createCommerceToolCatalog() {
       },
     },
     {
-      name: 'orders_update',
-      description: 'Update an order (notes, internal state). Only provided fields change.',
+      name: 'orders_set_affiliate',
+      description: 'Attribute an order to an affiliate after the fact. Backed by PATCH /dev/v1/orders/:id which is the affiliate-attribution endpoint. Provide one of affiliate_code, referral_code, or affiliate_id (pass null to clear an existing attribution).',
       inputSchema: {
         ...BaseToolSchema,
         order_id: z.string().trim().min(1),
-        notes: z.string().max(2000).optional().nullable(),
-        internal_note: z.string().max(2000).optional().nullable(),
+        affiliate_code: z.string().trim().optional().nullable(),
+        referral_code: z.string().trim().optional().nullable(),
+        affiliate_id: z.string().trim().optional().nullable(),
       },
       execute: async (args) => {
         const body = {};
-        if (args.notes !== undefined) body.notes = args.notes;
-        if (args.internal_note !== undefined) body.internal_note = args.internal_note;
+        if (args.affiliate_code !== undefined) body.affiliate_code = args.affiliate_code;
+        if (args.referral_code !== undefined) body.referral_code = args.referral_code;
+        if (args.affiliate_id !== undefined) body.affiliate_id = args.affiliate_id;
         return createClient(args).ordersUpdate(args.order_id, body);
       },
     },
@@ -930,19 +943,22 @@ export function createCommerceToolCatalog() {
     },
     {
       name: 'customers_wallet_credit',
-      description: 'Credit a customer wallet balance. Useful for refunds, goodwill credits, or promo grants.',
+      description: 'Credit a customer wallet balance. Useful for refunds, goodwill credits, or promo grants. Amount is a decimal string with up to 2 decimal places (e.g. "5.00"). Wallet currency is fixed to the shop default.',
       inputSchema: {
         ...BaseToolSchema,
         customer_id: z.string().trim().min(1),
-        amount: z.number().positive(),
-        currency: z.string().trim().min(3).max(8).default('USD'),
-        reason: z.string().max(255).optional(),
+        amount: z.string().regex(/^\d+(\.\d{1,2})?$/, 'Amount must be a positive decimal string (e.g. "5.00")'),
+        type: z.enum(['CREDIT', 'PROMO', 'ADJUSTMENT']).optional(),
+        description: z.string().max(500).optional(),
+        expires_at: z.string().datetime().optional(),
+      },
+      execute: async (args) => {
+        const body = { amount: args.amount };
+        if (args.type !== undefined) body.type = args.type;
+        if (args.description !== undefined) body.description = args.description;
+        if (args.expires_at !== undefined) body.expires_at = args.expires_at;
+        return createClient(args).customersWalletCredit(args.customer_id, body);
       },
-      execute: async (args) => createClient(args).customersWalletCredit(args.customer_id, {
-        amount: args.amount,
-        currency: args.currency,
-        reason: args.reason,
-      }),
     },
     {
       name: 'coupons_get',
@@ -970,26 +986,65 @@ export function createCommerceToolCatalog() {
     },
     {
       name: 'payment_links_update',
-      description: 'Update a payment link by uniqid. Only provided fields change.',
+      description: 'Update a payment link by uniqid. The backend expects a full create-style payload, so this tool reads the existing link, merges your overrides, and sends the merged result. Pass only the fields you want to change — the rest are preserved from the current link.',
       inputSchema: {
         ...BaseToolSchema,
         link_id: z.string().trim().min(1),
         name: z.string().trim().min(1).max(255).optional(),
+        type: z.enum(['PRODUCT', 'SUBSCRIPTION', 'SUBSCRIPTION_V2', 'LICENSE', 'PAY_WHAT_YOU_WANT', 'FIXED_PRICE']).optional(),
         description: z.string().max(255).optional().nullable(),
+        active: z.boolean().optional(),
         price: z.number().positive().optional(),
         currency: z.string().trim().min(3).max(8).optional(),
         gateways: z.array(z.string().trim().min(1)).optional(),
-        active: z.boolean().optional(),
+        product_ids: z.array(z.string().trim().min(1)).optional(),
+        cta: z.enum(['PAY', 'BOOK', 'DONATE', 'SUBSCRIBE']).optional(),
+        allow_discount_code: z.boolean().optional(),
+        require_customer_address: z.boolean().optional(),
+        require_customer_phone: z.boolean().optional(),
+        show_confirmation_page: z.boolean().optional(),
+        return_url: z.string().trim().url().optional().nullable(),
       },
       execute: async (args) => {
-        const body = {};
-        if (args.name !== undefined) body.name = args.name;
-        if (args.description !== undefined) body.description = args.description;
-        if (args.price !== undefined) body.price = args.price;
-        if (args.currency !== undefined) body.currency = args.currency;
-        if (args.gateways !== undefined) body.gateways = args.gateways.join(',');
-        if (args.active !== undefined) body.status = args.active;
-        return createClient(args).paymentLinksUpdate(args.link_id, body);
+        const client = createClient(args);
+        const existing = await client.paymentLinksGet(args.link_id);
+        if (!existing || typeof existing !== 'object') {
+          throw new ShoppexCommerceDevApiError(
+            `payment_links_update: payment link ${args.link_id} not found.`,
+            { code: 'not_found', retryable: false },
+          );
+        }
+        const cur = existing;
+        const body = {
+          uniqid: cur.uniqid ?? args.link_id,
+          name: args.name ?? cur.name,
+          type: args.type ?? cur.type,
+          description: args.description !== undefined ? args.description : cur.description ?? null,
+          status: args.active !== undefined ? args.active : cur.status,
+          price: args.price !== undefined ? args.price : cur.price,
+          currency: args.currency ?? cur.currency ?? 'USD',
+          gateways: args.gateways !== undefined
+            ? args.gateways.join(',')
+            : Array.isArray(cur.gateways) ? cur.gateways.join(',') : (cur.gateways ?? ''),
+          products_ids: args.product_ids !== undefined
+            ? args.product_ids.join(',')
+            : Array.isArray(cur.products_ids) ? cur.products_ids.join(',') : (cur.products_ids ?? ''),
+          cta: args.cta ?? cur.cta ?? 'PAY',
+          discount_code_allowed: args.allow_discount_code !== undefined
+            ? args.allow_discount_code
+            : (cur.discount_code_allowed ?? false),
+          customer_address_required: args.require_customer_address !== undefined
+            ? args.require_customer_address
+            : (cur.customer_address_required ?? false),
+          customer_phone_required: args.require_customer_phone !== undefined
+            ? args.require_customer_phone
+            : (cur.customer_phone_required ?? false),
+          show_confirmation_page: args.show_confirmation_page !== undefined
+            ? args.show_confirmation_page
+            : (cur.show_confirmation_page ?? true),
+          return_url: args.return_url !== undefined ? args.return_url : cur.return_url ?? null,
+        };
+        return client.paymentLinksUpdate(args.link_id, body);
       },
     },
     {
@@ -1029,22 +1084,21 @@ export function createCommerceToolCatalog() {
     },
     {
       name: 'tickets_create',
-      description: 'Create a new support ticket. Used when the merchant wants to proactively open a support conversation with a customer.',
+      description: 'Create a new support ticket. Email is the customer email; title is short (max 30 chars); message is the opening body. Optionally link an invoice.',
       inputSchema: {
         ...BaseToolSchema,
-        subject: z.string().trim().min(1).max(255),
-        message: z.string().trim().min(1),
-        customer_id: z.string().trim().min(1).optional(),
-        customer_email: z.string().trim().email().optional(),
+        email: z.string().trim().min(1),
+        title: z.string().trim().min(2).max(30),
+        message: z.string().trim().min(2).max(2000),
         invoice_id: z.string().trim().min(1).optional(),
-        order_id: z.string().trim().min(1).optional(),
       },
       execute: async (args) => {
-        const body = { subject: args.subject, message: args.message };
-        if (args.customer_id !== undefined) body.customer_id = args.customer_id;
-        if (args.customer_email !== undefined) body.customer_email = args.customer_email;
+        const body = {
+          email: args.email,
+          title: args.title,
+          message: args.message,
+        };
         if (args.invoice_id !== undefined) body.invoice_id = args.invoice_id;
-        if (args.order_id !== undefined) body.order_id = args.order_id;
         return createClient(args).ticketsCreate(body);
       },
     },
@@ -1114,21 +1168,23 @@ export function createCommerceToolCatalog() {
     },
     {
       name: 'licenses_update',
-      description: 'Update a license (revoke, extend validity, reset HWID/IP locks). Set active=false to revoke access.',
+      description: 'Update a license: set status (ACTIVE/SUSPENDED/REVOKED/EXPIRED), change the hardware-id binding, allowlist IPs, change activation limit, or update the expiry. Set status="REVOKED" to revoke access.',
       inputSchema: {
         ...BaseToolSchema,
         license_id: z.string().trim().min(1),
-        active: z.boolean().optional(),
-        valid_until: z.string().trim().optional().nullable(),
-        hwid_lock: z.string().trim().optional().nullable(),
-        ip_lock: z.string().trim().optional().nullable(),
+        status: z.enum(['ACTIVE', 'SUSPENDED', 'REVOKED', 'EXPIRED']).optional(),
+        hardware_id: z.string().trim().optional().nullable(),
+        allowed_ips: z.array(z.string().trim().min(1)).optional().nullable(),
+        max_uses: z.number().int().min(1).optional().nullable(),
+        expires_at: z.string().trim().optional().nullable(),
       },
       execute: async (args) => {
-        const body = {};
-        if (args.active !== undefined) body.active = args.active;
-        if (args.valid_until !== undefined) body.valid_until = args.valid_until;
-        if (args.hwid_lock !== undefined) body.hwid_lock = args.hwid_lock;
-        if (args.ip_lock !== undefined) body.ip_lock = args.ip_lock;
+        const body = { id: args.license_id };
+        if (args.status !== undefined) body.status = args.status;
+        if (args.hardware_id !== undefined) body.hardware_id = args.hardware_id;
+        if (args.allowed_ips !== undefined) body.allowed_ips = args.allowed_ips;
+        if (args.max_uses !== undefined) body.max_uses = args.max_uses;
+        if (args.expires_at !== undefined) body.expires_at = args.expires_at;
         return createClient(args).licensesUpdate(args.license_id, body);
       },
     },
@@ -1164,7 +1220,7 @@ export async function executeCommerceTool(toolName, args) {
 export function createCommerceMcpServer() {
   const server = new McpServer({
     name: 'shoppex-commerce',
-    version: '0.7.0',
+    version: '0.8.0',
   });
 
   for (const tool of createCommerceToolCatalog()) {