@shoppexio/mcp-commerce-server 0.6.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.6.0",
+  "version": "0.8.0",
   "description": "Shoppex MCP server for commerce operations over the Dev API",
   "type": "module",
   "repository": {
@@ -34,6 +34,8 @@
   "files": [
     "bin",
     "src/server.mjs",
+    "src/prompts.mjs",
+    "src/resources.mjs",
     "src/index.d.ts",
     "README.md"
   ],
@@ -45,6 +47,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
-    "zod": "^4.1.12"
+    "zod": "^4.3.6"
   }
 }

package/src/prompts.mjs

@@ -0,0 +1,168 @@
+/**
+ * MCP Prompts for Shoppex — curated multi-tool workflows that merchants
+ * invoke by name in their MCP client. Each prompt returns a user-message
+ * with a full instruction block that primes the LLM to run a pre-planned
+ * sequence of tool calls.
+ *
+ * Registration via `server.registerPrompt(name, {title, description, argsSchema}, cb)`.
+ */
+
+import * as z from 'zod/v4';
+
+function text(body) {
+  return { messages: [{ role: 'user', content: { type: 'text', text: body } }] };
+}
+
+export function registerShoppexPrompts(server) {
+  server.registerPrompt(
+    'shoppex_daily_brief',
+    {
+      title: 'Daily brief',
+      description:
+        'Summarise today\'s shop health: revenue, orders, failed payments, open tickets, new disputes. Produces an actionable morning brief.',
+    },
+    () => text(`Give me a concise morning brief for my Shoppex shop. Follow this order:
+
+1. Call analytics_revenue for the current month.
+2. Call orders_list with limit=10 to see the most recent orders.
+3. Call invoices_list with status="pending", limit=5.
+4. Call disputes_list with limit=5 (only flag if status=open).
+5. Call tickets_list with status="open", limit=5.
+
+Return a short markdown briefing with these sections:
+- **Revenue today / MTD** (use currency from the analytics response)
+- **Latest orders** (3 most recent, one line each)
+- **Attention items** — pending invoices over 24h, open disputes, open tickets
+- **Suggested next action** — one sentence, concrete
+
+Keep it under 150 words. Do not invent numbers — if a tool returned 0 items, say so.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_launch_product',
+    {
+      title: 'Launch a product',
+      description:
+        'End-to-end product launch: create the product, generate a launch coupon, and return a ready-to-send Discord/Telegram announcement.',
+      argsSchema: {
+        product_name: z.string().min(1),
+        price: z.string().min(1),
+        coupon_percent: z.string().min(1).optional(),
+      },
+    },
+    ({ product_name, price, coupon_percent }) => text(`Launch a new product called "${product_name}" priced at $${price}. Work in this order:
+
+1. Call products_create with { title: "${product_name}", price: ${price}, type: "SERVICE" }. Capture the returned uniqid.
+2. ${coupon_percent ? `Call coupons_create with { code: "LAUNCH${Math.round(Math.random() * 999)}", discount_value: ${coupon_percent}, discount_type: "PERCENTAGE" }.` : 'Skip coupon unless the user explicitly asks for one.'}
+3. Call payment_links_create for the new product so we have a single shareable checkout URL. Use name="${product_name} launch", type="PRODUCT", gateways=["STRIPE","CRYPTO"].
+
+After the tools run, produce:
+- A short confirmation in markdown ("Created …").
+- A ready-to-post Discord launch blurb (2-3 sentences, casual tone, include the payment link and the coupon code if created).
+
+Do NOT invent the uniqid or URL — use what the tools returned.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_fraud_check',
+    {
+      title: 'Fraud check',
+      description:
+        'Investigate suspicious orders: look at recent high-value orders, match them against the blacklist, and propose block/refund actions.',
+    },
+    () => text(`Run a fraud-risk scan on the shop. Work in this order:
+
+1. Call orders_list with limit=30.
+2. Call disputes_list with limit=20.
+3. Call blacklist_list with limit=50.
+
+Analyse the data and answer:
+- Any order whose customer email or IP is already on the blacklist? (exact match)
+- Any order with an unusually high value vs. the shop's typical order size?
+- Any order with a recent dispute against the same customer email?
+- Any order from a country/IP cluster that has disputes (>=2 in the last 30 days)?
+
+Return a markdown report:
+- **Risk score**: low / medium / high (overall)
+- **Flagged orders** (table: order id, customer, reason, suggested action)
+- **Recommended blacklist adds** (email/ip/country with reason)
+
+Do not execute block/refund automatically. End with: "Want me to add these to the blacklist? Confirm one-by-one."`),
+  );
+
+  server.registerPrompt(
+    'shoppex_weekly_recap',
+    {
+      title: 'Weekly recap',
+      description:
+        'Seven-day performance recap: revenue, top products, customer additions, operational health. Designed for founder/team standups.',
+    },
+    () => text(`Give me a 7-day recap for the shop. Work in this order:
+
+1. Call analytics_revenue for the last 7 days.
+2. Call orders_list with limit=50 (to estimate order volume).
+3. Call products_list with limit=20 to know the catalog.
+4. Call customers_list with limit=20 (most recent signups).
+5. Call invoices_list with status="paid", limit=20.
+
+Return a markdown recap with:
+- **Revenue (7d)** + YoY trend if data allows
+- **Top 3 products by order count**
+- **New customers this week** (count + 2-3 notable emails if VIP-like)
+- **Operational signals** (pending invoices, failed payments if visible)
+- **Focus for next week** — one concrete initiative
+
+Tone: factual, founder-facing, under 250 words.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_customer_care',
+    {
+      title: 'Customer care',
+      description:
+        'Look up a customer end-to-end: orders, invoices, subscriptions, licenses, tickets. Returns a full timeline plus a draft reply.',
+      argsSchema: {
+        email: z.string().email(),
+      },
+    },
+    ({ email }) => text(`Look up the full history for customer "${email}". Work in this order:
+
+1. Call customers_get with email="${email}".
+2. Call orders_list with customer_email="${email}", limit=20.
+3. Call invoices_list with customer_email="${email}", limit=10.
+4. Call licenses_list (then filter locally by the customer's id).
+5. Call subscriptions_list (then filter locally by the customer's id).
+
+Return a markdown report:
+- **Summary** (customer name/email, total spend, first-seen / last-seen)
+- **Timeline** (orders + tickets chronologically)
+- **Open issues** (active disputes, unresolved tickets, failed payments)
+- **Draft reply** — a ready-to-send support message that addresses likely concerns, signed as the shop
+
+Keep the draft reply polite, short, and actionable. Do not invent details the tools didn't return.`),
+  );
+
+  server.registerPrompt(
+    'shoppex_theme_refresh',
+    {
+      title: 'Theme refresh',
+      description:
+        'Guided mini-review of the shop\'s active theme: structure, sections, recent changes, publish readiness.',
+    },
+    () => text(`Do a theme-refresh review. Work in this order:
+
+1. Call theme_list to find the active theme for this shop (is_active=true).
+2. Call theme_inspect on the active theme to get sections, settings, tokens.
+3. Call theme_diff on the active theme to see draft vs. published state.
+4. Call theme_latest_run on the active theme to see the last build health.
+
+Return a markdown report:
+- **Active theme** (name, scheme, version)
+- **Section inventory** (list of sections + page count)
+- **Draft status** (any pending changes? any build errors?)
+- **Publish readiness** — safe to publish? what risks?
+- **Suggested improvements** — 2-3 concrete section-level tweaks (e.g. "Add a testimonials section above footer"). Keep them specific.
+
+Format: founder-facing, under 200 words.`),
+  );
+}

package/src/resources.mjs

@@ -0,0 +1,112 @@
+/**
+ * MCP Resources for Shoppex — cacheable read-only context documents the
+ * client can attach to a conversation (e.g. Claude Desktop "Attach" menu).
+ * Each resource fetches fresh data on read and returns JSON text.
+ *
+ * Registration via `server.registerResource(name, uri, { title, description, mimeType }, async () => ({ contents: [...] }))`.
+ */
+
+import { ShoppexCommerceDevApiClient } from './server.mjs';
+
+function resolveShopApiKey() {
+  const fromEnv = process.env.SHOPPEX_SHOP_API_KEY?.trim()
+    || process.env.SHOPPEX_API_KEY?.trim()
+    || process.env.SHOP_API_KEY?.trim();
+  if (!fromEnv) {
+    throw new Error('Shoppex resources require SHOPPEX_SHOP_API_KEY to be set.');
+  }
+  return fromEnv;
+}
+
+function buildClient() {
+  return new ShoppexCommerceDevApiClient({
+    shopApiKey: resolveShopApiKey(),
+    apiBaseUrl: process.env.SHOPPEX_API_BASE_URL?.trim()
+      || process.env.API_URL?.trim()
+      || 'https://api.shoppex.io',
+  });
+}
+
+function jsonResource(uri, value) {
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: 'application/json',
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  };
+}
+
+export function registerShoppexResources(server) {
+  server.registerResource(
+    'shoppex_products_catalog',
+    'shoppex://products',
+    {
+      title: 'Product catalog',
+      description: 'Current product catalog for the authenticated shop (up to 50 products, includes variants).',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().productsList({ limit: 50 });
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+
+  server.registerResource(
+    'shoppex_recent_orders',
+    'shoppex://orders/recent',
+    {
+      title: 'Recent orders',
+      description: '50 most recent orders across all statuses.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().ordersList({ limit: 50 });
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+
+  server.registerResource(
+    'shoppex_analytics_summary',
+    'shoppex://analytics/summary',
+    {
+      title: 'Analytics summary',
+      description: 'Month-to-date revenue totals and recent trends.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().analyticsRevenue({ currency: 'USD' });
+      return jsonResource(uri.href, data ?? {});
+    },
+  );
+
+  server.registerResource(
+    'shoppex_categories',
+    'shoppex://categories',
+    {
+      title: 'Category tree',
+      description: 'Full product category list for the shop.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().categoriesList();
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+
+  server.registerResource(
+    'shoppex_open_tickets',
+    'shoppex://tickets/open',
+    {
+      title: 'Open support tickets',
+      description: 'Tickets currently in status=open for the shop.',
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const data = await buildClient().ticketsList({ limit: 50, status: 'open' });
+      return jsonResource(uri.href, data ?? []);
+    },
+  );
+}

package/src/server.mjs

@@ -1,6 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod/v4';
+import { registerShoppexPrompts } from './prompts.mjs';
+import { registerShoppexResources } from './resources.mjs';
 
 const DEV_API_TIMEOUT_MS = Number.parseInt(process.env.SHOPPEX_DEV_API_TIMEOUT_MS ?? '10000', 10);
 
@@ -433,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) {
@@ -455,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,
   });
 }
 
@@ -759,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);
       },
     },
@@ -897,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);
       },
     },
@@ -928,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',
@@ -968,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);
       },
     },
     {
@@ -1027,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);
       },
     },
@@ -1112,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);
       },
     },
@@ -1162,7 +1220,7 @@ export async function executeCommerceTool(toolName, args) {
 export function createCommerceMcpServer() {
   const server = new McpServer({
     name: 'shoppex-commerce',
-    version: '0.1.0',
+    version: '0.8.0',
   });
 
   for (const tool of createCommerceToolCatalog()) {
@@ -1175,6 +1233,9 @@ export function createCommerceMcpServer() {
     });
   }
 
+  registerShoppexResources(server);
+  registerShoppexPrompts(server);
+
   return server;
 }