@shoppexio/mcp-commerce-server 0.5.0 → 0.6.0

package/README.md

@@ -1,3 +1,103 @@
 # @shoppexio/mcp-commerce-server
 
-Shoppex MCP server that exposes commerce tools over the Shoppex Dev API.
+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.
+
+## Install
+
+```bash
+npm install -g @shoppexio/mcp-commerce-server
+```
+
+Or run without installing:
+
+```bash
+npx -y @shoppexio/mcp-commerce-server
+```
+
+## Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "shoppex-commerce": {
+      "command": "npx",
+      "args": ["-y", "@shoppexio/mcp-commerce-server"],
+      "env": {
+        "SHOPPEX_SHOP_API_KEY": "shx_your_dev_api_key"
+      }
+    }
+  }
+}
+```
+
+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.
+
+## Cursor / Windsurf / Other
+
+Any MCP client with stdio transport works. Set the same env var and point to `shoppex-mcp-commerce-server` as the command.
+
+## Tools (12)
+
+### Read
+
+| 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 |
+
+### Write
+
+| 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 |
+
+## Required Scopes
+
+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`).
+
+Create one at [dashboard.shoppex.io/developer/api](https://dashboard.shoppex.io/developer/api).
+
+## Environment Variables
+
+| 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` |
+
+## Example Prompts
+
+Once connected in Claude Desktop:
+
+- "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."
+
+## Companion
+
+Pair with [`@shoppexio/mcp-theme-server`](https://www.npmjs.com/package/@shoppexio/mcp-theme-server) for storefront theme operations.
+
+## Docs
+
+- [Developer API Reference](https://docs.shoppex.io/api-reference/introduction)
+- [Quickstart](https://docs.shoppex.io/api-reference/quickstart)
+- [Authentication](https://docs.shoppex.io/api-reference/authentication)
+
+## License
+
+Proprietary. © Shoppex.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/mcp-commerce-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Shoppex MCP server for commerce operations over the Dev API",
   "type": "module",
   "repository": {

package/src/server.mjs

@@ -335,6 +335,102 @@ export class ShoppexCommerceDevApiClient {
       body: input,
     });
   }
+
+  ordersUpdate(orderId, input) {
+    return this.request('PATCH', `/dev/v1/orders/${encodeURIComponent(orderId)}`, { body: input });
+  }
+
+  ordersFulfill(orderId, input = {}) {
+    return this.request('POST', `/dev/v1/orders/${encodeURIComponent(orderId)}/fulfill`, { body: input });
+  }
+
+  customersWalletCredit(customerId, input) {
+    return this.request('POST', `/dev/v1/customers/${encodeURIComponent(customerId)}/wallet/credit`, { body: input });
+  }
+
+  couponsGet(couponId) {
+    return this.request('GET', `/dev/v1/coupons/${encodeURIComponent(couponId)}`);
+  }
+
+  couponsDelete(couponId) {
+    return this.request('DELETE', `/dev/v1/coupons/${encodeURIComponent(couponId)}`);
+  }
+
+  paymentLinksList() {
+    return this.request('GET', '/dev/v1/payment-links');
+  }
+
+  paymentLinksGet(linkId) {
+    return this.request('GET', `/dev/v1/payment-links/${encodeURIComponent(linkId)}`);
+  }
+
+  paymentLinksUpdate(linkId, input) {
+    return this.request('PATCH', `/dev/v1/payment-links/${encodeURIComponent(linkId)}`, { body: input });
+  }
+
+  paymentLinksDelete(linkId) {
+    return this.request('DELETE', `/dev/v1/payment-links/${encodeURIComponent(linkId)}`);
+  }
+
+  paymentLinksToggle(linkId, input = {}) {
+    return this.request('POST', `/dev/v1/payment-links/${encodeURIComponent(linkId)}/toggle`, { body: input });
+  }
+
+  ticketsList(input = {}) {
+    return this.request('GET', '/dev/v1/tickets', {
+      query: { limit: input.limit, status: input.status },
+    });
+  }
+
+  ticketsGet(ticketId) {
+    return this.request('GET', `/dev/v1/tickets/${encodeURIComponent(ticketId)}`);
+  }
+
+  ticketsCreate(input) {
+    return this.request('POST', '/dev/v1/tickets', { body: input });
+  }
+
+  ticketsReply(ticketId, input) {
+    return this.request('POST', `/dev/v1/tickets/${encodeURIComponent(ticketId)}/messages`, { body: input });
+  }
+
+  ticketsClose(ticketId) {
+    return this.request('POST', `/dev/v1/tickets/${encodeURIComponent(ticketId)}/close`);
+  }
+
+  blacklistList(input = {}) {
+    return this.request('GET', '/dev/v1/blacklist', {
+      query: { limit: input.limit, type: input.type },
+    });
+  }
+
+  blacklistAdd(input) {
+    return this.request('POST', '/dev/v1/blacklist', { body: input });
+  }
+
+  blacklistRemove(entryId) {
+    return this.request('DELETE', `/dev/v1/blacklist/${encodeURIComponent(entryId)}`);
+  }
+
+  disputesGet(disputeId) {
+    return this.request('GET', `/dev/v1/disputes/${encodeURIComponent(disputeId)}`);
+  }
+
+  licensesGet(licenseId) {
+    return this.request('GET', `/dev/v1/licenses/${encodeURIComponent(licenseId)}`);
+  }
+
+  licensesUpdate(licenseId, input) {
+    return this.request('PATCH', `/dev/v1/licenses/${encodeURIComponent(licenseId)}`, { body: input });
+  }
+
+  analyticsReportsList() {
+    return this.request('GET', '/dev/v1/analytics/reports');
+  }
+
+  analyticsReportGenerate(reportId) {
+    return this.request('POST', `/dev/v1/analytics/reports/${encodeURIComponent(reportId)}/generate`);
+  }
 }
 
 const BaseToolSchema = {
@@ -800,6 +896,252 @@ export function createCommerceToolCatalog() {
         return createClient(args).subscriptionsCancel(args.subscription_id, body);
       },
     },
+    {
+      name: 'orders_update',
+      description: 'Update an order (notes, internal state). Only provided fields change.',
+      inputSchema: {
+        ...BaseToolSchema,
+        order_id: z.string().trim().min(1),
+        notes: z.string().max(2000).optional().nullable(),
+        internal_note: z.string().max(2000).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;
+        return createClient(args).ordersUpdate(args.order_id, body);
+      },
+    },
+    {
+      name: 'orders_fulfill',
+      description: 'Mark an order as fulfilled. For service products, this confirms delivery; for key-based products, the keys have already been delivered but this marks the order manually.',
+      inputSchema: {
+        ...BaseToolSchema,
+        order_id: z.string().trim().min(1),
+        message: z.string().max(2000).optional(),
+      },
+      execute: async (args) => {
+        const body = {};
+        if (args.message !== undefined) body.message = args.message;
+        return createClient(args).ordersFulfill(args.order_id, body);
+      },
+    },
+    {
+      name: 'customers_wallet_credit',
+      description: 'Credit a customer wallet balance. Useful for refunds, goodwill credits, or promo grants.',
+      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(),
+      },
+      execute: async (args) => createClient(args).customersWalletCredit(args.customer_id, {
+        amount: args.amount,
+        currency: args.currency,
+        reason: args.reason,
+      }),
+    },
+    {
+      name: 'coupons_get',
+      description: 'Fetch one coupon by uniqid.',
+      inputSchema: { ...BaseToolSchema, coupon_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).couponsGet(args.coupon_id),
+    },
+    {
+      name: 'coupons_delete',
+      description: 'Delete a coupon by uniqid.',
+      inputSchema: { ...BaseToolSchema, coupon_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).couponsDelete(args.coupon_id),
+    },
+    {
+      name: 'payment_links_list',
+      description: 'List payment links for the authenticated shop.',
+      inputSchema: { ...BaseToolSchema },
+      execute: async (args) => createClient(args).paymentLinksList(),
+    },
+    {
+      name: 'payment_links_get',
+      description: 'Fetch one payment link by uniqid.',
+      inputSchema: { ...BaseToolSchema, link_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).paymentLinksGet(args.link_id),
+    },
+    {
+      name: 'payment_links_update',
+      description: 'Update a payment link by uniqid. Only provided fields change.',
+      inputSchema: {
+        ...BaseToolSchema,
+        link_id: z.string().trim().min(1),
+        name: z.string().trim().min(1).max(255).optional(),
+        description: z.string().max(255).optional().nullable(),
+        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(),
+      },
+      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);
+      },
+    },
+    {
+      name: 'payment_links_delete',
+      description: 'Delete a payment link by uniqid.',
+      inputSchema: { ...BaseToolSchema, link_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).paymentLinksDelete(args.link_id),
+    },
+    {
+      name: 'payment_links_toggle',
+      description: 'Activate or deactivate a payment link.',
+      inputSchema: {
+        ...BaseToolSchema,
+        link_id: z.string().trim().min(1),
+        active: z.boolean(),
+      },
+      execute: async (args) => createClient(args).paymentLinksToggle(args.link_id, { active: args.active }),
+    },
+    {
+      name: 'tickets_list',
+      description: 'List customer support tickets. Filter by status (open, closed, etc.).',
+      inputSchema: {
+        ...BaseToolSchema,
+        limit: z.number().int().min(1).max(50).optional(),
+        status: z.string().trim().min(1).optional(),
+      },
+      execute: async (args) => createClient(args).ticketsList({
+        limit: args.limit,
+        status: args.status,
+      }),
+    },
+    {
+      name: 'tickets_get',
+      description: 'Fetch one support ticket with all messages.',
+      inputSchema: { ...BaseToolSchema, ticket_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).ticketsGet(args.ticket_id),
+    },
+    {
+      name: 'tickets_create',
+      description: 'Create a new support ticket. Used when the merchant wants to proactively open a support conversation with a customer.',
+      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(),
+        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;
+        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);
+      },
+    },
+    {
+      name: 'tickets_reply',
+      description: 'Post a reply message to a support ticket. The reply is visible to the customer.',
+      inputSchema: {
+        ...BaseToolSchema,
+        ticket_id: z.string().trim().min(1),
+        message: z.string().trim().min(1),
+      },
+      execute: async (args) => createClient(args).ticketsReply(args.ticket_id, {
+        message: args.message,
+      }),
+    },
+    {
+      name: 'tickets_close',
+      description: 'Close a support ticket.',
+      inputSchema: { ...BaseToolSchema, ticket_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).ticketsClose(args.ticket_id),
+    },
+    {
+      name: 'blacklist_list',
+      description: 'List blacklist entries (blocked emails, IPs, countries, etc.) for the authenticated shop. Use for fraud prevention.',
+      inputSchema: {
+        ...BaseToolSchema,
+        limit: z.number().int().min(1).max(100).optional(),
+        type: z.enum(['email', 'ip', 'country', 'domain', 'phone']).optional(),
+      },
+      execute: async (args) => createClient(args).blacklistList({
+        limit: args.limit,
+        type: args.type,
+      }),
+    },
+    {
+      name: 'blacklist_add',
+      description: 'Add an entry to the shop blacklist. Blocks future checkouts from this email/IP/country/domain.',
+      inputSchema: {
+        ...BaseToolSchema,
+        type: z.enum(['email', 'ip', 'country', 'domain', 'phone']),
+        value: z.string().trim().min(1),
+        reason: z.string().max(255).optional(),
+      },
+      execute: async (args) => {
+        const body = { type: args.type, value: args.value };
+        if (args.reason !== undefined) body.reason = args.reason;
+        return createClient(args).blacklistAdd(body);
+      },
+    },
+    {
+      name: 'blacklist_remove',
+      description: 'Remove a blacklist entry by uniqid.',
+      inputSchema: { ...BaseToolSchema, entry_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).blacklistRemove(args.entry_id),
+    },
+    {
+      name: 'disputes_get',
+      description: 'Fetch one chargeback dispute with all evidence and history.',
+      inputSchema: { ...BaseToolSchema, dispute_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).disputesGet(args.dispute_id),
+    },
+    {
+      name: 'licenses_get',
+      description: 'Fetch one software license by uniqid with its activations and lock history.',
+      inputSchema: { ...BaseToolSchema, license_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).licensesGet(args.license_id),
+    },
+    {
+      name: 'licenses_update',
+      description: 'Update a license (revoke, extend validity, reset HWID/IP locks). Set active=false 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(),
+      },
+      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;
+        return createClient(args).licensesUpdate(args.license_id, body);
+      },
+    },
+    {
+      name: 'analytics_reports_list',
+      description: 'List custom analytics reports configured for the shop.',
+      inputSchema: { ...BaseToolSchema },
+      execute: async (args) => createClient(args).analyticsReportsList(),
+    },
+    {
+      name: 'analytics_report_generate',
+      description: 'Re-generate a custom analytics report by id. Useful to get fresh data for PDF/CSV exports.',
+      inputSchema: { ...BaseToolSchema, report_id: z.string().trim().min(1) },
+      execute: async (args) => createClient(args).analyticsReportGenerate(args.report_id),
+    },
   ];
 }